skip to main content
Water Quality : Reach Water Quality : Solution/Dispatching : Dispatch Methods
Dispatch Methods
The following water quality dispatch methods exist on all reaches. For the method to be executed the first time for each timestep, both the known and unknown slot lists must be satisfied. Once a dispatch method has been invoked in normal simulation, the same method is executed again if any slot value is reset; normally, this is caused by a value propagating across a link. Each dispatch method represents a possible combination of constituent and solution approach choices made at the global level.
* Solve Discretized Temp
This dispatch methods executes the selected method in the Water Quality Routing category (see Water Quality Routing).
Required Known Slots
• Inflow
• Outflow
• Inflow Heat
Unknown slots
• Outflow Heat
* Solve Discretized Salt
This dispatch methods executes the selected method in the Water Quality Routing category (see Water Quality Routing).
Required Known Slots
• Inflow
• Inflow Salt Concentration
• Outflow
Required Unknown Slots
• Outflow Salt Concentration
• Outflow Salt Mass
* Solve Discretized Temp and Salt
This dispatch methods executes the selected method in the Water Quality Routing category (see Water Quality Routing):
Required Known Slots
• Inflow
• Inflow Salt Concentration
• Inflow Heat
• Outflow
Required Unknown Slots
• Outflow Heat
• Outflow Salt Mass
• Outflow Salt Concentration
* Solve Discretized Temp and DO
This dispatch methods executes the selected method in the Water Quality Routing category (see Water Quality Routing):
Required Known Slots
• Inflow
• Outflow Dissolved Oxygen Mass
• Inflow Ammonia Mass
• Inflow Heat
• Inflow Detritus Mass
• Outflow
• Inflow Dissolved Organics Mass
Required Unknown Slots
• Outflow Ammonia Mass
• Outflow Dissolved Oxygen Mass
• Outflow Detritus Mass
• Outflow Heat
• Outflow Dissolved Organics Mass
* Solve Discretized Temp Salt and DO
This dispatch methods executes the selected method in the Water Quality Routing category (see Water Quality Routing):
Required Known Slots
• Inflow
• Outflow Dissolved Oxygen Mass
• Inflow Ammonia Mass
• Inflow Heat
• Inflow Detritus Mass
• Inflow Salt Concentration
• Inflow Dissolved Organics Mass
• Outflow
Required Unknown Slots
• Outflow Ammonia Mass
• Outflow Dissolved Oxygen Mass
• Outflow Detritus Mass
• Outflow Heat
• Outflow Dissolved Organics Mass
• Outflow Salt Mass
• Outflow Salt Concentration
* Solve Out Salt Given In Salt
This dispatch method is called when the Inflow, Outflow, and Inflow Salt Concentration slots are known and the Outflow Salt Concentration slot is unknown.
Required Known Slots
• Inflow
• Local Inflow Salt Concentration (if Instantiated)
• Inflow Salt Concentration
• Outflow
• Local Inflow (if instantiated)
Required Unknown Slots
• Outflow Salt Concentration
Method Details  
If Maximum Salt Concentration does not contain a valid value, the run will abort.
Equivalent volumes over the timestep are calculated for the following flows: Inflow, Outflow, Diversion, Local Inflow (plus Local Inflow Adjust), Return Flow.
Inflow Salt Mass and Local Inflow Salt Mass are calculated by multiplying each concentration by the corresponding flow volume. If Local Inflow is zero and Local Inflow Salt Concentration is not specified, Local Inflow Salt Concentration and Local Inflow Salt Mass are set equal to zero.
Next calculate the diversion salt. If Diversion Salt Concentration is not specified (input or set by a rule on either the reach slot or linked slot), the local variable tempDivSaltConc is set to the minimum of the Inflow Salt Concentration and Diversion Salt Concentration Maximum (if specified). If Diversion Salt Concentration is specified, tempDivSaltConc is set to the specified value. If Diversion Salt Concentration is specified, then Return Flow must be zero (the “Special Export” condition). If Diversion Salt Concentration is specified and Return Flow is non-zero, the run will abort with an error message.
Then a check is made to see if the corresponding salt mass is available to be diverted. It will not allow more salt to be diverted than is in the inflow.
IF
IF
All of the Inflow Salt Mass will be diverted.
ELSE (Inflow Salt Mass is negative)
END IF
ELSE (There is sufficient salt mass in the inflow to meet the calculated diversion mass.)
END IF
If the Diversion Salt Concentration is not specified, then the slot value will be calculated based on the final Diversion Salt Mass.
IF
If Diversion is zero or is unused, Diversion Salt Concentration will be set to zero.
END IF
Note:  A specified Diversion Salt Concentration value will not be changed even when the Diversion Salt Mass is reduced, but a warning message will be issued to notify the user that the Diversion Salt Mass does not correspond to the specified Diversion Salt Concentration. The appropriate mass balance will be maintained.
If Return Flow Salt Mass is linked but not valid, the method will exit and wait for the linked Agg Diversion Site to solve for Return Flow Salt Mass. If Return Flow Salt Mass is not linked and does not contain a value, it will default to zero.
If Salt Storage at the previous timestep is invalid (NaN), the local variable prevSaltStorage is set equal to 0. Otherwise it is set equal to Salt Storage at the previous timestep.
If Salt Available For Removal is linked, a check is made that Minimum Salt Concentration contains a valid value (otherwise Minimum Salt Concentration is an optional input). If Minimum Salt Concentration does not contain a valid value, the run will abort and an error message will be posted. Then Salt Available For Removal is calculated as follows:
IF
ELSE (negative Outflow)
For negative Outflow, removing salt will raise the concentration, so the maximum available for removal is based on the Maximum Salt Concentration.
END IF
If Salt Mass Removal is linked, it will check for a value in the slot. If there is no value, the method will exit and wait for the linked Agg Diversion Site to solve. If the slot is not linked and it does not contain an input value, it is set to zero.
Then the initial salinity mass balance solves for the local variable tempOutSaltMass:
    
