High-level interface for energy balance modeling and thermal calculations.
This class provides a user-friendly wrapper around the native Helios energy balance plugin with automatic plugin availability checking and graceful error handling.
The energy balance model computes surface temperatures based on local energy balance equations, including radiation absorption, convection, and transpiration. It supports both steady-state and dynamic (time-stepping) calculations.
System requirements:
- NVIDIA GPU with CUDA support
- CUDA Toolkit installed
- Energy balance plugin compiled into PyHelios
- Example
- >>> with Context() as context: ... # Add some geometry ... patch_uuid = context.addPatch(center=[0, 0, 1], size=[1, 1]) ... ... with EnergyBalanceModel(context) as energy_balance: ... # Add radiation band for flux calculations ... energy_balance.addRadiationBand("SW") ... ... # Run steady-state energy balance ... energy_balance.run() ... ... # Or run dynamic simulation with timestep ... energy_balance.run(dt=60.0) # 60 second timestep
Definition at line 60 of file EnergyBalance.py.
|
| | __init__ (self, Context context) |
| | Initialize EnergyBalanceModel with graceful plugin handling.
|
| |
| | __enter__ (self) |
| | Context manager entry.
|
| |
| | __exit__ (self, exc_type, exc_value, traceback) |
| | Context manager exit with proper cleanup.
|
| |
| | __del__ (self) |
| | Destructor to ensure C++ resources freed even without 'with' statement.
|
| |
| | getNativePtr (self) |
| | Get the native pointer for advanced operations.
|
| |
| None | enableMessages (self) |
| | Enable console output messages from the energy balance model.
|
| |
| None | disableMessages (self) |
| | Disable console output messages from the energy balance model.
|
| |
| None | run (self, Optional[List[int]] uuids=None, Optional[float] dt=None) |
| | Run the energy balance model.
|
| |
| None | addRadiationBand (self, Union[str, List[str]] band) |
| | Add a radiation band or bands for absorbed flux calculations.
|
| |
| None | enableAirEnergyBalance (self, Optional[float] canopy_height_m=None, Optional[float] reference_height_m=None) |
| | Enable air energy balance model for canopy-scale thermal calculations.
|
| |
| None | enableCanopyAirspaceModel (self, List[int] canopy_UUIDs, float canopy_height_m, float reference_height_m, float leaf_area_index, int num_layers=1, Optional[List[int]] ground_UUIDs=None) |
| | Enable the canopy airspace model.
|
| |
| None | disableCanopyAirspaceModel (self) |
| | Disable the canopy airspace model.
|
| |
| None | enableCanopyAirspaceStabilityCorrection (self) |
| | Enable Monin-Obukhov stability corrections in the canopy airspace model (the default).
|
| |
| None | disableCanopyAirspaceStabilityCorrection (self) |
| | Disable Monin-Obukhov stability corrections in the canopy airspace model.
|
| |
| None | setCanopyAirspaceConvergence (self, float tolerance_K=0.01, int max_iterations=50) |
| | Set convergence criteria for the canopy airspace iteration.
|
| |
| None | evaluateAirEnergyBalance (self, float dt_sec, float time_advance_sec, Optional[List[int]] UUIDs=None) |
| | Advance the air energy balance over time.
|
| |
| None | optionalOutputPrimitiveData (self, str label) |
| | Add optional output primitive data to the Context.
|
| |
| None | printDefaultValueReport (self, Optional[List[int]] UUIDs=None) |
| | Print a report detailing usage of default input values.
|
| |
| bool | is_available (self) |
| | Check if EnergyBalanceModel is available in current build.
|
| |
| None | enableGPUAcceleration (self) |
| | Enable GPU acceleration for energy balance calculations.
|
| |
| None | disableGPUAcceleration (self) |
| | Disable GPU acceleration and force CPU mode.
|
| |
| bool | isGPUAccelerationEnabled (self) |
| | Check if GPU acceleration is currently enabled.
|
| |
| None pyhelios.EnergyBalance.EnergyBalanceModel.enableCanopyAirspaceModel |
( |
| self, |
|
|
List[int] | canopy_UUIDs, |
|
|
float | canopy_height_m, |
|
|
float | reference_height_m, |
|
|
float | leaf_area_index, |
|
|
int | num_layers = 1, |
|
|
Optional[List[int]] | ground_UUIDs = None ) |
Enable the canopy airspace model.
Resolves the within-canopy air temperature and humidity surrounding leaves from a
vertically layered resistance network, instead of holding them at a prescribed
value, so the canopy feeds back on the air driving its own transpiration. The
airspace is divided into vertical layers of equal leaf area index, each exchanging
sensible heat and water vapor with its leaves, its neighboring layers and -- for
the outermost layers -- the soil surface and the above-canopy reference air.
Unlike :meth:`enableAirEnergyBalance`, which evolves a prognostic boundary layer
and thereby assumes a horizontally infinite canopy, this model suits canopies of
limited extent subject to advection, such as an orchard block. The two determine
the same air state and **may not both be enabled**.
Because it solves for a steady state, it cannot be combined with the form of
:meth:`run` that takes a timestep.
The above-canopy boundary condition is read from global data
``air_temperature_reference``, ``air_humidity_reference`` and
``wind_speed_reference`` when present, otherwise from this model's defaults. Set
them with :meth:`Context.setGlobalData` before calling :meth:`run`.
After :meth:`run`, primitive data ``air_temperature``, ``air_humidity`` and
``wind_speed`` are set on the canopy and ground primitives, and global data
``canopy_air_temperature``, ``canopy_air_humidity``, their per-layer counterparts,
``aerodynamic_resistance``, ``canopy_airspace_iterations``, ``friction_velocity`` and
``canopy_stability_parameter`` are reported.
Turbulent transport above and at the top of the canopy is corrected for atmospheric
stability (Monin-Obukhov) by default: exchange is enhanced over a canopy warmer than
the reference air and suppressed over one cooler than it. Use
:meth:`disableCanopyAirspaceStabilityCorrection` to assume neutral stability.
The soil exchanges sensible heat and water vapor with the lowest layer through the
same boundary-layer and moisture conductances its own surface energy balance uses,
so the heat and water released by the soil are exactly what the airspace receives.
Ground primitives without ``boundarylayer_conductance`` primitive data use the
bare-soil conductance of Kustas and Norman (1999) rather than the flat-plate
relation used for other primitives; a value set by the user or by the
boundary-layer conductance plug-in takes precedence. Soil evaporation is governed
by the ``moisture_conductance`` (zero by default, i.e. a dry soil) and
``surface_humidity`` primitive data of the ground primitives. Soil fluxes are
averaged over the area of the ground primitives, which are taken to represent the
soil surface beneath the whole canopy footprint.
- Parameters
-
| canopy_UUIDs | Canopy (leaf) primitives exchanging heat and moisture with the airspace. |
| canopy_height_m | Height of the canopy in meters. |
| reference_height_m | Height at which above-canopy conditions are measured, in meters. Must be greater than canopy_height_m. |
| leaf_area_index | One-sided leaf area index on a ground-area basis. |
| num_layers | Number of vertical layers of equal leaf area index. 1 gives a single within-canopy node. |
| ground_UUIDs | Ground primitives forming the soil node beneath the canopy. When omitted there is no exchange with the soil surface. |
- Exceptions
-
- Example
- >>> energy_balance.enableCanopyAirspaceModel( ... canopy_UUIDs=leaf_uuids, canopy_height_m=3.0, reference_height_m=5.0, ... leaf_area_index=2.5, num_layers=5, ground_UUIDs=ground_uuids) >>> energy_balance.run()
Definition at line 394 of file EnergyBalance.py.
| None pyhelios.EnergyBalance.EnergyBalanceModel.enableCanopyAirspaceStabilityCorrection |
( |
| self | ) |
|
Enable Monin-Obukhov stability corrections in the canopy airspace model (the default).
The aerodynamic resistance between the canopy top and the reference height, and the
eddy diffusivity at the canopy top, are corrected for atmospheric stability using the
Obukhov length implied by the sensible and latent heat fluxes leaving the canopy.
Unstable conditions (canopy warmer than the reference air, typically daytime) enhance
turbulent exchange, and stable conditions (night) suppress it. The model reports the
resulting global data ``friction_velocity`` (m/s) and ``canopy_stability_parameter``.
- Exceptions
-
| NotImplementedError | If the native library predates helios-core v1.3.93. |
| EnergyBalanceModelError | If the operation fails. |
Definition at line 449 of file EnergyBalance.py.
| None pyhelios.EnergyBalance.EnergyBalanceModel.enableGPUAcceleration |
( |
| self | ) |
|
Enable GPU acceleration for energy balance calculations.
Attempts to enable GPU acceleration using CUDA. If GPU is not available at runtime,
this will raise an error. The energy balance model will use three-tier execution:
GPU (CUDA), OpenMP (parallel CPU), or serial CPU fallback.
- Exceptions
-
| NotImplementedError | If library not compiled with CUDA support |
| EnergyBalanceModelError | If GPU acceleration cannot be enabled |
- Example
- >>> with EnergyBalanceModel(context) as energy_balance: ... try: ... energy_balance.enableGPUAcceleration() ... print("GPU acceleration enabled") ... except NotImplementedError: ... print("GPU not available - using CPU mode")
- Note
- Only available when PyHelios is compiled with CUDA support. OpenMP CPU mode is recommended for most workloads without GPU.
Definition at line 640 of file EnergyBalance.py.
| None pyhelios.EnergyBalance.EnergyBalanceModel.run |
( |
| self, |
|
|
Optional[List[int]] | uuids = None, |
|
|
Optional[float] | dt = None ) |
Run the energy balance model.
This method supports multiple execution modes:
- Steady state for all primitives: run()
- Dynamic with timestep for all primitives: run(dt=60.0)
- Steady state for specific primitives: run(uuids=[1, 2, 3])
- Dynamic with timestep for specific primitives: run(uuids=[1, 2, 3], dt=60.0)
- Parameters
-
| uuids | Optional list of primitive UUIDs to process. If None, processes all primitives. |
| dt | Optional timestep in seconds for dynamic simulation. If None, runs steady-state. |
- Exceptions
-
| ValueError | If parameters are invalid |
| EnergyBalanceModelError | If energy balance calculation fails, if a UUID does not exist, or if the same UUID appears more than once in uuids (helios-core 1.3.92+), or if the emitting radiation bands do not account for the blackbody spectrum exactly once – overlapping bounded bands, bands holding less than 95% of the emission, or more than one emitting band without wavelength bounds (helios-core 1.3.93+) |
- Example
- >>> # Steady state for all primitives >>> energy_balance.run()
- >>> # Dynamic simulation with 60-second timestep >>> energy_balance.run(dt=60.0)
- >>> # Steady state for specific patches >>> energy_balance.run(uuids=[patch1_uuid, patch2_uuid])
- >>> # Dynamic simulation for specific patches >>> energy_balance.run(uuids=[patch1_uuid, patch2_uuid], dt=30.0)
Definition at line 221 of file EnergyBalance.py.
1.13.2