# `Sidereon.OrbitalElements`
[🔗](https://github.com/neilberkman/sidereon-ex/blob/main/lib/sidereon/orbital_elements.ex#L1)

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.

# `orbit_type`

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

# `t`

```elixir
@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`

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

# `coe2rv`

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

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}`.

# `mu_earth`

```elixir
@spec mu_earth() :: float()
```

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

# `rv2coe`

```elixir
@spec rv2coe(vec3(), vec3(), number()) :: {:ok, t()} | {:error, term()}
```

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 `{:error, reason}`
for a degenerate or non-finite state.

---

*Consult [api-reference.md](api-reference.md) for complete listing*