astrox-python 1.0.0__tar.gz → 1.2.0__tar.gz

{astrox_python-1.0.0 → astrox_python-1.2.0}/.gitignore

@@ -11,9 +11,13 @@ wheels/
 # Virtual environments
 .venv
 
+# Local-only server runtime for validation triage (never commit)
+.local-runtime/
+
 # Internal & intermediate docs
 *.md
 !README.md
+!AGENTS.md
 !docs/**/*.md
 docs/MAINTAINER_QUESTIONS.md
 !openapi/**/*.md

{astrox_python-1.0.0 → astrox_python-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: astrox-python
-Version: 1.0.0
+Version: 1.2.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

{astrox_python-1.0.0 → astrox_python-1.2.0}/astrox/celestial.py

@@ -74,6 +74,9 @@ class MpcOrbitalElements:
     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 (
@@ -95,9 +98,14 @@ class MpcOrbitalElements:
                     parameter=field_name,
                 ),
             )
+        object.__setattr__(
+            self,
+            "reference_frame",
+            _optional_string(self.reference_frame, parameter="reference_frame"),
+        )
 
-    def to_wire(self) -> dict[str, float]:
-        payload: dict[str, float] = {}
+    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)
@@ -111,6 +119,7 @@ class MpcOrbitalElements:
             self.argument_of_periapsis_deg,
         )
         _include_if_supplied(payload, "MeanAnomaly", self.mean_anomaly_deg)
+        _include_if_supplied(payload, "ReferenceFrame", self.reference_frame)
         return payload
 
 
