pywatershed.PRMSRunoffAg

class pywatershed.PRMSRunoffAg(control, discretization, parameters, soil_lower_prev, soil_rechr_prev, net_ppt, net_rain, net_snow, potet, snowmelt, snow_evap, pkwater_equiv, pptmix_nopack, snowcov_area, through_rain, hru_intcpevap, intcp_changeover, ag_soil_moist_prev, ag_soil_rechr_prev, ag_frac, dprst_flag=None, intcp_changeover_in_net_rain=None, imbalance_behavior='defer', calc_method=None, input_aliases=None, verbose=None, restart_read=False, restart_write=False, restart_write_freq=False)

PRMS surface runoff with agricultural infiltration.

Extension of PRMSRunoff that calculates infiltration for both pervious and agricultural areas separately. This is required for agricultural soilzone simulations (PRMSSoilzoneAg).

Implementation based on GSFLOW with agricultural extensions, following the same logic as PRMSRunoff but adding parallel calculations for agricultural areas.

Restart Variables

PRMSRunoffAg inherits get_restart_variables() from PRMSRunoff without modification because it has no additional storage state variables beyond the parent class. The agricultural-specific outputs (infil_ag, infil_ag_hru, hru_sroff_ag) are flux variables that are recalculated each timestep, not state variables that need to be saved for restart.

The ag calculations use:

• ag_soil_moist_prev and ag_soil_rechr_prev: These come from PRMSSoilzoneAg as inputs, not from runoff itself

• ag_area: Derived from the ag_frac parameter and recalculated in _update_ag_areas() as needed

All storage states (imperv_stor, dprst_vol_open, dprst_vol_clos, etc.) are inherited from the parent class and properly saved/restored during restart.

type control:

Control

param control:

a Control object

type discretization:

Parameters

param discretization:

a discretization of class Parameters

type parameters:

Parameters

param parameters:

a parameter object of class Parameters

type soil_lower_prev:

Union[str, Path, ndarray, Adapter, PrmsDynamicParameter]

param soil_lower_prev:

Previous storage of lower reservoir for each HRU

type soil_rechr_prev:

Union[str, Path, ndarray, Adapter, PrmsDynamicParameter]

param soil_rechr_prev:

Previous storage of recharge reservoir for each HRU

type net_ppt:

Union[str, Path, ndarray, Adapter, PrmsDynamicParameter]

param net_ppt:

Precipitation (rain and/or snow) that falls through the canopy for each HRU

type net_rain:

Union[str, Path, ndarray, Adapter, PrmsDynamicParameter]

param net_rain:

Rain that falls through canopy for each HRU

type net_snow:

Union[str, Path, ndarray, Adapter, PrmsDynamicParameter]

param net_snow:

Snow that falls through canopy for each HRU

type potet:

Union[str, Path, ndarray, Adapter, PrmsDynamicParameter]

param potet:

Potential ET for each HRU

type snowmelt:

Union[str, Path, ndarray, Adapter, PrmsDynamicParameter]

param snowmelt:

Snowmelt from snowpack on each HRU

type snow_evap:

Union[str, Path, ndarray, Adapter, PrmsDynamicParameter]

param snow_evap:

Evaporation and sublimation from snowpack on each HRU

type pkwater_equiv:

Union[str, Path, ndarray, Adapter, PrmsDynamicParameter]

param pkwater_equiv:

Snowpack water equivalent on each HRU

type pptmix_nopack:

Union[str, Path, ndarray, Adapter, PrmsDynamicParameter]

param pptmix_nopack:

Flag indicating that a mixed precipitation event has occurred with no snowpack

type snowcov_area:

Union[str, Path, ndarray, Adapter, PrmsDynamicParameter]

param snowcov_area:

Snow-covered area on each HRU prior to melt and sublimation unless snowpack

type through_rain:

Union[str, Path, ndarray, Adapter, PrmsDynamicParameter]

param through_rain:

Rain that passes through snow when no snow present

type hru_intcpevap:

Union[str, Path, ndarray, Adapter, PrmsDynamicParameter]

param hru_intcpevap:

HRU area-weighted average evaporation from the canopy for each HRU

type intcp_changeover:

Union[str, Path, ndarray, Adapter, PrmsDynamicParameter]