After setting tempOutSaltMass it then carries out the following logic to check if the Outflow Salt Mass should be adjusted:
IF
IF
If there is no Outflow, and positive tempOutSaltMass will get added to Salt Storage.
ELSE (tempOutSaltMass is negative)
IF
Any available Salt Storage will be used to bring the Outflow Salt Mass up to 0.
ELSE (There is not enough Salt Storage to make up the negative tempOutSaltMass.
The negative salt will be added to the Salt Storage to make it more negative. A warning message is posted in this case: “The reach calculated that -11587.04 * 1.0 tons of salt must be stored. The new Salt Storage is ‑11587.036381 * 1.0 tons.”
END IF
END IF
ELSE (Outflow is non-zero.)
Solve for the initial outflow concentration
IF
Set the concentration to the maximum. Any excess salt will get added to Salt Storage.
ELSE IF
Set the concentration to the minimum. Any excess salt will get added to Salt Storage below.
ELSE
END IF
END IF
END IF
Finally calculate the new Salt Storage.
* Solve In Salt Given Out Salt
This dispatch method is called when the Inflow, Outflow, and Outflow Salt Concentration slots are known and the Inflow Salt Concentration slot is unknown.
Required Known Slots
• Inflow
• Outflow
• Local Inflow (if instantiated)
• Outflow Salt Concentration
• Local Inflow Salt Concentration (if instantiated)
Required Unknown Slots
• Inflow Salt Concentration
Method Details  
If Maximum Salt Concentration does not contain a valid value, the run will fail.
Equivalent volumes over the timestep are calculated for the following flows: Inflow, Outflow, Diversion, Local Inflow (plus Local Inflow Adjust), Return Flow.
If Local Inflow is zero and Local Inflow Salt Concentration is not specified, Local Inflow Salt Concentration and Local Inflow Salt Mass are set equal to zero.
In order for the Reach to solve for inflow salt and diversion salt, it must know the return flow salt, which is solved for by the linked object or must be specified. If Return Flow Salt Mass is linked, and it is not linked to the same object as the Diversion Salt Concentration, then the Return Flow Salt Mass must be valid, or the method will exit and wait for more information.
If Return Flow Salt Mass and Diversion Salt Concentration are linked to the same Agg Diversion Site, the Return Flow Salt Mass from the Agg Diversion Site is calculated as follows:
    
    Or if Return Flow is zero, then .
Therefore, if the Reach knows the value for saltPickupMass, it can solve for inflow salt and diversion salt. The Reach retrieves the value for saltPickupMass from one of four slots on the Agg Diversion Site, depending on which Return Flow Salt method is selected on the Agg Diversion Site, as described in Table 13.1.
Note:  Return Flow Salt Mass can only be linked to a single slot.
 
Table 13.1   
Agg Diversion Site
Return Flow Salt Method / Salinity Pickup Method (If Applicable)
saltPickupMass
None
0
Variable Salt Pickup/Salt Pickup Concentration
Variable Salt Pickup/Salt Pickup Mass
Return Flow Salinity Pickup Mass
Distributed Annual Salt Loading
Distributed Salinity Pickup Mass
Lumped Salt
Salt Loading
If Salt Storage at the previous timestep is invalid (NaN) or negative, the local variable prevSaltStorage is set equal to 0. Otherwise it is set equal to Salt Storage at the previous timestep.
Outflow Salt Mass and Local Inflow Salt Mass are calculated by multiplying each concentration by the corresponding flow volume.
If Salt Available For Removal is linked, its value is calculated as follows:
IF
IF
IF
ELSE (negative Inflow)
END IF
ELSE (Diversion Salt Concentration is not specified)
IF
ELSE (negative Inflow)
END IF
END IF
ELSE (Return Flow is non-zero, so diversion salt cancels from the mass balance)
IF
ELSE (negative Inflow)
END IF
END IF
If Salt Mass Removal is linked, the method will check for a value in the slot. If there is no value, the method will exit and wait for the linked Agg Diversion Site to solve. If the slot is not linked and it does not contain an input value, it is set to zero.
Then the initial salinity mass balance solves for the local variable tempInSaltMass. The form of the mass balance depends on whether there is a non-zero Return Flow and whether or not Diversion Salt Concentration is specified (input or set by a rule on either the reach slot or linked slot).
IF
If Return Flow is non-zero, all diverted salt mass gets returned and thus cancels from the mass balance.
IF
There cannot be a non-zero salt mass if there is no Inflow.
IF
IF
Use any Salt Storage to make up the difference, so that Inflow Salt Mass will be zero. The change in Salt Storage will be accounted for at the end of the method.
ELSE
There is not enough Salt Storage to make up the difference. This would result in positive salt with no flow, so the run will abort with an error message.
END IF
ELSE (tempInSaltMass is negative or zero)
Any change will be added to Salt Storage.
END IF
ELSE (Inflow is non-zero)
Incorporate salt from storage if there is any.
IF
IF
If the Minimum Salt Concentration is specified, calculate the corresponding minimum mass. Minimum Salt Concentration is generally an optional input, but it is a required input if using one of the Salt Removal methods on a linked Agg Diversion Site.
ELSE
If the minimum is not specified, all Salt Storage will be incorporated.
END IF
ELSE
For a negative Inflow, incorporating more salt from storage will lower the Inflow Salt Mass but will raise the Inflow Salt Concentration, so the minimum inflow mass is based on the Maximum Salt Concentration.
END IF
IF
Use up all of the salt from storage.
ELSE
Using up all Salt Storage would take Inflow Salt Concentration below the minimum, so only take it down to the minimum.
This also takes care of the case when tempInSaltMass is already less than the minimum. It will bring the inflow salt up to the minimum, and the difference will get added to Salt Storage.
END IF
END IF
Calculate the change in Salt Storage.
ELSE (Return Flow is zero. It is either the “Special Export” condition or there is no Diversion.)
The mass balance calculation depends on whether or not Diversion Salt Concentration is an specified (input or set by a rule on either the reach slot or linked slot)
IF
IF
There cannot be a non-zero salt mass if there is no Inflow.
IF
IF
Use any Salt Storage to make up the difference, so that Inflow Salt Mass will be zero. The change in Salt Storage will be accounted for at the end of the method.
ELSE
There is not enough Salt Storage to make up the difference. This would result in positive salt with no flow, so the run will abort.
END IF
ELSE (tempInSaltMass is negative or zero)
Any change will be added to Salt Storage.
END IF
ELSE (Inflow is non-zero)
Incorporate salt from storage if there is any.
IF
IF
If the Minimum Salt Concentration is specified, calculate the corresponding minimum mass. Minimum Salt Concentration is generally an optional input, but it is a required input if using one of the Salt Removal methods on a linked Agg Diversion Site.
ELSE
If the minimum is not specified, all Salt Storage will be incorporated.
END IF
ELSE
For a negative Inflow, incorporating more salt from storage will lower the Inflow Salt Mass but will raise the Inflow Salt Concentration, so the minimum inflow mass is based on the Maximum Salt Concentration.
END IF
IF
Use up all of the salt from storage.
ELSE
Using up all Salt Storage would take Inflow Salt Concentration below the minimum, so only take it down to the minimum.
This also takes care of the case when tempInSaltMass is already less than the minimum. It will bring the inflow salt up to the minimum, and the difference will get added to Salt Storage.
END IF
END IF
Calculate the change in Salt Storage.
ELSE (Return Flow is zero, and Diversion Salt Concentration is not specified.)
Diversion Salt Concentration will either be zero (if there is no Diversion), or it will be equal to the Inflow Salt Concentration.
First calculate the initial net in salt mass. This is the Inflow Salt Mass minus the Diversion Salt Mass.
IF
There cannot be a non-zero salt mass if there is no net flow.
IF
IF
Use any Salt Storage to make up the difference, so that netInSaltMass will be zero. The change in Salt Storage will be accounted for at the end of the method.
ELSE
There is not enough Salt Storage to make up the difference. This would result in positive salt with no flow, so the run will abort.
END IF
ELSE (tempNetInSaltMass is negative or zero)
Any change will be added to Salt Storage.
END IF
ELSE (netInVol is non-zero)
Incorporate salt from storage if there is any.
IF
IF
If the Minimum Salt Concentration is specified, calculate the corresponding minimum mass. Minimum Salt Concentration is generally an optional input, but it is a required input if using one of the Salt Removal methods on a linked Agg Diversion Site.
ELSE
If the minimum is not specified, all Salt Storage will be incorporated.
END IF
ELSE
For a negative netInVol, incorporating more salt from storage will lower the netInSaltMass but will raise the concentration, so the minimum mass is based on the Maximum Salt Concentration.
END IF
IF
Use up all of the salt from storage.
ELSE
Using up all Salt Storage would take Inflow Salt Concentration below the minimum, so only take it down to the minimum.
This also takes care of the case when tempInSaltMass is already less than the minimum. It will bring the inflow salt up to the minimum, and the difference will get added to Salt Storage.
END IF
END IF
Calculate the Inflow Salt Mass and the change in Salt Storage.
END IF
END IF
Set the final Diversion Salt Concentration if it is not specified, and calculate the Diversion Salt Mass.
IF
IF
ELSE
END IF
END IF
    
Finally calculate the new Salt Storage.
    
* Solve Local In Salt Given In and Out
This dispatch method is called when the Inflow, Outflow, Local Inflow, Inflow Salt Concentration and Outflow Salt Concentration slots are known and the Local Inflow Salt Concentration slot is unknown.
Required Known Slots
• Inflow
• Outflow
• Inflow Salt Concentration
• Outflow Salt Concentration
• Local Inflow
Required Unknown Slots
• Local Inflow Salt Concentration
Method Details  
If Maximum Salt Concentration does not contain a valid value, the run will abort.
Equivalent volumes over the timestep are calculated for the following flows: Inflow, Outflow, Diversion, Local Inflow (plus Local Inflow Adjust), Return Flow.
Inflow Salt Mass and Local Inflow Salt Mass are calculated by multiplying each concentration by the corresponding flow volume. If Local Inflow is zero and Local Inflow Salt Concentration is not specified, Local Inflow Salt Concentration and Local Inflow Salt Mass are set equal to zero.
Next calculate the diversion salt. If Diversion Salt Concentration is not specified (input or set by a rule on either the reach slot or linked slot), the local variable tempDivSaltConc is set to the minimum of the Inflow Salt Concentration and Diversion Salt Concentration Maximum (if specified). If Diversion Salt Concentration is specified, tempDivSaltConc is set to the specified value. If Diversion Salt Concentration is specified, then Return Flow must be zero (the “Special Export” condition). If Diversion Salt Concentration is specified and Return Flow is non-zero, the run will abort with an error message.
Then a check is made to see if the corresponding salt mass is available to be diverted. It will not allow more salt to be diverted than is in the inflow.
IF
IF
All of the Inflow Salt Mass will be diverted.
ELSE (Inflow Salt Mass is negative)
END IF
ELSE (There is sufficient salt mass in the inflow to meet the calculated diversion mass.)
END IF
If the Diversion Salt Concentration is not specified, then the slot value will be calculated based on the final Diversion Salt Mass.
IF
If Diversion is zero or is unused, Diversion Salt Concentration will be set to zero.
END IF
Note:  A specified Diversion Salt Concentration value will not be changed even when the Diversion Salt Mass is reduced, but a warning message will be issued to notify the user that the Diversion Salt Mass does not correspond to the specified Diversion Salt Concentration. The appropriate mass balance will be maintained.
If Return Flow Salt Mass is linked but not valid, the method will exit and wait for the linked Agg Diversion Site to solve for Return Flow Salt Mass. If Return Flow Salt Mass is not linked and does not contain a value, it will default to zero.
If Salt Storage at the previous timestep is invalid (NaN) or negative, the local variable tempInSaltMass is set equal to 0. Otherwise it is set equal to Salt Storage at the previous timestep.
Inflow Salt Mass, Outflow Salt Mass and Diversion Salt Mass are calculated by multiplying each concentration by the corresponding flow volume.
If Salt Available For Removal is linked, its value is calculated as follows:
IF
ELSE (negative Local Inflow)
For negative Outflow, removing salt will lower the concentration, so the maximum available for removal is based on the Minimum Salt Concentration.
END IF
If Salt Mass Removal is linked, it will check for a value in the slot. If there is no value, the method will exit and wait for the linked Agg Diversion Site to solve. If the slot is not linked and it does not contain an input value, it is set to zero.
Then the initial salinity mass balance solves for the local variable tempInSaltMass:
    
After setting tempInSaltMass it then carries out the following logic to check if the Local Inflow Salt Mass should be adjusted:
IF
IF
IF
Use any Salt Storage to make up the difference, so that Local Inflow Salt Mass will be zero. The change in Salt Storage will be accounted for at the end of the method
ELSE
There is not enough Salt Storage to make up the difference. This would result in positive salt with no flow, so the run will abort.
END IF
ELSE (tempInSaltMass is negative or zero)
Any change will be added to Salt Storage.
END IF
ELSE (Local Inflow is non-zero)
Incorporate salt from storage if there is any.
IF
IF
If the Minimum Salt Concentration is specified, calculate the corresponding minimum mass. Minimum Salt Concentration is generally an optional input, but it is a required input if using one of the Salt Removal methods on a linked Agg Diversion Site.
ELSE
If the minimum is not specified, all Salt Storage will be incorporated.
END IF
ELSE
For a negative Local Inflow, incorporating more salt from storage will lower the Local Inflow Salt Mass but will raise the Local Inflow Salt Concentration, so the minimum local inflow mass is based on the Maximum Salt Concentration.
END IF
IF
Use up all of the salt from storage.
ELSE
Using up all Salt Storage would take Local Inflow Salt Concentration below the minimum, so only take it down to the minimum.
This also takes care of the case when tempInSaltMass is already less than the minimum. It will bring the local inflow salt up to the minimum, and the difference will get added to Salt Storage.
END IF
END IF
Calculate the change in Salt Storage.
* Solve Outflow TDG
This dispatch method is called when the Inflow TDG Concentration is known.
This method executes the Water Quality Routing method: No Routing; TDG, Time Lag; TDG, or Time Lag TDG with Dispersion and Dissipation.
Required Known Slots
• Inflow TDG Concentration
Required Unknown Slots
• None
Revised: 07/09/2023