API Reference

Insolation

A Julia package to calculate top-of-atmosphere (TOA) insolation (incoming solar radiation) based on Earth's (or another planetary body's) orbital parameters.

The calculations follow fundamental principles of celestial mechanics and solar geometry, as described in "Physics of Earth's Climate" by Tapio Schneider and Lenka Novak.

The package provides functions to:

• Calculate instantaneous insolation for a specific time and location.
• Calculate diurnally averaged insolation.
• Fetch and use orbital parameters (eccentricity, obliquity, and longitude of perihelion) from Laskar et al. (2004) to compute insolation for paleoclimate studies.

orbital_params(od::OrbitalDataSplines, dt::FT) where {FT <: Real}

Interpolates time-varying orbital parameters using Milankovitch cycles.

Interpolates orbital parameters from the Laskar et al. (2004) dataset for paleoclimate studies. The parameters vary over geological timescales.

Arguments

• od::OrbitalDataSplines: The struct containing orbital parameter splines.
• dt::FT: The time for interpolation [Years since J2000 epoch].

Returns

• (ϖ, γ, e): A tuple containing:
  • ϖ: Longitude of perihelion [radians]
  • γ: Obliquity (axial tilt) [radians]
  • e: Orbital eccentricity [unitless]

orbital_params(param_set::AIP)

Returns fixed orbital parameters at epoch.

Uses the constant orbital parameter values at the reference epoch (typically J2000) stored in the parameter set. Suitable for modern climate simulations where orbital variations are negligible.

Arguments

• param_set::AIP: Parameter struct containing epoch orbital parameters

Returns

• (ϖ, γ, e): A tuple containing:
  • ϖ: Longitude of perihelion at epoch [radians]
  • γ: Obliquity (axial tilt) at epoch [radians]
  • e: Orbital eccentricity at epoch [unitless]

OrbitalDataSplines

A container struct that holds cubic spline interpolators for Earth's orbital parameters, based on the Laskar 2004 dataset.

The time series of orbital parameters are lazily downloaded from the orbital_parameters_dataset_path(artifact_dir) path where artifact_dir is the path and filename to save the artifacts toml file.

The splines are functions of time (in years since J2000 epoch).

GPU Support

This struct is GPU-compatible via Adapt.jl. To transfer to GPU memory:

using CUDA, Adapt
cpu_od = OrbitalDataSplines()  # Create on CPU
gpu_od = adapt(CuArray, cpu_od)  # Transfer to GPU

TSIDataSpline

A container struct that holds a cubic interpolator for the monthly mean total solar irradiance.

The spline is a function of date between 1850-01-15T12:00 and 2229-12-15T12:00. Dates outside this range will result in NaN.

GPU Support

This struct is GPU-compatible via Adapt.jl. To transfer to GPU memory:

using CUDA, Adapt
cpu_tsi = TSIDataSpline(Float32)  # Create on CPU
gpu_tsi = adapt(CuArray, TSIDataSpline)  # Transfer to GPU

TSIDataSpline(::Type{FT}) where {FT <: AbstractFloat}

Constructs a TSIDataSpline that interpolates monthly mean total solar irradiance as a function of the date and time.

evaluate(tsi::TSIDataSpline, date::Dates.DateTime)

Interpolate monthly mean total solar irradiance at date via a cubic interpolation.

The spline is a function of date between 1850-01-15T12:00 and 2229-12-15T12:00. Dates outside this range will result in NaN.

insolation(θ::FT, d::FT, param_set::IP.AIP) where {FT <: Real}

Calculates top-of-atmosphere (TOA) insolation and cosine of solar zenith angle.

Implements $F = S \cos(\theta)$ where S is the solar flux at the given planet-star distance. Insolation is set to 0 at night (when $\cos(\theta) < 0$).

Arguments

• θ::FT: Solar zenith angle [radians]
• d::FT: Planet-star distance [m]
• param_set::IP.AIP: Parameter struct
• date::Union{DateTime,Nothing}: (default nothing) Current date and time to evaluate the solar flux if tsi_spline is available.
• solar_variability_spline::Union{TSIDataSpline,Nothing}: Use time-varying solar luminosity if TSIDataSpline is passed as an argument.

Returns

• F: TOA insolation [W m⁻²]
• S: Solar flux at the given planet-star distance [W m⁻²]
• μ: Cosine of solar zenith angle [unitless], clamped to [0, 1]

