Add paper reproduction catalogue and retained-data tools

.cursorrules

@@ -15,8 +15,11 @@ mechanics fidelity, differentiability boundaries, and reproducible examples.
 - Avoid in-place tensor mutations in autograd-sensitive code. Prefer
   out-of-place expressions, `torch.where`, `scatter_add`, sparse operators, and
   vectorized batch operations.
-- Do not add inverse, hybrid/deep-learning, paper-2, paper-4, private HPC, or
-  proprietary-solver artifacts to the public surface.
+- Keep paper-specific reproduction commands in `reproduction/paper1` with an
+  explicit input catalogue and separate replot and simulation-run status.
+  These commands preserve historical experiments rather than adding a general
+  inverse API. Keep unrelated inverse studies, hybrid/deep-learning research,
+  paper-2, paper-4, private HPC and proprietary-solver artifacts separate.
 - Keep public examples flat, runnable, and reproducible: `config.yaml`,
   optional fluent setup, standard manifests, CSV histories, lightweight visuals,
   and documented result bundles.

CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## Unreleased
 
+### Paper reproduction
+
+- Add a manuscript and supplement catalogue with separate records for figures,
+  tables and numerical statements.
+- Add portable retained-data checks and selected figure-generation commands.
+  Record data replotting separately from complete simulation reproduction.
+- Preserve the existing example folders and configuration schema. Large fields
+  and historical execution sources remain in the companion data archive.
+
 ### Experimental tetrahedral geometry
 
 - Add validated TET4 connectivity, orientation repair, volumes and scalar

README.md

@@ -222,6 +222,7 @@ print(result.history_names())
 |---|---|
 | `src/phast/` | Core PyTorch solver packages, mechanics/damage kernels, and CLI entry points. |
 | `examples/` | Runnable examples, their YAML inputs, and lightweight reference outputs. |
+| [`reproduction/paper1/`](reproduction/paper1/README.md) | Manuscript and supplement catalogue, retained-data checks and figure reproduction commands. |
 | `configs/` | Runnable benchmark decks, the YAML reference template and schema, and explicitly labelled reproducibility contracts. |
 | `docs/` | Sphinx documentation, capability matrices, tutorials, and user guides. |
 | `assets/` | Lightweight visual assets for repository documentation. |

docs/index.md

@@ -172,6 +172,7 @@ user_guide/yaml_workflow
 user_guide/results_visualization
 user_guide/learned_damage
 performance-reproducibility
+paper-reproduction
 ```
 
 ```{toctree}

docs/paper-reproduction.md

