High-level interface for stomatal conductance modeling and gas exchange calculations. More...

Detailed Description

High-level interface for stomatal conductance modeling and gas exchange calculations.

This class provides a user-friendly wrapper around the native Helios stomatal conductance plugin with automatic plugin availability checking and graceful error handling.

The stomatal conductance model implements five different stomatal response models:

BWB: Ball, Woodrow, Berry (1987) - original model
BBL: Ball, Berry, Leuning (1990, 1995) - includes VPD response
MOPT: Medlyn et al. (2011) - optimality-based model
BMF: Buckley, Mott, Farquhar - simplified mechanistic model
BB: Bailey - hydraulic-based model

The plugin includes a species library with pre-calibrated coefficients for common plant species (Almond, Apple, Avocado, Grape, Lemon, Olive, Walnut, etc.).

Both steady-state and dynamic (time-stepping) calculations are supported, with configurable time constants for stomatal opening and closing dynamics.

System requirements:

Cross-platform support (Windows, Linux, macOS)
No GPU required
No special dependencies
Stomatal conductance plugin compiled into PyHelios

Example: >>> with Context() as context: ... # Add leaf geometry ... leaf_uuid = context.addPatch(center=[0, 0, 1], size=[0.1, 0.1]) ... ... with StomatalConductanceModel(context) as stomatal: ... # Set model coefficients using species library ... stomatal.setBMFCoefficientsFromLibrary("Almond") ... ... # Run steady-state calculation ... stomatal.run() ... ... # Or run dynamic simulation with timestep ... stomatal.run(dt=60.0) # 60 second timestep ... ... # Set custom BMF coefficients for specific leaves ... bmf_coeffs = BMFCoefficients(Em=258.25, i0=38.65, k=232916.82, b=609.67) ... stomatal.setBMFCoefficients(bmf_coeffs, uuids=[leaf_uuid])

Definition at line 108 of file StomatalConductance.py.

Public Member Functions
	__init__ (self, Context context)
	Initialize StomatalConductanceModel 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 stomatal conductance model.

None	disableMessages (self)
	Disable console output messages from the stomatal conductance model.

None	run (self, Optional[List[int]] uuids=None, Optional[float] dt=None)
	Run the stomatal conductance model.

None	setBWBCoefficients (self, BWBCoefficients coeffs, Optional[List[int]] uuids=None, Optional[str] material_label=None)
	Set Ball-Woodrow-Berry model coefficients.

None	setBBLCoefficients (self, BBLCoefficients coeffs, Optional[List[int]] uuids=None, Optional[str] material_label=None)
	Set Ball-Berry-Leuning model coefficients.

None	setMOPTCoefficients (self, MOPTCoefficients coeffs, Optional[List[int]] uuids=None, Optional[str] material_label=None)
	Set Medlyn et al.

None	setBMFCoefficients (self, Union[BMFCoefficients, List[BMFCoefficients]] coeffs, Optional[List[int]] uuids=None, Optional[str] material_label=None)
	Set Buckley-Mott-Farquhar model coefficients.

None	setBBCoefficients (self, BBCoefficients coeffs, Optional[List[int]] uuids=None, Optional[str] material_label=None)
	Set Bailey model coefficients.

None	setBMFCoefficientsFromLibrary (self, str species, Optional[List[int]] uuids=None, Optional[str] material_label=None)
	Set BMF model coefficients using the built-in species library.

BMFCoefficients	getBMFCoefficientsFromLibrary (self, str species)
	Return the library BMF coefficients for a species without applying them.

None	setDynamicTimeConstants (self, float tau_open, float tau_close, Optional[List[int]] uuids=None)
	Set time constants for dynamic stomatal opening and closing.

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 StomatalConductanceModel is available in current build.

Public Attributes
	context = context

	stomatal_model = None

Protected Member Functions
	_check_context_alive (self)
	Raise if the owning Context has been destroyed (see Context.check_context_alive).

Static Protected Member Functions
None	_validate_target (str method, uuids, material_label)

None	_validate_bmf ("BMFCoefficients" coeffs)

Constructor & Destructor Documentation

◆ init()

pyhelios.StomatalConductance.StomatalConductanceModel.__init__	(		self,
		Context	context )

Initialize StomatalConductanceModel with graceful plugin handling.

Parameters

context Helios Context instance

Exceptions

TypeError	If context is not a Context instance
StomatalConductanceModelError	If stomatal conductance plugin is not available

Definition at line 120 of file StomatalConductance.py.

◆ del()

pyhelios.StomatalConductance.StomatalConductanceModel.__del__ ( self )

Destructor to ensure C++ resources freed even without 'with' statement.

Definition at line 201 of file StomatalConductance.py.

Member Function Documentation

◆ enter()

pyhelios.StomatalConductance.StomatalConductanceModel.__enter__ ( self )

