AstroCalc 0.9.6

🔭 AstroCalc

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

✨ Overview

AstroCalc 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 AstroCalc.Core;
using AstroCalc.SolarSystem;
using AstroCalc.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

📦 Project structure

AstroCalc/
├── 📐 src/AstroCalc/
│   ├── 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/AstroCalc.Tests/  # 127 xUnit tests verified against almanac data

🧮 Namespaces and classes

AstroCalc.Core — Foundation types

AstroCalc.Time — Calendar and time

AstroCalc.Coordinates — Celestial coordinates

AstroCalc.Corrections — Atmospheric and geometric corrections

AstroCalc.SolarSystem — Sun, Moon and planets

AstroCalc.Phenomena — Observable events

AstroCalc.Optics — Telescope and visual calculations 🔬

AstroCalc.Observation — Observing session planning 🌌

AstroCalc.Catalogs — Built-in object databases 📋

AstroCalc.Coordinates — Additional features

AstroCalc.Time — Additional features

🚀 Quick start

Prerequisites

• .NET 9 SDK

Build and test

# Clone the repository
git clone https://github.com/<your-username>/AstroCalc.git
cd AstroCalc

# 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/AstroCalc.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:

📖 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

🤖 Built with GitHub Copilot CLI

This project was entirely designed and implemented with GitHub Copilot CLI (powered by Claude), which:

• 📐 Analyzed the astronomy textbook PDFs to extract formulas and algorithms
• 🏗️ Designed the library architecture (6 namespaces, 24 classes)
• 💻 Generated all source code and tests
• ✅ Verified results against published almanac data
• 🔄 Iterated to fix compilation errors and failing tests

📊 Accuracy

🎯 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

<p align="center"> <i>⭐ If you find this library useful, please give it a star!</i> </p>