High-level interface for Helios photosynthesis modeling. More...

Detailed Description

High-level interface for Helios photosynthesis modeling.

The PhotosynthesisModel provides methods for configuring and running photosynthesis simulations using various models including empirical and mechanistic (Farquhar-von Caemmerer-Berry) approaches.

Features

Support for empirical and FvCB photosynthesis models
Built-in species library with 21+ plant species
Comprehensive parameter validation
Context manager support for proper cleanup

Examples

>>> from pyhelios import Context, PhotosynthesisModel
>>> from pyhelios.types import EmpiricalModelCoefficients
>>> context = Context()
>>> with PhotosynthesisModel(context) as photosynthesis:
...     # Configure empirical model
...     coeffs = EmpiricalModelCoefficients(
...         Tref=298.0,      # Reference temperature (K)
...         Ci_ref=290.0,    # Reference CO2 concentration (μmol/mol)
...         Asat=20.0,       # Light-saturated photosynthesis rate (μmol/m²/s)
...         theta=65.0       # Light response curvature (W/m²)
...     )
...     photosynthesis.setEmpiricalModelCoefficients(coeffs)
...     photosynthesis.run()

Available species can be queried using:

>>> PhotosynthesisModel.get_available_species()

['ALMOND', 'APPLE', 'AVOCADO', ...]

Definition at line 70 of file PhotosynthesisModel.py.

Public Member Functions
	__init__ (self, Context context)
	Initialize PhotosynthesisModel.

	__enter__ (self)
	Context manager entry.

	__exit__ (self, exc_type, exc_value, traceback)
	Context manager exit with cleanup.

	cleanup (self)
	Clean up native resources.

	get_native_ptr (self)
	Get the native C++ pointer for advanced operations.

	__del__ (self)
	Destructor to ensure cleanup.

	setModelTypeEmpirical (self)
	Set the photosynthesis model type to empirical.

	setModelTypeFarquhar (self)
	Set the photosynthesis model type to Farquhar-von Caemmerer-Berry.

	run (self)
	Run photosynthesis calculations for all primitives in the context.

	runForPrimitives (self, Union[List[int], int] uuids)
	Run photosynthesis calculations for specific primitives.

	setSpeciesCoefficients (self, str species, Optional[List[int]] uuids=None)
	Set Farquhar model coefficients from built-in species library.

	setFarquharCoefficientsFromLibrary (self, str species, Optional[List[int]] uuids=None)
	Set Farquhar model coefficients from built-in species library.

List[float]	getSpeciesCoefficients (self, str species)
	Get Farquhar model coefficients for a species from the library.

	setEmpiricalModelCoefficients (self, EmpiricalModelCoefficients coefficients, Optional[List[int]] uuids=None)
	Set empirical model coefficients.

	setFarquharModelCoefficients (self, FarquharModelCoefficients coefficients, Optional[List[int]] uuids=None)
	Set Farquhar model coefficients.

	setVcmax (self, float vcmax, List[int] uuids, Optional[float] dha=None, Optional[float] topt=None, Optional[float] dhd=None)
	Set maximum carboxylation rate for Farquhar model.

	setJmax (self, float jmax, List[int] uuids, Optional[float] dha=None, Optional[float] topt=None, Optional[float] dhd=None)
	Set maximum electron transport rate for Farquhar model.

	setDarkRespiration (self, float respiration, List[int] uuids, Optional[float] dha=None, Optional[float] topt=None, Optional[float] dhd=None)
	Set dark respiration rate.

	setQuantumEfficiency (self, float efficiency, List[int] uuids, Optional[float] dha=None, Optional[float] topt=None, Optional[float] dhd=None)
	Set quantum efficiency of photosystem II.

	setLightResponseCurvature (self, float curvature, List[int] uuids, Optional[float] dha=None, Optional[float] topt=None, Optional[float] dhd=None)
	Set light response curvature parameter.

List[float]	getEmpiricalModelCoefficients (self, int uuid)
	Get empirical model coefficients for a specific primitive.

