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

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

@@ -14,6 +14,7 @@ wheels/
 # Internal & intermediate docs
 *.md
 !README.md
+!AGENTS.md
 !docs/**/*.md
 docs/MAINTAINER_QUESTIONS.md
 !openapi/**/*.md

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

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

{astrox_python-1.0.0 → astrox_python-1.1.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,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"),
     }
@@ -351,6 +395,11 @@ def mpc_ephemeris(
         "Stop",
         _optional_string(stop, parameter="stop"),
     )
+    _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.1.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.1.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.1.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.1.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.1.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.1.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.1.0}/docs/i18n/en/manual/celestial/README.md

@@ -113,19 +113,23 @@ celestial.mpc_ephemeris(
     observer_frame: str | None = None,
     start: str | None = None,
     stop: str | 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` |
+| `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), 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.
+This route fetches orbital elements from the external MPC data source (element epoch in MJD TDT), which the server propagates heliocentrically with a fixed 3-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`, `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.
+
+Verified (endpoint-internal invariant): passing the `OrbitElements` returned by a name query back as `target_elements` reproduces the name-query ephemeris exactly; the `reference_frame` values `EclpJ2000ICRF` (MPC convention, server default) and `MeanEclpJ2000` (JPL convention) are two distinguishable branches. See the [celestial validation page](../../../../validation/celestial.md) for the evidence.
 
 ```python
 mpc = celestial.mpc_ephemeris(target_name="Ceres")
@@ -149,6 +153,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 +170,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 +190,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 +211,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 |
 | --- | --- | --- |
@@ -224,6 +233,9 @@ Samples over the departure time window and the arrival time window, computes Lam
 | `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 +253,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 +263,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): 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 `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). These branches currently have only request-construction and response-structure evidence, so verify their meaning yourself before use.
 
 ## Convention notes
 

{astrox_python-1.0.0 → astrox_python-1.1.0}/docs/i18n/en/manual/orbits/README.md

@@ -346,10 +346,12 @@ orbits.lambert_delta_v(
     arrival_state: CartesianState,
     time_of_flight_s: float,
     gravitational_parameter_m3_s2: float | None = None,
-) -> tuple[tuple[float, float, float], tuple[float, float, float]]
+    get_path_points: bool = False,
+    path_point_count: int | None = None,
+) -> tuple[tuple[float, float, float], tuple[float, float, float]] | LambertResult
 ```
 
-Solves a single-revolution Lambert transfer between two Cartesian states, returning `(departure_delta_v_m_s, arrival_delta_v_m_s)`. Each delta-v is an `(x, y, z)` tuple in m/s.
+Solves a single-revolution Lambert transfer between two Cartesian states. By default it returns `(departure_delta_v_m_s, arrival_delta_v_m_s)`; each delta-v is an `(x, y, z)` tuple in m/s. With `get_path_points=True` it returns `orbits.LambertResult`, which additionally carries `positions`: transfer-trajectory position samples as a flat `(x, y, z, ...)` sequence in m, including both endpoints, with `path_point_count` points (server default 100).
 
 | Parameter | Unit | Description |
 | --- | --- | --- |
@@ -357,6 +359,8 @@ Solves a single-revolution Lambert transfer between two Cartesian states, return
 | `arrival_state` | — | Cartesian state at arrival |
 | `time_of_flight_s` | s | Time of flight |
 | `gravitational_parameter_m3_s2` | m³/s² | Gravitational parameter |
+| `get_path_points` | — | Whether to return transfer-trajectory position samples; single-case requests only |
+| `path_point_count` | — | Number of position samples (including both endpoints); server default 100, only sent when `get_path_points=True` |
 
 ```python
 departure_delta_v_m_s, arrival_delta_v_m_s = orbits.lambert_delta_v(
@@ -365,8 +369,20 @@ departure_delta_v_m_s, arrival_delta_v_m_s = orbits.lambert_delta_v(
     time_of_flight_s=817.4257,
     gravitational_parameter_m3_s2=398600441500000.0,
 )
+
+result = orbits.lambert_delta_v(
+    departure_state=departure_state,
+    arrival_state=arrival_state,
+    time_of_flight_s=817.4257,
+    gravitational_parameter_m3_s2=398600441500000.0,
+    get_path_points=True,
+    path_point_count=5,
+)
+print(result.positions)  # flat (x, y, z, ...) sequence of 5 samples
 ```
 
