WilliamForney.Ephemeris 0.1.1

Ephemeris

A .NET 10 library for computing positions of celestial bodies (Sun, Moon, planets, and stars) as seen from any observer location on Earth.

Features

Projects

Architecture

Domain namespaces mirror astronomical subdisciplines:

Public entry points are in the root Ephemeris namespace:

• EphemerisCalculator — single-instant position queries for Sun, Moon, and planets
• EphemerisBatch — generates time-series EphemerisRecord collections
• EphemerisPlotter — ASCII console visualization

Build & Test

dotnet restore
dotnet build
dotnet test

Integration tests that require local ephemeris kernel files (BSP, SE1) are skipped automatically when the files are not present.

Installation

dotnet add package WilliamForney.Ephemeris

Or add directly to your project file:

<PackageReference Include="WilliamForney.Ephemeris" Version="x.y.z" />

Or via the NuGet Package Manager console:

Install-Package WilliamForney.Ephemeris

Usage

// Single-instant Sun position
var result = EphemerisCalculator.GetSunPosition(
    DateTime.UtcNow, longitude: -87.65, latitude: 41.85);
Console.WriteLine($"Az: {result.Azimuth:F2}°  Alt: {result.Altitude:F2}°");

// Moon position with topocentric parallax (observer at 200 m elevation)
var moon = EphemerisCalculator.GetMoonPosition(
    DateTime.UtcNow, -87.65, 41.85, altitudeMeters: 200);
Console.WriteLine($"Phase: {moon.Illumination * 100:F1}%  Alt: {moon.Altitude:F2}°");

// Next-event queries
var calc = new EphemerisCalculator();
var nextFull    = calc.NextFullMoon(DateTime.UtcNow);
var nextSunrise = calc.NextSunrise(DateTime.UtcNow, longitude: -87.65, latitude: 41.85);
var nextEquinox = calc.NextVernalEquinox(DateTime.UtcNow.Year);

// Rise/set/transit for today
var riseSet = RiseSetCalculator.Sun(DateTime.UtcNow, longitude: -87.65, latitude: 41.85);
Console.WriteLine($"Sunrise: {riseSet.Rise}  Transit: {riseSet.Transit}  Sunset: {riseSet.Set}");

// Eclipse prediction
var nextSolar = EclipseCalculator.NextSolarEclipse(DateTime.UtcNow);
Console.WriteLine($"Next solar eclipse: {nextSolar.DateTime} ({nextSolar.Type})");

// Time-series batch for the Moon
var records = EphemerisBatch.GenerateMoonSeries(
    DateTime.UtcNow, intervalMinutes: 10, count: 144,
    longitude: -87.65, latitude: 41.85);

// Visibility windows (when altitude > 10°)
var windows = EphemerisBatch.VisibilityWindows("Moon",
    DateTime.UtcNow, TimeSpan.FromDays(7),
    longitude: -87.65, latitude: 41.85, altThreshold: 10.0);

// Stellar catalog — built-in 25-star catalog, or load from Yale BSC5
var catalog = StarCatalog.LoadBuiltIn();
var sirius   = catalog.GetByName("Sirius");
var bright   = catalog.GetBrighter(2.0);                    // stars brighter than magnitude 2
var inRegion = catalog.GetInRegion(ra: 80, dec: -10, radiusDeg: 20);

// Apply proper-motion + precession to current epoch
var siriusNow = sirius!.AtEpoch(TimeZoneUtils.ToJulianDay(DateTime.UtcNow));

// Native SPICE BSP kernel reader (place de440s.bsp or similar in ~/ephem-data/)
var db = new SpiceKernelDatabase();
db.LoadKernel("/path/to/de440s.bsp");
double et = db.ConvertUtcToEphemerisTime(DateTime.UtcNow); // leap-second-aware ET
double[] pos = db.GetPosition("SUN", et, "J2000", "EARTH"); // [x, y, z] km (ICRF)

// Or use BspImporter for a full time-series pipeline
var bspRecords = BspImporter.LoadFromBspKernel(
    kernelPaths: ["/path/to/de440s.bsp"],
    target: "SUN", observer: "EARTH",
    startUtc: DateTime.UtcNow, intervalMinutes: 60, count: 24,
    longitude: -87.65, latitude: 41.85);

