Metadata-Version: 2.4
Name: parallelcbf
Version: 0.1.1
Summary: Composable safety-filter interfaces for parallel robot learning.
Project-URL: Homepage, https://github.com/xiaoyang-123-cell/ParallelCBF
Project-URL: Repository, https://github.com/xiaoyang-123-cell/ParallelCBF
Project-URL: Issues, https://github.com/xiaoyang-123-cell/ParallelCBF/issues
Author: Yuyin Ma
Author-email: Zilei Yang <107552504876@stu.xju.edu.cn>
Maintainer-email: Zilei Yang <107552504876@stu.xju.edu.cn>
License-Expression: Apache-2.0
License-File: AUTHORS
License-File: LICENSE
License-File: NOTICE
Keywords: auditability,control barrier functions,robot learning,safe reinforcement learning
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: <3.14,>=3.10
Requires-Dist: gymnasium
Requires-Dist: numpy
Requires-Dist: pydantic
Requires-Dist: torch
Provides-Extra: docs
Requires-Dist: mkdocs-jupyter; extra == 'docs'
Requires-Dist: mkdocs-material; extra == 'docs'
Requires-Dist: mkdocstrings[python]; extra == 'docs'
Provides-Extra: test
Requires-Dist: hypothesis; extra == 'test'
Requires-Dist: mypy; extra == 'test'
Requires-Dist: pytest; extra == 'test'
Requires-Dist: pytest-cov; extra == 'test'
Description-Content-Type: text/markdown

# 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

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

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

## Quickstart

```python
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

```bash
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`.
