pywatershed.PRMSSoilzoneAgObsET

pywatershed.PRMSSoilzoneAgObsET#

class pywatershed.PRMSSoilzoneAgObsET(control, discretization, parameters, dprst_evap_hru, dprst_seep_hru, hru_impervevap, hru_intcpevap, infil, infil_ag, sroff, sroff_vol, potet, transp_on, snow_evap, snowcov_area, ag_frac, aet_observed, dprst_flag=None, imbalance_behavior='defer', calc_method=None, adjust_parameters='warn', input_aliases=None, verbose=None, restart_read=False, restart_write=False, restart_write_freq=False)[source]#

PRMS soil zone with agricultural area and iterative AET matching.

This is an agricultural variant of PRMSSoilzone based on GSFLOW 2.4.0 soilzone_ag.f90. The key differences from the base PRMSSoilzone are:

  1. Dual Area Treatment: Each HRU is divided into pervious and agricultural/irrigated areas, each with separate soil moisture accounting.

  2. Iterative AET Matching: When observed actual ET (AET_external) is provided, the code iteratively adjusts irrigation to match the observed AET within a convergence tolerance.

  3. Agricultural Parameters: Additional parameters for agricultural soil properties, cover density, and irrigation thresholds.

Implementation based on GSFLOW 2.4.0 soilzone_ag.f90 with theoretical documentation given in the PRMS-IV documentation:

Markstrom, S. L., Regan, R. S., Hay, L. E., Viger, R. J., Webb, R. M., Payn, R. A., & LaFontaine, J. H. (2015). PRMS-IV, the precipitation-runoff modeling system, version 4. US Geological Survey Techniques and Methods, 6, B7.

Parameters:

  • control (Control) – a Control object

  • discretization (Parameters) – a discretization of class Parameters

  • parameters (Parameters) – a parameter object of class Parameters

  • dprst_evap_hru (Union[str, Path, ndarray, Adapter, PrmsDynamicParameter]) – Evaporation from surface-depression storage for each HRU

  • dprst_seep_hru (Union[str, Path, ndarray, Adapter, PrmsDynamicParameter]) – Seepage from surface-depression storage to associated GWR for each HRU

  • hru_impervevap (Union[str, Path, ndarray, Adapter, PrmsDynamicParameter]) – HRU area-weighted average evaporation from impervious area for each HRU

  • hru_intcpevap (Union[str, Path, ndarray, Adapter, PrmsDynamicParameter]) – HRU area-weighted average evaporation from the canopy for each HRU

  • infil (Union[str, Path, ndarray, Adapter, PrmsDynamicParameter]) – Infiltration to the capillary and preferential-flow reservoirs, depth on pervious area

  • infil_ag (Union[str, Path, ndarray, Adapter, PrmsDynamicParameter]) – Infiltration to the capillary reservoir for agricultural area, depth on HRU agricultural area

  • sroff (Union[str, Path, ndarray, Adapter, PrmsDynamicParameter]) – Surface runoff to the stream network for each HRU

  • sroff_vol (Union[str, Path, ndarray, Adapter, PrmsDynamicParameter]) – Surface runoff volume to the stream network for each HRU

  • potet (Union[str, Path, ndarray, Adapter, PrmsDynamicParameter]) – Potential ET for each HRU

  • transp_on (Union[str, Path, ndarray, Adapter, PrmsDynamicParameter]) – Flag indicating whether transpiration is occurring (0=no;1=yes)

  • snow_evap (Union[str, Path, ndarray, Adapter, PrmsDynamicParameter]) – Evaporation and sublimation from snowpack on each HRU

  • snowcov_area (Union[str, Path, ndarray, Adapter, PrmsDynamicParameter]) – Snow-covered area on each HRU prior to melt and sublimation unless snowpack

  • ag_frac (Union[str, Path, ndarray, Adapter, PrmsDynamicParameter]) – Fraction of HRU that is agricultural/irrigated area

  • aet_observed (Union[str, Path, ndarray, Adapter, PrmsDynamicParameter]) – Observed actual ET from CBH file for each HRU (when iter_aet_flag is True). Used to calculate AET_external. Negative values are considered missing and set to zero, diabling AET matching.

  • dprst_flag (bool | None) – use depression storage or not? None uses value in control file, which otherwise defaults to True.

  • iter_aet_flag – Flag to enable iterative AET matching. If None, uses value from control.options[“iter_aet_flag”] if available, otherwise defaults to False.

  • imbalance_behavior (Literal['defer', None, 'warn', 'error']) – one of [“defer”, None, “warn”, “error”] with “defer” being the default and defering to control.options[“imbalance_behavior”] when available. When control.options[“imbalance_behavior”] is not avaiable, imbalance_behavior is set to “warn”.

  • calc_method (Literal['numpy', None]) – one of [“numpy”, “numba”]. None defaults to “numpy”. The “numba” option provides significant performance improvements, especially for the iterative AET matching loop. Parallelism is controlled via the NUMBA_NUM_THREADS environment variable.

  • adjust_parameters (Literal['warn', 'error', 'no']) – one of [“warn”, “error”, “no”]. Default is “warn”, the code edits the parameters and issues a warning. If “error” is selected the the code issues warnings about all edited parameters before raising the error to give you information. If “no” is selected then no parameters are adjusted and there will be no warnings or errors.

  • verbose (bool | None) – Print extra information or not?

  • restart_read (Path | bool) – May be boolean or a Pathlib.Path. If False, control.options will be examined for this key. If True, the working directory is searched for restart files. If a Pathlib.Path, this specifies an alternative directory to search for restart files.

  • restart_write (Path | bool) – As for restart_read but for writing. The directory in either case will be attempted to be created if it does not exist.

  • restart_write_freq (Literal['y', 'm', 'd', 'f', False]) – If False, then control.options is examined for this key. The follwing values set the frequency of restart output with “y” for yearly, “m” for monthly, “d” for daily, or “f” for final.

