Changelog

Release notes for symmray. See also the GitHub releases page.

v0.4.0 (unreleased)

Breaking Changes:

• conj_project now takes axes= instead of axis=. It accepts either a single integer or an ordered sequence of axes to keep uncontracted.

Enhancements:

• Flat array fusion and contraction no longer require einops

• Fermionic arrays expose dummy_parity, the combined parity of their dummy modes, while preserving traced backend scalar types for flat arrays.

• phase_global(parity=...) conditionally applies a global fermionic phase and supports traced parity scalars with the flat backend.

• Sparse svd_rand_truncated(): spread finite max_bond over charge sectors in proportion to their current sizes before computing block decompositions (otherwise no speedup) and also supports abs and rel cutoffs.

• Sparse truncated SVD and eigendecomposition accept max_bond_mode="eager" for the same size-based allocation. Their default max_bond_mode="global" now selects the largest values across full block spectra even when cutoff=0.0, preserving degenerate multiplets that cross the threshold.

• Truncated SVD and eigendecomposition methods now default to cutoff_mode="rel".

• Contraction now traces out conjugate dummy_modes pairs in a second pass over the sorted modes, so both backends fully reduce them and agree. The flat backend previously only sorted them.

• Add gram(axes=-1) and symmray.gram to form dag(x) @ x, contracting every other axis against the conjugate. Sparse and flat fermionic arrays use the positive fermionic operator convention, and currently support a single open axis.

• Fermionic conj and dagger accept a sequence of outer axes for phase_dual. Use inner_dummy_labels for dummy modes whose conjugate partners are already in the network. These modes get no dual phase and use virtual conjugate labels.

• Add FermionicOperator.vconj. It flips a mode’s dual flag and wraps its label as ("vconj", label). Applying it twice restores the original mode.

Bug Fixes:

• Flat fused-index charge selection supports traced scalar charges, fixing batched index selection under torch.vmap, for example in truncated boundary contractions (GH 52).

• ‘Fermionic reductions’ (sum, max, min, all, any) and elementwise operations (abs, sqrt, clip, isfinite, real, imag) now phase_sync (note some of these are not well-defined but its useful to match the equivalent to_dense)

• Fermionic item and get_scalar_element now phase_sync, including float, complex, int and bool conversions.

• Fusing an empty group of axes now records subindex information for the expanded axis, so that unfuse removes it again and the fuse/unfuse round trip is total. Fermionic unfusing also normalizes negative axes before computing phases.

• Fermionic conj(phase_dual=True) and dagger(phase_dual=True) now phase dual dummy modes like outer dual indices. This fixes wrong signs in norms and repeated conjugation of arrays with dual dummy modes.

• Dummy mode labels with mixed types now sort consistently. This fixes contraction signs when site labels and ("squeeze", label, ax) labels occur together.

• Fermionic splits, such as qr and svd, now pass explicit charge_side on to the abelian split, so charge, label and dummy modes go on the requested factor.

v0.3.1 (2026-08-25)

Enhancements:

• Added scalar 2D and 3D tensor-network builders: TN2D_abelian_rand(), TN2D_fermionic_rand(), TN3D_abelian_rand(), and TN3D_fermionic_rand().

• Network builders accept duals to choose, randomize, or override bond orientations.

• to_dense() accepts explicit index maps to restore the dense basis ordering supplied to from_dense().

Full Changelog: v0.3.0…v0.3.1

v0.3.0 (2026-08-22)

Breaking Changes:

• The minimum autoray version is now 0.8.10.

• ham_heisenberg_from_edges() now takes explicit j and b arguments instead of forwarding arbitrary keyword arguments to quimb.ham_heis. Couplings can vary by edge and fields can vary by site.

• tfim_local_array() moved from symmray.hamiltonians to symmray.spin_local_operators and is now exported from the top-level namespace.

Enhancements:

• Added conj_project(axis=...) for inserting an array and its conjugate as a projector with arbitrary rank, bond duality, and fermionic parity.

• Added finfo() for querying the machine limits of common NumPy floating-point and complex dtypes.

• Symmetric arrays support scalar exponentiation with x ** p.

• Added to() for changing the array backend, dtype, and device, including in place. This method requires autoray>=0.9.0.

• Added quimb-free local spin builders: build_local_spin_dense(), build_local_spin_array(), tfim_local_array(), heisenberg_local_array(), and spin_operator_local_array(). Passing symmetry=None returns dense arrays.

• ham_tfim_from_edges() and ham_heisenberg_from_edges() no longer require quimb. The Heisenberg builder supports anisotropic, per-edge couplings and per-site longitudinal fields.

• Added the local fermionic operators fermi_spin_z_local_array(), fermi_spin_plus_local_array(), fermi_spin_minus_local_array(), fermi_double_occupancy_local_array(), fermi_pairing_onsite_local_array(), and fermi_pairing_bond_local_array().

• Two-input einsum() expressions dispatch pure pairwise contractions directly to tensordot() and support vector-array diagonal multiplication patterns.

• Flat fermionic dummy-mode phases are calculated with vectorized Koszul sorting. This reduces jax.jit and torch.compile graph size and supports compiled, vectorized amplitudes and gradients (PR 36).

