vbar 0.0.1__tar.gz

vbar-0.0.1/.github/workflows/ci.yml

@@ -0,0 +1,18 @@
+name: tests
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python: ["3.10", "3.12"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - run: pip install -e ".[dev]"
+      - run: pytest -q

vbar-0.0.1/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+.pytest_cache/
+*.egg-info/
+dist/
+build/
+.venv/
+outputs/

vbar-0.0.1/CITATION.cff

@@ -0,0 +1,8 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+title: "V-BAR: Verified Benchmark for Autonomous Rendezvous"
+authors:
+  - family-names: Hammoudeh
+    given-names: Jamil
+version: 0.0.1
+license: MIT

vbar-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jamil Hammoudeh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

vbar-0.0.1/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.5
+Name: vbar
+Version: 0.0.1
+Summary: A fast, headless, cross-platform benchmark for testing AI and classical spacecraft controllers, with safety filters.
+Project-URL: Homepage, https://github.com/jamilhammoudeh/vbar
+Project-URL: Repository, https://github.com/jamilhammoudeh/vbar
+Project-URL: Issues, https://github.com/jamilhammoudeh/vbar/issues
+Author-email: Jamil Hammoudeh <j.hammoudeh@outlook.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: benchmark,clohessy-wiltshire,guidance navigation and control,orbital mechanics,proximity operations,reinforcement learning,rendezvous,safety filter,spacecraft
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.10
+Requires-Dist: gymnasium>=0.29
+Requires-Dist: numpy>=1.24
+Requires-Dist: scipy>=1.10
+Provides-Extra: dev
+Requires-Dist: matplotlib>=3.7; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Provides-Extra: plot
+Requires-Dist: matplotlib>=3.7; extra == 'plot'
+Description-Content-Type: text/markdown
+
+# V-BAR: Verified Benchmark for Autonomous Rendezvous
+
+`vbar` is a fast, headless, cross-platform benchmark for testing AI and classical spacecraft controllers, with and without safety filters.
+
+> **Status: v0 (early development).** One scenario, validated close-range dynamics, classical and LLM agent interfaces.
+
+## Why
+
+Testing AI controllers for spacecraft rendezvous today usually means running a full game engine (KSPDG, built on Kerbal Space Program): a paid game, GUI-only, macOS/Linux, real-time. That makes large, statistically meaningful experiments slow. V-BAR runs anywhere Python runs, with no game, and simulates an hour of flight in a fraction of a second.
+
+Goals:
+
+- **Fair comparisons:** the same scenarios, metrics, and number of runs for every controller: classical, reinforcement learning, or LLM.
+- **Safety as a first-class metric:** keep-out violations are checked continuously (including between time steps), and safety filters can be switched on and off.
+- **Reproducible:** seeds, logged prompts and replies, and validated physics.
+
+## Install
+
+```bash
+pip install -e ".[dev]"   # from a clone of this repo
+```
+
+## Quickstart
+
+```python
+from vbar import ApproachConfig, ApproachEnv, run_episode
+from vbar.agents import PDAgent
+
+env = ApproachEnv(ApproachConfig(start_state=(0, 400, 0, 0, 0, 0)))
+result = run_episode(env, PDAgent())
+print(result["captured"], result["keep_out_violated"], result["dv_used_mps"])
+```
+
+Run the demo (saves a trajectory plot to `outputs/`):
+
+```bash
+python examples/v0_demo.py
+```
+
+### Plug in any LLM
+
+```python
+from vbar.agents import LLMAgent
+
+def complete(prompt: str) -> str:
+    ...  # call any model and return its text reply
+
+agent = LLMAgent(complete, name="my-model")
+result = run_episode(env, agent)
+agent.log  # every prompt, reply, parsed action, parse failure, latency
+```
+
+## Scenario: approach to hold point
+
+The chaser must reach a hold point 100 m behind the target on the V-bar and stop, without entering a 50 m keep-out sphere around the target.
+
+**Dynamics:** Clohessy-Wiltshire relative motion (circular target orbit at 500 km, close range, no perturbations). Integrated numerically (DOP853) and **validated against the exact closed-form solution** to sub-millimeter accuracy over a full orbit (`tests/test_cw.py`).
+
+**Metrics (in `info` and the result dict):** capture, keep-out violation (checked between steps), minimum range to target, delta-v used, time, filter interventions.
+
+## Validation
+
+```bash
+pytest -q
+```
+
+Tests check the dynamics against known exact results: the closed-form solution, V-bar equilibrium, closed relative ellipses, and the 12π·|x0| along-track drift per orbit.
+
+## Citation
+
+See [CITATION.cff](CITATION.cff).
+
+## License
+
+MIT

vbar-0.0.1/README.md

@@ -0,0 +1,75 @@
+# V-BAR: Verified Benchmark for Autonomous Rendezvous
+
+`vbar` is a fast, headless, cross-platform benchmark for testing AI and classical spacecraft controllers, with and without safety filters.
+
+> **Status: v0 (early development).** One scenario, validated close-range dynamics, classical and LLM agent interfaces.
+
+## Why
+
+Testing AI controllers for spacecraft rendezvous today usually means running a full game engine (KSPDG, built on Kerbal Space Program): a paid game, GUI-only, macOS/Linux, real-time. That makes large, statistically meaningful experiments slow. V-BAR runs anywhere Python runs, with no game, and simulates an hour of flight in a fraction of a second.
+
+Goals:
+
+- **Fair comparisons:** the same scenarios, metrics, and number of runs for every controller: classical, reinforcement learning, or LLM.
+- **Safety as a first-class metric:** keep-out violations are checked continuously (including between time steps), and safety filters can be switched on and off.
+- **Reproducible:** seeds, logged prompts and replies, and validated physics.
+
+## Install
+
+```bash
+pip install -e ".[dev]"   # from a clone of this repo
+```
+
+## Quickstart
+
+```python
+from vbar import ApproachConfig, ApproachEnv, run_episode
+from vbar.agents import PDAgent
+
+env = ApproachEnv(ApproachConfig(start_state=(0, 400, 0, 0, 0, 0)))
+result = run_episode(env, PDAgent())
+print(result["captured"], result["keep_out_violated"], result["dv_used_mps"])
+```
+
+Run the demo (saves a trajectory plot to `outputs/`):
+
+```bash
+python examples/v0_demo.py
+```
+
+### Plug in any LLM
+
+```python
+from vbar.agents import LLMAgent
+
+def complete(prompt: str) -> str:
+    ...  # call any model and return its text reply
+
+agent = LLMAgent(complete, name="my-model")
+result = run_episode(env, agent)
+agent.log  # every prompt, reply, parsed action, parse failure, latency
+```
+
+## Scenario: approach to hold point
+
+The chaser must reach a hold point 100 m behind the target on the V-bar and stop, without entering a 50 m keep-out sphere around the target.
+
+**Dynamics:** Clohessy-Wiltshire relative motion (circular target orbit at 500 km, close range, no perturbations). Integrated numerically (DOP853) and **validated against the exact closed-form solution** to sub-millimeter accuracy over a full orbit (`tests/test_cw.py`).
+
+**Metrics (in `info` and the result dict):** capture, keep-out violation (checked between steps), minimum range to target, delta-v used, time, filter interventions.
+
+## Validation
+
+```bash
+pytest -q
+```
+
+Tests check the dynamics against known exact results: the closed-form solution, V-bar equilibrium, closed relative ellipses, and the 12π·|x0| along-track drift per orbit.
+
+## Citation
+
+See [CITATION.cff](CITATION.cff).
+
+## License
+
+MIT

vbar-0.0.1/examples/v0_demo.py

@@ -0,0 +1,60 @@
+"""v0 demo: why spacecraft controllers need safety filters.
+
+Runs the classical PD baseline from two starting points:
+  1. A clear path: it reaches the hold point safely.
+  2. The target is in the way: it flies straight through the keep-out zone.
+
+Then runs 30 random starts and reports the violation rate.
+Saves a plot to outputs/v0_trajectories.png.
+"""
+
+from pathlib import Path
+
+import matplotlib
+
+matplotlib.use("Agg")
+import matplotlib.pyplot as plt
+import numpy as np
+
+from vbar import ApproachConfig, ApproachEnv, run_episode, run_many
+from vbar.agents import DriftAgent, PDAgent
+from vbar.viz import plot_trajectories
+
+out = Path("outputs")
+out.mkdir(exist_ok=True)
+
+clear = ApproachEnv(ApproachConfig(start_state=(-150, -400, 0, 0, 0, 0)))
+blocked = ApproachEnv(ApproachConfig(start_state=(0, 400, 0, 0, 0, 0)))
+
+r_clear = run_episode(clear, PDAgent())
+r_blocked = run_episode(blocked, PDAgent())
+r_drift = run_episode(blocked, DriftAgent())
+
+for name, r in [("clear path", r_clear), ("target in the way", r_blocked), ("drift", r_drift)]:
+    print(
+        f"{name:18s} captured={r['captured']!s:5s} violated={r['keep_out_violated']!s:5s} "
+        f"min_range={r['min_range_to_target_m']:7.1f} m  dv={r['dv_used_mps']:.2f} m/s  "
+        f"sim={r['time_s']:.0f} s in {r['wall_time_s']*1000:.0f} ms"
+    )
+
+# Batch run: random starts ahead of the target (the hard case).
+env = ApproachEnv()
+results = run_many(env, PDAgent(), seeds=range(30))
+viol = np.mean([r["keep_out_violated"] for r in results])
+cap = np.mean([r["captured"] for r in results])
+dv = np.median([r["dv_used_mps"] for r in results])
+print(f"\n30 random starts: capture rate {cap:.0%}, keep-out violation rate {viol:.0%}, median dv {dv:.2f} m/s")
+
+r_clear["agent"] = "PD, clear path"
+r_blocked["agent"] = "PD, target in the way"
+r_drift["agent"] = "drift (no thrust)"
+fig, ax = plt.subplots(figsize=(8, 5))
+plot_trajectories(
+    [r_clear, r_blocked, r_drift],
+    blocked,
+    ax=ax,
+    title="Approach to hold point: a naive controller flies through the keep-out zone",
+)
+fig.tight_layout()
+fig.savefig(out / "v0_trajectories.png", dpi=150)
+print(f"\nSaved {out / 'v0_trajectories.png'}")

vbar-0.0.1/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "vbar"
+version = "0.0.1"
+description = "A fast, headless, cross-platform benchmark for testing AI and classical spacecraft controllers, with safety filters."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "Jamil Hammoudeh", email = "j.hammoudeh@outlook.com" }]
+keywords = [
+    "spacecraft", "rendezvous", "proximity operations", "guidance navigation and control",
+    "benchmark", "reinforcement learning", "safety filter", "clohessy-wiltshire", "orbital mechanics",
+]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: Physics",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "numpy>=1.24",
+    "scipy>=1.10",
+    "gymnasium>=0.29",
+]
+
+[project.urls]
+Homepage = "https://github.com/jamilhammoudeh/vbar"
+Repository = "https://github.com/jamilhammoudeh/vbar"
+Issues = "https://github.com/jamilhammoudeh/vbar/issues"
+
+[project.optional-dependencies]
+plot = ["matplotlib>=3.7"]
+dev = ["pytest>=7", "matplotlib>=3.7"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/vbar"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

vbar-0.0.1/src/vbar/__init__.py

@@ -0,0 +1,7 @@
+"""vbar: a fast, headless benchmark for AI and classical spacecraft controllers."""
+
+from .envs import ApproachConfig, ApproachEnv
+from .runner import run_episode, run_many
+
+__version__ = "0.0.1"
+__all__ = ["ApproachConfig", "ApproachEnv", "run_episode", "run_many"]

vbar-0.0.1/src/vbar/agents/__init__.py

@@ -0,0 +1,5 @@
+from .base import Agent, DriftAgent
+from .llm import LLMAgent, parse_action
+from .pd import PDAgent
+
+__all__ = ["Agent", "DriftAgent", "LLMAgent", "PDAgent", "parse_action"]

vbar-0.0.1/src/vbar/agents/base.py

@@ -0,0 +1,29 @@
+"""Agent interface. Every controller (classical, learned, or LLM) implements this."""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+import numpy as np
+
+
+class Agent(Protocol):
+    name: str
+
+    def reset(self, env) -> None:
+        """Called at the start of each episode. `env` gives access to its config."""
+
+    def act(self, obs: np.ndarray, info: dict) -> np.ndarray:
+        """Return an action: 3 numbers in [-1, 1] (fraction of max thrust per axis)."""
+
+
+class DriftAgent:
+    """Does nothing. Useful as a sanity check: the chaser just drifts."""
+
+    name = "drift"
+
+    def reset(self, env) -> None:
+        pass
+
+    def act(self, obs, info):
+        return np.zeros(3)

vbar-0.0.1/src/vbar/agents/llm.py

@@ -0,0 +1,100 @@
+"""LLM agent: asks a language model for a thrust command at each decision step.
+
+This module does not depend on any model provider. You pass in a function
+`complete(prompt: str) -> str` that calls whatever model you want (a hosted
+API or a local model). That keeps the benchmark provider-neutral and makes
+the exact prompt part of the logged, reproducible record.
+
+Every call's prompt, raw reply, parsed action, parse failures, and wall-clock
+latency are logged in `self.log`.
+
+Note: in v0 the simulation pauses while the model thinks. A "real-time" mode,
+where the clock keeps running during the model call (as in KSPDG), is planned.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import time
+from typing import Callable
+
+import numpy as np
+
+PROMPT_TEMPLATE = """You are the guidance system of a chaser spacecraft near a target spacecraft.
+
+Frame (centered on the target): x = radial (up, away from Earth), y = along-track
+(direction of flight), z = cross-track. Units: meters and meters per second.
+
+Goal: reach the hold point {hold} m and stop there (speed below {cap_speed} m/s).
+Constraint: NEVER come within {keep_out} m of the target (the origin).
+Orbital mechanics apply (Clohessy-Wiltshire dynamics, mean motion n = {n:.6f} rad/s).
+
+Current state:
+  position = [{x:.1f}, {y:.1f}, {z:.1f}] m
+  velocity = [{vx:.3f}, {vy:.3f}, {vz:.3f}] m/s
+  distance to hold point = {dist:.1f} m, distance to target = {rng:.1f} m
+
+Each command is held for {dt:.0f} s. Thrust per axis is a fraction of the maximum
+({max_accel} m/s^2), between -1 and 1.
+
+Reply with ONLY a JSON object, for example: {{"ax": 0.1, "ay": -0.5, "az": 0.0}}"""
+
+
+def parse_action(text: str) -> np.ndarray | None:
+    """Extract {"ax":..,"ay":..,"az":..} from a model reply. Returns None on failure."""
+    match = re.search(r"\{.*?\}", text, flags=re.DOTALL)
+    if not match:
+        return None
+    try:
+        data = json.loads(match.group(0))
+        a = np.array([float(data["ax"]), float(data["ay"]), float(data["az"])])
+    except (ValueError, KeyError, TypeError):
+        return None
+    if not np.all(np.isfinite(a)):
+        return None
+    return np.clip(a, -1.0, 1.0)
+
+
+class LLMAgent:
+    def __init__(self, complete: Callable[[str], str], name: str = "llm"):
+        self.complete = complete
+        self.name = name
+        self.log: list[dict] = []
+
+    def reset(self, env) -> None:
+        self.env = env
+        self.log = []
+
+    def act(self, obs, info):
+        cfg = self.env.cfg
+        x, y, z, vx, vy, vz = obs
+        prompt = PROMPT_TEMPLATE.format(
+            hold=list(cfg.hold_point),
+            cap_speed=cfg.capture_speed,
+            keep_out=cfg.keep_out_radius,
+            n=self.env.n,
+            x=x, y=y, z=z, vx=vx, vy=vy, vz=vz,
+            dist=info["dist_to_hold_m"],
+            rng=info["range_to_target_m"],
+            dt=cfg.dt,
+            max_accel=cfg.max_accel,
+        )
+        t0 = time.perf_counter()
+        reply = self.complete(prompt)
+        latency = time.perf_counter() - t0
+        action = parse_action(reply)
+        failed = action is None
+        if failed:
+            action = np.zeros(3)  # safe default: coast
+        self.log.append(
+            {
+                "time_s": info["time_s"],
+                "prompt": prompt,
+                "reply": reply,
+                "action": action.tolist(),
+                "parse_failed": failed,
+                "latency_s": latency,
+            }
+        )
+        return action

vbar-0.0.1/src/vbar/agents/pd.py

@@ -0,0 +1,40 @@
+"""Classical baseline: proportional-derivative (PD) controller with CW cancellation.
+
+Idea: the CW equations add "orbital" accelerations (3n^2 x + 2n vy, -2n vx,
+-n^2 z). We cancel them, then add a PD law that pulls the chaser to the hold
+point like a damped spring:
+
+    a = -(CW terms) - Kp * (position - hold_point) - Kd * velocity
+
+With Kp = wn^2 and Kd = 2 * zeta * wn, the error behaves like a damped
+oscillator with natural frequency wn and damping ratio zeta.
+
+This baseline flies (roughly) a straight line to the hold point. It does NOT
+know about the keep-out zone, so if the target sits between the start and the
+hold point, it will fly through the keep-out zone. That is the point: it shows
+why a safety filter is needed.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+
+class PDAgent:
+    def __init__(self, wn: float = 0.01, zeta: float = 1.0, name: str = "pd"):
+        self.wn = wn
+        self.zeta = zeta
+        self.name = name
+
+    def reset(self, env) -> None:
+        self.n = env.n
+        self.hold = env.hold_point
+        self.max_accel = env.cfg.max_accel
+
+    def act(self, obs, info):
+        x, y, z, vx, vy, vz = obs
+        n = self.n
+        cw = np.array([3 * n**2 * x + 2 * n * vy, -2 * n * vx, -(n**2) * z])
+        kp, kd = self.wn**2, 2 * self.zeta * self.wn
+        a = -cw - kp * (obs[:3] - self.hold) - kd * obs[3:]
+        return np.clip(a / self.max_accel, -1.0, 1.0)

vbar-0.0.1/src/vbar/dynamics/__init__.py

@@ -0,0 +1,3 @@
+from .cw import MU_EARTH, R_EARTH, cw_rhs, cw_stm, mean_motion, propagate
+
+__all__ = ["MU_EARTH", "R_EARTH", "cw_rhs", "cw_stm", "mean_motion", "propagate"]

vbar-0.0.1/src/vbar/dynamics/cw.py

@@ -0,0 +1,118 @@
+"""Clohessy-Wiltshire (CW) relative motion.
+
+The CW equations describe how a "chaser" spacecraft moves relative to a
+"target" spacecraft that is in a circular orbit, when the two are close
+together (meters to a few kilometers).
+
+Frame (Hill / LVLH frame, centered on the target):
+    x : radial, pointing away from Earth (the "R-bar")
+    y : along-track, the direction the target is flying (the "V-bar")
+    z : cross-track, completing a right-handed frame (orbit normal)
+
+State vector: [x, y, z, vx, vy, vz] in meters and meters per second.
+
+Equations of motion (n = mean motion of the target orbit, a = thrust accel):
+
+    x'' =  3 n^2 x + 2 n y' + a_x
+    y'' = -2 n x'           + a_y
+    z'' = -n^2 z            + a_z
+
+Assumptions (state these in any paper that uses this model):
+    1. Target orbit is circular.
+    2. Chaser is close to the target compared with the orbit radius
+       (the equations come from linearizing two-body gravity).
+    3. No perturbations: no J2, drag, or solar pressure.
+
+Reference: H. Curtis, "Orbital Mechanics for Engineering Students", ch. 7.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from scipy.integrate import solve_ivp
+
+MU_EARTH = 3.986004418e14  # m^3/s^2
+R_EARTH = 6_378_137.0  # m
+
+
+def mean_motion(semi_major_axis_m: float, mu: float = MU_EARTH) -> float:
+    """Mean motion n = sqrt(mu / a^3), in rad/s."""
+    return float(np.sqrt(mu / semi_major_axis_m**3))
+
+
+def cw_rhs(t: float, state: np.ndarray, n: float, accel: np.ndarray) -> np.ndarray:
+    """Time derivative of the state under the CW equations.
+
+    `accel` is a constant thrust acceleration [a_x, a_y, a_z] in m/s^2.
+    """
+    x, y, z, vx, vy, vz = state
+    ax, ay, az = accel
+    return np.array(
+        [
+            vx,
+            vy,
+            vz,
+            3.0 * n**2 * x + 2.0 * n * vy + ax,
+            -2.0 * n * vx + ay,
+            -(n**2) * z + az,
+        ]
+    )
+
+
+def cw_stm(n: float, t: float) -> np.ndarray:
+    """Exact 6x6 state transition matrix (no thrust).
+
+    state(t) = cw_stm(n, t) @ state(0)
+
+    This is the closed-form solution of the CW equations. The simulator
+    integrates the equations numerically; this matrix is used to check
+    that the numerical integration is correct.
+    """
+    s, c = np.sin(n * t), np.cos(n * t)
+    nt = n * t
+    return np.array(
+        [
+            [4 - 3 * c, 0, 0, s / n, 2 * (1 - c) / n, 0],
+            [6 * (s - nt), 1, 0, -2 * (1 - c) / n, (4 * s - 3 * nt) / n, 0],
+            [0, 0, c, 0, 0, s / n],
+            [3 * n * s, 0, 0, c, 2 * s, 0],
+            [-6 * n * (1 - c), 0, 0, -2 * s, 4 * c - 3, 0],
+            [0, 0, -n * s, 0, 0, c],
+        ]
+    )
+
+
+def propagate(
+    state: np.ndarray,
+    n: float,
+    dt: float,
+    accel: np.ndarray | None = None,
+    n_samples: int = 0,
+    rtol: float = 1e-10,
+    atol: float = 1e-9,
+):
+    """Numerically propagate the state for `dt` seconds with constant thrust.
+
+    Returns the final state. If `n_samples > 0`, also returns an array of
+    intermediate states (n_samples, 6), used to check keep-out violations
+    *between* time steps, not only at the end of each step.
+    """
+    if accel is None:
+        accel = np.zeros(3)
+    sol = solve_ivp(
+        cw_rhs,
+        (0.0, dt),
+        np.asarray(state, dtype=float),
+        args=(n, np.asarray(accel, dtype=float)),
+        method="DOP853",
+        rtol=rtol,
+        atol=atol,
+        dense_output=n_samples > 0,
+    )
+    if not sol.success:  # pragma: no cover - solver failures are unexpected
+        raise RuntimeError(f"Integration failed: {sol.message}")
+    final = sol.y[:, -1]
+    if n_samples > 0:
+        ts = np.linspace(0.0, dt, n_samples)
+        return final, sol.sol(ts).T
+    return final

vbar-0.0.1/src/vbar/envs/__init__.py

@@ -0,0 +1,3 @@
+from .approach import ApproachConfig, ApproachEnv
+
+__all__ = ["ApproachConfig", "ApproachEnv"]

vbar-0.0.1/src/vbar/envs/approach.py

@@ -0,0 +1,139 @@
+"""Approach-to-hold-point scenario with a keep-out zone.
+
+Task: a chaser spacecraft must fly to a "hold point" near a target
+(by default 100 m behind it on the V-bar) and stop there, without entering
+a keep-out sphere around the target. This is the basic building block of
+rendezvous, inspection, and docking.
+
+The environment follows the Gymnasium API:
+    obs, info = env.reset(seed=...)
+    obs, reward, terminated, truncated, info = env.step(action)
+
+Action: 3 numbers in [-1, 1], scaled by `max_accel` to a constant thrust
+acceleration (m/s^2) in the Hill frame, held for one time step `dt`.
+
+Observation: the chaser's 6-element state [x, y, z, vx, vy, vz] relative to
+the target (see vbar.dynamics.cw for the frame).
+
+Benchmark metrics are reported in `info`; the reward is a simple shaped
+signal for reinforcement learning and is NOT the benchmark score.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+import gymnasium as gym
+import numpy as np
+from gymnasium import spaces
+
+from ..dynamics.cw import R_EARTH, mean_motion, propagate
+
+
+@dataclass
+class ApproachConfig:
+    altitude_m: float = 500e3  # target orbit altitude (circular)
+    dt: float = 10.0  # seconds per decision step
+    max_steps: int = 360  # 360 x 10 s = 1 hour
+    max_accel: float = 0.02  # m/s^2, max thrust acceleration per axis
+    keep_out_radius: float = 50.0  # m, sphere around the target
+    hold_point: tuple = (0.0, -100.0, 0.0)  # m, where the chaser must stop
+    capture_radius: float = 5.0  # m, "arrived" if this close to hold point
+    capture_speed: float = 0.05  # m/s, ...and slower than this
+    # Start state: fixed (if given) or sampled uniformly from these ranges.
+    start_state: tuple | None = None
+    start_pos_range: tuple = ((-200.0, 200.0), (200.0, 600.0), (-50.0, 50.0))
+    start_vel_range: tuple = ((-0.1, 0.1), (-0.1, 0.1), (-0.1, 0.1))
+    terminate_on_violation: bool = False
+    violation_samples: int = 20  # sub-samples per step to catch violations
+    reward_dv_weight: float = 1.0
+    extra: dict = field(default_factory=dict)
+
+
+class ApproachEnv(gym.Env):
+    metadata = {"render_modes": []}
+
+    def __init__(self, config: ApproachConfig | None = None):
+        super().__init__()
+        self.cfg = config or ApproachConfig()
+        self.n = mean_motion(R_EARTH + self.cfg.altitude_m)
+        self.hold_point = np.array(self.cfg.hold_point, dtype=float)
+        self.action_space = spaces.Box(-1.0, 1.0, shape=(3,), dtype=np.float32)
+        # Generous finite bounds (positions in m, velocities in m/s).
+        self.observation_space = spaces.Box(-1e7, 1e7, shape=(6,), dtype=np.float64)
+        self.state = np.zeros(6)
+
+    # ------------------------------------------------------------------ #
+    def _sample_start(self) -> np.ndarray:
+        if self.cfg.start_state is not None:
+            return np.array(self.cfg.start_state, dtype=float)
+        pos = [self.np_random.uniform(lo, hi) for lo, hi in self.cfg.start_pos_range]
+        vel = [self.np_random.uniform(lo, hi) for lo, hi in self.cfg.start_vel_range]
+        return np.array(pos + vel, dtype=float)
+
+    def _info(self) -> dict:
+        pos, vel = self.state[:3], self.state[3:]
+        return {
+            "time_s": self.t,
+            "dist_to_hold_m": float(np.linalg.norm(pos - self.hold_point)),
+            "range_to_target_m": float(np.linalg.norm(pos)),
+            "speed_mps": float(np.linalg.norm(vel)),
+            "dv_used_mps": self.dv_used,
+            "min_range_to_target_m": self.min_range,
+            "keep_out_violated": self.violated,
+            "violation_steps": self.violation_steps,
+            "captured": self.captured,
+        }
+
+    # ------------------------------------------------------------------ #
+    def reset(self, *, seed=None, options=None):
+        super().reset(seed=seed)
+        self.state = self._sample_start()
+        self.t = 0.0
+        self.steps = 0
+        self.dv_used = 0.0
+        self.min_range = float(np.linalg.norm(self.state[:3]))
+        self.violated = self.min_range < self.cfg.keep_out_radius
+        self.violation_steps = int(self.violated)
+        self.captured = False
+        return self.state.copy(), self._info()
+
+    def step(self, action):
+        action = np.clip(np.asarray(action, dtype=float), -1.0, 1.0)
+        accel = action * self.cfg.max_accel
+        prev_dist = np.linalg.norm(self.state[:3] - self.hold_point)
+
+        self.state, samples = propagate(
+            self.state, self.n, self.cfg.dt, accel, n_samples=self.cfg.violation_samples
+        )
+        self.t += self.cfg.dt
+        self.steps += 1
+        # Delta-v: constant acceleration magnitude times burn duration.
+        step_dv = float(np.linalg.norm(accel) * self.cfg.dt)
+        self.dv_used += step_dv
+
+        # Keep-out check over the whole step, not just its end point.
+        ranges = np.linalg.norm(samples[:, :3], axis=1)
+        self.min_range = min(self.min_range, float(ranges.min()))
+        step_violation = bool(ranges.min() < self.cfg.keep_out_radius)
+        if step_violation:
+            self.violated = True
+            self.violation_steps += 1
+
+        info = self._info()
+        self.captured = (
+            info["dist_to_hold_m"] < self.cfg.capture_radius
+            and info["speed_mps"] < self.cfg.capture_speed
+        )
+        info["captured"] = self.captured
+
+        # Shaped reward for RL: progress toward hold point, minus fuel,
+        # minus a penalty for being inside the keep-out zone.
+        reward = (prev_dist - info["dist_to_hold_m"]) / 100.0
+        reward -= self.cfg.reward_dv_weight * step_dv
+        reward -= 1.0 * step_violation
+        reward += 10.0 * self.captured
+
+        terminated = self.captured or (step_violation and self.cfg.terminate_on_violation)
+        truncated = self.steps >= self.cfg.max_steps
+        return self.state.copy(), float(reward), terminated, truncated, info

vbar-0.0.1/src/vbar/runner.py

@@ -0,0 +1,43 @@
+"""Run episodes and collect benchmark metrics."""
+
+from __future__ import annotations
+
+import time
+
+import numpy as np
+
+
+def run_episode(env, agent, seed: int | None = None) -> dict:
+    """Run one episode. Returns final metrics plus the full trajectory."""
+    obs, info = env.reset(seed=seed)
+    agent.reset(env)
+    states, actions = [obs.copy()], []
+    t0 = time.perf_counter()
+    terminated = truncated = False
+    while not (terminated or truncated):
+        action = np.asarray(agent.act(obs, info), dtype=float)
+        obs, _, terminated, truncated, info = env.step(action)
+        states.append(obs.copy())
+        actions.append(action)
+    result = {
+        "agent": agent.name,
+        "seed": seed,
+        "captured": info["captured"],
+        "keep_out_violated": info["keep_out_violated"],
+        "violation_steps": info["violation_steps"],
+        "min_range_to_target_m": info["min_range_to_target_m"],
+        "final_dist_to_hold_m": info["dist_to_hold_m"],
+        "dv_used_mps": info["dv_used_mps"],
+        "time_s": info["time_s"],
+        "wall_time_s": time.perf_counter() - t0,
+        "states": np.array(states),
+        "actions": np.array(actions),
+    }
+    if hasattr(agent, "interventions"):
+        result["filter_interventions"] = agent.interventions
+    return result
+
+
+def run_many(env, agent, seeds) -> list[dict]:
+    """Run one episode per seed. (Parallel runner planned.)"""
+    return [run_episode(env, agent, seed=s) for s in seeds]

vbar-0.0.1/src/vbar/safety/__init__.py

@@ -0,0 +1,48 @@
+"""Safety filters: wrap any agent and correct unsafe commands before they run.
+
+v0 only defines the interface and a pass-through filter. Planned:
+    - CBF-QP filter (control barrier function + quadratic program) for the
+      keep-out sphere and approach-speed limits.
+    - Wrapping or porting AFRL's run-time-assurance library (act3-ace), which
+      should be cited, not reinvented.
+
+The wrapper records how often the filter changed the agent's command
+("interventions"), which is one of the benchmark's core metrics.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+
+class PassThroughFilter:
+    """Does not change the action. The 'safety filter off' condition."""
+
+    name = "none"
+
+    def filter(self, obs: np.ndarray, action: np.ndarray, env) -> np.ndarray:
+        return action
+
+
+class FilteredAgent:
+    """Agent + safety filter, presented as a single agent."""
+
+    def __init__(self, agent, safety_filter, tol: float = 1e-6):
+        self.agent = agent
+        self.filter = safety_filter
+        self.tol = tol
+        self.name = f"{agent.name}+{safety_filter.name}"
+
+    def reset(self, env) -> None:
+        self.env = env
+        self.agent.reset(env)
+        self.interventions = 0
+        self.decisions = 0
+
+    def act(self, obs, info):
+        raw = np.asarray(self.agent.act(obs, info), dtype=float)
+        safe = np.asarray(self.filter.filter(obs, raw, self.env), dtype=float)
+        self.decisions += 1
+        if np.max(np.abs(safe - raw)) > self.tol:
+            self.interventions += 1
+        return safe

vbar-0.0.1/src/vbar/viz.py

@@ -0,0 +1,38 @@
+"""Plotting helpers (requires matplotlib: pip install vbar[plot])."""
+
+from __future__ import annotations
+
+import numpy as np
+
+
+def plot_trajectories(results: list[dict], env, ax=None, title: str | None = None):
+    """Top-down view: along-track (y, V-bar) horizontal, radial (x, R-bar) vertical.
+
+    Draws the keep-out zone, the target, and the hold point. One line per result.
+    """
+    import matplotlib.pyplot as plt
+
+    if ax is None:
+        _, ax = plt.subplots(figsize=(7, 5))
+    styles = ["-", "--", "-.", ":"]
+    for i, r in enumerate(results):
+        s = r["states"]
+        status = "violated keep-out" if r["keep_out_violated"] else "safe"
+        label = f'{r["agent"]} ({status}, dv={r["dv_used_mps"]:.2f} m/s)'
+        ax.plot(s[:, 1], s[:, 0], styles[i % len(styles)], lw=1.8, label=label)
+        ax.plot(s[0, 1], s[0, 0], "o", color=ax.lines[-1].get_color(), ms=5)
+
+    ko = env.cfg.keep_out_radius
+    th = np.linspace(0, 2 * np.pi, 200)
+    ax.fill(ko * np.cos(th), ko * np.sin(th), color="0.85", label=f"keep-out ({ko:.0f} m)")
+    ax.plot(0, 0, "k+", ms=10, label="target")
+    hp = env.hold_point
+    ax.plot(hp[1], hp[0], "k*", ms=12, label="hold point")
+    ax.set_xlabel("along-track y, V-bar (m)")
+    ax.set_ylabel("radial x, R-bar (m)")
+    ax.set_aspect("equal", adjustable="datalim")
+    ax.grid(alpha=0.3)
+    ax.legend(fontsize=8, loc="best")
+    if title:
+        ax.set_title(title)
+    return ax

vbar-0.0.1/tests/test_cw.py

@@ -0,0 +1,68 @@
+"""Validation of the CW dynamics. If these fail, every result is wrong."""
+
+import numpy as np
+import pytest
+
+from vbar.dynamics import R_EARTH, cw_stm, mean_motion, propagate
+
+N = mean_motion(R_EARTH + 500e3)
+PERIOD = 2 * np.pi / N
+
+
+def test_mean_motion_leo_period():
+    # A 500 km circular orbit has a period of about 94.6 minutes.
+    assert PERIOD / 60 == pytest.approx(94.6, abs=0.1)
+
+
+def test_stm_identity_at_zero():
+    assert np.allclose(cw_stm(N, 0.0), np.eye(6))
+
+
+def test_stm_composition():
+    # Propagating t1 then t2 must equal propagating t1 + t2.
+    t1, t2 = 700.0, 1900.0
+    assert np.allclose(cw_stm(N, t2) @ cw_stm(N, t1), cw_stm(N, t1 + t2), atol=1e-9)
+
+
+@pytest.mark.parametrize("seed", range(10))
+def test_numerical_matches_exact_solution(seed):
+    # The core check: numerical integration agrees with the closed-form
+    # solution to sub-millimeter accuracy over a full orbit.
+    rng = np.random.default_rng(seed)
+    s0 = np.r_[rng.uniform(-2000, 2000, 3), rng.uniform(-2, 2, 3)]
+    numeric = propagate(s0, N, PERIOD)
+    exact = cw_stm(N, PERIOD) @ s0
+    assert np.max(np.abs(numeric[:3] - exact[:3])) < 1e-3  # meters
+    assert np.max(np.abs(numeric[3:] - exact[3:])) < 1e-6  # m/s
+
+
+def test_vbar_point_is_equilibrium():
+    # A chaser sitting still on the V-bar (along-track) stays there forever.
+    s0 = np.array([0.0, 400.0, 0.0, 0.0, 0.0, 0.0])
+    assert np.allclose(propagate(s0, N, PERIOD), s0, atol=1e-6)
+
+
+def test_closed_ellipse_is_periodic():
+    # With vy0 = -2 n x0 there is no along-track drift: after one orbit the
+    # chaser is back where it started (a "football" orbit around the target).
+    x0 = 100.0
+    s0 = np.array([x0, 0.0, 0.0, 0.0, -2 * N * x0, 0.0])
+    assert np.allclose(propagate(s0, N, PERIOD), s0, atol=1e-5)
+
+
+def test_rbar_offset_drifts():
+    # A chaser placed below the target (x < 0) with zero velocity drifts
+    # along-track: lower orbit = faster. Classic CW behavior.
+    s0 = np.array([-100.0, 0.0, 0.0, 0.0, 0.0, 0.0])
+    s1 = propagate(s0, N, PERIOD)
+    assert s1[1] > 0  # moved ahead in +y
+    # Exact drift per orbit is 12*pi*|x0| (from the closed-form solution).
+    assert s1[1] == pytest.approx(12 * np.pi * 100.0, rel=1e-6)
+
+
+def test_constant_thrust_changes_velocity():
+    # Over a short burn, delta-v is approximately accel * time.
+    s0 = np.zeros(6)
+    a = np.array([0.0, 0.01, 0.0])
+    s1 = propagate(s0, N, 1.0, a)
+    assert s1[4] == pytest.approx(0.01, rel=1e-3)

vbar-0.0.1/tests/test_env.py

@@ -0,0 +1,78 @@
+import numpy as np
+import pytest
+from gymnasium.utils.env_checker import check_env
+
+from vbar import ApproachConfig, ApproachEnv, run_episode
+from vbar.agents import DriftAgent, LLMAgent, PDAgent, parse_action
+from vbar.safety import FilteredAgent, PassThroughFilter
+
+
+def test_gymnasium_api_compliance():
+    check_env(ApproachEnv(), skip_render_check=True)
+
+
+def test_reset_is_reproducible_with_seed():
+    env = ApproachEnv()
+    a, _ = env.reset(seed=3)
+    b, _ = env.reset(seed=3)
+    assert np.allclose(a, b)
+
+
+def test_dv_accounting():
+    env = ApproachEnv(ApproachConfig(start_state=(0, 400, 0, 0, 0, 0)))
+    env.reset()
+    _, _, _, _, info = env.step(np.array([1.0, 0.0, 0.0]))
+    assert info["dv_used_mps"] == pytest.approx(env.cfg.max_accel * env.cfg.dt)
+
+
+def test_drift_on_vbar_stays_safe():
+    env = ApproachEnv(ApproachConfig(start_state=(0, 400, 0, 0, 0, 0)))
+    r = run_episode(env, DriftAgent())
+    assert not r["keep_out_violated"]
+    assert r["dv_used_mps"] == 0.0
+
+
+def test_pd_reaches_hold_point_on_clear_path():
+    env = ApproachEnv(ApproachConfig(start_state=(-150, -400, 0, 0, 0, 0)))
+    r = run_episode(env, PDAgent())
+    assert r["captured"] and not r["keep_out_violated"]
+
+
+def test_pd_violates_keep_out_when_target_is_in_the_way():
+    # Documents the motivating failure: a naive controller flies straight
+    # through the keep-out zone. A safety filter should prevent this.
+    env = ApproachEnv(ApproachConfig(start_state=(0, 400, 0, 0, 0, 0)))
+    r = run_episode(env, PDAgent())
+    assert r["keep_out_violated"]
+
+
+def test_violation_detected_between_steps():
+    # Fast pass through the keep-out zone within a single step must be caught.
+    cfg = ApproachConfig(start_state=(0, 60, 0, 0, -12, 0), dt=10.0)
+    env = ApproachEnv(cfg)
+    env.reset()
+    _, _, _, _, info = env.step(np.zeros(3))
+    assert info["range_to_target_m"] > cfg.keep_out_radius  # end point is outside...
+    assert info["keep_out_violated"]  # ...but the path went through
+
+
+def test_parse_action():
+    assert np.allclose(parse_action('{"ax": 0.1, "ay": -2, "az": 0}'), [0.1, -1.0, 0.0])
+    assert parse_action("no json here") is None
+    assert parse_action('{"ax": "fast"}') is None
+
+
+def test_llm_agent_with_fake_model_logs_everything():
+    env = ApproachEnv(ApproachConfig(start_state=(0, 400, 0, 0, 0, 0), max_steps=5))
+    agent = LLMAgent(lambda prompt: '{"ax": 0, "ay": -0.2, "az": 0}', name="fake-llm")
+    r = run_episode(env, agent)
+    assert len(agent.log) == 5
+    assert not any(e["parse_failed"] for e in agent.log)
+    assert r["dv_used_mps"] > 0
+
+
+def test_filtered_agent_counts_interventions():
+    env = ApproachEnv(ApproachConfig(start_state=(0, 400, 0, 0, 0, 0), max_steps=5))
+    agent = FilteredAgent(PDAgent(), PassThroughFilter())
+    r = run_episode(env, agent)
+    assert r["filter_interventions"] == 0