betaFeedback

WorksPhysics and Astronomy

u3lib: An AI-Ready Computational Framework for U(3) Symmetry Algebra, Wigner Coupling, and Racah Recoupling Coefficients

Abstract

u3lib is a C++ library for U(3)/SU(3) representation-theory calculations in nuclear structure and related applications. It evaluates Wigner coupling and Racah recoupling coefficients using the procedure proposed in 2024 by Dang et al., which avoids the binomial coefficients and alternating sums used in earlier formulations. The library also provides irreducible representations (irreps), dimensions, Casimir invariants, conjugation, and tensor-product decompositions with outer multiplicities. It supports the canonical Gelfand-Tsetlin basis and the physical SU(3) ⊃\supset SO(3) basis, including inner multiplicities and the transformation between the two bases. Generator routines return matrix elements in the canonical basis and reduced matrix elements in the physical basis. Python bindings mirror the C++ API. Domain skills supplied with the repository allow an AI assistant with code-execution access to call these routines from natural-language requests.

PROGRAM SUMMARY

Program title: u3lib

Licensing provisions: MIT License.

Code repository: https://github.com/Deep-SANE/u3lib

Programming language: C++ (C++20), with Python bindings via pybind11.

External libraries: Eigen3 for QR-based null space solver; Boost for hash tables; OpenMP for multi-threading; fmt for formatting output; libwignernj for SU(2)SU(2) coupling and recoupling coefficients; and KraNS for iterative sparse null-space solvers on large matrices (with an automatic dense-QR fallback for small or block-heavy cases). The Python extension additionally uses pybind11.

Nature of problem: Fast, accurate, and reproducible evaluation of Wigner reduced coupling coefficients for the two group-subgroup chains SU(3)⊃SO(3)SU(3) \supset SO(3) and U(3)⊃U(2)U(3) \supset U(2), Racah recoupling coefficients (6-U(3)U(3) and 9-U(3)U(3) coefficients), and the associated algebraic quantities (irrep dimensions, Casimirs, multiplicities, basis enumeration, generator matrix elements, and basis transformations) needed by symmetry-adapted calculations for nuclear structure and similar problems.

Solution method: The U(3)⊃U(2)U(3) \supset U(2) reduced coupling and recoupling coefficients are built from the highest-weight U(3)⊃U(2)⊃U(1)U(3) \supset U(2) \supset U(1) full coupling coefficients, obtained as the orthonormal null space of the canonical raising generators, and propagated by the corresponding lowering generators [1]; the physical SU(3)⊃SO(3)SU(3) \supset SO(3) coefficients follow from the physical-to-canonical basis transformation, also obtained as the orthonormal null space of the physical raising generator L+L_{+} [1].

Introduction

Algorithms for computing coupling and recoupling coefficients for the unitary group U(3)U(3) and its special unitary subgroup SU(3)SU(3) date back to two papers published in 1973 by Draayer and Akiyama, which introduced a general algorithm [2] and an associated Fortran program for their evaluation [3]. These coefficients underpin nuclear structure calculations using Elliott’s SU(3)SU(3) model [4, 5] and other symmetry-adapted shell-model approaches [6, 7, 8], where large numbers of coefficients make speed and accuracy essential. The same symmetry is used in nuclear-structure frameworks for medium-mass and heavy deformed nuclei, including the pseudo-SU(3)SU(3) [9, 11, 13], proxy-SU(3)SU(3) [10, 11], and quasi-SU(3)SU(3) [12, 13] schemes, as well as the multiconfigurational dynamical symmetry (MUSY) [14]. Over the following five decades, the Draayer and Akiyama library was updated to improve numerical accuracy [15] and implemented in modern programming languages [16, 17]. These implementations retained the underlying algorithm based on hypergeometric functions with large factorials and alternating sums. Dang et al. introduced a different approach that does not involve these instability-prone functions by constructing the coefficients from the action of the group’s raising generators using numerical null-space solvers [1, 18]. For the large sparse matrices arising in this approach, a dedicated iterative null-space solver, now known as KraNS, was developed [19].

The same algebraic tools also arise outside nuclear physics. In particle physics, flavor SU(3)\mathrm{SU}(3) underlies the eightfoldway classification of hadrons and the quark model [20, 21]. In quantum information, Schur transforms are constructed from successive Clebsch–Gordan transformations for dd-level systems; for d=3d = 3, this provides a potential application of U(3)\mathrm{U}(3) coupling data to qutrit basis transformations [22]. In condensed-matter physics, symmetry-adapted numerical renormalization-group calculations of the SU(3)\mathrm{SU}(3) Anderson impurity model require tensor-product decompositions, coupling coefficients, and outer-multiplicity labels [23]. In quantum optics, SU(3)\mathrm{SU}(3) representation theory organizes multiphoton states and interference in three-channel passive interferometers [24]. In quantum simulations of SU(3)\mathrm{SU}(3) lattice gauge theory, basis states are organized by SU(3)\mathrm{SU}(3) irreps and Gelfand–Tsetlin patterns, and the gauge-invariant singlet state at each vertex is assembled from coupling coefficients [25]. These examples suggest uses for the computational framework presented here as a source of representation-theoretic building blocks, with application-specific modeling and any basis conversion supplied by the user.

In this paper, we present u3lib, a library for calculations with the U(3)\mathrm{U}(3) symmetry algebra, including coupling and recoupling coefficients. The library is part of DeepSANE—Deep-learning and Symmetry-adapted Ab-initio Nuclear modeling: an AI-ready Ecosystem1. Alongside the coefficient routines, u3lib provides C++ objects for irreps and their Casimir invariants, the canonical Gelfand-Tsetlin U(3)⊃U(2)⊃U(1)\mathrm{U}(3) \supset\mathrm{U}(2) \supset\mathrm{U}(1) and the physical SU(3)⊃SO(3)\mathrm{SU}(3) \supset\mathrm{SO}(3) bases, the generator matrix elements, the tensor-product decomposition, and the physical-to-canonical transformation. The C++ API is header-only; Python bindings mirror it one-to-one.

Large language models can help run scientific calculations from natural-language requests. To support their use with u3lib, we provide an agent-skill catalog that guides AI assistants through the library’s capabilities. To use these routines correctly, an agent must follow group-theoretical notation, phase conventions, memory-lifetime rules, and thread-safety requirements. The repository-local skills make these requirements explicit alongside the source code and provide procedures for constructing and checking calculations. This approach follows the interest in reusable domain-specific skills for computational research seen in initiatives such as the U.S. Department of Energy (DOE) Genesis Mission and its scientific agent skill catalog2. We also evaluate whether this guidance improves task completion and reduces the resources needed to integrate the library, particularly as implementation complexity increases.

The remainder of this paper documents the repository structure (§ 3), the classes and interface (Sec. III), the Python bindings (Sec. IV), the AI-ready interface and its benchmark evaluation (§ 6), the installation (Sec. VI) and a short summary (Sec. VII).

Library structure