insolation(
    date::DateTime,
    latitude::FT1,
    longitude::FT2,
    param_set::IP.AIP,
    orbital_data::Union{OrbitalDataSplines, Nothing} = nothing,
    milankovitch::Bool = false,
    solar_variability_spline::Union{TSIDataSpline, Nothing} = nothing,
    eot_correction::Bool = true,
) where {FT1 <: Real, FT2 <: Real}

Calculates instantaneous TOA insolation with optional long-term variations in Earth's orbital parameters (Milankovitch cycles) and solar luminosity.

Arguments

• date::DateTime: Current date and time
• latitude::FT1: Latitude [degrees]
• longitude::FT2: Longitude [degrees]
• param_set::IP.AIP: Parameter struct
• orbital_data::Union{OrbitalDataSplines, Nothing}: (default nothing) Orbital parameter splines. Required when milankovitch=true for GPU compatibility.
• milankovitch::Bool: (default false) Use time-varying orbital parameters (Milankovitch cycles)
• solar_variability_spline::Union{TSIDataSpline, Nothing}: (default nothing) Use time-varying solar luminosity if TSIDataSpline is passed as an argument.
• eot_correction::Bool: (default true) Apply equation of time correction

Returns

• F: TOA insolation [W m⁻²]
• S: Solar flux [W m⁻²]
• μ: Cosine of solar zenith angle [unitless]
• ζ: Solar azimuth angle [radians], 0 = due East, increasing counterclockwise

Examples

# Modern climate (fixed epoch parameters)
F, S, μ, ζ = insolation(date, lat, lon, param_set)

# Paleoclimate with Milankovitch cycles
od = OrbitalDataSplines()  # Load once
milankovitch = true
F, S, μ, ζ = insolation(date, lat, lon, param_set, od, milankovitch)

# Without equation of time correction
milankovitch = false,
solar_variability_spline = nothing
eot_correction = false
F, S, μ, ζ = insolation(date, lat, lon, param_set, milankovitch, solar_variability_spline, eot_correction)

GPU Usage

For GPU execution, create orbital and solar variability data on CPU and transfer to GPU using Adapt.jl:

using CUDA, Adapt
cpu_od = OrbitalDataSplines()  # Create on CPU
gpu_od = adapt(CuArray, cpu_od)  # Transfer to GPU
cpu_solar = TSIDataSpline(Float32) # Create on CPU
gpu_solar = adapt(CuArray, cpu_solar) # Transfer to GPU
# In GPU kernel:
milankovitch=true
F, S, μ, ζ = insolation(date, lat, lon, param_set, gpu_od, milankovitch, gpu_solar)

daily_insolation(
    date::DateTime,
    latitude::Real,
    param_set::IP.AIP,
    orbital_data::Union{OrbitalDataSplines, Nothing} = nothing,
    milankovitch::Bool = false,
    solar_variability_spline::Union{TSIDataSpline, Nothing} = nothing,
)

Calculates diurnally averaged TOA insolation with optional long-term variations in orbital parameters (Milankovitch cycles) and solar luminosity. The insolation is averaged over a full day.

Arguments

• date::DateTime: Current date
• latitude::FT: Latitude [degrees]
• param_set::IP.AIP: Parameter struct
• orbital_data::Union{OrbitalDataSplines, Nothing}: (default nothing) Orbital parameter splines. Required when milankovitch=true for GPU compatibility.
• milankovitch::Bool: (default false) Use time-varying orbital parameters (Milankovitch cycles).
• solar_variability_spline::Union{TSIDataSpline, Nothing}: (default nothing) Use time-varying solar luminosity if TSIDataSpline is passed as an argument.

Returns

• F: Daily averaged TOA insolation [W m⁻²]
• S: Solar flux [W m⁻²]
• μ: Daily averaged cosine of solar zenith angle [unitless]

Examples

# Modern climate (fixed epoch parameters)
F, S, μ = daily_insolation(date, lat, param_set)

# Paleoclimate with Milankovitch cycles
od = OrbitalDataSplines()  # Load once
F, S, μ = daily_insolation(date, lat, param_set, od; milankovitch=true)

GPU Usage

For GPU execution, create orbital and solar variability data on CPU and transfer to GPU using Adapt.jl:

