improver.utilities.solar module

Utilities to find the relative position of the sun.

class DayNightMask[source]

Bases: BasePlugin

Plugin Class to generate a daynight mask for the provided cube

__init__()[source]: Initial the DayNightMask Object

_abc_impl = <_abc_data object>

_create_daynight_mask(cube)[source]

Create blank daynight mask cube

Parameters:: cube (Cube) – cube with the times and coordinates required for mask
Return type:: Cube
Returns:: Blank daynight mask cube. The resulting cube will be the same shape as the time, y, and x coordinate, other coordinates will be ignored although they might appear as attributes on the cube as it is extracted from the first slice.

_daynight_lat_lon_cube(mask_cube, day_of_year, utc_hour)[source]

Calculate the daynight mask for the provided Lat Lon cube

Parameters:

mask_cube (Cube) – daynight mask cube - data initially set to self.night
day_of_year (int) – day of the year 0 to 365, 0 = 1st January
utc_hour (float) – Hour in UTC

Return type:

Cube

Returns:

daynight mask cube - daytime set to self.day

process(cube)[source]

Calculate the daynight mask for the provided cube. Note that only the hours and minutes of the dtval variable are used. To ensure consistent behaviour with changes of second or subsecond precision, the second component is added to the time object. This means that when the hours and minutes are used, we have correctly rounded to the nearest minute, e.g.:

dt(2017, 1, 1, 11, 59, 59) -- +59 --> dt(2017, 1, 1, 12, 0, 58)
dt(2017, 1, 1, 12, 0, 1)   -- +1  --> dt(2017, 1, 1, 12, 0, 2)
dt(2017, 1, 1, 12, 0, 30)  -- +30 --> dt(2017, 1, 1, 12, 1, 0)

If the cube’s time coordinate has time bounds the mid-point of these bounds rather than the time point is used in the calculation. This ensures that should a majority of the period described fall into daylight hours, the data is not classified as falling at night. This is an issue as the time point is always located at the end of the time bounds. Without this approach weather symbols representing e.g. 20-21Z will be marked as night symbols should the sun set at 20:59, which is not suitable.

Parameters:: cube (Cube) – input cube
Return type:: Cube
Returns:: daynight mask cube, daytime set to self.day nighttime set to self.night. The resulting cube will be the same shape as the time, y, and x coordinate, other coordinates will be ignored although they might appear as attributes on the cube as it is extracted from the first slice.

calc_solar_declination(day_of_year)[source]

Calculate the Declination for the day of the year.

Calculation equivalent to the calculation defined in NOAA Earth System Research Lab Low Accuracy Equations https://www.esrl.noaa.gov/gmd/grad/solcalc/sollinks.html

Parameters:: day_of_year (int) – Day of the year 0 to 365, 0 = 1st January
Return type:: float
Returns:: Declination in degrees.North-South

calc_solar_elevation(latitudes, longitudes, day_of_year, utc_hour, return_sine=False)[source]

Calculate the Solar elevation.

Parameters:

latitudes (Union[float, ndarray]) – A single Latitude or array of Latitudes latitudes needs to be between -90.0 and 90.0
longitudes (Union[float, ndarray]) – A single Longitude or array of Longitudes longitudes needs to be between 180.0 and -180.0
day_of_year (int) – Day of the year 0 to 365, 0 = 1st January
utc_hour (float) – Hour of the day in UTC in hours
return_sine (bool) – If True return sine of solar elevation. Default False.

Return type:

Union[float, ndarray]

Returns:

Solar elevation in degrees for each location.

calc_solar_hour_angle(longitudes, day_of_year, utc_hour)[source]

Calculate the Solar Hour angle from the Local Solar Time.

Parameters:

longitudes (Union[float, ndarray]) – A single Longitude or array of Longitudes longitudes needs to be between 180.0 and -180.0 degrees
day_of_year (int) – Day of the year 0 to 365, 0 = 1st January
utc_hour (float) – Hour of the day in UTC

Return type:

Union[float, ndarray]

Returns:

Hour angles in degrees East-West.

calc_solar_time(longitudes, day_of_year, utc_hour, normalise=False)[source]

Calculate the Local Solar Time for each element of an array of longitudes.

Calculation equivalent to the calculation defined in NOAA Earth System Research Lab Low Accuracy Equations https://www.esrl.noaa.gov/gmd/grad/solcalc/sollinks.html

Parameters:

longitudes (Union[float, ndarray]) – A single Longitude or array of Longitudes longitudes needs to be between 180.0 and -180.0 degrees
day_of_year (int) – Day of the year 0 to 365, 0 = 1st January
utc_hour (float) – Hour of the day in UTC
normalise – Normalise hour values to be in range 0-24

Return type:

Union[float, ndarray]

Returns:

Local solar time in hours.

daynight_terminator(longitudes, day_of_year, utc_hour)[source]

Calculate the Latitude values of the daynight terminator for the given longitudes.

Parameters:

longitudes (ndarray) – Array of longitudes. longitudes needs to be between 180.0 and -180.0 degrees
day_of_year (int) – Day of the year 0 to 365, 0 = 1st January
utc_hour (float) – Hour of the day in UTC

Return type:

ndarray

Returns:

latitudes of the daynight terminator

get_day_of_year(time)[source]

Get day of the year from given datetime, starting at 0 for 1st Jan.

Parameters:: time (datetime) – Datetime from which to extract day-of-year.
Return type:: int
Returns:: The day of year corresponding to the specified datetime.

get_hour_of_day(time)[source]

Get the hour of day from datetime, with the minute values included as a fraction of the hour, and seconds rounded to the nearest minute.

Where rounding seconds moves the datetime into the following day, the hour_of_day returned is 24.0 rather than 0.0 to ensure the hour_of_day is consistent with the day_of_year value associated with datetime.

Parameters:: time (datetime) – Datetime from which to extract utc-hour.
Return type:: float
Returns:: The utc hour corresponding to the specified datetime. Minute values are expressed as fraction of an hour.