urania 0.0.1__py3-none-any.whl

urania/__init__.py

@@ -0,0 +1,19 @@
+"""urania — an astrodynamics library that computes, shows and explains."""
+
+from .bodies import Body, Earth, Mars, Moon, Sun
+from .environment import Environment
+from .maneuvers import Burn, Transfer
+from .orbits import GEO, ISS, LEO, SSO, Orbit, sun_synchronous
+from .propagation import PropagationInfo, Trajectory
+from .time import J2000, Epoch
+from .tle import TLEOrbit
+
+__version__ = "0.0.1"
+
+__all__ = [
+    "Body", "Earth", "Mars", "Moon", "Sun",
+    "Orbit", "sun_synchronous", "LEO", "ISS", "SSO", "GEO",
+    "Epoch", "J2000",
+    "Environment", "Trajectory", "PropagationInfo", "Transfer", "Burn",
+    "TLEOrbit",
+]

urania/bodies.py

@@ -0,0 +1,90 @@
+"""Celestial body objects and presets."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from . import units
+from .environment import ExponentialAtmosphere
+from .constants import G
+
+
+@dataclass(frozen=True)
+class Body:
+    """Central body. All values are SI.
+
+    Stores μ (GM) as the primary value: it is measured directly and is far more accurate than the mass.
+    """
+
+    name: str
+    mu: float                   # gravitational parameter GM [m³/s²]
+    radius: float               # equatorial radius [m]
+    J2: float = 0.0             # second zonal harmonic [-]
+    rotation_rate: float = 0.0  # rotation rate [rad/s] (sidereal)
+    flattening: float = 0.0     # reference ellipsoid flattening f = (a - b)/a [-]
+    atmosphere: Any = field(default=None, compare=False)  # atmospheric density Environment
+    source: str = field(default="", compare=False)        # source of the constants
+
+    @classmethod
+    def create(cls, name: str, mu, radius, J2: float = 0.0, rotation_rate=0.0,
+               flattening: float = 0.0, atmosphere=None, source: str = "") -> Body:
+        """Create from values with units. Plain numbers are taken as SI."""
+        return cls(
+            name=name,
+            mu=units.to_si(mu, units.MU),
+            radius=units.to_si(radius, units.LENGTH),
+            J2=J2,
+            rotation_rate=units.to_si(rotation_rate, units.ANGULAR_VELOCITY),
+            flattening=flattening,
+            atmosphere=atmosphere,
+            source=source,
+        )
+
+    @property
+    def mass(self) -> float:
+        """Mass [kg] = μ / G."""
+        return self.mu / G
+
+    def __repr__(self) -> str:
+        return f"Body({self.name!r}, R={self.radius / 1e3:.1f} km)"
+
+
+Sun = Body(
+    name="Sun",
+    mu=1.32712440041e20,
+    radius=6.957e8,
+    rotation_rate=2.8653e-6,  # Carrington rotation period 25.38 days
+    source="μ: DE440; R: IAU 2015 B3 nominal",
+)
+
+Earth = Body(
+    name="Earth",
+    mu=3.986004418e14,
+    radius=6378137.0,
+    J2=1.08262668e-3,
+    rotation_rate=7.292115e-5,
+    flattening=1 / 298.257223563,
+    atmosphere=ExponentialAtmosphere(radius=6378137.0, flattening=1 / 298.257223563),
+    source="μ, R, f: WGS 84; J2: EGM-08 (Vallado table D-1)",
+)
+
+Moon = Body(
+    name="Moon",
+    mu=4.902800118e12,
+    radius=1.7374e6,
+    J2=2.033e-4,
+    rotation_rate=2.6617e-6,  # sidereal month 27.3217 days
+    flattening=0.0012,
+    source="μ: DE440; J2: GRAIL GRGM1200A; f: Moon Fact Sheet (NASA GSFC)",
+)
+
+Mars = Body(
+    name="Mars",
+    mu=4.282837e13,
+    radius=3.3962e6,
+    J2=1.96045e-3,
+    rotation_rate=7.088218e-5,  # sidereal day 24.6229 hours
+    flattening=0.00589,
+    source="μ: DE440; R, J2, f: Mars Fact Sheet (NASA GSFC)",
+)

urania/constants.py

@@ -0,0 +1,10 @@
+"""Physical constants (SI)."""
+
+import math
+
+G = 6.67430e-11                   # gravitational constant [m³/(kg·s²)], CODATA 2018
+DAY = 86400.0                     # [s]
+TROPICAL_YEAR = 365.24219 * DAY   # tropical year [s]
+
+# Target nodal rate of a sun-synchronous orbit: 360° per tropical year [rad/s]
+SSO_RAAN_RATE = 2.0 * math.pi / TROPICAL_YEAR

urania/core/__init__.py

@@ -0,0 +1,36 @@
+"""Pure-function core. All inputs and outputs are plain SI numbers."""
+
+from .elements import Elements, coe_to_rv, elements_to_rv, rv_to_coe
+from .kepler import (
+    eccentric_to_mean,
+    eccentric_to_true,
+    hyperbolic_to_mean,
+    hyperbolic_to_true,
+    mean_to_eccentric,
+    mean_to_hyperbolic,
+    mean_to_parabolic,
+    mean_to_true,
+    parabolic_to_mean,
+    true_to_eccentric,
+    true_to_hyperbolic,
+    true_to_mean,
+)
+
+__all__ = [
+    "Elements",
+    "coe_to_rv",
+    "elements_to_rv",
+    "rv_to_coe",
+    "eccentric_to_mean",
+    "eccentric_to_true",
+    "hyperbolic_to_mean",
+    "hyperbolic_to_true",
+    "mean_to_eccentric",
+    "mean_to_hyperbolic",
+    "mean_to_parabolic",
+    "mean_to_true",
+    "parabolic_to_mean",
+    "true_to_eccentric",
+    "true_to_hyperbolic",
+    "true_to_mean",
+]

urania/core/elements.py

@@ -0,0 +1,127 @@
+"""State vector (r, v) ↔ classical orbital elements.
+
+All inputs and outputs are SI (m, m/s, m³/s², rad).
+
+Orbit size is stored as the semi-latus rectum p instead of the semi-major axis a,
+because p is finite for every conic, including the parabola (a = ∞).
+
+Angle conventions for singular orbits (Vallado):
+- Equatorial (i ≈ 0 or π): the node is undefined, so raan = 0 and the reference axis is x
+- Circular (e ≈ 0): periapsis is undefined, so argp = 0 and ν is measured from the node
+  (from the x axis if also equatorial)
+With these conventions coe_to_rv(rv_to_coe(r, v)) returns the original state even for singular orbits.
+"""
+
+import math
+from typing import NamedTuple
+
+import numpy as np
+
+from .kepler import PARABOLIC_TOL, _wrap_2pi
+
+# Dimensionless tolerances for treating an orbit as circular / equatorial
+CIRCULAR_TOL = 1e-11
+EQUATORIAL_TOL = 1e-11
+
+
+class Elements(NamedTuple):
+    """Classical orbital elements (SI, rad)."""
+
+    p: float      # semi-latus rectum [m]
+    ecc: float    # eccentricity [-]
+    inc: float    # inclination [rad], 0 to π
+    raan: float   # right ascension of the ascending node [rad], 0 to 2π
+    argp: float   # argument of periapsis [rad], 0 to 2π
+    nu: float     # true anomaly [rad]
+
+    @property
+    def a(self) -> float:
+        """Semi-major axis [m]. inf for a parabola, negative for a hyperbola."""
+        if abs(self.ecc - 1.0) < PARABOLIC_TOL:
+            return math.inf
+        return self.p / (1.0 - self.ecc**2)
+
+
+def _angle_between(ref: np.ndarray, vec: np.ndarray, normal: np.ndarray) -> float:
+    """Counterclockwise angle from ref to vec about normal, in [0, 2π)."""
+    y = np.dot(np.cross(ref, vec), normal)
+    x = np.dot(ref, vec)
+    return _wrap_2pi(math.atan2(y, x))
+
+
+def rv_to_coe(r, v, mu: float) -> Elements:
+    """Position and velocity vectors → classical orbital elements.
+
+    Args:
+        r: position vector [m], length 3
+        v: velocity vector [m/s], length 3
+        mu: gravitational parameter of the central body [m³/s²]
+    """
+    r = np.asarray(r, dtype=float)
+    v = np.asarray(v, dtype=float)
+    r_norm = np.linalg.norm(r)
+    v_norm = np.linalg.norm(v)
+
+    h_vec = np.cross(r, v)
+    h_norm = np.linalg.norm(h_vec)
+    if h_norm == 0.0:
+        raise ValueError("Angular momentum is zero (rectilinear orbits are not supported)")
+    h_hat = h_vec / h_norm
+
+    n_vec = np.cross([0.0, 0.0, 1.0], h_vec)  # ascending node direction
+    n_norm = np.linalg.norm(n_vec)
+
+    e_vec = ((v_norm**2 - mu / r_norm) * r - np.dot(r, v) * v) / mu
+    ecc = float(np.linalg.norm(e_vec))
+
+    p = h_norm**2 / mu
+    inc = math.acos(np.clip(h_vec[2] / h_norm, -1.0, 1.0))
+
+    equatorial = n_norm < EQUATORIAL_TOL * h_norm
+    circular = ecc < CIRCULAR_TOL
+
+    n_hat = np.array([1.0, 0.0, 0.0]) if equatorial else n_vec / n_norm
+    raan = 0.0 if equatorial else _wrap_2pi(math.atan2(n_hat[1], n_hat[0]))
+
+    if circular:
+        argp = 0.0
+        nu = _angle_between(n_hat, r, h_hat)
+    else:
+        argp = _angle_between(n_hat, e_vec, h_hat)
+        nu = _angle_between(e_vec, r, h_hat)
+
+    return Elements(p=p, ecc=ecc, inc=inc, raan=raan, argp=argp, nu=nu)
+
+
+def _rot_perifocal_to_inertial(inc: float, raan: float, argp: float) -> np.ndarray:
+    """Rotation matrix from the perifocal frame (PQW) to inertial: R3(Ω)·R1(i)·R3(ω)."""
+    cO, sO = math.cos(raan), math.sin(raan)
+    ci, si = math.cos(inc), math.sin(inc)
+    cw, sw = math.cos(argp), math.sin(argp)
+    return np.array([
+        [cO * cw - sO * sw * ci, -cO * sw - sO * cw * ci,  sO * si],
+        [sO * cw + cO * sw * ci, -sO * sw + cO * cw * ci, -cO * si],
+        [sw * si,                 cw * si,                 ci],
+    ])
+
+
+def coe_to_rv(p: float, ecc: float, inc: float, raan: float, argp: float,
+              nu: float, mu: float) -> tuple[np.ndarray, np.ndarray]:
+    """Classical orbital elements → position and velocity vectors (r [m], v [m/s])."""
+    if p <= 0.0:
+        raise ValueError(f"Semi-latus rectum must be positive: p={p}")
+    denom = 1.0 + ecc * math.cos(nu)
+    if denom <= 0.0:
+        raise ValueError(f"ν={nu} rad is not reachable on this orbit (e={ecc})")
+
+    cnu, snu = math.cos(nu), math.sin(nu)
+    r_pqw = (p / denom) * np.array([cnu, snu, 0.0])
+    v_pqw = math.sqrt(mu / p) * np.array([-snu, ecc + cnu, 0.0])
+
+    Q = _rot_perifocal_to_inertial(inc, raan, argp)
+    return Q @ r_pqw, Q @ v_pqw
+
+
+def elements_to_rv(el: Elements, mu: float) -> tuple[np.ndarray, np.ndarray]:
+    """Elements tuple → position and velocity vectors."""
+    return coe_to_rv(*el, mu=mu)

urania/core/forces.py

@@ -0,0 +1,105 @@
+"""Perturbation models: accelerations and atmospheric density. SI units, inertial frame."""
+
+import bisect
+import math
+
+import numpy as np
+
+
+def accel_twobody(r: np.ndarray, mu: float) -> np.ndarray:
+    """Point-mass gravity of the central body: a = -μ r / |r|³."""
+    r_norm = np.sqrt(r @ r)
+    return -mu * r / r_norm**3
+
+
+def accel_j2(r: np.ndarray, mu: float, R: float, J2: float) -> np.ndarray:
+    """J2 oblateness acceleration (Curtis eq. 12.30, Vallado eq. 8-30).
+
+    Assumes the body's spin axis is the inertial z axis.
+    """
+    x, y, z = r
+    r2 = r @ r
+    r_norm = np.sqrt(r2)
+    factor = -1.5 * J2 * mu * R**2 / r_norm**5
+    k = 5.0 * z * z / r2
+    return factor * np.array([x * (1.0 - k), y * (1.0 - k), z * (3.0 - k)])
+
+
+def accel_drag(r: np.ndarray, v: np.ndarray, rho: float, ballistic: float,
+               rotation_rate: float) -> np.ndarray:
+    """Atmospheric drag acceleration a = -½ ρ (C_D A / m) |v_rel| v_rel (Vallado eq. 8-28).
+
+    Args:
+        rho: atmospheric density [kg/m³]
+        ballistic: C_D·A/m [m²/kg]
+        rotation_rate: body rotation rate [rad/s]. The atmosphere co-rotates rigidly about z.
+    """
+    v_rel = v - rotation_rate * np.array([-r[1], r[0], 0.0])  # v - ω×r
+    return -0.5 * rho * ballistic * np.sqrt(v_rel @ v_rel) * v_rel
+
+
+# ---------------------------------------------------------------- atmospheric density
+# Exponential atmosphere (Vallado 4th ed. table 8-4): ρ = ρ₀ exp(-(h - h₀)/H) per altitude band.
+# A static model for mean solar activity; real density varies several-fold with solar activity.
+# (base altitude h₀ [km], base density ρ₀ [kg/m³], scale height H [km])
+VALLADO_TABLE = (
+    (0, 1.225, 7.249),
+    (25, 3.899e-2, 6.349),
+    (30, 1.774e-2, 6.682),
+    (40, 3.972e-3, 7.554),
+    (50, 1.057e-3, 8.382),
+    (60, 3.206e-4, 7.714),
+    (70, 8.770e-5, 6.549),
+    (80, 1.905e-5, 5.799),
+    (90, 3.396e-6, 5.382),
+    (100, 5.297e-7, 5.877),
+    (110, 9.661e-8, 7.263),
+    (120, 2.438e-8, 9.473),
+    (130, 8.484e-9, 12.636),
+    (140, 3.845e-9, 16.149),
+    (150, 2.070e-9, 22.523),
+    (180, 5.464e-10, 29.740),
+    (200, 2.789e-10, 37.105),
+    (250, 7.248e-11, 45.546),
+    (300, 2.418e-11, 53.628),
+    (350, 9.518e-12, 53.298),
+    (400, 3.725e-12, 58.515),
+    (450, 1.585e-12, 60.828),
+    (500, 6.967e-13, 63.822),
+    (600, 1.454e-13, 71.835),
+    (700, 3.614e-14, 88.667),
+    (800, 1.170e-14, 124.64),
+    (900, 5.245e-15, 181.05),
+    (1000, 3.019e-15, 268.00),
+)
+_BASE_ALTS = [row[0] * 1e3 for row in VALLADO_TABLE]
+
+
+def geodetic_altitude(r: np.ndarray, R: float, f: float) -> float:
+    """Height [m] above a reference ellipsoid (equatorial radius R, flattening f).
+
+    The ellipsoid is symmetric about the spin axis (inertial z), so no Earth rotation is needed.
+    Iterates the geodetic latitude (Vallado algorithm 12); the height formula stays well
+    conditioned at the poles. With f = 0 this is the spherical height |r| - R.
+    """
+    x, y, z = r
+    p = math.hypot(x, y)
+    if f == 0.0:
+        return math.hypot(p, z) - R
+    e2 = f * (2.0 - f)
+    lat = math.atan2(z, p * (1.0 - e2))
+    for _ in range(6):
+        sin_lat = math.sin(lat)
+        N = R / math.sqrt(1.0 - e2 * sin_lat * sin_lat)
+        lat = math.atan2(z + N * e2 * sin_lat, p)
+    sin_lat, cos_lat = math.sin(lat), math.cos(lat)
+    return p * cos_lat + z * sin_lat - R * math.sqrt(1.0 - e2 * sin_lat * sin_lat)
+
+
+def exponential_density(altitude: float) -> float:
+    """Altitude [m] → atmospheric density [kg/m³]. Above 1000 km the last band is extended."""
+    if altitude < 0.0:
+        altitude = 0.0
+    i = bisect.bisect_right(_BASE_ALTS, altitude) - 1
+    h0_km, rho0, H_km = VALLADO_TABLE[i]
+    return rho0 * math.exp(-(altitude - h0_km * 1e3) / (H_km * 1e3))

urania/core/j2.py

@@ -0,0 +1,43 @@
+"""Secular rates of orbital elements due to J2 (oblateness). Curtis sec. 4.7, Vallado sec. 9.6.
+
+Secular rates are orbit averages, so they are defined only for elliptic orbits (0 <= e < 1, a > 0).
+"""
+
+import math
+
+
+def _mean_motion_and_p(a: float, ecc: float, mu: float) -> tuple[float, float]:
+    if a <= 0.0 or not 0.0 <= ecc < 1.0:
+        raise ValueError(f"J2 secular rates are defined only for elliptic orbits: a={a}, e={ecc}")
+    return math.sqrt(mu / a**3), a * (1.0 - ecc**2)
+
+
+def raan_rate(a: float, ecc: float, inc: float, mu: float, R: float, J2: float) -> float:
+    """Mean rate of the right ascension of the ascending node dΩ/dt [rad/s].
+
+    dΩ/dt = -(3/2) n J2 (R/p)² cos i
+    """
+    n, p = _mean_motion_and_p(a, ecc, mu)
+    return -1.5 * n * J2 * (R / p) ** 2 * math.cos(inc)
+
+
+def argp_rate(a: float, ecc: float, inc: float, mu: float, R: float, J2: float) -> float:
+    """Mean rate of the argument of periapsis dω/dt [rad/s].
+
+    dω/dt = (3/4) n J2 (R/p)² (5cos²i - 1)
+    """
+    n, p = _mean_motion_and_p(a, ecc, mu)
+    return 0.75 * n * J2 * (R / p) ** 2 * (5.0 * math.cos(inc) ** 2 - 1.0)
+
+
+def sso_inclination(a: float, ecc: float, mu: float, R: float, J2: float,
+                    target_rate: float) -> float:
+    """Inclination [rad] that gives a nodal rate of target_rate [rad/s] (for sun-synchronous orbits).
+
+    The raan_rate formula solved for cos i.
+    """
+    n, p = _mean_motion_and_p(a, ecc, mu)
+    cos_i = -target_rate / (1.5 * n * J2 * (R / p) ** 2)
+    if abs(cos_i) > 1.0:
+        raise ValueError(f"The requested nodal rate is not achievable at a={a} m")
+    return math.acos(cos_i)

urania/core/kepler.py

@@ -0,0 +1,158 @@
+"""Kepler's equation and anomaly conversions.
+
+All angles are in rad. The eccentricity e selects the conic type:
+ellipse 0 <= e < 1, parabola e == 1, hyperbola e > 1.
+
+For parabolas, the "mean anomaly" is the M in Barker's equation M = D + D³/3 (D = tan(ν/2)).
+"""
+
+import math
+
+TWO_PI = 2.0 * math.pi
+
+# Eccentricity tolerance for treating an orbit as parabolic
+PARABOLIC_TOL = 1e-12
+
+_NEWTON_TOL = 1e-14
+_NEWTON_MAXITER = 50
+
+
+def _wrap_2pi(angle: float) -> float:
+    """Normalize an angle to [0, 2π)."""
+    wrapped = angle % TWO_PI
+    # A tiny negative angle can round to exactly 2π
+    return 0.0 if wrapped == TWO_PI else wrapped
+
+
+def _wrap_pi(angle: float) -> float:
+    """Normalize an angle to [-π, π)."""
+    return (angle + math.pi) % TWO_PI - math.pi
+
+
+def _check_ecc(e: float) -> None:
+    if e < 0.0:
+        raise ValueError(f"Eccentricity must be non-negative: e={e}")
+
+
+# ---------------------------------------------------------------- ellipse (e < 1)
+
+def eccentric_to_mean(E: float, e: float) -> float:
+    """Eccentric anomaly E → mean anomaly M (Kepler's equation M = E - e sin E)."""
+    return E - e * math.sin(E)
+
+
+def mean_to_eccentric(M: float, e: float) -> float:
+    """Mean anomaly M → eccentric anomaly E, solving Kepler's equation by Newton's method.
+
+    The result is in [0, 2π).
+    """
+    _check_ecc(e)
+    if e >= 1.0:
+        raise ValueError(f"Only elliptic orbits (e < 1) are allowed: e={e}")
+    M = _wrap_pi(M)
+    # For large e a start near M can diverge, so start from π (Vallado algorithm 2)
+    E = M + e if M >= 0.0 else M - e
+    if e > 0.8:
+        E = math.pi if M >= 0.0 else -math.pi
+    for _ in range(_NEWTON_MAXITER):
+        dE = (E - e * math.sin(E) - M) / (1.0 - e * math.cos(E))
+        E -= dE
+        if abs(dE) < _NEWTON_TOL:
+            return _wrap_2pi(E)
+    raise RuntimeError(f"Kepler's equation did not converge: M={M}, e={e}")
+
+
+def eccentric_to_true(E: float, e: float) -> float:
+    """Eccentric anomaly E → true anomaly ν. The result is in [0, 2π)."""
+    nu = 2.0 * math.atan2(math.sqrt(1.0 + e) * math.sin(E / 2.0),
+                          math.sqrt(1.0 - e) * math.cos(E / 2.0))
+    return _wrap_2pi(nu)
+
+
+def true_to_eccentric(nu: float, e: float) -> float:
+    """True anomaly ν → eccentric anomaly E. The result is in [0, 2π)."""
+    E = 2.0 * math.atan2(math.sqrt(1.0 - e) * math.sin(nu / 2.0),
+                         math.sqrt(1.0 + e) * math.cos(nu / 2.0))
+    return _wrap_2pi(E)
+
+
+# -------------------------------------------------------------- hyperbola (e > 1)
+
+def hyperbolic_to_mean(H: float, e: float) -> float:
+    """Hyperbolic anomaly H → mean anomaly M (M = e sinh H - H)."""
+    return e * math.sinh(H) - H
+
+
+def mean_to_hyperbolic(M: float, e: float) -> float:
+    """Mean anomaly M → hyperbolic anomaly H, by Newton's method."""
+    if e <= 1.0:
+        raise ValueError(f"Only hyperbolic orbits (e > 1) are allowed: e={e}")
+    # For large |M|, e sinh H ≈ M, so start from a logarithmic estimate
+    H = math.copysign(math.log(2.0 * abs(M) / e + 1.8), M) if M != 0.0 else 0.0
+    for _ in range(_NEWTON_MAXITER):
+        dH = (e * math.sinh(H) - H - M) / (e * math.cosh(H) - 1.0)
+        H -= dH
+        if abs(dH) < _NEWTON_TOL * max(1.0, abs(H)):
+            return H
+    raise RuntimeError(f"Hyperbolic Kepler equation did not converge: M={M}, e={e}")
+
+
+def hyperbolic_to_true(H: float, e: float) -> float:
+    """Hyperbolic anomaly H → true anomaly ν. The result is in (-π, π)."""
+    return 2.0 * math.atan(math.sqrt((e + 1.0) / (e - 1.0)) * math.tanh(H / 2.0))
+
+
+def true_to_hyperbolic(nu: float, e: float) -> float:
+    """True anomaly ν → hyperbolic anomaly H.
+
+    ν must lie inside the asymptotes ±arccos(-1/e).
+    """
+    nu = _wrap_pi(nu)
+    nu_inf = math.acos(-1.0 / e)
+    if abs(nu) >= nu_inf:
+        raise ValueError(f"ν={nu} rad is outside the hyperbola's asymptotes (±{nu_inf} rad)")
+    return 2.0 * math.atanh(math.sqrt((e - 1.0) / (e + 1.0)) * math.tan(nu / 2.0))
+
+
+# ------------------------------------------------------------- parabola (e == 1)
+
+def parabolic_to_mean(D: float) -> float:
+    """Parabolic anomaly D = tan(ν/2) → Barker mean anomaly M = D + D³/3."""
+    return D + D**3 / 3.0
+
+
+def mean_to_parabolic(M: float) -> float:
+    """Solve Barker's equation D + D³/3 = M in closed form."""
+    # Unique real root of D³ + 3D - 3M = 0 (Cardano): D = ∛(w+s) + ∛(w-s).
+    # Since (w+s)(w-s) = -1, ∛(w-s) = -1/∛(w+s). Computing w-s directly cancels badly for large |w|.
+    w = 1.5 * abs(M)
+    c = math.cbrt(w + math.sqrt(w * w + 1.0))
+    return math.copysign(c - 1.0 / c, M)
+
+
+# ------------------------------------------------------------- any conic
+
+def mean_to_true(M: float, e: float) -> float:
+    """Mean anomaly M → true anomaly ν for an ellipse, parabola or hyperbola.
+
+    Ellipses return [0, 2π); parabolas and hyperbolas return (-π, π).
+    """
+    _check_ecc(e)
+    if abs(e - 1.0) < PARABOLIC_TOL:
+        return 2.0 * math.atan(mean_to_parabolic(M))
+    if e < 1.0:
+        return eccentric_to_true(mean_to_eccentric(M, e), e)
+    return hyperbolic_to_true(mean_to_hyperbolic(M, e), e)
+
+
+def true_to_mean(nu: float, e: float) -> float:
+    """True anomaly ν → mean anomaly M.
+
+    Ellipses return [0, 2π); parabolas and hyperbolas return a signed value.
+    """
+    _check_ecc(e)
+    if abs(e - 1.0) < PARABOLIC_TOL:
+        return parabolic_to_mean(math.tan(_wrap_pi(nu) / 2.0))
+    if e < 1.0:
+        return _wrap_2pi(eccentric_to_mean(true_to_eccentric(nu, e), e))
+    return hyperbolic_to_mean(true_to_hyperbolic(nu, e), e)

urania/core/maneuvers.py

@@ -0,0 +1,85 @@
+"""Impulsive maneuver formulas. SI units. Curtis ch. 6, Vallado ch. 6.
+
+Transfers between circular orbits. Δv values are signed tangential components (+ is prograde).
+"""
+
+import math
+
+import numpy as np
+from scipy.optimize import minimize_scalar
+
+from .twobody import vis_viva as _vis_viva
+
+
+def hohmann(r1: float, r2: float, mu: float) -> tuple[float, float, float]:
+    """Hohmann transfer between circular orbits r1 → r2 (Vallado algorithm 36).
+
+    Returns:
+        (dv1, dv2, tof): tangential Δv of both burns [m/s] (negative when descending), transfer time [s]
+    """
+    a_t = 0.5 * (r1 + r2)
+    dv1 = _vis_viva(r1, a_t, mu) - math.sqrt(mu / r1)
+    dv2 = math.sqrt(mu / r2) - _vis_viva(r2, a_t, mu)
+    tof = math.pi * math.sqrt(a_t**3 / mu)
+    return dv1, dv2, tof
+
+
+def bielliptic(r1: float, rb: float, r2: float, mu: float) -> tuple[float, float, float, float]:
+    """Bi-elliptic transfer r1 → rb (intermediate apoapsis) → r2 between circular orbits (Vallado algorithm 37).
+
+    Returns:
+        (dv1, dv2, dv3, tof): tangential Δv of the three burns [m/s], transfer time [s]
+    """
+    if rb < max(r1, r2):
+        raise ValueError(f"Intermediate apoapsis rb={rb} must be larger than r1 and r2")
+    a1 = 0.5 * (r1 + rb)
+    a2 = 0.5 * (rb + r2)
+    dv1 = _vis_viva(r1, a1, mu) - math.sqrt(mu / r1)
+    dv2 = _vis_viva(rb, a2, mu) - _vis_viva(rb, a1, mu)
+    dv3 = math.sqrt(mu / r2) - _vis_viva(r2, a2, mu)
+    tof = math.pi * (math.sqrt(a1**3 / mu) + math.sqrt(a2**3 / mu))
+    return dv1, dv2, dv3, tof
+
+
+def plane_change_dv(v: float, dtheta: float) -> float:
+    """Δv to rotate the orbit plane by dtheta [rad] at constant speed: 2v sin(Δθ/2)."""
+    return 2.0 * v * math.sin(0.5 * abs(dtheta))
+
+
+def combined_dv(v1: float, v2: float, dtheta: float) -> float:
+    """Δv for a combined speed change and plane change (law of cosines)."""
+    return math.sqrt(max(v1 * v1 + v2 * v2 - 2.0 * v1 * v2 * math.cos(dtheta), 0.0))
+
+
+def hohmann_plane_change(r1: float, r2: float, dtheta: float, mu: float,
+                         split: float) -> tuple[float, float, float]:
+    """Hohmann transfer with a plane change.
+
+    Args:
+        dtheta: angle between the two orbit planes [rad]
+        split: fraction of the plane change done at the first burn (0 to 1); the rest at the second.
+
+    Returns:
+        (dv1, dv2, tof): Δv magnitudes of both burns [m/s], transfer time [s]
+    """
+    a_t = 0.5 * (r1 + r2)
+    dv1 = combined_dv(math.sqrt(mu / r1), _vis_viva(r1, a_t, mu), split * dtheta)
+    dv2 = combined_dv(_vis_viva(r2, a_t, mu), math.sqrt(mu / r2), (1.0 - split) * dtheta)
+    return dv1, dv2, math.pi * math.sqrt(a_t**3 / mu)
+
+
+def optimal_plane_split(r1: float, r2: float, dtheta: float, mu: float) -> float:
+    """Plane change split (0 to 1) that minimizes the total Δv."""
+    if dtheta == 0.0:
+        return 0.0
+    res = minimize_scalar(lambda s: sum(hohmann_plane_change(r1, r2, dtheta, mu, s)[:2]),
+                          bounds=(0.0, 1.0), method="bounded", options={"xatol": 1e-10})
+    return float(res.x)
+
+
+def rotate(vec, axis, angle: float) -> np.ndarray:
+    """Rotate a vector by angle [rad] about the unit axis (Rodrigues' formula)."""
+    vec = np.asarray(vec, dtype=float)
+    k = np.asarray(axis, dtype=float)
+    c, s = math.cos(angle), math.sin(angle)
+    return vec * c + np.cross(k, vec) * s + k * (k @ vec) * (1.0 - c)