0.1.33
Loading...
Searching...
No Matches
List of all members | Static Public Member Functions
pyhelios.Global.Global Class Reference

Process-wide helios-core functions that belong to no Context or plug-in model. More...

Detailed Description

Process-wide helios-core functions that belong to no Context or plug-in model.

The plug-in build root used to locate runtime assets is not settable here: it is a per-model construction argument (see WeberPennTree(context, build_directory)), and helios-core exposes no global setter for it.

Definition at line 12 of file Global.py.

Static Public Member Functions

bool gpuRequiredByEnvironment ()
 Check whether a GPU is required by the HELIOS_REQUIRE_GPU environment variable.
 
None requireGPUOrFail (str context_message)
 Raise if HELIOS_REQUIRE_GPU is set but no usable GPU was found.
 
None seedRandomGenerator (int seed)
 Seed the process-wide random number generator so a run can be reproduced.
 
 randu (Optional[int] imin=None, Optional[int] imax=None)
 Draw from the process-wide random number generator.
 
float evaluateBetaDistributionCDF (float theta, float mu, float nu)
 Cumulative probability that a Beta-distributed leaf inclination is at most theta.
 
float invertBetaDistributionCDF (float probability, float mu, float nu)
 Leaf inclination angle at a given cumulative probability of the Beta distribution.
 
float evaluateEllipsoidalAzimuthCDF (float phi, float e, float phi0_degrees)
 Cumulative probability that an ellipsoidally distributed leaf azimuth is at most phi.
 
float invertEllipsoidalAzimuthCDF (float probability, float e, float phi0_degrees)
 Leaf azimuth angle at a given cumulative probability of the ellipsoidal distribution.
 

Member Function Documentation

◆ evaluateBetaDistributionCDF()

float pyhelios.Global.Global.evaluateBetaDistributionCDF ( float theta,
float mu,
float nu )
static

Cumulative probability that a Beta-distributed leaf inclination is at most theta. 

   This is the CDF of the same Beta leaf-inclination distribution that
   PlantArchitecture's leaf angle distribution methods sample, in the same
parameterization    ``nu`` is the first shape parameter of the underlying Beta
   variate and ``mu`` the second, so the mean inclination is
   ``(pi/2) * nu / (mu + nu)``.

   ``theta`` is measured from vertical and saturates outside ``[0, pi/2]``: a
   negative angle gives 0 and an angle at or above ``pi/2`` gives 1.
Parameters
thetaLeaf inclination angle (radians)
muFirst parameter of the Beta distribution; must be positive
nuSecond parameter of the Beta distribution; must be positive
Returns
Cumulative probability in [0, 1]
Exceptions
HeliosErrorIf ``mu`` or ``nu`` is not positive
RuntimeErrorIf the native library predates helios-core v1.3.87
Example
>>> from pyhelios import Global >>> import math >>> Global.evaluateBetaDistributionCDF(math.pi / 2, 1.0, 1.0) 1.0

Definition at line 185 of file Global.py.

◆ evaluateEllipsoidalAzimuthCDF()

float pyhelios.Global.Global.evaluateEllipsoidalAzimuthCDF ( float phi,
float e,
float phi0_degrees )
static

Cumulative probability that an ellipsoidally distributed leaf azimuth is at most phi. 

   The probability is measured from the ellipse rotation ``phi0_degrees``, and
   ``phi`` is wrapped into ``[0, 2*pi)``.
Parameters
phiAzimuth angle (radians)
eEccentricity of the ellipsoidal distribution; must be in [0, 1]
phi0_degreesAzimuthal rotation of the ellipse (degrees)
Returns
Cumulative probability in [0, 1]
Exceptions
HeliosErrorIf ``e`` is outside ``[0, 1]``
RuntimeErrorIf the native library predates helios-core v1.3.87

Definition at line 227 of file Global.py.

◆ gpuRequiredByEnvironment()

bool pyhelios.Global.Global.gpuRequiredByEnvironment ( )
static

Check whether a GPU is required by the HELIOS_REQUIRE_GPU environment variable. 

   True when ``HELIOS_REQUIRE_GPU`` is set to any value other than ``"0"``.
   This is the counterpart to the ``HELIOS_NO_GPU`` veto: rather than changing
   what hardware probes report, it changes what a test does when no GPU is
   found, so a CI runner dedicated to GPU coverage cannot report success after
   silently skipping every GPU test.

   The environment is read on every call rather than cached, so a change made
   via ``os.environ`` is observed immediately — **except on Windows**, where it
   is never observed at all. ``libhelios.dll`` links the MSVC C runtime
   statically, so it holds a private copy of the environment snapshotted when
   the DLL was loaded, while ``os.environ`` writes go through Python's own
   runtime. On Windows ``HELIOS_REQUIRE_GPU`` must therefore be set before the
   interpreter starts (``set HELIOS_REQUIRE_GPU=1`` in the shell, or the ``env:``
   block of a CI job); setting it from Python has no effect on this function.
   The same applies to ``HELIOS_NO_GPU``.
Returns
True if a usable GPU is mandatory for this process
Example
>>> from pyhelios import Global >>> Global.gpuRequiredByEnvironment() False

Definition at line 45 of file Global.py.

◆ invertBetaDistributionCDF()

float pyhelios.Global.Global.invertBetaDistributionCDF ( float probability,
float mu,
float nu )
static

Leaf inclination angle at a given cumulative probability of the Beta distribution. 

   The inverse of :meth:`evaluateBetaDistributionCDF`, useful for laying out a
   prescribed inclination distribution over a known number of leaves.
