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.

Definition at line 7 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.

float	blackbodyBandFraction (float wavelength_min_nm, float wavelength_max_nm, float temperature_K)
	Fraction of a blackbody's total emissive power emitted between two wavelengths.

float	blackbodySpectralRadiance (float wavelength_nm, float temperature_K)
	Spectral radiance of a blackbody (Planck's law).

Member Function Documentation

◆ blackbodyBandFraction()

float pyhelios.Global.Global.blackbodyBandFraction	(	float	wavelength_min_nm,
		float	wavelength_max_nm,
		float	temperature_K )

static

Fraction of a blackbody's total emissive power emitted between two wavelengths.

   This is the integral of Planck's law between the two wavelengths divided by its
   integral over all wavelengths (``sigma * T**4``). Multiplying the result by
   ``emissivity * sigma * T**4`` gives the in-band emitted flux of a gray surface,
   which is what a RadiationModel emission band added with wavelength bounds emits.

Parameters

wavelength_min_nm	Lower wavelength bound (nm); must be >= 0
wavelength_max_nm	Upper wavelength bound (nm); must be greater than `wavelength_min_nm`
temperature_K	Blackbody temperature (K); must be > 0

Returns: Fraction of blackbody emissive power in the band, in [0, 1]

Exceptions

ValueError	If an argument is not a number
HeliosError	If the bounds or the temperature are out of range
RuntimeError	If the native library predates helios-core v1.3.90

Example: >>> from pyhelios import Global >>> fraction = Global.blackbodyBandFraction(8000, 14000, 300.0) # 8-14 um at 300 K >>> in_band_flux = 0.98 * 5.670374e-8 * 300.0**4 * fraction # W/m^2

Definition at line 266 of file Global.py.

◆ blackbodySpectralRadiance()

float pyhelios.Global.Global.blackbodySpectralRadiance	(	float	wavelength_nm,
		float	temperature_K )

static

Spectral radiance of a blackbody (Planck's law).

   Its integral over all wavelengths is ``sigma * T**4 / pi``.

Parameters

wavelength_nm	Wavelength (nm); must be > 0
temperature_K	Blackbody temperature (K); must be > 0

Returns: Spectral radiance in W/m^2/sr/nm

Exceptions

ValueError	If an argument is not a number
HeliosError	If the wavelength or the temperature is not positive
RuntimeError	If the native library predates helios-core v1.3.90

Definition at line 286 of file Global.py.

◆ 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

theta	Leaf inclination angle (radians)
mu	First parameter of the Beta distribution; must be positive
nu	Second parameter of the Beta distribution; must be positive

Returns: Cumulative probability in [0, 1]

Exceptions

HeliosError	If ``mu`` or ``nu`` is not positive
RuntimeError	If 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 171 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

phi	Azimuth angle (radians)
e	Eccentricity of the ellipsoidal distribution; must be in `[0, 1]`
phi0_degrees	Azimuthal rotation of the ellipse (degrees)

Returns: Cumulative probability in [0, 1]

Exceptions

HeliosError	If ``e`` is outside ``[0, 1]``
RuntimeError	If the native library predates helios-core v1.3.87

Definition at line 213 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 makes the absence of a GPU an error.

   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 38 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

probability	Cumulative probability; must be in `[0, 1]`
mu	First parameter of the Beta distribution; must be positive
nu	Second parameter of the Beta distribution; must be positive

Returns: Leaf inclination angle (radians) in [0, pi/2]

Exceptions

HeliosError	If ``probability`` is outside ``[0, 1]``, or ``mu``/``nu`` is not positive
RuntimeError	If the native library predates helios-core v1.3.87

Definition at line 192 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

probability	Cumulative probability; must be in `[0, 1]`
e	Eccentricity of the ellipsoidal distribution; must be in `[0, 1]`
phi0_degrees	Azimuthal rotation of the ellipse (degrees)

Returns: Azimuth angle (radians) in [0, 2*pi)

Exceptions

HeliosError	If ``probability`` or ``e`` is outside ``[0, 1]``
RuntimeError	If the native library predates helios-core v1.3.87

Definition at line 233 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

imin	Lower bound of the integer range (inclusive). Must be given with `imax`.
imax	Upper 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

ValueError	If exactly one of ``imin``/``imax`` is given, or either is not an int
RuntimeError	If the native library predates helios-core v1.3.85

Definition at line 134 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.

Parameters

context_message Description of what was about to be skipped, included in the error message

Exceptions

HeliosError If 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 65 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

seed	Value used to seed the generator (unsigned 32-bit)

Exceptions

ValueError	If ``seed`` is not an int in ``[0, 2**32 - 1]``
RuntimeError	If 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 108 of file Global.py.

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

pyhelios/Global.py

Detailed Description

Static Public Member Functions

Member Function Documentation

◆ blackbodyBandFraction()

◆ blackbodySpectralRadiance()

◆ evaluateBetaDistributionCDF()

◆ evaluateEllipsoidalAzimuthCDF()

◆ gpuRequiredByEnvironment()

◆ invertBetaDistributionCDF()

◆ invertEllipsoidalAzimuthCDF()

◆ randu()

◆ requireGPUOrFail()

◆ seedRandomGenerator()