solar module

Module: solar

Description

Solar geometry and time-conversion utilities for PyPacity ampacity calculations. Provides methods for computing extraterrestrial radiation, solar declination, hour angle, solar azimuth, and the conversions between standard clock time and solar time. Designed to support the solar heat-gain calculations required by CIGRE TB 601 and CIGRE TB 207 overhead line ampacity models.

Copyright

Copyright (c) 2026 Group of Advanced Electro-Technologies (GTEA). Universidad de Cantabria. All rights reserved.

License

SPDX-License-Identifier: GPL-3.0-only

Notes

This module is part of the PyPacity project.

References

• CIGRE Technical Brochure 601, Guide for Thermal Rating Calculations of Overhead Lines

• CIGRE Technical Brochure 207, Thermal Rating of Overhead Lines

• 10. 1. Duffie and W. A. Beckman, Solar Engineering of Thermal Processes, Wiley

class pypacity.utils.solar.SolarGeometry(Location='Santander', Country='Spain', Latitude=43.46, Longitude=-3.8)

Bases: object

Solar geometry and time-conversion toolkit.

Computes solar declination, hour angle, azimuth, extraterrestrial radiation, and standard-to-solar time conversions. Accepts a geographic location at construction time and uses it in all subsequent method calls.

Attributes

Attribute	Type	Role	Description
Location	str	Parameter	Name of the location. Defaults to 'Santander'.
Country	str	Parameter	Country name. Used to determine the local daylight saving time offset. Defaults to 'Spain'.
Lat	float	Parameter	Geographic latitude in degrees (constructor parameter Latitude). Defaults to 43.46.
Lon	float	Parameter	Geographic longitude in degrees (constructor parameter Longitude). Defaults to -3.8.
version	str	Variable	Module version string.
vdate	str	Variable	Release date of the current version.
Gsc	float	Variable	Solar constant in W/m² (1367.0 W/m²).
SolarDistance	float	Variable	Mean Sun–Earth distance in meters (1.495×10¹¹ m).
EarthDiameter	float	Variable	Earth diameter in meters (1.27×10⁷ m).
SunDiameter	float	Variable	Sun diameter in meters (1.39×10⁹ m).

Gon(day)

Compute the extraterrestrial solar radiation for a given day of the year.

Parameters:

day (int) – Day of the year in the range [1, 365].

Returns:

Extraterrestrial radiation in W/m².

Return type:

float

DayOfYear(day, month)

Compute the day of the year from the day of the month and the month.

Parameters:

• day (int) – Day of the month in the range [1, 31].

• month (int) – Month of the year in the range [1, 12].

Returns:

Day of the year in the range [1, 365].

Return type:

int

Note

Uses a fixed monthly offset table and does not apply a leap-year correction. For leap-year-aware computation from a datetime.datetime object use DatetimetoDayOfYear().

Declination(day)

Compute the solar declination for a given day of the year.

Parameters:

day (int) – Day of the year in the range [1, 365].

Returns:

Solar declination in degrees.

Return type:

float

LongStd()

Compute the standard meridian nearest to Lon (ceiling to the next multiple of 15°).

Returns:

Standard meridian longitude in degrees (multiple of 15).

Return type:

int

ET(dayofyear)

Compute the equation of time — the difference between solar and sidereal time.

Parameters:

dayofyear (int) – Day of the year in the range [1, 365].

Returns:

Equation of time in minutes.

Return type:

float

HMtoStandardTime(day, month, hour, minutes)

Convert a clock time to standard time in minutes past midnight.

Applies a daylight saving time correction when applicable for the configured country.

Parameters:

• day (int) – Day of the month in the range [1, 31].

• month (int) – Month of the year in the range [1, 12].

• hour (int) – Hour of the day in the range [0, 23].

• minutes (int) – Minutes of the hour in the range [0, 59].

Returns:

Standard time in minutes past midnight.

Return type:

int

StandardTimetoSolarTime(day, month, hour, minutes)

Convert standard clock time to solar time in minutes past midnight.

Parameters:

• day (int) – Day of the month in the range [1, 31].

• month (int) – Month of the year in the range [1, 12].

• hour (int) – Hour in standard time in the range [0, 23].

