GoGoKo699 · GoGoKo699 · Aug 25, 2026 · Aug 25, 2026 · Aug 25, 2026 · Aug 25, 2026
diff --git a/CITATION.cff b/CITATION.cff
@@ -1,5 +1,5 @@
 cff-version: 1.2.0
-message: "If you use the software, data, figures, protocols, or derived results, cite this repository; see CITATION.md for copy-ready formats."
+message: "If you use the software, data, figures, protocols, or derived results, cite this repository and identify the release tag or commit; see CITATION.md for copy-ready formats."
 title: "Representation Alignment in Commuting Quantum Boltzmann Machines"
 type: software
 authors:
@@ -14,14 +14,18 @@ license: BSD-3-Clause
 abstract: >-
   Reproducible theory, experiments, and exact preparation-resource analyses for
   representation alignment in commuting quantum Boltzmann machines. The archive
-  includes an independently confirmed weighted sparse-Ising experiment and a
-  separate exhaustive supporting study that records a graph-selection boundary.
+  includes a prospectively frozen weighted sparse-Ising confirmation on a
+  separately generated target ensemble and a separate exhaustive supporting
+  study that records a graph-selection boundary.
 keywords:
   - quantum Boltzmann machine
-  - Gibbs state
+  - commuting Gibbs model
+  - Gibbs-state preparation
+  - sparse Ising optimization
   - representation alignment
   - natural gradient
-  - Ising model
+  - graphical models
+  - maximum spanning tree
   - treewidth
   - q-sample
   - reproducible research
diff --git a/CITATION.md b/CITATION.md
@@ -1,6 +1,6 @@
 # How to cite this repository
 
-If you use the software, data, figures, protocols, or derived results, cite the repository and identify the exact version used.
+If you use the software, data, figures, protocols, or derived results, cite the repository and identify the exact version or commit used.
 
 ## Recommended citation
 
