solar package

Submodules

solar.solar module

Module contents

class solar.Angular(radians: float = nan, degrees: float = nan)[source]

Bases: object

This class combines a numeric value with an angular measurement unit.

Proper construction should call constructor with either radians=x or degrees=y; not both. The constructor will calculate the complementary. The value of the angle can then be retrieved from the .degrees or .radians value as needed.

Another class member, called .valued is available to determine if the class members contain meaningful values.

If the constructor is called without either argument, the .valued variable is False, and the numeric vars are None.

If the constructor is called with both arguments, they will be assigned if they agree to within a small tolerance; otherwise a ValueError is thrown.

degrees() → float[source]
radians() → float[source]
solar.altitude_angle(time_stamp: datetime, daylight_savings_on: bool, longitude: Angular, standard_meridian: Angular, latitude: Angular) → Angular[source]

Calculates the current solar altitude angle for a given set of time and location conditions. The solar altitude angle is the angle between the sun rays and the horizontal plane.

Parameters:

  • time_stamp – The current date and time to be used in this calculation of day of year.

  • daylight_savings_on – A flag if the current time is a daylight savings number. If True, the hour is decremented.

  • longitude – [degrees west] The current longitude in degrees west of the prime meridian. For Golden, CO, the variable should be = 105.2.

  • standard_meridian – [west] The local standard meridian for the location, west of the prime meridian. For Golden, CO, the variable should be = 105 degrees.

  • latitude – [north] The local latitude for the location, north of the equator. For Golden, CO, the variable should be = 39.75 degrees.

Returns:

[Angular] The solar altitude angle in an Angular with both radian and degree versions

solar.azimuth_angle(time_stamp: datetime, daylight_savings_on: bool, longitude: Angular, standard_meridian: Angular, latitude: Angular) → Angular[source]

Calculates the current solar azimuth angle for a given set of time and location conditions. The solar azimuth angle is the angle in the horizontal plane between due north and the sun. It is measured clockwise, so that east is +90 degrees and west is +270 degrees. Throws if the angle cannot be calculated because the sun is down

Parameters:

  • time_stamp – The current date and time to be used in this calculation of day of year.

  • daylight_savings_on – A flag if the current time is a daylight savings number. If True, the hour is decremented.

  • longitude – [west] The current longitude west of the prime meridian. For Golden, CO, the variable should be = 105.2 degrees.

  • standard_meridian – [west] The local standard meridian for the location, west of the prime meridian. For Golden, CO, the variable should be = 105 degrees.

  • latitude – [north] The local latitude for the location, north of the equator. For Golden, CO, the variable should be = 39.75 degrees.

Returns:

[Angular] The solar azimuth angle in an Angular with both radian and degree versions.

solar.day_of_year(time_stamp: datetime) → int[source]

Calculates the day of year (1-366) given a Python datetime.datetime instance. Basically a wrapper to ensure it is a full datetime instance . in subsequent calculations. If the type is not datetime.datetime, this will throw a TypeError.

Parameters:

time_stamp – The current date and time to be used in calculating day of year

Returns:

[dimensionless] The day of year, from 1 to 365 for non-leap years and 1-366 for leap years.

solar.declination_angle(time_stamp: datetime) → Angular[source]

Calculates the Solar Declination Angle for a given date. The solar declination angle is the angle between a line connecting the center of the sun and earth and the projection of that line on the equatorial plane. Calculation is based on McQuiston.

Parameters:

time_stamp – The current date and time to be used in this calculation of day of year.

Returns:

The solar declination angle in an Angular with both radian and degree versions

solar.direct_radiation_on_surface(time_stamp: datetime, daylight_savings_on: bool, longitude: Angular, standard_meridian: Angular, latitude: Angular, surface_azimuth: Angular, horizontal_direct_irradiation: float) → float[source]

Calculates the amount of direct solar radiation incident on a surface for a set of time and location conditions, a surface orientation, and a total global horizontal direct irradiation. This is merely the global horizontal direct solar irradiation times the angle of incidence on the surface.

Parameters:

  • time_stamp – The current date and time to be used in this calculation of day of year.

  • daylight_savings_on – A flag if the current time is a daylight savings number. If True, the hour is decremented.

  • longitude – [west] The current longitude west of the prime meridian. For Golden, CO, the variable should be = 105.2 degrees.

  • standard_meridian – [west] The local standard meridian for the location, west of the prime meridian. For Golden, CO, the variable should be = 105 degrees.

  • latitude – [north] The local latitude for the location, north of the equator. For Golden, CO, the variable should be = 39.75 degrees.

  • surface_azimuth – [CW from North] The angle between north and the outward facing normal vector of the wall, measured as positive clockwise from south (southwest facing surface: 225 degrees, northwest facing surface: 315 degrees)

  • horizontal_direct_irradiation – The global horizontal direct irradiation at the location, in any units

Returns:

The incident direct radiation on the surface. The units of this return value match the units of the parameter :horizontal_direct_irradiation:

solar.equation_of_time(time_stamp: datetime) → float[source]

Calculates the Equation of Time for a given date. I wasn’t able to get the McQuiston equation to match the values in the given table. I ended up using a different formulation here: http://holbert.faculty.asu.edu/eee463/SolarCalcs.pdf.