List[float]	getFarquharModelCoefficients (self, int uuid)
	Get Farquhar model coefficients for a specific primitive.

	exportResults (self, str label)
	Export photosynthesis results with optional label.

	enableMessages (self)
	Enable photosynthesis model status messages.

	disableMessages (self)
	Disable photosynthesis model status messages.

	printModelReport (self, Optional[List[int]] uuids=None)
	Print model configuration report.

bool	validateConfiguration (self)
	Basic validation that model has been configured.

	resetModel (self)
	Reset the model by recreating it.

Static Public Member Functions
List[str]	get_available_species ()
	Static method to get available species without creating a model instance.

dict	get_species_aliases ()
	Static method to get species aliases mapping.

Public Attributes
	context = context

Protected Attributes
	_native_ptr = None

Constructor & Destructor Documentation

◆ init()

pyhelios.PhotosynthesisModel.PhotosynthesisModel.__init__	(		self,
		Context	context )

Initialize PhotosynthesisModel.

Parameters

context PyHelios Context instance containing the 3D geometry

Exceptions

PhotosynthesisModelError If plugin is not available or initialization fails

Definition at line 81 of file PhotosynthesisModel.py.

◆ del()

pyhelios.PhotosynthesisModel.PhotosynthesisModel.__del__ ( self )

Destructor to ensure cleanup.

Definition at line 140 of file PhotosynthesisModel.py.

Member Function Documentation

◆ enter()

pyhelios.PhotosynthesisModel.PhotosynthesisModel.__enter__ ( self )

Context manager entry.

Definition at line 118 of file PhotosynthesisModel.py.

◆ exit()

pyhelios.PhotosynthesisModel.PhotosynthesisModel.__exit__	(	self,
		exc_type,
		exc_value,
		traceback )

Context manager exit with cleanup.

Definition at line 122 of file PhotosynthesisModel.py.

◆ cleanup()

pyhelios.PhotosynthesisModel.PhotosynthesisModel.cleanup ( self )

Clean up native resources.

Definition at line 126 of file PhotosynthesisModel.py.

◆ disableMessages()

pyhelios.PhotosynthesisModel.PhotosynthesisModel.disableMessages ( self )

Disable photosynthesis model status messages.

Definition at line 542 of file PhotosynthesisModel.py.

◆ enableMessages()

pyhelios.PhotosynthesisModel.PhotosynthesisModel.enableMessages ( self )

Enable photosynthesis model status messages.

Definition at line 538 of file PhotosynthesisModel.py.

◆ exportResults()

pyhelios.PhotosynthesisModel.PhotosynthesisModel.exportResults	(		self,
		str	label )

Export photosynthesis results with optional label.

Parameters

label Data label for export

Definition at line 533 of file PhotosynthesisModel.py.

◆ get_available_species()

List[str] pyhelios.PhotosynthesisModel.PhotosynthesisModel.get_available_species ( )

static

Static method to get available species without creating a model instance.

Returns: List of species names available in the photosynthesis library

Definition at line 244 of file PhotosynthesisModel.py.

◆ get_native_ptr()

pyhelios.PhotosynthesisModel.PhotosynthesisModel.get_native_ptr ( self )

Get the native C++ pointer for advanced operations.

Definition at line 136 of file PhotosynthesisModel.py.

◆ get_species_aliases()

dict pyhelios.PhotosynthesisModel.PhotosynthesisModel.get_species_aliases ( )

static

Static method to get species aliases mapping.

Returns: Dictionary mapping aliases to canonical species names

Definition at line 254 of file PhotosynthesisModel.py.

◆ getEmpiricalModelCoefficients()

List[float] pyhelios.PhotosynthesisModel.PhotosynthesisModel.getEmpiricalModelCoefficients	(		self,
		int	uuid )

Get empirical model coefficients for a specific primitive.

Parameters

uuid	Primitive UUID

Returns: List of empirical model coefficients

Definition at line 512 of file PhotosynthesisModel.py.

◆ getFarquharModelCoefficients()

