grid_process.sun#

Module to wrap some sun position utility functions

Attributes#

logger

Functions#

`zenith`(→ xarray.DataArray)	Analytical expression of solar zenith angle based on spherical
`cos_zenith`(→ xarray.DataArray)	Compute the cosine of the solar zenith angle. Atmospheric refraction is NOT
`params_zenith`(→ tuple[xarray.DataArray, ...)	get the different parameters to compute zenith angle
`hour_angle`(→ xarray.DataArray)	Hour angle [radians] in local solar time. Zero at local solar noon.
`elevation`(→ xarray.DataArray)	Analytical expression of solar elevation angle based on spherical
`azim_elev`(→ tuple[xarray.DataArray, xarray.DataArray])	Analytical expression of solar azimuth and elevation angles based on spherical
`rise_set`(→ tuple[xarray.DataArray, xarray.DataArray])	Geometric calculation of solar sunrise and sunset times
`daytime`(→ xarray.DataArray)	Return a boolean xarray.DataArray specifying whether times are daytime for
`topo_rise_set`(→ xarray.Dataset)	Computes topographic sunrise and sunset based on horizon data. Sunrise / sunset
`topo_shading_cor`(→ xarray.DataArray)	Computes topographic shading correction factor for variables

Module Contents#

logger#

zenith(times: xarray.DataArray, lat: xarray.DataArray, lon: xarray.DataArray, refrac_cor: bool = True) → xarray.DataArray[source]#

Analytical expression of solar zenith angle based on spherical trigonometry.

Parameters:

times (xarray.DataArray, 1D) – contains timestamps to be checked in UTC
lat (xarray.DataArray 1D or 2D) – contains latitudes of the points to be checked
lon (xarray.DataArray 1D or 2D) – contains longitudes of the points to be checked
refrac_cor (bool) – whether to account for atmospheric refraction. It is significant only when the sun is close to horizon, in which case atmospheric refraction correction is about 0.6 [degrees]. Default is True

Returns:

zen – zenith in [degrees] for each time/point couple

Return type:

xarray.DataArray 2D or 3D

References

J. A. Duffie and W. A. Beckman, “Solar Engineering of Thermal Processes, 3rd Edition” pp. 14, J. Wiley and Sons, New York (2006)
J. H. Seinfeld and S. N. Pandis, “Atmospheric Chemistry and Physics” p. 132, J. Wiley (1998)
Daryl R. Myers, “Solar Radiation: Practical Modeling for Renewable Energy Applications”, p. 5 CRC Press (2013)
Wikipedia: Solar Zenith Angle
PVCDROM: Sun’s Position

See also

azim_elev(), elevation()

cos_zenith(times: xarray.DataArray, lat: xarray.DataArray, lon: xarray.DataArray) → xarray.DataArray[source]#: Compute the cosine of the solar zenith angle. Atmospheric refraction is NOT considered

params_zenith(times: xarray.DataArray, lat: xarray.DataArray, lon: xarray.DataArray) → tuple[xarray.DataArray, xarray.DataArray, xarray.DataArray][source]#: get the different parameters to compute zenith angle

hour_angle(times: xarray.DataArray, lon: xarray.DataArray) → xarray.DataArray[source]#

Hour angle [radians] in local solar time. Zero at local solar noon.

Parameters:

times (xarray.DataArray, 1D) – contains timestamps in UTC for which to calculate the hour angle
lon (xarray.DataArray 1D or 2D) – contains longitudes of the points to be checked

elevation(times: xarray.DataArray, lat: xarray.DataArray, lon: xarray.DataArray, refrac_cor: bool = True) → xarray.DataArray[source]#

Analytical expression of solar elevation angle based on spherical trigonometry

Parameters:

times (xarray.DataArray, 1D) – contains timestamps to be checked in UTC
lat (xarray.DataArray 1D or 2D) – contains latitudes of the points to be checked
lon (xarray.DataArray 1D or 2D) – contains longitudes of the points to be checked
refrac_cor (bool) – whether to account for atmospheric refraction. It is significant only when the sun is close to horizon, in which case atmospheric refraction correction is about 0.6 [degrees]. Default is True

Returns:

elev – elevation in [degrees] for each time/point couple

Return type:

xarray.DataArray 2D or 3D

See also

azim_elev(), zenith()

azim_elev(times: xarray.DataArray, lat: xarray.DataArray, lon: xarray.DataArray, refrac_cor: bool = True) → tuple[xarray.DataArray, xarray.DataArray][source]#

Analytical expression of solar azimuth and elevation angles based on spherical trigonometry

Parameters:

times (xarray.DataArray, 1D) – contains timestamps to be checked in UTC
lat (xarray.DataArray 1D or 2D) – contains latitudes of the points to be checked
lon (xarray.DataArray 1D or 2D) – contains longitudes of the points to be checked
refrac_cor (bool) – whether to account for atmospheric refraction. It is significant only when the sun is close to horizon, in which case atmospheric refraction correction is about 0.6 [degrees]. Default is True

Returns:

azim (xarray.DataArray 2D or 3D) – azimuth in [degrees] for each time/point couple
elev (xarray.DataArray 2D or 3D) – elevation in [degrees] for each time/point couple

References

J. A. Duffie and W. A. Beckman, “Solar Engineering of Thermal Processes, 3rd Edition” pp. 14, J. Wiley and Sons, New York (2006)
J. H. Seinfeld and S. N. Pandis, “Atmospheric Chemistry and Physics” p. 132, J. Wiley (1998)
Wikipedia: Solar Azimuth Angle
PVCDROM: Azimuth Angle

See also

elevation(), zenith()

rise_set(times: xarray.DataArray, lat: xarray.DataArray, lon: xarray.DataArray, refrac_cor: bool = True) → tuple[xarray.DataArray, xarray.DataArray][source]#

Geometric calculation of solar sunrise and sunset times

Warning

The geometric calculation assumes a circular earth orbit with the sun as a point source at its center, and neglects the effect of atmospheric refraction on zenith. The error depends on location and time of year but is of order 10 minutes.

Parameters:

times (xarray.DataArray, 1D) – contains timestamps to be checked in UTC
lat (xarray.DataArray 1D or 2D) – contains latitudes of the points to be checked
lon (xarray.DataArray 1D or 2D) – contains longitudes of the points to be checked
refrac_cor (bool) – whether to account for atmospheric refraction. When true, the sunrise / sunset occurs about 4 minutes earlier / later. Default is True

Returns:

sunrise (xarray.DataArray 2D or 3D) – sunrise times for each time/point couple in UTC
sunset (xarray.DataArray 2D or 3D) – sunset times for each time/point couple in UTC

References

J. A. Duffie and W. A. Beckman, “Solar Engineering of Thermal Processes, 3rd Edition,” J. Wiley and Sons, New York (2006)
Frank Vignola et al., “Solar And Infrared Radiation Measurements,” CRC Press (2012)

daytime(times: xarray.DataArray, lat: xarray.DataArray, lon: xarray.DataArray, refrac_cor: bool = True) → xarray.DataArray[source]#

Return a boolean xarray.DataArray specifying whether times are daytime for each point defined by the lat and lon arrays. Daytime is defined here as the center of the sun being above the non-topographic flat horizon (i.e. sun elevation > 0)

Parameters:

times (xarray.DataArray, 1D) – contains timestamps to be checked in UTC
lat (xarray.DataArray 1D or 2D) – contains latitudes of the points to be checked
lon (xarray.DataArray 1D or 2D) – contains longitudes of the points to be checked
refrac_cor (bool) – whether to account for atmospheric refraction. When true, the sunrise / sunset occurs about 4 minutes earlier / later. Default is True

Returns:

da_out – indicates for each time/point couple whether it is daytime

Return type:

xarray.DataArray of bool

See also

rise_set()

topo_rise_set(times: xarray.DataArray, lat: xarray.DataArray, lon: xarray.DataArray, horizon: xarray.DataArray) → xarray.Dataset[source]#

Computes topographic sunrise and sunset based on horizon data. Sunrise / sunset is defined as the first / last time the sun path cross the horizon line

Parameters:

times (xarray.DataArray, 1D) – contains timestamps to be checked in UTC. Must be regularly sampled and cover full daytime periods
lat (xarray.DataArray 1D or 2D) – contains latitudes of the points to be checked
lon (xarray.DataArray 1D or 2D) – contains longitudes of the points to be checked
horizon (xarray.DataArray 2D or 3D) – topographic horizon in [degrees] of the points to be checked, regularly sampled along a dimension azimuth

Returns:

ds – contains topographic sunrise and sunset in UTC for each point and day of year in input times

Return type:

xarray.Dataset 2D or 3D

Note

The higher is the time frequency of times, the more accurate will be the sunrise and sunset times as it is interpolated between the two time points when the sun cross the topographic horizon.

topo_shading_cor(times: xarray.DataArray, lat: xarray.DataArray, lon: xarray.DataArray, horizon: xarray.DataArray, sampling_freq: str = '10min') → xarray.DataArray[source]#

Computes topographic shading correction factor for variables

Parameters:

times (xarray.DataArray, 1D) – contains timestamps for which correction factor are computed. Must have constant time granularity and be in UTC
lat (xarray.DataArray 1D or 2D) – contains latitudes of the points to be checked
lon (xarray.DataArray 1D or 2D) – contains longitudes of the points to be checked
horizon (xarray.DataArray 2D or 3D) – topographic horizon in [degrees] of the points to be checked, regularly sampled along a dimension azimuth
sampling_freq (frequency string as accepted by pandas date functionalities) – time frequency to compare sun elevation with topographic horizon. The higher the more precise will be the correction factors but at the cost of longer computation time. Should be at least higher than the frequency of the input times array

Returns:

da_out – contains topographic correction factors for each timestamps in input arg times

Return type:

xarray.DataArray 2D or 3D