astrox-python 0.1.0__tar.gz → 0.1.1__tar.gz

{astrox_python-0.1.0 → astrox_python-0.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: astrox-python
-Version: 0.1.0
+Version: 0.1.1
 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
@@ -28,55 +28,60 @@ Description-Content-Type: text/markdown
 
 # astrox-python
 
-Python SDK for the ASTROX Web API.
+astrox-python 是 ASTROX Web API 的 Python SDK。
 
-## Installation
+## 安装
+
+需要 Python 3.10 或更高版本。
 
 ```bash
 pip install astrox-python
 ```
 
-Requires Python 3.10 or later.
-
-## Quickstart
+## 一分钟示例
 
-Propagate a simple Keplerian orbit with J2 perturbations:
+用一组开普勒根数做 J2 传播：
 
 ```python
+import astrox
 from astrox import orbits, propagator
 
+astrox.configure(base_url="http://astrox.cn:8765")
+
 orbit = orbits.keplerian(
     semi_major_axis_m=6778137.0,
     eccentricity=0.001,
-    inclination_deg=28.5,
+    inclination_deg=51.6,
     argument_of_periapsis_deg=0.0,
-    raan_deg=0.0,
-    true_anomaly_deg=0.0,
+    raan_deg=120.0,
+    true_anomaly_deg=45.0,
 )
 
 period_s, position = propagator.j2(
-    start="2026-01-01T00:00:00Z",
-    stop="2026-01-01T01:00:00Z",
-    orbit_epoch="2026-01-01T00:00:00Z",
+    start="2024-01-01T00:00:00.000Z",
+    stop="2024-01-01T00:10:00.000Z",
+    orbit_epoch="2024-01-01T00:00:00.000Z",
     orbit=orbit,
 )
+
+print(f"轨道周期: {period_s:.3f} s")
+print(f"位置/速度采样数: {len(position.cartesian_velocity)}")
 ```
 
-## Documentation
+完整首次运行流程见 [快速上手](docs/getting_started.md)。
 
-- SDK guides and API notes: [`docs/sdk/`](./docs/sdk/)
-- Runnable examples: [`examples/`](./examples/)
+## 文档
 
-## Development
+- 完整文档导航：[docs/README.md](docs/README.md)
+- 可运行示例：[examples/](examples/)
+- 英文快照：[docs/i18n/en/README.md](docs/i18n/en/README.md)
 
-Install from a checkout:
+## 参与开发
 
-```bash
-uv sync --group dev
-uv build --no-build-isolation
-uv run python -m pytest -q tests/sdk
-```
+开发环境搭建与构建步骤见 [CONTRIBUTING.md](docs/CONTRIBUTING.md)。
+
+## 许可
 
-## License
+MIT 许可证，详见 [LICENSE](LICENSE)。
 
-MIT — see [LICENSE](./LICENSE).
+本项目目前处于 Alpha 阶段。

astrox_python-0.1.1/README.md

@@ -0,0 +1,59 @@
+# astrox-python
+
+astrox-python 是 ASTROX Web API 的 Python SDK。
+
+## 安装
+
+需要 Python 3.10 或更高版本。
+
+```bash
+pip install astrox-python
+```
+
+## 一分钟示例
+
+用一组开普勒根数做 J2 传播：
+
+```python
+import astrox
+from astrox import orbits, propagator
+
+astrox.configure(base_url="http://astrox.cn:8765")
+
+orbit = orbits.keplerian(
+    semi_major_axis_m=6778137.0,
+    eccentricity=0.001,
+    inclination_deg=51.6,
+    argument_of_periapsis_deg=0.0,
+    raan_deg=120.0,
+    true_anomaly_deg=45.0,
+)
+
+period_s, position = propagator.j2(
+    start="2024-01-01T00:00:00.000Z",
+    stop="2024-01-01T00:10:00.000Z",
+    orbit_epoch="2024-01-01T00:00:00.000Z",
+    orbit=orbit,
+)
+
+print(f"轨道周期: {period_s:.3f} s")
+print(f"位置/速度采样数: {len(position.cartesian_velocity)}")
+```
+
+完整首次运行流程见 [快速上手](docs/getting_started.md)。
+
+## 文档
+
+- 完整文档导航：[docs/README.md](docs/README.md)
+- 可运行示例：[examples/](examples/)
+- 英文快照：[docs/i18n/en/README.md](docs/i18n/en/README.md)
+
+## 参与开发
+
+开发环境搭建与构建步骤见 [CONTRIBUTING.md](docs/CONTRIBUTING.md)。
+
+## 许可
+
+MIT 许可证，详见 [LICENSE](LICENSE)。
+
+本项目目前处于 Alpha 阶段。

{astrox_python-0.1.0 → astrox_python-0.1.1}/astrox/components/__init__.py

@@ -36,11 +36,15 @@ from ._constraints import (
     AzElMaskConstraint,
     Constraint,
     ElevationConstraint,
+    MoonExclusionAngleConstraint,
     RangeConstraint,
+    SunExclusionAngleConstraint,
     _constraint_to_wire,
     az_el_mask_constraint,
     elevation_constraint,
+    moon_exclusion_angle_constraint,
     range_constraint,
+    sun_exclusion_angle_constraint,
 )
 from ._objects import Entity, EntityGroup, entity, entity_group
 from ._positions import (
@@ -141,6 +145,7 @@ __all__ = [
     "HpopPosition",
     "J2Position",
     "LvlhAxes",
+    "MoonExclusionAngleConstraint",
     "QuaternionRotation",
     "RangeConstraint",
     "RectangularSensor",
@@ -150,6 +155,7 @@ __all__ = [
     "Sgp4Position",
     "SitePosition",
     "SimpleAscentPosition",
+    "SunExclusionAngleConstraint",
     "TwoBodyPosition",
     "VgtAngle",
     "VgtDirection",
@@ -182,6 +188,7 @@ __all__ = [
     "hpop_position",
     "j2_position",
     "lvlh_axes",
+    "moon_exclusion_angle_constraint",
     "quaternion_rotation",
     "range_constraint",
     "ra_dec_direction",
@@ -198,5 +205,6 @@ __all__ = [
     "sgp4_position",
     "site_position",
     "simple_ascent_position",
+    "sun_exclusion_angle_constraint",
     "two_body_position",
 ]

{astrox_python-0.1.0 → astrox_python-0.1.1}/astrox/components/_constraints.py

@@ -65,10 +65,52 @@ class AzElMaskConstraint:
         return payload
 
 
-Constraint: TypeAlias = ElevationConstraint | RangeConstraint | AzElMaskConstraint
+@dataclass(frozen=True, kw_only=True)
+class SunExclusionAngleConstraint:
+    """Sun exclusion-angle constraint fragment shared by ASTROX entity and coverage inputs."""
+
+    minimum_deg: float | None = None
+    text: str | None = None
+
+    def to_wire(self) -> dict[str, Any]:
+        """Lower to an ASTROX Sun exclusion-angle constraint fragment."""
+        payload: dict[str, Any] = {"$type": "SunExclusionAngle"}
+        _include_if_supplied(payload, "MinimumValue", self.minimum_deg)
+        _include_if_supplied(payload, "Text", self.text)
+        return payload
+
+
+@dataclass(frozen=True, kw_only=True)
+class MoonExclusionAngleConstraint:
+    """Moon exclusion-angle constraint fragment shared by ASTROX entity and coverage inputs."""
+
+    minimum_deg: float | None = None
+    text: str | None = None
+
+    def to_wire(self) -> dict[str, Any]:
+        """Lower to an ASTROX Moon exclusion-angle constraint fragment."""
+        payload: dict[str, Any] = {"$type": "MoonExclusionAngle"}
+        _include_if_supplied(payload, "MinimumValue", self.minimum_deg)
+        _include_if_supplied(payload, "Text", self.text)
+        return payload
 
 
-_CONSTRAINT_TYPES = (ElevationConstraint, RangeConstraint, AzElMaskConstraint)
+Constraint: TypeAlias = (
+    ElevationConstraint
+    | RangeConstraint
+    | AzElMaskConstraint
+    | SunExclusionAngleConstraint
+    | MoonExclusionAngleConstraint
+)
+
+
+_CONSTRAINT_TYPES = (
+    ElevationConstraint,
+    RangeConstraint,
+    AzElMaskConstraint,
+    SunExclusionAngleConstraint,
+    MoonExclusionAngleConstraint,
+)
 
 
 def elevation_constraint(
@@ -132,6 +174,24 @@ def az_el_mask_constraint(
     )
 
 
+def sun_exclusion_angle_constraint(
+    *,
+    minimum_deg: float | None = None,
+    text: str | None = None,
+) -> SunExclusionAngleConstraint:
+    """Create a Sun exclusion-angle constraint fragment."""
+    return SunExclusionAngleConstraint(minimum_deg=minimum_deg, text=text)
+
+
+def moon_exclusion_angle_constraint(
+    *,
+    minimum_deg: float | None = None,
+    text: str | None = None,
+) -> MoonExclusionAngleConstraint:
+    """Create a Moon exclusion-angle constraint fragment."""
+    return MoonExclusionAngleConstraint(minimum_deg=minimum_deg, text=text)
+
+
 def _constraint_to_wire(constraint: Constraint) -> dict[str, Any]:
     if not isinstance(constraint, _CONSTRAINT_TYPES):
         raise TypeError("constraint must be an astrox.components constraint value")

{astrox_python-0.1.0 → astrox_python-0.1.1}/astrox/coverage/_core.py

@@ -9,6 +9,7 @@ from typing import Any, TypeAlias
 
 from astrox import components
 from astrox._http import raw
+from astrox.components._constraints import _CONSTRAINT_TYPES
 
 __all__ = [
     "CbLatLonGrid",
@@ -203,11 +204,6 @@ class CbLatLonGrid:
 CoverageGrid: TypeAlias = GlobalGrid | LatitudeGrid | LatLonGrid | CbLatLonGrid
 _GRID_TYPES = (GlobalGrid, LatitudeGrid, LatLonGrid, CbLatLonGrid)
 _SENSOR_TYPES = (components.ConicSensor, components.RectangularSensor)
-_CONSTRAINT_TYPES = (
-    components.ElevationConstraint,
-    components.RangeConstraint,
-    components.AzElMaskConstraint,
-)
 
 
 def global_grid(

astrox_python-0.1.1/docs/CONTRIBUTING.md

@@ -0,0 +1,9 @@
+# 参与开发
+
+从本仓库检出后，安装开发依赖并运行测试：
+
+```bash
+uv sync --group dev
+uv build --no-build-isolation
+uv run python -m pytest -q tests/sdk
+```

astrox_python-0.1.1/docs/README.md

@@ -0,0 +1,10 @@
+# ASTROX Python SDK 文档
+
+本文档树按四层组织，每层面向不同的阅读目标：
+
+- [快速上手](getting_started.md)：面向第一次使用的用户。提供一条完整的可运行脚本，安装、配置、构造开普勒根数、调用传播器并查看结果，五分钟内看到输出。
+- [How-To 指南](how_to/README.md)：面向任务导向的用户。每篇围绕一个具体问题给出最简可用代码，说明需要做的关键选择，并指向手册和验证页获取细节与证据。
+- [手册](manual/README.md)：面向希望了解完整约定的用户。按领域组织，先讲概念，再给出 API 参考、参数/单位、返回约定与最简示例。
+- [验证](validation/README.md)（英文）：面向维护者和高级用户。记录各领域的验证状态、比较路径、容差与已知残差，链接到 `tests/validation/` 下的脚本。
+
+各层互不替代；正常使用时无需逐层通读。

astrox_python-0.1.1/docs/docs-principles.md

@@ -0,0 +1,102 @@
+# ASTROX Documentation Principles
+
+User-facing documentation is the primary interface for the ASTROX Python SDK. It must be user-facing without internal jargons. It must be honest about what is verified, clear about what is convention, and never claim what tests do not prove.
+
+## Documentation Layers
+
+The documentation tree has four layers with non-overlapping jobs.
+
+| Layer | Location | Audience | Content | Language |
+|-------|----------|----------|---------|----------|
+| Getting Started | `docs/getting_started.md` | First-time user | One runnable end-to-end example. Install, configure, propagate an orbit, print a position. | Chinese |
+| How-To | `docs/how_to/*.md` | Task-oriented user | Cross-domain task guides. Each solves one specific problem completely. | Chinese |
+| Manual | `docs/manual/<domain>/*.md` | User who wants the full story | Per-function comprehensive walkthrough grouped by domains. Concepts → API reference → algorithms (only if verified). | Chinese |
+| Validation | `docs/validation/*.md` | Maintainer, advanced user | What is verified, against what, known residuals, coverage status. | English |
+
+No layer may substitute for another. A user should be able to follow Getting Started without reading Manual, and a maintainer should be able to read Validation without reading How-To.
+
+## Content Boundaries
+
+### Getting Started
+
+- One complete runnable script.
+- No optional arguments, no branches, no caveats.
+- Goal: a new user runs this in five minutes and sees output.
+
+### How-To
+
+- States the goal in the title.
+- Shows minimal working code.
+- Explains the one or two decisions the user must make.
+- Links to Manual for background and Validation for evidence.
+- Does not discuss calibration residuals, frame conventions, or investigation narratives.
+
+### Manual
+
+- Concepts: what this domain is, when to use it, how it relates to other domains.
+- API reference: function signatures, argument tables, return types, minimal examples.
+- Algorithms: underlying math or physics only when cross-validation has verified the behavior. Unverified algorithms are marked `unverified` or omitted.
+- Convention notes: one-sentence neutral statements about ASTROX conventions (frame interpretations, advance rules, coordinate definitions).
+- Does not contain investigation narratives, residual discussions, or calibration history.
+
+### Validation
+
+- Cross-validation results per branch.
+- Known residuals with explanations.
+- Frame and convention discoveries from calibration.
+- Coverage status and comparison paths.
+- Links to relevant cross-validation scripts in `tests/validation/cross_validation/`.
+- Does not contain usage examples or API signatures.
+
+## Convention vs. Investigation
+
+Content inherited from the former `docs/sdk/*.md` pages was split according to this rule; apply the same rule to any new material:
+
+- **Convention statements** stay in Manual as neutral one-sentence asides. Example: "For SGP4 results, `position.reference_frame == 'INERTIAL'` corresponds to GCRF/GCRS-style inertial coordinates."
+- **Investigation narratives** move to Validation. Example: "Cross-validation against Skyfield confirms the sign and units for representative cases. An arcsecond-scale residual remains visible after frame and light-time diagnostics."
+
+If a sentence describes what ASTROX does, it is a convention. If a sentence describes how we discovered it or what remains unexplained, it is an investigation narrative.
+
+## Evidence Honesty
+
+Documentation must not claim what tests do not prove.
+
+- If a branch is `verified` in the coverage checklist, the Manual may describe its behavior as documented.
+- If a branch is `partial`, `unresolved`, or `unverifiable`, the Manual must mark it as such or omit the claim.
+- The Manual must not say "correct" or "accurate" unless cross-validation has established a comparison path. Say "ASTROX returns" or "the result is" instead.
+- How-To guides may use verified branches as recommended paths. Unverified branches should not appear in How-To unless clearly marked.
+
+## Voice and Tone
+
+- **Getting Started:** Encouraging, imperative, minimal. Assume the user knows Python but not astrodynamics.
+- **How-To:** Direct, task-oriented. "Do X to achieve Y."
+- **Manual:** Precise, informative. Explain concepts before showing code. Use explicit unit suffixes (`_m`, `_deg`, `_s`) matching the public API.
+- **Validation:** Evidence-backed, cautious. State tolerances, comparison paths, and model assumptions explicitly. Never say "proven"; say "cross-validated against X within tolerance Y."
+
+## Relationship to Examples
+
+Examples under `examples/` are runnable artifacts. Docs explain and link to them. Getting Started may inline one short example. How-To and Manual link to relevant examples. Examples must not contain validation narratives or calibration notes.
+
+## Chinese-First Policy
+
+All user-facing documentation (Getting Started, How-To, Manual) is written in Chinese. English translation is optional and lives in `docs/i18n/en/`.
+
+English is preserved for:
+- Validation documentation
+- Architecture and principle documents (`docs-principles.md`, `sdk-principles.md`, `test-principles.md`, `automated-workflows.md`, `AGENTS.md`)
+- Code comments, tests, and validation scripts
+- `README.md` is Chinese-first with a link to the English version
+
+## i18n
+
+When an English original is preserved in `docs/i18n/en/`, it should be a faithful snapshot of the Chinese source at the time of writing. Do not expand or reduce claims during translation.
+
+## Anti-Patterns
+
+- Do not mix validation notes into API reference.
+- Do not write "see above" or "as discussed earlier" in Manual pages. Each section should be readable independently.
+- Do not use defensive language like "may return" or "might be" when the behavior is verified. Say what ASTROX does.
+- Do not use absolute language like "correct" or "accurate" when the behavior is unverified.
+- Do not hard-wrap Markdown prose. Preserve unwrapped paragraphs.
+- Do not introduce internal jargons when it's a user-facing material.
+- Do not write Chinese that looks like a machine translation.

astrox_python-0.1.1/docs/getting_started.md

@@ -0,0 +1,71 @@
+# 快速上手
+
+本页帮助你在五分钟内完成第一次轨道传播：安装 SDK、配置 ASTROX 服务地址、构造一组开普勒根数、调用 J2 传播器，并查看返回的位置。
+
+## 安装
+
+使用 Python 3.10 或更高版本：
+
+```bash
+pip install astrox-python
+```
+
+## 编写脚本
+
+将以下代码保存为 `first_orbit.py`：
+
+```python
+import astrox
+from astrox import orbits, propagator
+
+# 配置 ASTROX 服务地址
+astrox.configure(base_url="http://astrox.cn:8765")
+
+# 构造一组开普勒根数：400 km 近圆轨道，51.6° 倾角
+orbit = orbits.keplerian(
+    semi_major_axis_m=6778137.0,
+    eccentricity=0.001,
+    inclination_deg=51.6,
+    argument_of_periapsis_deg=0.0,
+    raan_deg=120.0,
+    true_anomaly_deg=45.0,
+)
+
+# 使用 J2 模型传播 10 分钟
+period_s, position = propagator.j2(
+    start="2024-01-01T00:00:00.000Z",
+    stop="2024-01-01T00:10:00.000Z",
+    orbit_epoch="2024-01-01T00:00:00.000Z",
+    orbit=orbit,
+)
+
+print(f"轨道周期: {period_s:.3f} s")
+print(f"历元: {position.epoch}")
+print(f"中心天体: {position.central_body}")
+print(f"参考系: {position.reference_frame}")
+print(f"位置/速度采样数: {len(position.cartesian_velocity)}")
+```
+
+## 运行
+
+```bash
+python first_orbit.py
+```
+
+你会看到类似下面的输出：
+
+```text
+轨道周期: 5553.624 s
+历元: 2024-01-01T00:00:00.000Z
+中心天体: Earth
+参考系: INERTIAL
+位置/速度采样数: 77
+```
+
+## 刚才发生了什么
+
+`orbits.keplerian` 用六个开普勒根数描述了一个轨道：半长轴 `semi_major_axis_m`、偏心率 `eccentricity`、倾角 `inclination_deg`、近地点幅角 `argument_of_periapsis_deg`、升交点赤经 `raan_deg` 和真近点角 `true_anomaly_deg`。`propagator.j2` 把这组根数从给定历元向前传播，返回轨道周期 `period_s` 和一个包含笛卡尔位置/速度采样的 `position` 对象。
+
+## 下一步
+
+了解更多任务导向的用法，请参阅 [How-To 指南](how_to/README.md)。

astrox_python-0.1.1/docs/how_to/README.md

@@ -0,0 +1,11 @@
+# How-To 指南
+
+面向任务的操作指南，每篇解决一个具体问题。
+
+- [如何传播一条轨道](propagate_an_orbit.md)：根据手头的轨道描述（开普勒根数、TLE 或力模型配置）选择传播器并读取采样结果。
+- [在不同轨道表示之间转换](convert_between_orbit_representations.md)：开普勒根数、笛卡尔状态与 Kozai-Izsak 平均根数之间的相互转换。
+- [搭建 HPOP 力模型配置](build_an_hpop_configuration.md)：用 `hpop_config` 系列构造器组装积分器、重力场、大气、太阳辐射压与第三方天体摄动。
+- [计算光照条件](compute_lighting_conditions.md)：光照/半影/本影区间、太阳辐射强度与太阳 AER 采样。
+- [计算地面站与卫星之间的访问区间](compute_access_intervals.md)：直接访问计算、AER 输出与仰角约束。
+
+每篇指南的完整参数说明见对应的[手册](../manual/README.md)条目，验证证据见[验证文档](../validation/README.md)。

astrox_python-0.1.1/docs/how_to/build_an_hpop_configuration.md

@@ -0,0 +1,148 @@
+# 搭建 HPOP 力模型配置
+
+本页解决一个具体任务：用 `propagator.hpop_config(...)` 系列构造器搭一套 HPOP 力模型配置，并用它运行一次高精度轨道传播。
+
+## 要做的两个选择
+
+1. **为任务选择力模型分量**：HPOP 配置由积分器、重力场、大气、太阳辐射压、第三方天体摄动等可选分量叠加而成。简单任务可以只用二体重力；需要更高精度时，再逐层加入重力场阶次、大气阻力、太阳辐射压和日月第三方天体摄动。
+2. **选择坐标系**：`coord_system` 决定输出位置的参考系。`"Inertial"` 对应惯性参考系输出，`"Fixed"` 对应地固参考系输出；与 J2/二体传播一样，默认由服务器决定，但建议在调用中显式指定。
+
+## 完整示例
+
+下面的脚本构造一个包含全部可选分量的 HPOP 力模型配置，并用开普勒根数运行一次 10 分钟传播。将代码保存为 `build_an_hpop_configuration.py`：
+
+```python
+import astrox
+from astrox import orbits, propagator
+
+astrox.configure(base_url="http://astrox.cn:8765")
+
+orbit = orbits.keplerian(
+    semi_major_axis_m=6778137.0,
+    eccentricity=0.001,
+    inclination_deg=28.5,
+    argument_of_periapsis_deg=0.0,
+    raan_deg=0.0,
+    true_anomaly_deg=0.0,
+)
+
+config = propagator.hpop_config(
+    central_body="Earth",
+    integrator=propagator.hpop_rkf78(
+        use_fixed_step=True,
+        initial_step_s=60.0,
+        max_step_s=60.0,
+        min_step_s=0.001,
+        max_abs_error=1e-10,
+        max_rel_error=1e-12,
+        max_iterations=50,
+    ),
+    gravity=propagator.hpop_gravity_field(
+        gravity_file_name="EGM2008.grv",
+        degree=4,
+        order=4,
+        use_secular_variations=False,
+        solid_tide_type="Permanent tide only",
+        eop_file_path="EOP-v1.1.txt",
+    ),
+    atmosphere=propagator.hpop_jacchia_roberts(
+        drag_model_type="Spherical",
+        atmos_data_source="Constant Values",
+        f10p7=150.0,
+        f10p7_avg=150.0,
+        kp=3.0,
+    ),
+    srp=propagator.hpop_srp_spherical(
+        shadow_model="DualCone",
+        sun_position="Apparent",
+        eclipsing_bodies=["Earth", "Moon"],
+    ),
+    third_bodies=[
+        propagator.hpop_third_body(
+            "Sun",
+            mode_type="PointMass",
+            ephem_source="DeFile",
+            grav_source="DeFile",
+            mu_m3_s2=1.3271244004193938e20,
+        ),
+        propagator.hpop_third_body("Moon"),
+    ],
+)
+
+period_s, position = propagator.hpop(
+    start="2024-01-01T00:00:00.000Z",
+    stop="2024-01-01T00:10:00.000Z",
+    orbit_epoch="2024-01-01T00:00:00.000Z",
+    orbit=orbit,
+    coord_system="Inertial",
+    gravitational_parameter_m3_s2=398600441500000.0,
+    coefficient_of_drag=2.2,
+    area_mass_ratio_drag_m2_kg=0.01,
+    coefficient_of_srp=1.3,
+    area_mass_ratio_srp_m2_kg=0.02,
+    config=config,
+)
+
+samples = position.cartesian_velocity
+print(f"轨道周期: {period_s:.3f} s")
+print(f"中心天体: {position.central_body}")
+print(f"参考系: {position.reference_frame}")
+print(f"采样点数: {len(samples) // 7}")
+t = samples[0]
+x, y, z, vx, vy, vz = samples[1:7]
+print(f"首个采样 t={t:.3f} s")
+print(f"位置 (m): x={x:.3f}, y={y:.3f}, z={z:.3f}")
+print(f"速度 (m/s): vx={vx:.6f}, vy={vy:.6f}, vz={vz:.6f}")
+```
+
+## 运行
+
+```bash
+python build_an_hpop_configuration.py
+```
+
+## 实际输出
+
+```text
+轨道周期: 6000.000 s
+中心天体: Earth
+参考系: INERTIAL
+采样点数: 11
+首个采样 t=0.000 s
+位置 (m): x=6771358.863, y=0.000, z=0.000
+速度 (m/s): vx=0.000000, vy=6746.002785, vz=3662.780662
+```
+
+## 刚才发生了什么
+
+上面的示例把所有可选分量都启用了一次，方便你看懂组装方式；实际任务中应根据精度需求裁剪，各分支的验证范围见 [传播器验证](../validation/propagator.md)。
+
+`propagator.hpop_config(...)` 把多个力模型分量组装成一个 `HpopConfig` 对象。每个分量都有对应的构造器：
+
+- `hpop_rkf78`：配置 RKF7(8) 数值积分器，可指定固定步长、误差容限和最大迭代次数。
+- `hpop_two_body_gravity`：只使用中心天体二体引力。
+- `hpop_gravity_field`：使用重力场文件，可指定阶次、潮汐模型和地球定向参数文件。
+- `hpop_jacchia_roberts`：配置 Jacchia-Roberts 大气模型，用于大气阻力计算。
+- `hpop_srp_spherical`：配置球形太阳辐射压模型，可指定阴影模型（`shadow_model`）、太阳位置和遮挡天体。
+- `hpop_third_body`：为指定天体（如 Sun、Moon）开启第三方天体摄动。
+
+`propagator.hpop(...)` 把这些配置发往 ASTROX，返回 `(period_s, position)`。`position.cartesian_velocity` 是 CZML 风格的 `[t, x, y, z, vx, vy, vz, ...]` 扁平序列，每 7 个数一帧，单位分别为秒、米、米/秒。与 `propagator.j2` 不同，HPOP 不暴露 `step_s` 参数，采样由积分器和服务器内部控制。
+
+## 简化版：只配二体重力
+
+如果任务暂时不需要重力场文件，最小配置可以简化为：
+
+```python
+config = propagator.hpop_config(
+    central_body="Earth",
+    gravity=propagator.hpop_two_body_gravity(),
+)
+```
+
+此时 `hpop` 等价于用 HPOP 数值积分器传播二体问题，适合先验证接口再逐步加入摄动模型。
+
+## 了解更多
+
+- 各构造器的完整参数、单位与返回值说明请参阅 [传播器手册](../manual/propagator/README.md)。
+- HPOP 各分支的验证状态、GMAT 交叉验证证据与已知残差请参阅 [传播器验证](../validation/propagator.md)。
+- 更多可运行示例见 `examples/01_propagation/hpop.py`。