Accuracy

For detailed algorithm documentation, formula derivations, and source references, see the Algorithm Reference wiki page.

Coordinate conventions

All angles are degrees at the API boundary; internal trigonometry converts to radians inline.

Coordinate record types (readonly record struct) in Ephemeris.Geometry: EquatorialCoordinates, HorizontalCoordinates, EclipticCoordinates, CartesianPosition

Format documentation

Reference documents in docs/ and on the GitHub Wiki:

Documentation

• GitHub Wiki — algorithm reference, format specifications, and development guides
• Algorithm Reference — all algorithms with formulas and Meeus/IAU citations
• Each project has its own README.md with project-specific details

Roadmap

Completed

• ✅ Foundation: Julian Day, GMST, sidereal time, coordinate transforms
• ✅ Solar ephemeris (Meeus Ch. 25), lunar ephemeris (Meeus Ch. 47)
• ✅ Topocentric parallax (Meeus Ch. 40) for Moon, Sun, and all planets
• ✅ Planetary positions, nutation, precession, atmospheric refraction
• ✅ Rise/set/transit (Meeus Ch. 15), seasons (Ch. 27), eclipses (Ch. 54)
• ✅ Stellar catalog — embedded 25-star subset + Yale BSC5 reader, proper-motion & IAU 2006 precession
• ✅ Native DAF/SPK BSP reader — Type 2/3 Chebyshev, leap-second-aware UTC→ET, BFS segment graph for arbitrary multi-hop chaining
• ✅ OpenGL/Skia 3D sky view — SkyViewForm renders stars, Sun, Moon, planets with OpenTK 4 GLControl + SkiaSharp label overlay; launcher (LauncherForm) added to Ephemeris.UI
• ✅ Planetary event calculators — opposition, conjunction, quadrature for outer planets; greatest elongation for inner planets
• ✅ 420 unit tests verified against JPL Horizons and synthetic reference values
• ✅ BenchmarkDotNet project, NuGet packaging, CI coverage reporting

Research App (completed 2026-03-22)

• ✅ CelestialResearchService + WorkspaceViewModel — research workspace foundation
• ✅ ResearchWorkspaceWindow — Sun/Moon data sidebar, scenario picker, historical mode badge
• ✅ PlaybackEngine, ScripturalEventLibraryWindow, NotesPanel, JSON session persistence
• ✅ ComparisonViewModel + ComparisonWindow with simulation override (freeze, Sun-offset, daylight)
• ✅ HomeWindow startup screen + dark observatory theme (ResearchTheme.axaml)
• ✅ CelestialEventDetector — full/new moons, equinoxes, solstices, eclipse scanning
• ✅ Constellation overlays + SkyDisplayToggleBar display controls
• ✅ ProlepticDate — BCE/BC date struct for Hezekiah (~701 BCE) and Joshua (~1406 BCE) scenarios
• ✅ Mazzaroth ecliptic overlay in SkyGlControl
• ✅ BiblicalCalendarHelper — Hebrew calendar, Mazzaroth signs, crescent moon visibility

Future

No planned items at this time — contributions welcome!

Dependencies

• ScottPlot 5 — charting (core library and WinForms UI)
• Scrutor — DI assembly scanning
• DotNext — advanced .NET utilities and async threading
• Generator.Equals — source-generated equality for record types
• Microsoft.Extensions.Hosting — dependency injection and service hosting
• CommunityToolkit.Mvvm — MVVM helpers (UI)
• OpenTK + SkiaSharp — OpenGL and Skia rendering (used in SkyViewForm)
• BenchmarkDotNet — performance benchmarking
• TUnit — test framework
• Verify.TUnit — snapshot testing
• Imposter — compile-time source-generated mocks

Contributing

Contributions are welcome! Please:

1. Fork the repository and create a feature branch: feat/<scope>/<description>
2. Follow the existing code style (4-space indent, nullable reference types, XML docs on all public and non-trivial private members)
3. Add or update tests in Ephemeris.Tests for any changed behaviour — all existing tests must continue to pass
4. Ensure dotnet build and dotnet test pass with no warnings
5. Open a pull request against main — the CI workflow will run build + tests automatically

See .github/copilot-instructions.md for architectural conventions, commit message format, and domain namespace guidance.

License

See LICENSE for details.