pywatershed.PRMSStreamTempHumidityCBH

pywatershed.PRMSStreamTempHumidityCBH#

class pywatershed.PRMSStreamTempHumidityCBH(control, discretization, parameters, seg_outflow, seg_lateral_inflow, swrad, potet, sroff, ssres_flow, gwres_flow, tavgc, snowmelt, hru_rain, soltab_potsw, humidity_hru, seg_flow_width=None, seg_flow_depth=None, seg_flow_area=None, seg_flow_velocity=None, stream_shade=None, stream_shade_class=None, stream_shade_parameters=None, calc_method=None, imbalance_behavior='defer', input_aliases=None, verbose=False, use_vectorized_shade=True, track_energy_fluxes=True, atmos_exchange_factor=1.0)[source]#

PRMS stream temperature with time-varying humidity input.

PRMSStreamTemp and PRMSStreamTempHumidityCBH model stream temperature following PRMS 5.2.1.1. The class PRMSStreamTemp covers the situation where humidity is supplied by the parameter files (strmtemp_humidity_flag=1) and PRMSStreamTempHumidityCBH covers the case of when humidity is supplied by time-varying input files (NetCDF CBH equivalents, e.g. strmtemp_humidity_flag=0. Note there is not currently an implementation for the PRMS case strmtemp_humidity_flag=2). This documentation provides general background for both classes.

The stream temperature classes use:

PRMSHydraulicGeometryFull and PRMSHydraulicGeometryWidthOnly as upstream processes which provide the hydraulic geometry variables (and are renamed seg_flow_* compared to the PRMS seg_* variables)
PRMSStreamShadeConstant and PRMSStreamShadeDynamic as models of stream shade. These are to be passed to or “composed” into the stream temperature on initialization.

See the example notebooks examples/01_multi-process_models.ipynb and examples/02_prms_legacy_models.ipynb for worked examples.

This implementation is based on PRMS 5.2.1.1 with theoretical documentation given by:

Markstrom, Steven L. P2S – Coupled simulation with the Precipitation-Runoff Modeling System (PRMS) and the Stream Temperature Network (SNTemp) Models. No. 2012-1116. US Geological Survey, 2012.

Sanders, M.J., Markstrom, S.L., Regan, R.S., and Atkinson, R.D., 2017, Documentation of a daily mean stream temperature module — An enhancement to the Precipitation-Runoff Modeling System: U.S. Geological Survey Techniques and Methods, book 6, chap. D4, 18 p.

The stream temperature module computes daily mean water temperature for each stream segment using an energy balance approach. The module accounts for:

Solar radiation (shortwave)
Longwave radiation (atmospheric and vegetation)
Convection and evaporation
Conduction with the streambed
Temperature of inflows (upstream, lateral, groundwater, subsurface)
Shading from riparian vegetation and topography

HRU quantities are aggregated to segments internally, computing segment- level meteorological variables (seg_tave_air, seg_humid, seg_ccov, seg_melt, seg_rain) from HRU inputs. This follows the Fortran PRMS stream_temp.f90 logic (lines ~699-850).

Parameters:

