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) diff --git a/CITATION.cff b/CITATION.cff index 5146be8..51bfee4 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,7 +7,7 @@ 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" license: BSD-3-Clause 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 diff --git a/README.md b/README.md index ce8e037..883d390 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: @@ -65,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) @@ -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 diff --git a/docs/evidence_map.md b/docs/evidence_map.md index a36fa38..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). 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 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. 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" }, 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, } 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():