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
)

Initializes LeafArea object from a given point cloud.

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)

Constructor for Terrain class object.

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.

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.
`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,
    sensors: list[Sensor] = None,
)

Constructor for Environment object.

Parameters:

Name	Type	Description	Default
`leaf_area`	`LeafArea`	A LeafArea class object.	required
`terrain`	`Terrain`	(optional) A Terrain class object. 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,
)

Constructor for Sensor object. If pitch and azimuth are provided, the returned irradiance will be corrected for the tilt of the sensor relative to the SolarPosition 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
)

Constructor for SolarPosition class.

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
) -> 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`

Returns:

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

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__

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

init

init