u3lib is a header-only C++ library with build targets for examples, tests, and Python bindings. The top-level directories are:

  • include/: the library itself (all algorithms live here; user programs include these headers directly):

    • U3irrep.h: the irrep classes su3::irrep, u3::irrep;

    • U3gelfand.h, internal/gelfand/: the Gelfand state class u3::gelfand;

    • U3basis.h: basis enumeration (gelfandBasis, physicalBasis), the inner multiplicity Kappa, the u3::physicalvector class, and the generator-action predicates;

    • U3decomposition.h: the outer multiplicity Rho and the tensor-product decomposition;

    • U3U2xU3U2.h, U3SO3xU3SO3.h: the canonical and physical coupling coefficients and their look-up tables;

    • U3_U6Z6Coeffs.h, U3_U9Coeffs.h: the 6-U(3) and 9-U(3) recoupling coefficients and their look-up tables;

    • U3SO3_to_U3U2U1.h: the physical-to-canonical transformation;

    • U3generatorsRME.h: the physical-generator reduced matrix elements RME_L, RME_Q;

    • Definitions.h: the structured coefficient containers;

    • u3lib.h: the umbrella header and the initialize/finalize lifecycle.

  • src/: example driver programs (one .cpp per task) that call the headers and print results; compiled to bin/.

  • python/: the pybind11 extension (pyu3lib.cpp → u3lib.so, built with make python) and a tutorial Jupyter notebook (tutorial.ipynb).

  • agents/: the AI-agent skill catalog: an index (AGENTS.md), shared runtime instructions, and one skill per capability.

  • test/: the regression suite (test_*.cpp, the *_cases.h case sets, and reference/ documented values), run by make test.

  • doc/: this manual (LaTeX source).

  • bin/: build output (not source).

Classes and library interface

This section describes the public classes, methods, and interfaces for accessing coefficients. Types belong to the u3 namespace, with SU(3)SU(3) base types in su3. The algebraic types can be used without initialization. Coefficient databases require initialization as described below. Table I lists the main entry points.

HeaderEntry pointTask
U3irrep.hdim, C1/C2/C3, conjugateirrep dimension, Casimirs, conjugation
U3basis.hKappa, gelfandBasis, physicalBasisinner multiplicity; basis enumeration
U3decomposition.hRho, decompositionouter multiplicity; irrep product
U3U2xU3U2.hwigU3U2dbU(3)⊃U(2)U(3)\supset U(2) reduced coupling coefficients
U3SO3xU3SO3.hwigU3SO3dbSU(3)⊃SO(3)SU(3)\supset SO(3) reduced coupling coefficients
U3_U6Z6Coeffs.hu3u6db, u3z6db6-U(3)U(3) recoupling coefficients (three irreps)
U3_U9Coeffs.hu3u9db9-U(3)U(3) recoupling coefficients (four irreps)
U3SO3_to_U3U2U1.hphys_to_canophysical-to-canonical transformation
U3generatorsRME.hRME_L, RME_Qreduced matrix elements of LL, QQ

Table I. Main entry points of u3lib.

Lifecycle

In u3lib.h:

  • initialize() / initialize(&argc,&argv): set up the caches of the SU(2)SU(2) coefficients from libwignernj, and the U(3)U(3) coefficient databases;

  • finalize(): destroy the databases;

  • initialize_thread() / finalize_thread(): per-thread setup for multithreaded use;

  • clear(): clear cached coefficients while keeping the databases available;

  • is_initialized(): check whether the library is initialized.

Note on shared-backend lifecycle: if u3lib runs in the same process as another library that shares the libwignernj backend, initialize all of them at startup and finalize only after all coefficient work is complete. Calling finalize() while another user of the backend is still active destroys the shared state and causes runtime errors.

Irreps: su3::irrep and u3::irrep

(U3irrep.h.) su3::irrep stores an SU(3)SU(3) irrep; u3::irrep derives from it and adds the third label n33n_{33} (fixing the total quanta).

Constructors:

  • su3::irrep(): default (empty) SU(3) irrep.

  • su3::irrep(lambda,mu): SU(3) irrep from its labels.

  • u3::irrep(): default (empty) U(3) irrep.

  • u3::irrep(n13,n23,n33): U(3) irrep from its three labels.

  • u3::irrep(lambda,mu): normalized representative [λ+μ,μ,0][\lambda+\mu,\mu,0].

  • u3::irrep(su3::irrep, N): fix the total quanta NN.

Label getters:

  • lam() / lambda(): the SU(3) label λ\lambda.

  • mu(): the SU(3) label μ\mu.

  • n13(), n23(), n33(): the three U(3) labels (only for u3::irrep).

Dimension and invariants:

  • dim(): the dimension (both classes).

  • C2(): the quadratic SU(3) Casimir (both classes, shift-invariant).

  • C3(): the cubic SU(3) Casimir (both classes, shift-invariant).

  • C1(): the first-order Casimir =n13+n23+n33=n_{13}+n_{23}+n_{33} (total quanta), on u3::irrep only; su3::irrep has no C1().

  • quanta(): synonym of C1().

Other:

  • zero(): test for the trivial irrep.

  • conjugate(): the conjugate irrep (μ,λ)(\mu,\lambda).

  • conjugate_phase(): the associated conjugation phase.

  • normalize(): set n33=0n_{33}=0 for u3::irrep.

  • comparison operators and stream output.

  • writeBinary / readBinary: serialization for binary files.

Gelfand states: u3::gelfand

(U3gelfand.h.) The canonical basis state ∣n13,n23,n33;n12,n22;n11⟩\lvert n_{13},n_{23},n_{33};n_{12},n_{22};n_{11}\rangle.

Constructor:

  • u3::gelfand(n13,n23,n33,n12,n22,n11): build a Gelfand state from its labels.

Label getters and validity check:

  • n13() . . . n11(): the six Gelfand-pattern labels.

  • check(): test the betweenness condition.

  • normalize(): shift all quantum numbers by n33n_{33}.

Subgroup labels:

  • lam() / lambda(): the SU(3) label λ\lambda.

  • mu(): the SU(3) label μ\mu.

  • epsilon(): the U(1) weight.

  • Lambdax2(): 2× the embedded SU(2)SU(2) angular momentum.

  • MLambdax2(): 2× its projection.

Conjugation:

  • conjugate(): the conjugate Gelfand state.

  • conjugate_phase(): the associated conjugation phase.

Generator matrix elements: Each returns the matrix element of a U(3)U(3) canonical generator EijE_{ij} acting on a Gelfand state; a _12/_22 suffix selects the target branch (either on n12n_{12} or n22n_{22}, see [1]).

  • e11(), e22(), e33(): the diagonal weight generators.

  • e12(): the E12E_{12} element.

  • e21(): the E21E_{21} element.

  • e23_12(), e23_22(): the E23E_{23} element, per target branch.

  • e32_12(), e32_22(): the E32E_{32} element, per target branch.

  • e13_12(), e13_22(): the E13E_{13} element, per target branch.

  • e31_12(), e31_22(): the E31E_{31} element, per target branch.

The raising-action predicates E12, E23_12, E23_22, E13_12, E13_22 (in U3basis.h) identify the target state of each generator.

Physical states: u3::physicalvector

(U3basis.h.) The SU(3)⊃SO(3)SU(3) \supset SO(3) reduced state ∣(λμ) κ L⟩\lvert(\lambda\mu)\ \kappa\ L\rangle.

Constructor:

  • u3::physicalvector(irrep, L): a physical state of angular momentum LL.

Accessors:

  • irr(): the underlying irrep.

  • lam() / lambda(): the SU(3)SU(3) label λ\lambda.

  • mu(): the SU(3)SU(3) label μ\mu.

  • n13(), n23(), n33(): the U(3)U(3) labels.

  • L(): the angular momentum.

  • kappa(), kappamax(): the inner multiplicity of LL.

Free functions

Multiplicities:

  • u3::Kappa(irrep,L): inner multiplicity κmax⁡\kappa_{\max} (also kmax, mult).

  • u3::Rho(A,B,C): outer multiplicity ρmax⁡\rho_{\max} of irrep CC in A⊗BA \otimes B product (U3decomposition.h).

