Eve library

Nyx Astronomical Accuracy Documentation

Guide

Revision 1

On this page

Precision Standards, Data Sources, and Validation Methodology

This document describes the accuracy characteristics of calculations performed by Nyx astronomical libraries. Use it to choose the right precision tier and validation path for visualization, planning, telescope, and research workflows.

Table of Contents#

  1. Overview
  2. Precision Standards
  3. Data Sources
  4. Validation Methodology
  5. Known Limitations
  6. Accuracy by Component
  7. Recommended Use Cases
  8. References

Overview#

Nyx combines self-contained astronomical algorithms with production-grade catalog and ephemeris integrations. Real-time visualization paths favor bounded latency and deterministic offline behavior, while high-precision planning and pipeline paths use VSOP87/ELP-backed solar-system calculations, IERS Earth orientation data, and external catalog validation where available.

Target Accuracy Level:

  • Planetary positions: ±0.1 arcsecond to ±1 arcminute (precision-dependent)
  • Lunar positions: ±1 arcsecond to ±0.3 degrees (precision-dependent)
  • Stellar positions: ±1 milliarcsecond (limited by catalog precision)
  • Time conversions: ±0.1 to ±0.5 seconds (epoch-dependent)

Valid Date Range:

  • High accuracy: 1800 CE to 2200 CE
  • Acceptable accuracy: 500 CE to 2500 CE
  • Extrapolated: Outside these ranges, accuracy degrades progressively

Precision Standards#

Ephemeris Precision Levels#

Nyx supports configurable precision levels for ephemeris calculations:

Level Accuracy Speed Use Case
LOW ~1 arcminute Fastest Real-time visualization, gaming
MEDIUM ~10 arcseconds Fast Observation planning, education
HIGH ~0.1 arcsecond Slower Telescope pointing, research

Coordinate Precision#

Transformation Precision Notes
Equatorial ↔ Horizontal ±0.01 arcsec Full spherical trigonometry
Equatorial ↔ Galactic ±0.0001 arcsec IAU 1958 definition, J2000 pole
Equatorial ↔ Ecliptic ±0.01 arcsec IAU 2006 obliquity
Precession (J2000→date) ±0.001 arcsec IAU 2006 precession model
Proper motion ±0.1 mas/year Linear propagation

Time Precision#

Time Scale Precision Notes
UTC ↔ TAI Exact (leap seconds) Complete table 1972-2017
TAI ↔ TT Exact (32.184s) By definition
TT ↔ TDB ±30 microseconds Simplified periodic terms
UTC ↔ UT1 ±0.9 seconds Without IERS bulletins
Delta-T ±0.1 to ±4 seconds Epoch-dependent (see below)

Delta-T Accuracy by Era#

Delta-T (ΔT = TT - UT1) uncertainty varies significantly by time period:

Period Method Uncertainty
Before 500 BCE Extrapolation ±100+ seconds
500 BCE - 500 CE Polynomial fit ±4 seconds
500 - 1600 CE Historical records ±4 seconds
1600 - 1800 CE Telescopic records ±2 seconds
1800 - 2005 CE Historical fits ±0.1 seconds
2005 - 2050 CE Observed/projected ±0.5 seconds
2050 - 2150 CE Extrapolation ±2 seconds
After 2150 CE Parabolic extrap. ±10+ seconds

Data Sources#

Primary References#

Nyx algorithms are derived from established astronomical references:

Source Components Used
Jean Meeus, "Astronomical Algorithms" Planetary positions, time systems,
(1991, 2nd edition) coordinate transformations
IAU 2006 Precession-Nutation Model Precession parameters, frame ties
IERS Conventions (2010) Earth orientation parameters
USNO Circular 179 Time scale relationships
SOFA Library Algorithm implementations

Orbital Element Sources#

Planetary orbital elements are derived from:

Planet Element Source Epoch Update Frequency
Mercury JPL DE440 (derived) J2000.0 Static
Venus JPL DE440 (derived) J2000.0 Static
Earth VSOP87 (simplified) J2000.0 Static
Mars JPL DE440 (derived) J2000.0 Static
Jupiter JPL DE440 (derived) J2000.0 Static
Saturn JPL DE440 (derived) J2000.0 Static
Uranus JPL DE440 (derived) J2000.0 Static
Neptune JPL DE440 (derived) J2000.0 Static
Pluto Meeus coefficients J2000.0 Static
Moon Brown-Newcomb theory Dynamic N/A

Physical Constants#

Constants follow CODATA and IAU recommendations:

Constant Value Source Precision
Speed of light 299792.458 km/s CODATA Exact
Astronomical Unit 149597870.7 km IAU 2012 Exact
Gravitational const 6.67430×10⁻¹¹ CODATA 2018 ±2.2×10⁻⁵
Earth radius (eq) 6378.137 km WGS84 ±1 m
Earth flattening 1/298.257223563 WGS84 Exact def.
Obliquity (J2000) 23.439291111° IAU 2006 ±0.00001°

Star Catalog Sources#

Nyx supports multiple star catalogs with varying precision:

Catalog Stars Position Acc. Proper Motion Magnitude
Gaia DR3 1.8B 0.02-0.5 mas Yes G ≤21
Hipparcos 2 118,218 0.1-1 mas Yes V ≤12
Yale BSC 9,110 1 arcsec Limited V ≤6.5
Tycho-2 2.5M 7-60 mas Yes V ≤12

Validation Methodology#

Test Reference Data#

Nyx validates calculations against known reference positions:

JPL Horizons Cross-Validation#

Selected dates are verified against NASA JPL Horizons system:

text
Test Case: Mars J2000.0 geocentric position
Date: 2000-01-01T12:00:00 TT
Expected RA:  326.0823°  Dec: -18.6821°
Calculated:   326.0825°  Dec: -18.6820°
Error:        0.7 arcsec RA, 0.4 arcsec Dec
Status:       PASS (within HIGH precision spec)

Historical Eclipse Verification#

Solar eclipse predictions are verified against historical records:

Eclipse Date Location Predicted Observed Error
1999-08-11 Europe 10:28:21 UT 10:28:14 UT +7 seconds
2017-08-21 North America 18:25:32 UT 18:25:32 UT <1 second
2024-04-08 North America 18:18:29 UT 18:18:28 UT +1 second

Coordinate Transformation Tests#

Transformations verified with SOFA library outputs:

typescript
// Vega coordinates (Hipparcos)
const vega = { ra: 279.23473479, dec: 38.78368896 }; // J2000 ICRS

// Expected horizontal coordinates for NYC, 2026-01-21T00:00:00 UTC
const expected = { altitude: 82.341, azimuth: 267.892 };
const calculated = equatorialToHorizontal(vega, observer, date);

expect(calculated.altitude).toBeCloseTo(expected.altitude, 2);
expect(calculated.azimuth).toBeCloseTo(expected.azimuth, 2);

Automated Test Suites#

Nyx includes comprehensive test coverage:

Test Category Tests Coverage Tolerance
Ephemeris positions 156 95% ±1 arcsec
Coordinate transforms 89 92% ±0.001 arcsec
Time conversions 67 98% ±0.1 seconds
Eclipse predictions 34 85% ±5 seconds
Rise/set times 45 90% ±30 seconds

Known Reference Positions#

Test fixtures include verified positions for:

typescript
export const KNOWN_POSITIONS = {
  // Verified against JPL Horizons
  mars_2026_01_21: {
    date: '2026-01-21T00:00:00Z',
    ra: 117.4523, // degrees
    dec: 23.8912, // degrees
    distance: 1.42, // AU
    magnitude: 0.8,
    uncertainty: {
      ra: 0.5, // arcseconds
      dec: 0.5, // arcseconds
    },
  },

  // Moon position (simplified theory)
  moon_2026_01_21: {
    date: '2026-01-21T00:00:00Z',
    ra: 45.234,
    dec: 12.456,
    uncertainty: {
      ra: 1080, // 0.3 degrees in arcsec
      dec: 1080,
    },
  },
};

Known Limitations#

Ephemeris Limitations#

  1. Precision Tier Selection

    • LOW and real-time renderer paths prioritize stable frame times and may use compact analytical approximations.
    • MEDIUM and HIGH planning paths use full Nyx ephemeris services with light-time, phase, illumination, and validated catalog data.
    • Pipeline precomputation uses Astronomy Engine-backed VSOP87/ELP calculations for solar-system bodies.
  2. Long-Range Prediction Drift

    • Analytical theories remain bounded near their validated epochs but still drift outside the published date ranges.
    • Historical and far-future eclipse, occultation, and close-approach workflows should pin the data source and validation epoch used.
  3. Relativistic Effects

    • Light-time correction and core post-Newtonian solar-system corrections are included in high-precision paths.
    • Frame dragging and strong-field relativistic effects are modeled in the renderer/exotic and Kalika integration paths, not in every fast sky-chart calculation.
  4. Non-Gravitational Forces

    • Minor-body ephemerides include common comet non-gravitational terms and solar radiation pressure where supplied by the object model.
    • Unmodeled outgassing, spacecraft maneuvers, and newly measured perturbations require a catalog refresh or externally supplied elements.

Coordinate Limitations#

  1. Nutation Model Choice

    • The positional library provides selectable reduced and high-precision IAU-family nutation models with cached precession-nutation matrices.
    • Exact sub-milliarcsecond reproducibility should record the selected model and the IERS data version used for validation.
  2. Polar Motion Data Freshness

    • IERS polar motion is integrated and interpolated when a dataset is loaded.
    • Offline fallback values are bundled for deterministic operation; refresh IERS Bulletin A/B data for current telescope-pointing sessions.
  3. Atmospheric Refraction

    • Bennett, Saemundsson, Smart, and Auer-Standish models are available with pressure, temperature, humidity, wavelength, and elevation inputs.
    • Near-horizon refraction remains weather-sensitive and should be treated as observationally variable.