param intcp_changeover:

Canopy throughfall caused by canopy density change from winter to summer

type ag_soil_moist_prev:

Union[str, Path, ndarray, Adapter, PrmsDynamicParameter]

param ag_soil_moist_prev:

Previous timestep water storage for upper portion in the capillary reservoir of the irrigated area for each HRU.

type ag_soil_rechr_prev:

Union[str, Path, ndarray, Adapter, PrmsDynamicParameter]

param ag_soil_rechr_prev:

Previous timestep water storage for upper portion in the capillary reservoir of the irrigated area for each HRU that is available for both evaporation and transpiration.

type dprst_flag:

Optional[bool]

param dprst_flag:

use depression storage or not? None uses value in control file, which otherwise defaults to True.

type intcp_changeover_in_net_rain:

bool | None

param intcp_changeover_in_net_rain:

Boolean flag indicating whether intcp_changeover is included in net rain (GSFLOW 4.2.0 and PRMS 6.0.0) or not (pywatershed and PRMS < 6.0.0).

type imbalance_behavior:

Literal['defer', None, 'warn', 'error']

param imbalance_behavior:

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”.

type calc_method:

Literal['numba', 'numpy', None]

param calc_method:

one of [“numba”, “numpy”]. None defaults to “numba”.

type verbose:

Optional[bool]

param verbose:

Print extra information or not?

type restart_read:

Union[Path, bool]

param restart_read:

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. Files searched for are of the pattern YYYY-mm-dd-varname.nc where the date is the control.init_time. The timestamp on the file is the valid time of the states in the file with the exception of processes with sub-daily timesteps. For example, the outflow_ts variable of PRMSChannel is instantaneous and valid at the 23rd hour of the timestampped day whereas its variable seg_outflow is the daily averge value over the timestampped day.

type restart_write:

Union[Path, bool]

param restart_write:

As for restart_read but for writing. The directory in either case will be attempted to be created if it does not exist.

type restart_write_freq:

Literal['y', 'm', 'd', 'f', False]

param restart_write_freq:

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. “Final” means that restart files are written with the states at control.end_time to files timestampped with control.end_time. Yearly and monthly restart options write files with timestamps on the last day of each year or month during the run. If daily, restarts are written every day. If restart_write is not False and restart_write_freq is False, the default of “f” is used.

__init__(control, discretization, parameters, soil_lower_prev, soil_rechr_prev, net_ppt, net_rain, net_snow, potet, snowmelt, snow_evap, pkwater_equiv, pptmix_nopack, snowcov_area, through_rain, hru_intcpevap, intcp_changeover, ag_soil_moist_prev, ag_soil_rechr_prev, ag_frac, dprst_flag=None, intcp_changeover_in_net_rain=None, imbalance_behavior='defer', calc_method=None, input_aliases=None, verbose=None, restart_read=False, restart_write=False, restart_write_freq=False)

Methods

__init__(control, discretization, ...[, ...])
advance()	Advance the Process in time.
ag_comp(ag_soil_moist_prev, ...)	Agricultural area runoff computations.
basin_init()	This is trying to replicate the prms basin.f90/basinit() function that calculates some of the variables needed here by runoff.
calculate(time_length, **kwargs)	Calculate Process terms for a time step
check_capacity(soil_moist_prev, ...)	Fill soil to soil_moist_max, if more than capacity restrict infiltration by snowinfil_max, with excess added to runoff
check_capacity_ag(ag_soil_moist_prev, ...)	Fill agricultural soil to ag_soil_moist_max, if more than capacity restrict infiltration by snowinfil_max, with excess added to runoff.
compute_infil(contrib_fraction, ...)
description()	A dictionary description of this Process.
dprst_comp(dprst_vol_clos, ...)
dprst_comp_ag(dprst_vol_clos, ...)	Depression storage computation with agricultural runoff routing.
dprst_init()
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 mass budget terms for agricultural runoff.
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.
imperv_et(imperv_stor, potet, imperv_evap, ...)
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
perv_comp(soil_moist_prev, carea_max, ...)	Pervious area computations.
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

static ag_comp(ag_soil_moist_prev, ag_soil_rechr_prev, carea_max, smidx_coef, smidx_exp, pptp, ptc, infil_ag, sroff_ag)

