racah-py 0.1.0__tar.gz

racah_py-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,88 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+env:
+  CARGO_TERM_COLOR: always
+  RUSTFLAGS: -D warnings
+
+jobs:
+  fmt:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: rustup toolchain install stable --profile minimal --component rustfmt
+      - run: cargo fmt --all --check
+
+  clippy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: rustup toolchain install stable --profile minimal --component clippy
+      - uses: Swatinem/rust-cache@v2
+      - run: cargo clippy --all-targets --all-features
+
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: rustup toolchain install stable --profile minimal
+      - uses: Swatinem/rust-cache@v2
+      # dev-dependency wigner-symbols pulls gmp-mpfr-sys, which builds GMP
+      # from source on first run; rust-cache keeps the build cached across runs.
+      - run: cargo test --all-features
+      - run: cargo test --no-default-features
+
+  # Non-blocking coverage measurement for the README badge. Line coverage is
+  # auxiliary here — the golden/coherence guards are the primary correctness
+  # gates — so this job never fails the pipeline. It publishes a shields.io
+  # endpoint JSON to the `badges` branch, which the README badge reads via
+  # raw.githubusercontent.com.
+  coverage:
+    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - run: rustup toolchain install stable --profile minimal --component llvm-tools-preview
+      - uses: Swatinem/rust-cache@v2
+      - uses: taiki-e/install-action@cargo-llvm-cov
+      # One instrumented test run; both report formats are re-emitted from it.
+      - run: cargo llvm-cov --workspace --all-features --no-report
+      - run: cargo llvm-cov report --summary-only --json --output-path coverage.json
+      - run: cargo llvm-cov report --codecov --output-path codecov.json
+      - uses: codecov/codecov-action@v5
+        with:
+          files: codecov.json
+          fail_ci_if_error: false
+      - name: Publish badge JSON to badges branch
+        run: |
+          pct=$(jq -r '.data[0].totals.lines.percent' coverage.json)
+          msg=$(printf '%.1f%%' "$pct")
+          color=$(awk -v p="$pct" 'BEGIN{print (p<60)?"red":(p<80)?"yellow":"brightgreen"}')
+          jq -n --arg m "$msg" --arg c "$color" \
+            '{schemaVersion:1,label:"coverage",message:$m,color:$c}' > badge.json
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          # Single-file branch built from plumbing; history is disposable, force-push.
+          blob=$(git hash-object -w badge.json)
+          tree=$(printf '100644 blob %s\tbadge.json\n' "$blob" | git mktree)
+          commit=$(git commit-tree "$tree" -m "coverage badge: $msg ($GITHUB_SHA)")
+          git push -f origin "$commit:refs/heads/badges"
+
+  doc:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: rustup toolchain install stable --profile minimal
+      - uses: Swatinem/rust-cache@v2
+      - run: cargo doc --no-deps --all-features
+        env:
+          # Same KaTeX header as docs.rs (Cargo.toml [package.metadata.docs.rs]);
+          # space-separated flags compose in the one RUSTDOCFLAGS env var.
+          RUSTDOCFLAGS: -D warnings --html-in-header doc/katex-header.html

racah_py-0.1.0/.github/workflows/wheels.yml

