Reference

Reference for all user available classes and functions.

LeafArea

Class that holds the formatted leaf area array, used as input.

Attributes:

Name	Type	Description
`leaf_area`	`ndarray`	Represents a point cloud of the canopy leaf area. A numpy array with shape (N, 4) where each row contains (x, y, z, leaf area) and y runs south to north.
`width`	`int`	Width of the area being described. Should be the same as any Terrain width being used in conjunction with this LeafArea.
`height`	`int`	Height of the area being described. Should be the same as any Terrain height being used in conjunction with this LeafArea.

init

__init__(
    leaf_area_point_cloud: ndarray, width: int, height: int
)

Parameters:

Name	Type	Description	Default
`leaf_area_point_cloud`	`ndarray`	Expected as a sparse numpy array with shape (N, 4) where each row is (x, y, z, leaf area) and y runs south to north.	required
`width`	`int`	Width of the area being described. Should be the same as any Terrain width being used in conjunction with this LeafArea.	required
`height`	`int`	Height of the area being described. Should be the same as any Terrain height being used in conjunction with this LeafArea.	required

Returns:

Type	Description
`Instance of LeafArea class object.`

from_uniformgrid `classmethod`

from_uniformgrid(leaf_area_uniform_grid: ndarray)

Initializes LeafArea object from a given uniform grid.

Parameters:

Name	Type	Description	Default
`leaf_area_uniform_grid`	`ndarray`	Uniform grid representing leaf area coordinates and their leaf area. Assumed to be dense. Expected as a 3D numpy array where each (y, x, z) coordinate represents a leaf area value, and where y runs north to south.	required

Returns:

Type	Description
`LeafArea`	Instance of LeafArea class.

Terrain

Class that holds information about the terrain input.

Attributes:

Name	Type	Description
`terrain`	`ndarray`	Represents the terrain. A numpy array with shape (N, 3), where each row is (x, y, z) and y runs south to north.
`width`	`int`	Width of terrain, from shape of input.
`height`	`int`	Height of terrain, from shape of input.
`terrain_grid`	`ndarray`	The original 2.5D provided grid, stored for internal use in later calculations.

init

__init__(terrain: ndarray)

Parameters:

Name	Type	Description	Default
`terrain`	`ndarray`	Assumed to be a 2.5D grid representing the terrain, expected as a 2D numpy array with shape (height, width) where each (y, x) coordinate value represents a z value and where y runs north to south.	required

Returns:

Type	Description
`Terrain`	Instance of Terrain class.

LeafAngle

Class that holds the formatted leaf angle array, used as input.

Attributes:

Name	Type	Description
`leaf_angle`	`ndarray`	Represents a point cloud of canopy mean leaf angle values (radians). A numpy array with shape (N, 4) where each row contains (x, y, z, leaf_angle) and y runs south to north.
`width`	`int`	Width of the area being described. Should be the same as any Terrain and LeafArea width being used in conjunction with this LeafAngle.
`height`	`int`	Height of the area being described. Should be the same as any Terrain and LeafArea height being used in conjunction with this LeafAngle.

init

__init__(
    leaf_angle_point_cloud: ndarray, width: int, height: int
)

Parameters:

Name	Type	Description	Default
`leaf_angle_point_cloud`	`ndarray`	Expected as a sparse numpy array with shape (N, 4) where each row is (x, y, z, leaf angle) and y runs south to north.	required
`width`	`int`	Width of the area being described. Should be the same as any Terrain width being used in conjunction with this LeafAngle.	required
`height`	`int`	Height of the area being described. Should be the same as any Terrain height being used in conjunction with this LeafAngle.	required

Returns:

Type	Description
`Instance of LeafAngle class object.`

from_uniformgrid `classmethod`

from_uniformgrid(leaf_angle_uniform_grid: ndarray)

Initializes LeafAngle object from a given uniform grid.

Parameters:

Name	Type	Description	Default
`leaf_angle_uniform_grid`	`ndarray`	Uniform grid representing leaf angle coordinates and their leaf angle. Assumed to be dense. Expected as a 3D numpy array where each (y, x, z) coordinate represents a leaf angle value, and where y runs north to south.	required