@@ -125,6 +134,7 @@ def mpc_orbital_elements(
     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(
@@ -137,6 +147,7 @@ def mpc_orbital_elements(
         raan_deg=raan_deg,
         argument_of_periapsis_deg=argument_of_periapsis_deg,
         mean_anomaly_deg=mean_anomaly_deg,
+        reference_frame=reference_frame,
     )
 
 
@@ -153,7 +164,7 @@ def _elements_to_wire(
     value: MpcOrbitalElements | None,
     *,
     parameter: str,
-) -> dict[str, float] | None:
+) -> dict[str, Any] | None:
     if value is None:
         return None
     if not isinstance(value, MpcOrbitalElements):
@@ -175,6 +186,9 @@ def lambert_transfer_window(
     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.
 
@@ -236,6 +250,30 @@ def lambert_transfer_window(
         "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",
@@ -331,8 +369,16 @@ def mpc_ephemeris(
     observer_frame: str | None = None,
     start: str | None = None,
     stop: str | None = None,
+    step_s: float | 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. ``step_s`` controls the output sampling cadence; zero
+    requests the server's internal integration grid.
+    """
     payload: dict[str, Any] = {
         "TargetName": _string(target_name, parameter="target_name"),
     }
@@ -351,6 +397,16 @@ def mpc_ephemeris(
         "Stop",
         _optional_string(stop, parameter="stop"),
     )
+    _include_if_supplied(
+        payload,
+        "Step",
+        _optional_number(step_s, parameter="step_s"),
+    )
+    _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_python-1.0.0 → astrox_python-1.2.0}/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_python-1.0.0 → astrox_python-1.2.0}/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_python-1.0.0 → astrox_python-1.2.0}/docs/how_to/compute_lambert_transfer.md

@@ -23,6 +23,9 @@ transfer = celestial.lambert_transfer_window(
     min_time_of_flight_days=10,
     departure_step_days=2.0,
     arrival_step_days=1.0,
+    # 该窗口出发双曲超速约 15 km/s，超出服务端 MaxDepartureDV 缺省值
+    # （10000 m/s），需要显式放宽上限才能保留结果
+    max_departure_delta_v_m_s=20000,
 )
 
 results = transfer["TransferResults"]
@@ -32,7 +35,8 @@ for result in results:
     print(
         f"出发 {result['DepartureTime']} → 到达 {result['ArrivalTime']}: "
         f"|DeltaV1|={result['DV1_Mag']:.1f} m/s, "
-        f"|DeltaV2|={result['DV2_Mag']:.1f} m/s"
+        f"|DeltaV2|={result['DV2_Mag']:.1f} m/s, "
+        f"TOF={result['TimeOfFlightDays']:.0f} d"
     )
 ```
 
@@ -47,14 +51,17 @@ python compute_lambert_transfer.py
 1. **选出发与到达天体**：`departure_body`/`arrival_body` 接受服务端支持的天体名称（如 `Earth`、`Mars`、`Ceres`）以及 MPC 编号或名称（如 `2015 XF261`）。小行星省略对应的 `*_elements` 参数时，服务端通过网络查询 MPC 根数。
 2. **定两个时间窗口**：`departure_start`/`departure_stop` 与 `arrival_start`/`arrival_stop` 各定义一个 UTC 时间窗口，SDK 分别组合为 `DepartureInterval`/`ArrivalInterval` 的 `"开始/结束"` 字符串。`departure_step_days` 与 `arrival_step_days`（单位 d）控制窗口内的采样步长，结果个数约等于两个窗口采样点数的乘积；示例中的 2 个出发日 × 3 个到达日产生 6 条结果。`min_time_of_flight_days`（单位 d，整数）过滤掉转移时间太短的组合，服务端缺省 10。
 3. **选输出参考系**：`sun_frame` 服务端缺省 `MeanEclpJ2000`；`ICRF` 分支的转移速度已与独立零圈顺行 Lambert 解一致，端点位置方向也已识别为 ICRF 轴方向，而 `MeanEclpJ2000` 与 ICRF 的精确关系尚未独立确认，需要参考系明确的数值时建议显式传 `sun_frame="ICRF"`。
+4. **按需调整过滤上限**：2026-08-20 起服务端按 `max_departure_delta_v_m_s`/`max_arrival_delta_v_m_s`（缺省各 10000 m/s，分别对应出发/到达双曲超速大小）与 `max_time_of_flight_days`（缺省 500 d）过滤算例，全部超界时返回空列表；扫描大 ΔV 或超长转移窗口时需显式放宽，示例中的 Earth→Mars 窗口就属于这种情况。
 
 ## 读懂结果
 
 每个结果对象包含：
 
 - `DepartureTime`/`ArrivalTime`：出发/到达时刻（UTC 字符串）。
-- `DeltaV1`/`DeltaV2`：出发/到达速度增量向量（m/s）；`DV1_Mag`/`DV2_Mag` 是它们的欧几里得范数（m/s）。`DeltaV` 相对端点天体速度的物理含义尚未独立确认，需要严格物理解释时请先核对。
+- `DeltaV1`/`DeltaV2`：出发/到达速度增量向量（出发/到达双曲超速矢量，m/s）；`DV1_Mag`/`DV2_Mag` 是它们的欧几里得范数（m/s）。`DeltaV` 相对端点天体速度的物理含义尚未独立确认，需要严格物理解释时请先核对。
 - `RV1`/`RV2`：出发/到达时的日心位置速度 `[x, y, z, vx, vy, vz]`（位置 m、速度 m/s）；ICRF 分支下转移速度与独立 Lambert 解一致，端点位置方向与 ICRF 轴方向一致。
+- `TimeOfFlightDays`：飞行时间（d），已验证为到达与出发时刻的精确天数差。
+- `ArrivalLightAngle`：到达时刻太阳光照角（deg），已验证为 `DeltaV2` 与 `RV2` 位置矢量的夹角。
 
 ## 小行星与显式 MPC 根数
 
@@ -84,7 +91,7 @@ transfer = celestial.lambert_transfer_window(
 )
 ```
 
-注意：显式 MPC 根数的独立开普勒递推尚未验证，元素系、参考系与时间约定未确认；这个分支可调用、响应结构已由 live 快照记录，但数值语义请自行核对。
+注意：显式 MPC 根数在转移路由中的独立开普勒递推尚未验证，元素系与时间约定未确认（`reference_frame` 选项不改变该路由的到达状态）；这个分支可调用、响应结构已由 live 快照记录，但数值语义请自行核对。`mpc_ephemeris` 的 `target_elements` 分支已验证（见天体手册）。
 
 ## 了解更多
 

{astrox_python-1.0.0 → astrox_python-1.2.0}/docs/how_to/propagate_an_orbit.md

@@ -6,9 +6,10 @@
 
 1. **输入决定传播器**：
    - 有开普勒根数 → 用 `propagator.j2` 或 `propagator.two_body`。
+   - 有笛卡尔位置速度状态 → 用 `propagator.two_body_rv`（纯二体，返回扁平星历序列，不返回 `(period_s, position)`）。
    - 有两行根数（TLE） → 用 `propagator.sgp4`。
    - 有力模型配置 → 用 `propagator.hpop`。
-2. **读取采样**：所有单轨传播函数都返回 `(period_s, position)`，其中 `position.cartesian_velocity` 是 CZML 风格的扁平序列 `[t, x, y, z, vx, vy, vz, ...]`。
+2. **读取采样**：除 `two_body_rv` 外，所有单轨传播函数都返回 `(period_s, position)`，其中 `position.cartesian_velocity` 是 CZML 风格的扁平序列 `[t, x, y, z, vx, vy, vz, ...]`。
 
 ## 完整示例
 
@@ -139,6 +140,7 @@ HPOP 传播
 | --- | --- | --- |
 | 开普勒根数 | `propagator.j2` | 考虑 J2 摄动，适合大多数低轨任务。 |
 | 开普勒根数，纯二体 | `propagator.two_body` | 只考虑中心天体引力，计算最快。 |
+| 笛卡尔位置速度状态 | `propagator.two_body_rv` | 定步长数值二体积分，返回扁平星历序列 `[t, x, y, z, vx, vy, vz, ...]`。 |
 | 两行根数（TLE） | `propagator.sgp4` | 直接从 TLE 传播，无需手动构造根数。 |
 | 需要配置力模型 | `propagator.hpop` | 支持重力场、大气、太阳辐射压、第三方天体摄动等配置。 |
 

{astrox_python-1.0.0 → astrox_python-1.2.0}/docs/i18n/en/how_to/compute_lambert_transfer.md

@@ -23,6 +23,10 @@ transfer = celestial.lambert_transfer_window(
     min_time_of_flight_days=10,
     departure_step_days=2.0,
     arrival_step_days=1.0,
+    # this window's departure hyperbolic excess speed is about 15 km/s, above
+    # the server MaxDepartureDV default (10000 m/s); widen the bound explicitly
+    # to keep the results
+    max_departure_delta_v_m_s=20000,
 )
 
 results = transfer["TransferResults"]
@@ -32,7 +36,8 @@ for result in results:
     print(
         f"Departure {result['DepartureTime']} → arrival {result['ArrivalTime']}: "
         f"|DeltaV1|={result['DV1_Mag']:.1f} m/s, "
-        f"|DeltaV2|={result['DV2_Mag']:.1f} m/s"
+        f"|DeltaV2|={result['DV2_Mag']:.1f} m/s, "
+        f"TOF={result['TimeOfFlightDays']:.0f} d"
     )
 ```
 
@@ -47,14 +52,17 @@ python compute_lambert_transfer.py
 1. **Choose the departure and arrival bodies**: `departure_body`/`arrival_body` accept server-supported body names (e.g. `Earth`, `Mars`, `Ceres`) and MPC numbers or names (e.g. `2015 XF261`). When the matching `*_elements` argument is omitted for an asteroid, the server queries the MPC elements over the network.
 2. **Set the two time windows**: `departure_start`/`departure_stop` and `arrival_start`/`arrival_stop` each define a UTC time window, which the SDK combines into the `"start/stop"` string of `DepartureInterval`/`ArrivalInterval` respectively. `departure_step_days` and `arrival_step_days` (unit d) control the sample step within each window; the number of results is roughly the product of the two windows' sample counts — the 2 departure days × 3 arrival days in the example produce 6 results. `min_time_of_flight_days` (unit d, integer) filters out combinations whose transfer time is too short; the server default is 10.
 3. **Choose the output reference frame**: the server default for `sun_frame` is `MeanEclpJ2000`; the transfer velocities of the `ICRF` branch agree with an independent zero-revolution prograde Lambert solution, and the endpoint position directions have also been identified as ICRF axes, while the exact relationship between `MeanEclpJ2000` and ICRF is not yet independently confirmed, so pass `sun_frame="ICRF"` explicitly when you need numbers with an identified frame.
+4. **Adjust the filter bounds as needed**: since 2026-08-20 the server filters cases by `max_departure_delta_v_m_s`/`max_arrival_delta_v_m_s` (defaults 10000 m/s each, the departure/arrival hyperbolic excess speed magnitudes) and `max_time_of_flight_days` (default 500 d), returning an empty list when everything is out of bounds; widen the bounds explicitly when scanning large-ΔV or very long transfer windows — the Earth→Mars window in the example is such a case.
 
 ## Reading the results
 
 Each result object contains:
 
 - `DepartureTime`/`ArrivalTime`: departure/arrival times (UTC strings).
-- `DeltaV1`/`DeltaV2`: departure/arrival velocity-increment vectors (m/s); `DV1_Mag`/`DV2_Mag` are their Euclidean norms (m/s). The physical meaning of `DeltaV` relative to the endpoint bodies' velocities is not yet independently confirmed, so verify it yourself when you need a strict physical interpretation.
+- `DeltaV1`/`DeltaV2`: departure/arrival velocity-increment vectors (departure/arrival hyperbolic excess velocity vectors, m/s); `DV1_Mag`/`DV2_Mag` are their Euclidean norms (m/s). The physical meaning of `DeltaV` relative to the endpoint bodies' velocities is not yet independently confirmed, so verify it yourself when you need a strict physical interpretation.
 - `RV1`/`RV2`: heliocentric position and velocity at departure/arrival `[x, y, z, vx, vy, vz]` (positions m, velocities m/s); under the ICRF branch the transfer velocities agree with the independent Lambert solution, and the endpoint position directions match the ICRF axes.
+- `TimeOfFlightDays`: time of flight (d), verified to be the exact day difference between the arrival and departure times.
+- `ArrivalLightAngle`: Sun lighting angle at arrival (deg), verified to be the angle between `DeltaV2` and the `RV2` position vector.
 
 ## Asteroids and explicit MPC elements
 
@@ -84,7 +92,7 @@ transfer = celestial.lambert_transfer_window(
 )
 ```
 
-Note: independent Kepler propagation of explicit MPC elements is not yet verified, and the element system, reference frame, and time convention are unconfirmed; this branch is callable and its response structure is recorded by live snapshots, but verify the numeric semantics yourself.
+Note: independent Kepler propagation of explicit MPC elements in the transfer route is not yet verified, and the element system and time convention are unconfirmed (the `reference_frame` option does not change the arrival states of that route); this branch is callable and its response structure is recorded by live snapshots, but verify the numeric semantics yourself. The `target_elements` branch of `mpc_ephemeris` is verified (see the celestial manual).
 
 ## Learn more
 

{astrox_python-1.0.0 → astrox_python-1.2.0}/docs/i18n/en/how_to/propagate_an_orbit.md

@@ -6,9 +6,10 @@ This page solves a specific task: choose the right propagator from the orbit des
 
 1. **Input determines the propagator**:
    - You have Keplerian elements → use `propagator.j2` or `propagator.two_body`.
+   - You have a Cartesian position/velocity state → use `propagator.two_body_rv` (pure two-body; returns a flat ephemeris sequence, not `(period_s, position)`).
    - You have a two-line element set (TLE) → use `propagator.sgp4`.
    - You have a force model config → use `propagator.hpop`.
-2. **Reading the samples**: all single-orbit propagation functions return `(period_s, position)`, where `position.cartesian_velocity` is a CZML-style flat sequence `[t, x, y, z, vx, vy, vz, ...]`.
+2. **Reading the samples**: except for `two_body_rv`, all single-orbit propagation functions return `(period_s, position)`, where `position.cartesian_velocity` is a CZML-style flat sequence `[t, x, y, z, vx, vy, vz, ...]`.
 
 ## Complete example
 
@@ -139,6 +140,7 @@ Every 7 numbers in `cartesian_velocity` form one frame: time offset (seconds), p
 | --- | --- | --- |
 | Keplerian elements | `propagator.j2` | Includes J2 perturbation; suitable for most LEO missions. |
 | Keplerian elements, pure two-body | `propagator.two_body` | Only central-body gravity; fastest computation. |
+| Cartesian position/velocity state | `propagator.two_body_rv` | Fixed-step numerical two-body integration; returns a flat ephemeris sequence `[t, x, y, z, vx, vy, vz, ...]`. |
 | Two-line element set (TLE) | `propagator.sgp4` | Propagates directly from TLE; no need to build elements manually. |
 | Need to configure a force model | `propagator.hpop` | Supports gravity field, atmosphere, solar radiation pressure, third-body perturbations, and more. |
 

{astrox_python-1.0.0 → astrox_python-1.2.0}/docs/i18n/en/manual/celestial/README.md

@@ -32,7 +32,7 @@ Computes an ephemeris for a target body over a time window and returns a raw JSO
 | `start` | `Start` | Analysis start time (UTC, `yyyy-MM-ddTHH:mm:ssZ`). Optional; the server default is January 1 of the current year |
 | `stop` | `Stop` | Analysis stop time (UTC). Optional; the server default is December 31 of the current year |
 | `observer_name` | `ObserverName` | Observer name, e.g. `Earth`; the server default is `Sun` |
-| `observer_frame` | `ObserverFrame` | Observer frame, server options `FIXED`, `INERTIAL`, `MeanEclpJ2000`, `J2000`, default `MeanEclpJ2000` |
+| `observer_frame` | `ObserverFrame` | Observer frame; the server currently accepts `FIXED`, `INERTIAL`, `MeanEclpJ2000`, `EclpJ2000ICRF`, `J2000`, and `ICRF`; default `MeanEclpJ2000` |
 | `step_s` | `Step` | Sample step, in s, server default 86400 s |
 
 `target_name` is the only required request field of this function; `start` and `stop` are optional — when omitted they are not sent to ASTROX and the server selects January 1 to December 31 of the current year as the window. Other optional fields that are not supplied are likewise not sent to ASTROX, and the server retains its default values.
@@ -43,7 +43,7 @@ from astrox import celestial
 start = "2026-01-01T00:00:00.000Z"
 stop = "2026-01-02T00:00:00.000Z"
 
-for frame in ("J2000", "MeanEclpJ2000"):
+for frame in ("J2000", "MeanEclpJ2000", "EclpJ2000ICRF"):
     ephemeris = celestial.ephemeris(
         target_name="Moon",
         start=start,
@@ -81,11 +81,11 @@ Computes the rotation from the coordinate axes of the source central body to tho
 | `from_central_body` | `FromCbName` | Source central body name, e.g. `Earth` |
 | `to_central_body` | `ToCbName` | Target central body name, e.g. `Moon` |
 | `epoch` | `Epoch` | Epoch time (UTC) |
-| `from_frame` | `FromCbFrame` | Source frame, server options `FIXED`, `INERTIAL`, `J2000`, `ICRF`, `MeanEclpJ2000`, default `INERTIAL` |
+| `from_frame` | `FromCbFrame` | Source frame, server options `FIXED`, `INERTIAL`, `J2000`, `ICRF`, `MeanEclpJ2000`, `EclpJ2000ICRF`, default `INERTIAL` |
 | `to_frame` | `ToCbFrame` | Target frame, same options, default `FIXED` |
 | `order` | `Order` | Rotation motion order: `0` returns the quaternion only, `1` returns the quaternion and angular velocity; passed through as an integer |
 
-`order` is preserved as an integer and lowered to the server as-is; the SDK does not rewrite the branch. The `Rotation` field of the response is a numeric array: with `order=0` it has length 4 (quaternion `[qx, qy, qz, qw]`), and with `order=1` it has length 7 (quaternion plus angular-velocity components, unit rad/s per the server documentation). Verified numeric semantics include: for the same central body on both sides with `INERTIAL` frames on both sides, the server returns the identity quaternion with zero angular velocity at `order=1`; the Earth `INERTIAL`→`FIXED` quaternion and angular velocity; and the Earth→Moon `INERTIAL`→`FIXED` angular velocity at `order=1`. The Earth→Moon `INERTIAL`→`FIXED` quaternion is unresolved, and other combinations are unverified, so verify their meaning yourself before use.
+`order` is preserved as an integer and lowered to the server as-is; the SDK does not rewrite the branch. The `Rotation` field of the response is a numeric array: with `order=0` it has length 4 (quaternion `[qx, qy, qz, qw]`), and with `order=1` it has length 7 (quaternion plus angular-velocity components, unit rad/s per the server documentation). Verified numeric semantics include: for the same central body on both sides with `INERTIAL` frames on both sides, the server returns the identity quaternion with zero angular velocity at `order=1`; Earth→Earth `EclpJ2000ICRF`→`ICRF` follows the fixed J2000 mean-obliquity rotation with zero angular velocity at the two maintained epochs and `order=0/1`; the Earth `INERTIAL`→`FIXED` quaternion and angular velocity; and the Earth→Moon `INERTIAL`→`FIXED` angular velocity at `order=1`. The Earth→Moon `INERTIAL`→`FIXED` quaternion is unresolved, and other combinations are unverified, so verify their meaning yourself before use.
 
 ```python
 rotation = celestial.cb_axes_rotation(
@@ -113,22 +113,28 @@ celestial.mpc_ephemeris(
     observer_frame: str | None = None,
     start: str | None = None,
     stop: str | None = None,
+    step_s: float | None = None,
+    target_elements: MpcOrbitalElements | None = None,
 ) -> dict[str, Any]
 ```
 
-Queries an MPC minor-planet ephemeris by asteroid name or number and returns a raw JSON response dictionary.
+Queries an MPC minor-planet ephemeris by asteroid name or number and returns a raw JSON response dictionary. When `target_elements` is provided, the server integrates the given MPC orbital elements directly instead of querying MPC over the network.
 
 | Parameter | Wire parameter | Description |
 | --- | --- | --- |
 | `target_name` | `TargetName` | Asteroid name or number, e.g. `Ceres`, `99942` |
-| `observer_frame` | `ObserverFrame` | Heliocentric frame, server options `FIXED`, `INERTIAL`, `MeanEclpJ2000`, `J2000`, default `MeanEclpJ2000` |
+| `observer_frame` | `ObserverFrame` | Heliocentric frame, server options `FIXED`, `INERTIAL`, `J2000`, `ICRF`, `MeanEclpJ2000`, `EclpJ2000ICRF`, default `MeanEclpJ2000` |
 | `start` | `Start` | Start time (UTC); defaults to the orbital epoch and cannot be earlier than the orbital epoch (server rule) |
 | `stop` | `Stop` | Stop time (UTC); defaults to 1 year after `Start` |
+| `step_s` | `Step` | Output sample step, in s, server default 86400 s; pass `0` to output at the internal integration steps |
+| `target_elements` | `TargetElements` | Explicit MPC orbital elements (built with `mpc_orbital_elements`); when omitted, the server queries MPC over the network |
+
+This route fetches orbital elements from the external MPC data source (element epoch in MJD TDT). The server contract declares adaptive heliocentric integration followed by Hermite interpolation onto the fixed output grid selected by `step_s`; `step_s=0` requests output at the server-declared internal integration steps. The response is a heliocentric CZML Position structure containing `OrbitElements` (orbital elements with keys `EpochMjdTdt`, `PeriTimeMjdTdt`, `Q`, `SemimajorAxis`, `Eccentricity`, `Inclination`, `Raan`, `ArgOfPeriapsis`, `MeanAnomaly`, `ReferenceFrame`) and `Position` (CZML structure, same as `ephemeris`). The orbital-element values come from external MPC data, are owned by that external data source, and may change with MPC updates. When `start`/`stop` are omitted, the server uses the orbital-epoch default window (`start` is the orbital epoch and `stop` is one year after it); an explicit fixed window depends on the orbital epoch at query time, and once the external MPC orbital epoch updates, a previously fixed window may fall before the new epoch and be rejected by the server, so prefer omitting the window parameters or following the current epoch.
 
-This route fetches orbital elements from the external MPC data source (element epoch in MJD TDT), which the server propagates heliocentrically with a fixed 1-day step, and outputs a heliocentric CZML Position structure. The response contains `OrbitElements` (orbital elements with keys `EpochMjdTdt`, `PeriTimeMjdTdt`, `Q`, `SemimajorAxis`, `Eccentricity`, `Inclination`, `Raan`, `ArgOfPeriapsis`, `MeanAnomaly`) and `Position` (CZML structure, same as `ephemeris`). The orbital-element values come from external MPC data, are owned by that external data source, and may change with MPC updates. When `start`/`stop` are omitted, the server uses the orbital-epoch default window (`start` is the orbital epoch and `stop` is one year after it); an explicit fixed window depends on the orbital epoch at query time, and once the external MPC orbital epoch updates, a previously fixed window may fall before the new epoch and be rejected by the server, so prefer omitting the window parameters or following the current epoch.
+Verified (within-route invariants): passing the `OrbitElements` returned by a name query back as `target_elements` reproduces the name-query ephemeris exactly; omitting `step_s` exactly matches explicit `86400`, `172800` produces an exact subset of the daily grid, and `0` returns the same endpoints on a nonuniform internal integration grid; the `reference_frame` values `EclpJ2000ICRF` (MPC convention, server default) and `MeanEclpJ2000` (JPL convention) are two distinguishable branches. This evidence verifies request branches and output-sampling semantics, not absolute orbit accuracy. See the [celestial validation page](../../../../validation/celestial.md) for details.
 
 ```python
-mpc = celestial.mpc_ephemeris(target_name="Ceres")
+mpc = celestial.mpc_ephemeris(target_name="Ceres", step_s=172800.0)
 
 print(f"Ceres MPC ephemeris: {len(mpc['Position']['cartesianVelocity']) // 7} state samples")
 ```
@@ -149,6 +155,7 @@ celestial.mpc_orbital_elements(
     raan_deg: float | None = None,
     argument_of_periapsis_deg: float | None = None,
     mean_anomaly_deg: float | None = None,
+    reference_frame: str | None = None,
 ) -> MpcOrbitalElements
 ```
 
@@ -165,6 +172,7 @@ Builds a heliocentric MPC orbital-element fragment. When either the departure or
 | `raan_deg` | `Raan` | deg |
 | `argument_of_periapsis_deg` | `ArgOfPeriapsis` | deg |
 | `mean_anomaly_deg` | `MeanAnomaly` | deg |
+| `reference_frame` | `ReferenceFrame` | Heliocentric ecliptic frame variant: `MeanEclpJ2000` (JPL) or `EclpJ2000ICRF` (MPC, server default) |
 
 ```python
 from astrox import celestial
@@ -184,7 +192,7 @@ elements = celestial.mpc_orbital_elements(
 print(elements.to_wire())
 ```
 
-`to_wire()` returns the ASTROX `MpcOrbElements` request fragment; the example above prints `{'EpochMjdTdt': 61000.0, 'PeriTimeMjdTdt': 60900.0, 'Q': 0.6740515, 'SemimajorAxis': 0.9898367, 'Eccentricity': 0.3190276, 'Inclination': 0.79379, 'Raan': 209.81829, 'ArgOfPeriapsis': 100.88187, 'MeanAnomaly': 120.0}`. When passed to `lambert_transfer_window`, the server propagates heliocentrically directly with these elements and no longer queries MPC over the network. The independent Kepler propagation of explicit elements is unverified: the element system, reference frame, and time convention are not confirmed, so verify their meaning yourself before use.
+`to_wire()` returns the ASTROX `MpcOrbElements` request fragment; the example above prints `{'EpochMjdTdt': 61000.0, 'PeriTimeMjdTdt': 60900.0, 'Q': 0.6740515, 'SemimajorAxis': 0.9898367, 'Eccentricity': 0.3190276, 'Inclination': 0.79379, 'Raan': 209.81829, 'ArgOfPeriapsis': 100.88187, 'MeanAnomaly': 120.0}`. When passed to `lambert_transfer_window`, the server propagates heliocentrically directly with these elements and no longer queries MPC over the network. The independent Kepler propagation of explicit elements in that route is unverified: the element system and time convention are not confirmed (the `reference_frame` option does not change the arrival states of that route); the `target_elements` branch of `mpc_ephemeris` is verified (see above), so verify the meaning yourself before use.
 
 ## Lambert transfer windows
 
@@ -205,10 +213,13 @@ celestial.lambert_transfer_window(
     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]
 ```
 
-Samples over the departure time window and the arrival time window, computes Lambert transfers between bodies, and returns a raw JSON response dictionary. It is not the single-case `orbits.lambert_delta_v` interface: that function takes two `CartesianState` values and a `time_of_flight_s`, calls `/orbit/lambert`, and returns the two triples `(DV1, DV2)`; this function scans the whole grid of departure/arrival time pairs and returns a `TransferResults` list.
+Samples over the departure time window and the arrival time window, computes Lambert transfers between bodies, and returns a raw JSON response dictionary. It is not the single-case `orbits.lambert_delta_v` interface: that function takes two `CartesianState` values and a `time_of_flight_s`, calls `/orbit/lambert`, and by default returns the two triples `(DV1, DV2)`; this function scans the whole grid of departure/arrival time pairs and returns a `TransferResults` list.
 
 | Parameter | Wire parameter | Description |
 | --- | --- | --- |
@@ -218,12 +229,15 @@ Samples over the departure time window and the arrival time window, computes Lam
 | `departure_stop` | `DepartureInterval` | Departure time window end (UTC) |
 | `arrival_start` | `ArrivalInterval` | Arrival time window start (UTC); combined with `arrival_stop` into `"start/stop"` |
 | `arrival_stop` | `ArrivalInterval` | Arrival time window end (UTC) |
-| `sun_frame` | `SunFrameName` | Heliocentric frame, server options `MeanEclpJ2000`, `ICRF`, default `MeanEclpJ2000` |
+| `sun_frame` | `SunFrameName` | Heliocentric output frame; the server currently accepts `MeanEclpJ2000`, `EclpJ2000ICRF`, and `ICRF`; default `EclpJ2000ICRF` |
 | `min_time_of_flight_days` | `MinTofDays` | Minimum transfer time, in d, integer; server default 10 |
 | `departure_step_days` | `DepartureStepDay` | Departure time sample step, in d; server default 1 |
 | `arrival_step_days` | `ArrivalStepDay` | Arrival time sample step, in d; server default 1 |
 | `departure_elements` | `DepartureElements` | MPC orbital elements of the departure asteroid (built with `mpc_orbital_elements`); when omitted, the server queries MPC over the network |
 | `arrival_elements` | `ArrivalElements` | MPC orbital elements of the arrival asteroid; when omitted, the server queries MPC over the network |
+| `max_departure_delta_v_m_s` | `MaxDepartureDV` | Maximum departure velocity increment (departure hyperbolic excess speed magnitude), in m/s, integer; server default 10000, cases above it are filtered out |
+| `max_arrival_delta_v_m_s` | `MaxArrivalDV` | Maximum arrival velocity increment (arrival hyperbolic excess speed magnitude), in m/s, integer; server default 10000, cases above it are filtered out |
+| `max_time_of_flight_days` | `MaxTofDays` | Maximum transfer time, in d, integer; server default 500, cases above it are filtered out |
 
 `departure_body`, `arrival_body`, and the four time strings are the required request fields of this function; `DepartureInterval`/`ArrivalInterval` is a single `"start/stop"` string, e.g. `"2028-06-01T00:00:00Z/2028-06-03T00:00:00Z"`. Other optional parameters that are not supplied are not sent to ASTROX, and the server retains its default values.
 
@@ -241,6 +255,9 @@ transfer = celestial.lambert_transfer_window(
     min_time_of_flight_days=10,
     departure_step_days=2.0,
     arrival_step_days=1.0,
+    # this window's departure hyperbolic excess speed is about 15 km/s, above
+    # the server MaxDepartureDV default (10000 m/s); widen the bound explicitly
+    max_departure_delta_v_m_s=20000,
 )
 
 results = transfer["TransferResults"]
@@ -248,20 +265,23 @@ first = results[0]
 print(f"{len(results)} transfer results")
 print(
     f"First: {first['DepartureTime']} → {first['ArrivalTime']}, "
-    f"|DeltaV1|={first['DV1_Mag']:.1f} m/s, |DeltaV2|={first['DV2_Mag']:.1f} m/s"
+    f"|DeltaV1|={first['DV1_Mag']:.1f} m/s, |DeltaV2|={first['DV2_Mag']:.1f} m/s, "
+    f"TOF={first['TimeOfFlightDays']:.0f} d"
 )
 ```
 
-The response contains `TransferResults` (an array of transfer results; each element corresponds to one sampled departure/arrival time pair, and the number of results is determined jointly by the two time windows and the sample steps). Each result has the following keys:
+The response contains `TransferResults` (an array of transfer results; each element corresponds to one sampled departure/arrival time pair, and the number of results is determined jointly by the two time windows and the sample steps, and is also affected by `min_time_of_flight_days` and the `max_departure_delta_v_m_s`/`max_arrival_delta_v_m_s`/`max_time_of_flight_days` filter bounds — when every case is out of bounds the list is empty). Each result has the following keys:
 
 | Key | Type | Unit / description |
 | --- | --- | --- |
 | `DepartureTime` / `ArrivalTime` | string | Departure/arrival time (UTC string) |
-| `DeltaV1` / `DeltaV2` | number[3] | Departure/arrival velocity-increment vector, m/s |
+| `DeltaV1` / `DeltaV2` | number[3] | Departure/arrival velocity-increment vector (departure/arrival hyperbolic excess velocity vector), m/s |
 | `DV1_Mag` / `DV2_Mag` | number | Departure/arrival velocity-increment magnitude, m/s; verified to be the Euclidean norm of the corresponding `DeltaV` vector |
 | `RV1` / `RV2` | number[6] | Position and velocity at departure/arrival (heliocentric) `[x, y, z, vx, vy, vz]`, positions m, velocities m/s |
+| `TimeOfFlightDays` | number | Time of flight, in d; verified to be the exact day difference between `ArrivalTime` and `DepartureTime` |
+| `ArrivalLightAngle` | number | Sun lighting angle at arrival, in deg; verified to be the angle between `DeltaV2` and the `RV2` position vector |
 
-Verified (supported by independent cross-validation): with `sun_frame="ICRF"`, the transfer velocities in `RV1`/`RV2` follow the zero-revolution prograde Lambert relationship, and the endpoint position directions use the ICRF axes. Unresolved: the exact coordinate relationship between `MeanEclpJ2000` and ICRF, the physical meaning of `DeltaV` relative to the endpoint-body velocities, and independent Kepler propagation of explicit MPC elements. These branches currently have only request-construction and response-structure evidence, so verify their meaning yourself before use.
+Verified (supported by independent cross-validation): omitting `sun_frame` produces exactly the same `TransferResults` as explicit `EclpJ2000ICRF`; `EclpJ2000ICRF` output is the `ICRF` output rotated by the fixed 23.43929111111111° J2000 mean obliquity; with `sun_frame="ICRF"`, the transfer velocities in `RV1`/`RV2` follow the zero-revolution prograde Lambert relationship, and the endpoint position directions use the ICRF axes; `max_departure_delta_v_m_s`/`max_arrival_delta_v_m_s`/`max_time_of_flight_days` filter the sampled grid by the `DV1_Mag`/`DV2_Mag`/time-of-flight upper bounds respectively. Note that since 2026-08-20 the server defaults (10000 m/s each for departure/arrival, 500 d) filter out cases beyond the defaults, so scans over large-ΔV windows need explicitly widened bounds. Unresolved: the exact coordinate relationship between explicit `MeanEclpJ2000` and ICRF, the physical meaning of `DeltaV` relative to the endpoint-body velocities, and independent Kepler propagation of explicit MPC elements (the `reference_frame` option does not change the arrival states of that route; the element convention is still unconfirmed). The numeric semantics of those branches remain unverified, so check them before use.
 
 ## Convention notes
 
@@ -269,6 +289,7 @@ Verified (supported by independent cross-validation): with `sun_frame="ICRF"`, t
 - Each `cartesianVelocity` sample is `[Time, X, Y, Z, dX, dY, dZ]`, with `Time` in seconds from the reference epoch, positions in m, and velocities in m/s.
 - `cb_axes_rotation` passes the integer `order` through as-is; the `Rotation` length corresponds to `order` (`0` → 4, `1` → 7).
 - `mpc_ephemeris` relies on the server's orbital-epoch default window when `start`/`stop` are omitted; an explicit fixed window may expire when the external MPC orbital epoch updates.
+- `mpc_ephemeris` `step_s` controls the output sampling grid; when omitted the server default is 86400 s, while `0` outputs at the internal integration steps.
 - The returns of all four functions on this page have the transport-level `IsSuccess` and `Message` removed, and the remaining server fields are preserved; errors are still raised by the HTTP layer (see error handling).
 - `lambert_transfer_window` combines `departure_start`/`departure_stop` and `arrival_start`/`arrival_stop` into the `"start/stop"` strings of `DepartureInterval`/`ArrivalInterval` respectively.
 - `mpc_orbital_elements` only performs the type checks required for lowering and does not perform physical-validity validation; fields that are not supplied do not appear in the `to_wire()` fragment.