using CUDA, Adapt
cpu_od = OrbitalDataSplines()  # Create on CPU
gpu_od = adapt(CuArray, cpu_od)  # Transfer to GPU
cpu_solar = TSIDataSpline(Float32) # Create on CPU
gpu_solar = adapt(CuArray, cpu_solar)
milankovitch = true
# In GPU kernel:
F, S, μ = daily_insolation(date, lat, param_set, gpu_od, milankovitch, gpu_solar)

solar_flux(
    d::FT,
    param_set::IP.AIP,
    date::Union{DateTime,Nothing} = nothing,
    solar_variability_spline::Union{TSIDataSpline,Nothing} = nothing,
) where {FT<:Real}

Calculates the solar radiative energy flux at the top of the atmosphere (TOA) based on the planet-star distance and the inverse square law.

Arguments

• d::FT: Planet-star distance [m]
• param_set::IP.AIP: Struct containing tot_solar_irrad [W m⁻²] and orbit_semimaj [m]
• date::Union{DateTime,Nothing}: (default nothing) Current date and time to evaluate the solar flux if tsi_spline is available.
• solar_variability_spline::Union{TSIDataSpline,Nothing}: Use time-varying solar luminosity if TSIDataSpline is passed as an argument.

solar_geometry(
    date::DateTime,
    latitude::Real,
    longitude::Real,
    (ϖ, γ, e)::Tuple{FT, FT, FT},
    param_set::AIP;
    eot_correction::Bool = true,
) where {FT}

Calculates planet-star distance, solar zenith angle, and azimuthal angle.

This is a high-level function that combines all necessary astronomical calculations to determine the planet's position and distance from the star at a specific time and location.

Arguments

• date::DateTime: Current date and time
• latitude::Real: Latitude [degrees]
• longitude::Real: Longitude [degrees]
• (ϖ, γ, e)::Tuple{FT, FT, FT}: Orbital parameters tuple containing:
  • ϖ: Longitude of perihelion [radians]
  • γ: Obliquity (axial tilt) [radians]
  • e: Orbital eccentricity [unitless]
• param_set::AIP: Parameter struct
• eot_correction::Bool: (default true) Apply equation of time correction

Returns

• d: Planet-Sun distance [m]
• θ: Solar zenith angle [radians]
• ζ: Solar azimuth angle [radians], 0 = due East, increasing CCW

daily_distance_zenith_angle(
    date::DateTime,
    latitude::FT,
    (ϖ, γ, e)::Tuple{FT, FT, FT},
    param_set::IP.AIP,
) where {FT <: Real}

Calculates the effective zenith angle for diurnally averaged insolation and planet-star distance.

Returns the effective zenith angle corresponding to the diurnally averaged insolation (averaging cos(zenith angle) over 24 hours) and the planet-star distance for a given date and latitude.

Arguments

• date::DateTime: Current date
• latitude::FT: Latitude [degrees]
• (ϖ, γ, e)::Tuple{FT, FT, FT}: Orbital parameters tuple containing:
  • ϖ: Longitude of perihelion [radians]
  • γ: Obliquity (axial tilt) [radians]
  • e: Orbital eccentricity [unitless]
• param_set::IP.AIP: Parameter struct

Returns

• daily_θ: Effective solar zenith angle [radians]
• d: Planet-star distance [m]

mean_anomaly(Δt_years::FT, param_set::IP.AIP) where {FT}

Calculates the mean anomaly at a given time since epoch.

The mean anomaly is the angle the planet would have traveled from perihelion if it moved in a circular orbit at constant angular velocity.

Arguments

• Δt_years::FT: Time since epoch [years]
• param_set::IP.AIP: Parameter struct containing mean_anom_epoch

Returns

• MA: Mean anomaly [radians]

true_anomaly(MA::FT, e::FT) where {FT <: Real}

Calculates the true anomaly from the mean anomaly.

The true anomaly is the actual angular distance of the planet from perihelion along its orbital path. This function uses a series expansion accurate to O(e⁴) where e is the eccentricity (see Fitzpatrick (2012), Appendix A.10).

Arguments

• MA::FT: Mean anomaly [radians]
• e::FT: Orbital eccentricity [unitless]

Returns

• TA: True anomaly [radians]

solar_longitude(TA::FT, ϖ::FT) where {FT <: Real}

Calculates the solar longitude (ecliptic longitude of the Sun).

