0.1.23
Loading...
Searching...
No Matches
pyhelios.PhotosynthesisModel.PhotosynthesisModel Class Reference

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
Example
>>> 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 76 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.
 
 setModelTypeC4 (self)
 Set the photosynthesis model type to the von Caemmerer (2021) steady-state C4 model.
 
 setFarquharMesophyllConductance (self, float gm_at_25c, float dha=-1.0, float topt=-1.0, float dhd=-1.0, Optional[List[int]] uuids=None)
 Set Farquhar mesophyll conductance gm (mol CO2 / m² / s / bar) for selected primitives.
 
 setC4CoefficientsFromLibrary (self, str species, Optional[List[int]] uuids=None, Optional[str] material_label=None)
 Set C4 model coefficients from the von Caemmerer (2021) species library.
 
List[float] getC4CoefficientsFromLibrary (self, str species)
 Return the 43-float C4 coefficient array for species.
 
 setC4ModelCoefficients (self, List[float] coefficients, Optional[List[int]] uuids=None, Optional[str] material_label=None)
 Apply a 43-float C4 coefficient array.
 
List[float] getC4ModelCoefficients (self, int uuid)
 Return the 43-float C4 coefficient array for a single primitive.
 
 setCm (self, float cm, List[int] uuids)
 Manually prescribe the mesophyll cytosolic CO2 partial pressure (Cm) for the C4 model.
 
 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
contextPyHelios Context instance containing the 3D geometry
Exceptions
PhotosynthesisModelErrorIf plugin is not available or initialization fails

Definition at line 87 of file PhotosynthesisModel.py.

◆ __del__()

pyhelios.PhotosynthesisModel.PhotosynthesisModel.__del__ ( self)

Destructor to ensure cleanup.

Definition at line 146 of file PhotosynthesisModel.py.

Member Function Documentation

◆ __enter__()

pyhelios.PhotosynthesisModel.PhotosynthesisModel.__enter__ ( self)

Context manager entry.

Definition at line 124 of file PhotosynthesisModel.py.

◆ __exit__()

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

Context manager exit with cleanup.

Definition at line 128 of file PhotosynthesisModel.py.

◆ cleanup()

pyhelios.PhotosynthesisModel.PhotosynthesisModel.cleanup ( self)

Clean up native resources.

Definition at line 132 of file PhotosynthesisModel.py.

◆ disableMessages()

pyhelios.PhotosynthesisModel.PhotosynthesisModel.disableMessages ( self)

Disable photosynthesis model status messages.

Definition at line 680 of file PhotosynthesisModel.py.

◆ enableMessages()

pyhelios.PhotosynthesisModel.PhotosynthesisModel.enableMessages ( self)

Enable photosynthesis model status messages.

Definition at line 676 of file PhotosynthesisModel.py.

◆ exportResults()

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

Export photosynthesis results with optional label.

Parameters
labelData label for export

Definition at line 671 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 382 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 142 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 392 of file PhotosynthesisModel.py.

◆ getC4CoefficientsFromLibrary()

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

Return the 43-float C4 coefficient array for species.

   See ``native/include/pyhelios_wrapper_photosynthesis.h`` for the per-index meaning.

Definition at line 248 of file PhotosynthesisModel.py.

◆ getC4ModelCoefficients()

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

Return the 43-float C4 coefficient array for a single primitive.

Definition at line 280 of file PhotosynthesisModel.py.

◆ getEmpiricalModelCoefficients()

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

Get empirical model coefficients for a specific primitive.

Parameters
uuidPrimitive UUID
Returns
List of empirical model coefficients

Definition at line 650 of file PhotosynthesisModel.py.

◆ getFarquharModelCoefficients()

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

Get Farquhar model coefficients for a specific primitive.

Parameters
uuidPrimitive UUID
Returns
List of Farquhar model coefficients

Definition at line 662 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
speciesSpecies name
Returns
List of Farquhar model coefficients for the species