List[float] pyhelios.PhotosynthesisModel.PhotosynthesisModel.getFarquharModelCoefficients	(		self,
		int	uuid )

Get Farquhar model coefficients for a specific primitive.

Parameters

uuid	Primitive UUID

Returns: List of Farquhar model coefficients

Definition at line 524 of file PhotosynthesisModel.py.

◆ getSpeciesCoefficients()

List[float] pyhelios.PhotosynthesisModel.PhotosynthesisModel.getSpeciesCoefficients	(		self,
		str	species )

Get Farquhar model coefficients for a species from the library.

Parameters

species Species name

Returns: List of Farquhar model coefficients for the species

Definition at line 233 of file PhotosynthesisModel.py.

◆ printModelReport()

pyhelios.PhotosynthesisModel.PhotosynthesisModel.printModelReport	(		self,
		Optional[List[int]]	uuids = None )

Print model configuration report.

Parameters

uuids Optional list of UUIDs. If None, prints report for all primitives.

Definition at line 551 of file PhotosynthesisModel.py.

◆ resetModel()

pyhelios.PhotosynthesisModel.PhotosynthesisModel.resetModel ( self )

Reset the model by recreating it.

Note: This will clear all configured parameters.

Definition at line 571 of file PhotosynthesisModel.py.

◆ run()

pyhelios.PhotosynthesisModel.PhotosynthesisModel.run ( self )

Run photosynthesis calculations for all primitives in the context.

   The model must be configured with appropriate coefficients before running.

Definition at line 167 of file PhotosynthesisModel.py.

◆ runForPrimitives()

pyhelios.PhotosynthesisModel.PhotosynthesisModel.runForPrimitives	(		self,
		Union[List[int], int]	uuids )

Run photosynthesis calculations for specific primitives.

Parameters

uuids Single UUID (integer) or list of UUIDs for primitives

Definition at line 177 of file PhotosynthesisModel.py.

◆ setDarkRespiration()

pyhelios.PhotosynthesisModel.PhotosynthesisModel.setDarkRespiration	(		self,
		float	respiration,
		List[int]	uuids,
		Optional[float]	dha = None,
		Optional[float]	topt = None,
		Optional[float]	dhd = None )

Set dark respiration rate.

   This method modifies only the Rd parameter while preserving all
   other existing Farquhar model parameters for each primitive.

Parameters

respiration	Dark respiration rate at 25°C (μmol m⁻² s⁻¹)
uuids	List of primitive UUIDs to modify (required)
dha	Activation energy (optional, kJ/mol)
topt	Optimal temperature (optional, °C)
dhd	Deactivation energy (optional, kJ/mol)

Note: Primitives must have existing Farquhar model coefficients set before calling this method. Use setFarquharCoefficientsFromLibrary() first if needed. To modify all primitives, use setFarquharModelCoefficients() with complete coefficient objects.

Definition at line 404 of file PhotosynthesisModel.py.

◆ setEmpiricalModelCoefficients()

pyhelios.PhotosynthesisModel.PhotosynthesisModel.setEmpiricalModelCoefficients	(		self,
		EmpiricalModelCoefficients	coefficients,
		Optional[List[int]]	uuids = None )

Set empirical model coefficients.

Parameters

coefficients	EmpiricalModelCoefficients instance with model parameters
uuids	Optional list of primitive UUIDs. If None, applies to all primitives.

Definition at line 266 of file PhotosynthesisModel.py.

◆ setFarquharCoefficientsFromLibrary()

pyhelios.PhotosynthesisModel.PhotosynthesisModel.setFarquharCoefficientsFromLibrary	(		self,
		str	species,
		Optional[List[int]]	uuids = None )

Set Farquhar model coefficients from built-in species library.

   This method matches the C++ API naming: setFarquharCoefficientsFromLibrary()

Parameters

species	Species name from the built-in library
uuids	Optional list of primitive UUIDs. If None, applies to all primitives.

Examples

>>> model.setFarquharCoefficientsFromLibrary("APPLE")

>>> model.setFarquharCoefficientsFromLibrary("SOYBEAN", [uuid1, uuid2])

