Utility Methods

Utility Methods are methods (subroutines, or functions) which do not belong to a user-selectable method type. Each of the utility methods outlined below is used by one or more of the methods above.

Note: Some of these methods set slots directly, while others return values but do not set slots explicitly.

calcHar

This method returns Har (J/(m^2*day), the surface heat flux due to incoming solar radiation.

Method Details

The method uses the following equation (Thomann and Mueller, 1987).

(13.6)

where

The values of the Stefan-Boltzmann constant and A are constants or internally set variables. Ta is user input through the Air Temperature slot, and air vapor pressure is returned by the getAirVaporPressure method (see below).

calcHbr

This method returns Hbr (J/(m^2*day), the longwave radiation emitted by the reach.

Method Details

The method uses the Stefan-Boltzmann law for a (nearly perfect) black-body emitter.

(13.7)

where

The values of the Stefan-Boltzmann constant and emissivity are static variables. Ts is the value of the reach segment temperature from the previous timestep (Distributed Temperature Output(‑1)).

calcHc

This method returns Hc (J/(m^2*day), the heat flux at the reach surface due to conduction.

Method Details

The form of the equation is as follows.

(13.8)

where:

getWindEffect is a utility method (see below) and 41860 is the conversion rate from cal/cm2 to J/m2.

calcHe

This method returns He (J/(m^2*day)), the heat flux at the surface due to evaporative heat loss.

Method Details

The form of the equation is as follows.

(13.9)

where

getWindEffect is a utility method and 41860 is the conversion rate from cal/cm2 to J/m2.

checkSideFlowConcDO

The function checkSideFlowConcDO checks detritus, ammonia, dissolved organics, and dissolved oxygen concentrations associated with side flows and sets them if appropriate.

Method Details

First, if Local Inflow is not in use, issue an error.

Next, if Diversion concentration for each DO component is not valid, set it to the respective inflow concentrations. If the respective return flow concentrations or local inflow concentrations are linked but are not valid, the method is exited so that the other object can solve first and propagate a concentration across the link.

checkSideFlowConcSalt

The function checkSideFlowConcSalt checks salt concentrations associated with side flows.

Method Details

First, if Local Inflow Salt Concentration is linked but not valid, exit the method and wait for it to become valid. If it is not linked, but Local Inflow is linked and Local Inflow Salt Concentration is not valid, issue an error that you should specify the value.

If Return Flow Salt Concentration is linked but not valid, exit the method and wait for it to become valid. If it is not linked, but Return Flow is linked and Return Flow Salt Concentration is not valid, issue an error that you should specify the value.

checkSideFlowTemp

The function, checkSideFlowTemp, checks temperatures associated with side flows and sets them if appropriate.

Method Details

First, if the previous Diversion Temperature is not valid, set a local variable temp to 10deg Celsius. Otherwise, set temp to the previous Diversion Temperature. This value is used to compute the density of the water. If the current Diversion Temperature is not valid, set it to:

(13.10)

If Local Inflow is in use but Local Inflow Temperature is linked but not valid, exit the method and wait for it to become valid.

If Return Flow Temperature is linked but not valid, exit the method and wait for it to become valid.

defaultCalcSurfaceFlux

This method is called from solveTempWQcontrolVolume Explicit and solveTempControlVolumeImplcit. This method calls several subroutines, each of which calculate a specific flux type. The total flux is recorded in the Surface Heat Flux slot. It is the sum of incoming solar radiation (input variable), long and short wave back radiation (calcHar and calcHbr), conductive/convective (calcHc), and evaporative (calcHe) heat fluxes.

getAirVaporPressure

This method returns Air Vapor Pressure, the vapor pressure of the air mass overlying the reach.

Method Details

The form of the equation is as follows.

(13.11)

where

getDensity

This method returns water density for a given temperature, temp.

Method Details

Calculations are based on the following polynomial relationship with temperature.

(13.12)

If this value evaluates to a density greater than 1x106 g/m3, the method returns 1x106 g/m3.

getQualStep

The function getQualStep is called if one of the control volume explicit methods is selected. It looks at Maximum Flow Rate for WQ Stability provided by the user and sets an internal water quality timestep, Water Quality Timestep Computed, in order to satisfy stability. It also sets Num WQ Steps per Sim Timestep.

getSurfaceVaporPressure

This method returns Surface Vapor Pressure, the vapor pressure at the surface of the reach.

Method Details

The form of the equation is as follows.

(13.13)

where

getWindEffect

This method returns Coefficient of Wind Effect, the effect of wind on the surface heat flux equations.

Method Details

The form of the equation is as follows.

(13.14)

where

solveNoRoutingDO

This method calculates Outflow Detritus Mass, Outflow Dissolved Organics Mass, Outflow Ammonia Mass, and Outflow Dissolved Oxygen Mass based on Inflow Detritus Mass, Inflow Diss Org Mass, Inflow Ammonia Mass, Inflow Diss Oxygen Mass and the associated side flow concentrations.

Method Details

Each constituent is calculated with the same basic equation where Constituent is DO variable.

(13.15)

solveNoRoutingOutSalt

This method calculates Outflow Salt Mass and Concentration based on Inflow Salt Conc, Return Flow Salt Concentration, Diversion Salt Concentration, Local Inflow Salt Concentration, Seepage Salt Concentration (if modeled), and the respective flows.

Method Details

If Diversion Salt Concentration is not input or set by a rule, then it is set to the Inflow Salt Concentration.

When a non-default Seepage method is selected and the water quality approach is Discretized Salt, Seepage Salt Concentration and Seepage Salt Mass slots are available. If Seepage is positive, the Seepage Salt Concentration is set to the Inflow Salt Concentration. If Seepage is negative, the Seepage Salt Concentration must be specified possibly by a link to a slot on another object. If Seepage Salt Concentration is linked but not valid, the reach exits the dispatch method and waits until the seepage Salt Concentration is available from that object. Seepage Salt Mass is computed from the Seepage Salt Concentration and the Seepage.

Note: Although there are Seepage Routing methods, these only serve to compute the Seepage at the current timestep. In general, Outflow = Inflow - Seepage. Thus, the Seepage Salt concentration does not need to be routed; it is just the value at that timestep.

Then, for each constituent, if the concentration and the flow is valid, the mass is computed. Otherwise the mass is considered zero, but not set.

Finally:

(13.16)

Finally, Outflow Salt Concentration is computed from the Outflow and Outflow Salt Mass.

solveNoRoutingTemp

This method calculates Outflow Heat based on Inflow Heat, Return Flow Temperature, Diversion Temperature, and Local Inflow Salt Temperature.

Method Details

The form of the equation is as follows.

(13.17)

where is water density and H is Specific Heat of Water.

solveSaltWQcontrolVolumeExplicit

There are two control volume water quality methods: controlVolumeExplicit and controlVolumeImplicit. Both of these methods utilize the discretized hydraulic variables generated from the hydraulic routing methods. Therefore, a hydraulic routing method must be used with the control volume water quality methods. The difference between controlVolumeExplicit and controlVolumeImplicit is simply in the solution technique described in the following sections

Method Details

This method uses the following mass balance equation for a conservative substance to Calculate Distributed Salt Concentration Output, the salt concentrations of each discretized segment of the reach. This function also sets Outflow Salt Mass for the reach.

(13.18)

where M = salt mass [M], c = salt concentration [M/L3], E = longitudinal dispersion coefficient [L2/T], and A = cross sectional area [L2].

solveSaltWQcontrolVolumeImplicit

This method calculates Distributed Salt Concentration Output, the salt concentrations of each discretized segment of the reach. This function also sets Outflow Salt Mass for the reach.

Method Details

This method uses the following mass balance equation for a conservative substance.

(13.19)

solveTempWQcontrolVolumeExplicit

This method calculates Distributed Temperature Output, the temperature of each discretized segment of the reach. This function also sets Outflow Heat for the reach.

Method Details

This method uses the following mass balance equation.

(13.20)

where T = water temperature, V = elemental volume [L3], H = flux of thermal energy across the system boundaries [H/L2/T], Asi = water surface area [L2], = water density [M/L3], and c = specific heat of water [H/M/Temp.]

solveTempWQcontrolVolumeImplicit

This method calculates Distributed Temperature Output, the temperature of each discretized segment of the reach. This function also sets Outflow Heat for the reach.

Method Details

This method uses the following mass balance equation.

(13.21)

solveTimeLagDO

This method calculates Outflow Detritus Mass, Outflow Diss Org Mass, Outflow Ammonia Mass, and Outflow Diss Oxygen Mass at future timesteps based on Inflow Detritus Mass, Inflow Diss Org Mass, Inflow Ammonia Mass, Inflow Diss Oxygen Mass at the current timestep and Lag Time of the reach.

solveTimeLagOutSalt

This method calculates Outflow Salt Concentration and Mass at future timesteps based on Inflow Salt Concentration at the current timestep and Lag Time of the reach.

solveVarTimeLagOutSalt

This method calculates Outflow Salt Concentration and Mass at future timesteps based on Inflow Salt Concentration at the current timestep (and previous timesteps) and Variable Lag Time of the reach.

Method Details

This method executes when the Inflow Salt Concentration is known for the current timestep. The resulting Inflow Salt Mass is computed using the Inflow. Outflow Salt Concentration (and Mass) values are solved for at the timesteps corresponding to the Variable Lag Time. A sample calculation is given below:

(13.22)

(13.23)

where flowFrac1 and flowFrac2 to are calculated by the following equations:

(13.24)

(13.25)

In the equations above, the integer value of a number means the number is truncated after the decimal point with no rounding.

Since the lag time can vary with every timestep, it possible that more the one Inflow Salt Mass can contribute to a particular Outflow Salt Mass/Concentration. This method may set multiple Outflow Salt Mass/Concentrations (up to the max lag) based on a range of previous and future Inflow Salt Mass values.

solveTimeLagTemp

This method calculates Outflow Heat based at future timesteps based on Inflow Heat at the current timestep and Lag Time of the reach.

setWQInitConds

The function getQualStep is called if one of the control volume methods (either explicit or implicit) is selected. It sets initial salt concentrations and temperatures in each internal reach segment by setting previous values on Distributed Salt Concentration Output, and Distributed Temperature Output.

Revised: 01/05/2024