Parameters
probabilityCumulative probability; must be in [0, 1]
muFirst parameter of the Beta distribution; must be positive
nuSecond parameter of the Beta distribution; must be positive
Returns
Leaf inclination angle (radians) in [0, pi/2]
Exceptions
HeliosErrorIf ``probability`` is outside ``[0, 1]``, or ``mu``/``nu`` is not positive
RuntimeErrorIf the native library predates helios-core v1.3.87

Definition at line 206 of file Global.py.

◆ invertEllipsoidalAzimuthCDF()

float pyhelios.Global.Global.invertEllipsoidalAzimuthCDF ( float probability,
float e,
float phi0_degrees )
static

Leaf azimuth angle at a given cumulative probability of the ellipsoidal distribution. 

   The inverse of :meth:`evaluateEllipsoidalAzimuthCDF`.
Parameters
probabilityCumulative probability; must be in [0, 1]
eEccentricity of the ellipsoidal distribution; must be in [0, 1]
phi0_degreesAzimuthal rotation of the ellipse (degrees)
Returns
Azimuth angle (radians) in [0, 2*pi)
Exceptions
HeliosErrorIf ``probability`` or ``e`` is outside ``[0, 1]``
RuntimeErrorIf the native library predates helios-core v1.3.87

Definition at line 247 of file Global.py.

◆ randu()

pyhelios.Global.Global.randu ( Optional[int] imin = None,
Optional[int] imax = None )
static

Draw from the process-wide random number generator. 

   With no arguments, returns a uniform float in ``[0, 1)``. With ``imin`` and
   ``imax``, returns a uniform integer over the **inclusive** range
   ``[imin, imax]``; every value, endpoints included, is equally likely, and if
   ``imin >= imax`` then ``imin`` is returned.

   This draws from the same generator that :meth:`seedRandomGenerator` seeds,
   not from any Context's generator; use :meth:`Context.randu` for that one.
Parameters
iminLower bound of the integer range (inclusive). Must be given with imax.
imaxUpper bound of the integer range (inclusive). Must be given with imin.
Returns
A float in [0, 1) when called without arguments, otherwise an int in [imin, imax].
Exceptions
ValueErrorIf exactly one of ``imin``/``imax`` is given, or either is not an int
RuntimeErrorIf the native library predates helios-core v1.3.85

Definition at line 148 of file Global.py.

◆ requireGPUOrFail()

None pyhelios.Global.Global.requireGPUOrFail ( str context_message)
static

Raise if HELIOS_REQUIRE_GPU is set but no usable GPU was found. 

   Call at the point code would otherwise skip for lack of a GPU. Does nothing
   unless ``HELIOS_REQUIRE_GPU`` is set. Setting both ``HELIOS_REQUIRE_GPU`` and
   ``HELIOS_NO_GPU`` is contradictory and is reported as such rather than letting
   one silently win.

   This function does not itself probe for hardware: reaching it is taken as
   proof the caller already determined no GPU was usable, so when
   ``HELIOS_REQUIRE_GPU`` is set it always raises.

   For gating PyHelios's own tests prefer the ``skip_or_fail_without_gpu``
   helper in ``conftest.py``, which reports a skip or failure to pytest directly
   and works in mock mode where no native library is loaded. It also reads the
   environment from Python, so unlike this function it works on Windows when
   the variable was set after the interpreter started — see
   :meth:`gpuRequiredByEnvironment` for why that difference exists.
Parameters
context_messageDescription of what was about to be skipped, included in the error message
Exceptions
HeliosErrorIf a GPU is required by the environment but none was found
Example
>>> from pyhelios import Global, RadiationModel >>> if not RadiationModel.probeAnyGPUBackend(): ... Global.requireGPUOrFail("radiation ray tracing")

Definition at line 79 of file Global.py.

◆ seedRandomGenerator()

None pyhelios.Global.Global.seedRandomGenerator ( int seed)
static

Seed the process-wide random number generator so a run can be reproduced. 

   helios-core has two generators. Each ``Context`` owns one, seeded with
   :meth:`Context.seedRandomGenerator`, and it drives everything drawn through
the primitive placement helpers, ``Context.randu()``, LiDAR
   synthetic-scan noise, and the plant-architecture library's parameter
   sampling. The other is a single process-wide generator behind the free
   function ``helios::randu()``, which plug-in code uses where no Context is at
hand    the LiDAR leaf-group and triangle index draws in
   ``calculateLeafArea()``, and the placement of berries within a grape
   cluster in PlantArchitecture. This method seeds that second generator.

   By default it is seeded from ``std::random_device`` and every run differs.
   Seeding it from Python makes those draws repeatable; seed the Context too
   if the rest of the simulation must repeat as well.

   The generator is shared by all threads and access to it is synchronized, so
   a seed set from any thread applies to every subsequent draw. Seeding fixes
   the sequence of values drawn, not which thread draws which value, so a
   parallel region that draws from it is still scheduling-dependent.
Parameters
seedValue used to seed the generator (unsigned 32-bit)
Exceptions
ValueErrorIf ``seed`` is not an int in ``[0, 2**32 - 1]``
RuntimeErrorIf the native library predates helios-core v1.3.85
Example
>>> from pyhelios import Global >>> Global.seedRandomGenerator(42) >>> a = [Global.randu() for _ in range(3)] >>> Global.seedRandomGenerator(42) >>> assert a == [Global.randu() for _ in range(3)]

Definition at line 122 of file Global.py.

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