astrox-python 0.2.0__py3-none-any.whl → 1.1.0__py3-none-any.whl

astrox/__init__.py

@@ -4,7 +4,7 @@ Functions are organized by domain modules and can use package-level
 configuration without requiring explicit client management:
 
     import astrox
-    from astrox import access, celestial, catalog, components, coverage, lighting, orbits, propagator, terrain
+    from astrox import access, celestial, catalog, components, coverage, libration, lighting, orbits, propagator, terrain
 
     astrox.configure(base_url="http://custom:8765", timeout=120)
     orbit = orbits.keplerian(...)
@@ -35,6 +35,7 @@ from astrox import (
     conjunction,
     components,
     coverage,
+    libration,
     lighting,
     orbits,
     propagator,
@@ -60,6 +61,7 @@ __all__ = [
     "conjunction",
     "coverage",
     "components",
+    "libration",
     "lighting",
     "orbits",
     "propagator",

astrox/catalog.py

@@ -43,6 +43,16 @@ def _optional_boolean_query(value: bool | None, *, parameter: str) -> str | None
     return "true" if value else "false"
 
 
+def _without_status_fields(value: Any, *, endpoint: str) -> dict[str, Any]:
+    if not isinstance(value, dict):
+        raise TypeError(f"{endpoint} response must be an object")
+    return {
+        key: item
+        for key, item in value.items()
+        if key not in {"IsSuccess", "Message"}
+    }
+
+
 def query_cities(
     *,
     city_name: str | None = None,
@@ -72,7 +82,10 @@ def query_cities(
         "typeOfCity",
         _optional_string(city_type, parameter="city_type"),
     )
-    return raw.get("/city", params=params)
+    return _without_status_fields(
+        raw.get("/city", params=params),
+        endpoint="/city",
+    )
 
 
 def query_facilities(
@@ -92,7 +105,10 @@ def query_facilities(
         "networkName",
         _optional_string(network_name, parameter="network_name"),
     )
-    return raw.get("/facility", params=params)
+    return _without_status_fields(
+        raw.get("/facility", params=params),
+        endpoint="/facility",
+    )
 
 
 def query_satellites(
@@ -172,4 +188,7 @@ def query_satellites(
             parameter="maximum_inclination_deg",
         ),
     )
-    return raw.get("/ssc", params=params)
+    return _without_status_fields(
+        raw.get("/ssc", params=params),
+        endpoint="/ssc",
+    )

astrox/celestial.py

@@ -1,16 +1,20 @@
-"""Read-like celestial endpoint functions."""
+"""Celestial read-like and computational endpoint functions."""
 
 from __future__ import annotations
 
+from dataclasses import dataclass
 from numbers import Real
 from typing import Any
 
 from astrox._http import raw
 
 __all__ = [
+    "MpcOrbitalElements",
     "cb_axes_rotation",
     "ephemeris",
+    "lambert_transfer_window",
     "mpc_ephemeris",
+    "mpc_orbital_elements",
 ]
 
 
@@ -47,6 +51,235 @@ def _optional_integer(value: int | None, *, parameter: str) -> int | None:
     return value
 
 
+def _without_status_fields(value: Any, *, endpoint: str) -> dict[str, Any]:
+    if not isinstance(value, dict):
+        raise TypeError(f"{endpoint} response must be an object")
+    return {
+        key: item
+        for key, item in value.items()
+        if key not in {"IsSuccess", "Message"}
+    }
+
+
+@dataclass(frozen=True, kw_only=True)
+class MpcOrbitalElements:
+    """MPC heliocentric orbital elements used by celestial transfer routes."""
+
+    epoch_mjd_tdt: float | None = None
+    periapsis_time_mjd_tdt: float | None = None
+    periapsis_distance_au: float | None = None
+    semi_major_axis_au: float | None = None
+    eccentricity: float | None = None
+    inclination_deg: float | None = None
+    raan_deg: float | None = None
+    argument_of_periapsis_deg: float | None = None
+    mean_anomaly_deg: float | None = None
+    reference_frame: str | None = None
+    """Heliocentric mean-ecliptic variant: ``MeanEclpJ2000`` (JPL) or
+    ``EclpJ2000ICRF`` (MPC, server default)."""
+
+    def __post_init__(self) -> None:
+        for field_name in (
+            "epoch_mjd_tdt",
+            "periapsis_time_mjd_tdt",
+            "periapsis_distance_au",
+            "semi_major_axis_au",
+            "eccentricity",
+            "inclination_deg",
+            "raan_deg",
+            "argument_of_periapsis_deg",
+            "mean_anomaly_deg",
+        ):
+            object.__setattr__(
+                self,
+                field_name,
+                _optional_number(
+                    getattr(self, field_name),
+                    parameter=field_name,
+                ),
+            )
+        object.__setattr__(
+            self,
+            "reference_frame",
+            _optional_string(self.reference_frame, parameter="reference_frame"),
+        )
+
+    def to_wire(self) -> dict[str, Any]:
+        payload: dict[str, Any] = {}
+        _include_if_supplied(payload, "EpochMjdTdt", self.epoch_mjd_tdt)
+        _include_if_supplied(payload, "PeriTimeMjdTdt", self.periapsis_time_mjd_tdt)
+        _include_if_supplied(payload, "Q", self.periapsis_distance_au)
+        _include_if_supplied(payload, "SemimajorAxis", self.semi_major_axis_au)
+        _include_if_supplied(payload, "Eccentricity", self.eccentricity)
+        _include_if_supplied(payload, "Inclination", self.inclination_deg)
+        _include_if_supplied(payload, "Raan", self.raan_deg)
+        _include_if_supplied(
+            payload,
+            "ArgOfPeriapsis",
+            self.argument_of_periapsis_deg,
+        )
+        _include_if_supplied(payload, "MeanAnomaly", self.mean_anomaly_deg)
+        _include_if_supplied(payload, "ReferenceFrame", self.reference_frame)
+        return payload
+
+
+def mpc_orbital_elements(
+    *,
+    epoch_mjd_tdt: float | None = None,
+    periapsis_time_mjd_tdt: float | None = None,
+    periapsis_distance_au: float | None = None,
+    semi_major_axis_au: float | None = None,
+    eccentricity: float | None = None,
+    inclination_deg: float | None = None,
+    raan_deg: float | None = None,
+    argument_of_periapsis_deg: float | None = None,
+    mean_anomaly_deg: float | None = None,
+    reference_frame: str | None = None,
+) -> MpcOrbitalElements:
+    """Build an MPC orbital-element fragment without adding physics policy."""
+    return MpcOrbitalElements(
+        epoch_mjd_tdt=epoch_mjd_tdt,
+        periapsis_time_mjd_tdt=periapsis_time_mjd_tdt,
+        periapsis_distance_au=periapsis_distance_au,
+        semi_major_axis_au=semi_major_axis_au,
+        eccentricity=eccentricity,
+        inclination_deg=inclination_deg,
+        raan_deg=raan_deg,
+        argument_of_periapsis_deg=argument_of_periapsis_deg,
+        mean_anomaly_deg=mean_anomaly_deg,
+        reference_frame=reference_frame,
+    )
+
+
+def _interval(start: str, stop: str, *, parameter: str) -> str:
+    return "/".join(
+        (
+            _string(start, parameter=f"{parameter}_start"),
+            _string(stop, parameter=f"{parameter}_stop"),
+        )
+    )
+
+
+def _elements_to_wire(
+    value: MpcOrbitalElements | None,
+    *,
+    parameter: str,
+) -> dict[str, Any] | None:
+    if value is None:
+        return None
+    if not isinstance(value, MpcOrbitalElements):
+        raise TypeError(f"{parameter} must be an MpcOrbitalElements value")
+    return value.to_wire()
+
+
+def lambert_transfer_window(
+    *,
+    departure_body: str,
+    arrival_body: str,
+    departure_start: str,
+    departure_stop: str,
+    arrival_start: str,
+    arrival_stop: str,
+    sun_frame: str | None = None,
+    min_time_of_flight_days: int | None = None,
+    departure_step_days: float | None = None,
+    arrival_step_days: float | None = None,
+    departure_elements: MpcOrbitalElements | None = None,
+    arrival_elements: MpcOrbitalElements | None = None,
+    max_departure_delta_v_m_s: int | None = None,
+    max_arrival_delta_v_m_s: int | None = None,
+    max_time_of_flight_days: int | None = None,
+) -> dict[str, Any]:
+    """Return a Lambert transfer-window scan from ASTROX.
+
+    The returned dictionary preserves every server field except the transport
+    success envelope fields ``IsSuccess`` and ``Message``. The transfer route
+    itself returns one result for each sampled departure/arrival time pair that
+    it evaluates; it is not the single-case ``orbits.lambert_delta_v`` route.
+    """
+    payload: dict[str, Any] = {
+        "DepartureCbName": _string(departure_body, parameter="departure_body"),
+        "ArrivalCbName": _string(arrival_body, parameter="arrival_body"),
+        "DepartureInterval": _interval(
+            departure_start,
+            departure_stop,
+            parameter="departure_interval",
+        ),
+        "ArrivalInterval": _interval(
+            arrival_start,
+            arrival_stop,
+            parameter="arrival_interval",
+        ),
+    }
+    _include_if_supplied(
+        payload,
+        "SunFrameName",
+        _optional_string(sun_frame, parameter="sun_frame"),
+    )
+    _include_if_supplied(
+        payload,
+        "MinTofDays",
+        _optional_integer(
+            min_time_of_flight_days,
+            parameter="min_time_of_flight_days",
+        ),
+    )
+    _include_if_supplied(
+        payload,
+        "DepartureStepDay",
+        _optional_number(
+            departure_step_days,
+            parameter="departure_step_days",
+        ),
+    )
+    _include_if_supplied(
+        payload,
+        "ArrivalStepDay",
+        _optional_number(
+            arrival_step_days,
+            parameter="arrival_step_days",
+        ),
+    )
+    _include_if_supplied(
+        payload,
+        "DepartureElements",
+        _elements_to_wire(departure_elements, parameter="departure_elements"),
+    )
+    _include_if_supplied(
+        payload,
+        "ArrivalElements",
+        _elements_to_wire(arrival_elements, parameter="arrival_elements"),
+    )
+    _include_if_supplied(
+        payload,
+        "MaxDepartureDV",
+        _optional_integer(
+            max_departure_delta_v_m_s,
+            parameter="max_departure_delta_v_m_s",
+        ),
+    )
+    _include_if_supplied(
+        payload,
+        "MaxArrivalDV",
+        _optional_integer(
+            max_arrival_delta_v_m_s,
+            parameter="max_arrival_delta_v_m_s",
+        ),
+    )
+    _include_if_supplied(
+        payload,
+        "MaxTofDays",
+        _optional_integer(
+            max_time_of_flight_days,
+            parameter="max_time_of_flight_days",
+        ),
+    )
+    return _without_status_fields(
+        raw.post("/celestial/transfer", json=payload),
+        endpoint="/celestial/transfer",
+    )
+
+
 def ephemeris(
     *,
     target_name: str,
@@ -85,7 +318,10 @@ def ephemeris(
         "Step",
         _optional_number(step_s, parameter="step_s"),
     )
-    return raw.post("/celestial/ephemeris", json=payload)
+    return _without_status_fields(
+        raw.post("/celestial/ephemeris", json=payload),
+        endpoint="/celestial/ephemeris",
+    )
 
 
 def cb_axes_rotation(
@@ -121,7 +357,10 @@ def cb_axes_rotation(
         "Order",
         _optional_integer(order, parameter="order"),
     )
-    return raw.post("/celestial/CbAxesRotation", json=payload)
+    return _without_status_fields(
+        raw.post("/celestial/CbAxesRotation", json=payload),
+        endpoint="/celestial/CbAxesRotation",
+    )
 
 
 def mpc_ephemeris(
@@ -130,8 +369,14 @@ def mpc_ephemeris(
     observer_frame: str | None = None,
     start: str | None = None,
     stop: str | None = None,
+    target_elements: MpcOrbitalElements | None = None,
 ) -> dict[str, Any]:
-    """Return ASTROX minor-planet ephemeris output from its MPC-backed route."""
+    """Return ASTROX minor-planet ephemeris output from its MPC-backed route.
+
+    When ``target_elements`` is supplied, the server integrates those MPC
+    orbital elements directly instead of resolving ``target_name`` through the
+    MPC network query.
+    """
     payload: dict[str, Any] = {
         "TargetName": _string(target_name, parameter="target_name"),
     }
@@ -150,4 +395,12 @@ def mpc_ephemeris(
         "Stop",
         _optional_string(stop, parameter="stop"),
     )
-    return raw.post("/celestial/mpc", json=payload)
+    _include_if_supplied(
+        payload,
+        "TargetElements",
+        _elements_to_wire(target_elements, parameter="target_elements"),
+    )
+    return _without_status_fields(
+        raw.post("/celestial/mpc", json=payload),
+        endpoint="/celestial/mpc",
+    )

astrox/libration.py

@@ -0,0 +1,448 @@
+"""CRTBP and Earth-Moon libration-dynamics functions."""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from numbers import Real
+from typing import Any
+
+from astrox._http import raw
+
+__all__ = [
+    "CrtbpSample",
+    "CrtbpState",
+    "CrtbpTrajectory",
+    "LibrationPoint",
+    "LibrationPoints",
+    "LibrationUnitSystem",
+    "PeriodicOrbit",
+    "correct_periodic_orbit_fixed_x",
+    "crtbp_state",
+    "crtbp_trajectory",
+    "earth_moon_dro",
+    "earth_moon_l1_halo",
+    "earth_moon_l2_halo",
+    "positions",
+    "units",
+]
+
+
+def _number(value: Any, *, field: str) -> float:
+    if isinstance(value, bool) or not isinstance(value, Real):
+        raise TypeError(f"{field} must be a number")
+    result = float(value)
+    if not math.isfinite(result):
+        raise ValueError(f"{field} must be finite")
+    return result
+
+
+def _optional_number(value: float | None, *, parameter: str) -> float | None:
+    if value is None:
+        return None
+    return _number(value, field=parameter)
+
+
+def _optional_boolean(value: bool | None, *, parameter: str) -> bool | None:
+    if value is None:
+        return None
+    if not isinstance(value, bool):
+        raise TypeError(f"{parameter} must be a boolean")
+    return value
+
+
+def _mapping(value: Any, *, field: str) -> Mapping[str, Any]:
+    if not isinstance(value, Mapping):
+        raise TypeError(f"{field} must be an object")
+    return value
+
+
+def _sequence(value: Any, *, field: str) -> Sequence[Any]:
+    if isinstance(value, (str, bytes)) or not isinstance(value, Sequence):
+        raise TypeError(f"{field} must be an array")
+    return value
+
+
+def _boolean(value: Any, *, field: str) -> bool:
+    if not isinstance(value, bool):
+        raise TypeError(f"{field} must be a boolean")
+    return value
+
+
+def _include_if_supplied(payload: dict[str, Any], wire_key: str, value: Any) -> None:
+    if value is not None:
+        payload[wire_key] = value
+
+
+def _boolean_query(value: bool | None, *, parameter: str) -> str | None:
+    parsed = _optional_boolean(value, parameter=parameter)
+    if parsed is None:
+        return None
+    return "true" if parsed else "false"
+
+
+@dataclass(frozen=True, kw_only=True)
+class LibrationPoint:
+    """One nondimensional CRTBP equilibrium-point coordinate."""
+
+    x: float
+    y: float
+
+
+@dataclass(frozen=True, kw_only=True)
+class LibrationPoints:
+    """The five CRTBP equilibrium points and collinear-point distances."""
+
+    l1: LibrationPoint
+    l2: LibrationPoint
+    l3: LibrationPoint
+    l4: LibrationPoint
+    l5: LibrationPoint
+    l1_distance_to_secondary: float
+    l2_distance_to_secondary: float
+    l3_distance_to_primary: float
+
+
+@dataclass(frozen=True, kw_only=True)
+class LibrationUnitSystem:
+    """Dimensional scales for a nondimensional CRTBP system."""
+
+    primary_gravitational_parameter_m3_s2: float
+    secondary_gravitational_parameter_m3_s2: float
+    mass_ratio: float
+    length_unit_m: float
+    time_unit_s: float
+    velocity_unit_m_s: float
+
+
+@dataclass(frozen=True, kw_only=True)
+class CrtbpState:
+    """Nondimensional CRTBP position and rotating-frame velocity."""
+
+    x: float
+    y: float
+    z: float
+    vx: float
+    vy: float
+    vz: float
+
+    def __post_init__(self) -> None:
+        for field_name in ("x", "y", "z", "vx", "vy", "vz"):
+            object.__setattr__(
+                self,
+                field_name,
+                _number(getattr(self, field_name), field=field_name),
+            )
+
+    def to_wire(self) -> list[float]:
+        """Lower to ASTROX ``[x, y, z, vx, vy, vz]`` order."""
+        return [self.x, self.y, self.z, self.vx, self.vy, self.vz]
+
+
+@dataclass(frozen=True, kw_only=True)
+class CrtbpSample:
+    """One nondimensional CRTBP state at a nondimensional time."""
+
+    time: float
+    state: CrtbpState
+
+
+@dataclass(frozen=True, kw_only=True)
+class CrtbpTrajectory:
+    """A sampled nondimensional CRTBP trajectory."""
+
+    mass_ratio: float
+    is_barycentric: bool
+    samples: tuple[CrtbpSample, ...]
+
+
+@dataclass(frozen=True, kw_only=True)
+class PeriodicOrbit:
+    """A corrected periodic CRTBP orbit and one sampled period."""
+
+    is_barycentric: bool
+    period: float
+    initial_state: CrtbpState
+    corrected_state: CrtbpState
+    samples: tuple[CrtbpSample, ...]
+
+
+def crtbp_state(
+    *,
+    x: float,
+    y: float,
+    z: float,
+    vx: float,
+    vy: float,
+    vz: float,
+) -> CrtbpState:
+    """Create a nondimensional rotating-frame CRTBP state."""
+    return CrtbpState(x=x, y=y, z=z, vx=vx, vy=vy, vz=vz)
+
+
+def _state_to_wire(value: CrtbpState, *, parameter: str) -> list[float]:
+    if not isinstance(value, CrtbpState):
+        raise TypeError(f"{parameter} must be a CrtbpState value")
+    return value.to_wire()
+
+
+def _state_from_wire(value: Any, *, field: str) -> CrtbpState:
+    values = _sequence(value, field=field)
+    if len(values) != 6:
+        raise TypeError(f"{field} must contain six numbers")
+    return CrtbpState(
+        x=_number(values[0], field=f"{field}[0]"),
+        y=_number(values[1], field=f"{field}[1]"),
+        z=_number(values[2], field=f"{field}[2]"),
+        vx=_number(values[3], field=f"{field}[3]"),
+        vy=_number(values[4], field=f"{field}[4]"),
+        vz=_number(values[5], field=f"{field}[5]"),
+    )
+
+
+def _points_from_wire(value: Any) -> LibrationPoints:
+    values = _sequence(value, field="positions response")
+    if len(values) != 10:
+        raise TypeError("positions response must contain ten numbers")
+    numbers = tuple(
+        _number(item, field=f"positions response[{index}]")
+        for index, item in enumerate(values)
+    )
+    return LibrationPoints(
+        l1=LibrationPoint(x=numbers[3], y=0.0),
+        l2=LibrationPoint(x=numbers[4], y=0.0),
+        l3=LibrationPoint(x=numbers[5], y=0.0),
+        l4=LibrationPoint(x=numbers[6], y=numbers[8]),
+        l5=LibrationPoint(x=numbers[7], y=numbers[9]),
+        l1_distance_to_secondary=numbers[0],
+        l2_distance_to_secondary=numbers[1],
+        l3_distance_to_primary=numbers[2],
+    )
+
+
+def _units_from_wire(value: Any) -> LibrationUnitSystem:
+    payload = _mapping(value, field="unit response")
+    return LibrationUnitSystem(
+        primary_gravitational_parameter_m3_s2=_number(
+            payload["GravitationalParameter1"],
+            field="GravitationalParameter1",
+        ),
+        secondary_gravitational_parameter_m3_s2=_number(
+            payload["GravitationalParameter2"],
+            field="GravitationalParameter2",
+        ),
+        mass_ratio=_number(payload["U"], field="U"),
+        length_unit_m=_number(payload["UnitL"], field="UnitL"),
+        time_unit_s=_number(payload["UnitT"], field="UnitT"),
+        velocity_unit_m_s=_number(payload["UnitV"], field="UnitV"),
+    )
+
+
+def _trajectory_from_wire(value: Any) -> CrtbpTrajectory:
+    payload = _mapping(value, field="crtbp trajectory response")
+    positions = _sequence(payload["Positions"], field="Positions")
+    if not positions or len(positions) % 7 != 0:
+        raise TypeError("Positions must contain one or more seven-number samples")
+    samples = tuple(
+        CrtbpSample(
+            time=_number(positions[index], field=f"Positions[{index}]"),
+            state=_state_from_wire(
+                positions[index + 1 : index + 7],
+                field=f"Positions[{index + 1}:{index + 7}]",
+            ),
+        )
+        for index in range(0, len(positions), 7)
+    )
+    return CrtbpTrajectory(
+        mass_ratio=_number(payload["U"], field="U"),
+        is_barycentric=_boolean(payload["IsBarycentric"], field="IsBarycentric"),
+        samples=samples,
+    )
+
+
+def _periodic_orbit_from_wire(value: Any) -> PeriodicOrbit:
+    payload = _mapping(value, field="periodic orbit response")
+    times = _sequence(payload["ListT"], field="ListT")
+    states = _sequence(payload["ListX"], field="ListX")
+    if not times or len(times) != len(states):
+        raise TypeError("ListT and ListX must be non-empty arrays of equal length")
+    samples = tuple(
+        CrtbpSample(
+            time=_number(time, field=f"ListT[{index}]"),
+            state=_state_from_wire(state, field=f"ListX[{index}]"),
+        )
+        for index, (time, state) in enumerate(zip(times, states, strict=True))
+    )
+    return PeriodicOrbit(
+        is_barycentric=_boolean(payload["IsBarycentric"], field="IsBarycentric"),
+        period=_number(payload["Period"], field="Period"),
+        initial_state=_state_from_wire(payload["InitialX0"], field="InitialX0"),
+        corrected_state=_state_from_wire(payload["X0"], field="X0"),
+        samples=samples,
+    )
+
+
+def positions(*, mass_ratio: float) -> LibrationPoints:
+    """Return the five barycentric CRTBP equilibrium points."""
+    return _points_from_wire(
+        raw.get(
+            "/libration/positions",
+            params={"u": _number(mass_ratio, field="mass_ratio")},
+        )
+    )
+
+
+def units(
+    *,
+    primary_gravitational_parameter_m3_s2: float | None = None,
+    secondary_gravitational_parameter_m3_s2: float | None = None,
+    mean_separation_m: float | None = None,
+) -> LibrationUnitSystem:
+    """Return the dimensional scales for a CRTBP primary-secondary system."""
+    params: dict[str, Any] = {}
+    _include_if_supplied(
+        params,
+        "gm1",
+        _optional_number(
+            primary_gravitational_parameter_m3_s2,
+            parameter="primary_gravitational_parameter_m3_s2",
+        ),
+    )
+    _include_if_supplied(
+        params,
+        "gm2",
+        _optional_number(
+            secondary_gravitational_parameter_m3_s2,
+            parameter="secondary_gravitational_parameter_m3_s2",
+        ),
+    )
+    _include_if_supplied(
+        params,
+        "meanRange",
+        _optional_number(mean_separation_m, parameter="mean_separation_m"),
+    )
+    return _units_from_wire(raw.get("/libration/unit", params=params))
+
+
+def crtbp_trajectory(
+    *,
+    initial_state: CrtbpState,
+    mass_ratio: float,
+    start_time: float | None = None,
+    end_time: float | None = None,
+    barycentric: bool | None = None,
+    output_step: float | None = None,
+) -> CrtbpTrajectory:
+    """Integrate a nondimensional CRTBP state in the rotating frame."""
+    payload: dict[str, Any] = {
+        "RV0": _state_to_wire(initial_state, parameter="initial_state"),
+        "U": _number(mass_ratio, field="mass_ratio"),
+    }
+    _include_if_supplied(
+        payload,
+        "T0",
+        _optional_number(start_time, parameter="start_time"),
+    )
+    _include_if_supplied(
+        payload,
+        "TEnd",
+        _optional_number(end_time, parameter="end_time"),
+    )
+    _include_if_supplied(
+        payload,
+        "IsBarycentric",
+        _optional_boolean(barycentric, parameter="barycentric"),
+    )
+    _include_if_supplied(
+        payload,
+        "OutStep",
+        _optional_number(output_step, parameter="output_step"),
+    )
+    return _trajectory_from_wire(
+        raw.post("/libration/crtbp-trajectory", json=payload)
+    )
+
+
+def earth_moon_l1_halo(
+    *,
+    z_amplitude: float | None = None,
+    southern: bool | None = None,
+) -> PeriodicOrbit:
+    """Return a corrected Earth-Moon L1 Halo orbit."""
+    params: dict[str, Any] = {}
+    _include_if_supplied(
+        params,
+        "az",
+        _optional_number(z_amplitude, parameter="z_amplitude"),
+    )
+    _include_if_supplied(
+        params,
+        "isSouth",
+        _boolean_query(southern, parameter="southern"),
+    )
+    return _periodic_orbit_from_wire(
+        raw.get("/libration/em-l1-halo", params=params)
+    )
+
+
+def earth_moon_l2_halo(
+    *,
+    x_amplitude: float | None = None,
+    southern: bool | None = None,
+) -> PeriodicOrbit:
+    """Return a corrected Earth-Moon L2 Halo orbit."""
+    params: dict[str, Any] = {}
+    _include_if_supplied(
+        params,
+        "ax",
+        _optional_number(x_amplitude, parameter="x_amplitude"),
+    )
+    _include_if_supplied(
+        params,
+        "isSouth",
+        _boolean_query(southern, parameter="southern"),
+    )
+    return _periodic_orbit_from_wire(
+        raw.get("/libration/em-l2-halo", params=params)
+    )
+
+
+def earth_moon_dro(*, x_amplitude: float | None = None) -> PeriodicOrbit:
+    """Return a corrected planar Earth-Moon distant retrograde orbit."""
+    params: dict[str, Any] = {}
+    _include_if_supplied(
+        params,
+        "ax",
+        _optional_number(x_amplitude, parameter="x_amplitude"),
+    )
+    return _periodic_orbit_from_wire(raw.get("/libration/em-dro", params=params))
+
+
+def correct_periodic_orbit_fixed_x(
+    *,
+    initial_state: CrtbpState,
+    period_guess: float,
+    mass_ratio: float,
+    barycentric: bool | None = None,
+    output_step: float | None = None,
+) -> PeriodicOrbit:
+    """Correct an XZ-plane-crossing seed while holding its x coordinate fixed."""
+    payload: dict[str, Any] = {
+        "RV0": _state_to_wire(initial_state, parameter="initial_state"),
+        "TEnd": _number(period_guess, field="period_guess"),
+        "U": _number(mass_ratio, field="mass_ratio"),
+    }
+    _include_if_supplied(
+        payload,
+        "IsBarycentric",
+        _optional_boolean(barycentric, parameter="barycentric"),
+    )
+    _include_if_supplied(
+        payload,
+        "OutStep",
+        _optional_number(output_step, parameter="output_step"),
+    )
+    return _periodic_orbit_from_wire(
+        raw.post("/libration/crtbp-period-orbit-fixed-x", json=payload)
+    )

astrox/orbits.py

@@ -11,6 +11,7 @@ from astrox._http import raw
 __all__ = [
     "CartesianState",
     "KeplerianElements",
+    "LambertResult",
     "MeanKeplerianElements",
     "Tle",
     "cartesian_state",
@@ -517,14 +518,37 @@ def geo_ym_lambert_delta_v(
     )
 
 
+@dataclass(frozen=True, kw_only=True)
+class LambertResult:
+    """Single-case Lambert solution with the sampled transfer positions."""
+
+    departure_delta_v_m_s: tuple[float, float, float]
+    arrival_delta_v_m_s: tuple[float, float, float]
+    positions: tuple[float, ...]
+    """Flat ``(x, y, z, ...)`` transfer position sequence in meters.
+
+    The server samples ``path_point_count`` points including the departure and
+    arrival positions, so the sequence length is ``path_point_count * 3``.
+    """
+
+
 def lambert_delta_v(
     *,
     departure_state: CartesianState,
     arrival_state: CartesianState,
     time_of_flight_s: float,
     gravitational_parameter_m3_s2: float | None = None,
-) -> tuple[tuple[float, float, float], tuple[float, float, float]]:
-    """Return single-revolution Lambert delta-v between two Cartesian states."""
+    get_path_points: bool = False,
+    path_point_count: int | None = None,
+) -> tuple[tuple[float, float, float], tuple[float, float, float]] | LambertResult:
+    """Return single-revolution Lambert delta-v between two Cartesian states.
+
+    By default returns ``(departure_delta_v_m_s, arrival_delta_v_m_s)``. When
+    ``get_path_points`` is true, the server also samples the transfer orbit and
+    the return is a :class:`LambertResult` carrying the delta-v pair plus the
+    flat position sequence; ``path_point_count`` sets the sample count
+    (server default 100, including both endpoints).
+    """
     if not isinstance(departure_state, CartesianState):
         raise TypeError("departure_state must be a CartesianState instance")
     if not isinstance(arrival_state, CartesianState):
@@ -536,12 +560,20 @@ def lambert_delta_v(
         "TOF": [time_of_flight_s],
     }
     _include_if_supplied(payload, "Gm", gravitational_parameter_m3_s2)
+    if get_path_points:
+        payload["GetPathPoints"] = True
+        _include_if_supplied(payload, "NumberOfPathPoints", path_point_count)
 
     result = raw.post("/orbit/lambert", json=payload)
-    return (
-        (result["DV1"][0], result["DV1"][1], result["DV1"][2]),
-        (result["DV2"][0], result["DV2"][1], result["DV2"][2]),
-    )
+    departure_delta_v = (result["DV1"][0], result["DV1"][1], result["DV1"][2])
+    arrival_delta_v = (result["DV2"][0], result["DV2"][1], result["DV2"][2])
+    if get_path_points:
+        return LambertResult(
+            departure_delta_v_m_s=departure_delta_v,
+            arrival_delta_v_m_s=arrival_delta_v,
+            positions=tuple(result["Positions"]),
+        )
+    return departure_delta_v, arrival_delta_v
 
 
 def convert_czml_position(

astrox/propagator.py

@@ -42,6 +42,7 @@ __all__ = [
     "sgp4",
     "simple_ascent",
     "two_body",
+    "two_body_rv",
 ]
 
 
@@ -672,6 +673,36 @@ def two_body(
     return _success_path(result)
 
 
+def two_body_rv(
+    *,
+    state: CartesianState,
+    time_of_flight_s: float,
+    gravitational_parameter_m3_s2: float | None = None,
+    step_s: float | None = None,
+) -> tuple[float, ...]:
+    """Propagate a Cartesian state with two-body dynamics and return the sampled ephemeris.
+
+    Returns the flat ``[t, x, y, z, vx, vy, vz, ...]`` sequence, where ``t`` is
+    seconds relative to the initial epoch, positions are in meters, and
+    velocities are in m/s. The sequence includes the start and stop samples;
+    intermediate samples follow ``step_s`` (server default 60 s).
+    """
+    if not isinstance(state, CartesianState):
+        raise TypeError("state must be a CartesianState instance")
+
+    payload: dict[str, Any] = {
+        "RV0": state.to_wire(),
+        "TimeOfFlight": time_of_flight_s,
+    }
+    if gravitational_parameter_m3_s2 is not None:
+        payload["Gm"] = gravitational_parameter_m3_s2
+    if step_s is not None:
+        payload["Step"] = step_s
+
+    result = raw.post("/Propagator/TwoBodyRV", json=payload)
+    return tuple(result["Positions"])
+
+
 def j2(
     *,
     start: str,

astrox/terrain.py

@@ -45,6 +45,16 @@ def _optional_integer(value: int | None, *, parameter: str) -> int | None:
     return value
 
 
+def _without_status_fields(value: Any, *, endpoint: str) -> dict[str, Any]:
+    if not isinstance(value, dict):
+        raise TypeError(f"{endpoint} response must be an object")
+    return {
+        key: item
+        for key, item in value.items()
+        if key not in {"IsSuccess", "Message"}
+    }
+
+
 def _site_position_to_wire(
     value: components.SitePosition,
     *,
@@ -164,7 +174,10 @@ def _mask_request(
         "TerrainMaskPara",
         _terrain_mask_config_to_wire(config, parameter="config"),
     )
-    return raw.post(endpoint, json=payload)
+    return _without_status_fields(
+        raw.post(endpoint, json=payload),
+        endpoint=endpoint,
+    )
 
 
 def azimuth_elevation_mask(

{astrox_python-0.2.0.dist-info → astrox_python-1.1.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: astrox-python
-Version: 0.2.0
+Version: 1.1.0
 Summary: Python SDK for the ASTROX Web API.
 Project-URL: Homepage, https://github.com/Mtrya/astrox-python
 Project-URL: Repository, https://github.com/Mtrya/astrox-python.git
@@ -10,7 +10,7 @@ Author-email: Mtrya <erchanmion20@outlook.com>
 License-Expression: MIT
 License-File: LICENSE
 Keywords: astrodynamics,astrox,orbit,propagation,sdk,space
-Classifier: Development Status :: 3 - Alpha
+Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Science/Research
 Classifier: License :: OSI Approved :: MIT License

{astrox_python-0.2.0.dist-info → astrox_python-1.1.0.dist-info}/RECORD

@@ -1,16 +1,17 @@
-astrox/__init__.py,sha256=9wJZtYZQoUqgmSBDMYGXQHskNmZDqcTbGV-KbK0eeIU,1523
+astrox/__init__.py,sha256=2OlHH2Bx83mXoazHMd6hOD3laKNqrYQrgK-JNmRvtAM,1566
 astrox/_http.py,sha256=ZZDkJ6qPG4VbMDRZO7xonIib88aYS6PPTVRxRYwXU3A,15606
 astrox/access.py,sha256=pjyCher_yQNmkoojf2sWpG1HRDnLLK9gI90jM1iEoTo,5817
 astrox/cat.py,sha256=doZqy6lGDtgrVe9QlU57l1lccmzirc14RDSR41tyGUU,15057
-astrox/catalog.py,sha256=OK1Qp9J4CJBkD7sn4qpZCuXT78VgAzMY0s1pZLMkPIk,4754
-astrox/celestial.py,sha256=rOCRBQukYPJSkUcSHYzDTeSrtj0HmpmKLyoLiBIoefc,4163
+astrox/catalog.py,sha256=WDb3adiDO41YY6IdivjN3ri1vIQMHi6DPI3dBa8W1Gc,5255
+astrox/celestial.py,sha256=ILZjn1MrjYS4cqpp4aBDnwJGBkAv5dW-V87eh6bJFxg,12444
 astrox/conjunction.py,sha256=sXhTNAlMai27ejuJekksaAw-850nHPimo21YdFpuzQo,9108
 astrox/exceptions.py,sha256=apClRT1r-N3XY1ibXxkW3oxpsJgiHos4tC0cMJ8eBRk,2592
+astrox/libration.py,sha256=YBgcZi2pTAjL5VUlE8y6jLhVbYnwRxv-PIUxJQmFBSg,13454
 astrox/lighting.py,sha256=aWMty64rU3wv1H1Q5q-yXG5mINbIY31omyd-pjdNaVs,3876
-astrox/orbits.py,sha256=JiSkCyWqYmeV-yX5WBL9554_JNhec1Li8EdmkZmzXQc,17823
-astrox/propagator.py,sha256=kiW4kFSBy2_quZPZ2VqP49vfSYDKkJ1dna5rM5bo-9M,37334
+astrox/orbits.py,sha256=SdRE7f9W9zO4N6Xxjg5quHK--gsVh1E5qdvJigpwxLA,19223
+astrox/propagator.py,sha256=GPcg5fpra_jsof4ipxgtaeJNof2PrWBvUTnDG1aH940,38434
 astrox/rocket.py,sha256=tb6wXc4bZ0EMAd9bVzva_7k3I9S2lsYA7Q2RD6byqfk,2755
-astrox/terrain.py,sha256=mAcjIAVjUMch4z8M1asMdmtof-7ox-tpXE218sPR2jY,5777
+astrox/terrain.py,sha256=2v_Ca5OnXjmMtIKNFQJ_Kbdsh42ZuIc4ZDe-0aWnpdg,6146
 astrox/astrogator/__init__.py,sha256=rgIHos9rHjQ3i-qkpLeLRwZL6zsVthc2bOVbAdwHWHU,267
 astrox/astrogator/_api.py,sha256=ovfBHzstXmhLj1QKIFFSpraEQb5ZRlMlAwaUCXvIiqA,1882
 astrox/astrogator/_models.py,sha256=jIFts5jH6RjAb6NneU4WLqpbwQU2IWGX_1h3OMs8Tww,50620
@@ -32,7 +33,7 @@ astrox/coverage/number_of_assets.py,sha256=Bf1OQRu1r9lunyARyQoV4x7KetkgY_7OMNcEc
 astrox/coverage/response_time.py,sha256=yLnv8eEDL6CS0PJHC1JIKBCoOachOwo3m8dNoHH3HfQ,5164
 astrox/coverage/revisit_time.py,sha256=R5vF2egixCF9elvsGYXzpgWbD5lfcQW8uZqi1ifIDX8,5155
 astrox/coverage/simple_coverage.py,sha256=ZPj3HrP3M59rG47pz4eHt1rq-vTlk-oZ7c2ZBmFsz1U,4992
-astrox_python-0.2.0.dist-info/METADATA,sha256=wgkeBpIfyYGbDhlj84CC55b2WR84zkKrrIFKAI-ha9c,2508
-astrox_python-0.2.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
-astrox_python-0.2.0.dist-info/licenses/LICENSE,sha256=Fbt55lCQnv_n5yGhbG_VDlowjaV_FPHBQWsJIyuBpDk,1062
-astrox_python-0.2.0.dist-info/RECORD,,
+astrox_python-1.1.0.dist-info/METADATA,sha256=2oZePQ_YT4pqPYJP2PqhKlPrLxWt3YfcxUml36z_9pQ,2520
+astrox_python-1.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+astrox_python-1.1.0.dist-info/licenses/LICENSE,sha256=Fbt55lCQnv_n5yGhbG_VDlowjaV_FPHBQWsJIyuBpDk,1062
+astrox_python-1.1.0.dist-info/RECORD,,

{astrox_python-0.2.0.dist-info → astrox_python-1.1.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.31.0
+Generator: hatchling 1.32.0
 Root-Is-Purelib: true
 Tag: py3-none-any