quantum-group: exact SymPy verification of explicit U_q(sl_2) and GL_q(2|1) matrix identities

quantum-group builds the explicit matrices behind concrete quantum-group calculations with SymPy, forms the difference between the two sides of an identity, and checks that every entry of this residual simplifies exactly to zero. It covers finite-dimensional U_q(sl_2) representations and the graded GL_q(2|1) R-matrix of Çelik and Çelik (2021). It verifies identities on concrete representations; it is not a general quantum-group computer algebra system and not a theorem prover.

Main features

• q-integers, q-factorials and q-binomials as Laurent polynomials, and classical limits.
• Explicit E, F, K, K_inv matrices for the modules V_n of U_q(sl_2).
• Defining relations checked as exact residual matrices.
• Coproduct, counit and antipode, with generator-level Hopf identities.
• Tensor products, Clebsch–Gordan highest-weight vectors.
• The fundamental R-matrix on V_1 ⊗ V_1: QYBE, braid and Hecke relations, coproduct intertwining, in both the historical and the coproduct-compatible convention (see below).
• The 9x9 GL_q(2|1) R-matrix, super-permutation, the 27x27 graded Yang–Baxter residual, and R_ij placements on V^{⊗n} via graded swaps.
• The combinatorial crystal graph B(n) and simple weight/crystal plots.

Installation

Python 3.10–3.13. Runtime dependencies: SymPy ≥ 1.10, NetworkX ≥ 2.6, Matplotlib ≥ 3.5 (installed automatically). Distribution name quantum-group, import name quantum_group.

From PyPI:

python3 -m pip install quantum-group==1.1.1

From this repository (for development, or to install a specific commit):

git clone https://github.com/TerekliTahaBerk/quantum-groups.git
cd quantum-groups
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install -e ".[test]"

Without cloning: python3 -m pip install "git+https://github.com/TerekliTahaBerk/quantum-groups". For the notebook in notebooks/, install ".[test,notebooks]" (equivalent to pip install -r requirements.txt).

Quickstart

This is examples/quickstart.py; CI runs it from outside the source tree against an installed wheel.

from quantum_group import (
    build_representation,
    verify_on_representation,
    R_matrix_V1_coproduct,
    intertwining_holds_V1,
    qybe_holds,
    graded_yang_baxter_residual_GLq21,
    is_zero_matrix,
)

# U_q(sl_2): the 3-dimensional module V_2 satisfies the defining relations.
rep = build_representation(2)
checks = verify_on_representation(rep.E, rep.F, rep.K, rep.K_inv)
assert all(check.holds for check in checks.values())

# The fundamental R-matrix compatible with the package coproduct satisfies
# the QYBE and intertwines the coproduct for every generator.
assert qybe_holds(R_matrix_V1_coproduct())
assert all(intertwining_holds_V1(X) for X in ("E", "F", "K", "K_inv"))

# GL_q(2|1): the graded Yang-Baxter residual is an exact 27x27 zero matrix.
residual = graded_yang_baxter_residual_GLq21()
assert residual.shape == (27, 27) and is_zero_matrix(residual)

print("quickstart: all checks passed")

examples/sample_verification.py is a slightly longer example that prints each result, including a negative control; its expected output is examples/sample_verification_expected.txt, and CI checks that the two agree.

Every *_residual function returns the exact SymPy difference matrix, so a failing identity can be inspected entry by entry. Draft names used in the thesis, build_representation_core and verify_relations_core, remain available as wrappers.

Validation

One command runs the complete test suite and the package doctests; it is what CI runs on Python 3.10–3.13 and with the oldest supported dependency versions:

python3 -m pytest          # or: make check

Plots use Matplotlib's noninteractive Agg backend in the tests. The GL_q(2|1) checks use symbolic 81x81 matrices; the full suite took about 15 s when prepared for 1.1.0 (Python 3.12, SymPy 1.14, x86-64 Linux; the suite is unchanged in 1.1.1). Targeted runs, e.g. python3 -m pytest tests/test_supergroup_gl21.py, also work.

Conventions and mathematical background

The coproduct is Δ(E) = E⊗1 + K⊗E, Δ(F) = F⊗K^{-1} + 1⊗F, Δ(K) = K⊗K.

R_matrix_V1() is the historical upper-triangular matrix diag(q, 1, 1, q) plus the entry q - q^{-1}: the image of Drinfeld's universal R-matrix on V_1 ⊗ V_1 multiplied by q^{1/2} (Drinfeld 1987, §13, pp. 816–817; derivation in AUDIT.md §4). It intertwines the opposite of the package coproduct. For the package coproduct and its tensor-product submodules use R_matrix_V1_coproduct() (= R_21 = P R P) and R_check_V1_coproduct() (= R P); intertwining_residual_V1(X) exposes the check for X in E, F, K, K_inv. Both conventions satisfy the QYBE and the Hecke relation, but their braid eigenspaces differ. The historical function is kept unchanged so that earlier results remain reproducible.

