From 4dbb2208f33bb10991ed24fd947d75740c654ecc Mon Sep 17 00:00:00 2001 From: Ruge Lin Date: Wed, 26 Aug 2026 11:47:10 +0800 Subject: [PATCH 01/12] Add v1.1.0 release notes --- CHANGELOG.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) create mode 100644 CHANGELOG.md diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..44d89d1 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,23 @@ +# Changelog + +## v1.1.0 — Expanded research archive + +Release date: 2026-08-26 + +- Added the exhaustive temperature-dependent tree-geometry supporting study, including its frozen protocol, source instances, compact canonical summaries, scientific report, and validation records. +- Recorded the negative operational result that retained target-state cooling power is not validated as a compressed-state tree-selection objective on the tested development corpus. +- Preserved the prospectively frozen weighted sparse-Ising `MAXJ` confirmation and its primary result tables unchanged. +- Improved the claim-to-evidence map, reader routes, classical graphical-model context, reproduction instructions, and study-level citation links. +- Clarified that the primary evidence is an internal confirmation on unseen, separately generated targets rather than an external replication. +- Updated package, citation, and machine-readable metadata to Version 1.1.0. + +Published release: [`v1.1.0`](https://github.com/GoGoKo699/QBM-Representation-Alignment/releases/tag/v1.1.0) + +## v1.0.0 — Initial public release + +Release date: 2026-08-25 + +- Published the prospectively frozen confirmation on 24 weighted sparse-Ising targets and 1,440 optimization trajectories. +- Included exact preparation-resource accounting, supporting geometry studies, raw and compact results, validation records, and the reproducible Python package. + +Published release: [`v1.0.0`](https://github.com/GoGoKo699/QBM-Representation-Alignment/releases/tag/v1.0.0) From 56eb054244eebbf7f74689929846a9fdc22aa6d9 Mon Sep 17 00:00:00 2001 From: Ruge Lin Date: Wed, 26 Aug 2026 11:48:40 +0800 Subject: [PATCH 02/12] Finalize v1.1.0 release and citation links --- README.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 868ec2c..c07aa8f 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,12 @@ # Representation Alignment in Commuting Quantum Boltzmann Machines [![tests](https://github.com/GoGoKo699/QBM-Representation-Alignment/actions/workflows/tests.yml/badge.svg)](https://github.com/GoGoKo699/QBM-Representation-Alignment/actions/workflows/tests.yml) +[![Release: v1.1.0](https://img.shields.io/badge/release-v1.1.0-blue.svg)](https://github.com/GoGoKo699/QBM-Representation-Alignment/releases/tag/v1.1.0) [![License: BSD 3-Clause](https://img.shields.io/badge/License-BSD_3--Clause-blue.svg)](LICENSE) [![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) -**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) +**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) · [release notes](CHANGELOG.md) · [cite](CITATION.md) This repository studies a concrete ansatz-design question: @@ -93,7 +94,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 -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. +For the complete archive, cite the published [`v1.1.0`](https://github.com/GoGoKo699/QBM-Representation-Alignment/releases/tag/v1.1.0) release. For the primary confirmed `MAXJ` result in its original release state, cite [`v1.0.0`](https://github.com/GoGoKo699/QBM-Representation-Alignment/releases/tag/v1.0.0). See [`CITATION.md`](CITATION.md) for copy-ready formats and exact-result guidance. ## Geometry From fc8f7a2b3372a2ab3b32a308cda8a68a5016333f Mon Sep 17 00:00:00 2001 From: Ruge Lin Date: Wed, 26 Aug 2026 11:48:53 +0800 Subject: [PATCH 03/12] Set v1.1.0 release date and citation metadata --- CITATION.cff | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/CITATION.cff b/CITATION.cff index 5146be8..6334905 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 and identify the release tag or commit; see CITATION.md for copy-ready formats." +message: "If you use the software, data, figures, protocols, or derived results, cite release v1.1.0 and identify any later commit used; see CITATION.md for copy-ready formats." title: "Representation Alignment in Commuting Quantum Boltzmann Machines" type: software authors: @@ -7,9 +7,9 @@ authors: given-names: Ruge affiliation: "The Hong Kong University of Science and Technology (Guangzhou)" version: 1.1.0 -date-released: 2026-08-25 +date-released: 2026-08-26 repository-code: "https://github.com/GoGoKo699/QBM-Representation-Alignment" -url: "https://github.com/GoGoKo699/QBM-Representation-Alignment" +url: "https://github.com/GoGoKo699/QBM-Representation-Alignment/releases/tag/v1.1.0" license: BSD-3-Clause abstract: >- Reproducible theory, experiments, and exact preparation-resource analyses for From 85555072cdc302d42c1238300201016fa65df76d Mon Sep 17 00:00:00 2001 From: Ruge Lin Date: Wed, 26 Aug 2026 11:49:17 +0800 Subject: [PATCH 04/12] Keep canonical repository URL in citation metadata --- CITATION.cff | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CITATION.cff b/CITATION.cff index 6334905..51bfee4 100644 --- a/CITATION.cff +++ b/CITATION.cff @@ -9,7 +9,7 @@ authors: version: 1.1.0 date-released: 2026-08-26 repository-code: "https://github.com/GoGoKo699/QBM-Representation-Alignment" -url: "https://github.com/GoGoKo699/QBM-Representation-Alignment/releases/tag/v1.1.0" +url: "https://github.com/GoGoKo699/QBM-Representation-Alignment" license: BSD-3-Clause abstract: >- Reproducible theory, experiments, and exact preparation-resource analyses for From 389c143f7f70a9d27e53ca6e7118bca9f0049202 Mon Sep 17 00:00:00 2001 From: Ruge Lin Date: Wed, 26 Aug 2026 11:49:34 +0800 Subject: [PATCH 05/12] Point citation guidance to published v1.1.0 release --- CITATION.md | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/CITATION.md b/CITATION.md index 0830564..fdf7af2 100644 --- a/CITATION.md +++ b/CITATION.md @@ -1,10 +1,10 @@ # How to cite this repository -If you use the software, data, figures, protocols, or derived results, cite the repository and identify the exact version or commit used. +If you use the software, data, figures, protocols, or derived results, cite the repository and identify the exact release or commit used. ## Recommended citation -> Lin, R. (2026). *Representation Alignment in Commuting Quantum Boltzmann Machines* (Version 1.1.0) [Computer software]. GitHub. https://github.com/GoGoKo699/QBM-Representation-Alignment +> Lin, R. (2026). *Representation Alignment in Commuting Quantum Boltzmann Machines* (Version 1.1.0) [Computer software]. GitHub. https://github.com/GoGoKo699/QBM-Representation-Alignment/releases/tag/v1.1.0 GitHub also displays a **Cite this repository** control generated from [`CITATION.cff`](CITATION.cff). @@ -16,16 +16,17 @@ GitHub also displays a **Cite this repository** control generated from [`CITATIO title = {Representation Alignment in Commuting Quantum Boltzmann Machines}, year = {2026}, version = {1.1.0}, - url = {https://github.com/GoGoKo699/QBM-Representation-Alignment}, + url = {https://github.com/GoGoKo699/QBM-Representation-Alignment/releases/tag/v1.1.0}, license = {BSD-3-Clause} } ``` ## 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. +- **Complete research archive:** cite the published [`v1.1.0`](https://github.com/GoGoKo699/QBM-Representation-Alignment/releases/tag/v1.1.0) release. It includes the prospectively frozen weighted sparse-Ising confirmation, all supporting studies, the later temperature-dependent tree boundary study, and the reviewer-facing citation and navigation improvements. +- **Primary confirmed `MAXJ` result in its original release state:** cite [`v1.0.0`](https://github.com/GoGoKo699/QBM-Representation-Alignment/releases/tag/v1.0.0). - **Pre-boundary-study state:** the branch `archive/confirmed-result-2026-08-25` preserves the repository immediately before the temperature-dependent supporting study was added. +- **A later unreleased state:** cite the most recent release and include the full commit SHA used. To record the exact commit of a local checkout, run: @@ -37,7 +38,11 @@ git rev-parse HEAD - 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/). -- For a particular table or figure, cite the repository and name the file path, release tag, or full commit SHA used. +- For a particular table or figure, cite the release and name the file path. Include a full commit SHA only when the cited state differs from the tagged release. + +## Release history + +See [`CHANGELOG.md`](CHANGELOG.md) for the scientific and repository-level contents of each release. ## Future paper citation From ec7c5f811955e91aa7e81b6f246a93dd11f86128 Mon Sep 17 00:00:00 2001 From: Ruge Lin Date: Wed, 26 Aug 2026 11:49:58 +0800 Subject: [PATCH 06/12] Pin reproducibility guidance to v1.1.0 release --- docs/reproducibility.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/reproducibility.md b/docs/reproducibility.md index 2399f56..b0f9cdf 100644 --- a/docs/reproducibility.md +++ b/docs/reproducibility.md @@ -15,13 +15,15 @@ The maintained dependencies are listed in `pyproject.toml` and `requirements.txt ## Record the exact version -Before running a calculation, record the checked-out commit: +The complete archive is published as GitHub release [`v1.1.0`](https://github.com/GoGoKo699/QBM-Representation-Alignment/releases/tag/v1.1.0). The primary confirmed `MAXJ` result in its original release state is preserved as [`v1.0.0`](https://github.com/GoGoKo699/QBM-Representation-Alignment/releases/tag/v1.0.0). + +Before running a calculation from a later checkout, record its 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). +Citation formats and version-selection guidance are in [`CITATION.md`](../CITATION.md). Release contents are summarized in [`CHANGELOG.md`](../CHANGELOG.md). ## Fast validation From be9f401f4c8954412126937c976ba97facc1b39f Mon Sep 17 00:00:00 2001 From: Ruge Lin Date: Wed, 26 Aug 2026 11:50:16 +0800 Subject: [PATCH 07/12] Publish v1.1.0 machine-readable release metadata --- llms.txt | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/llms.txt b/llms.txt index e4ad355..04cdc18 100644 --- a/llms.txt +++ b/llms.txt @@ -3,15 +3,17 @@ Repository URL: https://github.com/GoGoKo699/QBM-Representation-Alignment -Release metadata: -1.1.0 (2026-08-25), BSD-3-Clause +Published release: +v1.1.0 (2026-08-26), BSD-3-Clause +https://github.com/GoGoKo699/QBM-Representation-Alignment/releases/tag/v1.1.0 Primary question: 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, repository map, and citation route. +- README.md: confirmed result, commands, repository map, release notes, and citation route. +- CHANGELOG.md: release contents and scientific scope changes. - 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, classical tree comparison, and novelty boundary. @@ -52,5 +54,6 @@ Important boundaries: Citation: - 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. +- cite release v1.1.0 for the complete archive. +- cite release v1.0.0 for the primary confirmed MAXJ result in its original release state. +- identify the full commit SHA only when using a later unreleased state. From c0d4afac7304b5a6668cbfc80fb35749ccd6ce9f Mon Sep 17 00:00:00 2001 From: Ruge Lin Date: Wed, 26 Aug 2026 11:50:52 +0800 Subject: [PATCH 08/12] Guard v1.1.0 release metadata and links --- tests/test_repository_layout.py | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/tests/test_repository_layout.py b/tests/test_repository_layout.py index 1fe72fe..fe254ef 100644 --- a/tests/test_repository_layout.py +++ b/tests/test_repository_layout.py @@ -11,13 +11,16 @@ ROOT = Path(__file__).resolve().parents[1] EXPECTED_VERSION = "1.1.0" +EXPECTED_RELEASE_DATE = "2026-08-26" EXPECTED_URL = "https://github.com/GoGoKo699/QBM-Representation-Alignment" +EXPECTED_RELEASE_URL = f"{EXPECTED_URL}/releases/tag/v{EXPECTED_VERSION}" def test_canonical_public_files_exist(): required = [ ".gitattributes", ".github/workflows/tests.yml", + "CHANGELOG.md", "README.md", "CITATION.cff", "CITATION.md", @@ -58,6 +61,7 @@ def test_release_metadata_is_consistent(): citation = (ROOT / "CITATION.cff").read_text(encoding="utf-8") assert f"version: {EXPECTED_VERSION}" in citation + assert f"date-released: {EXPECTED_RELEASE_DATE}" in citation assert f'repository-code: "{EXPECTED_URL}"' in citation assert "license: BSD-3-Clause" in citation @@ -72,13 +76,17 @@ def test_citation_is_easy_to_find_and_versioned(): readme = (ROOT / "README.md").read_text(encoding="utf-8") citation = (ROOT / "CITATION.md").read_text(encoding="utf-8") cff = (ROOT / "CITATION.cff").read_text(encoding="utf-8") + changelog = (ROOT / "CHANGELOG.md").read_text(encoding="utf-8") assert "## How to cite" in readme assert "Cite this repository" in readme + assert EXPECTED_RELEASE_URL in readme assert f"Version {EXPECTED_VERSION}" in citation + assert EXPECTED_RELEASE_URL in citation assert "@software" in citation assert "v1.0.0" in citation assert "full commit SHA" in citation assert "see CITATION.md" in cff + assert f"## v{EXPECTED_VERSION}" in changelog def test_deep_entry_points_link_back_to_citation(): From ae48b099827ca12266eedc8bfafb42d3b75eaeb3 Mon Sep 17 00:00:00 2001 From: Ruge Lin Date: Wed, 26 Aug 2026 11:51:42 +0800 Subject: [PATCH 09/12] Validate v1.1.0 release metadata and changelog --- scripts/validate_repository.py | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/scripts/validate_repository.py b/scripts/validate_repository.py index 66fa457..bb7b719 100755 --- a/scripts/validate_repository.py +++ b/scripts/validate_repository.py @@ -15,7 +15,9 @@ ROOT = Path(__file__).resolve().parents[1] EXPECTED_NAME = "qbm-representation-alignment" EXPECTED_VERSION = "1.1.0" +EXPECTED_RELEASE_DATE = "2026-08-26" EXPECTED_URL = "https://github.com/GoGoKo699/QBM-Representation-Alignment" +EXPECTED_RELEASE_URL = f"{EXPECTED_URL}/releases/tag/v{EXPECTED_VERSION}" EXPECTED_LICENSE = "BSD-3-Clause" VALIDATION_RECORDS = { "confirmatory": ROOT / "results" / "confirmatory" / "validation.json", @@ -28,6 +30,7 @@ ".gitattributes", ".github/workflows/tests.yml", ".gitignore", + "CHANGELOG.md", "CITATION.cff", "CITATION.md", "CONTRIBUTING.md", @@ -91,6 +94,7 @@ def _validate_release_metadata() -> dict[str, object]: citation = (ROOT / "CITATION.cff").read_text(encoding="utf-8") assert _yaml_scalar(citation, "version") == EXPECTED_VERSION + assert _yaml_scalar(citation, "date-released") == EXPECTED_RELEASE_DATE assert _yaml_scalar(citation, "repository-code") == EXPECTED_URL assert _yaml_scalar(citation, "url") == EXPECTED_URL assert _yaml_scalar(citation, "license") == EXPECTED_LICENSE @@ -100,12 +104,19 @@ def _validate_release_metadata() -> dict[str, object]: assert "Copyright (c) 2026, Ruge Lin" in license_text readme = (ROOT / "README.md").read_text(encoding="utf-8") + citation_guide = (ROOT / "CITATION.md").read_text(encoding="utf-8") + changelog = (ROOT / "CHANGELOG.md").read_text(encoding="utf-8") assert EXPECTED_URL in readme + assert EXPECTED_RELEASE_URL in readme + assert EXPECTED_RELEASE_URL in citation_guide + assert f"## v{EXPECTED_VERSION}" in changelog assert "BSD 3-Clause License" in readme return { "package_name": EXPECTED_NAME, "version": EXPECTED_VERSION, + "release_date": EXPECTED_RELEASE_DATE, + "release_url": EXPECTED_RELEASE_URL, "repository_url": EXPECTED_URL, "license": EXPECTED_LICENSE, } From 0d88a8e4a6965b6ed1d105942c64d64403f7f0ad Mon Sep 17 00:00:00 2001 From: Ruge Lin Date: Wed, 26 Aug 2026 11:52:14 +0800 Subject: [PATCH 10/12] Refresh v1.1.0 packaged validation metadata --- results/repository_validation.json | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/results/repository_validation.json b/results/repository_validation.json index 3a76a29..36962cf 100644 --- a/results/repository_validation.json +++ b/results/repository_validation.json @@ -1,7 +1,7 @@ { "layout": { "container_local_paths": 0, - "file_count": 425, + "file_count": 426, "oversized_files": 0, "zero_byte_files": 0 }, @@ -103,6 +103,8 @@ "release_metadata": { "license": "BSD-3-Clause", "package_name": "qbm-representation-alignment", + "release_date": "2026-08-26", + "release_url": "https://github.com/GoGoKo699/QBM-Representation-Alignment/releases/tag/v1.1.0", "repository_url": "https://github.com/GoGoKo699/QBM-Representation-Alignment", "version": "1.1.0" }, From cf61fbb2293744dcd8ce7aa8e8d5d25551233f46 Mon Sep 17 00:00:00 2001 From: Ruge Lin Date: Wed, 26 Aug 2026 11:54:08 +0800 Subject: [PATCH 11/12] Use robust plain-language treewidth and MAXJ notation --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index c07aa8f..883d390 100644 --- a/README.md +++ b/README.md @@ -66,9 +66,9 @@ conditional angles: 31 CNOT upper count: 30 ``` -The full target graphs have treewidth $3$–$5$ and require 75–159 conditional angles, with median 131. +The full target graphs have treewidth between 3 and 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. +In source code and CSV files, `problem_tree` denotes the deterministic target-supported spanning tree obtained by maximizing edge weight $|J|$, abbreviated `MAXJ` in the documentation. - [Primary effects](results/confirmatory/primary_effects.csv) - [Aggregate outcomes](results/confirmatory/aggregate.csv) From 980140f824e8eb50d053d3d3f1f60efe0c316673 Mon Sep 17 00:00:00 2001 From: Ruge Lin Date: Wed, 26 Aug 2026 11:54:54 +0800 Subject: [PATCH 12/12] Align evidence-map terminology and release citation --- docs/evidence_map.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/evidence_map.md b/docs/evidence_map.md index 6bf61fb..ef283b5 100644 --- a/docs/evidence_map.md +++ b/docs/evidence_map.md @@ -6,7 +6,7 @@ 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`). +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 target-supported spanning tree that maximizes edge weight $|J|$ (`MAXJ`). | Evidence layer | Canonical location | |---|---| @@ -95,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 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). +Use [`CITATION.md`](../CITATION.md) for copy-ready APA-style and BibTeX entries. Cite release `v1.1.0` for the complete archive or `v1.0.0` for the primary confirmed `MAXJ` result in its original release state. Machine-readable metadata are in [`CITATION.cff`](../CITATION.cff).