Returns:

Type	Description
`LeafAngle`	Instance of LeafAngle class.

Environment

Class that holds the leaf area and terrain arrays.

Attributes:

Name	Type	Description
`leaf_area`	`LeafArea`	Object that holds the coordinates and leaf area for the canopy.
`terrain`	`Terrain`	Object that holds the coordinates of the terrain.
`leaf_angle`	`LeafAngle`	Object that holds the coordinates and mean leaf angles for the canopy.
`voxel_dim`	`tuple[float, float, float]`	Tuple that holds voxel dimensions like (x, y, z). Should be in the same dimensions used in your leaf_area, terrain, and leaf_angle grids. LeafLux will not do any grid resampling, the user should ensure that all elements of their environment are compatible. If voxel_dim is not specified, than a path length of 1.0 will be used. Note that this is different than supplying voxel dimenions of (1, 1, 1). Not specifying voxel dimension will eliminate the calculation of path length, which increases performance but may impact accuracy.
`sensors`	`ndarray`	A column stack of Sensors present in the environment. Each row of the array is like (x, y, z, pitch, azimuth)

init

__init__(
    leaf_area: LeafArea,
    terrain: Terrain = None,
    leaf_angle: LeafAngle = None,
    voxel_dim: tuple[float, float, float] = None,
    sensors: list[Sensor] = None,
)

Parameters:

Name	Type	Description	Default
`leaf_area`	`LeafArea`	A LeafArea class object.	required
`terrain`	`Terrain`	(optional) A Terrain class object. Default is None.	`None`
`leaf_angle`	`LeafAngle`	(optional) A LeafAngle class object. Default is None.	`None`
`voxel_dim`	`tuple[float, float, float]`	(optional) A tuple describing voxel dimensions in (x, y, z). Default is None.	`None`
`sensors`	`list[Sensor]`	(optional) A list of Sensor objects. Default is None.	`None`

Returns:

Type	Description
`Environment`	Instance of Environment class.

Sensor

Class that holds information about sensors in the environment.

Attributes:

Name	Type	Description
`sensor`	`ndarray`	Holds the (x, y, z) coordinates of the sensor, as well as the pitch and azimuth (if provided). Y coordinates run south to north and angles are in radians. Is a (5,) shaped array where the single row is (x, y, z, pitch, azimuth).

init

__init__(
    x: int,
    y: int,
    z: int,
    pitch: float = None,
    azimuth: float = None,
)

provided to attenuate_all(). If either pitch or azimuth are not provided, returned irradiance will not be corrected.

Parameters:

Name	Type	Description	Default
`x`	`int`	x coordinate of sensor.	required
`y`	`int`	y coordinate of sensor. Y coordinates are expected to run south to north.	required
`z`	`int`	z coordinate of sensor.	required
`pitch`	`float`	Pitch of sensor in radians. Default is None.	`None`
`azimuth`	`float`	Azimuth angle of sensor in radians. Default is None.	`None`

Returns:

Type	Description
`Instance of Sensor class.`

SolarPosition

Class that holds information about the position of the sun for a given date, time, latitude, and longitude.

Attributes:

Name	Type	Description
`timestamp`	`datetime`	The date and time. Must be in UTC.
`latitude`	`float`	Latitide in degrees at which to run light model. Positive south of equator, negative to south. Must be between -90 and 90.
`longitude`	`float`	Longitude in degrees at which to run the light model. Positive south of prime meridian, negative to the west. Must be between -180 and 180.
`light_vector`	`array`	Holds the resulting light vector as a numpy array of three floats.
`zenith`	`float`	The zenith angle in radians.
`azimuth`	`float`	The azimuth angle in radians.

init

__init__(
    datetime: datetime, latitude: float, longitude: float
)

Parameters:

Name	Type	Description	Default
`datetime`	`datetime`	A Python datetime object representing the date and time in UTC.	required
`latitude`	`float`	Latitide in degrees at which to run light model. Positive south of equator, negative to south. Must be between -90 and 90.	required
`longitude`	`float`	Longitude in degrees at which to run the light model. Positive south of prime meridian, negative to the west. Must be between -180 and 180.	required

Returns:

