![]() |
0.1.39
|
High-level interface for plant hydraulics modeling. More...
High-level interface for plant hydraulics modeling.
The model computes the water potential of the root, stem and leaf compartments of a plant from the transpiration of its leaves and a soil water potential set by the user. Stems and roots are each one compartment per plant; leaf water potential, turgor pressure, osmotic potential and relative water content are computed for each leaf primitive.
Leaves are grouped into plants by a "plantID", read from the object data of a primitive's parent object or from the primitive's own data. run() groups the primitives it is given that have no plantID into a new plant (see run()).
Input primitive data (float):
Water-potential dependent conductances are evaluated once per run at the water potentials from before the run (for the stem and root, those stored from the model's previous run of the plant, or -0.001 MPa), so a steady-state run is not iterated to a self-consistent solution.
Output primitive data:
Steady-state runs (timespan=0) are the supported mode; non-steady-state runs are under construction in the native plugin.
System requirements:
Definition at line 576 of file PlantHydraulics.py.
Public Member Functions | |
| __init__ (self, Context context) | |
| Initialize PlantHydraulicsModel 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 | setModelCoefficients (self, PlantHydraulicsModelCoefficients modelcoefficients, Optional[List[int]] UUIDs=None) |
| Set the model coefficients for all primitives, or for a subset of primitives. | |
| None | setModelCoefficientsFromLibrary (self, str species, Optional[Union[int, List[int]]] UUIDs=None) |
| Set the model coefficients from the species library. | |
| PlantHydraulicsModelCoefficients | getModelCoefficients (self, int UUID) |
| Get the coefficients set for a specific primitive. | |
| PlantHydraulicsModelCoefficients | getModelCoefficientsFromLibrary (self, str species) |
| Get the model coefficients of a species from the library. | |
| None | run (self, Optional[List[int]] UUIDs=None, int timespan=0, int timestep=100) |
| Run the plant hydraulics model. | |
| None | outputConductancePrimitiveData (self, bool toggle) |
| Toggle writing of the optional primitive data "hydraulic_conductance" (mol/m²/s/MPa). | |
| None | outputCapacitancePrimitiveData (self, bool toggle) |
| Toggle writing of the optional primitive data "hydraulic_capacitance" (mol/m²/MPa). | |
| int | groupPrimitivesIntoPlantObject (self, List[int] UUIDs) |
| Group leaf primitives into a plant that shares stem, root and soil hydraulics. | |
| int | getPlantID (self, Union[int, List[int]] UUIDs) |
| Get the plantID of a primitive, or the plantID shared by a list of primitives. | |
| List[int] | getUniquePlantIDs (self, List[int] UUIDs) |
| Get the unique plantIDs of a list of primitives. | |
| List[int] | getPrimitivesByPlantID (self, int plantID) |
| Get the primitives belonging to a plant. | |
| List[int] | getPrimitivesWithoutPlantID (self, List[int] UUIDs) |
| Get the primitives that have no plantID, in either parent object data or primitive data. | |
| float | getStemWaterPotential (self, Union[int, List[int]] UUIDs) |
| Get the stem water potential (MPa) of the plant that a leaf primitive, or a list of leaf primitives of one plant, belongs to. | |
| float | getStemWaterPotentialOfPlant (self, int plantID) |
| Get the stem water potential (MPa) of a plant. | |
| float | getRootWaterPotential (self, Union[int, List[int]] UUIDs) |
| Get the root water potential (MPa) of the plant that a leaf primitive, or a list of leaf primitives of one plant, belongs to. | |
| float | getRootWaterPotentialOfPlant (self, int plantID) |
| Get the root water potential (MPa) of a plant. | |
| float | getSoilWaterPotential (self, Union[int, List[int]] UUIDs) |
| Get the soil water potential (MPa) of the plant that a leaf primitive, or a list of leaf primitives of one plant, belongs to. | |
| float | getSoilWaterPotentialOfPlant (self, int plantID) |
| Get the soil water potential (MPa) of a plant. | |
| None | setSoilWaterPotentialOfPlant (self, int plantID, float soil_water_potential) |
| Set the soil water potential of a plant. | |
| bool | is_available (self) |
| Check if PlantHydraulicsModel is available in current build. | |
Static Public Member Functions | |
| float | computeOsmoticPotential (HydraulicCapacitance coeffs, float relative_water_content) |
| Compute osmotic potential (MPa) at a relative water content from pressure-volume curve parameters. | |
| float | computeTurgorPressure (HydraulicCapacitance coeffs, float relative_water_content) |
| Compute turgor pressure (MPa) at a relative water content from pressure-volume curve parameters. | |
| float | computeWaterPotential (HydraulicCapacitance coeffs, float relative_water_content) |
| Compute water potential (MPa) at a relative water content, the sum of turgor pressure and osmotic potential from pressure-volume curve parameters. | |
| float | computeCapacitance (HydraulicCapacitance coeffs, float relative_water_content) |
| Compute hydraulic capacitance (mol/m²/MPa) at a relative water content. | |
| float | computeConductance (HydraulicConductance coeffs, float water_potential, float temperature=298.15) |
| Compute hydraulic conductance (mol/m²/s/MPa) at a water potential and temperature. | |
Public Attributes | |
| context = context | |
| hydraulics_model = None | |
Protected Member Functions | |
| _check_context_alive (self) | |
| Raise if the owning Context has been destroyed (see Context.check_context_alive). | |
| None | _require_shared_plant (self, List[int] uuid_list) |
| float | _get_water_potential (self, str compartment, UUIDs, str method_name) |
| float | _get_water_potential_of_plant (self, str compartment, plantID, str method_name) |
Static Protected Member Functions | |
| _single_or_list (UUIDs, str method_name) | |
| float | _validate_curve_args (coeffs, relative_water_content, str method_name) |
Protected Attributes | |
| _per_primitive_uuids = set() | |
| pyhelios.PlantHydraulics.PlantHydraulicsModel.__init__ | ( | self, | |
| Context | context ) |
Initialize PlantHydraulicsModel with graceful plugin handling.
| context | Helios Context instance |
| TypeError | If context is not a Context instance |
| PlantHydraulicsModelError | If the plant hydraulics plugin is not available |
Definition at line 588 of file PlantHydraulics.py.
| pyhelios.PlantHydraulics.PlantHydraulicsModel.__del__ | ( | self | ) |
Destructor to ensure C++ resources freed even without 'with' statement.
Definition at line 651 of file PlantHydraulics.py.
| pyhelios.PlantHydraulics.PlantHydraulicsModel.__enter__ | ( | self | ) |
Context manager entry.
Definition at line 636 of file PlantHydraulics.py.
| pyhelios.PlantHydraulics.PlantHydraulicsModel.__exit__ | ( | self, | |
| exc_type, | |||
| exc_value, | |||
| traceback ) |
Context manager exit with proper cleanup.
Definition at line 640 of file PlantHydraulics.py.
|
protected |
Raise if the owning Context has been destroyed (see Context.check_context_alive).
Definition at line 632 of file PlantHydraulics.py.
|
protected |
Definition at line 1041 of file PlantHydraulics.py.
|
protected |
Definition at line 1052 of file PlantHydraulics.py.
|
protected |
Definition at line 968 of file PlantHydraulics.py.
|
staticprotected |
Definition at line 1036 of file PlantHydraulics.py.
|
staticprotected |
Definition at line 1144 of file PlantHydraulics.py.
|
static |
Compute hydraulic capacitance (mol/m²/MPa) at a relative water content.
Returns the constant capacitance if coeffs holds one, otherwise the saturated specific water content divided by the slope of the pressure-volume curve.
| coeffs | Hydraulic capacitance parameters |
| relative_water_content | Relative water content (unitless), in (0.001, 1] |
Definition at line 1201 of file PlantHydraulics.py.
|
static |
Compute hydraulic conductance (mol/m²/s/MPa) at a water potential and temperature.
| coeffs | Hydraulic conductance parameters |
| water_potential | Water potential (MPa) |
| temperature | Temperature (K); used only if coeffs has temperature dependence enabled |
Definition at line 1216 of file PlantHydraulics.py.
|
static |
Compute osmotic potential (MPa) at a relative water content from pressure-volume curve parameters.
| coeffs | Pressure-volume curve parameters |
| relative_water_content | Relative water content (unitless), in (0, 1] |
Definition at line 1161 of file PlantHydraulics.py.
|
static |
Compute turgor pressure (MPa) at a relative water content from pressure-volume curve parameters.
| coeffs | Pressure-volume curve parameters |
| relative_water_content | Relative water content (unitless), in (0, 1] |
Definition at line 1173 of file PlantHydraulics.py.
|
static |
Compute water potential (MPa) at a relative water content, the sum of turgor pressure and osmotic potential from pressure-volume curve parameters.
| coeffs | Pressure-volume curve parameters |
| relative_water_content | Relative water content (unitless), in (0, 1] |
Definition at line 1186 of file PlantHydraulics.py.
| PlantHydraulicsModelCoefficients pyhelios.PlantHydraulics.PlantHydraulicsModel.getModelCoefficients | ( | self, | |
| int | UUID ) |
Get the coefficients set for a specific primitive.
Only coefficients given for specific primitives can be read: those set with setModelCoefficients() or setModelCoefficientsFromLibrary() and a UUIDs argument. A primitive without its own coefficients uses the model-wide ones, which the native model does not expose. Leaf capacitance taken from the species library is returned as its pressure-volume curve parameters, with leaf_capacitance_species set to None.
| UUID | Primitive UUID |
| ValueError | If UUID is not a non-negative integer |
| PlantHydraulicsModelError | If no coefficients were set for this primitive, or the operation fails |
Definition at line 777 of file PlantHydraulics.py.
| PlantHydraulicsModelCoefficients pyhelios.PlantHydraulics.PlantHydraulicsModel.getModelCoefficientsFromLibrary | ( | self, | |
| str | species ) |
Get the model coefficients of a species from the library.
The library provides leaf pressure-volume curve parameters; all other coefficients are at their default values. The leaf capacitance is returned as its parameter values, with leaf_capacitance_species set to None.
| species | Species name. See pyhelios.PlantHydraulics.AVAILABLE_SPECIES. |
| ValueError | If the species is not in the library |
| PlantHydraulicsModelError | If operation fails |
Definition at line 815 of file PlantHydraulics.py.
| pyhelios.PlantHydraulics.PlantHydraulicsModel.getNativePtr | ( | self | ) |
Get the native pointer for advanced operations.
Definition at line 661 of file PlantHydraulics.py.
| int pyhelios.PlantHydraulics.PlantHydraulicsModel.getPlantID | ( | self, | |
| Union[int, List[int]] | UUIDs ) |
Get the plantID of a primitive, or the plantID shared by a list of primitives.
| UUIDs | Primitive UUID or list of UUIDs |
| ValueError | If UUIDs is empty |
| PlantHydraulicsModelError | If a primitive has no plantID, or the primitives do not share one |
Definition at line 957 of file PlantHydraulics.py.
| List[int] pyhelios.PlantHydraulics.PlantHydraulicsModel.getPrimitivesByPlantID | ( | self, | |
| int | plantID ) |
Get the primitives belonging to a plant.
| plantID | Plant identifier |
Definition at line 1004 of file PlantHydraulics.py.
| List[int] pyhelios.PlantHydraulics.PlantHydraulicsModel.getPrimitivesWithoutPlantID | ( | self, | |
| List[int] | UUIDs ) |
Get the primitives that have no plantID, in either parent object data or primitive data.
| UUIDs | Primitive UUIDs to check |
| ValueError | If UUIDs is empty |
Definition at line 1025 of file PlantHydraulics.py.
| float pyhelios.PlantHydraulics.PlantHydraulicsModel.getRootWaterPotential | ( | self, | |
| Union[int, List[int]] | UUIDs ) |
Get the root water potential (MPa) of the plant that a leaf primitive, or a list of leaf primitives of one plant, belongs to.
| PlantHydraulicsModelError | If the model has not been run for the plant |
Definition at line 1086 of file PlantHydraulics.py.
| float pyhelios.PlantHydraulics.PlantHydraulicsModel.getRootWaterPotentialOfPlant | ( | self, | |
| int | plantID ) |
Get the root water potential (MPa) of a plant.
| PlantHydraulicsModelError | If the model has not been run for the plant |
Definition at line 1095 of file PlantHydraulics.py.
| float pyhelios.PlantHydraulics.PlantHydraulicsModel.getSoilWaterPotential | ( | self, | |
| Union[int, List[int]] | UUIDs ) |
Get the soil water potential (MPa) of the plant that a leaf primitive, or a list of leaf primitives of one plant, belongs to.
| PlantHydraulicsModelError | If no soil water potential has been set and the model has not been run for the plant |
Definition at line 1106 of file PlantHydraulics.py.
| float pyhelios.PlantHydraulics.PlantHydraulicsModel.getSoilWaterPotentialOfPlant | ( | self, | |
| int | plantID ) |
Get the soil water potential (MPa) of a plant.
| PlantHydraulicsModelError | If no soil water potential has been set and the model has not been run for the plant |
Definition at line 1116 of file PlantHydraulics.py.
| float pyhelios.PlantHydraulics.PlantHydraulicsModel.getStemWaterPotential | ( | self, | |
| Union[int, List[int]] | UUIDs ) |
Get the stem water potential (MPa) of the plant that a leaf primitive, or a list of leaf primitives of one plant, belongs to.
| PlantHydraulicsModelError | If the model has not been run for the plant |
Definition at line 1067 of file PlantHydraulics.py.
| float pyhelios.PlantHydraulics.PlantHydraulicsModel.getStemWaterPotentialOfPlant | ( | self, | |
| int | plantID ) |
Get the stem water potential (MPa) of a plant.
| PlantHydraulicsModelError | If the model has not been run for the plant |
Definition at line 1076 of file PlantHydraulics.py.
| List[int] pyhelios.PlantHydraulics.PlantHydraulicsModel.getUniquePlantIDs | ( | self, | |
| List[int] | UUIDs ) |
Get the unique plantIDs of a list of primitives.
| UUIDs | Primitive UUIDs |
| ValueError | If UUIDs is empty |
| PlantHydraulicsModelError | If a primitive has no plantID |
Definition at line 987 of file PlantHydraulics.py.
| int pyhelios.PlantHydraulics.PlantHydraulicsModel.groupPrimitivesIntoPlantObject | ( | self, | |
| List[int] | UUIDs ) |
Group leaf primitives into a plant that shares stem, root and soil hydraulics.
Those of the primitives that do not belong to an object are added to a new polymesh object. All of them are given the primitive data "plantID", set to that object's ID; primitives that already belong to an object stay in it.
| UUIDs | Leaf primitive UUIDs |
| ValueError | If UUIDs is empty, or any of the primitives already has a plantID |
| PlantHydraulicsModelError | If all of the primitives already belong to an object, so that no polymesh object can be created |
Definition at line 925 of file PlantHydraulics.py.
| bool pyhelios.PlantHydraulics.PlantHydraulicsModel.is_available | ( | self | ) |
Check if PlantHydraulicsModel is available in current build.
Definition at line 1232 of file PlantHydraulics.py.
| None pyhelios.PlantHydraulics.PlantHydraulicsModel.outputCapacitancePrimitiveData | ( | self, | |
| bool | toggle ) |
Toggle writing of the optional primitive data "hydraulic_capacitance" (mol/m²/MPa).
The data is written by non-steady-state runs only.
| toggle | True to write the data |
Definition at line 897 of file PlantHydraulics.py.
| None pyhelios.PlantHydraulics.PlantHydraulicsModel.outputConductancePrimitiveData | ( | self, | |
| bool | toggle ) |
Toggle writing of the optional primitive data "hydraulic_conductance" (mol/m²/s/MPa).
The data is written by non-steady-state runs only.
| toggle | True to write the data |
Definition at line 881 of file PlantHydraulics.py.
| None pyhelios.PlantHydraulics.PlantHydraulicsModel.run | ( | self, | |
| Optional[List[int]] | UUIDs = None, | ||
| int | timespan = 0, | ||
| int | timestep = 100 ) |
Run the plant hydraulics model.
Primitives sharing a plantID are treated as the leaves of one plant, with one stem, root and soil water potential. The model runs for every plant that the given primitives belong to, and writes output data to all primitives in the Context with that plantID, not only to the primitives given. Given primitives with no plantID are grouped into one new plant: those that do not belong to an object are added to a new polymesh object, and all of them are given the primitive data "plantID", set to that object's ID. Primitives that already belong to an object stay in it.
| UUIDs | Optional list of primitive UUIDs selecting the plants to run. If None, runs for all primitives in the Context; primitives with no plantID, including any that are not leaves, are then grouped into a single plant. |
| timespan | Duration of the simulation (s). 0 gives the steady-state solution. |
| timestep | Timestep of a non-steady-state simulation (s). |
| ValueError | If UUIDs is empty, timespan is negative, or timestep is not positive |
| PlantHydraulicsModelError | If calculation fails, including when every primitive without a plantID already belongs to an object, so that no polymesh object can be created |
Definition at line 859 of file PlantHydraulics.py.
| None pyhelios.PlantHydraulics.PlantHydraulicsModel.setModelCoefficients | ( | self, | |
| PlantHydraulicsModelCoefficients | modelcoefficients, | ||
| Optional[List[int]] | UUIDs = None ) |
Set the model coefficients for all primitives, or for a subset of primitives.
Setting coefficients for all primitives clears any coefficients previously set for specific primitives. Coefficients set for specific primitives apply to their leaf conductance and capacitance only. Stem and root water potentials are always computed from the coefficients set for all primitives.
| modelcoefficients | Hydraulic conductance and capacitance parameters |
| UUIDs | Optional list of primitive UUIDs. If None, applies to all primitives. |
| ValueError | If modelcoefficients is not a PlantHydraulicsModelCoefficients, a parameter is out of range, or UUIDs is empty |
| PlantHydraulicsModelError | If operation fails |
Definition at line 690 of file PlantHydraulics.py.
| None pyhelios.PlantHydraulics.PlantHydraulicsModel.setModelCoefficientsFromLibrary | ( | self, | |
| str | species, | ||
| Optional[Union[int, List[int]]] | UUIDs = None ) |
Set the model coefficients from the species library.
The library provides leaf pressure-volume curve parameters; all other coefficients take their default values.
| species | Species name. See pyhelios.PlantHydraulics.AVAILABLE_SPECIES. |
| UUIDs | Optional primitive UUID or list of UUIDs. If None, applies to all primitives. |
| ValueError | If the species is not in the library or UUIDs is empty |
| PlantHydraulicsModelError | If operation fails |
Definition at line 731 of file PlantHydraulics.py.
| None pyhelios.PlantHydraulics.PlantHydraulicsModel.setSoilWaterPotentialOfPlant | ( | self, | |
| int | plantID, | ||
| float | soil_water_potential ) |
Set the soil water potential of a plant.
Plants with no soil water potential set use -0.001 MPa.
| plantID | Plant identifier |
| soil_water_potential | Soil water potential (MPa) |
Definition at line 1132 of file PlantHydraulics.py.
|
protected |
Definition at line 598 of file PlantHydraulics.py.
| pyhelios.PlantHydraulics.PlantHydraulicsModel.context = context |
Definition at line 595 of file PlantHydraulics.py.
| pyhelios.PlantHydraulics.PlantHydraulicsModel.hydraulics_model = None |
Definition at line 596 of file PlantHydraulics.py.