Definition at line 218 of file PhotosynthesisModel.py.

◆ setFarquharModelCoefficients()

pyhelios.PhotosynthesisModel.PhotosynthesisModel.setFarquharModelCoefficients	(		self,
		FarquharModelCoefficients	coefficients,
		Optional[List[int]]	uuids = None )

Set Farquhar model coefficients.

Parameters

coefficients	FarquharModelCoefficients instance with FvCB parameters
uuids	Optional list of primitive UUIDs. If None, applies to all primitives.

Definition at line 284 of file PhotosynthesisModel.py.

◆ setJmax()

pyhelios.PhotosynthesisModel.PhotosynthesisModel.setJmax	(		self,
		float	jmax,
		List[int]	uuids,
		Optional[float]	dha = None,
		Optional[float]	topt = None,
		Optional[float]	dhd = None )

Set maximum electron transport rate for Farquhar model.

   This method modifies only the Jmax parameter while preserving all
   other existing Farquhar model parameters for each primitive.

Parameters

jmax	Maximum electron transport rate at 25°C (μmol m⁻² s⁻¹)
uuids	List of primitive UUIDs to modify (required)
dha	Activation energy (optional, kJ/mol)
topt	Optimal temperature (optional, °C)
dhd	Deactivation energy (optional, kJ/mol)

Note: Primitives must have existing Farquhar model coefficients set before calling this method. Use setFarquharCoefficientsFromLibrary() first if needed. To modify all primitives, use setFarquharModelCoefficients() with complete coefficient objects.

Definition at line 367 of file PhotosynthesisModel.py.

◆ setLightResponseCurvature()

pyhelios.PhotosynthesisModel.PhotosynthesisModel.setLightResponseCurvature	(		self,
		float	curvature,
		List[int]	uuids,
		Optional[float]	dha = None,
		Optional[float]	topt = None,
		Optional[float]	dhd = None )

Set light response curvature parameter.

   This method modifies only the theta parameter while preserving all
   other existing Farquhar model parameters for each primitive.

Parameters

curvature	Light response curvature at 25°C (dimensionless)
uuids	List of primitive UUIDs to modify (required)
dha	Activation energy (optional, kJ/mol)
topt	Optimal temperature (optional, °C)
dhd	Deactivation energy (optional, kJ/mol)

Note: Primitives must have existing Farquhar model coefficients set before calling this method. Use setFarquharCoefficientsFromLibrary() first if needed. To modify all primitives, use setFarquharModelCoefficients() with complete coefficient objects.; The theta parameter is stored in the coefficient array but may not be directly exposed in the current FarquharModelCoefficients structure. This method sets the basic curvature value.

Definition at line 483 of file PhotosynthesisModel.py.

◆ setModelTypeEmpirical()

pyhelios.PhotosynthesisModel.PhotosynthesisModel.setModelTypeEmpirical ( self )

Set the photosynthesis model type to empirical.

   The empirical model uses light response curves with saturation kinetics.

Definition at line 149 of file PhotosynthesisModel.py.

◆ setModelTypeFarquhar()

pyhelios.PhotosynthesisModel.PhotosynthesisModel.setModelTypeFarquhar ( self )

Set the photosynthesis model type to Farquhar-von Caemmerer-Berry.

   The FvCB model is a mechanistic model accounting for biochemical
   limitations of C3 photosynthesis.

Definition at line 158 of file PhotosynthesisModel.py.

◆ setQuantumEfficiency()

pyhelios.PhotosynthesisModel.PhotosynthesisModel.setQuantumEfficiency	(		self,
		float	efficiency,
		List[int]	uuids,
		Optional[float]	dha = None,
		Optional[float]	topt = None,
		Optional[float]	dhd = None )

Set quantum efficiency of photosystem II.

   This method modifies only the alpha parameter while preserving all
   other existing Farquhar model parameters for each primitive.

Parameters

