# Reproduction Guide

This guide maps the paper evidence to files and commands in this artifact.

## 1. Quick Cached Reproduction

Run from the repository root:

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

Expected outputs:

- `reproduced/tables/safe10_high_noise_comparison.csv`
- `reproduced/tables/safe10_high_noise_comparison.md`
- `reproduced/tables/full3d_high_noise_summary.csv`
- `reproduced/tables/causal_isolation_effects.csv`
- `reproduced/verification_summary.json`

The script verifies that:

- high-noise safe10 contains the Direct TD3, TD3 ablation, PPO-Penalty, PPO-Lagrangian, SAC-Lagrangian, Shielded SAC, and CG-RVC rows;
- every required high-noise method has five seed rows;
- CG-RVC reduces RMSE, applied action variance, dense safety violations, and Bellman-Lyapunov maximum relative to Direct TD3 in the cached high-noise comparison;
- the broader safe-RL comparators are present and finite;
- the causal-isolation summary contains the amplifier/source intervention effects used in the paper narrative;
- the Full3D high-noise white-vs-filtered summary is present.

On Windows, the equivalent smoke wrapper is:

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

The smoke wrapper runs cached reproduction plus a fast subset of unit tests. Use `-FullPytest` only for the longer training/simulation test suite.

## 2. Data-to-Paper Map

| Paper evidence | Cached source | Reproduction output |
| --- | --- | --- |
| safe10 high-noise TD3, ablation, and safe-RL table | `data/raw/safe10_formal_5seed/metrics_long.csv` | `reproduced/tables/safe10_high_noise_comparison.*` |
| PPO-Penalty / PPO-Lagrangian / SAC-Lagrangian / Shielded SAC coverage | `data/raw/safe10_formal_5seed/metrics_long.csv` and per-seed folders | `reproduced/verification_summary.json` |
| causal amplifier/source intervention | `data/raw/ci_causal_isolation/summary.json` | `reproduced/tables/causal_isolation_effects.csv` |
| certificate-metric attribution | `data/raw/metric_attribution_5seed/metric_attribution_table.csv` | copied/checked by the cached verifier |
| actor-augmented diagnostics | `data/raw/actor_augmented_diagnostics_5seed/actor_augmented_summary.csv` | checked by the cached verifier |
| Full3D high-noise white-vs-filtered diagnostic | `data/raw/full3d_5seed/high_noise_white_filtered_summary.csv` | `reproduced/tables/full3d_high_noise_summary.csv` |
| final paper and figures | `paper/main.pdf`, `paper/main.tex`, `paper/figures_v4_1/` | compiled PDF already included |

## 3. Full-Rerun Entry Points

The included raw CSV/JSON files are the authoritative low-cost reproduction surface. To rerun experiments instead of using cached results, use the entrypoints below and choose seeds/timesteps according to available compute.

Safe10 matched comparison and broader safe-RL baselines:

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

Causal-isolation intervention suite:

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

Metric attribution:

```bash
python summarize_metric_attribution.py --help
```

Full3D/UAV diagnostics:

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

Optional OmniSafe CPO adapter:

```bash
python -m pip install -r requirements-cpo-optional.txt
python run_omnisafe_cpo_baseline.py --help
```

## 4. Numerical Conventions

The cached verifier reports sample standard deviations for regenerated tables. Some legacy paper reports used population standard deviations in Chinese-language intermediate reports. The paper-level comparisons and verifier gates use method presence, seed coverage, finite values, means, and qualitative inequalities instead of requiring exact legacy standard-deviation formatting.

## 5. Known Limits

- This package includes raw seed-level logs, summaries, and plotting artifacts, but not large model checkpoint archives.
- Full retraining is stochastic and compute-dependent; cached reproduction is the primary reviewer path.
- The manuscript claims are local-surrogate and simulation-level claims. The package does not certify global nonlinear safety.
