High-level interface for energy balance modeling and thermal calculations. More...

Detailed Description

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

Examples

>>> 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 62 of file EnergyBalance.py.

Public Member Functions
	__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.

	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	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.

Public Attributes
	context = context

	energy_model = None

Constructor & Destructor Documentation

◆ init()

pyhelios.EnergyBalance.EnergyBalanceModel.__init__	(		self,
		Context	context )

Initialize EnergyBalanceModel with graceful plugin handling.

Parameters

context Helios Context instance

Exceptions

TypeError	If context is not a Context instance
EnergyBalanceModelError	If energy balance plugin is not available

Definition at line 74 of file EnergyBalance.py.

Member Function Documentation

◆ enter()

pyhelios.EnergyBalance.EnergyBalanceModel.__enter__ ( self )

Context manager entry.

Definition at line 127 of file EnergyBalance.py.

◆ exit()

pyhelios.EnergyBalance.EnergyBalanceModel.__exit__	(	self,
		exc_type,
		exc_value,
		traceback )

Context manager exit with proper cleanup.

Definition at line 131 of file EnergyBalance.py.

◆ addRadiationBand()

None pyhelios.EnergyBalance.EnergyBalanceModel.addRadiationBand	(		self,
		Union[str, List[str]]	band )

Add a radiation band or bands for absorbed flux calculations.

   The energy balance model uses radiation bands from the RadiationModel
   plugin to calculate absorbed radiation flux for each primitive.

Parameters

band	Name of radiation band (e.g., "SW", "PAR", "NIR", "LW") or list of band names

Exceptions

ValueError	If band name is invalid
EnergyBalanceModelError	If operation fails

Examples

>>> energy_balance.addRadiationBand("SW") # Single band

>>> energy_balance.addRadiationBand(["SW", "LW", "PAR"]) # Multiple bands

Definition at line 241 of file EnergyBalance.py.

◆ disableMessages()

None pyhelios.EnergyBalance.EnergyBalanceModel.disableMessages ( self )

Disable console output messages from the energy balance model.

Exceptions

EnergyBalanceModelError If operation fails

Definition at line 163 of file EnergyBalance.py.

◆ enableAirEnergyBalance()

None pyhelios.EnergyBalance.EnergyBalanceModel.enableAirEnergyBalance	(		self,
		Optional[float]	canopy_height_m = None,
		Optional[float]	reference_height_m = None )

Enable air energy balance model for canopy-scale thermal calculations.

   The air energy balance computes average air temperature and water vapor
   mole fraction based on the energy balance of the air layer in the canopy.

Parameters

canopy_height_m	Optional canopy height in meters. If not provided, computed automatically from primitive bounding box.
reference_height_m	Optional reference height in meters where ambient conditions are measured. If not provided, assumes reference height is at canopy top.

Exceptions

ValueError	If parameters are invalid
EnergyBalanceModelError	If operation fails

Examples

>>> # Automatic canopy height detection
>>> energy_balance.enable_air_energy_balance()
 
>>> # Manual canopy and reference heights
>>> energy_balance.enable_air_energy_balance(canopy_height_m=5.0, reference_height_m=10.0)

Definition at line 289 of file EnergyBalance.py.

◆ enableMessages()

None pyhelios.EnergyBalance.EnergyBalanceModel.enableMessages ( self )

Enable console output messages from the energy balance model.

Exceptions

EnergyBalanceModelError If operation fails

Definition at line 151 of file EnergyBalance.py.

◆ evaluateAirEnergyBalance()

None pyhelios.EnergyBalance.EnergyBalanceModel.evaluateAirEnergyBalance	(		self,
		float	dt_sec,
		float	time_advance_sec,
		Optional[List[int]]	UUIDs = None )

Advance the air energy balance over time.

   This method advances the air energy balance model by integrating over
   multiple timesteps to reach the target time advancement.

Parameters

dt_sec	Timestep in seconds for integration
time_advance_sec	Total time to advance in seconds (must be >= dt_sec)
uuids	Optional list of primitive UUIDs. If None, processes all primitives.

Exceptions

ValueError	If parameters are invalid
EnergyBalanceModelError	If operation fails

Examples

>>> # Advance air energy balance by 1 hour using 60-second timesteps
>>> energy_balance.evaluate_air_energy_balance(dt_sec=60.0, time_advance_sec=3600.0)
 
>>> # Advance for specific primitives
>>> energy_balance.evaluate_air_energy_balance(
...     dt_sec=30.0, time_advance_sec=1800.0, uuids=[patch1_uuid, patch2_uuid])

Definition at line 334 of file EnergyBalance.py.

◆ getNativePtr()

pyhelios.EnergyBalance.EnergyBalanceModel.getNativePtr ( self )

Get the native pointer for advanced operations.

Definition at line 142 of file EnergyBalance.py.

◆ is_available()

bool pyhelios.EnergyBalance.EnergyBalanceModel.is_available ( self )

Check if EnergyBalanceModel is available in current build.

Returns: True if plugin is available, False otherwise

Definition at line 421 of file EnergyBalance.py.

◆ optionalOutputPrimitiveData()

None pyhelios.EnergyBalance.EnergyBalanceModel.optionalOutputPrimitiveData	(		self,
		str	label )

Add optional output primitive data to the Context.

   This method adds additional data fields to primitives that will be
   calculated and stored during energy balance execution.

Parameters

label Name of the data field to add (e.g., "vapor_pressure_deficit", "boundary_layer_conductance", "net_radiation")

Exceptions

ValueError	If label is invalid
EnergyBalanceModelError	If operation fails

Examples

>>> energy_balance.add_optional_output_data("vapor_pressure_deficit")

>>> energy_balance.add_optional_output_data("net_radiation")

Definition at line 372 of file EnergyBalance.py.

◆ printDefaultValueReport()

None pyhelios.EnergyBalance.EnergyBalanceModel.printDefaultValueReport	(		self,
		Optional[List[int]]	UUIDs = None )

Print a report detailing usage of default input values.

   This diagnostic method prints information about which primitives are
   using default values for energy balance parameters, helping identify
   where additional parameter specification might be needed.

Parameters

uuids Optional list of primitive UUIDs to report on. If None, reports on all primitives.

Exceptions

EnergyBalanceModelError If operation fails

Examples

>>> # Report on all primitives
>>> energy_balance.print_default_value_report()
 
>>> # Report on specific primitives
>>> energy_balance.print_default_value_report(uuids=[patch1_uuid, patch2_uuid])

Definition at line 405 of file EnergyBalance.py.

◆ run()

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

Examples

>>> # 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 202 of file EnergyBalance.py.

Member Data Documentation

◆ context

pyhelios.EnergyBalance.EnergyBalanceModel.context = context

Definition at line 79 of file EnergyBalance.py.

◆ energy_model

pyhelios.EnergyBalance.EnergyBalanceModel.energy_model = None

Definition at line 80 of file EnergyBalance.py.

The documentation for this class was generated from the following file:

pyhelios/EnergyBalance.py

Detailed Description

Public Member Functions

Public Attributes

Constructor & Destructor Documentation

◆ __init__()

Member Function Documentation

◆ __enter__()

◆ __exit__()

◆ addRadiationBand()

◆ disableMessages()

◆ enableAirEnergyBalance()

◆ enableMessages()

◆ evaluateAirEnergyBalance()

◆ getNativePtr()

◆ is_available()

◆ optionalOutputPrimitiveData()

◆ printDefaultValueReport()

◆ run()

Member Data Documentation

◆ context

◆ energy_model

◆ init()

◆ enter()

◆ exit()