efficiency	Quantum efficiency at 25°C (dimensionless, 0-1)
uuids	List of primitive UUIDs to modify (required)
dha	Activation energy (optional, kJ/mol)
topt	Optimal temperature (optional, °C)
dhd	Deactivation energy (optional, kJ/mol)

Note: Primitives must have existing Farquhar model coefficients set before calling this method. Use setFarquharCoefficientsFromLibrary() first if needed. To modify all primitives, use setFarquharModelCoefficients() with complete coefficient objects.

Definition at line 441 of file PhotosynthesisModel.py.

◆ setSpeciesCoefficients()

pyhelios.PhotosynthesisModel.PhotosynthesisModel.setSpeciesCoefficients	(		self,
		str	species,
		Optional[List[int]]	uuids = None )

Set Farquhar model coefficients from built-in species library.

Parameters

species	Species name from the built-in library
uuids	Optional list of primitive UUIDs. If None, applies to all primitives.

Examples

>>> model.setSpeciesCoefficients("APPLE")

>>> model.setSpeciesCoefficients("SOYBEAN", [uuid1, uuid2])

Definition at line 197 of file PhotosynthesisModel.py.

◆ setVcmax()

pyhelios.PhotosynthesisModel.PhotosynthesisModel.setVcmax	(		self,
		float	vcmax,
		List[int]	uuids,
		Optional[float]	dha = None,
		Optional[float]	topt = None,
		Optional[float]	dhd = None )

Set maximum carboxylation rate for Farquhar model.

   This method modifies only the Vcmax parameter while preserving all
   other existing Farquhar model parameters for each primitive.

Parameters

vcmax	Maximum carboxylation rate at 25°C (μmol m⁻² s⁻¹)
uuids	List of primitive UUIDs to modify (required)
dha	Activation energy (optional, kJ/mol)
topt	Optimal temperature (optional, °C)
dhd	Deactivation energy (optional, kJ/mol)

Note: Primitives must have existing Farquhar model coefficients set before calling this method. Use setFarquharCoefficientsFromLibrary() first if needed. To modify all primitives, use setFarquharModelCoefficients() with complete coefficient objects.

Definition at line 314 of file PhotosynthesisModel.py.

◆ validateConfiguration()

bool pyhelios.PhotosynthesisModel.PhotosynthesisModel.validateConfiguration ( self )

Basic validation that model has been configured.

Returns: True if model appears to be configured (has native pointer)

Definition at line 564 of file PhotosynthesisModel.py.

Member Data Documentation

◆ _native_ptr

pyhelios.PhotosynthesisModel.PhotosynthesisModel._native_ptr = None

protected

Definition at line 88 of file PhotosynthesisModel.py.

◆ context

pyhelios.PhotosynthesisModel.PhotosynthesisModel.context = context

Definition at line 87 of file PhotosynthesisModel.py.

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

pyhelios/PhotosynthesisModel.py

Detailed Description

Public Member Functions

Static Public Member Functions

Public Attributes

Protected Attributes

Constructor & Destructor Documentation

◆ __init__()

◆ __del__()

Member Function Documentation

◆ __enter__()

◆ __exit__()

◆ cleanup()

◆ disableMessages()

◆ enableMessages()

◆ exportResults()

◆ get_available_species()

◆ get_native_ptr()

◆ get_species_aliases()

◆ getEmpiricalModelCoefficients()

◆ getFarquharModelCoefficients()

◆ getSpeciesCoefficients()

◆ printModelReport()

◆ resetModel()

◆ run()

◆ runForPrimitives()

◆ setDarkRespiration()

◆ setEmpiricalModelCoefficients()

◆ setFarquharCoefficientsFromLibrary()

◆ setFarquharModelCoefficients()

◆ setJmax()

◆ setLightResponseCurvature()

◆ setModelTypeEmpirical()

◆ setModelTypeFarquhar()

◆ setQuantumEfficiency()

◆ setSpeciesCoefficients()

◆ setVcmax()

◆ validateConfiguration()

Member Data Documentation

◆ _native_ptr

◆ context

◆ init()

◆ del()

◆ enter()

◆ exit()