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 | 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 primitives, and global data
``canopy_air_temperature``, ``canopy_air_humidity``, their per-layer counterparts,
``aerodynamic_resistance`` and ``canopy_airspace_iterations`` are reported.
- 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 371 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 574 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
-
- 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 216 of file EnergyBalance.py.
1.13.2