Definition at line 371 of file PhotosynthesisModel.py.

◆ printModelReport()

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

Print model configuration report.

Parameters
uuidsOptional list of UUIDs. If None, prints report for all primitives.

Definition at line 689 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 709 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 309 of file PhotosynthesisModel.py.

◆ runForPrimitives()

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

Run photosynthesis calculations for specific primitives.

Parameters
uuidsSingle UUID (integer) or list of UUIDs for primitives

Definition at line 319 of file PhotosynthesisModel.py.

◆ setC4CoefficientsFromLibrary()

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

Set C4 model coefficients from the von Caemmerer (2021) species library.

Parameters
speciesSpecies name (case-insensitive). See :data:AVAILABLE_C4_SPECIES.
uuidsOptional list of primitive UUIDs. If None and material_label is also None, applies to all primitives in the Context.
material_labelOptional material label. When set, applies the coefficients to every primitive that references this material at run() time. Mutually exclusive with uuids.
Exceptions
ValueErrorIf both ``uuids`` and ``material_label`` are provided.
NotImplementedErrorIf running against helios-core older than v1.3.72.

Definition at line 232 of file PhotosynthesisModel.py.

◆ setC4ModelCoefficients()

pyhelios.PhotosynthesisModel.PhotosynthesisModel.setC4ModelCoefficients ( self,
List[float] coefficients,
Optional[List[int]] uuids = None,
Optional[str] material_label = None )

Apply a 43-float C4 coefficient array.

   Pair with :meth:`getC4CoefficientsFromLibrary` to round-trip a species' defaults.
Parameters
coefficients43-float C4 coefficient array.
uuidsOptional list of primitive UUIDs. If None and material_label is also None, applies to all primitives in the Context.
material_labelOptional material label. When set, applies the coefficients to every primitive that references this material at run() time. Mutually exclusive with uuids.
Exceptions
ValueErrorIf both ``uuids`` and ``material_label`` are provided.

Definition at line 267 of file PhotosynthesisModel.py.

◆ setCm()

pyhelios.PhotosynthesisModel.PhotosynthesisModel.setCm ( self,
float cm,
List[int] uuids )

Manually prescribe the mesophyll cytosolic CO2 partial pressure (Cm) for the C4 model.

   Bypasses the ``Cm = Ci - A/gm`` fixed-point iteration and the stomatal balance
   on Ci. Primarily intended for testing and validation against the von Caemmerer 2021
   reference spreadsheet.
Parameters
cmMesophyll cytosolic CO2 partial pressure in ubar.
uuidsPrimitive UUIDs to set. Must be non-empty.
Exceptions
ValueErrorIf ``uuids`` is empty.
NotImplementedErrorIf running against helios-core older than v1.3.72.

Definition at line 298 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
respirationDark respiration rate at 25°C (μmol m⁻² s⁻¹)
uuidsList of primitive UUIDs to modify (required)
dhaActivation energy (optional, kJ/mol)
toptOptimal temperature (optional, °C)
dhdDeactivation 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 542 of file PhotosynthesisModel.py.

◆ setEmpiricalModelCoefficients()

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

Set empirical model coefficients.

Parameters
coefficientsEmpiricalModelCoefficients instance with model parameters
uuidsOptional list of primitive UUIDs. If None, applies to all primitives.

Definition at line 404 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
speciesSpecies name from the built-in library
uuidsOptional list of primitive UUIDs. If None, applies to all primitives.
Example
>>> model.setFarquharCoefficientsFromLibrary("APPLE") >>> model.setFarquharCoefficientsFromLibrary("SOYBEAN", [uuid1, uuid2])

Definition at line 356 of file PhotosynthesisModel.py.

◆ setFarquharMesophyllConductance()

pyhelios.PhotosynthesisModel.PhotosynthesisModel.setFarquharMesophyllConductance ( self,
float gm_at_25c,
float dha = -1.0,
float topt = -1.0,
float dhd = -1.0,
Optional[List[int]] uuids = None )

