Astrodynamics

IO.Astrodynamics

A modern .NET astrodynamics toolkit powered by NASA/JPL NAIF SPICE. IO.Astrodynamics delivers SPICE accuracy with a productive .NET API; a thin, stable C++ layer provides fast interop with CSPICE.

Documentation

The reference documentation lives at docs.io-aerospace.org:

• Quick Start — install, load kernels, first calculations
• Tutorials — ephemeris queries, coordinate conversions, orbit creation, TLE & OMM, numerical propagation, maneuvers, geometry & visibility, mission design
• API Reference — types, methods, and parameters
• Guides — kernel management, thread safety, high-fidelity propagation, Cosmographia export, validation
• Standards & Units — SI units, frame and time conventions
• Contributing — how to contribute, versioning policy, migration notes

A single-file companion reference is also kept in this repository: DEVELOPER_GUIDE.md.

Install

dotnet add package IO.Astrodynamics

Requirements:

• .NET 10 — the package targets net10.0 only
• Supported runtimes: win-x64, linux-x64, osx-arm64, osx-x64. Native CSPICE interop is bundled for all four and resolved automatically by the NuGet runtime asset layout
• SPICE kernels: you must supply the kernels required for your computations (see Getting SPICE data)

Quick start (C#)

Load kernels once at startup, then query ephemerides, frames, and more.

using System;
using System.IO;
using IO.Astrodynamics;
using IO.Astrodynamics.Body;
using IO.Astrodynamics.Frames;
using IO.Astrodynamics.SolarSystemObjects;
using IO.Astrodynamics.TimeSystem;

// Load required kernels (recursively) from your data directory
SpiceAPI.Instance.LoadKernels(new DirectoryInfo("Data/SolarSystem"));

// Moon state relative to Earth at 2000-01-01T12:00Z, expressed in ICRF
var earth = new CelestialBody(PlanetsAndMoons.EARTH);
var moon = new CelestialBody(PlanetsAndMoons.MOON);
var epoch = new Time(new DateTime(2000, 1, 1, 12, 0, 0), TimeFrame.UTCFrame);

var state = moon.GetEphemeris(epoch, earth, Frame.ICRF, Aberration.None).ToStateVector();

Console.WriteLine($"Position: {state.Position} m");
Console.WriteLine($"Velocity: {state.Velocity} m/s");

More worked examples: docs.io-aerospace.org/tutorials.

What you can do

• Orbital parameters — compute and convert State Vector, Keplerian, Equinoctial, TLE (mean and osculating). Mean elements keep their precision; use ToOsculating() before any state-vector math. NORAD catalog numbers beyond the 5-digit range are handled through the Alpha-5 convention, up to 339999.
• Ephemerides — SPICE-backed ephemeris for bodies, spacecraft, sites and stars, with light-time and stellar aberration corrections. A reference-body strategy avoids solar-system-barycenter round-trips, cutting SPICE calls and allocations for spacecraft- or site-relative ephemeris.
• Numerical propagation — central-body propagator with a segment-based loop and event-driven maneuver execution: EGM2008 geopotential gravity (degree/order up to 70, validated against GMAT), atmospheric drag with co-rotation (Earth, Mars), solar radiation pressure with Cr and continuous shadow fraction, albedo and thermal radiation pressure, Battin’s third-body perturbations, dynamic mass and fuel balance, dense output at the accuracy of the integrator in RK7(8) (shortened RK7(8) steps), cubic Hermite with Velocity-Verlet. A 60-second ephemeris grid with 8-point Lagrange interpolation feeds the force models.
• State transition matrix and covariance — in RK7(8), the state transition matrix Φ, the sensitivity Ψ to Cd and Cr, and the covariance P propagated with the state (off by default): RTN process noise, Cd and Cr as consider parameters with the extended covariance, the execution error of impulsive maneuvers (model of Gates), read at any epoch of the solution; StateVector.WithRemediatedCovariance() for an initial covariance that rounding made indefinite. Validated against central differences, a Monte Carlo (with its measured domain of validity) and GMAT.
• Integrators — Velocity-Verlet symplectic fixed-step, and the adaptive 13-stage Prince-Dormand RK7(8) with embedded 7th-order error estimate, PI step control and sub-step event refinement by bisection (~1e-10 s).
• Maneuvers — Lambert transfers, apogee/perigee height changes, plane and apsidal alignment, phasing, combined maneuvers, all triggered by industry-standard g-function zero-crossing event detection.
• Space situational awareness — conjunction screening and analysis, Foster 2D collision probability with the covariance of each participant propagated in RK7(8) to the time of closest approach (its source stated per participant), maximum probability at a single covariance, an optional non-linearity index, encounter quality indicators, and avoidance manoeuvre evaluation with each option propagated numerically.
• Batch and statistical analysis — fluent propagator builder, batch propagation of many spacecraft, and Monte Carlo dispersion analysis with per-epoch statistics and RSS percentiles.
• Attitudes — instrument pointing, nadir/zenith, prograde/retrograde, normal/anti-normal, TRIAD fully-constrained 3-DOF pointing with orbital and celestial targets, configurable body axes.
• Launch and mission analysis — launch windows from a launch site to a target orbit, scenario definition and simulation, fuel budgets.
• Atmospheric modeling — unified IAtmosphericModel interface returning an Atmosphere record. Earth: U.S. Standard Atmosphere 1976 and NRLMSISE-00 with space weather. Mars: standard analytical model. Earth picks NRLMSISE-00 automatically when the full context is available.
• Frames and coordinates — ICRF/J2000, Ecliptic (J2000/B1950), TEME, Galactic, FK4, body-fixed/ITRF93, the CIO-based IAU chain (IAU 2006 precession with IAU 2000B nutation: GCRF, CIRS, TIRS) with pluggable Earth orientation parameters, plus Equatorial, Horizontal, Planetodetic and Planetographic coordinates.
• Time systems — Calendar, Julian, TDB, TAI, TDT, UTC, GPS and local time, with conversions.
• Event finding — distance, occultation, coordinate and illumination constraints; instrument field-of-view windows.
• CCSDS messages — OMM (Orbit Mean-elements Message), OPM (Orbit Parameter Message) and CDM (Conjunction Data Message) reading, writing and schema validation, with bidirectional OMM↔TLE and OPM↔Spacecraft conversion and EncounterCase.ToCdm() export, a propagated covariance with its consider parameters (CDRG_*, CSRP_*) and the force model of the propagation.
• Spacecraft configuration — clocks, fuel tanks, engines, instruments, configurable body axes.
• Interoperability — SPICE kernel and star-catalog handling, Cosmographia export, PDS archive tooling (generate, materialize objects, validate against XML schemas).
• Math helpers — vectors, matrices, planes, quaternions, Jacobians, Lagrange interpolation, geodesy-normalized Legendre functions with derivatives, SLERP/LERP.
• CLI — common tasks straight from the shell (see below).

How it works

• SPICE data: you supply the NAIF kernels (ephemerides, planetary constants, leap seconds, mission data)
• Native bridge: a small C++ interop library talks to CSPICE for performance-critical calls (frozen API)
• .NET SDK: the rich, evolving API surface for modeling, propagation and analysis
• CLI: command-line tools built on the .NET SDK for quick analyses

Background reading: SPICE concept and SPICE data.

The C++ layer is feature-frozen and exists only to communicate with SPICE. All new features and APIs land in the .NET projects.

Getting SPICE data

You provide the kernels relevant to your scenario. A common set:

• Leap seconds (e.g. naif0012.tls)
• Planetary constants (.tpc / PCK files)
• Ephemerides (e.g. de440.bsp, plus planetary and spacecraft SPKs)
• Frame kernels and spacecraft clocks as needed

Organize them in a directory and load them recursively:

SpiceAPI.Instance.LoadKernels(new DirectoryInfo("Data/SolarSystem"));

A single file works too:

SpiceAPI.Instance.LoadKernels(new FileInfo("de440.bsp"));

See the kernel management guide for layout and precedence rules.

Using the CLI

The CLI ships as a .NET global tool named astro:

dotnet tool install -g IO.Astrodynamics.CLI
astro --help

Or run it from a clone of this repository:

dotnet run --project IO.Astrodynamics.Net/IO.Astrodynamics.CLI -- --help

Available commands: ephemeris, propagate, orientation, sub-point, angular-separation, celestial-body-info, orbital-parameters-converter, frame-converter, time-converter, and the window finders find-windows-from-distance-constraint, find-windows-from-occultation-constraint, find-windows-from-coordinate-constraint, find-windows-from-illumination-constraint, find-windows-from-FOV-constraint.

Native C++ interop (frozen)

The native C++ library exists only as a high-performance bridge to CSPICE. It won’t receive new features (only safety and correctness fixes). If you need to link it directly:

• Download prebuilt binaries from Releases
• Linux: install the headers to /usr/local/include/IO and libIO.Astrodynamics.so to /usr/local/lib
• macOS: place libIO.Astrodynamics.dylib alongside your app (arm64 and x64 builds are provided) and include the headers
• Windows: place IO.Astrodynamics.dll / .lib alongside your app and include the headers

The native library and the .NET assembly must come from the same release — P/Invoke signatures are version-coupled. Prefer the .NET SDK for all new work.

Contributing

Contributions to the .NET SDK, CLI, docs and tests are welcome; the native layer accepts only fixes and performance or stability improvements. Please read CONTRIBUTING.md and the code of conduct. Security reports: see SECURITY.md.

Sponsoring

Building and sustaining a .NET-first astrodynamics toolkit on top of SPICE takes significant effort: keeping pace with SPICE releases and kernel updates, evolving the .NET API, CLI and documentation, cross-platform packaging and CI, extensive tests and validation against reference data, new features and scenarios, and community support.

You can help by sponsoring the project through GitHub Sponsors, through a company sponsorship to prioritize features, integrations or support, by backing specific issues, or by contributing kernel sets, scenarios and docs. Funds go to .NET SDK and CLI development, documentation and examples, validation datasets and automated QA, and release engineering across platforms.

Services

The framework is free; IO Aerospace funds its development through services around it: annual support with a contractual response time, integration work, validation reports against reference trajectories, training, and a hosted MCP server for AI-assisted mission analysis. See Services, or get in touch through io-aerospace.org.

Disclaimer

THIS SOFTWARE IS PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND.

IO.Astrodynamics is distributed under the GNU Lesser General Public License v3.0 or later (LGPL-3.0-or-later). By using this software, you acknowledge and agree that:

• The software is provided without any warranty, express or implied, including but not limited to the implied warranties of merchantability and fitness for a particular purpose
• The authors and contributors are not liable for any damages, losses, or consequences arising from the use or inability to use this software
• Users are solely responsible for validating all results before use in any application
• This software is NOT certified for flight-critical, safety-critical, or life-critical applications
• Independent verification and validation (IV&V) is required before use in operational mission planning or spacecraft operations
• Results should be cross-checked against authoritative sources (e.g. JPL Horizons, GMAT, FreeFlyer or equivalent tools) for critical applications

The algorithms implemented are based on publicly available literature and the NAIF SPICE toolkit. While we strive for accuracy, computational results may contain errors. You assume all risk associated with using this software.

See the LICENSE file, together with GPL-3.0.txt, for complete terms.

License and acknowledgments

• License: LGPL-3.0-or-later — see LICENSE. The LGPL v3 incorporates the terms of the GNU GPL v3, supplied verbatim in GPL-3.0.txt
• Built on NASA/JPL NAIF SPICE, developed by the Navigation and Ancillary Information Facility (NAIF) at JPL