Reservoir Model

Reservoir class for storing and validating reservoir parameters and calculation of reservoir characteristics and operational parameters from primary data.

class reemission.reservoir.Reservoir(coordinates: Tuple[float, float], temperature: MonthlyTemperature, volume: float, max_depth: float, mean_depth: float, inflow_rate: float, area: float, soil_carbon: float, area_fractions: List, mean_radiance: float, mean_radiance_may_sept: float, mean_radiance_nov_mar: float, mean_monthly_windspeed: float, water_intake_depth: float, name: str = 'n/a')

Bases: object

Model of a generic reservoir.

coordinates

Reservoir’s latitude and longitude, degrees.

Type:

Tuple[float, float]

temperature

MonthlyTemperature object with a 12x1 monthly average temperature vector, degC.

Type:

MonthlyTemperature

volume

Reservoir volume, m\(^3\).

Type:

float

max_depth

Maximum reservoir depth, m.

Type:

float

mean_depth

Mean reservoir depth, m.

Type:

float

inflow_rate

Flow of water entering the reservoir, m\(^3\)/year.

Type:

float

area

Inundated area of the reservoir, km\(^2\).

Type:

float

soil_carbon

Mass of carbon in the inundated area, kg/m\(^2\).

Type:

float

area_fractions

List of fractions of the inundated area allocated to specific landuse types given in Landuse Enum type per 3 soil type categories: mineral -> organic -> nodata.

Type:

List[float]

mean_radiance

Mean annual monthly horizontal radiance, kWh/m\(^2\)/d.

Type:

float

mean_radiance_may_sept

Mean monthly horizontal radiance between May and September, kWh/m\(^2\)/d.

Type:

float

mean_radiance_nov_mar

Mean monthly horizontal radiance between November and March, kWh/m\(^2\)/d.

Type:

float

mean_monthly_windspeed

Mean annual monthly wind speed, m/s (assumed to be measured at the height of 50 metres.)

Type:

float

water_intake_depth

Water intake depth below surface, m.

Type:

float

name

Reservoir name. Default is “n/a”.

Type:

str

Note

• Sum of area fractions should be equal to 1 +/- EPS.

• Reservoir volume in G-Res is given in km\(^3\).

• Water intake depth is used for estimating CH\(_4\) emissions via degassing.

__post_init__()

Post-initialization checks and validations.

Validates the size and sum of area fractions and ensures coordinates are tuples.

Raises:

• WrongAreaFractionsException – If the number of area fractions is not equal to the number of land uses times three.

• WrongSumOfAreasException – If the sum of area fractions does not equal 1 +/- EPS.

area: float

area_fractions: List

bottom_density() → float

Calculate the water density in kg/m\(^3\) at the bottom of the reservoir. Refer to Equation A.3. in Praire2021.

Returns:

The water density at the bottom of the reservoir, kg/m\(^3\).

Return type:

float

bottom_temperature() → float

Calculate the bottom (hypolimnion) temperature in the reservoir from a 12x1 profile of monthly average air temperatures. Refer to Equation A.2. in Praire2021.

Note

Mean Temperature of the Colder Month in Praire2021 was interpreted as the coldest mean monthly temperature in the 12x1 temperature profile.

Returns:

The bottom temperature of the reservoir, degrees Celcius.

Return type:

float

ch4_preemission_factor(wind_height: float = 50) → float

Calculate the CH\(_4\) emission factor for the water body, in kg CH\(_4\)/ha/yr. Refer to Eq. A.20. in Praire2021.

This value is used for estimating preimpoundment reservoir CH\(_4\) emissions from water bodies present in the inundated area prior to inundation on top of what was emitted from soil (based on inundated soil land cover composition and soil type).

Parameters:

wind_height (float) – The height at which the wind speed is measured, in meters. Default is 50 meters.

Returns:

The CH\(_4\) emission factor for the water body, kg CH\(_4\)/ha/yr.

Return type:

float

check_geometry(error_margin: float = 5) → bool