Exact Python integers are converted to SymPy integers; floats remain approximate. The default parameter is a generic nonzero symbol q; identities are rational in q and hold where denominators are defined. The defining commutator quotient excludes q = ±1 (use the classical-limit helpers there). At roots of unity the modules need not be irreducible or semisimple, and the Clebsch–Gordan routine assumes generic q.

For GL_q(2|1) the basis parities are (0, 0, 1). The matrix matches the unnumbered display on printed page 261 of Çelik and Çelik, Reports on Mathematical Physics 88 (2021) 259–269; every entry is fixed by a test. General placements accept even (parity-preserving) operators only.

Scope and limitations

• Checks run on explicit finite-dimensional representations; they do not prove identities in the abstract Hopf algebra or classify representations.

• A residual that SymPy does not simplify to zero is not by itself a proof of inequality (simplify is not a decision procedure).

• Root-of-unity helpers are examples; the small quantum group is not implemented. B(n) is a combinatorial model, not a crystal-basis algorithm.

• The RTT relations, Hopf superalgebra and Gauss decomposition of GL_q(2|1), Markov traces and the Jones polynomial are not implemented.

• Dense symbolic matrices grow as 3^n. Recorded timings (benchmarks/results.md; Python 3.11, SymPy 1.14, 2.1 GHz Xeon, mean of 3):

  Check	n	Matrix size	Mean time
  graded_yang_baxter_holds_GLq21	3	27x27	0.06 s
  all_Rij_GLq21	4	81x81	0.98 s
  local_ybe_on_four_tensor_GLq21	4	81x81	1.56 s
  all_Rij_GLq21	5	243x243	14.6 s
  graded YBE on one triple, incl. embedding	5	243x243	15.2 s

  At n = 5 building the embeddings dominates. n ≥ 6 has not been benchmarked. Rerun with python benchmarks/benchmark.py (overwrites the recorded table) or make benchmark-smoke (writes to build/).

Related software

GAP's QuaGroup (W. A. de Graaf) and SageMath's QuantumGroup interface to it are far more general: they compute with U_q(g) for semisimple g, including highest-weight modules, R-matrices and canonical/crystal bases; SageMath also has crystals for gl(m|n). This package does not replace them. It is a small pure-Python layer for checking the explicit matrices of a particular text, in its basis order and conventions, including the graded GL_q(2|1) example, which lies outside QuaGroup's documented U_q(g) scope. For general U_q(g) computations, use those systems. Section 6.3 of the userguide (scipost/) tests matrices computed by QuaGroup with this package and identifies where the two systems' conventions differ.

Userguide and reproducing its calculations

The userguide is scipost/paper.pdf (source scipost/paper.tex, prepared for SciPost Physics Codebases); the same text in the AMS amsart layout of an arXiv preprint is arxiv/paper.pdf, generated from it by arxiv/build.py. Its six code listings are scripts in examples/, scipost/examples/ and scipost/crosscheck/, each stored with its expected output:

make listings    # run Listings 1-6 and compare with the stored outputs (also run by CI)
make paper       # build scipost/paper.pdf and check listings, outputs and references
make -C arxiv check    # regenerate and check the arXiv version

The thesis claims are mapped to code and tests in MANUSCRIPT_CODE_MAPPING.md. The main verification claims:

Repository layout

quantum_group/        the package (linalg.py holds the shared kron/zero-test helpers)
tests/                pytest suite; doctests in quantum_group/ run with it
examples/             quickstart.py, sample_verification.py (+ expected output)
benchmarks/           timing script and recorded results
notebooks/            exploratory notebook
scipost/              userguide (SciPost Physics Codebases), Listings 2-6, QuaGroup cross-check
arxiv/                the userguide as an amsart preprint, generated from scipost/
thesis/               the undergraduate thesis (Turkish), its poster and errata; see thesis/README.md
AUDIT.md              mathematical/technical audit (September 2026)
MANUSCRIPT_CODE_MAPPING.md
main.py               demo script (writes outputs/V4_combined.png)

Makefile targets: make check, make quickstart, make listings, make paper, make demo, make figures and make benchmark-smoke. Corrections to the submitted thesis (thesis/Lisans Bitirme Tezi.pdf) are listed in thesis/ERRATA.md.

Contributing and support

Bug reports, questions and suggestions are welcome through GitHub issues; see CONTRIBUTING.md. The package is maintained by its author on a best-effort basis. Changes are listed in CHANGELOG.md.

Citation

Please cite the software using CITATION.cff (GitHub's "Cite this repository" button exports it). Every GitHub Release is archived on Zenodo. Version 1.1.0 is 10.5281/zenodo.23015576; version 1.1.1 has the same package code and adds the userguide material. The earlier record 10.5281/zenodo.22997681 archives version 1.0.0 only and does not contain the changes listed for 1.1.0 in the changelog.

License

MIT; see LICENSE.