• minutes (int) – Minutes in standard time in the range [0, 59].

Returns:

Solar time in minutes past midnight.

Return type:

float

SolarTimetoStandardTime(day, month, solartime)

Convert solar time to standard time in minutes past midnight.

Parameters:

• day (int) – Day of the month in the range [1, 31].

• month (int) – Month of the year in the range [1, 12].

• solartime (float) – Solar time in minutes past midnight.

Returns:

Standard time in minutes past midnight.

Return type:

float

SolarTimetoHourAngle(SolarTime)

Convert solar time to the hour angle omega.

Parameters:

SolarTime (float) – Solar time in minutes past midnight.

Returns:

Hour angle omega in degrees (negative before solar noon, positive after).

Return type:

float

StandardTimetoHM(standardtime, day, month)

Convert standard time in minutes to a [hour, minutes] list.

Applies a daylight saving time correction when applicable for the configured country.

Parameters:

• standardtime (float) – Standard time in minutes past midnight.

• day (int) – Day of the month in the range [1, 31].

• month (int) – Month of the year in the range [1, 12].

Returns:

Two-element list [hour, minutes] in official local time.

Return type:

list

HourAngletoSolarTime(HourAngle)

Convert the hour angle to solar time in minutes past midnight.

Parameters:

HourAngle (float) – Hour angle in degrees.

Returns:

Solar time in minutes past midnight.

Return type:

float

Theta(day, month, hour, minutes, Azimuth, beta)

Compute the angle of incidence of solar radiation on a tilted surface.

Parameters:

• day (int) – Day of the month in the range [1, 31].

• month (int) – Month of the year in the range [1, 12].

• hour (int) – Solar time hour in the range [0, 23].

• minutes (int) – Solar time minutes in the range [0, 59].

• Azimuth (float) – Surface azimuth angle in degrees.

• beta (float) – Surface tilt angle from the horizontal in degrees.

Returns:

Angle of incidence theta in degrees.

Return type:

float

Azimuth(day, month, hour, minutes)

Compute the solar azimuth angle.

Parameters:

• day (int) – Day of the month in the range [1, 31].

• month (int) – Month of the year in the range [1, 12].

• hour (int) – Solar time hour in the range [0, 23].

• minutes (int) – Solar time minutes in the range [0, 59].

Returns:

Solar azimuth angle in degrees.

Return type:

float

SunsetHourAngle(declination)

Compute the sunset hour angle in degrees.

Parameters:

declination (float) – Solar declination in degrees.

Returns:

Sunset hour angle in degrees.

Return type:

float

GetLocation()

Return the location name.

Returns:

Location name.

Return type:

str

GetLatitude()

Return the latitude in degrees.

Returns:

Latitude in degrees.

Return type:

float

GetLongitude()

Return the longitude in degrees.

Returns:

Longitude in degrees.

Return type:

float

print_ver()

Print and return the module name, version, and last update date.

Returns:

Module name, version, and last update date.

Return type:

str

DatetimetoDayOfYearNative(dt)

Compute the day of the year from a datetime object using Python’s built-in calendar.

Delegates to datetime.datetime.timetuple() so leap years are handled automatically.

Parameters:

dt (datetime.datetime) – Date and time.

Returns:

Day of the year in the range [1, 365/366].

Return type:

int

DatetimetoSolarTime(dt)

Compute the solar time in minutes from a datetime object.

Parameters:

dt (datetime.datetime) – Date and time in official local time.

Returns:

Solar time in minutes past midnight.

Return type:

float

DatetimetoSolarHour(dt)

Compute the solar time in decimal hours from a datetime object.

Parameters:

dt (datetime.datetime) – Date and time in official local time.

Returns:

Solar time in decimal hours in the range [0, 24).

Return type:

float

DatetimetoDayOfYear(dt)

Compute the day of the year from a datetime object using an explicit offset table.

Uses a monthly offset table with an explicit Gregorian leap-year correction. See also DatetimetoDayOfYearNative() for an equivalent implementation that delegates to Python’s built-in calendar.

Parameters:

dt (datetime.datetime) – Date and time.

Returns:

Day of the year in the range [1, 365/366].

Return type:

int