@@ -21,13 +21,23 @@ GitHub also displays a **Cite this repository** control generated from [`CITATIO
 }
 ```
 
-## Citing an exact computational result
+## Which version to cite
+
+- **Primary confirmed `MAXJ` result:** cite the preserved [`v1.0.0`](https://github.com/GoGoKo699/QBM-Representation-Alignment/releases/tag/v1.0.0) release. It contains the prospectively frozen weighted sparse-Ising confirmation and its complete evidence chain.
+- **Expanded archive:** cite Version 1.1.0 together with a matching release tag when available. Otherwise include the full commit SHA so the cited state is unambiguous.
+- **Pre-boundary-study state:** the branch `archive/confirmed-result-2026-08-25` preserves the repository immediately before the temperature-dependent supporting study was added.
+
+To record the exact commit of a local checkout, run:
 
-For reproducibility, include a release tag, archived branch, or full commit SHA in addition to the citation.
+```bash
+git rev-parse HEAD
+```
+
+## Citing an exact computational result
 
-- The primary confirmed experiment is under [`experiments/sparse_ising_confirmation/`](experiments/sparse_ising_confirmation/), with canonical tables in [`results/confirmatory/`](results/confirmatory/).
+- The primary confirmation is under [`experiments/sparse_ising_confirmation/`](experiments/sparse_ising_confirmation/), with canonical tables in [`results/confirmatory/`](results/confirmatory/).
 - The later exhaustive graph-selection boundary study is under [`studies/temperature_tree_geometry/`](studies/temperature_tree_geometry/), with compact tables in [`results/temperature_tree_geometry/`](results/temperature_tree_geometry/).
-- The repository state immediately before the later supporting study is preserved on branch `archive/confirmed-result-2026-08-25`.
+- For a particular table or figure, cite the repository and name the file path, release tag, or full commit SHA used.
 
 ## Future paper citation
 

diff --git a/README.md b/README.md
@@ -5,21 +5,23 @@
 [![Python 3.10-3.13](https://img.shields.io/badge/Python-3.10--3.13-blue.svg)](pyproject.toml)
 [![Cite](https://img.shields.io/badge/Cite-CITATION.cff-blue.svg)](CITATION.md)
 
-**Start here:** [evidence map](docs/evidence_map.md) · [scientific claims](docs/scientific_claims.md) · [research context](docs/research_context.md) · [theory](docs/theory.md) · [statistics](docs/statistical_analysis.md) · [reproduce](docs/reproducibility.md) · [how to cite](CITATION.md)
+**Reader routes:** [confirmed result](#confirmed-result) · [claim-to-evidence map](docs/evidence_map.md) · [scope and nonclaims](docs/scientific_claims.md) · [research context](docs/research_context.md) · [reproduce](docs/reproducibility.md) · [cite](CITATION.md)
 
 This repository studies a concrete ansatz-design question:
 
 > How should the interaction graph of a commuting quantum Boltzmann machine be chosen when both finite-budget trainability and exact Gibbs/q-sample preparation matter?
 
-The central result is independently confirmed on 24 weighted sparse-Ising targets. At the same treewidth, interaction count, and parameter count, a target-supported spanning-tree representation trains substantially better than a generic chain. Selecting the tree by maximum absolute target-coupling weight improves further over a prespecified random target-supported tree. The full target graph remains the trainability ceiling, but requires a larger exact conditional-rotation description.
+The central result comes from a prospectively frozen confirmation on 24 separately generated weighted sparse-Ising targets. The protocol, instance-seed commitment, graph rules, endpoints, and decision thresholds were fixed before that target ensemble was generated. This is an internal confirmation on unseen targets, not an external replication by another group.
+
+At the same treewidth, interaction count, and parameter count, a target-supported spanning-tree representation trains substantially better than a generic chain. Selecting the tree by maximum absolute target-coupling weight improves further over a prespecified random target-supported tree. The full target graph remains the trainability ceiling, but requires a larger exact conditional-rotation description.
 
 The work concerns a commuting, classically tractable sector of quantum Boltzmann machines. It provides exact geometry, controlled optimization evidence, and explicit q-sample preparation resources. It does **not** claim quantum speedup.
 
 ![Confirmatory success by representation](figures/success_by_representation.png)
 
 ## Confirmed result
 
-The independent experiment uses:
+The prospectively frozen experiment uses:
 
 ```text
 instances:              24 connected weighted 3-regular Ising targets
@@ -65,6 +67,8 @@ CNOT upper count:    30
 
 The full target graphs have treewidth $3$–$5$ and require 75–159 conditional angles, with median 131.
 
+In source code and CSV files, `problem_tree` denotes the deterministic maximum-$|J|$ target-supported spanning tree, abbreviated `MAXJ` in the documentation.
+
 - [Primary effects](results/confirmatory/primary_effects.csv)
 - [Aggregate outcomes](results/confirmatory/aggregate.csv)
 - [Preparation resources](results/confirmatory/preparation_resources.csv)
@@ -89,7 +93,7 @@ GitHub reads [`CITATION.cff`](CITATION.cff) and exposes a **Cite this repository
 
 > Lin, R. (2026). *Representation Alignment in Commuting Quantum Boltzmann Machines* (Version 1.1.0) [Computer software]. GitHub. https://github.com/GoGoKo699/QBM-Representation-Alignment
 
-When citing a precisely reproduced result, include the release tag or full commit SHA used.
+For the primary confirmed `MAXJ` result alone, the preserved GitHub release is [`v1.0.0`](https://github.com/GoGoKo699/QBM-Representation-Alignment/releases/tag/v1.0.0). For the expanded Version 1.1.0 archive, cite a matching release tag when available; otherwise include the full commit SHA. See [`CITATION.md`](CITATION.md) for the exact choice.
 
 ## Geometry
 
@@ -121,13 +125,13 @@ $$
 
 Full alignment gives $R_G=0$, so the Fisher natural-gradient direction is the target coefficient direction. Partial representations retain a state-dependent omitted-cost covariance term. This explains why representations with the same width and number of parameters can have different trainability.
 
-See [theory](docs/theory.md). For established prior work and the novelty boundary, see [research context](docs/research_context.md).
+See [theory](docs/theory.md). For established prior work, the classical tree-approximation comparison, and the novelty boundary, see [research context](docs/research_context.md).
 
 ## Repository structure
 
 ```text
 src/qbm_alignment/                         shared implementation
-experiments/sparse_ising_confirmation/     primary independent experiment
+experiments/sparse_ising_confirmation/     prospectively frozen primary experiment
 studies/boundary_geometry/                 same-state optimizer replay
 studies/finite_sample_geometry/            sampled covariance geometry
 studies/partial_alignment_geometry/        partial-representation study
@@ -139,7 +143,7 @@ docs/                                      theory, preparation, formats, limits
 tests/                                     fast regression and identity tests
 ```
 
-The supporting studies are not additional primary claims. They document mechanisms, estimator behavior, and tested boundaries that motivated or contextualize the independent confirmation.
+The supporting studies are not additional primary claims. They document mechanisms, estimator behavior, and tested boundaries that motivated or contextualize the prospectively frozen confirmation.
 
 ## Installation
 

diff --git a/docs/evidence_map.md b/docs/evidence_map.md
@@ -6,6 +6,8 @@ This page gives reviewers, reusers, and first-time readers the shortest path fro
 
 **Claim.** At fixed treewidth, interaction count, and parameter count, a target-supported spanning-tree Gibbs representation trains better than a generic chain; selecting the spanning tree by maximum absolute target-coupling weight improves further over a prespecified random target-supported tree.
 
+The protocol and seed commitments were frozen before the separately generated target ensemble was evaluated. This is an internal confirmation on unseen targets, not an external replication. In code and result files, `problem_tree` denotes the maximum-$|J|$ spanning tree (`MAXJ`).
+
 | Evidence layer | Canonical location |
 |---|---|
 | Human-readable result | [`README.md`](../README.md#confirmed-result) |
@@ -76,7 +78,7 @@ python scripts/validate_repository.py
 python -m pytest -q
 ```
 
-Full independent-experiment validation:
+Full primary-experiment validation:
 
 ```bash
 python experiments/sparse_ising_confirmation/scripts/validate_experiment.py
@@ -93,4 +95,4 @@ See [`docs/reproducibility.md`](reproducibility.md) for the complete workflow.
 
 ## Citation
 
-Use [`CITATION.md`](../CITATION.md) for copy-ready APA-style and BibTeX entries. Machine-readable metadata are in [`CITATION.cff`](../CITATION.cff).
+Use [`CITATION.md`](../CITATION.md) for copy-ready APA-style and BibTeX entries and for choosing between release `v1.0.0`, a later release tag, or a full commit SHA. Machine-readable metadata are in [`CITATION.cff`](../CITATION.cff).
diff --git a/docs/reproducibility.md b/docs/reproducibility.md
@@ -13,6 +13,16 @@ python -m pip install -e ".[test]"
 
 The maintained dependencies are listed in `pyproject.toml` and `requirements.txt`.
 
+## Record the exact version
+
+Before running a calculation, record the checked-out commit:
+
+```bash
+git rev-parse HEAD
+```
+
+The primary confirmed `MAXJ` result is preserved in GitHub release `v1.0.0`. For the expanded Version 1.1.0 archive, use a matching release tag when available or record the full commit SHA. Citation formats and version-selection guidance are in [`CITATION.md`](../CITATION.md).
+
 ## Fast validation
 
 ```bash
@@ -72,7 +82,7 @@ The exhaustive run enumerates all target-supported spanning trees over 61 temper
 
 ## Frozen evidence
 
-`experiments/sparse_ising_confirmation/protocol/frozen_source/` preserves the exact locked protocol and generator source used before the independent instances were generated. These files intentionally retain their original wording and hashes. Maintained scripts outside that directory use the public repository layout.
+`experiments/sparse_ising_confirmation/protocol/frozen_source/` preserves the exact locked protocol and generator source used before the separately generated confirmatory targets were created. These files intentionally retain their original wording and hashes. Maintained scripts outside that directory use the public repository layout.
 
 The temperature-tree study separately preserves its protocol in [`studies/temperature_tree_geometry/protocol.md`](../studies/temperature_tree_geometry/protocol.md). It is a later development study and is not part of the primary frozen comparison.
 

diff --git a/docs/research_context.md b/docs/research_context.md
@@ -9,6 +9,7 @@ This repository studies a commuting, classically tractable sector of quantum Bol
 - Patel and Wilde, [“Natural gradient and parameter estimation for quantum Boltzmann machines,”](https://doi.org/10.1103/j8nb-by4l) *Physical Review A* **112**, 052421 (2025), developed thermal-state information matrices and natural-gradient estimation procedures.
 - Minervini, Patel, and Wilde, [“Evolved quantum Boltzmann machines,”](https://doi.org/10.1103/k2hw-r25g) *Physical Review A* **113**, 032427 (2026), introduced the broader evolved-QBM ansatz and its information geometry.
 - McClean *et al.*, [“Barren plateaus in quantum neural network training landscapes,”](https://doi.org/10.1038/s41467-018-07090-4) *Nature Communications* **9**, 4812 (2018), established the standard random-circuit barren-plateau phenomenon. This repository does not claim that phenomenon.
+- Chow and Liu, [“Approximating discrete probability distributions with dependence trees,”](https://doi.org/10.1109/TIT.1968.1054142) *IEEE Transactions on Information Theory* **14**, 462–467 (1968), established the forward-KL-optimal dependence-tree construction based on pairwise mutual information.
 - Peyrard *et al.*, [“Exact and approximate inference in graphical models: variable elimination and beyond,”](https://arxiv.org/abs/1506.08544) reviews variable elimination and the role of treewidth in exact inference.
 - Möttönen *et al.*, [“Transformation of quantum states using uniformly controlled rotations,”](https://arxiv.org/abs/quant-ph/0407010) provides the controlled-rotation machinery used in logical q-sample resource accounting.
 
@@ -18,11 +19,20 @@ The repository combines four elements:
 
 1. an exact decomposition of fully and partially aligned commuting Gibbs optimization geometry;
 2. matched sparse-representation controls at fixed treewidth, interaction count, and parameter count;
-3. a prespecified independent weighted sparse-Ising confirmation comparing a native chain, a random target-supported tree, a maximum-weight target-supported tree, and the full target graph;
+3. a prospectively frozen weighted sparse-Ising confirmation on separately generated targets, comparing a native chain, a random target-supported tree, a maximum-weight target-supported tree, and the full target graph;
 4. exact logical q-sample preparation accounting for every confirmatory representation.
 
 The maximum-weight spanning-tree algorithm itself is classical and is not claimed as new. The supported design result is empirical: retaining stronger target interactions improves finite-budget trainability over both a generic chain and a prespecified random target-supported tree while preserving width-one exact inference and q-sample preparation.
 
+## Relation to classical tree approximation
+
+The deterministic `MAXJ` rule and the Chow–Liu rule answer different questions:
+
+- Chow–Liu weights edges by pairwise mutual information and selects the tree minimizing forward information loss for a target probability distribution.
+- `MAXJ` weights target-Hamiltonian edges by $|J_{ij}|$ and is evaluated here for finite-budget optimization under a fixed Gibbs parameterization and for exact logical preparation cost.
+
+Accordingly, `MAXJ` is not a Chow–Liu estimator and is not claimed to be forward-KL optimal. The later temperature-dependent tree study explicitly compares cooling-power and forward-KL criteria and records their operational disagreement.
+
 ## Scope boundary
 
 The numerical calculations use exact classical enumeration at the studied sizes. The quantum relevance lies in thermal-ansatz design and coherent q-sample or purification preparation. See [scientific claims](scientific_claims.md) and [limitations](limitations.md) for the precise claim hierarchy.
diff --git a/docs/scientific_claims.md b/docs/scientific_claims.md
@@ -4,13 +4,17 @@
 
 For commuting quantum Boltzmann machines used to minimize sparse Ising costs, target-informed sparse interaction graphs can improve finite-budget trainability without increasing treewidth or parameter count.
 
-The independent weighted sparse-Ising experiment compares four representations:
+The prospectively frozen weighted sparse-Ising experiment compares four representations on a separately generated target ensemble:
 
 1. a native chain;
 2. a prespecified random target-supported spanning tree;
 3. a maximum-absolute-coupling target-supported spanning tree;
 4. the full target graph.
 
+The protocol, seed commitments, graph rules, endpoints, and decision thresholds were fixed before the target ensemble was generated. This is an internal confirmation on unseen targets, not an external replication by another group.
+
+In source code and result tables, `problem_tree` denotes the maximum-absolute-coupling target-supported spanning tree (`MAXJ`).
+
 The chain and both tree models have width one, fifteen pair interactions, and thirty-one parameters. Under target-biased Adam, the maximum-weight target tree exceeds the chain by 32.5 percentage points and the random target tree by 18.33 points. Under exact natural-gradient optimization, it exceeds the chain by 51.67 points. The paired effects and multiplicity-adjusted intervals are stored in [`results/confirmatory/primary_effects.csv`](../results/confirmatory/primary_effects.csv).
 
 ## Preparation-aware interpretation