• Matmul-shaped flat contractions use the faster direct batched-matmul path.

• Flat contraction and fusion skip redundant charge columns when sorting, reducing sorting overhead.

Bug Fixes:

• Flat sector sorting no longer creates temporary backend arrays on the default device when packing integer keys.

• Empty BlockVector objects now pass structural validation.

• Fermionic eigendecomposition and Cholesky accept drop_dummy_modes and again drop dummy modes and labels by default, avoiding unwanted phases when their factors are used as projectors.

• eigh_truncated() clips small negative eigenvalues when positive=True before truncating the positive spectrum.

• Flat charge selection now constructs its selection index on the active backend and device, fixing JAX tracing and Torch execution (PR 42).

• get_array_cls() raises a clear ValueError when flat storage is requested for an unsupported symmetry instead of exposing an internal lookup error.

Docs:

• Split the README into task-focused guides covering construction, storage, fermionic arrays, dummy modes, local operators, linear algebra, and tensor networks, with extensive API cross-references.

• Added a worked landing-page example and moved the existing notebooks under docs/examples so they are built from saved outputs without being executed.

• Added a developer guide, API reference, changelog resolver, references page, and zero-warning API docstring rendering.

Infrastructure:

• Added dedicated testjax and testtorch Pixi environments and CI jobs, including compiled vectorized fermionic amplitude and gradient coverage (PR 36).

• Added a distribution build smoke test, refreshed package metadata and Pixi tasks, and updated Ruff formatting.

• Added contributing guidance and a code of conduct.

• Grouped monthly Dependabot updates and updated the Pixi, checkout, Codecov, setup-python, and PyPI publishing actions (PR 33, PR 34, PR 35, PR 37, and PR 43).

Full Changelog: v0.2.1…v0.3.0

v0.2.1 (2026-04-28)

Breaking Changes:

• Decompositions now use the corrected convention for which side carries the charge. Results from the non-default side may differ. This affects svd(), qr(), lq(), and eigh().

• Internal abstract hooks are now concrete methods on the appropriate common mixin. This affects external subclasses of internal mixins.

• Absorb now provides consistent absorb-mode handling across sparse and flat linear algebra.

Enhancements:

• einsum() supports multiple input arrays using cotengra contraction paths.

• Added cholesky() and cholesky_regularized() for sparse and flat, bosonic and fermionic arrays. Flat support was contributed in (PR 25).

• Added svd_rand_truncated(), qr_via_cholesky(), and lq_via_cholesky().

• Added svd_via_eig_truncated() for flat arrays.

• svd_via_eig() accepts eps to stabilize small singular values.

• Flat svd_via_eig() supports every Absorb mode and shortcut.

• Linear algebra decompositions now share the internal split interface across array types.

• Faster lexicographic sorting and phase calculations reduce jax.jit tracing time. Integer packing also uses narrower dtypes where possible (PR 31).

• Reshape argument parsing was simplified and given broader test coverage.

• Added the API reference and Read the Docs build (PR 30).

Bug Fixes:

• Fixed single-input einsum() expressions.

• Fixed reshape() when newshape contains an ambiguous -1.

• Fixed charge-carrying side behavior in decompositions.

• Fixed dtype handling when shifting charges.

• Fixed cholesky() errors found during multi-backend testing.

Internal:

• More operations now use the shared bosonic mixin. The test suite enforces that a public class has no duplicate method definitions in its MRO.

Infrastructure:

• Added a debug-enabled pixi run pytest task, renamed the Python test environments, and simplified CI to use the Pixi task.

Full Changelog: v0.2.0…v0.2.1

v0.2.0 (2026-01-13)

Breaking Changes:

• Renamed oddpos to dummy_modes and adjusted its behavior.

• Changed the spinful local-basis ordering, with compatibility tests against tensor-network energy calculations.

Enhancements:

• Added to_pytree and from_pytree methods, including to_pytree() and from_pytree().

• Preserve labels where possible when contracting arrays.

• Added flat to the local fermionic operator constructors, including build_local_fermionic_array().

• from_dense() accepts additional array-construction options (PR 19).

• fermi_hubbard_spinless_local_array() supports a pairing term.

Bug Fixes:

• Fixed several Torch and JAX compatibility problems.

• Use backend-agnostic take() instead of direct tensor indexing for Torch compatibility (PR 23).

Full Changelog: v0.1.1…v0.2.0

v0.1.1 (2025-12-03)

Enhancements:

• Support flat fermionic arrays under torch.vmap.

• Added take().

• Improved transpose handling for singleton dimensions (PR 1).

• Added 2D-input support to the abelian symmetry-line solver (PR 14).

• Added an MPS construction helper (PR 17).

Bug Fixes:

• Avoided in-place multiplication in truncated SVD (PR 2).

• Fixed symmetry-line location (PR 9).

Infrastructure:

• Updated the Micromamba, uv, checkout, and Pixi setup actions (PR 4, PR 11, PR 12, PR 13, PR 16, and PR 18).

Full Changelog: v0.1.1