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) 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 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 and , Racah recoupling coefficients (6- and 9- 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 reduced coupling and recoupling coefficients are built from the highest-weight full coupling coefficients, obtained as the orthonormal null space of the canonical raising generators, and propagated by the corresponding lowering generators [1]; the physical coefficients follow from the physical-to-canonical basis transformation, also obtained as the orthonormal null space of the physical raising generator [1].
Introduction
Algorithms for computing coupling and recoupling coefficients for the unitary group and its special unitary subgroup 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 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- [9, 11, 13], proxy- [10, 11], and quasi- [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 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 -level systems; for , this provides a potential application of coupling data to qutrit basis transformations [22]. In condensed-matter physics, symmetry-adapted numerical renormalization-group calculations of the Anderson impurity model require tensor-product decompositions, coupling coefficients, and outer-multiplicity labels [23]. In quantum optics, representation theory organizes multiphoton states and interference in three-channel passive interferometers [24]. In quantum simulations of lattice gauge theory, basis states are organized by 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 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 and the physical 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 classessu3::irrep,u3::irrep;U3gelfand.h,internal/gelfand/: the Gelfand state classu3::gelfand;U3basis.h: basis enumeration (gelfandBasis,physicalBasis), the inner multiplicity Kappa, theu3::physicalvectorclass, 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.cppper task) that call the headers and print results; compiled tobin/.
python/: the pybind11 extension (pyu3lib.cpp→u3lib.so, built withmake 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.hcase sets, andreference/documented values), run bymake 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 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.
| Header | Entry point | Task |
U3irrep.h | dim, C1/C2/C3, conjugate | irrep dimension, Casimirs, conjugation |
U3basis.h | Kappa, gelfandBasis, physicalBasis | inner multiplicity; basis enumeration |
U3decomposition.h | Rho, decomposition | outer multiplicity; irrep product |
U3U2xU3U2.h | wigU3U2db | reduced coupling coefficients |
U3SO3xU3SO3.h | wigU3SO3db | reduced coupling coefficients |
U3_U6Z6Coeffs.h | u3u6db, u3z6db | 6- recoupling coefficients (three irreps) |
U3_U9Coeffs.h | u3u9db | 9- recoupling coefficients (four irreps) |
U3SO3_to_U3U2U1.h | phys_to_cano | physical-to-canonical transformation |
U3generatorsRME.h | RME_L, RME_Q | reduced matrix elements of , |
Table I. Main entry points of u3lib.
Lifecycle
In u3lib.h:
initialize()/initialize(&argc,&argv): set up the caches of the coefficients fromlibwignernj, and the 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 irrep; u3::irrep derives from it and adds the third label (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 .u3::irrep(su3::irrep, N): fix the total quanta .
Label getters:
lam()/lambda(): the SU(3) label .mu(): the SU(3) label .n13(),n23(),n33(): the three U(3) labels (only foru3::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 (total quanta), onu3::irreponly;su3::irrephas noC1().quanta(): synonym ofC1().
Other:
zero(): test for the trivial irrep.conjugate(): the conjugate irrep .conjugate_phase(): the associated conjugation phase.normalize(): set foru3::irrep.comparison operators and stream output.
writeBinary/readBinary: serialization for binary files.
Gelfand states: u3::gelfand
(U3gelfand.h.) The canonical basis state .
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 .
Subgroup labels:
lam()/lambda(): the SU(3) label .mu(): the SU(3) label .epsilon(): the U(1) weight.
Lambdax2(): 2× the embedded 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 canonical generator acting on a Gelfand state; a _12/_22 suffix selects the target branch (either on or , see [1]).
e11(),e22(),e33(): the diagonal weight generators.
e12(): the element.
e21(): the element.
e23_12(),e23_22(): the element, per target branch.
e32_12(),e32_22(): the element, per target branch.
e13_12(),e13_22(): the element, per target branch.
e31_12(),e31_22(): the 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 reduced state .
Constructor:
u3::physicalvector(irrep, L): a physical state of angular momentum .
Accessors:
irr(): the underlying irrep.
lam()/lambda(): the label .
mu(): the label .
n13(),n23(),n33(): the labels.
L(): the angular momentum.
kappa(),kappamax(): the inner multiplicity of .
Free functions
Multiplicities:
u3::Kappa(irrep,L): inner multiplicity (alsokmax,mult).
u3::Rho(A,B,C): outer multiplicity of irrep in product (U3decomposition.h).
Bases:
u3::gelfandBasis(irrep): all Gelfand states of the irrep.
u3::physicalBasis(irrep): all physical states with nonzero .
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 ) with .
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 .
RME_L: the angular-momentum RME, .
RME_Q: the quadrupole RME, carrying an extra (Sec. III H).
Transformation: Both expand a physical state in the Gelfand basis gArr, returning the canonical-state indices and an amplitude matrix with one orthonormal column per .
u3::phys_to_cano(p,M,gArr): the expansion at a single projection .
u3::phys_to_cano_allM(p,gArr): the expansion over all .
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, . For axis sizes , the equivalent flat index is , where an empty product is one. Thus, for a four-axis container, .
data()exposes the underlying flat buffer;size()gives its number of coefficients; andempty()tests whether it contains no coefficients.
print(s)ands << block: output a formatted table of all multiplicity indices and their corresponding values to the streams(defaulting tostd::coutforprint()).
In the equations below, , , , denote U(3) irreps, and , , , , denote selected intermediate irreps in the indicated tensor products, rather than the tensor products themselves. The total irrep is denoted by for three- and four-irrep recoupling. Each labels a particular occurrence of an output irrep in its coupling channel; 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 , reduced with respect to U(2): , where are their fixed U(2) sublabels . Only the outer multiplicity varies within the container, so block(rho) and block[rho] are identical.
rhomax(): the outer multiplicity .
operator()(rho): indexed by .
print(s = std::cout): prints the coefficient row over .
U3SO3: physical coupling of , reduced with respect to SO(3): , where are fixed angular momenta. The three inner multiplicities and the outer multiplicity are the four container axes.
kappaAmax(): inner multiplicity .
kappaBmax(): inner multiplicity .
kappaCmax(): inner multiplicity .rhomax(): the outer multiplicity .operator()(kappaA,kappaB,kappaC,rho).print(s = std::cout): tabular print over .
U3U6: -recoupling: . The labels and resolve the final couplings and , respectively.
rhoABmax(): multiplicity of the coupling.rhoAB_Cmax(): multiplicity of the coupling.rhoBCmax(): multiplicity of the coupling.rhoA_BCmax(): multiplicity of the coupling.operator()(rhoAB,rhoAB_C,rhoBC,rhoA_BC).print(s = std::cout): tabular print over .
U3Z6: -recoupling: . The labels and resolve the couplings and , respectively.
rhoABmax(): multiplicity of the coupling.rhoAB_Cmax(): multiplicity of the coupling.rhoACmax(): multiplicity of the channel.rhoAC_Bmax(): multiplicity of the channel.operator()(rhoAB,rhoAB_C,rhoAC,rhoAC_B).print(s = std::cout): tabular print over .
U3U9: 9- recoupling:
The rightmost entries label the row couplings, and the bottom entries label the column couplings. In particular, labels and is named rhoABCD in the code; labels and is named rhoACBD. The container’s axis order is .
rhoACmax(): multiplicity of the coupling.rhoBDmax(): multiplicity of the coupling.rhoABCDmax(): multiplicity of the route.rhoABmax(): multiplicity of the coupling.rhoCDmax(): multiplicity of the coupling.rhoACBDmax(): multiplicity of the 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 viaoperator(), linear flat indexing viaoperator[], 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} )U3U2: structured container over .get( n^{a}_{13}, n^{a}_{23}, n^{a}_{33}, n^{a}_{12}, n^{a}_{22}, \ldots^{b}, \ldots^{c} )Eigen::RowVectorXd: direct row vector of reduced coupling coefficients across all outer multiplicities . 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 )U3SO3: structured 4D container indexed by .get( \lambda_1, \mu_1, L_1, \lambda_2, \mu_2, L_2, \lambda_3, \mu_3, L_3 )std::vector<double>: flat coefficient buffer laid out in row-major order of , with size .
-recoupling database (
u3::u3u6db()):get_U3U6( A, B, ABC, C, AB, \rho_{AB}, \rho_{AB\,C}, BC, \rho_{BC}, \rho_{A\,BC} )U3U6: structured container indexed by .get( A, B, ABC, C, AB, \rho_{AB}, \rho_{AB\,C}, BC, \rho_{BC}, \rho_{A\,BC} )std::vector<double>: flat buffer of length .get( n^{a}_{13}, n^{a}_{23}, n^{a}_{33}, \ldots, n^{bc}_{13}, n^{bc}_{23}, n^{bc}_{33} )(18 integers)std::vector<double>: raw-integer overload taking the partition labels of , , , , , directly, computing intermediate maxima internally.
-recoupling database (
u3::u3z6db()):get_U3Z6( B, A, ABC, C, AB, \rho_{AB}, \rho_{AB\,C}, AC, \rho_{AC}, \rho_{AC\,B} )U3Z6: structured container indexed by (note the leading , exchanging the first pair).get( B, A, ABC, C, AB, \rho_{AB}, \rho_{AB\,C}, AC, \rho_{AC}, \rho_{AC\,B} )std::vector<double>: flat buffer of length .get( n^{b}_{13}, n^{b}_{23}, n^{b}_{33}, \ldots, n^{ac}_{13}, n^{ac}_{23}, n^{ac}_{33} )(18 integers)std::vector<double>: raw-integer overload taking the partition labels of , , , , , directly.
9-(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} )U3U9: structured container view. Multiplicity parameters follow the container’s axis order: column intermediate channels followed by row intermediate channels .get( A, B, C, D, AB, CD, AC, BD, ABCD, \rho_{AB},\rho_{CD},\rho_{ABCD}, \rho_{AC},\rho_{BD},\rho_{ACBD} )std::span<const double>(orstd::vector<double>): flat buffer of length . Note the multiplicity ordering difference: inget, intermediate row channels precede column channels , whereas inget_U3U9the 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)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 block the phase and normalization are fixed by the highest-weight reduced coefficients—the orthonormal null space of the system imposed by and annihilating the highest-weight coupled state. For (and self-conjugate irreps) the solver fixes a valid orthonormal basis (Row Reduced Echelon Form + Gram-Schmidt + positive leading sign); any alternative must be applied consistently to every -carrying coefficient. Conjugation of a Gelfand state satisfies (
gelfand::conjugate_phase()).Physical-to-canonical transformation: A physical SO(3) state is expanded in canonical Gelfand states with . The highest-weight state belongs to the null space of ; fixes the lower- phases within a multiplet. Distinct conjugate irreps obey (for the transformation is built from the conjugate irrep with the phase factor ). For a self-conjugate irrep conjugation acts as an -independent symmetric matrix () that may mix .
Generator reduced matrix element factor: RME_L/RME_Q carry an extra , so .
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.
| Skill | Example 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 | “ for the SU(3) irrep (3, 1), and for the U(3) irrep [4, 2, 1].” (SU(3): 50/3, 160/9; U(3): =7, 32/3, 56/9, U(3)-only) |
| cano-list | “Enumerate the canonical Gelfand basis of (2, 0) with each state’s , , labels.” (6 states) |
| phys-list | “List the physical SO(3) basis of (4, 2) and verify the dimension sum rule.” (=6, 5, 4, 3, 2, 0 with =1, 1, 2, 1, 2, 1; =60) |
| cano-generators | “Act with on the Gelfand state of (2, 0); give the resulting state and matrix element.” with |
| phys-generators | “Compute and .” ( and ) |
| phys-to-cano | “Express in the canonical Gelfand basis.” (amplitudes , ) |
| inner-mult | “SO(3) multiplicity of in (4, 2)?” (2) |
| outer-mult | “Outer multiplicity of (1, 1) in (1, 1) (1, 1)?” (2) |
| decomposition | “Full decomposition of (2, 0) (0, 2) with outer multiplicities; check the dimension sum rule.” ((2, 2)+(1, 1)+(0, 0)) |
| cano-coupling | “U(3)U(2) reduced coupling for highest-weight states [2, 0, 0] [2, 0] [2, 0, 0] [2, 0] [4, 0, 0] [4, 0] of (2, 0) (2, 0) (4, 0); verify it equals 1.” |
| phys-coupling | “SO(3)-reduced coupling (2, 0) =1 =2 (2, 0) =1 =2 (4, 0) =1 =2; check against .” |
| u6recoupling | “U-recoupling for (1, 0) (1, 0) (1, 0) (3, 0) through intermediate irreps = (2, 0) and = (2, 0).” (1) |
| z6recoupling | “Z-recoupling between and routes for (1, 0) (1, 0) (1, 0) (3, 0) with intermediate irreps = (2, 0) and = (2, 0).” (1) |
| u9recoupling | “9- recoupling for four fundamentals (1, 0) coupling to (4, 0) with intermediate irreps = = = = (2, 0).” (1) |
| conjugation | “Conjugate the SU(3) irrep (2, 1) and its Gelfand states, reporting the phases.” (irrep (1, 2), phase power ) |
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:
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.
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 - and -recoupling coefficients through the pybind11 interface and verifying unitary symmetry relations across fundamental representations (e.g. ). 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 viau3::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-fopenmpconfiguration, 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 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, 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 -tests (unequal variance), reporting , degrees of freedom, and .
Results and discussion
Overall results
Table III and Figure 1 summarize the 60 runs. Across the three tasks:
| Task | Condition | Pass Rate | Total Tokens | Time (s) | Cost ($) | Token | Time |
| Task 1 | Control () | 100% (10/10) | 381,613 80,140 | 58.90 10.51 | $0.2780 | — | — |
| Treatment () | 100% (10/10) | 270,260 93,890 | 46.61 7.88 | $0.2280 | −29.2%* | −20.9% | |
| Task 2 | Control () | 100% (10/10) | 614,511 144,848 | 105.21 20.86 | $0.3751 | — | — |
| Treatment () | 100% (10/10) | 329,829 62,106 | 71.42 7.74 | $0.2499 | −46.3%* | −32.1%* | |
| Task 3 | Control () | 90.0% (9/10) | 654,185 163,874 | 110.73 18.35 | $0.3934 | — | — |
| Treatment () | 100% (10/10) | 320,246 141,267 | 65.89 15.71 | $0.2459 | −51.0%* | −40.5%* | |
| Aggregate | Control () | 96.7% (29/30) | 550,103 178,309 | 91.61 28.85 | $0.3488 | — | — |
| Treatment () | 100% (30/30) | 306,778 104,076 | 61.31 15.21 | $0.2413 | −44.2%* | −33.1%* |
Table III. Empirical performance comparison between Control (Zero Skills) and Treatment (Domain Skills) across independent matched pairs per task (60 runs total) using Claude Sonnet 5.5. Tokens, execution duration, and costs are reported as Mean Standard Deviation. Statistical significance is assessed via two-tailed Welch’s -tests. * (); ** (); *** (Task 2: , ; Task 3: , ; Grand Aggregate: , ; Welch’s two-tailed -test).
Figure 1. Benchmark results comparing autonomous agent performance between Control (Zero Skills) and Treatment (Domain Skills) across 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 sample standard deviation.
Token Consumption: Providing domain skills reduced mean token consumption from 550,103 178,309 tokens to 306,778 104,076 tokens—an aggregate reduction of 44.2% (, , Welch’s -test).
Execution Latency: Wall-clock execution time decreased from 91.61 28.85 s to 61.31 15.21 s, representing an aggregate speedup of 33.1% (, ).
API Cost: Direct inference costs fell from an average of $0.3488 to $0.2413 per task (−30.8%, , ).
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:
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:
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.
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 locatingU3_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.
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 and , 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:
libwignernj: https://github.com/susilehtola/libwignernjEigen3: https://eigen.tuxfamily.orgBoost: https://www.boost.orgOpenMP(via the compiler runtime, e.g. GCC’s libgomp): https://www.openmp.orgpybind11: https://github.com/pybind/pybind11
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 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 and physical coupling coefficients as well as 6- and 9- 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 supermultiplet library u4lib and symmetry-adapted ab initio nuclear-structure framework SAM, while offering a reusable building block for 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 model, the Symplectic model, the ab initio Symmetry-Adapted No-Core Shell Model, and his recent effort in Wigner’s 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]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]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]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]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]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]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]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]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]V. K. B. Kota, “SU(3) Symmetry in Atomic Nuclei,” Springer, Singapore (2020), doi:10.1007/978-981-15-3603-8.DOI
- [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]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]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]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]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]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]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]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]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]A. Krastenov, “Sparse Null Space Solver in C++,” Master’s thesis, Faculty of Information Technology, Czech Technical University in Prague (2026).
- [20]M. Gell-Mann, “Symmetries of Baryons and Mesons,” Phys. Rev. 125, 1067 (1962), doi:10.1103/PhysRev.125.1067.
- [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]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]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]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]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
