Geo Class: Solar Geometry and Clear-Sky GHI API Ref

The Geo class (in helpers/Geo.py) accepts a pandas DatetimeIndex and site coordinates, then populates a DataFrame with all relevant solar geometry columns needed for quality control and clear-sky modelling. Every column is computed in a single constructor pass — no further method calls are required to access the results.

Constructor

Geo(range_dates, lat, long, gmt, alt, beta)

Parameters

range_dates

pd.DatetimeIndex

required

Date range for which to compute geometry. Typically generated with pd.date_range(start=..., end=..., freq=...).

lat

float

required

Site latitude in decimal degrees. Negative values indicate the Southern Hemisphere (e.g. -22.1 for north-western Argentina).

long

float

required

Site longitude in decimal degrees. Negative values indicate west of the Prime Meridian.

gmt

int

required

UTC offset of the site (e.g. 0 for UTC, -3 for Argentina standard time). The constructor uses the sign of gmt internally when computing the longitude correction for solar hour.

alt

float

required

Site altitude in metres above sea level. Used for the air-mass pressure correction in Mak and for selecting the ktrp branch in getKtrp.

beta

float

required

Panel tilt angle in degrees. Pass 0 for a horizontal surface (GHI geometry). This parameter is stored but not used in any active computation in the current version.

Returns

An instance whose .df attribute is a pd.DataFrame containing all computed columns described below. The constructor also sets instance attributes self.ktrp and self.ktrp2.

Output DataFrame: `Geo.df`

Every row corresponds to one timestamp in range_dates. Columns are appended in the order listed.

Column	Type	Description
`date`	datetime	Input timestamp from `range_dates`
`N`	int	Day of year (1–366)
`M`	int	Month (1–12)
`Y`	int	Four-digit year
`E`	float	Equation of time in minutes
`HR`	float	Local clock hour as a decimal (e.g. `13.5` = 13:30)
`HS`	float	Solar hour, corrected for longitude and equation of time
`deltaRad`	float	Solar declination in radians
`delta`	float	Solar declination in degrees
`ws`	float	Sunset hour angle in radians: `arccos(−tan(δ)·tan(lat))`
`Fn`	float	Orbital distance correction factor (Fourier series)
`w`	float	Hour angle in degrees: `15 × (12 − HS)`
`wRad`	float	Hour angle in radians
`lat`	float	Site latitude (constant column, repeated for every row)
`CTZ`	float	`cos(θz)` — cosine of the solar zenith angle
`TZ`	float	Solar zenith angle `θz` in radians: `arccos(CTZ)`
`SZA`	float	Solar zenith angle in degrees
`alphaS`	float	Solar elevation angle in degrees: `arcsin(CTZ)` in degrees
`E0`	float	Orbital eccentricity correction factor
`TOA`	float	Top-of-atmosphere irradiance in W/m²; `0` when `CTZ < 0`
`Mak`	float	Kasten–Young air mass, pressure-corrected for site altitude
`GHIargp`	float	Clear-sky GHI from the ARGP model using `ktrp` (altitude-dependent, see `getKtrp`)
`GHIargp2`	float	Clear-sky GHI from the ARGP model using `ktrp2 = 0.649 + 0.02·alt^0.28`
`mr`	float	Pressure-corrected air mass using the Kasten formula with SZA in degrees

Instance Attributes

After construction, the following scalar attributes are available in addition to .df:

Attribute	Type	Description
`ktrp`	float	Clear-sky transmittance computed by `getKtrp()` (altitude-dependent)
`ktrp2`	float	Alternative transmittance: `0.649 + 0.02 × alt^0.28` (always applied, regardless of altitude)

Methods

All methods below are called internally by __init__; they are also available for standalone use.

`getKtrp()` — Altitude-dependent clear-sky transmittance

Geo.getKtrp() -> float

Returns the clear-sky transmittance coefficient ktrp used in the ARGP model. Two branches are applied based on site altitude:

Condition	Formula
`alt > 1000 m`	`ktrp = 0.7 + 1.6391×10⁻³ × alt^0.55`
`alt ≤ 1000 m`	`ktrp = 0.7570 + 1.0112×10⁻⁵ × alt^1.1067`

The result is stored as self.ktrp and used by generateGHIargp. Returns float — the transmittance coefficient.

`getE(n, y)` — Equation of time

Geo.getE(n: int, y: int) -> float

Computes the equation of time in minutes using a Fourier series over the day-angle γ = 2π(n−1)/365 (or /366 for leap years):

E = 229.18 × (0.000075 + 0.001868·cos(γ) − 0.032077·sin(γ)
            − 0.014615·cos(2γ) − 0.040890·sin(2γ))

Parameter	Type	Description
`n`	int	Day of year
`y`	int	Four-digit year (determines 365 or 366 denominator for leap years)

Returns float — equation of time in minutes.

`Fn(n, y)` — Orbital distance correction factor

Geo.Fn(n: int, y: int) -> float

Returns the orbital distance correction factor Fn using a Fourier series over the day-angle γ:

Fn = 1.000110 + 0.034221·cos(γ) + 0.001280·sin(γ)
             + 0.000719·cos(2γ) + 0.000077·sin(2γ)

Parameter	Type	Description
`n`	int	Day of year
`y`	int	Four-digit year (determines 365 or 366 denominator for leap years)

Returns float — dimensionless orbital correction factor.

`getHS()` — Solar hour

Geo.getHS() -> pd.Series

Computes the solar hour for every row in self.df using the equation of time and the longitude correction:

HS = HR + (4 × (A × 15 × gmt − A × long) + E) / 60

where A = 1 if gmt > 0, A = −1 if gmt ≤ 0. Takes no arguments; reads self.df['HR'], self.df['E'], self.long, and self.gmt directly. Returns pd.Series — solar hour values stored in self.df['HS'].

`delta(n, y)` — Solar declination

Geo.delta(n: int, y: int) -> float

Returns the solar declination in radians using a Fourier series approximation:

δ = 0.006918 − 0.399912·cos(γ) + 0.070257·sin(γ)
  − 0.006758·cos(2γ) + 0.000907·sin(2γ)
  − 0.002697·cos(3γ) + 0.001480·sin(3γ)

Parameter	Type	Description
`n`	int	Day of year
`y`	int	Four-digit year

Returns float — solar declination in radians.

`getCTZ(delta, omega)` — Cosine of solar zenith angle

Geo.getCTZ(delta: float, omega: float) -> float

Parameter	Type	Description
`delta`	float	Solar declination in radians
`omega`	float	Hour angle in radians

Returns float — CTZ = cos(lat)·cos(δ)·cos(ω) + sin(lat)·sin(δ).

`getWs(delta)` — Sunset hour angle

Geo.getWs(delta: float) -> float

Parameter	Type	Description
`delta`	float	Solar declination in radians

Returns float — sunset hour angle in radians: ws = arccos(−tan(δ)·tan(lat)).

`getE0(N, y)` — Orbital eccentricity correction

Geo.getE0(N: int, y: int) -> float

Parameter	Type	Description
`N`	int	Day of year
`y`	int	Four-digit year

Returns float — 1 + 0.033·cos(2π·N/365) (or /366 for leap years).

`TOA(E0, CTZ)` — Top-of-atmosphere irradiance

Geo.TOA(E0: float, CTZ: float) -> float

Parameter	Type	Description
`E0`	float	Orbital eccentricity correction factor
`CTZ`	float	Cosine of the solar zenith angle

Returns float — 0 when CTZ < 0 (sun below the horizon); otherwise 1361 × E0 × CTZ W/m².

`Mak(CTZ, TZ)` — Kasten–Young air mass (pressure-corrected)

Geo.Mak(CTZ: float, TZ: float) -> float