Context manager entry.

Definition at line 186 of file StomatalConductance.py.

◆ exit()

pyhelios.StomatalConductance.StomatalConductanceModel.__exit__	(	self,
		exc_type,
		exc_value,
		traceback )

Context manager exit with proper cleanup.

Definition at line 190 of file StomatalConductance.py.

◆ _check_context_alive()

pyhelios.StomatalConductance.StomatalConductanceModel._check_context_alive ( self )

protected

Raise if the owning Context has been destroyed (see Context.check_context_alive).

Definition at line 182 of file StomatalConductance.py.

◆ _validate_bmf()

None pyhelios.StomatalConductance.StomatalConductanceModel._validate_bmf ( "BMFCoefficients" coeffs )

staticprotected

Definition at line 304 of file StomatalConductance.py.

◆ _validate_target()

None pyhelios.StomatalConductance.StomatalConductanceModel._validate_target	(	str	method,
			uuids,
			material_label )

staticprotected

Definition at line 291 of file StomatalConductance.py.

◆ disableMessages()

None pyhelios.StomatalConductance.StomatalConductanceModel.disableMessages ( self )

Disable console output messages from the stomatal conductance model.

Exceptions

StomatalConductanceModelError If operation fails

Definition at line 233 of file StomatalConductance.py.

◆ enableMessages()

None pyhelios.StomatalConductance.StomatalConductanceModel.enableMessages ( self )

Enable console output messages from the stomatal conductance model.

Exceptions

StomatalConductanceModelError If operation fails

Definition at line 220 of file StomatalConductance.py.

◆ getBMFCoefficientsFromLibrary()

BMFCoefficients pyhelios.StomatalConductance.StomatalConductanceModel.getBMFCoefficientsFromLibrary	(		self,
		str	species )

Return the library BMF coefficients for a species without applying them.

   The result can be modified and passed to :meth:`setBMFCoefficients`.

Parameters

species Species name from the library (e.g., "Almond", "Walnut"). An unrecognized name raises, and the error message lists the valid names.

Returns: BMFCoefficients for the species

Exceptions

ValueError	If species name is empty or not a str
StomatalConductanceModelError	If the species is not in the library, or the operation fails

Example: >>> almond = stomatal.getBMFCoefficientsFromLibrary("Almond") >>> stomatal.setBMFCoefficients(almond._replace(Em=almond.Em * 0.8), uuids=[leaf])

Definition at line 611 of file StomatalConductance.py.

◆ getNativePtr()

pyhelios.StomatalConductance.StomatalConductanceModel.getNativePtr ( self )

Get the native pointer for advanced operations.

Definition at line 211 of file StomatalConductance.py.

◆ is_available()

bool pyhelios.StomatalConductance.StomatalConductanceModel.is_available ( self )

Check if StomatalConductanceModel is available in current build.

Returns: True if plugin is available, False otherwise

Definition at line 720 of file StomatalConductance.py.

◆ optionalOutputPrimitiveData()

None pyhelios.StomatalConductance.StomatalConductanceModel.optionalOutputPrimitiveData	(		self,
		str	label )

Add optional output primitive data to the Context.

Parameters

label Name of primitive data to output (e.g., "Ci", "gs", "E")

Exceptions

ValueError	If label is invalid
StomatalConductanceModelError	If operation fails

Example: >>> # Output stomatal conductance values >>> stomatal.optionalOutputPrimitiveData("gs")

: >>> # Output intercellular CO2 concentration >>> stomatal.optionalOutputPrimitiveData("Ci")

Definition at line 678 of file StomatalConductance.py.

◆ printDefaultValueReport()

None pyhelios.StomatalConductance.StomatalConductanceModel.printDefaultValueReport	(		self,
		Optional[List[int]]	uuids = None )

Print a report detailing usage of default input values.

Parameters

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

Exceptions

StomatalConductanceModelError If operation fails

Example: >>> # Print report for all primitives >>> stomatal.printDefaultValueReport()

: >>> # Print report for specific leaves >>> stomatal.printDefaultValueReport(uuids=[leaf1_uuid, leaf2_uuid])

Definition at line 704 of file StomatalConductance.py.

◆ run()

None pyhelios.StomatalConductance.StomatalConductanceModel.run	(		self,
		Optional[List[int]]	uuids = None,
		Optional[float]	dt = None )

Run the stomatal conductance 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
StomatalConductanceModelError	If calculation fails

Example: >>> # Steady state for all primitives >>> stomatal.run()

: >>> # Dynamic simulation with 60-second timestep >>> stomatal.run(dt=60.0)

: >>> # Steady state for specific leaves >>> stomatal.run(uuids=[leaf1_uuid, leaf2_uuid])