__init__(control, discretization, parameters, dprst_evap_hru, dprst_seep_hru, hru_impervevap, hru_intcpevap, infil, infil_ag, sroff, sroff_vol, potet, transp_on, snow_evap, snowcov_area, ag_frac, aet_observed, dprst_flag=None, imbalance_behavior='defer', calc_method=None, adjust_parameters='warn', input_aliases=None, verbose=None, restart_read=False, restart_write=False, restart_write_freq=False)[source]#

Methods

__init__(control, discretization, ...[, ...])

advance()

Advance the Process in time.

calculate(time_length, **kwargs)

Calculate Process terms for a time step

description()

A dictionary description of this Process.

finalize()

Finalize the Process, output methods, and close input adapters.

get_dimensions()

Get a tuple of dimension names for this Process.

get_energy_budget_terms()

Get a dictionary of variable names for energy budget terms.

get_init_values()

Get a dictionary of initialization values for each public variable.

get_inputs()

Get a tuple of input variable names for this Process.

get_mass_budget_terms()

Get a dictionary of variable names for mass budget terms.

get_parameters()

Get a tuple of parameter names for this Process.

get_restart_variables()

A list of restart varible names.

get_variables()

Get a tuple of (public) variable names for this Process.

initialize_netcdf([output_dir, ...])

Initialize NetCDF output.

output()

Output data to previously initialized output types.

output_to_csv(pth)

Save each output variable to separate csv file in specified path

set_input_to_adapter(input_variable_name, ...)

Set input variables to adapter.current and manage the adapter.

Attributes

budget

Legacy property for backward compatibility - returns mass budget.

dimensions

A tuple of parameter names.

energy_budget

The energy budget for this process, if enabled.

energy_budget_terms

A dictionary of variable names for the energy budget terms.

init_values

A dictionary of initial values for each public variable.

inputs

A tuple of input variable names.

mass_budget

The mass budget for this process, if enabled.

mass_budget_terms

A dictionary of variable names for the mass budget terms.

parameters

A tuple of parameter names.

restart_variables

previous.

variables

A tuple of public variable names.
advance()#

Advance the Process in time.

Returns:

None

property budget#

Legacy property for backward compatibility - returns mass budget.

Deprecated since version The: ‘budget’ property is deprecated. Use ‘mass_budget’ instead.

calculate(time_length, **kwargs)#

Calculate Process terms for a time step

Parameters:

simulation_time – current simulation time

Return type:

None

Returns:

None

classmethod description()#

A dictionary description of this Process.

Return type:

dict

Returns:

All metadata for all variables in inputs, variables, parameters, mass_budget_terms, and energy_budget_terms for this Process.

property dimensions: tuple#

A tuple of parameter names.

property energy_budget#

The energy budget for this process, if enabled.

property energy_budget_terms: dict#

A dictionary of variable names for the energy budget terms.

finalize()#

Finalize the Process, output methods, and close input adapters.

Return type:

None

Returns:

None

static get_dimensions()[source]#

Get a tuple of dimension names for this Process.

Return type:

tuple

classmethod get_energy_budget_terms()#

Get a dictionary of variable names for energy budget terms.

Return type:

dict

static get_init_values()[source]#

Get a dictionary of initialization values for each public variable.

Return type:

dict

static get_inputs()[source]#

Get a tuple of input variable names for this Process.

Return type:

tuple

static get_mass_budget_terms()[source]#

Get a dictionary of variable names for mass budget terms.

Return type:

dict

static get_parameters()[source]#

Get a tuple of parameter names for this Process.

Return type:

tuple

static get_restart_variables()[source]#

A list of restart varible names.

Return type:

list

classmethod get_variables()#

Get a tuple of (public) variable names for this Process.

Return type:

tuple

property init_values: dict#

A dictionary of initial values for each public variable.

initialize_netcdf(output_dir=None, separate_files=None, budget_args=None, output_vars=None, extra_coords=None, addtl_output_vars=None)#

Initialize NetCDF output.

Parameters:

  • output_dir ([<class ‘str’>, <class ‘pathlib.Path’>]) – base directory path or NetCDF file path if separate_files is True

  • separate_files (bool) – boolean indicating if storage component output variables should be written to a separate file for each variable

  • output_vars (list) – list of variable names to output.

Return type:

None

Returns:

None

property inputs: tuple#

A tuple of input variable names.

property mass_budget#

The mass budget for this process, if enabled.

property mass_budget_terms: dict#

A dictionary of variable names for the mass budget terms.

output()#

Output data to previously initialized output types. :rtype: None :returns: None

output_to_csv(pth)#

Save each output variable to separate csv file in specified path

property parameters: tuple#

A tuple of parameter names.

property restart_variables: dict#

previous.

Type:

A dict of restart variable names mapping current

set_input_to_adapter(input_variable_name, adapter)#

Set input variables to adapter.current and manage the adapter.

TODO: make this private?

Parameters:

  • input_variable_name (str) – key of input variable

  • adapter (Adapter) – the Adapter for the input.

property variables: tuple#

A tuple of public variable names.