@@ -0,0 +1,48 @@
+# Paper reproduction
+
+The [paper reproduction directory](https://github.com/CEMS-Lab/PhAST/tree/main/reproduction/paper1)
+contains the manuscript and supplement catalogue and its commands. The
+catalogue follows the paper's order and uses stable figure and table labels.
+It also maps numerical statements in the text to their supporting studies.
+
+The existing example folders and YAML configurations remain the starting
+point for using PhAST. Each study records the relationship between its exact
+paper configuration and the related public example. Large numerical fields,
+meshes and historical execution sources belong in the companion archive.
+Its publication details will be added after the archive is complete.
+
+From the repository root, list the paper entries and check their mappings.
+
+```bash
+python reproduction/paper1/reproduce.py list
+python reproduction/paper1/reproduce.py check
+```
+
+With the retained data available locally, check its file hashes and regenerate
+the selected quasi-static holed-plate figure.
+
+```bash
+python reproduction/paper1/reproduce.py check --data /path/to/phast-paper-reproduction
+python reproduction/paper1/reproduce.py replot q2 --data /path/to/phast-paper-reproduction --output runs/paper-q2
+```
+
+The `forward` group covers standing-wave and damage-update-interval plots. The
+`inverse` group covers the selected scalar, cross-mesh, joint, finite-difference
+and memory plots. Install the separate plotting requirements described in the
+reproduction directory before running these commands. Output directories must
+be fresh and separate from the retained data.
+
+The commands check the archive manifest and document-edition hashes against
+the catalogue before using the files. Use a trusted data archive because the
+plotting adapters load its preserved experiment code.
+
+A checksum check establishes input integrity. Replotting checks the recorded
+data and figure-generation route. Complete simulation reproduction also
+requires the executed solver version, all numerical inputs, the environment
+and a verified run command. These statuses are recorded separately for each
+study, including inputs still being collected.
+
+This separation of the solver and experiment dependencies follows
+[Firedrake's reproduction guidance](https://www.firedrakeproject.org/zenodo.html).
+The problem-based ordering also follows the approach used in the
+[DOLFINx demonstrations](https://docs.fenicsproject.org/dolfinx/main/python/demos.html).

docs/user_guide/capability_matrix.md

@@ -66,6 +66,12 @@ For the current plasticity, cohesive interface, and PF-CZM technical-preview bou
 | Public inverse-analysis examples | Scaffold | `examples/inverse_problems_beta/` is a README-only landing zone until promoted inverse examples include configs, losses, retained lightweight outputs, and validation notes. |
 | General-purpose inverse-calibration framework | Unsupported | The public release does not provide a turnkey inverse-problem framework for arbitrary observations, priors, or optimizers. |
 
+Selected paper-specific inverse figures have separate
+[retained-data reproduction commands](../paper-reproduction.md). Their
+catalogue distinguishes replotting saved results from running the inverse
+calculation. These utilities preserve the scope of the recorded studies while
+the complete companion archive is prepared.
+
 ## Declarative YAML Workflows
 
 | Capability | Status | Public Statement |

examples/inverse_problems_beta/README.md

@@ -4,6 +4,11 @@
 possible future inverse-analysis example based on differentiable PhAST forward
 operations. It does not contain a runnable inverse benchmark.
 
+For the paper's selected inverse figures, use the separate
+[retained-data reproduction commands](../../reproduction/paper1/README.md).
+Their catalogue records plotting and simulation-rerun status individually.
+The companion numerical archive is being prepared.
+
 The current public release foregrounds forward phase-field fracture examples.
 Inverse workflows should be added here only when they include:
 

llms.txt

@@ -29,9 +29,10 @@ derived documentation, examples, or release material.
 - Completed runs expose machine-readable artifacts such as `run_manifest.json`,
   `run_lockfile.json`, `run_metadata.json`, `summary.json`, and CSV telemetry.
 - Use `phast.load_result(path)` for read-only result inspection.
-- Advanced inverse, hybrid/deep-learning, future paper-specific workflows, raw
-  HPC logs, proprietary files, and heavy trajectory stores are not part of the
-  public release surface.
+- Selected paper-specific retained-data checks and inverse replots are
+  documented in `reproduction/paper1`. General inverse and hybrid research,
+  raw HPC logs, proprietary files and heavy trajectory stores stay separate
+  from the public solver release.
 
 ## Quick Start For Agents
 
@@ -75,6 +76,9 @@ python -m phast explain-config examples/quasistatic/notched_holed_plate/config.y
 - [`examples/`](examples/) - curated public YAML examples and retained visual
   result bundles.
 - [`examples/README.md`](examples/README.md) - public example overview.
+- [`reproduction/paper1/README.md`](reproduction/paper1/README.md) - manuscript
+  and supplement catalogue, retained-data verification and bounded replots.
+  Historical experiment sources and large fields use a separate data archive.
 - [`configs/`](configs/) - benchmark decks, schemas, reference templates, and
   reusable configuration material.
 - [`docs/`](docs/) - Sphinx/user documentation source.

reproduction/paper1/README.md

@@ -0,0 +1,105 @@
+# Paper 1 Reproduction
+
+This directory indexes the PhAST manuscript and supplement. It provides a
+bounded retained-data route, not a claim that every paper simulation can
+currently be rerun.
+
+The **data record is in preparation**. No data DOI or download URL is assigned
+here. Large fields, historical execution sources and environments remain
+external to this repository.
+
+## Commands
+
+Run from the PhAST repository root. `list` needs no external data:
+
+```bash
+python reproduction/paper1/reproduce.py list
+python reproduction/paper1/reproduce.py check --data DIR
+python reproduction/paper1/reproduce.py replot q2 --data DIR --output OUTPUT_DIR
+python reproduction/paper1/reproduce.py replot inverse --data DIR --output OUTPUT_DIR
+python reproduction/paper1/reproduce.py replot forward --data DIR --output OUTPUT_DIR
+```
+
+`list` and `check` use only the Python standard library. Before replotting,
+create a separate plotting environment from the repository root:
+
+```bash
+python3.10 -m venv .venv-paper1-replot
+source .venv-paper1-replot/bin/activate
+python -m pip install -r reproduction/paper1/requirements-replot.txt
+```
+
+The retained-data checks were tested on macOS arm64 with Python 3.10.18 and
+the versions in `requirements-replot.txt`. This is a replot-only environment,
+not a reconstruction of historical simulation, CUDA or timing environments.
+Other platforms have not been verified for this route.
+
+Replace `DIR` with the local extracted `phast-paper-reproduction` data root,
+containing `manifest.json`, `document_identity.json`, `forward/`, `inverse/`,
+`verification/`, `sources/` and `shared/`. Use a different fresh `OUTPUT_DIR`
+outside the data tree for each replot. Data are supplied explicitly; these
+commands do not download a record or launch full simulations. Replotting
+executes selected archived Python code, so use only a trusted extraction.
+Hash matching binds the input identity; it does not sandbox that code.
+
+`check --data DIR` verifies the manifest and document identity against the
+catalogue's pinned SHA-256 hashes, then checks the listed payload sizes and
+hashes. Another self-consistent dataset is not a substitute for this audited
+edition. This checks selected-file integrity, not completeness of catalogue
+coverage, missing historical inputs, or full simulation reproduction.
+Replots write generated figures and verification records under the requested
+output directory without replacing the input data.
+
+## Current Status
+
+| Route | Recorded retained-data checks | Full simulation |
+| --- | --- | --- |
+| `q2` | Force curve and three damage panels regenerated; 200 saved fields checked | Pending |
+| `inverse` | Six figures regenerated from 487 exact inputs, covering scalar, six-start, cross-mesh, joint, memory and finite-difference studies | Pending; original inputs or environments remain incomplete for some studies |
+| `forward` | Standing-wave and subcycling figures regenerated; observed orders, selected terminal metrics and timing summaries checked | Pending; this command does not cover all forward studies |
+| Other studies | Inputs mapped, with individual restrictions in the catalogue | Pending or not applicable |
+
+These are preparation records, not certification of every metric or a new
+solver execution. Original perforated-plate native fields, five-mesh impact
+inputs, complete AT1 energy-integration states, historical execution identities
+and several study environments remain unresolved. Photograph reuse permission
+and reference-curve provenance are separate restrictions.
+
+The new terminal AT2 profile statement reports local/gradient contributions
+of **1.53/0.26**, versus **0.5/0.5** for the static profile. Its exact source
+SHA-256 is recorded under `prose_at2_terminal_profile`. The calculation script,
+mesh/state choice, integration region, quadrature and normalisation are pending;
+no independent analysis is claimed.
+
+## Catalogue
+
+[`catalogue.json`](catalogue.json) uses schema version 1, independently of the
+existing [public example contract](../../docs/user_guide/example_contract.md):
+
+- `data_identity` binds checks and replots to the tested frozen data extraction's
+  manifest and document-identity file hashes.
+- `documents` identifies the indexed manuscript and supplement by stable labels
+  and PDF SHA-256 hashes, not local paths.
+- `items` contains 38 figures/tables in document order: 14 figures and 8 tables
+  in the manuscript, followed by 14 figures and 2 tables in the supplement.
+  Each entry maps labels to studies and selected archive-relative assets.
+- `results` contains 36 grouped text mappings plus the pending AT2 profile
+  statement. A mapping is not independent numerical recomputation. Source edits
+  after the indexed edition require a final scope refresh before publication.
+- `studies` separates `replot_status`, `rerun_status`, `required_inputs` and
+  `unresolved_gaps`. `replot_group` is `q2`, `inverse`, `forward` or `null`;
+  `null` means no route in this CLI. Archive paths are relative to `--data`.
+
+`retained_data_checked` applies only to the bounded checks described above.
+`pending_full_run` means a fresh complete simulation has not been verified;
+`pending_inputs` additionally identifies missing or unresolved dependencies.
+Rights/provenance holds are not numerical failures. Empty `archive_assets` means
+a table is represented by study records or a composite is explicitly excluded;
+it does not imply completion. Asset paths preserve exact historical filenames.
+
+`related_example` names an existing public example, **not an identical paper
+run**. In particular, paper B1 relates to `B3_dynamic_sent`, paper B3 to
+`B7_dynamic_crack_branching_comsol`, and paper B4a-d to the `B6_perforated_*`
+family. Public example names, schemas and inputs are unchanged. The paper's
+inverse replot route does not promote the documentation-only public inverse
+example into a runnable inverse solver.