Agricultural area runoff computations.

Similar to perv_comp but uses agricultural soil moisture.

basin_init()

This is trying to replicate the prms basin.f90/basinit() function that calculates some of the variables needed here by runoff. This should probably go somewhere else at some point as I suspect other components may need similar information.

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

static check_capacity(soil_moist_prev, soil_moist_max, snowinfil_max, infil, srp)

Fill soil to soil_moist_max, if more than capacity restrict infiltration by snowinfil_max, with excess added to runoff

static check_capacity_ag(ag_soil_moist_prev, ag_soil_moist_max, snowinfil_max, infil_ag, sroff_ag)

Fill agricultural soil to ag_soil_moist_max, if more than capacity restrict infiltration by snowinfil_max, with excess added to runoff.

static compute_infil(contrib_fraction, soil_moist_prev, soil_moist_max, carea_max, smidx_coef, smidx_exp, pptmix_nopack, net_rain, net_ppt, imperv_stor, imperv_stor_max, snowmelt, snowinfil_max, net_snow, pkwater_equiv, infil, hru_type, intcp_changeover, hruarea_imperv, sri, srp, check_capacity, perv_comp, through_rain, intcp_changeover_in_net_rain)

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.

static dprst_comp(dprst_vol_clos, dprst_area_clos_max, dprst_area_clos, dprst_vol_open_max, dprst_vol_open, dprst_area_open_max, dprst_sroff_hru, sro_to_dprst_perv, sro_to_dprst_imperv, dprst_evap_hru, pptmix_nopack, snowmelt, pkwater_equiv, net_snow, hru_area, dprst_insroff_hru, dprst_frac_open, dprst_frac_clos, va_open_exp, dprst_vol_clos_max, dprst_vol_clos_frac, va_clos_exp, potet, snowcov_area, dprst_et_coef, dprst_seep_rate_open, dprst_vol_thres_open, dprst_flow_coef, dprst_seep_rate_clos, avail_et, net_rain, dprst_in, srp, sri, imperv_frac, perv_frac)

static dprst_comp_ag(dprst_vol_clos, dprst_area_clos_max, dprst_area_clos, dprst_vol_open_max, dprst_vol_open, dprst_area_open_max, dprst_sroff_hru, sro_to_dprst_perv, sro_to_dprst_imperv, dprst_evap_hru, through_rain, snowmelt, hru_area, dprst_insroff_hru, dprst_frac_open, dprst_frac_clos, va_open_exp, dprst_vol_clos_max, dprst_vol_clos_frac, va_clos_exp, potet, snowcov_area, dprst_et_coef, dprst_seep_rate_open, dprst_vol_thres_open, dprst_flow_coef, dprst_seep_rate_clos, avail_et, dprst_in, srp, sri, sroff_ag, imperv_frac, perv_frac, ag_frac)

Depression storage computation with agricultural runoff routing.

This is a modified version of dprst_comp that also routes agricultural runoff through depression storage, following the Fortran implementation in srunoff.f90 lines 1687-1700.

dprst_init()

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()

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()

Get a dictionary of initialization values for each public variable.

Return type:

dict

static get_inputs()

Get a tuple of input variable names for this Process.

Return type:

tuple

static get_mass_budget_terms()

Get mass budget terms for agricultural runoff.

In GSFLOW with agriculture, the pervious area (hru_perv) is reduced by ag_area. We break out infiltration and surface runoff into separate pervious and agricultural components for budget clarity:

Infiltration components: - infil_perv_hru: pervious infiltration only = infil * hru_frac_perv - infil_ag_hru: agricultural infiltration = infil_ag * ag_frac - infil_hru: combined total (pervious + ag) for compatibility with

PRMS source code

Surface runoff is split into three components: - hru_sroffi: impervious runoff - hru_sroffp: pervious runoff - hru_sroff_ag: agricultural runoff

static get_parameters()

Get a tuple of parameter names for this Process.

Return type:

tuple

static get_restart_variables()

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

static imperv_et(imperv_stor, potet, imperv_evap, sca, avail_et, imperv_frac)

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.

static perv_comp(soil_moist_prev, carea_max, smidx_coef, smidx_exp, pptp, ptc, infil, srp)

Pervious area computations.

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.