Type	Description
`SolarPosition`	Instance of SolarPosition class.

Irradiance

Class that holds the output relative irradiance for the terrain surface, and if returned from attenuate_all, the canopy irradiance as well.

Attributes:

Name	Type	Description
`canopy_irradiance`	`ndarray`	Holds the coordinates and relative irradiance for the canopy. Is a numpy array with shape (N, 4) where each row is (x, y, z, irradiance), and y runs south to north.
`terrain_irradiance`	`ndarray`	Holds the coordinates and their relative irradiance for the surface/topography. Is a numpy array with shape (height, width) where each (y, x) coordinate holds the irradiance value for that point on the terrain, and y runs north to south.
`sensor_irradiance`	`ndarray`	Holds the coordinates and relative irradiance for each sensor. Is an (N, 4) stack where each row is (x, y, z, irradiance), and y runs south to north. Irradiance values for a particular provided Sensor object can be retrieved with `get_sensor_irradiance()`.

get_sensor_irradiance

get_sensor_irradiance(sensor: Sensor) -> float

Returns the irradiance of a given Sensor.

Parameters:

Name	Type	Description	Default
`sensor`	`Sensor`	Object of type Sensor.	required

Returns:

Type	Description
`float`	Contains the irradiance of the given Sensor.

to_srad

to_srad(dni: float, dhi: float, in_place: bool = False)

Converts the given Irradiance object from relative irradiance to total short wave radiation, GHI (Global Horizontal Irradiance) in Watts/m^2.

Parameters:

Name	Type	Description	Default
`dni`	`float`	DNI (Direct Normal Irradiance) for the datetime this `Irradiance` result is from in Watts/m^2.	required
`dhi`	`float`	DHI (Diffuse Horizontal Irradiance) for the datetime this `Irradiance` result is from in Watts/m^2.	required
`in_place`	`bool`	Bool indicating whether the operation should ocurr in place, modidying the given `Irradiance` object, or if it should return a new result. Default is False.	`False`

Returns:

Type	Description
`Irradiance or None`	If `in_place` was set to False, returns an Irradiance object where all irradiance values have been converted into GHI in Watts/m^2. If `in_place` was set to True, returns None.

to_par

to_par(
    dni: float,
    dhi: float,
    par_ratio: float = 0.5,
    in_place: bool = False,
)

Converts the given Irradiance object from relative to PAR (Photosynthetically Active Radiation) in micromoles/m^2s.

Parameters:

Name	Type	Description	Default
`dni`	`float`	DNI (Direct Normal Irradiance) for the datetime this `Irradiance` result is from in Watts/m^2.	required
`dhi`	`float`	DHI (Diffuse Horizontal Irradiance) for the datetime this `Irradiance` result is from in Watts/m^2.	required
`par_ratio`	`float`	Ratio used to convert GHI to PAR. Default is 0.5.	`0.5`
`in_place`	`bool`	Bool indicating whether the operation should ocurr in place, modidying the given `Irradiance` object, or if it should return a new result. Default is False.	`False`

Returns:

Type	Description
`Irradiance or None`	If `in_place` was set to False, returns an Irradiance object where all irradiance values have been converted into PAR in micromoles/m^2s. If `in_place` was set to True, returns None.

attenuate_surface

attenuate_surface(
    env: Environment, sol: SolarPosition, extn: float = 0.5
) -> Irradiance

Produces Irradiance object, containing the relative irradiance on the terrain surface, for a given Environment and SolarPosition. Runs the irradiance attenuation model on either the surface provided, if it was provided, or on a flat surface. Both algorithms manipulate z values to be in relation to 0, but provided LeafArea and Terrain z values can be absolute. If both LeafArea and Terrain are provided it is expected that sets of coordinates are either both absolute or both manipulated to be relative to 0.

Note: When run with both a LeafArea and Terrain, this function can have different results depending on platform due to vectorized operations. While this algorithm is faster than attenuate_all(), use attenuate_all() if consistency is a priority for your use case.

Note: While having sensors in the provided Environment will not cause any errors, the output will not contain any results for sensors, as results for sensors can only be obtained using attenuate_all().

Parameters:

Name	Type	Description	Default
`env`	`Environment`	Envrironment object which contains the leaf area array and (optionally) the terrain array to be used.	required
`sol`	`SolarPosition`	SolarPosition object which describes the date, time, and latitude.	required
`extn`	`float`	Extinction coefficient for Beer's Law. Default is 0.5.	`0.5`

Returns:

Type	Description
`Irradiance`	Class containing the resulting relative irradiance for the terrain surface.

attenuate_all

attenuate_all(
    env: Environment,
    sol: SolarPosition,
    extn: float = 0.5,
    origin: tuple[float, float] = (0.0, 0.0),
) -> Irradiance

Produces a Irradiance object containing the relative irradiance for the canopy, and, if appropriate information was provided, the terrain and sensors.

Parameters:

Name	Type	Description	Default
`env`	`Environment`	Environment object which may or may not contain a Terrain object. If no Terrain object is provided, surface irradiance is still returned, but on a flat plane that is created below the leaf area.	required
`sol`	`SolarPosition`	SolarPosition object which describes the date, time, and latitude.	required
`extn`	`float`	Extinction coefficient for Beer's Law. Default is 0.5.	`0.5`
`origin`	`tuple[float, float]`	(x, y) world offset added to every coordinate before it is rotated for the shadow-bucketing sweep. The sweep floors rotated coordinates onto a 1x1 lattice, so the result depends on where the coordinates start; passing a shared `origin` anchors that lattice to a common global frame. This lets a sub-window of a larger domain reproduce a whole-domain run: give each window the offset of its lower-left corner in the global frame. Output coordinates are unchanged (they stay in the input's local frame); only the shadow grouping is re-anchored. Default is (0.0, 0.0), which reproduces the un-anchored result exactly. The offset is in the same index units as the input coordinates and is applied before the voxel-aspect scaling below.	`(0.0, 0.0)`

Returns:

Type	Description
`Irradiance`	Class containing the resulting relative irradiance for the canopy, the terrain (if provided), and the sensors (if provided).

Notes

Shadows are cast at the physical solar angle for the voxel dimensions given in env.voxel_dim. Coordinates are grid indices, so a non-cubic voxel (e.g. a canopy 2 m wide but 1 m tall) is stretched to physical proportions before the shadow sweep; without voxel dimensions (or with a cubic voxel) coordinates are used as-is. When the horizontal resolutions differ (dx != dy) the shadow angle is still physical, but the sweep's cell buckets are no longer square.

plot_irradiance

plot_irradiance(
    irr: Irradiance,
    terrain_coords: Terrain = None,
    show_solar_vector: bool = False,
    show_sensors=False,
    show_axes: bool = False,
    show_canopy=True,
)

Uses pyvista to plot the irradiance results, optionally showing the solar direction vector, sensors (if available), and axes. The optional parameters can be helpful for debugging. Canopy can optionally be omitted.

Parameters:

Name	Type	Description	Default
`irr`	`Irradiance`	Object of type Irradiance that has been returned from `attenuate_all` or `attenuate_surface`	required
`terrain_coords`	`Terrain`	(optional) Object of type Terrain. This is used to plot the z values of the terrain. Default is None but is required if you provided a `Irradiance` with terrain.	`None`
`show_solar_vector`	`bool`	(optional) Bool indicating if an arrow in the direction of the solar vector will be drawn. Default is False.	`False`
`show_sensors`		(optional) Bool indicating whether sensors, if they exist, will be shown. Default is False.	`False`
`show_axes`	`bool`	(optional) Bool indicating whether axes should be drawn. Default is False.	`False`
`show_canopy`		(optional) Bool indicating whether, when terrain is present, canopy should also be plotted. Can be useful for visualizing terrain by itself. Default is True.	`True`

Reference

LeafArea

__init__

from_uniformgrid classmethod

Terrain

__init__

LeafAngle

__init__

from_uniformgrid classmethod

Environment

__init__

Sensor

__init__

SolarPosition

__init__

Irradiance

get_sensor_irradiance

to_srad

to_par

attenuate_surface

attenuate_all

plot_irradiance

init

from_uniformgrid `classmethod`

init

init

from_uniformgrid `classmethod`

init

init

init