Check if the mean depth in the input data is near the value obtained from volume and surface area.

If the difference is less than the error margin, returns True, otherwise returns False.

Parameters:

error_margin (float) – The allowable error margin in percent. Default is 5.

Returns:

True if the difference is less than the error margin, otherwise False.

Return type:

bool

compare_mean_depth() → float

Compare the mean depth of the reservoir against the calculated mean depth from volume and area.

Returns the relative difference between the data and the calculated value in percents. Refer to Eqs. A.8./A.9./A.10. in Praire2021.

\[100 \, \frac{\bar{h}_{\textrm{from data}}-\bar{h}_{\textrm{from volume}}}{\bar{h}_{\textrm{from data}}}\]

Returns:

The relative difference between the data and the calculated mean depth, %.

Return type:

float

coordinates: Tuple[float, float]

property discharge: float

Return discharge from the reservoir.

Over a long enough timescale compared to residence time, discharge is equal to the inflow rate.

Returns:

Discharge, m\(^3\)/year.

Return type:

float

classmethod from_dict(parameters: dict, **kwargs) → ReservoirType

Initialize the class from a dictionary.

Skips keys that are not attributes of the class.

Parameters:

parameters (dict) – Dictionary of parameters.

Returns:

An instance of the Reservoir class.

Return type:

ReservoirType

global_radiance(period: str = 'd') → float

Calculate cumulative global horizontal radiance as a function of reservoir’s latitude.

Eq. A.29. from Praire2021.

Parameters:

period (str) – Time period. Options are “d” for day and “m” for month.

Returns:

Global horizontal radiance, kWh/m\(^2\)/period.

Return type:

float

Caution

The multiplier of 30.4 was included in the published in G-Res Technical Documentation but not in Praire2021. This multiplier converts the unit of radiance from kWh/m\(^2\)/day to kWh/m\(^2\)/month. However, this results in very high CH\(_4\) emission estimates. Hence, we set it to 1.0.

inflow_rate: float

property latitude: float

Obtain latitude from coordinates.

Returns:

Latitude of the reservoir.

Return type:

float

littoral_area_frac() → float

Calculate the percentage of the reservoir’s surface area that is littoral (close to the shore). Refer to Eq. A22 in Praire2021.

Ensure that the return value is always greater than 0.

Returns:

Littoral area fraction in percent.

Return type:

float

\[f_{lit} = 100 \left(1-\left(1-3/h_{max}\right)^{s_{q,bath}}\right)\]

where:

\(f_{lit}\), \(h_{max}\), and \(s_{q,bath}\) are, respectively, the littoral area fraction (%), maximum reservoir depth (m), and q-bathymetric shape.

property longitude: float

Obtain longitude from coordinates.

Returns:

Longitude of the reservoir.

Return type:

float

max_depth: float

mean_depth: float

mean_monthly_windspeed: float

mean_radiance: float

mean_radiance_lat() → float

Select representative mean horizontal radiance for a reservoir depending on its latitude.

Returns:

Mean horizontal radiance in kWh/m\(^2\)/d.

Return type:

float

mean_radiance_may_sept: float

mean_radiance_nov_mar: float

name: str = 'n/a'

q_bath_shape() → float

Calculate q-bathymetric shape. Refer to Eq. A21 in Praire2021.

\[s_{q,bath} = \frac{h_{max}}{h_{mean}} - 1\]

where:

\(s_{q,bath}\), \(h_{max}\), and \(h_{mean}\) are, respectively, the q-bathymetric shape, maximum reservoir depth, and mean reservoir depth.

Returns:

The q-bathymetric shape.

Return type:

float

reservoir_conc(inflow_conc: float, method: str | None = None) → float

Calculate the reservoir concentration based on inflow concentration and the reservoir retention coefficient.

Parameters:

• inflow_conc (float) – The inflow concentration, usually TP/TN concentration, \(\mu\)grams/L.

• method (Optional[str]) – Retention coefficient estimation method.

Returns:

