pywatershed.Control

pywatershed.Control#

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

Control manages global time and options, and provides metadata.

Parameters:

start_time (datetime64) – this is the first time of integration NOT the restart time
end_time (datetime64) – the last integration time
time_step (timedelta64) – the length fo the time step
options (Optional[dict]) – a dictionary of global Process options.

Available pywatershed options:

budget_type: one of [None, “warn”, “error”]
calc_method: one of [“numpy”, “numba”, “fortran”]
input_dir: str or pathlib.path directory to search for input data
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
netcdf_budget_args:
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
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”
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)[source]#

Methods

`__init__`(start_time, end_time, time_step[, ...])
`advance`()	Advance time.
`edit_end_time`(new_end_time)	Supply a new end time 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[, warn_unused_options])	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_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_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.

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_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:

budget_type: 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.
input_dir: path relative to this file.
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:

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)[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 below for a list of used/available legacy options.

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:#