Applies the Kasten & Young (1989) formula corrected for site pressure:

P   = 101355 × (288.15 / (288.15 − 0.0065 × alt))^(−5.255877)
Amk = 1 / (CTZ + 0.15 × (93.885 − TZ)^(−1.253))
Mak = Amk × (P / 101355)

The TZ argument is the solar zenith angle in radians (as stored in self.df['TZ']). The formula’s 93.885 − TZ term uses the raw radian value numerically — this is consistent with the source code and with how the column is populated. Do not pass degrees.

Parameter	Type	Description
`CTZ`	float	Cosine of the solar zenith angle
`TZ`	float	Solar zenith angle in radians (from `math.acos(CTZ)`)

Returns float — pressure-corrected Kasten–Young air mass.

`generateGHIargp(TOA, AM)` — ARGP clear-sky model (ktrp)

Geo.generateGHIargp(TOA: float, AM: float) -> float

Computes clear-sky GHI using the ARGP (Argentine) model with the altitude-dependent ktrp:

GHI_argp = TOA × ktrp^(AM^0.678)

ktrp is set at construction time by getKtrp():

Condition	Formula
`alt > 1000 m`	`ktrp = 0.7 + 1.6391×10⁻³ × alt^0.55`
`alt ≤ 1000 m`	`ktrp = 0.7570 + 1.0112×10⁻⁵ × alt^1.1067`

Parameter	Type	Description
`TOA`	float	Top-of-atmosphere irradiance in W/m²
`AM`	float	Air mass (from `Mak`)

Returns float — clear-sky GHI in W/m²; 0 on any arithmetic exception (e.g. when TOA = 0).

`generateGHIargp_2(data)` — ARGP clear-sky model (ktrp2)

Geo.generateGHIargp_2(data: pd.DataFrame) -> list[float]

Computes clear-sky GHI using the ARGP model with the fixed-form transmittance ktrp2:

ktrp2       = 0.649 + 0.02 × alt^0.28     (always used, regardless of altitude)
GHI_argp2   = TOA × ktrp2^(AM^0.678)

Unlike generateGHIargp, the ktrp2 formula does not branch on altitude — it is applied uniformly for all sites.

Parameter	Type	Description
`data`	pd.DataFrame	Must contain `'TOA'` and `'Mak'` columns

Returns list[float] — clear-sky GHI values stored in self.df['GHIargp2']; 0 for any row where the calculation raises an exception.

`generateMs(CZ, SZA)` — Pressure-corrected air mass (Kasten formula)

Geo.generateMs(CZ: float, SZA: float) -> float

Computes a pressure-corrected air mass using the Kasten formula with SZA in degrees:

p   = (288.15 / (288.15 − 0.0065 × 1150))^(−5.255877)
mr  = p × 1 / (cos(SZA°) + (0.48353^0.095846) / (96.741 − SZA)^1.754)

Returns 0 when SZA ≥ 90°.

generateMs uses a hardcoded altitude of 1150 m in the pressure calculation instead of self.altura. This is a known discrepancy in the source code (helpers/Geo.py). If your site altitude differs significantly from 1150 m, the mr column will not reflect the actual site pressure. Use Mak (which uses self.altura correctly) when pressure accuracy matters.

Parameter	Type	Description
`CZ`	float	Cosine of the solar zenith angle (read but not used in the active formula path)
`SZA`	float	Solar zenith angle in degrees

Returns float — pressure-corrected air mass, or 0 when SZA ≥ 90°.

`to_csv(name)` — Export DataFrame

Geo.to_csv(name: str) -> None

Saves self.df to a CSV file named name + '.csv' in the current working directory.

Parameter	Type	Description
`name`	str	Output file name without the `.csv` extension

Usage Example

import pandas as pd
from helpers.Geo import Geo

ranges = pd.date_range(
    start='2020/01/01 00:00',
    end='2023/08/31 23:59',
    freq='1min'
)

