pywatershed.Control

pywatershed.Control#

class pywatershed.Control(start_time, end_time, time_step, init_time=None, options=None, only_warn_invalid=False)[source]#

Control manages global time and options, and provides metadata.

Parameters:

init_time (datetime64) – The initialization or restart time. Typically one day prior to start_time (but not necessarily).
start_time (datetime64) – The first time of model integration, NOT the restart or init time.
end_time (datetime64) – The final integration time of the run.
time_step (timedelta64) – Length of the time step (not currently optional).
options (dict) – A dictionary of global Process options.

Available pywatershed options:

imbalance_behavior: one of [None, “warn”, “error”]
calc_method: one of [“numpy”, “numba”, “fortran”]
dprst_flag: boolean if depression storage is included (true) or not.
input_dir: str or pathlib.path directory to search for input data. Use exactly one of input_dir or input_file.
input_file: str or pathlib.path file name containing all input data. Use exactly one of input_dir or input_file.
netcdf_output_dir: str or pathlib.Path directory for output
netcdf_output_var_names: a list of variable names to output
netcdf_output_separate_files: bool if output is grouped by Process or if each variable is written to an individual file
parameter_file: the name of a parameter file to use
streamflow_module: the selected streamflow module in PRMS.
start_time: np.datetime64
end_time: np.datetime64
time_step_units: str containing single character code for np.timedelta64
verbosity: 0-10

Available PRMS legacy options:

Either used as-is or mapped to pywatershed options as indicated below.

start_time
end_time
dprst_flag: integer is converted to boolean.
initial_deltat: translates to “time_step”
init_vars_from_file: translates to “restart”
nhruOutBaseFileName: translates to “netcdf_output_dir”
nhruOutVar_names: translates to a subset of “netcdf_output_var_names”
nsegmentOutBaseFileName: translates to “netcdf_output_dir”
nsegmentOutVar_names: translates to a subset of “netcdf_output_var_names”
param_file: translates to “parameter_file”
print_debug: translates to “verbosity”

Examples:#

>>> import pathlib as pl
>>>
>>> import numpy as np
>>> import pywatershed as pws
>>>
>>> control = pws.Control(
...     start_time=np.datetime64("2023-01-01T00:00:00"),
...     end_time=np.datetime64("2023-01-02T00:00:00"),
...     time_step=np.timedelta64(24, "h"),
...     options={"input_dir": pl.Path("./input")},
... )
>>>
>>> # A more interesting example reads from a PRMS control file
>>> pws_root = pws.constants.__pywatershed_root__
>>> drb_control_file = pws_root / "data/drb_2yr/control.test"
>>> control_drb = pws.Control.load_prms(
...     drb_control_file,
...     warn_unused_options=False,
... )
>>> control_drb.current_time
numpy.datetime64('1978-12-31T00:00:00')
>>> control_drb.previous_time
>>> control_drb.init_time
numpy.datetime64('1978-12-31T00:00:00')
>>> control_drb.time_step
numpy.timedelta64(24,'h')
>>> control_drb.time_step_seconds
86400.0
>>> control_drb.start_time
numpy.datetime64('1979-01-01T00:00:00')
>>> control_drb.advance()
>>> control_drb.current_time
numpy.datetime64('1979-01-01T00:00:00')
>>> control_drb.current_doy
1
>>> control_drb.current_dowy
93
>>> control_drb.previous_time
numpy.datetime64('1978-12-31T00:00:00')

__init__(start_time, end_time, time_step, init_time=None, options=None, only_warn_invalid=False)[source]#

Methods

`__init__`(start_time, end_time, time_step[, ...])
`advance`()	Advance time.
`diff`(other)	Diff self with another Control instance
`edit_end_time`(new_end_time)	Supply a new end time for the simulation.
`edit_init_start_times`(new_init_time[, ...])	Supply a new init and start times for the simulation.
`edit_n_time_steps`(new_n_time_steps)	Supply a new number of timesteps to change the simulation end time.
`from_yaml`(yaml_file)	Instantate a Control object from a yaml file
`load`(control_file[, warn_unused_options])	rtype: `Control`
`load_prms`(control_file[, ...])	Initialize a control object from a PRMS control file.
`to_dict`([deep_copy])	Export a control object to a dictionary
`to_yaml`(yaml_file)	Export to a yaml file

Attributes

`current_datetime`	Get the current time as a datetime.datetime object
`current_dowy`	Get the current day of water year in 1-366 (unless zero-based).
`current_doy`	Get the current day of year in 1-366 (unless zero based).
`current_epiweek`	Get the current epiweek [1, 53].
`current_jsol`	The number of days since the last winter solstice.
`current_month`	Get the current month in 1-12 (unless zero based).
`current_time`	Get the current time.
`current_year`	Get the current year.
`end_time`	The simulation end time.
`init_time`	Get the simulation initialization time
`itime_step`	The counth of the current time [0, self.n_times-1]
`n_times`	The number of time steps.
`previous_time`	The previous time.
`start_doy`	The simulation start day of year.
`start_month`	The simulation start month.
`start_time`	The simulation start time
`time_step`	The time step
`time_step_seconds`	The timestep length in units of seconds.

