# CG-RVC Reproducibility Package

This repository is a standalone artifact for the paper:

**Certificate-Guided Residual Variance Control for Safe Learned Control under Nonnormal Closed-Loop Amplification**

The package contains the paper PDF/LaTeX source, implementation code, seed-level result logs, aggregated tables, plotting artifacts, and a cached-results verifier. The fastest reviewer path is:

```bash
python repro/reproduce_cached_results.py --strict
```

Equivalent wrapper:

```bash
bash code/run_all.sh
```

Docker cached verification:

```bash
docker build -f docker/Dockerfile -t cgrvc-repro .
docker run --rm cgrvc-repro
```

The command reads the included seed-level CSV/JSON files, regenerates the key comparison tables under `reproduced/`, and checks that the main claims used in the paper are supported by the cached evidence.

## Repository Layout

- `paper/` - manuscript source, compiled PDF, bibliography, figure PNGs, and revision notes.
- `src/` - reusable control, RL, certificate, and diagnostic modules.
- `controlgym_full_method*/` - compact method implementations used by the controlled benchmark suites.
- `run_*.py` - experiment entrypoints for causal isolation, TD3/CG-RVC baselines, safe-RL comparisons, UAV/Full3D suites, and diagnostics.
- `data/raw/` - seed-level and suite-level raw outputs copied from the paper runs.
- `data/processed/` - processed revision tables used by the submitted manuscript.
- `repro/` - reviewer-facing reproduction and smoke-test scripts.
- `docs/` - artifact manifest, detailed reproduction guide, legacy notes, and expected runtimes.

## Included Evidence

The cached evidence covers:

- 2D safe10 high-noise comparison with Direct TD3, TD3 ablations, PPO-Penalty, PPO-Lagrangian, SAC-Lagrangian, and Shielded SAC.
- Causal-isolation source/amplifier intervention results.
- Metric-attribution ablations for the certificate-weighted action metric.
- Actor-augmented closed-loop diagnostics.
- Full3D quadrotor white-vs-filtered high-noise diagnostics.

Large model checkpoint archives are intentionally not included. The CSV/JSON rollout logs needed to regenerate the paper tables are included, and the training entrypoints that regenerate checkpoints are included.

`appendix_proofs.pdf` is an alias to the submitted full paper PDF, whose appendix/proof material is included inside the manuscript rather than shipped as a separate proof-only document.

## Environment

For cached verification only:

```bash
python -m pip install -r requirements-cached.txt
python repro/reproduce_cached_results.py --strict
```

For retraining and plotting:

```bash
python -m pip install -r requirements.txt
```

The optional OmniSafe CPO bridge is isolated in `run_omnisafe_cpo_baseline.py`; install `requirements-cpo-optional.txt` only if you want to rerun that external CPO adapter.

## Full Reproduction Commands

Cached table regeneration:

```bash
python repro/reproduce_cached_results.py --strict
```

2D safe10 TD3/CG-RVC/safe-RL comparison:

```bash
python run_td3_paper_baseline_comparison.py --help
```

Causal-isolation suite:

```bash
python run_causal_isolation_suite.py --help
```

Full3D quadrotor suite:

```bash
python run_uav_rl_benchmark.py --help
python run_full_quadrotor_generalization_suite.py --help
```

The detailed command map is in `docs/REPRO_GUIDE.md`.

## Publishing to GitHub

The repository is ready for GitHub publication after a remote or authenticated GitHub CLI session is available:

```powershell
powershell -ExecutionPolicy Bypass -File repro/publish_to_github.ps1 -RemoteUrl https://github.com/<owner>/<repo>.git
```

See `docs/GITHUB_PUBLISHING.md` for the `gh repo create` path and readiness checks.

## Validation Status

This artifact is designed so a reviewer can verify paper tables from cached raw evidence without retraining. Full retraining is compute-dependent and may take hours depending on hardware and selected seeds. Local validation results should be recorded by rerunning:

```bash
powershell -ExecutionPolicy Bypass -File repro/run_smoke_tests.ps1
```

Use `-FullPytest` only when you explicitly want to run the longer training and simulation tests.