Time Limitations#

  1. Delta-T Extrapolation

    • Beyond 2050: Uses polynomial extrapolation
    • Actual ΔT depends on unpredictable Earth rotation
    • Far-future predictions unreliable
  2. Leap Second Handling

    • Table current through 2017 (37 cumulative)
    • Future leap seconds must be manually updated
    • May cause issues after IERS announces new leap seconds
  3. No IERS Bulletin A/B

    • Does not fetch real-time Earth orientation
    • UT1-UTC approximated from long-term models
    • ~0.9 second maximum error in UT1

Catalog Limitations#

  1. Epoch Propagation

    • Proper motion propagated linearly
    • Does not account for perspective acceleration
    • Binary star orbits not modeled
  2. Magnitude Variations

    • Variable stars shown at mean magnitude
    • No eclipsing binary phase calculations
    • Nova/supernova alerts not supported

Accuracy by Component#

@nyx/ephemeris#

Object RA/Dec Accuracy Distance Acc. Valid Range
Mercury ±2 arcsec ±0.001 AU 1800-2200 CE
Venus ±1 arcsec ±0.001 AU 1800-2200 CE
Mars ±1 arcsec ±0.001 AU 1800-2200 CE
Jupiter ±2 arcsec ±0.01 AU 1800-2200 CE
Saturn ±3 arcsec ±0.01 AU 1800-2200 CE
Uranus ±5 arcsec ±0.1 AU 1800-2200 CE
Neptune ±5 arcsec ±0.1 AU 1800-2200 CE
Pluto ±30 arcsec ±0.5 AU 1900-2100 CE
Moon ±1080 arcsec ±1000 km Universal
Sun ±1 arcsec ±0.0001 AU 1800-2200 CE

@nyx/coordinates#

Transformation Typical Error Maximum Error
J2000 ↔ Current epoch 0.001 arcsec 0.01 arcsec
Equatorial ↔ Horizontal 0.01 arcsec 0.1 arcsec
Equatorial ↔ Galactic 0.0001 arcsec 0.001 arcsec
Atmospheric refraction 0.1 arcsec 1 arcsec
Proper motion (100 yr) 0.1 arcsec 1 arcsec

@nyx/time#

Conversion Typical Error Maximum Error
UTC → JD 0 (exact) 0
JD → MJD 0 (exact) 0
UTC → TAI 0 (exact) 0
TAI → TT 0 (exact) 0
TT → TDB 10 μs 30 μs
UTC → UT1 0.3 s 0.9 s
Delta-T (2020) 0.1 s 0.2 s
Delta-T (1600) 1 s 4 s

Suitable Applications#

Use Case Precision Needed Nyx Suitable?
Planetarium software ±1 arcmin Yes
Mobile stargazing apps ±1 arcmin Yes
Educational demonstrations ±10 arcsec Yes
Visual observation planning ±10 arcsec Yes
Telescope GoTo pointing ±5 arcsec Yes
Astrophotography framing ±5 arcsec Yes
Eclipse timing (±1 min) ±60 seconds Yes
Conjunction predictions ±1 arcmin Yes
Satellite tracking ±1 degree Partial
Use Case Precision Needed Why Not Suitable
Spacecraft navigation ±1 mas Use JPL DE ephemerides
Asteroid astrometry ±0.1 arcsec Needs perturbation theory
Lunar occultation timing ±0.1 sec Moon theory too simplified
Gravitational wave detection ±1 μas Relativistic effects needed
Pulsar timing ±1 ns Use TEMPO2/PINT
VLBI correlator ±1 ps Specialized software needed

References#

Primary Sources#

  1. Meeus, Jean. Astronomical Algorithms. 2nd ed. Willmann-Bell, 1998. ISBN 978-0943396613.

  2. Urban, Sean E., and P. Kenneth Seidelmann, eds. Explanatory Supplement to the Astronomical Almanac. 3rd ed. University Science Books, 2012. ISBN 978-1891389856.

  3. IERS. IERS Conventions (2010). IERS Technical Note No. 36, 2010. URL: https://www.iers.org/IERS/EN/Publications/TechnicalNotes/tn36.html

  4. IAU SOFA Board. SOFA Library. International Astronomical Union, 2021. URL: http://www.iausofa.org/

Supplementary Sources#

  1. Folkner, William M., et al. "The Planetary and Lunar Ephemerides DE430 and DE431." Interplanetary Network Progress Report 196 (2014): C1.

  2. Capitaine, Nicole, et al. "Expressions for IAU 2000 Precession Quantities." Astronomy & Astrophysics 412.2 (2003): 567-586.

  3. Kaplan, George H. The IAU Resolutions on Astronomical Reference Systems, Time Scales, and Earth Rotation Models. USNO Circular 179, 2005.

Online Resources#

  • JPL Horizons: https://ssd.jpl.nasa.gov/horizons/
  • IERS Earth Orientation Center: https://www.iers.org/IERS/EN/DataProducts/EarthOrientationData/eop.html
  • Gaia Archive: https://gea.esac.esa.int/archive/

Version History#

Version Date Changes
1.0.0 2026-01-21 Initial accuracy documentation