vbar 0.0.1__py3-none-any.whl

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/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/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/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/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/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/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/envs/__init__.py

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

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/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/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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,16 @@
+vbar/__init__.py,sha256=2ydnwI5qLPbI7WjKUpKN_tLgar56S0wuWUWDRjs5NT0,267
+vbar/runner.py,sha256=GcStaBsq1O6juslcWKP0PvlP0rk4iKOl8mQV4mKXPAQ,1481
+vbar/viz.py,sha256=UL4qMhSfoPfm8L-8I7qmh-BYrDWIsnIbl5JQJSQioNU,1440
+vbar/agents/__init__.py,sha256=PIys_bTuH7fyGqXL0jFMYhHnoDH9oXB3i7bDLtVGd5c,174
+vbar/agents/base.py,sha256=LmWqfCPcyZv3RGLmYf6TMl5aO-Qx41v77oAvGjhWWXI,701
+vbar/agents/llm.py,sha256=UUcM9u_A0AUga-1h_zCAGdbfyLdloQc0zT-cR01NAW0,3486
+vbar/agents/pd.py,sha256=GagjADKBZatprUIVEyuLhyLxZN4-U1FLIFGBOl1LvJM,1425
+vbar/dynamics/__init__.py,sha256=87D68Ra2nRVpsVdWtpixha8hzkYjop9-WfRNT4gShgA,157
+vbar/dynamics/cw.py,sha256=0d_0DXqKs5YxEjYDSRVQqqQrZiMVW5WkUvXjB7BT1DA,3734
+vbar/envs/__init__.py,sha256=l1ZDBDI5q6xu4cEjz0lR7muDhKazsaVLXeadY2jVc-w,95
+vbar/envs/approach.py,sha256=07SqPq61gVMzSKVSlWink5y3Gf1BHg6C-qa-MKE5jLE,5928
+vbar/safety/__init__.py,sha256=R_XodYV62PrGWf8keWsljLk3S9FdeexBhM7Iq1RUN1E,1551
+vbar-0.0.1.dist-info/METADATA,sha256=U6V3yE5pJtSnS4zYecUrIUHJwhYCvbRYx1VRsuY-N6A,4026
+vbar-0.0.1.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+vbar-0.0.1.dist-info/licenses/LICENSE,sha256=cDHetqbE_LnMj1mM7gvxVCuDU1i6nAI3bebIYdoULgw,1072
+vbar-0.0.1.dist-info/RECORD,,

vbar-0.0.1.dist-info/WHEEL

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

vbar-0.0.1.dist-info/licenses/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.