: >>> # Dynamic simulation for specific leaves >>> stomatal.run(uuids=[leaf1_uuid, leaf2_uuid], dt=30.0)

Definition at line 270 of file StomatalConductance.py.

◆ setBBCoefficients()

None pyhelios.StomatalConductance.StomatalConductanceModel.setBBCoefficients	(		self,
		BBCoefficients	coeffs,
		Optional[List[int]]	uuids = None,
		Optional[str]	material_label = None )

Set Bailey model coefficients.

Parameters

coeffs	BB model coefficients (pi_0, pi_m, theta, sigma, chi)
uuids	Optional list of primitive UUIDs. If None and `material_label` is also None, applies to all primitives.
material_label	Optional Context material label; applies to every primitive that references the material at run() time. Mutually exclusive with `uuids`.

Exceptions

ValueError	If coefficients are invalid, or both ``uuids`` and ``material_label`` are given
StomatalConductanceModelError	If operation fails

Example: >>> bb_coeffs = BBCoefficients(pi_0=1.0, pi_m=1.67, theta=211.22, sigma=0.4408, chi=2.076) >>> stomatal.setBBCoefficients(bb_coeffs)

Definition at line 521 of file StomatalConductance.py.

◆ setBBLCoefficients()

None pyhelios.StomatalConductance.StomatalConductanceModel.setBBLCoefficients	(		self,
		BBLCoefficients	coeffs,
		Optional[List[int]]	uuids = None,
		Optional[str]	material_label = None )

Set Ball-Berry-Leuning model coefficients.

Parameters

coeffs	BBL model coefficients (gs0, a1, D0)
uuids	Optional list of primitive UUIDs. If None and `material_label` is also None, applies to all primitives.
material_label	Optional Context material label; applies to every primitive that references the material at run() time. Mutually exclusive with `uuids`.

Exceptions

ValueError	If coefficients are invalid, or both ``uuids`` and ``material_label`` are given
StomatalConductanceModelError	If operation fails

Example: >>> bbl_coeffs = BBLCoefficients(gs0=0.0743, a1=4.265, D0=14570.0) >>> stomatal.setBBLCoefficients(bbl_coeffs)

Definition at line 376 of file StomatalConductance.py.

◆ setBMFCoefficients()

None pyhelios.StomatalConductance.StomatalConductanceModel.setBMFCoefficients	(		self,
		Union[BMFCoefficients, List[BMFCoefficients]]	coeffs,
		Optional[List[int]]	uuids = None,
		Optional[str]	material_label = None )

Set Buckley-Mott-Farquhar model coefficients.

   ``coeffs`` may be a single :class:`BMFCoefficients` (applied to all primitives, to
   ``uuids``, or to ``material_label``), or a list of :class:`BMFCoefficients` with one
   entry per UUID in ``uuids`` (``coeffs[i]`` is applied to ``uuids[i]``).

Parameters

coeffs	BMF model coefficients (Em, i0, k, b), or a list of them (per-UUID form)
uuids	Optional list of primitive UUIDs. Required for the per-UUID list form. If None and `material_label` is also None, applies to all primitives.
material_label	Optional Context material label; applies to every primitive that references the material at run() time. Mutually exclusive with `uuids` and not accepted with the per-UUID list form.

Exceptions

ValueError	If coefficients are invalid, list and UUID lengths differ, or both `uuids` and `material_label` are given
StomatalConductanceModelError	If operation fails

Example: >>> bmf_coeffs = BMFCoefficients(Em=258.25, i0=38.65, k=232916.82, b=609.67) >>> stomatal.setBMFCoefficients(bmf_coeffs) >>> # One coefficient set per leaf >>> stomatal.setBMFCoefficients([coeffs_a, coeffs_b], uuids=[leaf_a, leaf_b])

Definition at line 466 of file StomatalConductance.py.

◆ setBMFCoefficientsFromLibrary()

None pyhelios.StomatalConductance.StomatalConductanceModel.setBMFCoefficientsFromLibrary	(		self,
		str	species,
		Optional[List[int]]	uuids = None,
		Optional[str]	material_label = None )

Set BMF model coefficients using the built-in species library.

Parameters

species	Species name from the library (e.g., "Almond", "Apple", "Grape", "Walnut"). An unrecognized name raises, and the error message lists the valid names.
uuids	Optional list of primitive UUIDs. If None and `material_label` is also None, applies to all primitives.
material_label	Optional Context material label; applies to every primitive that references the material at run() time. Mutually exclusive with `uuids`.

Exceptions

ValueError	If species name is not a non-empty str, or both ``uuids`` and ``material_label`` are given
StomatalConductanceModelError	If the species is not in the library, or the operation fails

Example: >>> # Set coefficients for almond tree >>> stomatal.setBMFCoefficientsFromLibrary("Almond")

