feat(math): add NOAA solar position and day phases

Meeus/NOAA equations for elevation (with refraction) and azimuth,
iteratively refined sunrise, sunset and civil/nautical/astronomical
twilight per local solar day, and DayPhase classification.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012iLMBNwBE2GnphAsu4cjaC
This commit is contained in:
Claude committed 2026-10-02 09:31:06 +00:00
1 parent 72ffd8ec47
commit 8c2692073c
2 files changed
+323

No files matched your search

+219
View File
@@ -0,0 +1,219 @@
namespace Titano.Core.Mathematics;
/// <summary>Light condition by solar elevation (geometric centre of the disc).</summary>
public enum DayPhase
{
/// <summary>Sun below −18°.</summary>
Night,
/// <summary>−18° to −12°.</summary>
AstronomicalTwilight,
/// <summary>−12° to −6°.</summary>
NauticalTwilight,
/// <summary>−6° to sunrise/sunset (−0.833°).</summary>
CivilTwilight,
/// <summary>Sun up but below 6°.</summary>
GoldenHour,
/// <summary>Sun at or above 6°.</summary>
Day,
}
/// <summary>Sun position for an instant and place.</summary>
/// <param name="Elevation">Apparent elevation in degrees, corrected for standard atmospheric refraction.</param>
/// <param name="Azimuth">Degrees clockwise from true north.</param>
/// <param name="GeometricElevation">Elevation without refraction, in degrees (used for twilight limits).</param>
/// <param name="Declination">Solar declination in degrees.</param>
/// <param name="EquationOfTimeMinutes">Apparent minus mean solar time, in minutes.</param>
public readonly record struct SolarCoordinates(double Elevation, double Azimuth, double GeometricElevation, double Declination, double EquationOfTimeMinutes)
{
public DayPhase Phase => SolarPosition.Classify(GeometricElevation);
}
/// <summary>Sun events of one local solar day, all in UTC; null when the event does not occur (polar day/night).</summary>
public sealed record SolarDay(
DateOnly Date,
DateTime SolarNoon,
DateTime? Sunrise,
DateTime? Sunset,
DateTime? CivilDawn,
DateTime? CivilDusk,
DateTime? NauticalDawn,
DateTime? NauticalDusk,
DateTime? AstronomicalDawn,
DateTime? AstronomicalDusk);
/// <summary>
/// Solar position and rise/set times with the NOAA Solar Calculator equations (after Meeus, "Astronomical
/// Algorithms"). Event times are refined iteratively at the event instant; accuracy is about one minute for
/// latitudes within ±72°. Longitudes are east-positive, latitudes north-positive, times UTC.
/// </summary>
public static class SolarPosition
{
/// <summary>Geometric elevation of the disc centre at apparent sunrise/sunset (34′ refraction + 16′ semi-diameter).</summary>
public const double SunriseElevation = -0.833;
public const double CivilTwilightElevation = -6;
public const double NauticalTwilightElevation = -12;
public const double AstronomicalTwilightElevation = -18;
public const double GoldenHourElevation = 6;
private const double Deg = Math.PI / 180;
private static readonly DateTime J2000 = new(2000, 1, 1, 12, 0, 0, DateTimeKind.Utc);
/// <summary>Sun position at <paramref name="utc"/> (a value of unspecified kind is taken as UTC).</summary>
public static SolarCoordinates Compute(DateTime utc, double latitude, double longitude)
{
ValidateLocation(latitude, longitude);
var sun = Ephemeris(utc);
var minutes = utc.TimeOfDay.TotalMinutes;
var trueSolarTime = Mod(minutes + sun.EquationOfTime + 4 * longitude, 1440);
var hourAngle = trueSolarTime / 4 - 180;
var phi = latitude * Deg;
var delta = sun.Declination * Deg;
var cosZenith = Math.Clamp(Math.Sin(phi) * Math.Sin(delta) + Math.Cos(phi) * Math.Cos(delta) * Math.Cos(hourAngle * Deg), -1, 1);
var zenith = Math.Acos(cosZenith);
var geometric = 90 - zenith / Deg;
double azimuth;
var denominator = Math.Cos(phi) * Math.Sin(zenith);
if (Math.Abs(denominator) < 1e-12)
{
azimuth = latitude > 0 ? 180 : 0;
}
else
{
var a = Math.Acos(Math.Clamp((Math.Sin(phi) * cosZenith - Math.Sin(delta)) / denominator, -1, 1)) / Deg;
azimuth = hourAngle > 0 ? Mod(a + 180, 360) : Mod(540 - a, 360);
}
return new SolarCoordinates(geometric + Refraction(geometric), azimuth, geometric, sun.Declination, sun.EquationOfTime);
}
/// <summary>Day phase from the geometric elevation in degrees.</summary>
public static DayPhase Classify(double geometricElevation) => geometricElevation switch
{
< AstronomicalTwilightElevation => DayPhase.Night,
< NauticalTwilightElevation => DayPhase.AstronomicalTwilight,
< CivilTwilightElevation => DayPhase.NauticalTwilight,
< SunriseElevation => DayPhase.CivilTwilight,
< GoldenHourElevation => DayPhase.GoldenHour,
_ => DayPhase.Day,
};
public static DayPhase Phase(DateTime utc, double latitude, double longitude) => Compute(utc, latitude, longitude).Phase;
/// <summary>All rise/set and twilight events of the local solar day <paramref name="date"/> (the day whose solar
/// noon falls on that calendar date at the given longitude).</summary>
public static SolarDay Events(DateOnly date, double latitude, double longitude)
{
ValidateLocation(latitude, longitude);
return new SolarDay(
date,
SolarNoon(date, longitude),
EventTime(date, latitude, longitude, SunriseElevation, rising: true),
EventTime(date, latitude, longitude, SunriseElevation, rising: false),
EventTime(date, latitude, longitude, CivilTwilightElevation, rising: true),
EventTime(date, latitude, longitude, CivilTwilightElevation, rising: false),
EventTime(date, latitude, longitude, NauticalTwilightElevation, rising: true),
EventTime(date, latitude, longitude, NauticalTwilightElevation, rising: false),
EventTime(date, latitude, longitude, AstronomicalTwilightElevation, rising: true),
EventTime(date, latitude, longitude, AstronomicalTwilightElevation, rising: false));
}
/// <summary>UTC solar noon (upper transit) of the local solar day.</summary>
public static DateTime SolarNoon(DateOnly date, double longitude)
{
var midnight = date.ToDateTime(TimeOnly.MinValue, DateTimeKind.Utc);
var minutes = 720 - 4 * longitude;
for (var i = 0; i < 3; i++)
minutes = 720 - 4 * longitude - Ephemeris(midnight.AddMinutes(minutes)).EquationOfTime;
return midnight.AddMinutes(minutes);
}
/// <summary>
/// UTC time at which the sun's geometric centre crosses <paramref name="elevation"/> degrees on the given
/// local solar day, rising (morning) or setting (evening); null when it stays above or below all day.
/// </summary>
public static DateTime? EventTime(DateOnly date, double latitude, double longitude, double elevation, bool rising)
{
ValidateLocation(latitude, longitude);
var midnight = date.ToDateTime(TimeOnly.MinValue, DateTimeKind.Utc);
var minutes = 720 - 4 * longitude;
for (var i = 0; i < 4; i++)
{
var sun = Ephemeris(midnight.AddMinutes(minutes));
var hourAngle = HourAngle(latitude, sun.Declination, elevation);
if (double.IsNaN(hourAngle)) return null;
var noon = 720 - 4 * longitude - sun.EquationOfTime;
minutes = noon + (rising ? -4 : 4) * hourAngle;
}
return midnight.AddMinutes(minutes);
}
private static double HourAngle(double latitude, double declination, double elevation)
{
var phi = latitude * Deg;
var delta = declination * Deg;
var cosH = (Math.Cos((90 - elevation) * Deg) - Math.Sin(phi) * Math.Sin(delta)) / (Math.Cos(phi) * Math.Cos(delta));
return cosH is < -1 or > 1 || double.IsNaN(cosH) ? double.NaN : Math.Acos(cosH) / Deg;
}
/// <summary>NOAA approximation of standard atmospheric refraction, in degrees, for a geometric elevation.</summary>
private static double Refraction(double elevation)
{
if (elevation > 85) return 0;
var t = Math.Tan(elevation * Deg);
var arcSeconds = elevation switch
{
> 5 => 58.1 / t - 0.07 / (t * t * t) + 0.000086 / Math.Pow(t, 5),
> -0.575 => 1735 + elevation * (-518.2 + elevation * (103.4 + elevation * (-12.79 + elevation * 0.711))),
_ => -20.772 / t,
};
return arcSeconds / 3600;
}
private readonly record struct Sun(double Declination, double EquationOfTime);
private static Sun Ephemeris(DateTime utc)
{
var julianDay = 2451545.0 + (DateTime.SpecifyKind(utc, DateTimeKind.Utc) - J2000).TotalDays;
var t = (julianDay - 2451545.0) / 36525.0;
var meanLongitude = Mod(280.46646 + t * (36000.76983 + t * 0.0003032), 360);
var meanAnomaly = 357.52911 + t * (35999.05029 - 0.0001537 * t);
var eccentricity = 0.016708634 - t * (0.000042037 + 0.0000001267 * t);
var m = meanAnomaly * Deg;
var center = Math.Sin(m) * (1.914602 - t * (0.004817 + 0.000014 * t))
+ Math.Sin(2 * m) * (0.019993 - 0.000101 * t)
+ Math.Sin(3 * m) * 0.000289;
var trueLongitude = meanLongitude + center;
var omega = (125.04 - 1934.136 * t) * Deg;
var apparentLongitude = trueLongitude - 0.00569 - 0.00478 * Math.Sin(omega);
var meanObliquity = 23 + (26 + (21.448 - t * (46.815 + t * (0.00059 - t * 0.001813))) / 60) / 60;
var obliquity = (meanObliquity + 0.00256 * Math.Cos(omega)) * Deg;
var declination = Math.Asin(Math.Sin(obliquity) * Math.Sin(apparentLongitude * Deg)) / Deg;
var y = Math.Tan(obliquity / 2);
y *= y;
var l0 = meanLongitude * Deg;
var e = eccentricity;
var equationOfTime = 4 / Deg * (y * Math.Sin(2 * l0) - 2 * e * Math.Sin(m) + 4 * e * y * Math.Sin(m) * Math.Cos(2 * l0)
- 0.5 * y * y * Math.Sin(4 * l0) - 1.25 * e * e * Math.Sin(2 * m));
return new Sun(declination, equationOfTime);
}
private static double Mod(double value, double modulus)
{
var r = value % modulus;
return r < 0 ? r + modulus : r;
}
private static void ValidateLocation(double latitude, double longitude)
{
if (!(latitude >= -90 && latitude <= 90)) throw new ArgumentOutOfRangeException(nameof(latitude));
if (!(longitude >= -180 && longitude <= 180)) throw new ArgumentOutOfRangeException(nameof(longitude));
}
}
@@ -0,0 +1,104 @@
using System.Globalization;
using Titano.Core.Mathematics;
using Titano.Testing;
namespace Titano.Core.Tests.Mathematics;
/// <summary>
/// Reference values are NOAA Solar Calculator results (spreadsheet equations as implemented by the
/// <c>astral</c> package, cross-checked against PyEphem/VSOP87 to within 35 s), UTC, for the local solar day.
/// </summary>
public sealed class SolarPositionTests
{
private const double OneMinute = 60;
[Theory]
[Case("Greenwich summer", 51.4769, -0.0005, "2024-06-21", "03:43:13", "20:20:36", "02:54:34", "21:09:14", "01:40:14", "22:23:33", null, null)]
[Case("Greenwich winter", 51.4769, -0.0005, "2024-12-21", "08:03:42", "15:52:56", "07:22:37", "16:34:01", "06:39:40", "17:16:58", "05:58:57", "17:57:41")]
[Case("New York equinox", 40.7128, -74.0060, "2024-03-20", "10:58:42", "23:08:28", "10:30:54", "23:36:20", "09:59:06", "+00:08:13", "09:26:36", "+00:40:50")]
[Case("Sydney winter", -33.8688, 151.2093, "2024-06-21", "-21:00:18", "06:53:41", "-20:32:02", "07:21:57", "-20:00:56", "07:53:03", "-19:30:30", "08:23:28")]
[Case("Quito equinox", -0.1807, -78.4678, "2024-09-22", "11:03:17", "23:09:26", "10:42:14", "23:30:29", "10:18:21", "23:54:22", "09:54:23", "+00:18:19")]
[Case("Tromso March", 69.6492, 18.9553, "2024-03-01", "06:08:32", "15:46:01", "05:06:36", "16:48:12", "03:57:47", "17:57:27", "02:44:21", "19:11:43")]
// The sun grazes −6° here, so tiny ephemeris differences move the crossing by minutes: astral's single-pass
// NOAA value is 77 s early, while the iterated NOAA solution and PyEphem agree on 08:31:31 / 12:53:21.
[Case("Tromso polar night", 69.6492, 18.9553, "2024-12-21", null, null, "08:31:31", "12:53:21", "06:46:35", "14:38:21", "05:28:22", "15:56:34")]
[Case("Tromso midnight sun", 69.6492, 18.9553, "2024-06-21", null, null, null, null, null, null, null, null)]
[Case("Golden NREL SPA site", 39.742476, -105.1786, "2003-10-17", "13:12:57", "+00:18:36", "12:45:10", "+00:46:21", "12:13:59", "+01:17:30", "11:42:47", "+01:48:39")]
public void EventsMatchNoaaWithinOneMinute(string place, double latitude, double longitude, string date,
string? sunrise, string? sunset, string? civilDawn, string? civilDusk, string? nauticalDawn, string? nauticalDusk, string? astroDawn, string? astroDusk)
{
var day = DateOnly.ParseExact(date, "yyyy-MM-dd", CultureInfo.InvariantCulture);
var events = SolarPosition.Events(day, latitude, longitude);
Check(place + " sunrise", day, sunrise, events.Sunrise);
Check(place + " sunset", day, sunset, events.Sunset);
Check(place + " civil dawn", day, civilDawn, events.CivilDawn);
Check(place + " civil dusk", day, civilDusk, events.CivilDusk);
Check(place + " nautical dawn", day, nauticalDawn, events.NauticalDawn);
Check(place + " nautical dusk", day, nauticalDusk, events.NauticalDusk);
Check(place + " astronomical dawn", day, astroDawn, events.AstronomicalDawn);
Check(place + " astronomical dusk", day, astroDusk, events.AstronomicalDusk);
}
[Theory]
[Case(51.4769, -0.0005, "2024-06-21", "12:01:49")]
[Case(-33.8688, 151.2093, "2024-06-21", "01:56:58")]
[Case(39.742476, -105.1786, "2003-10-17", "18:46:14")]
public void SolarNoonMatchesNoaa(double latitude, double longitude, string date, string noon)
{
_ = latitude;
var day = DateOnly.ParseExact(date, "yyyy-MM-dd", CultureInfo.InvariantCulture);
Check("noon", day, noon, SolarPosition.SolarNoon(day, longitude));
}
[Theory]
[Case(39.742476, -105.1786, "2003-10-17T19:30:30", 39.8914, 39.8721, 194.3426)]
[Case(51.4769, -0.0005, "2024-06-21T12:00:00", 61.9665, 61.9579, 179.0598)]
[Case(-33.8688, 151.2093, "2024-01-15T06:30:00", 30.7712, 30.7442, 263.8208)]
[Case(35.6762, 139.6503, "2024-09-01T21:00:00", 8.4899, 8.3861, 86.3181)]
[Case(64.1466, -21.9426, "2024-12-01T15:00:00", 1.9248, 1.6140, 203.7679)]
public void PositionMatchesNoaa(double latitude, double longitude, string utc, double elevation, double geometric, double azimuth)
{
var time = DateTime.SpecifyKind(DateTime.ParseExact(utc, "yyyy-MM-ddTHH:mm:ss", CultureInfo.InvariantCulture), DateTimeKind.Utc);
var sun = SolarPosition.Compute(time, latitude, longitude);
Assert.Approximately(geometric, sun.GeometricElevation, 0.01);
Assert.Approximately(elevation, sun.Elevation, 0.01);
Assert.Approximately(azimuth, sun.Azimuth, 0.01);
}
[Theory]
[Case(10.0, DayPhase.Day)]
[Case(3.0, DayPhase.GoldenHour)]
[Case(-0.5, DayPhase.GoldenHour)]
[Case(-3.0, DayPhase.CivilTwilight)]
[Case(-8.0, DayPhase.NauticalTwilight)]
[Case(-15.0, DayPhase.AstronomicalTwilight)]
[Case(-30.0, DayPhase.Night)]
public void ClassifiesElevation(double elevation, DayPhase expected) => Assert.Equal(expected, SolarPosition.Classify(elevation));
[Test]
public void PhaseFollowsTheEvents()
{
var day = new DateOnly(2024, 12, 21);
var events = SolarPosition.Events(day, 51.4769, -0.0005);
Assert.Equal(DayPhase.Day, SolarPosition.Phase(events.SolarNoon, 51.4769, -0.0005));
Assert.Equal(DayPhase.GoldenHour, SolarPosition.Phase(events.Sunset!.Value.AddMinutes(-5), 51.4769, -0.0005));
Assert.Equal(DayPhase.CivilTwilight, SolarPosition.Phase(events.Sunset!.Value.AddMinutes(5), 51.4769, -0.0005));
Assert.Equal(DayPhase.Night, SolarPosition.Phase(events.AstronomicalDusk!.Value.AddMinutes(5), 51.4769, -0.0005));
Assert.Throws<ArgumentOutOfRangeException>(() => SolarPosition.Compute(DateTime.UtcNow, 91, 0));
}
/// <summary>Expected "HH:mm:ss" on <paramref name="day"/>; a leading '-' or '+' means the previous or next UTC day.</summary>
private static void Check(string label, DateOnly day, string? expected, DateTime? actual)
{
if (expected is null)
{
Assert.Null(actual);
return;
}
var offsetDays = expected[0] switch { '-' => -1, '+' => 1, _ => 0 };
var clock = TimeOnly.ParseExact(expected.TrimStart('+', '-'), "HH:mm:ss", CultureInfo.InvariantCulture);
var reference = day.AddDays(offsetDays).ToDateTime(clock, DateTimeKind.Utc);
var value = Assert.NotNull(actual, label);
Assert.Approximately(0, (value - reference).TotalSeconds, OneMinute, label);
}
}