From 608e30e83b27f904bc37467549a4281a888286c2 Mon Sep 17 00:00:00 2001 From: Ruge Lin Date: Wed, 26 Aug 2026 05:44:15 +0800 Subject: [PATCH 01/16] Clarify evidence hierarchy, reader routes, and citation guidance --- README.md | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 3f9dc9d..868ec2c 100644 --- a/README.md +++ b/README.md @@ -5,13 +5,15 @@ [![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. @@ -19,7 +21,7 @@ The work concerns a commuting, classically tractable sector of quantum Boltzmann ## 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 From 2b3deb7d930af5f9821fe5c06e2ceaf4e4ee0342 Mon Sep 17 00:00:00 2001 From: Ruge Lin Date: Wed, 26 Aug 2026 05:44:34 +0800 Subject: [PATCH 02/16] Clarify citation scope and discovery metadata --- CITATION.cff | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/CITATION.cff b/CITATION.cff index baca658..5146be8 100644 --- 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 From c0623cb3319b1a268c47ca50a2f8acbeaf11fda8 Mon Sep 17 00:00:00 2001 From: Ruge Lin Date: Wed, 26 Aug 2026 05:44:49 +0800 Subject: [PATCH 03/16] Make version-specific citation choices explicit --- CITATION.md | 20 +++++++++++++++----- 1 file changed, 15 insertions(+), 5 deletions(-) diff --git a/CITATION.md b/CITATION.md index 0e5a912..0830564 100644 --- 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 From 60370e97a759e50313e5390a2ce053fee24dd930 Mon Sep 17 00:00:00 2001 From: Ruge Lin Date: Wed, 26 Aug 2026 05:45:06 +0800 Subject: [PATCH 04/16] Clarify primary experiment terminology and entry points --- .../sparse_ising_confirmation/README.md | 26 +++++++++++++------ 1 file changed, 18 insertions(+), 8 deletions(-) diff --git a/experiments/sparse_ising_confirmation/README.md b/experiments/sparse_ising_confirmation/README.md index b1891a7..e363363 100644 --- a/experiments/sparse_ising_confirmation/README.md +++ b/experiments/sparse_ising_confirmation/README.md @@ -1,6 +1,6 @@ # Weighted sparse-Ising confirmation -This is the repository's primary independent experiment. It tests whether a target-informed sparse Gibbs representation improves finite-budget QBM optimization while retaining exact low-width preparation. +This is the repository's prospectively frozen primary experiment. Its protocol, seed commitments, graph rules, endpoints, and decision thresholds were fixed before a separately generated target ensemble was evaluated. It is an internal confirmation on unseen targets, not an external replication by another group. ## Design @@ -13,27 +13,37 @@ Twenty-four connected weighted 3-regular Ising targets at `n=16` are compared us The chain and both trees have the same treewidth, pair-term count, and parameter count. Optimizers and initializations follow the prespecified protocol in [`protocol/protocol.md`](protocol/protocol.md). +In source code and result tables, `problem_tree` denotes the deterministic maximum-absolute-coupling spanning tree, abbreviated `MAXJ` in the documentation. + Success is defined by ```text (expected energy - ground energy) / spectral gap <= 0.1 ``` -which certifies planted-ground-state probability at least 0.9 for the unique-ground-state targets. +which certifies ground-state probability at least 0.9 for the unique-ground-state targets. ## Main confirmed results -Under target-biased Adam, the maximum-weight problem tree improves success by 32.5 percentage points over the chain and by 18.33 points over the random target tree. Under exact natural gradient, it improves by 51.67 points over the chain. All three prespecified paired effects exceed their practical thresholds and have multiplicity-adjusted intervals above zero. +Under target-biased Adam, the maximum-weight problem tree improves success by 32.5 percentage points over the chain and by 18.33 points over the random target tree. Under the exact-natural oracle, it improves by 51.67 points over the chain. All three prespecified paired effects exceed their practical thresholds and have multiplicity-adjusted intervals above zero. + +The exact-natural oracle uses the exact Fisher pseudoinverse and exact Armijo energy evaluation. It is a geometric ceiling, not a practical sampled-cost claim. The full graph remains the trainability ceiling, while the problem tree retains exact width-one inference and a 31-angle q-sample description. ## Reproduction +From the repository root: + ```bash -python scripts/validate_seed_commitment.py -python scripts/analyze_results.py -python scripts/make_figures.py -python scripts/validate_experiment.py +python experiments/sparse_ising_confirmation/scripts/validate_seed_commitment.py +python experiments/sparse_ising_confirmation/scripts/analyze_results.py +python experiments/sparse_ising_confirmation/scripts/make_figures.py +python experiments/sparse_ising_confirmation/scripts/validate_experiment.py ``` -The raw trajectory logs and stored initial/final parameter arrays are under `results/`. Canonical compact tables are under the repository-level `results/confirmatory/` directory. +The raw trajectory logs and stored initial/final parameter arrays are under `results/`. Canonical compact tables are under the repository-level [`results/confirmatory/`](../../results/confirmatory/) directory. + +## Citation + +Cite the repository using [`CITATION.md`](../../CITATION.md). For the primary confirmed result, the preserved release is [`v1.0.0`](https://github.com/GoGoKo699/QBM-Representation-Alignment/releases/tag/v1.0.0); include a full commit SHA when citing a later repository state. From ddba76dd02876e7beee4997e50dceb52987ae51f Mon Sep 17 00:00:00 2001 From: Ruge Lin Date: Wed, 26 Aug 2026 05:45:30 +0800 Subject: [PATCH 05/16] Strengthen classical context and novelty boundary --- docs/research_context.md | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/docs/research_context.md b/docs/research_context.md index 67d4d99..e327a4d 100644 --- 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. From 5dcca27c6a05132d3a8286305d986f0a49bd009e Mon Sep 17 00:00:00 2001 From: Ruge Lin Date: Wed, 26 Aug 2026 05:45:47 +0800 Subject: [PATCH 06/16] Disambiguate confirmation language in scientific claims --- docs/scientific_claims.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/scientific_claims.md b/docs/scientific_claims.md index a80a193..23a69d2 100644 --- 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 From 8cecf14f884a8b758e05846a560bf8e5d0d670b0 Mon Sep 17 00:00:00 2001 From: Ruge Lin Date: Wed, 26 Aug 2026 05:46:06 +0800 Subject: [PATCH 07/16] Improve machine-readable scope and citation guidance --- llms.txt | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) diff --git a/llms.txt b/llms.txt index 0b2e553..e4ad355 100644 --- a/llms.txt +++ b/llms.txt @@ -3,7 +3,7 @@ Repository URL: https://github.com/GoGoKo699/QBM-Representation-Alignment -Release: +Release metadata: 1.1.0 (2026-08-25), BSD-3-Clause Primary question: @@ -11,19 +11,24 @@ How does the interaction graph of a commuting QBM affect finite-budget trainability and exact Gibbs/q-sample preparation? Canonical entry points: -- README.md: confirmed result, commands, and repository map. +- README.md: confirmed result, commands, repository map, and citation route. - docs/evidence_map.md: claim-to-protocol/data/code/validation navigation. - docs/scientific_claims.md: claim hierarchy and evidence boundaries. -- docs/research_context.md: established literature and novelty boundary. +- docs/research_context.md: established literature, classical tree comparison, and novelty boundary. - docs/statistical_analysis.md: paired instance-cluster bootstrap and Holm step-down rule. - docs/theory.md: aligned and partially aligned Gibbs geometry. -- experiments/sparse_ising_confirmation/: independent primary experiment. +- experiments/sparse_ising_confirmation/: prospectively frozen primary experiment. - results/confirmatory/: canonical compact result tables. - figures/: three main public figures. - studies/: supporting mechanism, estimator, and graph-selection-boundary studies. - studies/temperature_tree_geometry/: exhaustive temperature-dependent tree study. - results/temperature_tree_geometry/: compact tree-temperature summaries and validation. +Primary evidence status: +- the protocol, seed commitments, graph rules, endpoints, and decision thresholds were fixed before a separately generated weighted sparse-Ising target ensemble was evaluated; +- this is an internal confirmation on unseen targets, not an external replication; +- in source code and CSV tables, problem_tree denotes the deterministic maximum-|J| target-supported spanning tree (MAXJ). + Primary confirmed effects: - target-biased Adam, max-weight problem tree minus chain: +0.325; - target-biased Adam, max-weight problem tree minus random target tree: +0.183333; @@ -45,5 +50,7 @@ Important boundaries: - no adaptive tree-selection algorithm is validated. Citation: -- CITATION.md: copy-ready citation and BibTeX. +- CITATION.md: copy-ready citation, BibTeX, and version-selection guidance. - CITATION.cff: machine-readable GitHub citation metadata. +- use release v1.0.0 for the primary confirmed MAXJ result; +- for a later repository state, identify the matching release tag or full commit SHA. From f20b46b57e59ce72673e09ecbb1198a76cd10deb Mon Sep 17 00:00:00 2001 From: Ruge Lin Date: Wed, 26 Aug 2026 05:46:18 +0800 Subject: [PATCH 08/16] Make boundary-study reproduction and citation self-contained --- studies/boundary_geometry/README.md | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/studies/boundary_geometry/README.md b/studies/boundary_geometry/README.md index 0795ed2..742448e 100644 --- a/studies/boundary_geometry/README.md +++ b/studies/boundary_geometry/README.md @@ -12,10 +12,16 @@ This supporting study isolates a finite-budget optimizer failure in a fully alig ## Reproduce compact results +From the repository root: + ```bash -python scripts/analyze_results.py -python scripts/make_figures.py -python scripts/validate_study.py +python studies/boundary_geometry/scripts/analyze_results.py +python studies/boundary_geometry/scripts/make_figures.py +python studies/boundary_geometry/scripts/validate_study.py ``` -The twenty shared instances are stored once under `../../data/certificate_tight_instances/`. Raw and derived tables are stored under `../../results/boundary_geometry/`. +The twenty shared instances are stored once under [`data/certificate_tight_instances/`](../../data/certificate_tight_instances/). Raw and derived tables are stored under [`results/boundary_geometry/`](../../results/boundary_geometry/). + +## Citation + +Cite the repository using [`CITATION.md`](../../CITATION.md) and include the release tag or full commit SHA used. This is a supporting mechanism study, not a separate primary confirmation. From e53216bfae617419a3691e41b5dffbcf0a2de618 Mon Sep 17 00:00:00 2001 From: Ruge Lin Date: Wed, 26 Aug 2026 05:46:33 +0800 Subject: [PATCH 09/16] Make finite-sample study reproduction and citation self-contained --- studies/finite_sample_geometry/README.md | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/studies/finite_sample_geometry/README.md b/studies/finite_sample_geometry/README.md index 0cb0e9a..b03727e 100644 --- a/studies/finite_sample_geometry/README.md +++ b/studies/finite_sample_geometry/README.md @@ -16,10 +16,16 @@ The identity is not a generic claim about Fisher estimation. At mature wrong-sta ## Reproduce compact results +From the repository root: + ```bash -python scripts/analyze_results.py -python scripts/make_figures.py -python scripts/validate_study.py +python studies/finite_sample_geometry/scripts/analyze_results.py +python studies/finite_sample_geometry/scripts/make_figures.py +python studies/finite_sample_geometry/scripts/validate_study.py ``` -Raw and canonical tables are under `../../results/finite_sample_geometry/`. Saved boundary states are shared with `../boundary_geometry/` rather than duplicated. +Raw and canonical tables are under [`results/finite_sample_geometry/`](../../results/finite_sample_geometry/). Saved boundary states are shared with [`studies/boundary_geometry/`](../boundary_geometry/) rather than duplicated. + +## Citation + +Cite the repository using [`CITATION.md`](../../CITATION.md) and include the release tag or full commit SHA used. This is a supporting estimator study, not a separate primary confirmation. From 8ed07ef6d892d9b10ac2806fcc5df8d2740f836e Mon Sep 17 00:00:00 2001 From: Ruge Lin Date: Wed, 26 Aug 2026 05:46:46 +0800 Subject: [PATCH 10/16] Make partial-alignment study reproduction and citation self-contained --- studies/partial_alignment_geometry/README.md | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/studies/partial_alignment_geometry/README.md b/studies/partial_alignment_geometry/README.md index a02abb7..144264f 100644 --- a/studies/partial_alignment_geometry/README.md +++ b/studies/partial_alignment_geometry/README.md @@ -26,10 +26,16 @@ The omitted-cost covariance is state dependent, so the exact natural direction i ## Reproduce compact results +From the repository root: + ```bash -python scripts/analyze_results.py -python scripts/make_figures.py -python scripts/validate_study.py +python studies/partial_alignment_geometry/scripts/analyze_results.py +python studies/partial_alignment_geometry/scripts/make_figures.py +python studies/partial_alignment_geometry/scripts/validate_study.py ``` -Graphs are stored under `graphs/`; canonical tables are under `../../results/partial_alignment_geometry/`. The twenty shared instances are not duplicated here. +Graphs are stored under [`graphs/`](graphs/); canonical tables are under [`results/partial_alignment_geometry/`](../../results/partial_alignment_geometry/). The twenty shared instances are not duplicated here. + +## Citation + +Cite the repository using [`CITATION.md`](../../CITATION.md) and include the release tag or full commit SHA used. This is a supporting geometry study, not a separate primary confirmation. From d0cef6a0d125a6ba528af90b31dbaea10387f731 Mon Sep 17 00:00:00 2001 From: Ruge Lin Date: Wed, 26 Aug 2026 05:47:15 +0800 Subject: [PATCH 11/16] Clarify temperature-study status and citation route --- studies/temperature_tree_geometry/README.md | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/studies/temperature_tree_geometry/README.md b/studies/temperature_tree_geometry/README.md index b2c0780..60b2218 100644 --- a/studies/temperature_tree_geometry/README.md +++ b/studies/temperature_tree_geometry/README.md @@ -4,7 +4,7 @@ This supporting study asks a narrow follow-up question to the repository's confi > If a width-one tree is selected by the fraction of the target Gibbs cooling direction that it retains, does the preferred tree change with temperature, and does that change improve the compressed Gibbs state? -The study exhaustively evaluates all target-supported spanning trees for ten reused $n=8$ positive Exact-1-in-3-SAT instances. It is developmental evidence, not an additional independent confirmation. +The study exhaustively evaluates all target-supported spanning trees for ten reused $n=8$ positive Exact-1-in-3-SAT instances. It is developmental evidence, not an additional prospectively frozen confirmation. ## Result @@ -29,7 +29,6 @@ The supported conclusion is therefore negative and specific: This result does **not** weaken the repository's primary confirmed claim. The primary experiment shows that the deterministic maximum-absolute-coupling tree is an effective preparation-matched heuristic under its prospectively frozen optimization benchmark. This study asks a different question: whether another target-state geometric criterion can systematically improve upon that heuristic. - ## Evidence map - [Frozen protocol](protocol.md) @@ -42,12 +41,12 @@ This result does **not** weaken the repository's primary confirmed claim. The pr - [Mechanism correlation summary](../../results/temperature_tree_geometry/mechanism_correlation_summary.csv) - [Mechanism summary](../../results/temperature_tree_geometry/mechanism_summary.json) - [Detailed validation](../../results/temperature_tree_geometry/detailed_validation.json) -- [Independent validation](../../results/temperature_tree_geometry/independent_validation.json) +- [Independent numerical validation](../../results/temperature_tree_geometry/independent_validation.json) - [Repository validation record](../../results/temperature_tree_geometry/validation.json) ## Regenerate the study -Install the repository normally, then run the exhaustive calculation: +Install the repository normally, then run the exhaustive calculation from the repository root: ```bash python studies/temperature_tree_geometry/scripts/run_exhaustive_study.py --clean-results @@ -68,4 +67,8 @@ bash scripts/refresh_analysis.sh temperature - The instances were reused from earlier development work. - No adaptive rewiring experiment is claimed. - The post-hoc metric correlations are descriptive rather than frozen selection tests. -- A different on-manifold tree criterion would be a new hypothesis and would require independent confirmation. +- A different on-manifold tree criterion would be a new hypothesis and would require fresh confirmation on a new corpus. + +## Citation + +Cite the repository using [`CITATION.md`](../../CITATION.md) and include the release tag or full commit SHA used. When citing this boundary result, also name `studies/temperature_tree_geometry/` or the specific compact result file. From ddc091d90c5f1535a55b6a69b4d882d467d15b16 Mon Sep 17 00:00:00 2001 From: Ruge Lin Date: Wed, 26 Aug 2026 05:48:01 +0800 Subject: [PATCH 12/16] Refresh packaged repository validation record --- results/repository_validation.json | 26 +++++++++++++++++++++++--- 1 file changed, 23 insertions(+), 3 deletions(-) diff --git a/results/repository_validation.json b/results/repository_validation.json index 8f6805c..3a76a29 100644 --- a/results/repository_validation.json +++ b/results/repository_validation.json @@ -1,7 +1,7 @@ { "layout": { "container_local_paths": 0, - "file_count": 397, + "file_count": 425, "oversized_files": 0, "zero_byte_files": 0 }, @@ -79,19 +79,39 @@ "independent_batch_controls": 700, "sampled_trajectories": 3200, "status": "PASS" + }, + "temperature_tree_geometry": { + "detailed_validation": "detailed_validation.json", + "gate_results": { + "distinct_from_forward_kl": true, + "finite_temperature_evolution": true, + "projected_energy_relevance": false, + "useful_geometric_headroom": true + }, + "independent_validation": "independent_validation.json", + "instances": 10, + "mode": "compact supporting-study validation", + "scientific_outcome": "GEOMETRY_ONLY_DO_NOT_USE_COOLING_POWER_AS_OPERATIONAL_SELECTOR", + "source_verdict": "pt1a_verdict.json", + "spanning_trees": 20812, + "status": "PASS", + "study": "temperature-dependent tree geometry", + "temperature_points_per_instance": 61, + "tree_temperature_cells_recomputed_in_reference_run": 1269532 } }, "release_metadata": { "license": "BSD-3-Clause", "package_name": "qbm-representation-alignment", "repository_url": "https://github.com/GoGoKo699/QBM-Representation-Alignment", - "version": "1.0.0" + "version": "1.1.0" }, "status": "PASS", "validation_records": { "boundary_geometry": "results/boundary_geometry/validation.json", "confirmatory": "results/confirmatory/validation.json", "finite_sample_geometry": "results/finite_sample_geometry/validation.json", - "partial_alignment_geometry": "results/partial_alignment_geometry/validation.json" + "partial_alignment_geometry": "results/partial_alignment_geometry/validation.json", + "temperature_tree_geometry": "results/temperature_tree_geometry/validation.json" } } From 6a9e3dc9fb5d73c6e294ef783acca6a333fd4af9 Mon Sep 17 00:00:00 2001 From: Ruge Lin Date: Wed, 26 Aug 2026 05:48:26 +0800 Subject: [PATCH 13/16] Guard citation routes and packaged validation freshness --- tests/test_repository_layout.py | 34 +++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/tests/test_repository_layout.py b/tests/test_repository_layout.py index 2db129d..1fe72fe 100644 --- a/tests/test_repository_layout.py +++ b/tests/test_repository_layout.py @@ -1,5 +1,6 @@ from __future__ import annotations +import json import re from pathlib import Path @@ -37,6 +38,7 @@ def test_canonical_public_files_exist(): "figures/preparation_resources.png", "results/confirmatory/validation.json", "results/temperature_tree_geometry/validation.json", + "results/repository_validation.json", "studies/temperature_tree_geometry/README.md", "studies/temperature_tree_geometry/protocol.md", "studies/temperature_tree_geometry/scripts/validate_study.py", @@ -74,4 +76,36 @@ def test_citation_is_easy_to_find_and_versioned(): assert "Cite this repository" in readme assert f"Version {EXPECTED_VERSION}" in citation assert "@software" in citation + assert "v1.0.0" in citation + assert "full commit SHA" in citation assert "see CITATION.md" in cff + + +def test_deep_entry_points_link_back_to_citation(): + readmes = [ + "experiments/sparse_ising_confirmation/README.md", + "studies/boundary_geometry/README.md", + "studies/finite_sample_geometry/README.md", + "studies/partial_alignment_geometry/README.md", + "studies/temperature_tree_geometry/README.md", + ] + for relative in readmes: + text = (ROOT / relative).read_text(encoding="utf-8") + assert "## Citation" in text, relative + assert "CITATION.md" in text, relative + + +def test_primary_experiment_terms_are_unambiguous(): + text = (ROOT / "experiments/sparse_ising_confirmation/README.md").read_text(encoding="utf-8") + assert "not an external replication" in text + assert "`problem_tree`" in text + assert "ground-state probability" in text + assert "planted-ground-state probability" not in text + + +def test_packaged_repository_validation_is_current(): + payload = json.loads((ROOT / "results" / "repository_validation.json").read_text(encoding="utf-8")) + assert payload["status"] == "PASS" + assert payload["release_metadata"]["version"] == EXPECTED_VERSION + assert "temperature_tree_geometry" in payload["validation_records"] + assert payload["records"]["temperature_tree_geometry"]["status"] == "PASS" From 61e34408e8dda5247dfcf2f81d5167572e9a0d6a Mon Sep 17 00:00:00 2001 From: Ruge Lin Date: Wed, 26 Aug 2026 05:49:14 +0800 Subject: [PATCH 14/16] Clarify internal confirmation status in maintained protocol --- .../sparse_ising_confirmation/protocol/protocol.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/experiments/sparse_ising_confirmation/protocol/protocol.md b/experiments/sparse_ising_confirmation/protocol/protocol.md index 5ec1f00..9cc8234 100644 --- a/experiments/sparse_ising_confirmation/protocol/protocol.md +++ b/experiments/sparse_ising_confirmation/protocol/protocol.md @@ -2,11 +2,13 @@ ## Purpose -This experiment tests whether a problem-aligned spanning-tree QBM outperforms generic sparse controls of the same treewidth and pair-parameter count on an independent weighted sparse-Ising ensemble, and whether exact natural geometry preserves the same representation ordering. +This experiment tests whether a problem-aligned spanning-tree QBM outperforms generic sparse controls of the same treewidth and pair-parameter count on a separately generated weighted sparse-Ising ensemble, and whether exact natural geometry preserves the same representation ordering. The protocol, instance seeds, graph rules, optimizer settings, endpoint, and primary effect thresholds were fixed before the confirmatory instances were generated. Exact locked source files and hashes are preserved under [`frozen_source/`](frozen_source/). -## Independent problem family +This is a prospectively frozen internal confirmation on targets unseen during development. It is not an external replication by another research group. + +## Separately generated problem family Each target is @@ -65,7 +67,7 @@ Assign random priorities independent of target weights and take the resulting Kr ### Maximum-weight target-supported spanning tree -Take a maximum spanning tree with edge weights $|J_{ij}|$ and lexicographic tie-breaking. +Take a maximum spanning tree with edge weights $|J_{ij}|$ and lexicographic tie-breaking. In source code and result tables this representation is named `problem_tree`; the documentation also abbreviates it as `MAXJ`. ### Full target graph From bdd7cc2d6e02ec545f894c7ab9c6d0141adbb6d8 Mon Sep 17 00:00:00 2001 From: Ruge Lin Date: Wed, 26 Aug 2026 05:49:50 +0800 Subject: [PATCH 15/16] Add exact-version reproducibility guidance --- docs/reproducibility.md | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/docs/reproducibility.md b/docs/reproducibility.md index e6061f6..2399f56 100644 --- 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. From 72cb89db584a40231388c0e2315769fe4abe9fe9 Mon Sep 17 00:00:00 2001 From: Ruge Lin Date: Wed, 26 Aug 2026 05:50:33 +0800 Subject: [PATCH 16/16] Clarify evidence naming and citation anchors --- docs/evidence_map.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/evidence_map.md b/docs/evidence_map.md index 5908866..6bf61fb 100644 --- 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).