+The position samples are cross-validated: the first and last samples reproduce the position triples of the input `RV1`/`RV2`, and intermediate samples lie on the two-body transfer trajectory started from the departure state plus the returned delta-v (consistent with independent Brahe propagation). See the [orbits validation page](../../../../validation/orbits.md) for the evidence.
+
 ### `orbits.geo_ym_lambert_delta_v`
 
 ```python

{astrox_python-1.0.0 → astrox_python-1.1.0}/docs/i18n/en/manual/propagator/README.md

@@ -27,7 +27,7 @@ For details on orbit constructors, see the [orbits manual](../orbits/README.md).
 
 ## Return Values
 
-Single-orbit propagation functions return a `(period_s, position)` tuple:
+Except for `propagator.two_body_rv`, single-orbit propagation functions return a `(period_s, position)` tuple (`two_body_rv` returns a flat ephemeris sequence; see its section below):
 
 - `period_s`: `float`, the orbital period returned by ASTROX, in seconds.
 - `position`: `propagator.PropagatorPosition` frozen dataclass with the following fields:
@@ -126,6 +126,45 @@ period_s, position = propagator.two_body(
 
 A complete runnable example is available at `examples/01_propagation/two_body_classical.py`.
 
+### `propagator.two_body_rv`
+
+```python
+propagator.two_body_rv(
+    *,
+    state: CartesianState,
+    time_of_flight_s: float,
+    gravitational_parameter_m3_s2: float | None = None,
+    step_s: float | None = None,
+) -> tuple[float, ...]
+```
+
+Propagates directly from an initial position/velocity state using the two-body model (`/Propagator/TwoBodyRV`, simplified RV integrator), returning a flat ephemeris sequence `[t, x, y, z, vx, vy, vz, ...]`: `t` is seconds relative to the initial epoch, positions are in m and velocities in m/s. The sequence includes the start and end samples, with intermediate samples spaced by `step_s`.
+
+| Parameter | Wire parameter | Unit | Description |
+| --- | --- | --- | --- |
+| `state` | `RV0` | m, m/s | Initial Cartesian state (built with `orbits.cartesian_state`) |
+| `time_of_flight_s` | `TimeOfFlight` | s | Time of flight |
+| `gravitational_parameter_m3_s2` | `Gm` | m³/s² | Central-body gravitational constant; server default 3.986004415E14 (Earth) |
+| `step_s` | `Step` | s | Output step; server default 60 |
+
+This route is a fixed-step numerical two-body integrator, unlike the analytic Kepler route of `propagator.two_body`: cross-validation against independent Brahe two-body propagation shows its residual oscillates with orbital phase, peaking at about 4e-4 m and 5.4e-7 m/s over a 10-minute arc, without secular growth. See the [propagator validation page](../../../../validation/propagator.md) for the evidence.
+
+```python
+state = orbits.cartesian_state(
+    x_m=7000000.0, y_m=0.0, z_m=0.0,
+    vx_m_s=0.0, vy_m_s=7546.053290114564, vz_m_s=0.0,
+)
+
+positions = propagator.two_body_rv(
+    state=state,
+    time_of_flight_s=3600.0,
+    step_s=600.0,
+    gravitational_parameter_m3_s2=398600441500000.0,
+)
+```
+
+A complete runnable example is available at `examples/01_propagation/two_body_rv.py`.
+
 ## Batch Propagation
 
 Batch propagation brings multiple states or TLEs to a common target epoch `epoch`.