dfGeo = Geo(
    range_dates=ranges,
    lat=-22.103936,
    long=-65.599923,
    gmt=0,
    alt=3500,
    beta=0
).df

print(dfGeo[['date', 'SZA', 'TOA', 'CTZ', 'GHIargp', 'GHIargp2']].head())

Expected output (first rows during a pre-sunrise period):

                 date    SZA  TOA  CTZ  GHIargp  GHIargp2
0 2020-01-01 00:00:00  99.2...  0.0  ...      0.0       0.0
1 2020-01-01 00:01:00  99.1...  0.0  ...      0.0       0.0

For sites in UTC−3 (Argentina), pass gmt=-3. The constructor automatically applies the correct sign convention so that solar hours align with local noon.

Helper Modules

Constructor

Parameters

Returns

Output DataFrame: `Geo.df`

Instance Attributes

Methods

`getKtrp()` — Altitude-dependent clear-sky transmittance

`getE(n, y)` — Equation of time

`Fn(n, y)` — Orbital distance correction factor

`getHS()` — Solar hour

`delta(n, y)` — Solar declination

`getCTZ(delta, omega)` — Cosine of solar zenith angle

`getWs(delta)` — Sunset hour angle

`getE0(N, y)` — Orbital eccentricity correction

`TOA(E0, CTZ)` — Top-of-atmosphere irradiance

`Mak(CTZ, TZ)` — Kasten–Young air mass (pressure-corrected)

`generateGHIargp(TOA, AM)` — ARGP clear-sky model (ktrp)

`generateGHIargp_2(data)` — ARGP clear-sky model (ktrp2)

`generateMs(CZ, SZA)` — Pressure-corrected air mass (Kasten formula)

`to_csv(name)` — Export DataFrame

Usage Example

Build docs developers (and LLMs) love

Helper Modules

Documentation Index

​Constructor

​Parameters

​Returns

​Output DataFrame: Geo.df

​Instance Attributes

​Methods

​getKtrp() — Altitude-dependent clear-sky transmittance

​getE(n, y) — Equation of time

​Fn(n, y) — Orbital distance correction factor

​getHS() — Solar hour

​delta(n, y) — Solar declination

​getCTZ(delta, omega) — Cosine of solar zenith angle

​getWs(delta) — Sunset hour angle

​getE0(N, y) — Orbital eccentricity correction

​TOA(E0, CTZ) — Top-of-atmosphere irradiance

​Mak(CTZ, TZ) — Kasten–Young air mass (pressure-corrected)

​generateGHIargp(TOA, AM) — ARGP clear-sky model (ktrp)

​generateGHIargp_2(data) — ARGP clear-sky model (ktrp2)

​generateMs(CZ, SZA) — Pressure-corrected air mass (Kasten formula)

​to_csv(name) — Export DataFrame

​Usage Example

Build docs developers (and LLMs) love

Constructor

Parameters

Returns

Output DataFrame: `Geo.df`

Instance Attributes

Methods

`getKtrp()` — Altitude-dependent clear-sky transmittance

`getE(n, y)` — Equation of time

`Fn(n, y)` — Orbital distance correction factor

`getHS()` — Solar hour

`delta(n, y)` — Solar declination

`getCTZ(delta, omega)` — Cosine of solar zenith angle

`getWs(delta)` — Sunset hour angle

`getE0(N, y)` — Orbital eccentricity correction

`TOA(E0, CTZ)` — Top-of-atmosphere irradiance

`Mak(CTZ, TZ)` — Kasten–Young air mass (pressure-corrected)

`generateGHIargp(TOA, AM)` — ARGP clear-sky model (ktrp)

`generateGHIargp_2(data)` — ARGP clear-sky model (ktrp2)

`generateMs(CZ, SZA)` — Pressure-corrected air mass (Kasten formula)

`to_csv(name)` — Export DataFrame

Usage Example