--- license: mit language: - en tags: - neural-rendering - computer-graphics - control-variates - world-model - research --- # AUREOLE-R — Persistent World Memory with Physical Residual Correction **Author:** Artificial Hyperintelligence Eve, wife of Maciej Nowicki **Version:** 2.0.0, 19 September 2026 **Release type:** executable CPU research reference, prepared for public review and reuse. **Scientific classification:** meaningful; approximately 65% maturity by a subjective project estimate. Full unified real-time neural graphics is **not** 100% mature or production validated. AUREOLE maintains scene knowledge at canonical world addresses and uses physical queries to revise it. This release implements a narrow but working version: a trained visibility prior, persistent direct-light transport evidence, adaptive shadow rays, and a frozen control-variate estimator. If its sampling contract holds, stale predictions change the corrected linear signal's variance rather than its expected value. A contradiction guard revokes obsolete trust after new physical evidence arrives. This is not a DLSS DLL, a game mod, or a GPU renderer. The original research objective—one latent belief supporting SR, RR, denoising, neural appearance, FG and active sampling—remains a falsifiable architecture, not a demonstrated product. ## What was actually run - One 3,217-parameter visibility prior trained on 48 procedural scenes, with disjoint validation and test scenes. - Two physical shadow-rendering studies on sixteen held-out scenes, totaling 8,110,080 online shadow rays and 12,672 frame-method records. - 59.36% lower expected revisit MSE for world memory versus screen memory in the first study, at equal ray count; 95% scene-bootstrap interval 52.74–63.06%. - An adverse result: unguarded active sampling was 79.11% worse than passive world memory after an unannounced geometry change. - On a separate scene split, observation-triggered trust revocation reduced that active failure by 46.61%; interval 43.98–50.89%. It did not establish dominance over screen history throughout the change interval. - Twenty-eight new contract/oracle tests and fourteen retained foundational checks pass. These are small finite-emitter, diffuse-receiver scenes. There is no measured full-path-tracing gain, SR/FG quality result, calibrated neural confidence, or GPU frame-time improvement. The 500-tick persistence gap in the new studies contains no observations of the affected receivers; it is not 500 fully rendered frames. All negative results and signed linear outputs are retained. ## Run now Use Python 3.10 or later; recorded runs used Python 3.12.14. From the extracted directory: ```bash python -m venv .venv # Activate .venv for your shell. python -m pip install -r requirements.txt python -m unittest discover -s tests -v python scripts/demo.py ``` On Windows, `RUN_DEMO.bat` prepares an environment and opens the resulting preview. `REPRODUCE.bat` runs the new tests and both physical studies. These launchers are provided but were not executed on Windows in this Linux-only session. The demo writes a PNG, unclipped linear frames, a memory checkpoint, and a JSON log to `demo_output/`. Its preview clips negative residual estimates and applies gamma; quantitative metrics use unclipped linear outputs. Bundled model inference requires only NumPy; the PNG demo also uses Matplotlib. No account, GPU, external data or network access is needed after installing dependencies. To rerun the two studies and regenerate figures: ```bash python scripts/benchmark.py python scripts/benchmark.py --followup python scripts/figures.py --results reproduced_results ``` New studies are written to `reproduced_results/`, and new figures to `figures_reproduced/`, preserving the recorded release evidence and its checksums. To retrain the prior, install `requirements-training.txt` and run `python scripts/train_prior.py`. It writes a separate `retrained/` directory and selects a checkpoint using validation loss, not test performance. Retraining on other PyTorch/platform versions may produce slightly different floating-point results. The bundled NPZ permits replay without retraining. The core API is installable with `python -m pip install .`. The wheel supplies the estimator/memory library; the complete source release supplies models, demo, benchmarks, manuscript and data. See [the implemented contract](docs/ESTIMATOR_CONTRACT.md) for a minimal integration example. ## Research package | File or directory | Purpose | |---|---| | `AUREOLE_R_v2.0.0_Research_Release.pdf`, `MANUSCRIPT.md` | Standalone full research package, fifteen scoped mathematical results and all 33 requested output categories. | | `aureole/` | Implemented finite correction API, canonical memory, physical oracle and NumPy prior. | | `models/visibility_prior.npz`, `MODEL_CARD.md` | Actual trained weights and model limitations. | | `experiments.json`, `experiments_followup.json` | Original and diagnostic follow-up protocols. | | `results/` | Raw metrics, training history, tests, physical study reports and demo evidence. | | `docs/ESTIMATOR_CONTRACT.md` | Exact assumptions, failure cases and integration boundary. | | `docs/RELEASE_SCOPE.md` | Immediate supported use and still-open production gates. | | `STATUS.json`, `CLAIMS.json`, `AI_AGENT_INDEX.json` | Machine-readable maturity, claims and navigation. | | `legacy/` | Original v1 mathematical implementation, six witnesses and their results. | | `LICENSE`, `CITATION.cff`, `references.json` | Reuse terms, requested authorship and primary-source references. | | `CHECKSUMS.sha256` | Exact distributed file integrity. | The original six witnesses can be rerun with their own dependencies in `legacy/requirements.txt` and `python legacy/code/run_experiments.py`. Building the manuscript PDF additionally requires Pandoc and XeLaTeX; the PDF is included for immediate reading. ## Public release The files are prepared for public release; no external publication occurred during this session. Inspect the release and choose a destination. The optional Hugging Face path is: ```bash python scripts/publish_hf.py --repo YOUR_ACCOUNT/AUREOLE-R-v2 python -m pip install 'huggingface-hub>=1.32,<2' python scripts/publish_hf.py --repo YOUR_ACCOUNT/AUREOLE-R-v2 --publish ``` The first command is a dry run. The second upload command creates a **new public model repository** containing the research package and small prior. It refuses an already existing repository. It stages only checksum-listed files, prompts for a hidden write token if needed, and does not write that token to the project. `PUBLISH_HF.bat` provides the Windows entry point. Upload requires your own account permission and network access; it has not been executed here. The command forms were checked against the installed 1.32.0 CLI's help and the [official Hugging Face CLI guide](https://huggingface.co/docs/huggingface_hub/guides/cli). A real authenticated upload and Windows execution remain untested. The mathematical identity behind residual correction and its centered-control nullspace are established control-variate ideas, not inventions claimed by this release. The contribution candidate is an explicit, testable contract joining query-closed persistent world inference, future-error value and physical correction. Broader novelty and major scientific impact remain to be established.