@@ -0,0 +1,116 @@
+name: wheels
+
+# Python bindings (`racah-py`): abi3-py312 wheels for linux (x86_64, aarch64),
+# macos (arm64, x86_64), windows (x86_64), plus an sdist.
+#
+# Trusted publishing (OIDC, no tokens), same ladder as tenet-py's release.yml:
+# a `py-v*` tag push dry-runs the artifacts through TestPyPI; publishing a
+# GitHub release whose tag starts with `py-v` ships them to PyPI. The crate's
+# own `v*` releases never touch PyPI, so the two cadences stay independent.
+on:
+  push:
+    branches: [main]
+    tags: ["py-v*"]
+  pull_request:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  # Build the extension in place and run the Python smoke tests.
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: rustup toolchain install stable --profile minimal
+      - uses: Swatinem/rust-cache@v2
+      - run: pip install maturin pytest numpy
+      # `maturin develop` needs an activated virtualenv; the runner's Python is
+      # already isolated, so build the wheel and install it.
+      - run: maturin build --release --manifest-path racah-py/Cargo.toml --out dist
+      - run: pip install --no-index --find-links dist racah-py
+      - run: pytest racah-py/tests -q
+
+  wheels:
+    if: >-
+      startsWith(github.ref, 'refs/tags/py-v') ||
+      github.event_name == 'workflow_dispatch' ||
+      (github.event_name == 'release' && startsWith(github.event.release.tag_name, 'py-v'))
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          # linux aarch64 cross-compiles inside maturin-action's manylinux
+          # docker image; macos x86_64 cross-compiles from the arm64 runner.
+          # The crate is pure Rust, so stock toolchains suffice everywhere.
+          - runner: ubuntu-latest
+            target: x86_64
+          - runner: ubuntu-latest
+            target: aarch64
+          - runner: macos-14
+            target: aarch64
+          - runner: macos-14
+            target: x86_64
+          - runner: windows-latest
+            target: x64
+    runs-on: ${{ matrix.runner }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - uses: PyO3/maturin-action@v1
+        with:
+          target: ${{ matrix.target }}
+          # abi3-py312: one wheel per platform covers CPython >= 3.12.
+          args: --release --out dist --manifest-path racah-py/Cargo.toml
+          manylinux: auto
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wheels-${{ matrix.runner }}-${{ matrix.target }}
+          path: dist
+
+  # Unsupported platforms build from source with a Rust toolchain.
+  sdist:
+    if: >-
+      startsWith(github.ref, 'refs/tags/py-v') ||
+      github.event_name == 'workflow_dispatch' ||
+      (github.event_name == 'release' && startsWith(github.event.release.tag_name, 'py-v'))
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: PyO3/maturin-action@v1
+        with:
+          command: sdist
+          args: --out dist --manifest-path racah-py/Cargo.toml
+      - uses: actions/upload-artifact@v4
+        with:
+          name: sdist
+          path: dist
+
+  publish:
+    needs: [wheels, sdist]
+    if: >-
+      startsWith(github.ref, 'refs/tags/py-v') ||
+      (github.event_name == 'release' && startsWith(github.event.release.tag_name, 'py-v'))
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          path: dist
+          merge-multiple: true
+      - if: github.event_name == 'push'
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+      - if: github.event_name == 'release'
+        uses: pypa/gh-action-pypi-publish@release/v1

racah_py-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+/target
+Cargo.lock
+.DS_Store
+# Developer-local tenferro-rs override (see AGENTS.md); never committed.
+/.cargo/
+
+# Python bindings dev venv (racah-py); never committed.
+/racah-py/.venv/
+__pycache__/
+.pytest_cache/
+
+# LaTeX build artifacts (docs/theory.tex); the built theory.pdf IS committed.
+docs/*.aux
+docs/*.log
+docs/*.out
+docs/*.toc

racah_py-0.1.0/AGENTS.md

@@ -0,0 +1,90 @@
+# racah Agent Policy
+
+Design authority: the architecture, acceptance criteria, and reference-role
+map recorded in the upstream design discussion. Read them before any
+non-trivial change.
+
+## Boundaries
+
+- Pure representation mathematics only. No fusion-category trait vocabulary,
+  no sector identity types, no tensor-network concepts, and no dependency on
+  any tensor-network engine crate.
+- Base crate: exact SU(2) only; dependencies stay minimal (big-integer
+  arithmetic at most).
+- `cgc-gen` feature: all runtime generation (SU(N)/SO(N)/Sp(2N)) and every
+  dense-kernel dependency live behind this feature. Factorizations
+  (nullspace/QR/least-squares) and CGC contractions route through the
+  selected dense backend; hand-rolled numeric kernels are not accepted.
+- CGC are a legitimate public output of this crate; recoupling (F/R)
+  derivation and its caches live here, next to the gauge contract.
+
+## Acceptance criteria (every coefficient-affecting change)
+
+1. Combinatorial structure exact (integer/rational; no floats in
+   enumeration, multiplicities, or weights).
+2. Discrete data exact (duals, Frobenius–Schur phases, signs, basis order).
+3. Gauge fixing deterministic: pivot rules and sign conventions are part of
+   the specification; discrete gauge flips across runs/backends are defects.
+4. The gauge is a **frozen normative specification** (`docs/gauge.md`,
+   `docs/gauge_soN.md`): the documents are the authority, the code implements
+   them. A change that moves a coefficient value is a bug unless it ships as a
+   specification correction — spec edit, fingerprint `epoch` bump, CHANGELOG
+   breaking-change entry, regenerated `tests/gauge_golden.rs` values, one PR
+   (`docs/gauge.md`, "Status").
+5. Floating-point stages verification-gated: orthogonality, unitarity,
+   pentagon/hexagon checks run at generation time; violations are typed
+   errors, never silently degraded coefficients.
+
+## Guard inventory (every port PR)
+
+Reference guards that live *outside* the expression being ported are the
+recurring defect class tracked in issue #15 (dropped `@assert`s, type
+constraints, and unreachable-by-construction assumptions). Every port PR must:
+
+1. Enumerate, in the PR body, each guard on the reference path being ported —
+   `@assert`/`@check`, type or domain constraints, and invariants the reference
+   relies on as unreachable-by-construction.
+2. Map each to exactly one of: a typed error, a documented loud-panic invariant,
+   or an explicit N/A with justification. An unmapped guard blocks merge.
+3. Ensure every fast-path / special-case branch runs the same verification
+   gates as the general path, or prove those gates vacuous for that branch.
+
+## tenferro-rs dependency (cgc-gen)
+
+The `cgc-gen` feature depends on `tenferro-{linalg,cpu,runtime}` via a **git
+dependency pinned to an exact revision** (`Cargo.toml`), so a standalone CI
+checkout with no sibling `tenferro-rs` on disk resolves. Bumping the pinned
+`rev` is an ordinary reviewed commit (it can change coefficient values — see the
+gauge semver contract).
+
+To develop against an in-progress local `tenferro-rs` checkout, use a
+**developer-local, never-committed** override: a gitignored `.cargo/config.toml`
+with
+
+```toml
+[patch."https://github.com/tensor4all/tenferro-rs"]
+tenferro-linalg  = { path = "../tenferro-rs/crates/tenferro-linalg" }
+tenferro-cpu     = { path = "../tenferro-rs/crates/tenferro-cpu" }
+tenferro-runtime = { path = "../tenferro-rs/crates/tenferro-runtime" }
+```
+
+`.cargo/` is gitignored. CI and every reviewed build use the pinned git rev, not
+the patch.
+
+## Verification
+
+- Oracles are independent: reference-implementation outputs (WignerSymbols,
+  SUNRepresentations, GroupMath, QSpace after gauge alignment), checked-in
+  fixtures with provenance, and self-consistency identities. Values derived
+  from the code under test are not oracles.
+- **Reference-inventory rule.** Any "existing X" a spec/issue/PR relies on
+  (function, symbol, test, fixture) must be cited as `file::symbol` and
+  verified to exist before it is built on. Unverified references block merge.
+- **Warm-no-resweep rule.** Adding or touching a coefficient-generation API
+  requires a test proving a warm second call is served from cache without
+  re-sweeping. Consumer-only strands (they call an existing decomposition)
+  are exempt.
+- Fixture strands document normalization, OM-axis convention, and label
+  format in their header (`tools/README.md`, "Fixture and spec rules").
+- `cargo fmt` and `cargo test` (all feature combinations touched) before
+  every commit; fine-grained commits, each building and testing green.

racah_py-0.1.0/CHANGELOG.md

@@ -0,0 +1,290 @@
+# Changelog
+
+All notable changes to this crate are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project
+follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html) with the
+value/gauge rule noted below.
+
+## [Unreleased]
+
+## [0.2.0] - 2026-08-18
+
+**Value/gauge status of this release:** the one value-affecting change is the
+[#90](https://github.com/Ryo-wtnb11/racah/issues/90) base-case frame
+correction below — `SO(2r+1)`/`SO(2r)`/`Spin(N)` coefficient values move and
+`bcd_authority_fingerprint()` is now `epoch=2`; persisted B/D coefficients
+generated under `epoch=1` must be regenerated. `Sp(2r)` values are
+byte-identical, and the SU(2) and SU(N) fingerprints do not move. No
+coefficient, gauge, normalization or fingerprint change has landed since that
+`epoch=2` correction; everything else in this release is API surface
+(`racah::group`, `Spin(N)`, `from_dynkin_in`, the `BcdError` rename), docs,
+tests and CI.
+
+### Added
+
+- **Documentation reorganized into five layers** with a top-level index
+  ([`docs/README.md`](docs/README.md)). New task-oriented **User Guide**
+  (`docs/user-guide/`): getting started, representations, choosing a group,
+  fusion, Clebsch–Gordan, recoupling (F/R), and numerical behaviour/resources.
+  New `docs/developer/` index; the coefficient-cache audit and trade-off
+  documents and their raw JSONL moved there, marked non-user-facing. The README
+  is roughly 60% shorter: the provider contract, cache contract, layering
+  diagram, kernel routing and verification-strategy prose moved to the User
+  Guide, the crate rustdoc and the developer docs rather than being duplicated.
+  Rustdoc gained per-item examples and explicit **Returns** sections stating
+  array shapes, axis order and multiplicity-index meaning for the CGC / F / R
+  surfaces; `tests/doc_examples.rs` compiles and runs every code block in the
+  README and the guide. Documentation only — no API, convention, gauge or
+  coefficient value changes.
+
+- **`sun::Irrep::from_dynkin_in(&GroupId, &[i64])`** — the `A`-series
+  form-aware constructor, matching `bcd::Irrep::from_dynkin_in`
+  ([#87](https://github.com/Ryo-wtnb11/racah/issues/87)). `SU(N)/Z_k` (`k | N`)
+  and `PSU(N)` now restrict the admissible highest weights by `N`-ality; the
+  rule itself stays in `GroupId::admits` and `sun` does not restate it.
+  `from_dynkin` is unchanged and remains the simply connected `SU(N)`. **No
+  coefficient value, basis ordering, phase, normalization or fingerprint
+  moves**: a global form gates which weights may be requested, and every
+  admissible weight goes through the one Gelfand–Tsetlin engine and the same
+  (form-free) cache entry.
+- **`Spin(N)` — the spinor irreps of the `B`/`D` covers**
+  ([#54](https://github.com/Ryo-wtnb11/racah/issues/54), stage (b) of
+  [#87](https://github.com/Ryo-wtnb11/racah/issues/87)). `Irrep::from_dynkin_in`
+  takes a `GroupId`, so `GroupId::spin(N)` admits the spinor labels that
+  `SO(N)` rejects; their dimensions, duals, Frobenius–Schur indicators, fusion,
+  CGC and F/R are produced by the same bootstrap. Three parts:
+  - `bcd::Irrep` now stores the **doubled** ε-basis weight `2λ`, so a spinor's
+    half-integer highest weight is exact (`Irrep::two_partition`,
+    `Irrep::is_spinor`; `Irrep::partition` returns `Option`, `None` on a
+    spinor, and `Irrep::weight_multiplicities` likewise, with
+    `two_weight_multiplicities` always available).
+  - `bcd::spinor_seeds` — the second base case: the Clifford/Fock generator
+    seeds for `ω_r` (`B_r`) and `ω_{r-1}`, `ω_r` (`D_r`), gated by the same
+    exact `check_commutators`, specified in
+    [`docs/gauge_soN.md`](docs/gauge_soN.md) §16 and pinned by new
+    `tests/gauge_golden.rs` rows (`Spin(5)`, `Spin(6)`, `Spin(7)`, `Spin(10)`).
+  - The canonical-parent candidate set is **class-indexed** (§14.2): a tensor
+    irrep's parents are searched in the tensor sublattice only. **Every shipped
+    `SO(N)`/`Sp(2N)` coefficient is byte-identical** and the `bcd` `epoch` stays
+    at `1` at this stage; `bcd_authority_fingerprint()` gains no tag (§16.4
+    states why). (The separate #90 correction under **Changed** below is what
+    later moves the `bcd` epoch to `2`.)
+
+  Oracles in `tests/isomorphism.rs` and `tests/spin.rs`: `Spin(6) ≅ SU(4)` and
+  `Spin(5) ≅ Sp(4)` now agree on the **whole** weight lattice (dimensions,
+  duals, every ordered product, Frobenius–Schur), and `Spin(3) ≅ SU(2)` is the
+  form-aware low-rank redirect.
+
+- **`racah::group` — root datum plus global form** (stage (a) of
+  [#87](https://github.com/Ryo-wtnb11/racah/issues/87)). `RootSystem`,
+  `GlobalForm`, `CenterSubgroup`, `GroupId` with fallible named constructors
+  (`GroupId::su/su_quotient/psu/sp/psp/spin/so/pso/half_spin_plus/
+  half_spin_minus`), and `GroupId::admits(&[i64])` — the central-character
+  predicate that says which dominant weights are representations of which
+  connected compact group. Ungated (pure integer arithmetic). `bcd`'s spinor
+  rejection is now the one call site of that predicate, and
+  `Series::root_system(r)` is the single bridge to the label-lattice type.
+  Conventions pinned in [`docs/references.md`](docs/references.md): the
+  `D_r`-odd `Z4` generator `[ω_r]`, and the `D_r`-even half-spin forms named
+  by the class they retain. **No coefficient value changes**; no `epoch` moves.
+
+- **Frozen gauge specification.** [`docs/gauge.md`](docs/gauge.md) and
+  [`docs/gauge_soN.md`](docs/gauge_soN.md) are declared **normative**: the
+  documents are the authority and the code implements them. `docs/gauge.md` also
+  now specifies the base SU(2) conventions (§12) and marks the rules the
+  implementation fixes only implicitly. **No coefficient value changes** from
+  this declaration itself; all three `epoch` tags stayed at `1` at this stage
+  (the #90 correction below is the release's one epoch move). What changes is the meaning of the authority
+  fingerprints: they are now **specification versions**, moving only on a
+  specification correction (spec edit + `epoch` bump + CHANGELOG breaking-change
+  entry + regenerated goldens, in one PR), never because a refactor moved a
+  value. A refactor that moves a value is now a bug by definition.
+  ([#84](https://github.com/Ryo-wtnb11/racah/issues/84))
+- **`tests/gauge_golden.rs`**: the in-repo gauge tripwire — a small committed
+  table of SU(3) CGC (including the OM = 2 adjoint vertex), SU(3) F, and signed
+  SO(5)/Sp(4) CGC and F values, asserted at `1e-12` in the default `cgc-gen` test
+  run. It covers the drift the external oracles miss by default: SU(3) F symbols
+  are otherwise pinned only by an `#[ignore]`d heavy table oracle, and the QSpace
+  B/C/D anchor compares an isotypic projector that is blind to the coupled-side
+  gauge. It is a drift detector, not an oracle.
+- **`racah-py`**: PyO3/maturin Python bindings for the SU(N) surface, built as
+  a workspace member with `cgc-gen` always on. Import name `racah`,
+  distribution `racah-py`; abi3-py312 wheels are built by the `wheels`
+  workflow. See [`racah-py/README.md`](racah-py/README.md).
+- **Coverage badges** — self-hosted llvm-cov badge branch plus Codecov
+  integration ([#93](https://github.com/Ryo-wtnb11/racah/pull/93)).
+- **`CITATION.cff`**, README badges and a Citation section
+  ([#92](https://github.com/Ryo-wtnb11/racah/pull/92)).
+
+### Changed
+
+- **BREAKING (error variant renamed): `BcdError::SpinorLabel` is now
+  `BcdError::NotAdmissible { group: GroupId, dynkin: Vec<i64> }`**
+  ([#87](https://github.com/Ryo-wtnb11/racah/issues/87)). The old name was
+  mathematically misleading: the variant is returned whenever
+  `group.admits(dynkin)` is false, and `PSp(2r)`, `PSO(2r)` and the two
+  half-spin forms all reject *non-spinor* weights through it — `C_r` has no
+  spinor sector at all. It now carries the rejecting `GroupId` rather than just
+  the `Series`. Pre-1.0, no deprecation shim: the variant is renamed outright,
+  and the meaning is exactly "a dominant integral highest weight of the cover
+  that is not a genuine representation of the selected global form", kept
+  distinct from the invalid-label, rank, excluded-rank, generation and
+  verification errors.
+- `SunError` gains `NotAdmissible`, `UnsupportedRootSystem` and
+  `LabelRankMismatch` for the new `sun::Irrep::from_dynkin_in` guards.
+
+- **BREAKING (gauge specification correction, B/D coefficient values move):
+  the B/D defining-rep base case is re-framed into the sweep's descending-weight
+  order; `bcd_authority_fingerprint()` moves to `epoch=2`**
+  ([#90](https://github.com/Ryo-wtnb11/racah/issues/90)). The QSpace-ported
+  defining seed was stored in QSpace's `Setup_*` state order while every
+  rediscovery of the same irrep inside a product was produced in the sweep's
+  descending-weight order, and `assemble_cgc` exempted base cases from both the
+  coherence guard and the intertwiner alignment — so the two frames were mixed
+  silently inside a contraction. Measured on `epoch=1`: the `B_2` vector
+  pentagon residual `0.285_239_560_970_874_55`, the `D_3` vector pentagon
+  residual `0.129_099_444_873_580_74`, and `B_2 F(1,v,v;adj|v,adj) = 0.0` where
+  unitarity forces `1.0`. The seed is now put through one §1–§8 sweep pass over
+  its own carrier before it enters the catalog (`docs/gauge_soN.md` §14.2,
+  "Base-case frame"), so there is one frame convention in the crate, and the
+  base-case exemption is **removed**: the coherence guard and the alignment now
+  bind every block, base cases included, which makes this defect class
+  impossible to reintroduce silently. Consequences for consumers: persisted
+  `SO(2r+1)`/`SO(2r)`/`Spin(N)` coefficients derived under `epoch=1` are stale
+  and must be regenerated; `Sp(2r)` (the `C` family) values are **unchanged** —
+  `Setup_SpN`'s order was already descending-weight, which is why the C gates
+  always closed. `tests/gauge_golden.rs` is regenerated for the moved entries.
+
+- **`BcdError::ExcludedRank::redirect` is form-aware** (stage (b) of #87, Q3):
+  the low-rank isomorphism is an isomorphism of *groups*, so `Spin(3)` now
+  redirects to `"use SU(2) instead"` while `SO(3)` redirects to `"use SU(2)
+  with integer j only instead"` (likewise `Spin(4)`/`SO(4)`). Diagnostic strings
+  only; no coefficient value changes.
+- **`bcd::Irrep::partition` returns `Option<Vec<i64>>`** and
+  `bcd::Irrep::weight_multiplicities` returns `Option<…>`, both `None` on a
+  spinor irrep, whose ε-basis weights are half-integers. The always-exact
+  doubled forms are `two_partition` / `two_weight_multiplicities`.
+- Docs: replaced the "no label ceiling" absolute with the machine-word label
+  bounds that report a typed overflow, and corrected "selectable dense
+  backend" to the single Tenferro seam with no public backend-selection API.
+- **`wheels` workflow: full abi3 wheel matrix + PyPI trusted publishing for
+  `racah-py`** ([#103](https://github.com/Ryo-wtnb11/racah/pull/103)): linux
+  x86_64/aarch64, macOS arm64/x86_64, windows x86_64, plus an sdist. Publishing
+  is gated on `py-v*` tags/releases, so the crate's own `v*` releases never
+  touch PyPI. `racah-py` itself is unversioned by this release (stays 0.1.0,
+  `publish = false` for crates.io) and releases separately.
+
+## [0.1.1] - 2026-08-12
+
+This release publishes the generated-provider dependency closure against the
+published Tenferro 0.3.0 registry line.
+
+### Changed
+
+- Use registry `tenferro-* = "0.3.0"` dependencies for `cgc-gen`.
+- Document crates.io installation and the published feature configuration.
+
+Generated-provider (`cgc-gen`) observability and convention-identity surface
+(issue [#47](https://github.com/Ryo-wtnb11/racah/issues/47)). This whole surface
+is **unstable: shape may change while the generated-provider contract is
+negotiated** — Cargo features cannot express instability tiers, so the rustdoc
+labels plus issue #47 are the ledger.
+
+### Added
+
+- **Per-tier coefficient-cache trim**: `trim_to(CoefficientCacheTier, bytes)`
+  releases the oldest FIFO prefix of exactly one tier and reports its
+  linearization-point charged-entry accounting in `CacheTrimReport`. It is a
+  process-global single-owner lifecycle operation; it preserves the one-shot
+  cache budget and makes no allocator/RSS release claim.
+
+- **One-shot coefficient-cache budgets**: `CoefficientCacheBudgets`,
+  `CoefficientCacheTier`, `configure_cache_budgets`, and `cache_budgets` let
+  applications shrink independent process-local tier caps before first use.
+  Zero retains no entry; reset preserves the selected policy.
+
+- **Shared SU(N) product tier** (`cgc-gen`, issue #59): exact
+  `directproduct` decompositions are retained once as sorted shared channels
+  under an order-normalized irrep pair. The unchanged public API reconstructs
+  its `BTreeMap`; Racah-private multiplicity and channel consumers use the
+  shared value directly. The tier is bounded at 256 entries and a 128 KiB
+  retained-charge backstop, sized from the checked-in collector and a
+  downstream SU(3)+SU(4) Generic HomSpace/topology probe.
+- **Generated-tier cache stats** (`cgc-gen`): `generated_cache_stats() ->
+  GeneratedCacheStats` (`#[non_exhaustive]`, reusing `TierStats`) reports the
+  five generated tiers (SU(N) product / CGC / F, B/C/D CGC / F) per-tier plus a
+  field-wise `total()`. `GeneratedCacheStats` `bytes` fields are conservative
+  retained charges of cache-owned entries, with container scaffolding,
+  allocator/RSS costs, external clones, and returned values excluded.
+  `GENERATED_CACHE_MAX_BYTES` (640 MiB + 128 KiB) is the documented aggregate
+  retained-charge cap, tied to the per-tier caps by a `const` assertion.
+  Two-layer cache story: base = `BASE_CACHE_MAX_BYTES`, generated =
+  `GENERATED_CACHE_MAX_BYTES`, whole = the documented sum; no cross-feature
+  constant. `reset()` clears the generated tiers alongside the base ones.
+- **Generated authority fingerprints** (`cgc-gen`):
+  `sun::sun_authority_fingerprint()` and `bcd::bcd_authority_fingerprint()`
+  (`&'static [u8]`). Their contract is weaker than the exact SU(2) fingerprint —
+  equal fingerprints identify the same convention, generation pipeline, and
+  tolerance policy, but do not imply byte-identical values or independently prove
+  numerical agreement (verification gates and oracles own that). Epochs are
+  per-family and independent. Backend identity is excluded by design.
+- **Backend structural-identity gate** (`cgc-gen`, D2): a test asserting the
+  discrete/structural generation outputs are a function of the convention alone
+  (stable across independent in-process runs), the single-backend reduction of
+  the cross-backend gate.
+
+## [0.1.0] - 2026-07-24
+
+First tagged release of the v0 scope: the full representation-theory
+coefficient set for SU(2), SU(N), SO(N), and Sp(2N), computed on demand with no
+label ceiling.
+
+### Added
+
+- **Exact SU(2)** (default build, no features): 3j, 6j, Clebsch–Gordan, and
+  F / R / Frobenius–Schur symbols in closed-form big-rational arithmetic with a
+  single final rounding. Dependency-light (`num-bigint` / `num-rational` /
+  `num-traits` only).
+- **Generated SU(N)** (`cgc-gen` feature): the Gelfand–Tsetlin pipeline — CGC,
+  F, and R with outer-multiplicity indices.
+- **Generated SO(N) / Sp(2N)** (`cgc-gen` feature): the generator-bootstrap
+  pipeline over the B/C/D Cartan series — CGC, F, and R.
+- **Base SU(2) provider contract:**
+  - `su2_authority_fingerprint()` — opaque bytes identifying the value-fixing
+    convention set; compared by equality, changed only on a value-affecting
+    breaking release.
+  - Checked representation surface — `Su2Irrep` (with `dj` / `dim` / `dual` /
+    `fusion`), `Su2Fusion`, `Su2Error` / `AdmissibilityViolation`, and the
+    `wigner_3j_checked` / `wigner_6j_checked` / `clebsch_gordan_checked` /
+    `su2_f_symbol_checked` / `su2_r_symbol_checked` functions. Additive over the
+    infallible zero-convention functions; distinguishes `Ok(0)` (an admissible
+    accidental zero) from `Err(NotAdmissible)` (a forbidden coupling).
+  - Cache resource contract — `BASE_CACHE_MAX_BYTES` static partition over the
+    three base tiers, `base_cache_stats()` / `BaseCacheStats` / `TierStats`
+    per-tier statistics (entries, bytes, hits, misses, evictions), and
+    single-owner `reset()`.
+- **Self-check / oracle batteries**, shipped as public API and used as
+  generation gates: CGC orthogonality, F-unitarity, R-orthogonality, and the
+  pentagon / hexagon identities.
+
+### Notes
+
+- Not published to crates.io: the `cgc-gen` feature depends on the unpublished
+  `tenferro-rs`, so a crates.io release is blocked upstream. The git dependency
+  is the supported path.
+
+### Versioning policy
+
+Coefficient *values* are floating point, but the *computation* is exact:
+combinatorial structure, discrete data (duals, signs, Frobenius–Schur phases),
+and gauge fixing are deterministic. Any change that can alter a coefficient
+value, its normalization, or its canonical gauge is a **breaking** change, so
+consumers may key caches and persisted data on the crate version. For the base
+SU(2) provider this rule is mechanized by `su2_authority_fingerprint()`: its
+epoch is bumped only on such a value-affecting release, so a fingerprint change
+and a breaking release are one reviewable event.
+
+[Unreleased]: https://github.com/Ryo-wtnb11/racah/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/Ryo-wtnb11/racah/compare/v0.1.1...v0.2.0
+[0.1.1]: https://github.com/Ryo-wtnb11/racah/releases/tag/v0.1.1
+[0.1.0]: https://github.com/Ryo-wtnb11/racah/releases/tag/v0.1.0

racah_py-0.1.0/CITATION.cff

@@ -0,0 +1,16 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+type: software
+title: racah
+authors:
+  - family-names: Watanabe
+    given-names: Ryo
+repository-code: "https://github.com/Ryo-wtnb11/racah"
+license:
+  - MIT
+  - Apache-2.0
+abstract: >-
+  A Rust library for Racah-Wigner calculus: Clebsch-Gordan and recoupling
+  (F/R) coefficients for SU(2), SU(N), SO(N), and Sp(2N), computed on demand
+  for any admissible labels under a gauge frozen as a normative specification,
+  with Python bindings.