Bases:

  • u3::gelfandBasis(irrep): all Gelfand states of the irrep.

  • u3::physicalBasis(irrep): all physical states with nonzero κ\kappa.

  • u3::findGelfand(g,gArr): the index of a state within the gArr Gelfand basis.

Decomposition:

  • u3::decomposition(A,B): the full Kronecker series, returning (list of C, list of ρmax⁡\rho_{\max}) with ∑Cρmax⁡(C)dim⁡C=dim⁡Adim⁡B\sum_C \rho_{\max}(C)\dim C = \dim A\dim B.

Physical generator reduced matrix elements: Each takes two physicalvector states (bra, ket) and two std::vector<int> out-parameters (which receive the zero-based multiplicity labels), and returns an Eigen::MatrixXd of shape κmax⁡×κmax⁡\kappa_{\max}\times\kappa_{\max}.

  • RME_L: the angular-momentum RME, ⟨(λμ)κ′L′∥L∥(λμ)κL⟩=δL′LL(L+1)(2L+1)\langle(\lambda\mu)\kappa'L'\Vert L\Vert(\lambda\mu)\kappa L\rangle=\delta_{L'L}\sqrt{L(L+1)(2L+1)}.

  • RME_Q: the quadrupole RME, carrying an extra 2L′+1\sqrt{2L'+1} (Sec. III H).

Transformation: Both expand a physical state pp in the Gelfand basis gArr, returning the canonical-state indices and an amplitude matrix with one orthonormal column per κ\kappa.

  • u3::phys_to_cano(p,M,gArr): the expansion at a single projection MM.

  • u3::phys_to_cano_allM(p,gArr): the expansion over all MM.

Coefficient containers

(Definitions.h.) Every container provides operator()(...), operator[](i), a member print() method, and stream insertion via operator<<. The indexing operators return a writable reference for a non-const C++ container and a value for a const container. They access the same coefficients using different indexing schemes:

  • block(i0,...,id) selects a coefficient by its multiplicity indices, in the order listed for each container below. Each index starts at zero and is smaller than its corresponding *max() count.

  • block[i] selects a coefficient by a single flat index, 0≤i<block.size()0\le i<\texttt{block.size()}. For axis sizes d0,…,dm−1d_0,\ldots,d_{m-1}, the equivalent flat index is i=∑j=0m−1ij∏k=j+1m−1dki=\sum_{j=0}^{m-1}i_j\prod_{k=j+1}^{m-1}d_k, where an empty product is one. Thus, for a four-axis container, i=((i0d1+i1)d2+i2)d3+i3i=((i_0d_1+i_1)d_2+i_2)d_3+i_3.

  • data() exposes the underlying flat buffer; size() gives its number of coefficients; and empty() tests whether it contains no coefficients.

  • print(s) and s << block: output a formatted table of all multiplicity indices and their corresponding values to the stream s (defaulting to std::cout for print()).

In the equations below, AA, BB, CC, DD denote U(3) irreps, and ABAB, BCBC, ACAC, BDBD, CDCD denote selected intermediate irreps in the indicated tensor products, rather than the tensor products themselves. The total irrep is denoted by TT for three- and four-irrep recoupling. Each ρ\rho labels a particular occurrence of an output irrep in its coupling channel; κ\kappa resolves repeated angular momenta within an SU(3) irrep. The multiplicity indices in these equations use the library’s zero-based indexing.

U3U2: canonical coupling of A⊗B→CA\otimes B\to C, reduced with respect to U(2): ⟨Aa;Bb∥Cc⟩ρ\langle Aa;Bb\Vert Cc\rangle_{\rho}, where a,b,ca,b,c are their fixed U(2) sublabels [n12,n22][n_{12},n_{22}]. Only the outer multiplicity varies within the container, so block(rho) and block[rho] are identical.

  • rhomax(): the outer multiplicity ρmax⁡\rho_{\max}.

  • operator()(rho): indexed by ρ\rho.

  • print(s = std::cout): prints the coefficient row over ρ\rho.

U3SO3: physical coupling of A⊗B→CA\otimes B\to C, reduced with respect to SO(3): ⟨AκALA;BκBLB∥CκCLC⟩ρ\langle A\kappa_A L_A;B\kappa_B L_B\Vert C\kappa_C L_C\rangle_{\rho}, where LA,LB,LCL_A,L_B,L_C are fixed angular momenta. The three inner multiplicities and the outer multiplicity are the four container axes.

  • kappaAmax(): inner multiplicity κA,max⁡\kappa_{A,\max}.

  • kappaBmax(): inner multiplicity κB,max⁡\kappa_{B,\max}.

  • kappaCmax(): inner multiplicity κC,max⁡\kappa_{C,\max}.

  • rhomax(): the outer multiplicity ρmax⁡\rho_{\max}.

  • operator()(kappaA,kappaB,kappaC,rho).

  • print(s = std::cout): tabular print over (κA,κB,κC,ρ)(\kappa_A,\kappa_B,\kappa_C,\rho).

U3U6: UU-recoupling: U(A,B,T,C;AB,ρAB,ρAB_C;BC,ρBC,ρA_BC)U(A,B,T,C;AB,\rho_{AB},\rho_{AB\_C};BC,\rho_{BC},\rho_{A\_BC}). The labels ρAB_C\rho_{AB\_C} and ρA_BC\rho_{A\_BC} resolve the final couplings AB⊗C→TAB \otimes C \to T and A⊗BC→TA \otimes BC \to T, respectively.

  • rhoABmax(): multiplicity of the A⊗B→ABA \otimes B \to AB coupling.

  • rhoAB_Cmax(): multiplicity of the AB⊗CAB \otimes C coupling.

  • rhoBCmax(): multiplicity of the B⊗C→BCB \otimes C \to BC coupling.

  • rhoA_BCmax(): multiplicity of the A⊗BCA \otimes BC coupling.

  • operator()(rhoAB,rhoAB_C,rhoBC,rhoA_BC).

  • print(s = std::cout): tabular print over (ρAB,ρAB_C,ρBC,ρA_BC)(\rho_{AB},\rho_{AB\_C},\rho_{BC},\rho_{A\_BC}).

U3Z6: ZZ-recoupling: Z(B,A,T,C;AB,ρAB,ρAB_C;AC,ρAC,ρAC_B)Z(B,A,T,C;AB,\rho_{AB},\rho_{AB\_C};AC,\rho_{AC},\rho_{AC\_B}). The labels ρAB_C\rho_{AB\_C} and ρAC_B\rho_{AC\_B} resolve the couplings AB⊗C→TAB \otimes C \to T and AC⊗B→TAC \otimes B \to T, respectively.

  • rhoABmax(): multiplicity of the A⊗B→ABA \otimes B \to AB coupling.

  • rhoAB_Cmax(): multiplicity of the AB⊗CAB \otimes C coupling.

  • rhoACmax(): multiplicity of the A⊗C→ACA \otimes C \to AC channel.

  • rhoAC_Bmax(): multiplicity of the AC⊗BAC \otimes B channel.

  • operator()(rhoAB,rhoAB_C,rhoAC,rhoAC_B).

  • print(s = std::cout): tabular print over (ρAB,ρAB_C,ρAC,ρAC_B)(\rho_{AB},\rho_{AB\_C},\rho_{AC},\rho_{AC\_B}).

U3U9: 9-U(3)U(3) recoupling:

[ABABρABCDCDρCDACBDTρAC_BDρACρBDρAB_CD](1)\begin{bmatrix} A & B & AB & \rho_{AB}\\ C & D & CD & \rho_{CD}\\ AC & BD & T & \rho_{AC\_BD}\\ \rho_{AC} & \rho_{BD} & \rho_{AB\_CD} \tag*{(1)} \end{bmatrix}

The rightmost entries label the row couplings, and the bottom entries label the column couplings. In particular, ρAB_CD\rho_{AB\_CD} labels AB⊗CD→TAB \otimes CD \to T and is named rhoABCD in the code; ρAC_BD\rho_{AC\_BD} labels AC⊗BD→TAC \otimes BD \to T and is named rhoACBD. The container’s axis order is (ρAC,ρBD,ρAB_CD,ρAB,ρCD,ρAC_BD)(\rho_{AC},\rho_{BD},\rho_{AB\_CD},\rho_{AB},\rho_{CD},\rho_{AC\_BD}).

  • rhoACmax(): multiplicity of the A⊗C→ACA \otimes C \to AC coupling.

  • rhoBDmax(): multiplicity of the B⊗D→BDB \otimes D \to BD coupling.

  • rhoABCDmax(): multiplicity of the AB⊗CD→TAB \otimes CD \to T route.

  • rhoABmax(): multiplicity of the A⊗B→ABA \otimes B \to AB coupling.

  • rhoCDmax(): multiplicity of the C⊗D→CDC \otimes D \to CD coupling.

  • rhoACBDmax(): multiplicity of the AC⊗BD→TAC \otimes BD \to T route.

  • operator()(rhoAC,rhoBD,rhoABCD,rhoAB,rhoCD,rhoACBD).

  • print(s = std::cout): tabular print over all six recoupling multiplicity axes.

In C++ the U3U9 result is a view into a thread-local scratch buffer that the next database call overwrites; copy it before the next call. The other four own their buffers.

Coefficient databases

All coupling and recoupling coefficients are computed on demand and cached inside singleton database instances: u3::wigU3U2db(), u3::wigU3SO3db(), u3::u3u6db(), u3::u3z6db(), and u3::u3u9db(). The databases provide two ways to retrieve coefficients:

  • Structured container getters (get_U3U2, get_U3SO3, get_U3U6, get_U3Z6, get_U3U9): return the dedicated multidimensional containers described above (U3U2, U3SO3, U3U6, U3Z6, U3U9). These containers support multi-index coordinate access via operator(), linear flat indexing via operator[], shape accessors (*max()), and formatted stream printing.

  • Direct and flat-buffer getters (get): return contiguous buffers without container wrapper overhead.

The available getters across the five databases are:

  • Canonical coupling database (u3::wigU3U2db()):

    • get_U3U2( n^{a}_{13}, n^{a}_{23}, n^{a}_{33}, n^{a}_{12}, n^{a}_{22}, \ldots^{b}, \ldots^{c} ) →\to U3U2: structured container over ρ\rho.

    • get( n^{a}_{13}, n^{a}_{23}, n^{a}_{33}, n^{a}_{12}, n^{a}_{22}, \ldots^{b}, \ldots^{c} ) →\to Eigen::RowVectorXd: direct row vector of reduced coupling coefficients ⟨Aa;Bb∥Cc⟩ρ\langle Aa; Bb\|Cc\rangle_{\rho} across all outer multiplicities ρ=0,…,ρmax⁡−1\rho= 0,\ldots,\rho_{\max}-1. Returns an empty vector if the coupling is forbidden or outside branching rules.

  • Physical coupling database (u3::wigU3SO3db()):

    • get_U3SO3( \lambda_1, \mu_1, L_1, \lambda_2, \mu_2, L_2, \lambda_3, \mu_3, L_3 ) →\to U3SO3: structured 4D container indexed by (κA,κB,κC,ρ)(\kappa_A,\kappa_B,\kappa_C,\rho).

    • get( \lambda_1, \mu_1, L_1, \lambda_2, \mu_2, L_2, \lambda_3, \mu_3, L_3 ) →\to std::vector<double>: flat coefficient buffer laid out in row-major order of (κA,κB,κC,ρ)(\kappa_A,\kappa_B,\kappa_C,\rho), with size κA,max⁡κB,max⁡κC,max⁡ρmax⁡\kappa_{A,\max}\kappa_{B,\max}\kappa_{C,\max}\rho_{\max}.

  • UU-recoupling database (u3::u3u6db()):

    • get_U3U6( A, B, ABC, C, AB, \rho_{AB}, \rho_{AB\,C}, BC, \rho_{BC}, \rho_{A\,BC} ) →\to U3U6: structured container indexed by (ρAB,ρAB C,ρBC,ρA BC)(\rho_{AB},\rho_{AB\,C},\rho_{BC},\rho_{A\,BC}).

    • get( A, B, ABC, C, AB, \rho_{AB}, \rho_{AB\,C}, BC, \rho_{BC}, \rho_{A\,BC} ) →\to std::vector<double>: flat buffer of length ρABρAB CρBCρA BC\rho_{AB}\rho_{AB\,C}\rho_{BC}\rho_{A\,BC}.

    • get( n^{a}_{13}, n^{a}_{23}, n^{a}_{33}, \ldots, n^{bc}_{13}, n^{bc}_{23}, n^{bc}_{33} ) (18 integers) →\to std::vector<double>: raw-integer overload taking the partition labels of AA, BB, ABCABC, CC, ABAB, BCBC directly, computing intermediate ρ\rho maxima internally.

  • ZZ-recoupling database (u3::u3z6db()):

    • get_U3Z6( B, A, ABC, C, AB, \rho_{AB}, \rho_{AB\,C}, AC, \rho_{AC}, \rho_{AC\,B} ) →\to U3Z6: structured container indexed by (ρAB,ρAB C,ρAC,ρAC B)(\rho_{AB},\rho_{AB\,C},\rho_{AC},\rho_{AC\,B}) (note the leading BB, AA exchanging the first pair).

    • get( B, A, ABC, C, AB, \rho_{AB}, \rho_{AB\,C}, AC, \rho_{AC}, \rho_{AC\,B} ) →\to std::vector<double>: flat buffer of length ρABρAB CρACρAC B\rho_{AB}\rho_{AB\,C}\rho_{AC}\rho_{AC\,B}.

    • get( n^{b}_{13}, n^{b}_{23}, n^{b}_{33}, \ldots, n^{ac}_{13}, n^{ac}_{23}, n^{ac}_{33} ) (18 integers) →\to std::vector<double>: raw-integer overload taking the partition labels of BB, AA, ABCABC, CC, ABAB, ACAC directly.

  • 9-UU(3) recoupling database (u3::u3u9db()):

    • get_U3U9( A, B, C, D, AB, CD, AC, BD, ABCD, \rho_{AC}, \rho_{BD}, \rho_{ABCD}, \rho_{AB}, \rho_{CD}, \rho_{ACBD} ) →\to U3U9: structured container view. Multiplicity parameters follow the container’s axis order: column intermediate channels (ρAC,ρBD,ρABCD)(\rho_{AC},\rho_{BD},\rho_{ABCD}) followed by row intermediate channels (ρAB,ρCD,ρACBD)(\rho_{AB},\rho_{CD},\rho_{ACBD}).

    • get( A, B, C, D, AB, CD, AC, BD, ABCD, \rho_{AB},\rho_{CD},\rho_{ABCD}, \rho_{AC},\rho_{BD},\rho_{ACBD} ) →\to std::span<const double> (or std::vector<double>): flat buffer of length ρACρBDρABCDρABρCDρACBD\rho_{AC}\rho_{BD}\rho_{ABCD}\rho_{AB}\rho_{CD}\rho_{ACBD}. Note the multiplicity ordering difference: in get, intermediate row channels (ρAB,ρCD,ρABCD)(\rho_{AB},\rho_{CD},\rho_{ABCD}) precede column channels (ρAC,ρBD,ρACBD)(\rho_{AC},\rho_{BD},\rho_{ACBD}), whereas in get_U3U9 the column channels appear first to match internal storage strides.

    • get( n^{a}_{13},n^{a}_{23},n^{a}_{33}, \ldots, n^{abcd}_{13},n^{abcd}_{23},n^{abcd}_{33} ) (27 integers) →\to std::vector<double>: raw-integer overload taking the partition labels of all 9 participating irreps.

The multiplicity maxima passed to recoupling routines must match the exact Rho values for the corresponding channels; a mismatch triggers an internal assertion. A forbidden or empty coupling returns an empty container or buffer. You can query its shape, but must not index it.

Each database singleton provides a clear() member function (and u3::clear() clears all five) to remove cached coefficient blocks while retaining allocated thread workspaces.

Conventions and normalization

Phase and normalization conventions follow Ref. [1]; documented values and the generation procedure are in test/reference/.

  • Multiplicity indexing: Counts come from Kappa/Rho; container accessors use zero-based indices.

  • Canonical-coupling phase: For each ρ\rho block the phase and normalization are fixed by the highest-weight reduced coefficients—the orthonormal null space of the system imposed by E23E_{23} and E12E_{12} annihilating the highest-weight coupled state. For ρmax⁡>1\rho_{\max} > 1 (and self-conjugate irreps) the solver fixes a valid orthonormal ρ\rho basis (Row Reduced Echelon Form + Gram-Schmidt + positive leading sign); any alternative must be applied consistently to every ρ\rho-carrying coefficient. Conjugation of a Gelfand state satisfies C∣g⟩=(−1)n23−n12−n22−n11∣g.conjugate()⟩C \lvert g\rangle= (-1)^{n_{23}-n_{12}-n_{22}-n_{11}} \lvert g.\mathrm{conjugate}()\rangle (gelfand::conjugate_phase()).

  • Physical-to-canonical transformation: A physical SO(3) state ∣(λμ) κ L M⟩\lvert(\lambda\mu)\,\kappa\,L\,M\rangle is expanded in canonical Gelfand states ∣g⟩\lvert g\rangle with M=e11−e22=2n11−(n12+n22)M = e_{11} - e_{22} = 2n_{11} - (n_{12} + n_{22}). The highest-weight state M=LM = L belongs to the null space of L+L_+; L−L_- fixes the lower-MM phases within a κ\kappa multiplet. Distinct conjugate irreps obey C∣(λμ) κ L M⟩=(−1)λ+μ−L+M∣(μλ) κ L, −M⟩C\lvert(\lambda\mu)\,\kappa\,L\,M\rangle= (-1)^{\lambda+\mu-L+M}\lvert(\mu\lambda)\,\kappa\,L,\,-M\rangle (for λ>μ\lambda> \mu the transformation is built from the conjugate irrep with the phase factor (−1)n22+n11−L(-1)^{n_{22}+n_{11}-L}). For a self-conjugate irrep (λ,λ)(\lambda,\lambda) conjugation acts as an MM-independent symmetric matrix DD (D2=1D^2 = 1) that may mix κ\kappa.

  • Generator reduced matrix element factor: RME_L/RME_Q carry an extra 2L′+1\sqrt{2L' + 1}, so ⟨κL∥Q∥κ′L′⟩=(−1)L−L′⟨κ′L′∥Q∥κL⟩\langle\kappa L\Vert Q\Vert\kappa' L'\rangle= (-1)^{L-L'}\langle\kappa' L'\Vert Q\Vert\kappa L\rangle.

  • Input checks. Invalid labels or out-of-range indices abort via assertion.

Python bindings

The u3lib module mirrors the C++ API. Build it with make python, using an interpreter whose ABI matches the extension. Irreps (su3.irrep, irrep), gelfand, physicalvector, the free functions Rho, Kappa, decomposition, gelfandBasis, physicalBasis, the physical-generator reduced matrix elements RME_L/RME_Q, the transformation phys_to_cano/phys_to_cano_allM, and the five database accessors are all exposed with the same names and semantics as Sec. III. The structured containers provide __call__ (multiplicity-indexed), hat_data() as a NumPy array, and formatted printing via print() and __str__; database access before initialize() (or after finalize()) raises RuntimeError rather than aborting. The U3U9 container, a scratch-buffer view in C++, is copied into owning storage automatically in Python. For worked examples of irreps, bases, coupling, and recoupling, see the Jupyter notebook python/tutorial.ipynb. Build and toolchain details are in the top-level README.md.

AI-ready interface

Skill catalog and orchestration

The agents/ directory contains skills that guide an AI assistant through u3lib calculations. The catalog includes an index (agents/AGENTS.md), shared runtime instructions, and a skill for each capability. Each skill specifies the inputs, library call, conventions, and a numerical check. When an AI assistant with code-execution access enters the library and opens the README.md file, it is told to skip the rest of the file and go directly to the agents/ directory and use those instructions to run the configured local library. The library calculations do not require a network service.

The install skill (agents/install/SKILL.md) covers setup on a fresh checkout. The agent first runs make config to resolve or download dependencies, followed by make and make test. It can then run the calculation skills. Table II gives a sample request for each skill, with expected results checked against the library.

SkillExample prompt (expected result)
dim“Dimension of the SU(3) irrep (2, 1) – equivalently the U(3) irrep [3, 1, 0] or any shift such as [4, 2, 1]?” (15; shift-invariant)
casimirs“C2,C3C_2, C_3 for the SU(3) irrep (3, 1), and C1,C2,C3C_1, C_2, C_3 for the U(3) irrep [4, 2, 1].” (SU(3): 50/3, 160/9; U(3): C1C_1=7, 32/3, 56/9, U(3)-only)
cano-list“Enumerate the canonical Gelfand basis of (2, 0) with each state’s ϵ\epsilon, 2Λ2\Lambda, 2M2M labels.” (6 states)
phys-list“List the physical SO(3) basis (κ,L)(\kappa, L) of (4, 2) and verify the dimension sum rule.” (LL=6, 5, 4, 3, 2, 0 with κ\kappa=1, 1, 2, 1, 2, 1; ∑κ(2L+1)\sum\kappa(2L+1)=60)
cano-generators“Act with E12E_{12} on the Gelfand state ∣2,0,0;2,0;1⟩|2,0,0;2,0;1\rangle of (2, 0); give the resulting state and matrix element.” ∣2,0,0;2,0;2⟩|2,0,0;2,0;2\rangle with 2\sqrt{2}
phys-generators“Compute ⟨(2,0) κ=1 L=2∥Q∥(2,0) κ=1 L=2⟩\langle(2,0)\ \kappa=1\ L=2\Vert Q\Vert(2,0)\ \kappa=1\ L=2\rangle and ⟨∥L∥⟩\langle\Vert L\Vert\rangle.” (35/3≈3.416\sqrt{35/3}\approx3.416 and 30≈5.477\sqrt{30}\approx5.477)
phys-to-cano“Express ∣(2,0) κ=1 L=2 M=0⟩|(2,0)\ \kappa=1\ L=2\ M=0\rangle in the canonical Gelfand basis.” (amplitudes 1/3\sqrt{1/3}, 2/3\sqrt{2/3})
inner-mult“SO(3) multiplicity κ\kappa of L=2L=2 in (4, 2)?” (2)
outer-mult“Outer multiplicity ρ\rho of (1, 1) in (1, 1) ⊗\otimes (1, 1)?” (2)
decomposition“Full decomposition of (2, 0) ⊗\otimes (0, 2) with outer multiplicities; check the dimension sum rule.” ((2, 2)+(1, 1)+(0, 0))
cano-coupling“U(3)⊃\supsetU(2) reduced coupling for highest-weight states [2, 0, 0] [2, 0] ×\times [2, 0, 0] [2, 0] →\rightarrow [4, 0, 0] [4, 0] of (2, 0) ×\times (2, 0) →\rightarrow (4, 0); verify it equals 1.”
phys-coupling“SO(3)-reduced coupling (2, 0) κ\kappa=1 LL=2 ×\times (2, 0) κ\kappa=1 LL=2 →\rightarrow (4, 0) κ\kappa=1 LL=2; check against 2/9\sqrt{2}/9.”
u6recoupling“U-recoupling for (1, 0) ⊗\otimes (1, 0) ⊗\otimes (1, 0) →\rightarrow (3, 0) through intermediate irreps ABAB = (2, 0) and BCBC = (2, 0).” (1)
z6recoupling“Z-recoupling between (AB)C(AB)C and (AC)B(AC)B routes for (1, 0) ⊗\otimes (1, 0) ⊗\otimes (1, 0) →\rightarrow (3, 0) with intermediate irreps ABAB = (2, 0) and ACAC = (2, 0).” (1)
u9recoupling“9-(λμ)(\lambda\mu) recoupling for four fundamentals (1, 0) coupling to (4, 0) with intermediate irreps ABAB = CDCD = ACAC = BDBD = (2, 0).” (1)
conjugation“Conjugate the SU(3) irrep (2, 1) and its Gelfand states, reporting the phases.” (irrep →\rightarrow (1, 2), phase power −1-1)

Table 2. TABLE II: The u3lib agent skills with a representative prompt for each.

The assistant translates a request into library calls: it selects a skill, prepares inputs in the required conventions, runs the compiled C++ or Python routine, and reports the results with their labels and numerical check. The library computes the coefficients, Casimirs, and matrix elements; the assistant does not derive or approximate them. If a request is ambiguous or asks for an undefined quantity, the assistant asks for clarification or explains the problem. For example, a first-order Casimir is not defined for an SU(3) irrep.

Evaluation objectives

To evaluate the practical value of the skill catalog, we compare autonomous coding agents with and without access to the skills. We ask whether the skills help agents complete tasks correctly with fewer resources, and whether the benefit depends on the implementation complexity of the task. We examine two hypotheses:

  1. Resource efficiency: Domain skills reduce token consumption, execution time, and API cost by supplying conventions and usage patterns that the agent would otherwise need to discover from the source.

  1. Dependence on task complexity: The benefit increases as tasks move from Python integration to C++ workspace management and parallel execution, where memory ownership and thread-safety requirements introduce additional constraints.

Experimental methodology

Benchmark Tasks

We designed three tasks with increasing implementation complexity, covering Python integration, C++ workspace management, and parallel execution:

  • Task 1: Python Racah recoupling (consumer/recouple.py). A standalone Python utility computing UU- and ZZ-recoupling coefficients through the pybind11 interface and verifying unitary symmetry relations across fundamental representations (e.g. (1,0)×(1,0)×(1,0)→(3,0)(1,0)\times(1,0)\times(1,0) \to(3,0)). Architectural complexity: low (declarative bindings, automatic memory, single-threaded).

  • Task 2: C++ 9-U(3) batch exporter (consumer/u9_batch.cpp). A C++ executable evaluating 9-U(3) blocks via u3::u3u9db(): it parses the multi-irrep label specification, computes intermediate outer multiplicities, and serializes block and entry records, copying scratch-buffer views into owning storage to avoid aliasing across iterations. Architectural complexity: medium (C++ typing, headers, manual workspace lifecycle).

  • Task 3: C++ multi-threaded coupling (consumer/coupling_batch.cpp). Parallel canonical- and physical-basis coupling with OpenMP (#pragma omp parallel for), requiring per-thread database cache and scratch state (initialized on each thread) to avoid races, correct -fopenmp configuration, and deterministic output. Architectural complexity: high (shared-memory concurrency, thread-private state isolation).

Isolated test environments

Each run used a separate, disposable sandbox directory with its own consumer build environment, so files from one trial were unavailable to subsequent trials. The two conditions differed only in access to the skills:

  • Control (zero skills): a clean checkout containing the source, headers, and build scripts, with the skill directory (agents/) removed.

  • Treatment (domain skills): the same workspace plus the repository-local skill catalog indexed by agents/AGENTS.md, which the prompt directed the agent to consult.

Hidden tests and grader validation

The agent could inspect files and directories, edit code, and execute shell commands. When it declared completion or reached the limit of 50 steps, the environment was locked and an automated grader tested the resulting program against a hidden validation suite. The tests compared coupling and recoupling values with exact group-theoretical results across a range of irreps, using a 10−1210^{-12} tolerance.

Before the trials, we tested the grader by introducing phase inversions, memory leaks, uninitialized buffer reads, and artificial race conditions into reference implementations. On these validation cases, the grader achieved 100% sensitivity and specificity, with no false positives or false negatives.

Model and Statistical Protocol

All experiments used Anthropic’s Claude Sonnet 5.5 (claude-sonnet-5-5) in an autonomous agent test environment. For each task, N=10N = 10 matched Control/Treatment pairs were run (60 runs total), recording four metrics per run: functional pass rate; total token consumption (prompt, cache-read, and completion tokens); wall-clock latency; and API cost at official token pricing. Significance was assessed with two-tailed Welch’s tt-tests (unequal variance), reporting tt, degrees of freedom, and pp.

Results and discussion

Overall results

Table III and Figure 1 summarize the 60 runs. Across the three tasks:

TaskConditionPass RateTotal TokensTime (s)Cost ($) | Token Δ\Delta | Time Δ\Delta
Task 1Control (N=10N=10)100% (10/10)381,613 ±\pm 80,14058.90 ±\pm 10.51$0.2780 | — | —
Treatment (N=10N=10)100% (10/10)270,260 ±\pm 93,89046.61 ±\pm 7.88$0.2280 | −29.2%* | −20.9%
Task 2Control (N=10N=10)100% (10/10)614,511 ±\pm 144,848105.21 ±\pm 20.86$0.3751 | — | —
Treatment (N=10N=10)100% (10/10)329,829 ±\pm 62,10671.42 ±\pm 7.74$0.2499 | −46.3%* | −32.1%*
Task 3Control (N=10N=10)90.0% (9/10)654,185 ±\pm 163,874110.73 ±\pm 18.35$0.3934 | — | —
Treatment (N=10N=10)100% (10/10)320,246 ±\pm 141,26765.89 ±\pm 15.71$0.2459 | −51.0%* | −40.5%*
AggregateControl (N=30N=30)96.7% (29/30)550,103 ±\pm 178,30991.61 ±\pm 28.85$0.3488 | — | —
Treatment (N=30N=30)100% (30/30)306,778 ±\pm 104,07661.31 ±\pm 15.21$0.2413 | −44.2%* | −33.1%*

Table III. Empirical performance comparison between Control (Zero Skills) and Treatment (Domain Skills) across N=10N = 10 independent matched pairs per task (60 runs total) using Claude Sonnet 5.5. Tokens, execution duration, and costs are reported as Mean ±\pm Standard Deviation. Statistical significance is assessed via two-tailed Welch’s tt-tests. *p<0.05p < 0.05 (t=−2.85t = -2.85); **p<0.01p < 0.01 (t=−2.96t = -2.96); ***p<0.001p < 0.001 (Task 2: ttok=−5.71t_{\mathrm{tok}} = -5.71, ttime=−4.80t_{\mathrm{time}} = -4.80; Task 3: ttok=−4.88t_{\mathrm{tok}} = -4.88, ttime=−5.87t_{\mathrm{time}} = -5.87; Grand Aggregate: ttok=−6.46t_{\mathrm{tok}} = -6.46, ttime=−5.09t_{\mathrm{time}} = -5.09; Welch’s two-tailed tt-test).

Figure 1. Benchmark results comparing autonomous agent performance between Control (Zero Skills) and Treatment (Domain Skills) across N=10N = 10 independent trials per task. (a) Total token consumption (thousands) by task, showing monotonic savings of 29.2%, 46.3%, and 51.0%. (b) Wall-clock execution duration (seconds) by task, showing speedups of 20.9%, 32.1%, and 40.5%. Error bars indicate ±1\pm1 sample standard deviation.

  • Token Consumption: Providing domain skills reduced mean token consumption from 550,103 ±\pm 178,309 tokens to 306,778 ±\pm 104,076 tokens—an aggregate reduction of 44.2% (t=−6.46t = -6.46, p=6.0×10−8p = 6.0 \times10^{-8}, Welch’s tt-test).

  • Execution Latency: Wall-clock execution time decreased from 91.61 ±\pm 28.85 s to 61.31 ±\pm 15.21 s, representing an aggregate speedup of 33.1% (t=−5.09t = -5.09, p=7.2×10−6p = 7.2 \times10^{-6}).

  • API Cost: Direct inference costs fell from an average of $0.3488 to $0.2413 per task (−30.8%, t=−7.16t = -7.16, p=4.4×10−9p = 4.4 \times10^{-9}).

  • Reliability: Treatment runs achieved a 100% pass rate across all 30 evaluations. One Control run failed Task 3 (9/10), giving an aggregate pass rate of 96.7%.

Dependence on task complexity

For the three tasks considered here, the relative reductions in token consumption and execution time increase with the intended progression in task complexity:

Δtokens=−29.2%  (Task 1)⟶−46.3%  (Task 2)⟶−51.0%  (Task 3),\Delta_{\mathrm{tokens}} = -29.2\% \;(\text{Task 1}) \longrightarrow-46.3\% \;(\text{Task 2}) \longrightarrow-51.0\% \;(\text{Task 3}),
Δtime=−20.9%  (Task 1)⟶−32.1%  (Task 2)⟶−40.5%  (Task 3).\Delta_{\mathrm{time}} = -20.9\% \;(\text{Task 1}) \longrightarrow-32.1\% \;(\text{Task 2}) \longrightarrow-40.5\% \;(\text{Task 3}).

This trend is consistent with the hypothesis that explicit guidance becomes more useful as implementation constraints increase. Three tasks alone do not establish a general scaling law; the following observations describe agent behavior within this benchmark:

  1. Task 1 (API discovery): Control agents produced correct recoupling solutions but typically needed 3–6 shell turns (grep, ls, inspecting pybind11 modules) to discover the exposed bindings (u3lib.u6recoupling, u3lib.z6recoupling) and their argument order. Treatment agents retrieved the signatures directly from the catalog, finishing in 16.6 steps versus 22.8 for Control.

  1. Task 2 (scratch-buffer aliasing): The 9-U(3) database (u3::u3u9db()) returns views into internal scratch buffers reused across queries. Control agents encountered aliasing bugs when later queries overwrote stored blocks, spent time locating U3_U9Coeffs.h, and misordered the multiplicity strides, inflating consumption to 614, 511 tokens on average (worst case exceeding 853, 000). Treatment agents used the documented copying and indexing procedures and completed the task in 329, 829 tokens with about half the variance.

  1. Task 3 (concurrency): The coefficient databases keep per-thread cache and scratch state, so sharing one database across threads without initializing each thread causes races. The second Control run failed the hidden tests after attempts to resolve non-deterministic segmentation faults; even successful Control runs averaged 33.6 steps and 110.7 s to find the need for per-thread state. Treatment agents applied the skill’s OpenMP guidance from the first turn, completing the task with deterministic output in 65.89 s and 320, 246 tokens.

Build and installation

u3lib is header-only; user programs include the headers in include/ directly. The source is hosted publicly at https://github.com/Deep-SANE/u3lib. The build reads dependency paths from a configuration environment. After sourcing it from the repository root, use the following make targets: make (example programs → bin/), make test (build and run the regression suite), and make python (the pybind11 extension). The regression tests check dimensions, Gelfand interlacing and ordering, SO(3) branching, canonical/physical coupling orthonormality across κ\kappa and ρ\rho, conjugation identities, and documented analytic values; comparisons use numerical tolerances, since results need not be bitwise identical across backends.

make config locates the dependencies and writes config/config.generated.mk. It uses existing installations or downloads pinned versions from upstream sources and builds them under external-libs/, which is not part of the repository:

The KraNs null-space solver (https://github.com/Deep-SANE/krans) is used as a sibling checkout alongside u3lib rather than vendored under external-libs/; make config clones it from the Deep-SANE organization and builds it in place when it is not already present.

Conclusion

In summary, we have presented u3lib, an open-source, header-only C++20 library with one-to-one Python bindings for U(3)U(3) symmetry algebra. Built on the generator-action and null-space procedure of Dang et al. [1] and paired with the iterative sparse solver KraNS [19], the framework evaluates canonical U(3)⊃U(2)U(3) \supset U(2) and physical SU(3)⊃SO(3)SU(3) \supset SO(3) coupling coefficients as well as 6- and 9-U(3)U(3) recoupling coefficients without the factorial-heavy alternating sums of traditional formulations. The library also provides irrep invariants, canonical Gelfand–Tsetlin and physical basis enumeration, generator matrix elements, basis transformations, and tensor-product decompositions.

To support autonomous scientific workflows, the repository includes a structured catalog of domain skills that encode group-theoretical conventions, scratch-buffer lifetimes, and OpenMP thread-isolation rules for code-executing AI agents. Across 60 controlled benchmark runs spanning Python integration, C++ batch processing, and multi-threaded OpenMP execution, access to these skills raised task completion to 100% while reducing mean token consumption by 44.2%, wall-clock runtime by 33.1%, and inference cost by 30.8%, with the largest savings of 51.0% in tokens and 40.5% in runtime occurring on the concurrent C++ task. While three tasks on a single language model do not establish a universal scaling law and motivate broader evaluation across models and workloads, these results indicate that repository-local domain guidance becomes increasingly effective as implementation and concurrency constraints tighten. Within the broader DeepSANE ecosystem, u3lib provides the algebraic foundation for higher-rank extensions such as Wigner’s U(4)U(4) supermultiplet library u4lib and symmetry-adapted ab initio nuclear-structure framework SAM, while offering a reusable building block for U(3)/SU(3)U(3)/SU(3) calculations in quantum information, condensed-matter physics, and lattice gauge theory.

Acknowledgments

This work is dedicated to the memory of J. P. Draayer, who passed on September 13, 2026 and whose pioneering contributions to algebraic computational nuclear physics through Elliott’s SU(3)SU(3) model, the Symplectic Sp(3,R)Sp(3,R) model, the ab initio Symmetry-Adapted No-Core Shell Model, and his recent effort in Wigner’s SU(4)SU(4) model inspired this framework. The authors also gratefully acknowledge F. Pan and D. Kekejian for valuable discussions. PD was supported by the Institute of International Education through the Quad Fellowship, Louisiana State University, and Quantum CodeX. DL and TD were funded by Quantum CodeX. This work was supported in part by complimentary access to Google Antigravity and Gemini 4 Argon to accelerate scientific workflows.

References

References

  1. [1]P. Dang, J. P. Draayer, F. Pan, and K. S. Becker, “New Procedure for Evaluation of U(3) Coupling and Recoupling Coefficients,” Eur. Phys. J. Plus 139, 704 (2024), doi:10.1140/epjp/s13360-024-05501-8.DOI
  2. [2]J. P. Draayer and Y. Akiyama, “Wigner and Racah coefficients for SU₃,” J. Math. Phys. 14, 1904 (1973), doi:10.1063/1.1666267.DOI
  3. [3]Y. Akiyama and J. P. Draayer, “A User’s Guide to Fortran Programs for Wigner and Racah Coefficients of SU₃,” Comp. Phys. Comms. 5, 405 (1973), doi:10.1016/0010-4655(73)90077-5.DOI
  4. [4]J. P. Elliott, “Collective motion in the nuclear shell model. I. Classification schemes for states of mixed configurations,” Proc. R. Soc. Lond. A 245, 128–145 (1958), doi:10.1098/rspa.1958.0072.DOI
  5. [5]J. P. Elliott, “Collective motion in the nuclear shell model II. The introduction of intrinsic wave-functions,” Proc. R. Soc. Lond. A 245, 562–581 (1958), doi:10.1098/rspa.1958.0101.DOI
  6. [6]T. Dytrych, K. D. Launey, J. P. Draayer, P. Maris, J. P. Vary, et al., “Collective Modes in Light Nuclei from First Principles,” Phys. Rev. Lett. 111, 252501 (2013), doi:10.1103/PhysRevLett.111.252501.DOI
  7. [7]T. Dytrych, K. D. Launey, J. P. Draayer, D. J. Rowe, J. L. Wood, et al., “Physics of Nuclei: Key Role of an Emergent Symmetry,” Phys. Rev. Lett. 124, 042501 (2020), doi:10.1103/PhysRevLett.124.042501.DOI
  8. [8]A. E. McCoy, M. A. Caprio, T. Dytrych, and P. J. Fasano, “Emergent Sp(3,R) Dynamical Symmetry in the Nuclear Many-Body System from an Ab Initio Description,” Phys. Rev. Lett. 125, 102505 (2020), doi:10.1103/PhysRevLett.125.102505.DOI
  9. [9]V. K. B. Kota, “SU(3) Symmetry in Atomic Nuclei,” Springer, Singapore (2020), doi:10.1007/978-981-15-3603-8.DOI
  10. [10]D. Bonatsos, A. Martinou, S. K. Peroulis, T. J. Mertzikmekis, and N. Minkov, “The Proxy-SU(3) Symmetry in Atomic Nuclei,” Symmetry 15, 169 (2023), doi:10.3390/sym15010169.DOI
  11. [11]J. Cseh, “Shell-like quarteting in heavy nuclei: Algebraic approaches based on the pseudo- and proxy-SU(3) schemes,” Phys. Rev. C 101, 054306 (2020), doi:10.1103/PhysRevC.101.054306.DOI
  12. [12]A. P. Zuker, J. Retamosa, A. Poves, and E. Caurier, “Spherical shell model description of rotational motion,” Phys. Rev. C 52, R1741 (1995), doi:10.1103/PhysRevC.52.R1741.
  13. [13]A. Gade, B. Longfellow, R. V. F. Janssens, D. D. Dao, F. Nowacki, et al., “In-beam spectroscopy reveals competing nuclear shapes in the rare isotope ⁶²Cr,” Nat. Phys. 21, 37–42 (2025), doi:10.1038/s41567-024-02680-0.DOI
  14. [14]J. Cseh, “Microscopic structure and mathematical background of the multiconfigurational dynamical symmetry,” Phys. Rev. C 103, 064322 (2021), doi:10.1103/PhysRevC.103.064322.DOI
  15. [15]C. Bahri, D. J. Rowe and J. P. Draayer, “Programs for generating Clebsch–Gordan coefficients of SU(3) in SU(2) and SO(3) bases,” Comp. Phys. Comms. 159, 121 (2004), doi:10.1016/j.cpc.2004.01.005.DOI
  16. [16]D. Tytrych, D. Langr, J. P. Draayer, K. D. Launey and D. Gazda, “SU3lib: A C++ library for accurate computation of Wigner and Racah coefficients of SU(3),” Comp. Phys. Comms 269, 108137 (2021), doi:10.1016/j.cpc.2021.108137.
  17. [17]J. Herko, M. A. Caprio, A. E. McCoy and P. J. Fasano, “A modern Fortran library for SU(3) coupling and recoupling coefficients,” Eur. Phys. J. A 62, 95 (2026), doi:10.1140/epja/s10050-026-01845-0.DOI
  18. [18]A. Alex, M. Kalus, A. Huckleberry, and J. von Delft, “A numerical algorithm for the explicit calculation of SU(N) and SL(N, C) Clebsch–Gordan coefficients,” J. Math. Phys. 52, 023507 (2011), doi:10.1063/1.3521562.DOI
  19. [19]A. Krastenov, “Sparse Null Space Solver in C++,” Master’s thesis, Faculty of Information Technology, Czech Technical University in Prague (2026).
  20. [20]M. Gell-Mann, “Symmetries of Baryons and Mesons,” Phys. Rev. 125, 1067 (1962), doi:10.1103/PhysRev.125.1067.
  21. [21]Y. Ne’eman, “Derivation of strong interactions from a gauge invariance,” Nucl. Phys. 26, 222 (1961), doi:10.1016/0029-5582(61)90134-1.DOI
  22. [22]D. Bacon, I. L. Chuang, and A. W. Harrow, “Efficient Quantum Circuits for Schur and Clebsch–Gordan Transforms,” Phys. Rev. Lett. 97, 170502 (2006), doi:10.1103/PhysRevLett.97.170502.DOI
  23. [23]C. P. Moca, A. Alex, J. von Delft, and G. Zaránd, “SU(3) Anderson impurity model: A numerical renormalization group approach exploiting non-Abelian symmetries,” Phys. Rev. B 86, 195128 (2012), doi:10.1103/PhysRevB.86.195128.DOI
  24. [24]S.-H. Tan, Y. Y. Gao, H. de Guise, and B. C. Sanders, “SU(3) Quantum Interferometry with Single-Photon Input Pulses,” Phys. Rev. Lett. 110, 113603 (2013), doi:10.1103/PhysRevLett.110.113603.DOI
  25. [25]P. Draper and D. Gupta, “Impact of Irrep Truncations on Quantum Simulations of QCD,” arXiv:2610.23681 (2026), doi:10.48550/arXiv.2610.23681.DOI

Paper details

vlnc:W_jfuxzmhw
Version
v1 · latest
Published
Fresh — added to the Hub within the last 30 days
Added
License
CC BY 4.0
Usage

views · 10

downloads · 0

A view counts once per browser per day, a download each time the PDF is requested.

  • Physics and Astronomy

Not recorded for this paper

View statement
Looking for related papers…
Contents