The reservoir concentration, same unit as inflow_conc

Return type:

float

property residence_time: float

Calculate water residence time (WRT) from inflow rate and reservoir volume.

Residence time represents the average amount of time that a molecule of water spends in a reservoir or lake. With assumed units of m\(^3\) for volume and m\(^3\)/year for inflow rate the residence time is given in years.

Returns:

Water residence time, years.

Return type:

float

retention_coeff(method: str) → float

Return the retention coefficient using the chosen calculation method.

Parameters:

method (str) – Retention coefficient calculation method.

Returns:

The retention coefficient based on the selected method.

Return type:

float

property retention_coeff_emp: float

Empirical retention coefficient for solutes.

Obtained from regression with residence time in years.

\[f_R = 1 - \frac{1}{1+0.801\,WRT}\]

Returns:

Empirical retention coefficient, –

Return type:

float

property retention_coeff_larsen: float

Retention coefficient using the model of Larsen and Mercier (1976) for Phosphorus retention.

Assumes residence time in years.

Returns:

Retention coefficient, –

Return type:

float

soil_carbon: float

surface_ch4_conc(waterbody_area: float) → float

Calculate the surface water CH\(_4\) concentration in mg CH\(_4\)/m\(^3\) (\(\mu\)g/L). Refer to Eq. A.19. in Praire2021.

Parameters:

waterbody_area (float) – The area of the waterbody, km\(^2\).

Returns:

The surface water CH\(_4\) concentration in mg CH\(_4\)/m\(^3\) (\(\mu\)g/L).

Return type:

float

surface_density() → float

Calculate the water density in kg/m\(^3\) at the surface of the reservoir. Refer to Equation A.4. in Praire2021.

Returns:

The water density at the surface of the reservoir, kg/m\(^3\).

Return type:

float

surface_temperature() → float

Calculate the surface (epilimnion) temperature as the mean temperature of the 4 warmest months in a year. Refer to Equation A.4. in Praire2021.

Returns:

The surface temperature of the reservoir, degrees Celcius.

Return type:

float

temperature: MonthlyTemperature

thermocline_depth(wind_speed: float | None = None, wind_height: float = 50) → float

Calculate the thermocline depth required for the calculation of CH\(_4\) degassing.

Assumes that the surface water temperature is equal to the mean monthly air temperature from the 4 warmest months in the year.

Follows the equation in Gorham and Boyce (1989): https://www.sciencedirect.com/science/article/pii/S0380133089714799 Influence of Lake Surface Area and Depth Upon Thermal Stratification and the Depth of the Summer Thermocline, Gorham, Eville and Boyce, Farrell M. Journal of Great Lakes ResearchOpen AccessVolume 15, Issue 2, Pages 233 - 245, 1989.

If wind_speed or monthly_temp is not supplied, a simplified equation from Hanna 1990 is used, as implemented in G-Res.

Parameters:

• wind_speed (Optional[float]) – Average annual wind speed at the location of the reservoir, m/s.

• wind_height (float) – Height at which wind_speed is measured, in meters. Default is 50 meters.

Returns:

The thermocline depth of the reservoir, m.

Return type:

float

trophic_status(tp_inflow_conc: float, as_value: bool = True) → Enum | str

Return the reservoir’s trophic status depending on the influent TP concentration.

Parameters:

• tp_inflow_conc (float) – The TP concentration in the inflow, in \(\mu\)grams/L.

• as_value (bool) – Whether to return the value or the Enum. Default is True.

Returns:

The trophic status of the reservoir.

Return type:

Enum | str

validate_attributes() → None

Validate object attributes and correct if necessary.

volume: float

property volume_km3: float

Return volume in km\(^3\).

Note

The attribute value is in m\(^3\).

Returns:

Volume, km\(^3\).

Return type:

float

property wat_area_frac_pre: float

Return the fraction of reservoir area that was water prior to impoundment.

Returns:

Fraction of the reservoir area that was water before impoundment.

Return type:

float

water_intake_depth: float