REPRODUCIBILITY.md

# Reproducing AUREOLE-R

Scientific release **3.0.0**; publication edition **3.0.0-hf.1**. The recorded evidence is bundled: no private dataset, external manuscript or previous conversation is needed. Installation may download public Python dependencies. The experiments generate procedural scenes locally.

## Obtain and verify an exact revision

Use this ZIP, or obtain the full repository with the Hugging Face CLI after publication:

```bash
hf download PureOne/AUREOLE-R-v3 --revision COMMIT_SHA --local-dir aureole-release
cd aureole-release
python scripts/publish_hf.py
```

Replace `COMMIT_SHA` with the actual immutable revision from the publication receipt or Hub history; it is a placeholder, not a claimed existing commit. The final command only checks hashes and performs no network requests. Download the complete repository: the prior and experiment artifacts are needed together.

## Environment

Python **3.10+**; recorded science used **Python 3.12.14 / NumPy 2.3.5 / CPU**. A virtual environment avoids changing global dependencies:

```bash
python -m venv .venv
```

Activate on Windows PowerShell with `.\.venv\Scripts\Activate.ps1`, in Windows Command Prompt with `.venv\Scripts\activate.bat`, or on Linux/macOS with `source .venv/bin/activate`. Then:

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

For a closer numerical reproduction on Python 3.12, pin `numpy==2.3.5`; package minimum ranges support installation but do not guarantee bitwise equality across versions, CPUs or operating systems. Matplotlib generates figures; PyTorch is required only for optional retraining. The finite reference does not use an RTX GPU.

## Smoke run and scientific acceptance

```bash
python scripts/demo_innovation.py
python scripts/validate_release.py
```

The demo writes to `innovation_demo/` and illustrates finite static-domain completion. Recorded evidence: 27,648 distinct physical terms, queried once each; exact completion after 18 visits, with six final zero-query frames. `validation_reproduced.json` reports the 15 scoped gates and executes the 58 scientific tests. Without `--require-replay`, it checks the bundled recorded replay evidence rather than rerunning both experiments.

## Reproduce the current experiments

Use one BLAS/OMP thread for timing comparability. On Linux/macOS set `OPENBLAS_NUM_THREADS=1` and `OMP_NUM_THREADS=1`; on Windows use `set OPENBLAS_NUM_THREADS=1` and `set OMP_NUM_THREADS=1` in Command Prompt. `REPRODUCE.bat` already sets these.

```bash
python scripts/benchmark_innovation.py
python scripts/benchmark_queries.py
python scripts/validate_release.py --require-replay
```

Outputs go to `innovation_reproduced/` and `queries_reproduced/`. The last command compares **298** non-timing quantities with bundled results and requires maximum difference below `1e-12`; the original recorded replay had zero difference. Timing is deliberately excluded from deterministic replay. New timings should name their hardware and include a clear cost boundary.

| Protocol | Frozen configuration | Recorded evidence |
|---|---|---|
| E10: known motion / sequential elimination | [experiments_innovation.json](experiments_innovation.json) | [Report](results_v3/innovation_report.json), [raw records](results_v3/innovation_raw.csv) |
| E11: shared spatial, prescribed-time and appearance queries | [experiments_queries.json](experiments_queries.json) | [Report](results_v3/queries_report.json), [raw records](results_v3/queries_raw.csv) |

[DATA_DICTIONARY.md](DATA_DICTIONARY.md) explains units, grouping and query accounting. Analytic references and diagnostic audits are excluded from the online policy budget and reported separately. Full experiments are CPU workloads; no wall-time promise is made for other machines.

## Retained v2 studies and optional training

```bash
python scripts/benchmark.py
python scripts/benchmark.py --followup
```

These reproduce the earlier residual-memory algorithm and its hidden-change guard study. Their event-access assumptions differ from E10. Do not combine their results into a single matched baseline without reading the protocols. See [historical manuscript](history/v2/MANUSCRIPT.md) and [model card](MODEL_CARD.md) for training, held-out scene IDs, optimization and the retained prior. Optional training dependencies are in `requirements-training.txt`; `python scripts/train_prior.py --help` exposes the training entry point. The frozen scientific weights stay in `models/visibility_prior.npz`.

## Publication packaging checks

```bash
python -m unittest discover -s publication_tests -v
python scripts/validate_publication.py --output publication_validation_local.json
```

These test the new uploader and release navigation, not graphics quality. They are reported separately from the 58 scientific tests. Default publication dry runs require only the Python standard library; actual upload uses the pinned `requirements-publish.txt`. The simulated publication tests use no network or credentials. Authenticated upload and execution of the `.bat` shell in Windows were not performed in the release environment.

## Preserve the evidence

Reproduction defaults write to new output directories. Keep `results/`, `results_v3/`, weights, protocols, original logs and paper unchanged. `scripts/build_manifest.py` is for reviewed release maintenance, not a command needed to reproduce science. Changing the source and regenerating hashes creates a new artifact; it does not reproduce the original checksummed release.