Parameters:

time_stamp – The current date and time to be used in this calculation of day of year.

Returns:

The equation of time, which is the difference between local civil time and local solar time

solar.hour_angle(time_stamp: datetime, daylight_savings_on: bool, longitude: Angular, standard_meridian: Angular) → Angular[source]

Calculates the current hour angle for a given set of time and location conditions. The hour angle is the angle between solar noon and the current solar angle, so at local solar noon the value is zero, in the morning it is below zero, and in the afternoon it is positive.

Parameters:

  • time_stamp – The current date and time to be used in this calculation of day of year.

  • daylight_savings_on – A flag if the current time is a daylight savings number. If True, the hour is decremented.

  • longitude – [west] The current longitude west of the prime meridian. For Golden, CO, the variable should be = 105.2 degrees.

  • standard_meridian – [west] The local standard meridian for the location, west of the prime meridian. For Golden, CO, the variable should be = 105 degrees.

Returns:

The hour angle in an Angular with both radian and degree versions

solar.local_civil_time(time_stamp: datetime, daylight_savings_on: bool, longitude: Angular, standard_meridian: Angular) → float[source]

Calculates the local civil time for a given set of time and location conditions. The local civil time is the local time based on prime meridian and longitude.

Parameters:

  • time_stamp – The current date and time to be used in this calculation of day of year.

  • daylight_savings_on – A flag if the current time is a daylight savings number. If True, the hour is decremented.

  • longitude – [west] The current longitude, west of the prime meridian. For Golden, CO, the variable should be = 105.2 degrees.

  • standard_meridian – [west] The local standard meridian for the location, west of the prime meridian. For Golden, CO, the variable should be = 105 degrees.

Returns:

[hours] Returns the local civil time in hours for the given date/time/location

solar.local_solar_time(time_stamp: datetime, daylight_savings_on: bool, longitude: Angular, standard_meridian: Angular) → float[source]

Calculates the local solar time for a given set of time and location conditions. The local solar time is the local civil time that has been corrected by the equation of time.

Parameters:

  • time_stamp – The current date and time to be used in this calculation of day of year.

  • daylight_savings_on – A flag if the current time is a daylight savings number. If True, the hour is decremented.

  • longitude – [west] The current longitude, west of the prime meridian. For Golden, CO, the variable should be = 105.2 degrees.

  • standard_meridian – [west] The local standard meridian for the location, west of the prime meridian. For Golden, CO, the variable should be = 105 degrees.

Returns:

[hours] Returns the local solar time in hours for the given date/time/location

solar.solar_angle_of_incidence(time_stamp: datetime, daylight_savings_on: bool, longitude: Angular, standard_meridian: Angular, latitude: Angular, surface_azimuth: Angular) → Angular[source]

Calculates the solar angle of incidence for a given set of time and location conditions, and a surface orientation. The solar angle of incidence is the angle between the solar ray vector incident on the surface, and the outward facing surface normal vector. Throws if the wall azimuth cannot be calculated

Parameters:

  • time_stamp – The current date and time to be used in this calculation of day of year.

  • daylight_savings_on – A flag if the current time is a daylight savings number. If True, the hour is decremented.

  • longitude – [west] The current longitude west of the prime meridian. For Golden, CO, the variable should be = 105.2 degrees.

  • standard_meridian – [west] The local standard meridian for the location, west of the prime meridian. For Golden, CO, the variable should be = 105 degrees.

  • latitude – [north] The local latitude for the location, north of the equator. For Golden, CO, the variable should be = 39.75 degrees.

  • surface_azimuth – [CW from North] The angle between north and the outward facing normal vector of the wall, measured as positive clockwise from south (southwest facing surface: 225 degrees, northwest facing surface: 315 degrees)

Returns:

[Angular] The solar angle of incidence in an Angular with both radian & degree versions.

solar.wall_azimuth_angle(time_stamp: datetime, daylight_savings_on: bool, longitude: Angular, standard_meridian: Angular, latitude: Angular, surface_azimuth: Angular) → Angular[source]

Calculates the current wall azimuth angle for a given set of time/location conditions, and a surface orientation. The wall azimuth angle is the angle in the horizontal plane between the solar azimuth and the vertical wall’s outward facing normal vector. Throws if the sun is behind the surface or the sun is down.

Parameters:

  • time_stamp – The current date and time to be used in this calculation of day of year.

  • daylight_savings_on – A flag if the current time is a daylight savings number. If True, the hour is decremented.

  • longitude – [west] The current longitude west of the prime meridian. For Golden, CO, the variable should be = 105.2 degrees.

  • standard_meridian – [west] The local standard meridian for the location, west of the prime meridian. For Golden, CO, the variable should be = 105 degrees.

  • latitude – [north] The local latitude for the location, north of the equator. For Golden, CO, the variable should be = 39.75 degrees.

  • surface_azimuth – [CW from North] The angle between north and the outward facing normal vector of the wall, measured as positive clockwise from south (southwest facing surface: 225 degrees, northwest facing surface: 315 degrees)

Returns:

[Angular] The wall azimuth angle in an Angular with both radian and degree versions.