The solar longitude is the angular distance of the planet along its orbital path, measured from vernal equinox. It is the sum of the true anomaly (angle from perihelion) and the longitude of perihelion.

Arguments

• TA::FT: True anomaly [radians]
• ϖ::FT: Longitude of perihelion [radians]

Returns

• SL: Solar longitude [radians]

hour_angle(
    date::DateTime,
    λ::FT,
    MA::FT,
    (ϖ, γ, e)::Tuple{FT, FT, FT};
    eot_correction::Bool = true,
) where {FT}

Calculates the hour angle at a given time and longitude.

The hour angle is zero at local solar noon and increases with time. Optionally applies the equation of time correction to account for the difference between apparent and mean solar time.

Arguments

• date::DateTime: Current date and time
• λ::FT: Longitude [radians]
• MA::FT: Mean anomaly [radians]
• (ϖ, γ, e)::Tuple{FT, FT, FT}: Orbital parameters tuple containing:
  • ϖ: Longitude of perihelion [radians]
  • γ: Obliquity (axial tilt) [radians]
  • e: Orbital eccentricity [unitless]
• eot_correction::Bool: (default true) Apply equation of time correction

Returns

• η: Hour angle [radians]

equation_of_time(MA::FT, (ϖ, γ, e)::Tuple{FT, FT, FT}) where {FT <: Real}

Calculates the equation of time correction for the hour angle.

The equation of time accounts for the difference between apparent solar time (based on the actual Sun's position in the sky) and mean solar time (based on a fictitious mean Sun moving at constant speed). This difference arises from two effects:

1. Earth's elliptical orbit (eccentricity e)
2. Earth's axial tilt (obliquity γ)

Arguments

• MA::FT: Mean anomaly [radians]
• (ϖ, γ, e)::Tuple{FT, FT, FT}: Orbital parameters tuple containing:
  • ϖ: Longitude of perihelion [radians]
  • γ: Obliquity (axial tilt) [radians]
  • e: Orbital eccentricity [unitless]

Returns

• Δη: Hour angle correction [radians]

planet_star_distance(TA::FT, e::FT, param_set::IP.AIP) where {FT <: Real}

Calculates the distance between planet (Earth) and star (Sun) at a given true anomaly.

The distance varies due to the planet's elliptical orbit, being shortest at perihelion and longest at aphelion. The calculation uses the orbit equation for an ellipse.

Arguments

• TA::FT: True anomaly [radians]
• e::FT: Orbital eccentricity [unitless]
• param_set::IP.AIP: Parameter struct containing orbit_semimaj

Returns

• d: Planet-star distance [m]

years_since_epoch(
    param_set::IP.InsolationParameters{FT},
    date::DateTime,
) where {FT}

Calculates the time elapsed since epoch (typically J2000) in anomalistic years (the time from perihelion to perihelion).

Converts the time difference between two dates from Julian days to anomalistic years, which is the natural time unit for orbital calculations.

Arguments

• param_set::IP.InsolationParameters{FT}: Parameter struct
• date::DateTime: Current date and time

Returns

• Δt_years: Time since epoch [anomalistic years]

distance_declination_mean_anomaly(
    Δt_years::FT,
    (ϖ, γ, e)::Tuple{FT, FT, FT},
    param_set::IP.AIP,
) where {FT}

Computes planet-star distance, solar declination angle, and mean anomaly.

This function calculates key astronomical parameters from orbital elements. The declination determines the subsolar latitude, while the planet-star distance varies due to orbital eccentricity. The mean anomaly is returned for use in hour angle calculations.

Arguments

• Δt_years::FT: Time since epoch [anomalistic years]
• (ϖ, γ, e)::Tuple{FT, FT, FT}: Orbital parameters tuple containing:
  • ϖ: Longitude of perihelion [radians]
  • γ: Obliquity (axial tilt) [radians]
  • e: Orbital eccentricity [unitless]
• param_set::IP.AIP: Parameter struct

Returns

• d: Planet-star distance [m]
• δ: Solar declination angle [radians]
• MA: Mean anomaly [radians]

AbstractInsolationParams

Abstract base type for insolation parameter sets.

All parameter structs used in Insolation.jl should inherit from this type. The main concrete implementation is InsolationParameters.

This type hierarchy allows for flexible parameter management and enables package extensions to provide alternative parameter implementations while maintaining API compatibility.