parallelcbf 0.1.1

Composable safety-filter interfaces for parallel robot learning.

ParallelCBF

Composable safety filters, deterministic test fixtures, and auditability tools for parallel robot-learning pipelines.

v0.2 cycle complete: 2D ParallelCBF archive. See tags for the exact code state matching our arXiv preprint. The v0.2 release keeps the full experiment-record audit trail in experiment_records_log/, including negative results, spec defects, amendment history, and KF-001 through KF-005 telemetry.

While Isaac Lab provides massive parallel UAV simulation, OmniSafe and safe-control-gym provide constrained-RL benchmarks, and CBFKit provides control-barrier-function synthesis tooling, no existing framework unifies these capabilities for end-to-end safety-constrained training. ParallelCBF is the first framework to unify (i) tensor-parallel UAV environments, (ii) hard-gate CBF safety filters, (iii) sharded BC-to-RL pipelines, and (iv) first-class operational auditability — pre-registration, watchdog registries, failure forensics, and dataset audits as composable APIs rather than user-implemented scripts.

Why ParallelCBF?

ParallelCBF is a small, simulator-agnostic framework for composing:

• safety-aware environments;
• control barrier function safety filters;
• SB3/CleanRL-style algorithms;
• watchdogs, pre-registration artifacts, atomic checkpoints, and failure forensics.

The v0.1 scope is intentionally narrow: pure Python/NumPy/PyTorch CPU examples, strict type hints, property tests, and reusable contracts. Isaac Lab adapters, Mamba policies, and PPO training integrations are deferred to v0.2.

Capability Comparison

Capability	ParallelCBF	Isaac Lab	OmniSafe	safe-control-gym	CBFKit
Simulator-agnostic safety API	✅	❌	❌	❌	❌
Extends Gymnasium-style envs	✅	✅	✅	✅	❌
Composable safety wrapper	✅	❌	❌	❌	❌
CBF safety-filter abstraction	✅	❌	❌	❌	✅
PyTorch batched CBF reference	✅	❌	❌	❌	❌
Strict broadcast-shape tests	✅	❌	❌	❌	❌
Property tests for invariance	✅	❌	❌	❌	❌
CPU-only reference environment	✅	❌	✅	✅	❌
Parallel/vectorized toy fixture	✅	✅	✅	❌	❌
Watchdog registry	✅	❌	❌	❌	❌
Failure-forensics rolling buffer	✅	❌	❌	❌	❌
Atomic checkpoint helper	✅	❌	❌	❌	❌
Pre-registration artifact commit	✅	❌	❌	❌	❌
Dataset audit as plugin	✅	❌	❌	❌	❌
MLOSS-oriented packaging/docs	✅	✅	✅	✅	❌

Installation

python -m pip install -e ".[test]"

ParallelCBF v0.1 supports Python >=3.10,<3.14.

Quickstart

import numpy as np

from parallelcbf.algorithms import RandomActionAlgorithm
from parallelcbf.envs import Toy2DAvoidanceEnv
from parallelcbf.ops import DefaultWatchdogRegistry, ThresholdWatchdog
from parallelcbf.safety import NaiveDistanceCBF
from parallelcbf.api import SafetyWrapper

env = SafetyWrapper(Toy2DAvoidanceEnv(), NaiveDistanceCBF())
watchdogs = DefaultWatchdogRegistry()
watchdogs.register(ThresholdWatchdog("h_hard_violation", 0.0))
algo = RandomActionAlgorithm(seed=7)

obs, _ = env.reset(seed=7)
algo.learn(env, total_timesteps=20, callback=watchdogs)
assert obs.shape == (8,)
assert not watchdogs.should_halt()

Development

pytest tests
mypy --strict parallelcbf tests
pytest --cov=parallelcbf --cov-report=term-missing tests

The test suite pins CPU execution in tests/conftest.py to avoid accidental GPU allocation in shared training environments.

Citation

If you use ParallelCBF, please cite the repository metadata in CITATION.cff.

License

Apache License 2.0. See LICENSE.