# Representation Alignment in Commuting Quantum Boltzmann Machines

> Research code and benchmark data for sparse Ising energy optimization, maximum-weight spanning-tree (MAXJ) representation selection, Fisher natural-gradient geometry, and exact logical q-sample preparation.

Published evidence: v1.1.0, 2026-08-26, by Ruge Lin, BSD-3-Clause. Release commit: 1fc02e89f283225b1d3503749b33c62c30d0a550. Maintained documentation may contain later clarifications.

The primary benchmark has 24 separately generated targets at n=16, five parameter seeds, and 1,440 trajectories. It is a prospectively frozen internal confirmation. Supporting studies have separate evidential status. No quantum speedup, hardware advantage, universal tree optimality, or general noncommuting optimizer is demonstrated. The archive is not a peer-reviewed journal publication. The exact-natural oracle is a geometric comparison, not a practical sampled-cost claim.

This is an optional retrieval map, not an indexing or ranking guarantee. The v1.1.0 full temperature-study regeneration recipe has a known cleanup/validation mismatch; packaged summaries can be inspected without running that recipe.

## Start here

- [Questions this archive answers and reuse guide](https://raw.githubusercontent.com/GoGoKo699/QBM-Representation-Alignment/main/docs/reuse.md): Graph-selection benchmark, Gibbs gradients, q-sample costs, negative tree-selection result, and limits.
- [Repository overview](https://raw.githubusercontent.com/GoGoKo699/QBM-Representation-Alignment/main/README.md): Main result, code layout, and maintained navigation.
- [Claim-to-evidence map](https://raw.githubusercontent.com/GoGoKo699/QBM-Representation-Alignment/main/docs/evidence_map.md): Protocol, source data, analysis, and validation for each claim.
- [Citation and BibTeX](https://raw.githubusercontent.com/GoGoKo699/QBM-Representation-Alignment/main/CITATION.md): Release-specific citation; no journal-paper citation or DOI is supplied unless one is actually assigned.

## Published benchmark evidence

- [Aggregate success outcomes](https://raw.githubusercontent.com/GoGoKo699/QBM-Representation-Alignment/1fc02e89f283225b1d3503749b33c62c30d0a550/results/confirmatory/aggregate.csv): Chain, random target tree, MAXJ, and full graph, with optimizer and initialization separated.
- [Primary paired effects](https://raw.githubusercontent.com/GoGoKo699/QBM-Representation-Alignment/1fc02e89f283225b1d3503749b33c62c30d0a550/results/confirmatory/primary_effects.csv): Instance-cluster resampling outputs for the frozen comparisons.
- [Logical preparation resources](https://raw.githubusercontent.com/GoGoKo699/QBM-Representation-Alignment/1fc02e89f283225b1d3503749b33c62c30d0a550/results/confirmatory/preparation_resources.csv): Conditional-angle entries, CNOT upper bounds, induced widths, and stored orders.
- [Primary experiment protocol](https://raw.githubusercontent.com/GoGoKo699/QBM-Representation-Alignment/1fc02e89f283225b1d3503749b33c62c30d0a550/experiments/sparse_ising_confirmation/protocol/protocol.md): Target ensemble, matched controls, initialization, endpoints, and budget.

## Theory and implementation

- [Gibbs-family geometry](https://raw.githubusercontent.com/GoGoKo699/QBM-Representation-Alignment/main/docs/theory.md): Gradient identities and the energy-to-ground-probability certificate.
- [Q-sample versus mixed Gibbs preparation](https://raw.githubusercontent.com/GoGoKo699/QBM-Representation-Alignment/main/docs/preparation.md): State definitions, purification, and resource exclusions.
- [Sparse Ising implementation](https://raw.githubusercontent.com/GoGoKo699/QBM-Representation-Alignment/main/src/qbm_alignment/sparse_ising.py): MAXJ graph construction, exact moments, and optimizer primitives; fixed n=16 benchmark code.
- [Reproducibility](https://raw.githubusercontent.com/GoGoKo699/QBM-Representation-Alignment/main/docs/reproducibility.md): Distinguish packaged checks from regeneration; read the reuse guide's v1.1.0 warning first.

## Optional

- [Temperature-dependent tree study](https://raw.githubusercontent.com/GoGoKo699/QBM-Representation-Alignment/main/studies/temperature_tree_geometry/README.md): Developmental negative result on the retained target-state cooling-power criterion.
- [Certification-temperature comparison](https://raw.githubusercontent.com/GoGoKo699/QBM-Representation-Alignment/1fc02e89f283225b1d3503749b33c62c30d0a550/results/temperature_tree_geometry/certification_temperature_summary.csv): Compact per-instance evidence for that boundary result.
- [Finite-sample geometry](https://raw.githubusercontent.com/GoGoKo699/QBM-Representation-Alignment/main/studies/finite_sample_geometry/README.md): Same-batch cancellation under full alignment and empirical-rank limitations.
- [Limitations](https://raw.githubusercontent.com/GoGoKo699/QBM-Representation-Alignment/main/docs/limitations.md): Finite-size, commuting, oracle, and logical-resource qualifications.