A small, standalone research implementation of current-action gradient policy-barrier filtering with a latent world model. Extracted from the working LatentCBF thesis code, not from its project website.
Includes the RSSM, a supervised physical-state decoder, fixed-control physical sensitivity losses, exact branch-aware ClearRay feedback, gradient filtering, a sampled reference, the original RGB Dubins environment, training/evaluation commands, and numerical tests. No diffusion policy, HJ actor/critic, original MPC, experiment banks, website, datasets, or pretrained weights are bundled.
Python3.10+; tested with Python3.10, PyTorch2.7.1 and NumPy1.24.4. Choose the appropriate PyTorch CPU/CUDA build first.
python -m venv .venv
. .venv/bin/activate
# Optional CPU-only build:
pip install torch==2.7.1 --index-url https://download.pytorch.org/whl/cpu
pip install -e '.[test]'
pytest -q
# Runnable without any data or checkpoint:
gradient-cbf demo --seed 0 --max-steps 20 --output outputs/demoThe demo uses a privileged analytic physical-state model, not a learned encoder and not the thesis benchmark. It checks the filter wiring; do not present its trajectories as learned-model results. Output paths are exclusive: commands refuse to overwrite existing runs.
For a frozen model F, physical readout p_hat, known circles (c_i,r_i) and ClearRay backup pi:
ell(z) = min_i(||p_hat(z) - c_i|| - r_i)
z_0 = z; z_{k+1} = F(z_k, pi(z_k))
h_H(z) = min_{k=0,...,H} ell(z_k)
r(z,u) = h_H(F(z,u)) - 0.9 h_H(z)
accept if r(z,u) >= residual_buffer
H=18 includes stage0. The successor gets its OWN full18 backup transitions, never an H17 tail. Only the current scalar command is optimized; future backup controls remain feedback, not MPC decision variables. alpha=0.9 in RolloutFilterConfig means retention, not the paper's decay-alpha convention.
The gradient solver retains the source's12 projected-Adam iterations,8 refinements, lr0.25, tolerance0.001, exact nominal/backup/zero checks, final scalar verification and highest-tested-value fallback. The sampled reference retains257 grid points plus exact markers and its nominal fast path. Fallback does not imply feasibility or safety. ClearRay retains buffer0.1m, gain4, bounds+-2rad/s, original tangent/wrap/clip/tie branches, bit-preserved NumPy forward values and analytic derivatives within the selected branch. No soft minimum or detached-feedback surrogate is substituted.
The safety model observes RGB plus measured heading and the actual previous float32 command, with a full warm mean-RSSM history from reset. It never receives simulator xy. The shared obstacle-blind nominal does use measured current xy/heading and the actual goal; this privilege is intentional and disclosed.
Supply an existing self-describing physical-readout checkpoint or train one. Loading checks architecture, camera, timestep, finite weights, and nonzero completed training steps. It does not establish physical prediction accuracy or verify the horizon condition.
gradient-cbf evaluate \
--checkpoint /path/to/world_model.pt --device cuda:0 \
--seeds 12001 12002 12003 --method gradient \
--allow-experimental-model --output outputs/learnedresidual_buffer defaults to 0m. It is NOT a universal robust threshold. The historical J3-Q95 value 0.009147522598034925m was calibrated for the SPECIFIC checkpoint SHA256 ca2d3e5240a5193d47b1e8370149906392cec264cf5c73025778e9c55c9bde9f and its frozen experimental setup. Only when deliberately reproducing that setup should you pass:
--residual-buffer 0.009147522598034925Do not reuse that margin for a retrained model. Calibration tooling and the full immutable benchmark runner are intentionally not bundled. This lightweight CLI saves actions, physical states, nominal actions, residual/fallback diagnostics and synchronized end-to-end controller times. It is not a reproduction of the full five-arm benchmark's trace overhead, statistical analysis or canonical offline oracle audit.
Training is opt-in and always requires a fixed update budget. Nothing trains during evaluation or import.
gradient-cbf train \
--data /path/to/raw.h5 \
--normalization /path/to/normalization.json \
--steps 40000 --batch-size 32 --seed 0 --device cuda:0 \
--sensitivity-weight 10 --output outputs/trainThe native reconstruction/continuation/KL objective, posterior physical-state loss, fixed-control rollout-value loss and mixed-derivative sensitivity loss have weights1/1/1/10. --sensitivity-weight 0 provides the corresponding ablation. The physical teacher uses speed1m/s, dt0.05s and action gain1. Horizons1/2/4/8/16, periodic heading error, recorded future controls, reset/terminal masks, frozen positive normalization scales and create_graph=True mixed derivatives follow the source implementation. No latent-to-latent Jacobian-matching replacement is used.
normalization.json must contain the original horizons, dt, true_speed, true_action_gain, value_rms and sensitivity_rms schema. Scales must be frozen from training-only data, not fitted on test/failure banks. Normalization fitting and the historical physical-coverage collection/selection pipeline remain external. The original J3 coverage data deliberately reused previously frozen scales; blindly refitting those is not historical reproduction.
Required HDF5 layout:
attrs: observation_geometry (version1 JSON), collection_complete, class_coverage_passed
splits/train, splits/validation: exhaustive, disjoint UTF-8 trajectory keys
trajectories/<key>/
observations: uint8 [T+1,128,128,3]
states: [T+1,3] physical x[m], y[m], theta[rad]
actions: [T] physical steering[rad/s]
failures: [T] destination contact labels
state_collisions, terminals: [T+1]
attrs/metadata: JSON with condition_seed, goal_position
Group every behavior for a condition into ONE split. Incoming command at frame0 is zero; at frame t>0 it is the recorded actions[t-1], without an extra factor2. Camera-censored endings are not fabricated physical terminals. The versioned joint-pose coverage corpus is supported; the older first-camera collection-plan validator is deliberately NOT included, and that older protocol is rejected rather than silently bypassing its checks.
Final output is checkpoint.pt, with embedded model config, camera, data/source hashes, split and fixed step count, plus loss logs and optimizer state. No early stopping, test selection, actor or GP-margin fitting occurs. The unused legacy GP tensors remain only to keep strict compatibility with original RSSM checkpoints; the structured filter never queries them. The source optimizer's continuation-head parameter handling is retained, not silently repaired.
This is a compact training entry point, not a bitwise reproduction of the historical paired40k run: initialization, batch order, environment, grouped data and frozen scales must also match. A new training run is a new experiment.
Point agent; circles (0.25,+-0.65,0.5); speed1m/s, dt0.05s, turn bounds+-2rad/s. Literal resets x[-2,-1.5],y[-1,1],heading[-pi/3,pi/3]. RGB128x128 camera x[-2.5,1.5],y[-2,2] is a perception viewport, not a wall. Contacts and camera exits do not terminate motion. Goal radius is configured0.05m; original native success uses0.20m. Preserve postcontact/off-camera suffixes through goal or timeout.
Gradients can be locally correct while values remain optimistic. Hard minima, wraps, tangencies and clipping are nonsmooth; active-branch derivatives are not global smoothness guarantees. Model-feasible actions can still contact physical obstacles. No uniform-error, conjugacy/preimage, recursive-feasibility, invariance, infinite-tail, intersample-safety or hard-real-time guarantee is claimed.
The original fresh100-case comparison observed0contacts for both Classic sampled and both J3-Q95 solvers; it did NOT establish contact superiority for gradient search. J3 gradient was substantially slower than sampled search. That evidence belongs to the original locked run, not this extracted package; no favorable performance result is implied by the repository name.
src/gradient_cbf/: filter, backup, RSSM adapter, training losses, loader and commands.src/gradient_cbf/_dreamer/: minimal vendored model/network/math dependency closure.tests/: preserved numerical assertions plus standalone packaging/data/CLI checks.extraction.json: source-file hashes, extraction notes and local website-backup location.
Derived from CMU Intent Lab's LatentCBF and the dirty thesis checkout recorded in extraction.json. Original authorship, comments and licenses are retained. See LICENSE and THIRD_PARTY.md. The accidentally copied website is preserved outside this repository. No commits, remote URL or push are created automatically.