control (Control) – a Control object
discretization (Parameters) – a discretization of class Parameters
parameters (Parameters) – a parameter object of class Parameters
seg_outflow (Union[str, Path, ndarray, Adapter, PrmsDynamicParameter]) – Streamflow leaving each segment (from PRMSChannel)
seg_lateral_inflow (Union[str, Path, ndarray, Adapter, PrmsDynamicParameter]) – Lateral inflow entering each segment (from PRMSChannel)
swrad (Union[str, Path, ndarray, Adapter, PrmsDynamicParameter]) – Solar radiation for each HRU (from PRMSAtmosphere)
potet (Union[str, Path, ndarray, Adapter, PrmsDynamicParameter]) – Potential ET for each HRU (from PRMSAtmosphere)
sroff (Union[str, Path, ndarray, Adapter, PrmsDynamicParameter]) – Surface runoff for each HRU (from PRMSRunoff)
ssres_flow (Union[str, Path, ndarray, Adapter, PrmsDynamicParameter]) – Subsurface flow for each HRU (from PRMSSoilzone)
gwres_flow (Union[str, Path, ndarray, Adapter, PrmsDynamicParameter]) – Groundwater flow for each HRU (from PRMSGroundwater)
tavgc (Union[str, Path, ndarray, Adapter, PrmsDynamicParameter]) – Average air temperature for each HRU in Celsius (from PRMSAtmosphere)
snowmelt (Union[str, Path, ndarray, Adapter, PrmsDynamicParameter]) – Snowmelt for each HRU (from PRMSSnow)
hru_rain (Union[str, Path, ndarray, Adapter, PrmsDynamicParameter]) – Rainfall for each HRU (from PRMSAtmosphere)
soltab_potsw (Union[str, Path, ndarray, Adapter, PrmsDynamicParameter]) – Potential shortwave radiation table for current day (from PRMSSolarGeometry or Adapter)
humidity_hru (Union[str, Path, ndarray, Adapter, PrmsDynamicParameter]) – Humidity for each HRU (from CBH via Adapter). Values are relative humidity in percent (0-100).
seg_flow_width (Union[str, Path, ndarray, Adapter, PrmsDynamicParameter]) – Flow-dependent width from PRMSHydraulicGeometryFull
seg_flow_depth (Union[str, Path, ndarray, Adapter, PrmsDynamicParameter]) – Flow-dependent depth from PRMSHydraulicGeometryFull
seg_flow_area (Union[str, Path, ndarray, Adapter, PrmsDynamicParameter]) – Flow-dependent cross-sectional area from PRMSHydraulicGeometryFull
seg_flow_velocity (Union[str, Path, ndarray, Adapter, PrmsDynamicParameter]) – Flow-dependent velocity from PRMSHydraulicGeometryFull
stream_shade (Optional[PRMSStreamShade]) – PRMSStreamShade instance (Dynamic or Constant). If provided, stream_shade_class and stream_shade_parameters are ignored.
stream_shade_class (Optional[type]) – Class to use for stream shade computation (e.g., PRMSStreamShadeDynamic, PRMSStreamShadeConstant). Only used if stream_shade is None.
stream_shade_parameters (Union[Parameters, Path, None]) – Parameters for stream shade computation. Can be a Parameters object or a Path to a parameter file. Only used if stream_shade is None and stream_shade_class is provided.
imbalance_behavior (Literal['defer', None, 'warn', 'error']) – one of [“defer”, None, “warn”, “error”]
verbose (bool) – Print extra information or not?
use_vectorized_shade (bool) – Use vectorized shade computation for all segments at once (default True)
track_energy_fluxes (bool) – Track energy flux terms for budget analysis

__init__(control, discretization, parameters, seg_outflow, seg_lateral_inflow, swrad, potet, sroff, ssres_flow, gwres_flow, tavgc, snowmelt, hru_rain, soltab_potsw, humidity_hru, seg_flow_width=None, seg_flow_depth=None, seg_flow_area=None, seg_flow_velocity=None, stream_shade=None, stream_shade_class=None, stream_shade_parameters=None, calc_method=None, imbalance_behavior='defer', input_aliases=None, verbose=False, use_vectorized_shade=True, track_energy_fluxes=True, atmos_exchange_factor=1.0)[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 energy budget terms for stream temperature.
`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 with energy flux tracking checks.
`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

static get_energy_budget_terms()[source]#

Get energy budget terms for stream temperature.

Return type:: dict
Returns:: Dictionary with inputs, outputs, exchanges, and storage_changes for energy budget.

Notes

Energy fluxes are computed in Watts (J/s). The budget tracks: - Advective heat transport (upstream, lateral, outflow) - Surface energy exchange (solar, longwave, evaporation) - Internal sources (friction, groundwater conduction) - Bi-directional exchanges that can be gains or losses

Storage changes are empty because the kinematic wave assumption means water storage is constant - only temperature (and thus heat content) changes, which is captured by the balance of inputs and outputs.

Exchanges are net fluxes that can be positive (heat gain) or negative (heat loss) depending on temperature gradients: - convective_exchange: depends on air vs water temperature While it seems that the following could be exchanges, their current formulation restricts their sign and they have been categorized to match that pre-determined sign: - longwave_vegetation: net longwave exchange with vegetation - groundwater_conduction: depends on groundwater vs water temp

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

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)[source]#

Initialize NetCDF output with energy flux tracking checks.

This method overrides the parent class to add consistency checks for energy flux tracking.

Parameters:

output_dir (Union[str, 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
budget_args (dict) – arguments to pass to budget initialization
output_vars (list) – list of variable names to output
extra_coords (dict) – extra coordinates to add to the output
addtl_output_vars (list) – additional output variables

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.

pywatershed.PRMSStreamTempHumidityCBH

Contents

pywatershed.PRMSStreamTempHumidityCBH#