advance()[source]#

Advance time.

Return type:: None

property current_datetime: datetime#: Get the current time as a datetime.datetime object

property current_dowy: int#: Get the current day of water year in 1-366 (unless zero-based).

property current_doy: int#: Get the current day of year in 1-366 (unless zero based).

property current_epiweek: int#: Get the current epiweek [1, 53].

property current_jsol: int#

The number of days since the last winter solstice. Currently ASSUMES Norther Hemisphere.

This is based on GSFLOW 2.4.0:rc/prms/sm_utils_prms.f90:L470 julian_day function with argument “solar”.

property current_month: int#: Get the current month in 1-12 (unless zero based).

property current_time: datetime64#: Get the current time.

property current_year: int#: Get the current year.

diff(other)[source]#

Diff self with another Control instance

Parameters:: other – An other dict against which to compare.
Return type:: None

edit_end_time(new_end_time)[source]#

Supply a new end time for the simulation.

Parameters:: new_end_time (datetime64) – the new time at which to end the simulation.
Return type:: None

edit_init_start_times(new_init_time, new_start_time=None)[source]#

Supply a new init and start times for the simulation.

The initialization time is the time of the restart files. The start time is generally one timestep later, the time of the end of the first model advance but not necessarily so. Initialization could happen from an arbitrarty time/state. If new_start_time is not supplied, it is calculated as one timestep greater than the required new_init_time.

Parameters:

new_init_time (datetime64) – The time of the restart files to use.
new_start_time (datetime64) – The new time after the first advance of the model.

Return type:

None

edit_n_time_steps(new_n_time_steps)[source]#

Supply a new number of timesteps to change the simulation end time.

Parameters:: new_n_time_steps (int) – The new number of timesteps.
Return type:: None

property end_time: datetime64#: The simulation end time.

static from_yaml(yaml_file)[source]#

Instantate a Control object from a yaml file

Parameters:: yaml_file (Union[str, Path]) – a yaml file to parse.

Required key:value pairs:

imbalance_behavior: None | “warn” | “error”
calc_method: None | “numpy” | “numba” | “fortran” (depending on availability)
end_time: ISO8601 string for numpy datetime64, e.g. 1980-12-31T00:00:00.
start_time: ISO8601 string for numpy datetime64, e.g. 1979-01-01T00:00:00.
time_step: The first argument to get a numpy.timedelta64, e.g. 24
time_step_units: The second argument to get a numpy.timedelta64, e.g. ‘h’.
verbosity: integer 0-10

Optional key, value pairs:

input_dir: path relative to this file. Use exactly one of input_dir or input_file.
input_file: path relative to this file. Use exactly one of input_dir or input_file.
netcdf_output: boolean
netcdf_output_var_names: list of variable names to output, e.g. - albedo - cap_infil_tot - contrib_fraction

Return type:: Control
Returns:: Control object

property init_time: datetime64#: Get the simulation initialization time

property itime_step: int#: The counth of the current time [0, self.n_times-1]

classmethod load(control_file, warn_unused_options=True)[source]#

Return type:: Control

classmethod load_prms(control_file, warn_unused_options=True, keep_unused_options=False)[source]#

Initialize a control object from a PRMS control file.

Parameters:

control_file (Union[str, Path]) – PRMS control file
warn_unused_options (bool) – bool if warnings are to be issued for unused options from the PRMS control file. Recommended and True by default. See Control for a list of used/available legacy options. “Invalid” options will still be warned and can only be silenced by trapping warnings.
keep_unused_options (bool) – Retain all key information in the control file. “Invalid” options will still be warned and can only be silenced by trapping warnings.

Return type:

Control

Returns:

An instance of a Control object.

property n_times: int#: The number of time steps.

property previous_time: datetime64#: The previous time.

property start_doy: int#: The simulation start day of year.

property start_month: int#: The simulation start month.

property start_time: datetime64#: The simulation start time

property time_step: int#: The time step

property time_step_seconds: float64#: The timestep length in units of seconds.

to_dict(deep_copy=True)[source]#

Export a control object to a dictionary

Parameters:: deep_copy – If the dictionary should be a deep copy or not.
Return type:: dict

to_yaml(yaml_file)[source]#

Export to a yaml file

Parameters:: yaml_file (Union[Path, str]) – The file to write to.
Return type:: None

Note: This flattens .options to the top level of the yaml/dict: so that option keys are all at the same level as “start_time”, “end_time”, “time_step”, and “time_step_units”. Using .from_yaml will restore options to a nested dictionary.

Parameters:: yaml_file – pl.Path or str to designate the output path/file.

pywatershed.Control

Contents

pywatershed.Control#

Examples:#