openunits

OpenUnits is a TypeScript orbital mechanics engine for scientific computing. It offers unit-safe APIs for orbital propagation, trajectory planning, and mission analysis — making space simulation accessible to developers, educators, and researchers.

Features

• 🪐 2-Body Keplerian Propagation — analytic mean-motion propagation
• 🔄 Elements ↔ State Vector — full transforms between Keplerian elements and Cartesian ECI
• 🚀 Maneuver Planning — Hohmann transfers, inclination changes, escape velocity, launch ΔV
• 🌍 Named Orbit Presets — LEO, MEO, GEO, SSO, HEO, TLI
• 🖥️ CLI — command-line interface with JSON (default) and table output
• 🧩 Vue 3 Integration — reactive composable useOrbit and TSX components
• 📦 Dual-format — ESM + CJS, full TypeScript types

Installation

npm install openunits
# or
pnpm add openunits

For the CLI globally:

npm install -g openunits

CLI Usage

JSON output is the default. Add --format table for human-readable output.

Show orbit info

openunits info --orbit LEO
openunits info --orbit GEO --format table
openunits info --sma 7000000 --ecc 0.01 --inc 28.5

Convert elements → state vector

openunits state --orbit LEO
openunits state --sma 7000000 --ecc 0.001 --inc 28.5 --format table

Convert state vector → elements

openunits elements --x 6558137 --y 0 --z 0 --vx 0 --vy 7784 --vz 0

Propagate an orbit

openunits propagate --orbit LEO --dt 3600
openunits propagate --orbit GEO --dt 86400 --format table

Hohmann transfer ΔV

# Using radii
openunits hohmann --r1 6778137 --r2 42164000

# Using altitudes (--altitude adds R_Earth automatically)
openunits hohmann --r1 400000 --r2 35786000 --altitude --format table

Escape velocity

openunits escape --r 6778137
openunits escape --r 400000 --altitude --format table

Launch ΔV estimate

openunits launch --alt 400000 --format table

Library Usage

import {
  namedOrbitPreset,
  elementsToState,
  propagate,
  propagateSeries,
  hohmannTransfer,
  orbitalPeriod,
  deg2rad,
  MU_EARTH,
  R_EARTH,
} from 'openunits'

// Get a named preset
const leo = namedOrbitPreset('LEO')

// Convert to state vector
const sv = elementsToState(leo)

// Propagate 1 hour forward
const result = propagate(leo, 3600)
console.log(result.state)

// Hohmann transfer LEO → GEO
const maneuver = hohmannTransfer(R_EARTH + 400_000, 42_164_000)
console.log(`Total ΔV: ${maneuver.totalDv.toFixed(0)} m/s`)

Vue 3 Integration

import { useOrbit, OrbitCard, HohmannCard } from 'openunits/vue'

useOrbit composable

const {
  elements,      // Ref<KeplerianElements>
  stateVector,   // ComputedRef<StateVector>
  period,        // ComputedRef<number> — seconds
  altitudeKm,   // ComputedRef<number>
  orbitType,     // ComputedRef<OrbitType>
  propagateBy,   // (dt: number) => PropagationResult
  generateSeries,// (duration, steps) => PropagationResult[]
  reset,
  updateElements,
} = useOrbit({ sma: 6_778_137, ecc: 0, inc: 0.9 })

TSX Components

// Display orbit parameters
<OrbitCard :elements="elements" label="My Orbit" />

// Display Hohmann transfer budget
<HohmannCard :r1="6778137" :r2="42164000" label="LEO → GEO" />

API Reference

Constants

| Symbol | Value | Description | |--------|-------|-------------| | G | 6.674×10⁻¹¹ | Gravitational constant (m³ kg⁻¹ s⁻²) | | MU_EARTH | 3.986×10¹⁴ | Earth gravitational parameter (m³/s²) | | R_EARTH | 6 378 137 | Earth equatorial radius (m) | | MU_SUN | 1.327×10²⁰ | Sun gravitational parameter (m³/s²) | | AU_M | 1.496×10¹¹ | Astronomical unit (m) |

Core Functions

| Function | Description | |----------|-------------| | elementsToState(el, μ?) | Keplerian elements → ECI state vector | | stateToElements(sv, μ?) | ECI state vector → Keplerian elements | | propagate(el, dt, μ?) | Propagate orbit by dt seconds | | propagateSeries(el, dur, n, μ?) | Generate time series of n+1 states | | propagateToEpoch(el, epoch, μ?) | Propagate to a specific epoch | | orbitalPeriod(sma, μ?) | Compute orbital period (s) | | circularVelocity(r, μ?) | Circular orbit speed at radius r | | visViva(r, sma, μ?) | Speed from vis-viva equation | | classifyOrbit(ecc) | Returns 'circular' | 'elliptic' | 'parabolic' | 'hyperbolic' | | hohmannTransfer(r1, r2, μ?) | Compute Hohmann transfer ΔV | | escapeVelocity(r, μ?) | Escape velocity at radius r | | namedOrbitPreset(name) | Get KeplerianElements for a named orbit |

License

GPL-3.0 © DeepcometAI