Set Farquhar mesophyll conductance gm (mol CO2 / m² / s / bar) for selected primitives.

   Pass ``dha`` < 0 (the default) to apply ``gm`` with no temperature response. Pass a
   positive ``dha`` and leave ``topt``/``dhd`` at -1 to use a monotonic Arrhenius response.
   Set ``topt`` (in °C) for a peaked Arrhenius response, and ``dhd`` to override the
   deactivation energy (defaults to ``10*dha``).
Parameters
gm_at_25cgm at the 25 °C reference, mol CO2 / m² / s / bar.
dhaActivation energy (kJ/mol). -1 disables temperature response.
toptOptimum temperature in °C. -1 keeps Arrhenius monotonic.
dhdDeactivation energy (kJ/mol). -1 picks a default.
uuidsPrimitive UUIDs to update. None is rejected; the underlying wrapper requires explicit UUIDs (matching setVcmax etc.).
Exceptions
ValueErrorIf ``uuids`` is None or empty.
NotImplementedErrorIf running against helios-core older than v1.3.72.

Definition at line 203 of file PhotosynthesisModel.py.

◆ setFarquharModelCoefficients()

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

Set Farquhar model coefficients.

Parameters
coefficientsFarquharModelCoefficients instance with FvCB parameters
uuidsOptional list of primitive UUIDs. If None, applies to all primitives.

Definition at line 422 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
jmaxMaximum electron transport rate at 25°C (μmol m⁻² s⁻¹)
uuidsList of primitive UUIDs to modify (required)
dhaActivation energy (optional, kJ/mol)
toptOptimal temperature (optional, °C)
dhdDeactivation 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 505 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
curvatureLight response curvature at 25°C (dimensionless)
uuidsList of primitive UUIDs to modify (required)
dhaActivation energy (optional, kJ/mol)
toptOptimal temperature (optional, °C)
dhdDeactivation 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 621 of file PhotosynthesisModel.py.

◆ setModelTypeC4()

pyhelios.PhotosynthesisModel.PhotosynthesisModel.setModelTypeC4 ( self)

Set the photosynthesis model type to the von Caemmerer (2021) steady-state C4 model.

   Pair with :meth:`setC4CoefficientsFromLibrary` (e.g. ``"SetariaViridis_vC2021"``,
   ``"Maize_Massad2007"``) or :meth:`setC4ModelCoefficients` to populate parameters.
Note
Requires helios-core v1.3.72 or newer.
Exceptions
NotImplementedErrorIf running against an older helios-core that does not support the C4 bindings — rebuild with build_scripts/build_helios --clean.

Definition at line 180 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 155 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 164 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
efficiencyQuantum efficiency at 25°C (dimensionless, 0-1)
uuidsList of primitive UUIDs to modify (required)
dhaActivation energy (optional, kJ/mol)
toptOptimal temperature (optional, °C)
dhdDeactivation 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 579 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
speciesSpecies name from the built-in library
uuidsOptional list of primitive UUIDs. If None, applies to all primitives.
Example
>>> model.setSpeciesCoefficients("APPLE") >>> model.setSpeciesCoefficients("SOYBEAN", [uuid1, uuid2])

Definition at line 337 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
vcmaxMaximum carboxylation rate at 25°C (μmol m⁻² s⁻¹)
uuidsList of primitive UUIDs to modify (required)
dhaActivation energy (optional, kJ/mol)
toptOptimal temperature (optional, °C)
dhdDeactivation 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 452 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 702 of file PhotosynthesisModel.py.

Member Data Documentation

◆ _native_ptr

pyhelios.PhotosynthesisModel.PhotosynthesisModel._native_ptr = None
protected

Definition at line 94 of file PhotosynthesisModel.py.

◆ context

pyhelios.PhotosynthesisModel.PhotosynthesisModel.context = context

Definition at line 93 of file PhotosynthesisModel.py.


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