: >>> # Set coefficients for specific leaves only >>> stomatal.setBMFCoefficientsFromLibrary("Grape", uuids=[leaf1_uuid, leaf2_uuid])

: >>> # Set coefficients for every primitive using a material >>> stomatal.setBMFCoefficientsFromLibrary("Walnut", material_label="walnut_leaf")

Definition at line 574 of file StomatalConductance.py.

◆ setBWBCoefficients()

None pyhelios.StomatalConductance.StomatalConductanceModel.setBWBCoefficients	(		self,
		BWBCoefficients	coeffs,
		Optional[List[int]]	uuids = None,
		Optional[str]	material_label = None )

Set Ball-Woodrow-Berry model coefficients.

Parameters

coeffs	BWB model coefficients (gs0, a1)
uuids	Optional list of primitive UUIDs. If None and `material_label` is also None, applies to all primitives.
material_label	Optional Context material label. The coefficients are stored on the material and apply to every primitive that references it when run() is called. Mutually exclusive with `uuids`. See "Coefficient precedence" in the Stomatal Conductance plugin documentation.

Exceptions

ValueError	If coefficients are invalid, or both ``uuids`` and ``material_label`` are given
StomatalConductanceModelError	If operation fails (e.g. the material does not exist)

Example: >>> bwb_coeffs = BWBCoefficients(gs0=0.0733, a1=9.422) >>> stomatal.setBWBCoefficients(bwb_coeffs) >>> stomatal.setBWBCoefficients(bwb_coeffs, material_label="sun_leaf")

Definition at line 336 of file StomatalConductance.py.

◆ setDynamicTimeConstants()

None pyhelios.StomatalConductance.StomatalConductanceModel.setDynamicTimeConstants	(		self,
		float	tau_open,
		float	tau_close,
		Optional[List[int]]	uuids = None )

Set time constants for dynamic stomatal opening and closing.

Parameters

tau_open	Time constant (seconds) for stomatal opening
tau_close	Time constant (seconds) for stomatal closing
uuids	Optional list of primitive UUIDs. If None, applies to all primitives.

Exceptions

ValueError	If time constants are invalid
StomatalConductanceModelError	If operation fails

Example: >>> # Set time constants for all leaves >>> stomatal.setDynamicTimeConstants(tau_open=120.0, tau_close=240.0)

: >>> # Set different time constants for specific leaves >>> stomatal.setDynamicTimeConstants(tau_open=60.0, tau_close=180.0, uuids=[leaf1_uuid])

Definition at line 641 of file StomatalConductance.py.

◆ setMOPTCoefficients()

None pyhelios.StomatalConductance.StomatalConductanceModel.setMOPTCoefficients	(		self,
		MOPTCoefficients	coeffs,
		Optional[List[int]]	uuids = None,
		Optional[str]	material_label = None )

Set Medlyn et al.

optimality model coefficients.

Parameters

coeffs	MOPT model coefficients (gs0, g1)
uuids	Optional list of primitive UUIDs. If None and `material_label` is also None, applies to all primitives.
material_label	Optional Context material label; applies to every primitive that references the material at run() time. Mutually exclusive with `uuids`.

Exceptions

ValueError	If coefficients are invalid, or both ``uuids`` and ``material_label`` are given
StomatalConductanceModelError	If operation fails

Example: >>> mopt_coeffs = MOPTCoefficients(gs0=0.0825, g1=2.637) >>> stomatal.setMOPTCoefficients(mopt_coeffs)

Definition at line 418 of file StomatalConductance.py.

Member Data Documentation

◆ context

pyhelios.StomatalConductance.StomatalConductanceModel.context = context

Definition at line 127 of file StomatalConductance.py.

◆ stomatal_model

pyhelios.StomatalConductance.StomatalConductanceModel.stomatal_model = None

Definition at line 128 of file StomatalConductance.py.

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

pyhelios/StomatalConductance.py

Detailed Description

Public Member Functions

Public Attributes

Protected Member Functions

Static Protected Member Functions

Constructor & Destructor Documentation

◆ __init__()

◆ __del__()

Member Function Documentation

◆ __enter__()

◆ __exit__()

◆ _check_context_alive()

◆ _validate_bmf()

◆ _validate_target()

◆ disableMessages()

◆ enableMessages()

◆ getBMFCoefficientsFromLibrary()

◆ getNativePtr()

◆ is_available()

◆ optionalOutputPrimitiveData()

◆ printDefaultValueReport()

◆ run()

◆ setBBCoefficients()

◆ setBBLCoefficients()

◆ setBMFCoefficients()

◆ setBMFCoefficientsFromLibrary()

◆ setBWBCoefficients()

◆ setDynamicTimeConstants()

◆ setMOPTCoefficients()

Member Data Documentation

◆ context

◆ stomatal_model

◆ init()

◆ del()

◆ enter()

◆ exit()