🔭 Ephemeris

A .NET library for astronomical calculations — from Julian dates to sunsets, planetary positions to eclipses.

---

✨ Overview

Ephemeris implements classical computational astronomy formulas in a modern, strongly-typed, immutable .NET library. Every algorithm is referenced to its original source and verified against published almanac data.

using Ephemeris.Core;
using Ephemeris.SolarSystem;
using Ephemeris.Time;

// 🌅 Calculate sunrise and sunset for Rome, Italy
var rome = GeographicCoordinate.FromDms(41, 54, 0, 12, 29, 0, 37);
var result = SunriseSunset.Calculate(2026, 3, 8, rome);

var (hRise, mRise) = SunriseSunset.ToHoursMinutes(result.Sunrise);
var (hSet, mSet) = SunriseSunset.ToHoursMinutes(result.Sunset);
Console.WriteLine($"Sunrise: {hRise}:{mRise:D2} UT");
Console.WriteLine($"Sunset:  {hSet}:{mSet:D2} UT");

// 🌙 Moon position
var jd = JulianDate.FromCalendar(2026, 3, 8);
var moon = LunarPosition.Calculate(jd);
Console.WriteLine($"Moon: λ={moon.Position.Longitude.Degrees:F2}°, distance={moon.DistanceKm:F0} km");

// 🔭 Can I see M42 tonight?
var report = VisibilityPlanner.CheckMessier(42, 2026, 1, 15, rome, telescopeApertureMm: 200);
Console.WriteLine(report); // ✅ M42: EXCELLENT — alt 41°, Moon 120° away

---

💾 The Origin Story

This project has roots that go way back. As a teenager, my very first program — written in GW-BASIC and saved on a 3.5″ floppy disk — calculated the sunrise and sunset times. I still remember my father patiently dictating the code listing while I typed it, line by line, on my Olivetti M80.

Since that day, I've always had the itch to build my own astronomy library, fueled by all those books on computational astronomy I'd collected over the years — Meeus, Smart, the USNO Almanac… But life got in the way, and those books gathered dust on the shelf for a long time.

Now, finally, that small dream is fulfilled. Ephemeris is the result of a passion that was born on a floppy disk and grew through decades of curiosity. From GW-BASIC to .NET 10 — the journey was long, but the stars were always there, waiting. 🔭

---

📦 Project structure

Ephemeris/
├── 📐 src/Ephemeris/
│   ├── Core/                  # Foundation types: Angle, GeographicCoordinate, SexagesimalConverter
│   ├── Time/                  # Julian dates, sidereal time, Easter date
│   ├── Coordinates/           # Coordinate systems and transformations
│   ├── Corrections/           # Precession, nutation, aberration, refraction, parallax
│   ├── SolarSystem/           # Sun, Moon, planets, Jovian moons, Saturn rings, comets
│   ├── Phenomena/             # Eclipses, conjunctions, oppositions, Moon phase info
│   ├── Optics/                # Telescope calculations, visual magnitude, Bortle scale
│   └── Observation/           # Observing session planning, rise/transit/set, dark sky windows
│
└── 🧪 tests/Ephemeris.Tests/  # 127 xUnit tests verified against almanac data

---

🧮 Namespaces and classes

Ephemeris.Core — Foundation types

Class	Description
Angle	Immutable value type: degrees, radians, DMS, HMS with arithmetic operators and trigonometry
GeographicCoordinate	Observer latitude, longitude and elevation
SexagesimalConverter	Sexagesimal ↔ decimal conversions

Ephemeris.Time — Calendar and time

Class	Description
JulianDate	Julian Day Number ↔ calendar conversions (Gregorian reform handled)
SiderealTime	Greenwich and local mean sidereal time
Easter	Easter date computation (Meeus Ch.9)

Ephemeris.Coordinates — Celestial coordinates

Class	Description
EquatorialCoordinate	Right ascension and declination
EclipticCoordinate	Ecliptic longitude and latitude
HorizontalCoordinate	Azimuth and altitude
GalacticCoordinate	Galactic coordinates (l, b)
CoordinateTransform	Transformations between all coordinate systems

Ephemeris.Corrections — Atmospheric and geometric corrections

Class	Description
Precession	Precession of the equinoxes (Lieske 1979)
Nutation	Nutation in longitude and obliquity
Aberration	Annual aberration of starlight
Refraction	Atmospheric refraction (Sæmundsson/Bennett formula)
Parallax	Geocentric → topocentric parallax correction

Ephemeris.SolarSystem — Sun, Moon and planets

Class	Description
SolarPosition	Solar coordinates (low and medium precision), equation of time
SunriseSunset	Sunrise, sunset, twilight (civil, nautical, astronomical)
LunarPosition	Lunar position and phase
PlanetaryPosition	Geocentric positions for all planets (Mercury–Neptune)
PlanetaryMagnitude	Visual magnitude of planets from phase angle and distance
JovianMoons	Positions of Galilean satellites (Io, Europa, Ganymede, Callisto)
SaturnRings	Ring tilt, position angle, and apparent dimensions
CometPosition	Position from parabolic, elliptical, or hyperbolic orbital elements

Ephemeris.Phenomena — Observable events

Class	Description
Eclipse	Solar and lunar eclipse prediction
PlanetaryPhenomena	Elongations, oppositions, conjunctions
MoonPhaseInfo	Phase name, lunar age, illumination, next phase dates

Ephemeris.Optics — Telescope and visual calculations 🔬

Class	Description
Telescope	Magnification, exit pupil, FOV, limiting magnitude, Dawes/Rayleigh limits, light-gathering power
VisualMagnitude	Pogson's law, combined magnitudes, airmass, atmospheric extinction, surface brightness, Bortle scale

