Sidereon.OrbitalElements (Sidereon v3.0.0)

Classical (Keplerian) orbital elements and the two-body state transforms.

Converts between a Cartesian state (position in km, velocity in km/s) and the classical element set via the sidereon-core astro::elements kernels (rv2coe / coe2rv). Angles are in radians, the crate's native element unit; distances are in km and mu is in km^3/s^2 (defaulting to Earth's gravitational parameter).

This struct is distinct from Sidereon.Elements, which holds the mean TLE/OMM element set used to seed SGP4. The orbit_type tag reports which auxiliary angle (arglat, truelon, lonper) carries the meaningful value for a degenerate (circular and/or equatorial) orbit.

Summary

Types

boundary_error()

coe2rv_error()

elements_error()

native_call()

orbit_type()

rv2coe_error()

t()

vec3()

Functions

coe2rv(coe, mu \\ 398_600.4418)

Cartesian position (km) and velocity (km/s) from a classical element set.

mu_earth()

Earth's gravitational parameter in km^3/s^2, the default mu.

rv2coe(r, v, mu \\ 398_600.4418)

Classical orbital elements from a Cartesian state.

Types

boundary_error()

@type boundary_error() ::
  {:invalid_argument, native_call()} | {:arithmetic_error, native_call()}

coe2rv_error()

@type coe2rv_error() ::
  elements_error() | boundary_error() | {:unknown_orbit_type, term()}

elements_error()

@type elements_error() ::
  {:orbital_elements,
   :non_positive_mu
   | :zero_position
   | :degenerate_orbit
   | :non_positive_semi_latus, nil}
  | {:orbital_elements, :non_finite, String.t()}

native_call()

@type native_call() :: :elements_rv2coe | :elements_coe2rv

orbit_type()

@type orbit_type() ::
  :elliptical_inclined
  | :elliptical_equatorial
  | :circular_inclined
  | :circular_equatorial

rv2coe_error()

@type rv2coe_error() :: elements_error() | boundary_error()

t()

@type t() :: %Sidereon.OrbitalElements{
  a: float(),
  arglat: float() | nil,
  argp: float() | nil,
  ecc: float(),
  incl: float(),
  lonper: float() | nil,
  nu: float() | nil,
  orbit_type: orbit_type(),
  p: float(),
  raan: float() | nil,
  truelon: float() | nil
}

vec3()

@type vec3() :: {number(), number(), number()}

Functions

coe2rv(coe, mu \\ 398_600.4418)

@spec coe2rv(t(), number()) ::
  {:ok, %{position_km: vec3(), velocity_km_s: vec3()}}
  | {:error, coe2rv_error()}

Cartesian position (km) and velocity (km/s) from a classical element set.

coe is a %Sidereon.OrbitalElements{} (angles in radians); mu is the gravitational parameter in km^3/s^2 (default Earth). The orbit_type tag selects which auxiliary angle the core reads for a degenerate orbit. Returns {:ok, %{position_km: {x, y, z}, velocity_km_s: {vx, vy, vz}}} or {:error, reason} with the same typed core reasons as rv2coe/3, or {:error, {:unknown_orbit_type, value}} when the orbit_type tag is not recognized. Invalid native-call arguments and BEAM numeric conversion overflow retain the corresponding :elements_coe2rv boundary reasons.

mu_earth()

@spec mu_earth() :: float()

Earth's gravitational parameter in km^3/s^2, the default mu.

rv2coe(r, v, mu \\ 398_600.4418)

@spec rv2coe(vec3(), vec3(), number()) :: {:ok, t()} | {:error, rv2coe_error()}

Classical orbital elements from a Cartesian state.

r is the position {x, y, z} in km, v the velocity {vx, vy, vz} in km/s, and mu the gravitational parameter in km^3/s^2 (default Earth). Returns {:ok, %Sidereon.OrbitalElements{}} (angles in radians) or a typed {:error, reason}. Core refusals use {:orbital_elements, kind, field}: kind is :non_finite (with the offending input field as a string), :non_positive_mu, :zero_position, :degenerate_orbit, or :non_positive_semi_latus. The field is nil for finite-domain refusals. Invalid native-call arguments and BEAM numeric conversion overflow retain the {:invalid_argument, :elements_rv2coe} and {:arithmetic_error, :elements_rv2coe} boundary reasons.