Posted by Jason Lillywhite
This blog post describes a GoldSim model application that integrates the rTemp water temperature model into dynamic simulations. The rTemp model calculates the response temperature of water bodies using a comprehensive heat budget approach. Response temperature represents the equilibrium temperature that a fully mixed water column would reach based solely on surface heat exchange processes:
- solar radiation
- atmospheric longwave radiation
- evaporation
- convection
- sediment conduction
 |
| Screen capture of the GoldSim model with rTemp integration |
The integration uses the GSPy Python bridge to resolve a temporal scale mismatch: GoldSim operates at a daily timestep for water balance and state management, while rTemp performs high-resolution thermal physics calculations at an hourly timestep. This architecture allows GoldSim to leverage an external physics engine for detailed heat budget calculations while retaining control over simulation time, water balance, and state persistence. The approach is particularly useful for water quality modeling where accurate water temperature predictions are needed for regulatory compliance or ecological assessments.
The Python component, `rTemp`, does not maintain memory of the system state between calls. Instead, GoldSim acts as the central controller:
The following tools are needed for this implementation:
- GoldSim version 15
- Python 3.11 or 3.14 (64-bit distribution)
- GSPy version 1.8.8 (C++ bridge DLL)
- Python Libraries:
numpy,pandas,scipy, and thertemppackage.
The GSPy bridge is platform-specific (Windows-only) and necessitates a version-matched DLL (e.g., GSPy_Release_py314.dll for Python 3.14). Successful deployment requires configuration of the Python execution path within the GSPy JSON configuration file.
The rTemp package can be installed via: pip install git+https://github.com/jlillywh/rTemp.git
A script, named rtemp_goldsim_adapter.py, defines the entry point: a function (e.g., process_data) that accepts 12 input arguments and returns 3 output values.
The script executes the following sequence upon being called by GoldSim:
- Input Deconstruction: Input scalars and vectors are unpacked from the GSPy C-array structure.
- Validation and Exception Handling: Inputs are validated (e.g., checking latitude/longitude ranges). A check is performed for dry-bed conditions (water depth < 0.01 m), which triggers a bypass to prevent numerical instability.
- Temporal Reconstruction: Daily meteorological data (min/max Air Temp, Dewpoint) are used to construct a high-resolution
pandas DataFramewith hourly datetime stamps. Note: Dewpoint temperature is estimated internally from air temperature using typical dewpoint depression values, eliminating the need for separate dewpoint inputs. - Solar Synchronization: The simulation start date, passed from GoldSim, is used to synchronize the `REFERENCE_DATE` within the script, ensuring accurate solar geometry calculations (sun position, intensity) are performed internally by
rTemp. - Execution: The `rTemp` model is executed for 24 hourly iterations.
- State Extraction: Final state (New Water Temp, New Sediment Temp) and the diagnostic variable (Daily Avg Net Flux) are extracted and returned to GoldSim.
 |
| Schematic diagram showing how the tools interact. |
The JSON configuration file (e.g.,
GSPy_314.json) defines the mapping between the External Element and the Python environment. It specifies the python_path, the adapter script_path, and rigidly defines the number, type, and order of the inputs and outputs, which must match the Python function signature.
Within the GoldSim environment, the integration relies on the External Element and a State Variable Feedback Loop.
The External element is configured to link to the GSPy DLL and call the GSPy function interface. The key is ensuring that the 12 input scalar elements and 3 output scalar elements are defined in the exact, rigid sequence required by the Python adapter.
 |
| Screen capture showing the how the GoldSim model interfaces with rTemp |
State Variable Persistence
The stateless nature of the Python engine is overcome by using GoldSim’s Previous Value elements for water and sediment temperature. These elements are configured to:
- Receive their input from the External Element's outputs (e.g.,
rTemp.New_Water_Temp). - Feed their value back into the External Element's `Current_Temp` inputs for the next timestep.
Model Physics and Assumptions
The water temperature output returned by rTemp explicitly represents the water surface temperature. This calculation is based on the following core assumptions:
- Well-Mixed Condition: The model assumes the water body is vertically mixed with no stratification.
- Uniformity: The entire water column is treated as having a uniform temperature, meaning the surface temperature equals the bulk average temperature.
These assumptions are most appropriate for shallow water bodies (typically < 2-3 meters), well-mixed conditions driven by wind or flow, and daily timestep modeling where vertical stratification is less critical.
The script design preserves the flexibility of the underlying `rTemp` model. Within the Python script, the `ModelConfiguration` object allows for the selection and tuning of various physics methods used in the heat budget equation:
- Radiation Models: Options for Solar (Bras, Bird, Iqbal, Ryan) and Longwave (Brunt, Brutsaert, Swinbank) radiation calculations.
- Turbulence Models: Selection of different Wind function methods (e.g., Brady-Graves-Geyer).
This approach allows the GoldSim user to customize the thermal physics based on site-specific requirements without modifying the GoldSim model architecture.
Conclusion
The GSPy bridge provides a robust mechanism for integrating external, high-resolution physics models into GoldSim's dynamic simulation environment. The `rTemp` integration successfully resolves the temporal disaggregation challenge, enabling detailed, hourly thermal simulation while leveraging GoldSim’s established framework for state management and probabilistic analysis.
The complete integration package, including the Python adapter script and JSON configuration, is available in the rTemp package documentation.
No comments:
Post a Comment