Ephemeris.Observation — Observing session planning 🌌

Class	Description
RiseTransitSet	Rise, transit, and set times for any celestial object, the Sun, or Moon
ObservingWindow	Dark sky window, Moon interference assessment, sky quality rating
VisibilityPlanner	"Can I See It Tonight?" — combines horizon, darkness, Moon, airmass, and telescope limits
MonthlyPlanner	Best objects for any month — deep-sky, doubles, meteor showers, and lunar features

Ephemeris.Catalogs — Built-in object databases 📋

Class	Description
MessierCatalog	All 110 Messier objects with coordinates, magnitude, size, type, and constellation
BrightStarCatalog	50 brightest named stars with J2000.0 coordinates and proper motion
DoubleStarCatalog	36 notable double/multiple stars with separation, PA, magnitudes, and color notes
MeteorShowerCatalog	16 major meteor showers with radiant coords, ZHR, active periods, parent bodies
LunarFeatureCatalog	45 lunar features (craters, maria, mountains, rilles) with selenographic coordinates
ConstellationIdentifier	Identify constellation from RA/Dec; all 88 IAU constellations with names and meanings

Ephemeris.Coordinates — Additional features

Class	Description
EpochConverter	Proper motion correction and epoch conversion (J2000.0 → any date)

Ephemeris.Time — Additional features

Class	Description
TimeZoneHelper	UT ↔ local time conversion with DST support for US and EU

---

🚀 Quick start

Prerequisites

• .NET 10 SDK

Build and test

# Clone the repository
git clone https://github.com/robgrame/Ephemeris.git
cd Ephemeris

# Build
dotnet build

# Run all tests
dotnet test

# Run a single test
dotnet test --filter "MathcadExample_MmtObservatory_19880115"

Use in your project

# Add as a project reference
dotnet add reference path/to/Ephemeris.csproj

---

📚 References

The implemented formulas come from four classical texts in computational astronomy:

📖 Jean Meeus — Astronomical Formulae for Calculators (3rd ed., Willmann-Bell, 1985)

The primary reference for most algorithms. Chapters used:

Chapter	Topic	Ephemeris class
Ch. 7	Julian Day Number	JulianDate
Ch. 9	Easter date	Easter
Ch. 12	Sidereal time	SiderealTime
Ch. 13	Coordinate transformations	CoordinateTransform
Ch. 16	Atmospheric refraction	Refraction
Ch. 17	Angular separation	CoordinateTransform.AngularSeparation
Ch. 21	Precession	Precession
Ch. 22	Nutation	Nutation
Ch. 23	Aberration	Aberration
Ch. 25	Solar coordinates	SolarPosition
Ch. 31–36	Planetary positions	PlanetaryPosition
Ch. 33–34	Comet positions from orbital elements	CometPosition
Ch. 40	Parallax	Parallax
Ch. 41	Planetary visual magnitudes	PlanetaryMagnitude
Ch. 47	Lunar position	LunarPosition
Ch. 48	Lunar phase	LunarPosition.Phase
Ch. 49	Lunar phases (new/full moon)	Eclipse
Ch. 54	Eclipses	Eclipse
Ch. 44	Galilean satellite positions	JovianMoons
Ch. 45	Saturn ring geometry	SaturnRings

📖 U.S. Naval Observatory — Almanac for Computers

Algorithm for computing sunrise, sunset and twilight times. Implemented via a Mathcad worksheet (Ch. 3 — Astronomical Phenomena) that includes a verified worked example:

MMT Observatory, Arizona — 31°41'18" N, 110°53'06" W, 2608 m
Date: January 15, 1988
Computes sunrise, sunset and all three twilight types with observer elevation correction.

📖 W.M. Smart — Textbook on Spherical Astronomy (6th ed., Cambridge University Press, 1977)

Reference for spherical trigonometry and coordinate system transformations:

• Ch. 2–3: Equatorial ↔ ecliptic ↔ horizontal ↔ galactic transformations
• Ch. 4: Precession of the equinoxes
• Ch. 5: Annual and diurnal aberration

📖 H. Karttunen et al. — Fundamental Astronomy (3rd ed., Springer, 2003)

Supporting reference for modern theory and updated astronomical constants.

---

🛠️ Technology stack

Technology	Role
	Target framework
	Language (record structs, pattern matching, primary constructors)
	Test framework (127 tests)
	AI assistant for code and test generation

---

📊 Accuracy

Calculation	Typical accuracy	Method
Julian dates	Exact	Meeus Ch.7
Solar coordinates (low)	~1'	USNO
Solar coordinates (medium)	~0.01°	Meeus Ch.25
Sunrise/sunset	±2 min	USNO Almanac
Lunar position	~10' lon, ~3' lat	Meeus Ch.47 (simplified)
Planetary positions	~1–2'	Truncated VSOP87
Coordinate transforms	~0.01°	Rigorous spherical trigonometry

---

🎯 Design principles

• Immutability — all value types are readonly struct or record struct
• Pure functions — no side effects, easy to test
• Strong typing — Angle instead of double to prevent degree/radian confusion
• Fully referenced — every algorithm cites the chapter and equation from the original source
• double precision — sufficient for arc-second accuracy

---

📄 License

This project is licensed under the MIT License.

---

🙏 Acknowledgements

• Jean Meeus for his foundational collections of astronomical algorithms
• U.S. Naval Observatory for the sunrise/sunset algorithm
• GitHub Copilot CLI for assistance in design and implementation

---

Built with ❤️ for astronomy — from GW-BASIC on an Olivetti M80 to .NET 10.
⭐ If you find this library useful, please give it a star!