Changelog¶
0.1.6 — July 15, 2026¶
What's New¶
Development Status: Beta → Stable¶
The PyPI classifier has been updated from Development Status :: 4 - Beta to
Development Status :: 5 - Production/Stable, signalling that the public API is
considered stable for general use.
Dynamic Version Retrieval¶
yuzuha.__version__ is no longer a hardcoded string literal. It is now resolved
at import time via importlib.metadata.version("yuzuha"), so it always matches
the installed package metadata with no manual edit step on release.
Documentation Build Dependencies¶
A new docs optional-dependency group (mkdocs-material, mkdocstrings[python])
has been added to pyproject.toml, installable via pip install yuzuha[docs].
Documentation Site Security Hardening¶
The unmaintained, previously-compromised polyfill.io script has been removed
from extra_javascript in mkdocs.yml.
Packaging Fix¶
A stray trailing backslash on the PDF LFS filter line in .gitattributes has been
removed.
Statistics¶
- 4 commits since v0.1.5
API Changes¶
No breaking changes.
| Symbol | Kind | Change |
|---|---|---|
yuzuha.__version__ |
attribute | now resolved via importlib.metadata instead of a hardcoded string |
0.1.5 — April 7, 2026¶
What's New¶
Equality, Hashing, and Ordering for All Core Types¶
All five core PyO3 types now implement proper Python equality and hashing, making
them usable as dictionary keys and set members without any wrapper. Spin additionally
supports < ordering, so lists of spins can be passed to sorted() directly. All
five classes are also declared frozen in PyO3, so attribute assignment raises
AttributeError rather than silently doing nothing.
| Type | New dunder methods |
|---|---|
Spin |
__eq__, __hash__, __lt__ |
Direction |
— (frozen; equality already worked via identity) |
Edge |
__eq__, __hash__ |
CGSpec |
__eq__, __hash__ |
Contraction |
__eq__, __hash__ |
canonical_basis Minimum-Edges Validator Corrected¶
The Rust guard previously raised ValueError for CGSpecs with fewer than 3
external edges; it now correctly raises for fewer than 2. The underlying
computation already supported \(n \geq 2\) edges since v0.1.1 — only the
input-validation check was wrong.
Return-Type Improvement for compute_xsymbol / compute_rsymbol¶
The second element of the return tuple (the output CGSpec) was previously typed
as object in the Python type stubs. It is now typed as CGSpec, enabling proper
IDE auto-completion and static type-checking on the result.
Cache stats() Deadlock Fix¶
XSymbolCache.stats() and RSymbolCache.stats() previously called self.size()
while already holding the cache lock, causing a potential deadlock. A new internal
_size_unlocked() helper is used instead.
Improved Error Messages¶
CGSpec.from_edges()error now reads "an odd number of half-integer spins" rather than "odd number of fermions (j=1/2)".DimensionMismatchnow displays the full expected and actual shape tuples instead of bare integer counts.
Expanded Test Suite¶
24 net Python tests added (25 new, 1 removed):
| Suite | v0.1.4 | v0.1.5 | Change |
|---|---|---|---|
test_basic |
44 | 62 | +18 |
test_symbol_cache |
30 | 37 | +7 |
test_canonical_basis |
57 | 56 | −1 |
| (other Python suites unchanged) | 218 | 218 | — |
| Python total | 349 | 373 | +24 |
| Rust (all suites unchanged) | 120 | 120 | — |
| Grand total | 469 | 493 | +24 |
Statistics¶
- 493 tests (373 Python + 120 Rust)
- 39 commits since v0.1.4
API Changes¶
No breaking changes. All additions are strictly additive.
| Symbol | Kind | Change |
|---|---|---|
Spin.__eq__ / __hash__ / __lt__ |
dunder | added |
Edge.__eq__ / __hash__ |
dunder | added |
CGSpec.__eq__ / __hash__ |
dunder | added |
Contraction.__eq__ / __hash__ |
dunder | added |
compute_xsymbol return type |
type stub | object → CGSpec |
compute_rsymbol return type |
type stub | object → CGSpec |
0.1.4 — March 28, 2026¶
What's New¶
Full MkDocs Documentation Site¶
A comprehensive documentation site is now published, covering the Getting Started guide, full API Reference, and the formal Yuzuha Protocol specification. The site is built with MkDocs Material and includes MathJax for rendered equations, syntax-highlighted code blocks with copy buttons, a custom landing page with a full-viewport hero image, and a three-option light/dark/system colour palette.
The Protocol section includes a dedicated SU(2) Conventions sub-site covering fusion conventions, canonical basis construction (with the Racah formula), and arrow conventions — including derivations of the FS phase from bond inversion and the origin of the conjugate phase.
Python Type Stubs (yuzuha.pyi)¶
A complete .pyi stub file for the Rust-compiled extension module has been added at
python/yuzuha/yuzuha.pyi, enabling full IDE auto-completion, inline parameter hints,
and static type-checking for all Rust-exposed types and functions.
Terminology: "Leg" → "Edge"¶
All occurrences of leg have been renamed to edge throughout the codebase for consistency with standard tensor network literature. Two Rust error variants were renamed accordingly:
| Old name | New name |
|---|---|
LegNotFound |
EdgeNotFound |
IncompatibleLegs |
IncompatibleEdges |
Statistics¶
- 349 Python tests (unchanged)
- 29 commits since v0.1.3
- 1 new file:
python/yuzuha/yuzuha.pyi
API Changes¶
No new public API methods. Error variant renames are non-breaking — they are not exposed through the Python bindings.
0.1.3 — March 26, 2026¶
What's New¶
CGSpec Axis Inversion (CGSpec.with_inverted_axes)¶
A new method with_inverted_axes(axes) on CGSpec returns a copy of the spec with
the edge directions at the specified axis indices flipped (Incoming ↔ Outgoing). The
OM configurations (alphas) are reused unchanged because they depend only on spin values,
not edge directions.
CGSpec.with_inverted_axes(axes)— returns a newCGSpecwith the given edges direction-flipped; raisesValueErrorif any axis index is out of bounds- Available in both the Rust API and the Python bindings
Bond Inversion Scheme in X-Symbol Tests¶
The X-symbol test suite has been substantially reorganised around a systematic bond inversion scheme. Each test case now constructs a contracted tensor network, flips one or more contracted edge pairs, and verifies that the resulting X-symbol agrees with the original up to the expected Frobenius-Schur phase factor \((-1)^{2j}\) accumulated over the flipped pairs.
Expanded Test Suite¶
26 net tests added (17 Python + 9 Rust):
| Suite | v0.1.2 | v0.1.3 | Change |
|---|---|---|---|
test_invert_axes |
— | 17 | +17 |
test_xsymbol |
87 | 87 | 0 (refactored) |
| (other Python suites unchanged) | 245 | 245 | — |
| Python total | 332 | 349 | +17 |
test_cgspec (Rust) |
27 | 36 | +9 |
| (other Rust suites unchanged) | 84 | 84 | — |
| Rust total | 111 | 120 | +9 |
| Grand total | 443 | 469 | +26 |
Statistics¶
- 469 tests (349 Python + 120 Rust)
- 6 commits since v0.1.2
- 1 new test file:
test_invert_axes.py
API Changes¶
One new method added to CGSpec; no breaking changes.
| Symbol | Kind | Change |
|---|---|---|
CGSpec.with_inverted_axes |
method | added — returns a new CGSpec with selected edge directions flipped |
0.1.2 — March 14, 2026¶
What's New¶
CGSpec Dualization (dualize module)¶
A new dualize module implements conjugation of CGSpecs. The canonical conjugate
convention flips all edge directions relative to the original spec (first \(n-1\) edges
become Outgoing, last edge becomes Incoming), with an accumulated FS phase correction
for any edge deviating from that pattern.
compute_conjugate(spec)— returns(phase, conj_spec): the conjugated CGSpec with all edge directions flipped, and the cumulated FS phase factor (+1.0or−1.0)fs_phase_for_spin(j)— returns \((-1)^{2j}\) for a single spin
Both functions are exposed in the Python bindings and added to __all__.
FS Phase Removed from X-Symbol Computation¶
The integrated FS phase bookkeeping has been removed from compute_xsymbol. X-symbols
now return bare recoupling coefficients, consistent with the mathematical definition.
Users requiring FS phase correction should apply compute_conjugate or
fs_phase_for_spin explicitly.
The fs_phase module has been removed; its functionality is superseded by dualize.
Expanded Test Suite¶
59 net Python tests added (99 new, 40 removed); Rust suite unchanged:
| Suite | v0.1.1 | v0.1.2 | Change |
|---|---|---|---|
test_conjugate |
— | 60 | +60 |
test_xr_consistency |
— | 39 | +39 |
test_canonical_basis |
97 | 57 | −40 |
| (other Python suites unchanged) | 176 | 176 | — |
| Python total | 273 | 332 | +59 |
| Rust (all suites unchanged) | 111 | 111 | — |
| Grand total | 384 | 443 | +59 |
Statistics¶
- 443 tests (332 Python + 111 Rust)
- 12 commits since v0.1.1
- 1 new source file:
src/builders/dualize.rs - 1 removed source file:
src/builders/fs_phase.rs - 2 new test files:
test_conjugate.py,test_xr_consistency.py
API Changes¶
| Symbol | Kind | Change |
|---|---|---|
compute_conjugate |
function | added — conjugate CGSpec with FS phase |
fs_phase_for_spin |
function | added — standalone per-spin FS phase |
compute_fs_phase |
function | removed — superseded by compute_conjugate |
0.1.1 — February 26, 2026¶
What's New¶
Frobenius-Schur Phase Bookkeeping¶
A new fs_phase module implements the FS phase factor \((-1)^{2j}\) that arises when
contracting a pair of edges in opposite canonical directions. The phase is accumulated
over all contracted pairs and integrated directly into compute_xsymbol:
- First-region pairs (both axes
< n−1): phase applies when directions are(Incoming, Outgoing) - Last-edge pairs (both axes
== n−1): phase applies when directions are(Outgoing, Incoming)
compute_fs_phase(spec_a, spec_b, contraction) is also exposed as a standalone Python
function for inspection and testing.
Direction Class in Python¶
The Direction enum (Incoming / Outgoing) is now exported from the Python package,
making edge direction explicit in Python-level code.
Canonical Basis Generalised to n ≥ 2 Edges¶
The canonical basis builder and OM tensor construction have been refactored to correctly handle all configurations with two or more external edges.
Expanded Test Suite¶
165 new tests added across Python and Rust. New test categories include:
Directionclass construction and behaviour- X-symbol 2-edge and 3-edge consistency and inversion checks
- R-symbol two-edge configuration tests
- Canonical basis two-edge identity and cross-Gram orthogonality
- Canonical basis stress tests for large edge counts
Statistics¶
- 384 tests (273 Python + 111 Rust)
- 23 commits since v0.1.0
- 1 new source file:
src/builders/fs_phase.rs
API Changes¶
| Symbol | Kind | Notes |
|---|---|---|
Direction |
type | Incoming / Outgoing enum, now exported to Python |
compute_fs_phase |
function | standalone FS phase computation |
0.1.0 — February 16, 2026¶
Initial stable release.
Core Features¶
- X-symbols (
compute_xsymbol): tensor contraction coefficients \(X^\gamma_{\alpha\beta}\) coupling two CG tensors into an output CG tensor, with full outer multiplicity support - R-symbols (
compute_rsymbol): tensor permutation coefficients encoding the effect of transposing edges in a CG tensor - Clebsch-Gordan coefficients with Condon-Shortley phase convention
- Left-associative fusion-tree canonical basis for arbitrary edge configurations
- Full outer multiplicity (OM) enumeration via
CGSpec - Persistent SQLite caching for canonical basis data
- In-memory caching for X-symbol and R-symbol results with full lifecycle control
- PyO3-based Python bindings with ABI3 compatibility (Python ≥ 3.11)
- NumPy integration — all symbol tensors returned as
numpy.ndarray
Statistics¶
- 219 tests (119 Python + 100 Rust)
- 62 commits across 2 feature branches
- GPL-3.0 licence
Initial API Surface¶
Core types: Spin, Edge, CGSpec, Contraction
Computation: canonical_basis, compute_xsymbol, compute_rsymbol
Database & Cache: startup_database, set_cache_path, reset_caches,
clear_all_caches, get_cache_stats, print_cache_stats, TestCacheContext