Posted by Jason Lillywhite
This blog post describes a GoldSim model application that integrates the rTemp water temperature model. Originally developed by the Washington State Department of Ecology, the tool calculates the thermal dynamics of water bodies and has been ported to a Python library available for download from the GoldSim Help Center. This example demonstrates how to bridge daily timestep system models with hourly physics calculations, illustrated through a comparison of three distinct method configurations.
What is Response Temperature?
The name rTemp stands for Response Temperature. This is defined as the temperature that a fully mixed column of water would reach if surface heat fluxes were the only heat transfer processes occurring. The model calculates the rate of change in water temperature based on a net heat flux approach, represented by the governing equation:
dT/dt = Jnet / (D × ρw × Cpw)
Where the net heat flux (Jnet) accounts for the gain and loss of heat through:
- Solar Shortwave Radiation: The largest heat source during the day.
- Longwave Atmospheric Radiation: Thermal infrared radiation from the atmosphere.
- Longwave Back Radiation: Heat lost from the water surface.
- Convection & Evaporation: Driven by wind speed and vapor pressure gradients.
- Sediment Conduction: Heat exchange with the streambed.
Method Selection
A feature of this Python implementation is the ability to select calculation methods based on available data.
For example, if atmospheric data is limited, the model can use the Bras method for solar radiation and the Brunt method for longwave radiation, which rely primarily on air temperature and turbidity estimates. For applications with detailed data (such as ozone and aerosols), the model can be configured to use the Bird-Hulstrom method. Wind functions can be selected based on the water body type, such as river-specific methods (e.g., Ryan-Harleman) or lake-specific methods (e.g., Marciano-Harbeck).
 |
| Screen capture of the GoldSim model with rTemp integration |
Integration with GoldSim
This example demonstrates how to use the GSPy Python bridge to incorporate these physics calculations into GoldSim. GoldSim manages the system logic, water balance, and state, while rTemp performs the hourly heat budget calculations.
Because the Python physics engine is stateless, GoldSim acts as the controller, managing the water balance and passing data to Python only when a calculation is required.
Prerequisites
To run this integration, the following tools are required:
- GoldSim 15 (or later)
- Python 3.11 or 3.14 (64-bit distribution)
- GSPy 1.8.8 (The platform-specific C++ bridge DLL)
- Python Libraries:
numpy,pandas,scipy, and thertemppackage.
The rtemp package is installed via pip: pip install git+https://github.com/jlillywh/rTemp.git
The Adapter Script
The integration relies on a Python script (rtemp_goldsim_adapter.py) that interfaces between the two environments. The script performs a temporal reconstruction at each step:
- Input & Validation: Accepts current conditions (flow, geometry, meteorology) and validates them. It checks for dry-bed conditions (depth < 0.01m) to prevent numerical instability.
- Disaggregation: Converts daily inputs (such as Min/Max Air Temp) into a 24-hour internal profile.
- Execution: Runs the rTemp physics engine for 24 hourly iterations.
- Return: Calculates final water and sediment temperatures and returns them to GoldSim along with diagnostic data.
 |
| Schematic diagram showing how the tools interact. |
Managing State in GoldSim
Since the Python script is stateless, GoldSim must retain the water temperature from the previous timestep. This is achieved using a State Variable Feedback Loop:
- An External Element calls the Python script and outputs the
New_Water_Temp. - A Previous Value Element captures this result.
- In the next timestep, the Previous Value element feeds the temperature back into the External Element as the
Initial_Water_Temp.
 |
| Screen capture showing how the GoldSim model interfaces with rTemp |
Comparing Method Combinations
To demonstrate the application of different physics options, the model was run using three combinations of calculation methods. Each combination was selected to represent specific environmental conditions or data availability:
- Standard (Bras-Brunt-BGG): The default configuration using Bras solar radiation, Brunt longwave radiation, and Brady-Graves-Geyer wind function. This combination is suitable for general applications.
- Humid Climate (Ryan-Brutsaert-RH): Uses Ryan-Stolzenbach solar (elevation-aware), Brutsaert longwave, and Ryan-Harleman wind function. This combination is typically applied in humid climates and flowing water.
- Variable Atmosphere (Iqbal-Brunt-MH): Employs Iqbal solar radiation (visibility-based), Brunt longwave, and Marciano-Harbeck wind function (from Lake Hefner studies). This configuration accounts for variable atmospheric conditions.
 |
| Comparison of water temperature predictions using three different method combinations over the simulation period. |
While all three scenarios produce similar overall trends, predicted temperatures diverge based on the methodology. The Standard scenario provides a baseline, while the Humid Climate scenario predicts slightly higher temperatures due to reduced evaporative cooling from the Brutsaert longwave method. The Variable Atmosphere scenario demonstrates sensitivity to atmospheric changes via the Iqbal solar radiation method.
These differences indicate the importance of selecting methods appropriate to site conditions. The ability to switch between method combinations within GoldSim facilitates sensitivity analysis and uncertainty quantification.
Assumptions
The model assumes a well-mixed water column, meaning there is no vertical stratification; the surface temperature is effectively the bulk temperature. This approach is applicable to streams, rivers, and shallow water bodies.
The physics are customizable. The ModelConfiguration can be adjusted within the Python script to toggle between different radiation models or wind functions without changing the GoldSim model structure. Alternatively, the adapter can be configured to control method selection directly from GoldSim using integer codes, enabling dynamic scenario comparison.
Conclusion
The GSPy bridge allows GoldSim to leverage rTemp's physics calculations within a probabilistic framework. This addresses the timescale difference between daily system models and hourly heat budget requirements, providing a solution for water quality modeling.
