Model roadmap and literature survey¶

Supported models · Bibliography

This is a living, non-exhaustive catalogue, with an emphasis on models whose energies would be useful alongside Uni20 and MPToolkit. A model being exactly solvable in the literature does not mean this repository solves it, or that every boundary condition, coupling, or excited state is covered.

Use this document according to the question you want to answer:

• What can I calculate? Use the supported-model index, then follow the model guide.
• What equations and limitations matter? Read the model-by-model notes and extensions of existing models.
• What could we add? Browse the wider catalogue, thermodynamics and shared machinery.
• What is the MPS excitation sequence? See the separate goal and completion record.

Initial survey: 2026-09-22, implementation baseline 6a414cc. Coverage is updated as implementations land. Priorities and difficulty assessments are engineering judgments, not conclusions of the cited papers or a committed schedule.

Reading and maintaining the catalogue¶

Status and effort labels¶

Entry IDs are stable handles for issues and model guides. Status has a deliberately narrow meaning:

• Implemented (limited): executable/API coverage exists; follow its guide.
• Proposed: a useful first implementation is outlined, but no solver exists.
• Watch: established literature, with scope or numerical machinery still to investigate before implementation.
• Related: an exact benchmark worth considering, but not necessarily a conventional finite-size Bethe-root calculation.

For a proposed slice, small means mostly equations, conventions, and validation using existing numerical tools; medium includes new sector or nested-root handling; large includes complex roots, singular solutions, functional equations, or a different spectral problem. These are relative technical risks, not estimates in days. A small ground-state implementation can have a much harder excitation extension.

Updating an entry¶

Record enough detail to distinguish a supported calculation from a solvable model family:

• Hamiltonian, energy shift, statistics/local representation and integrable coupling restrictions.
• Boundary conditions, supported sectors/root families, and finite-size versus thermodynamic scope.
• Reference IDs, validation tests and the next unresolved step.
• Once implemented, the model guide and implementation commit.

Do not mark an entire family implemented because one slice works. New entries need an original solution or explicit Bethe-equation source; before coding, audit the chosen branch's equations and normalization separately.

Literature policy¶

Bibliographic metadata belongs in data/citations.json. Catalogue-only references appear in CITATIONS.md, not in any executable's --references output, until a supported method actually uses them. See citation maintenance. The links in this document identify literature starting points; they are not a claim that we implement a cited paper's correlation functions, thermodynamics, or full spectrum.

Current coverage¶

For programs you can run now, use the supported-model index. This roadmap preserves the literature survey, original proposed slices and remaining extensions. It is not the command reference or a committed schedule.

Candidate index¶

Entries with implementation/guide links have the stated limited coverage; proposed or watch entries are not CLI capabilities. Boundary conditions shown are starting targets, not a classification of all integrable boundaries in the literature.

Leading proposals¶

These are the original leading candidates, now mostly implemented in limited slices. Each entry preserves its equation sources, validation evidence and remaining extensions; it is not a new implementation queue.

lieb-liniger: the simplest new interacting family¶

The continuum Bose gas has contact interactions. In units \(\hbar ^{2}/(2m)=1\), one common convention is H=-sum_j d_j^2 + 2c sum_(i<j) delta(x_i-x_j). For c>0 its finite-ring Bethe momenta are real, with E=sum_j k_j^2. The original solution and the two excitation branches are in Lieb–Liniger I and Lieb II.

Implemented in lieb_liniger.hpp and bethe-lieb-liniger-pbc: physical length ell, N bosons, c>0, consecutive ground labels, explicit labels, and scans over N occupied slots in an N+2P window. Implementation commit: 4ba617c. See the guide for units, parity, residual scaling and limits. Tests cover two-/three-body analytic values, weak coupling, the impenetrable-boson (Tonks–Girardeau) limit, boosts, all three precisions, finite windows, and convergence to a separately discretized bulk integral equation. The implementation checkpoint passed 285 tests with GCC 13 and fp128 enabled, 198 with Clang 20 Release without MPLAPACK, and the new CLI suite in an app-only build using the published Uni20 pin (no sibling-source override).

The hard-wall library and CLI add ground states, selected positive-integer labels and finite-window scans using reflected scattering. It shares Newton iteration and rational kernels with the ring, but owns its boundary equations: Gaudin (1971). Attractive c is a separate bound-state problem, not a sign toggle on a real-root solver. Nor does all make sense without an energy or quantum-number cutoff: even a fixed-N continuum system has infinitely many levels.

The thermodynamic library and frontend now supply Q, energy per length, chemical potential, and type-I/type-II dispersions using mesh-verified integral equations and physical-momentum inversion. The repulsive finite-size and zero-temperature bulk slices are complete; The finite-temperature Yang–Yang library also supplies grand-canonical pressure, density, energy, and entropy with separate mesh and cutoff checks, plus fixed-density inversion and a temperature-scan frontend; attraction remains a separate bound-state project.

su-n: permutation chains and the spin-1 ULS point¶

Take one fundamental n-state degree of freedom per site and the antiferromagnetic Hamiltonian H=J sum_j P_(j,j+1), J>0, where P exchanges neighboring colors. This is the SU(n) permutation chain associated with Sutherland's multicomponent solution. It is a direct lattice benchmark for non-Abelian tensor-network calculations.

SU(3) is especially attractive: in a spin-1 basis, \(P = S_{i} .S_{j} + (S_{i} .S_{j})^{2} - 1\). Thus it also supplies the Uimin–Lai–Sutherland (ULS) bilinear–biquadratic point, after an explicit per-bond energy shift. The identity follows from the two-site total-spin eigenvalues; this is not the generic spin-1 Heisenberg chain.

Implemented in su3.hpp and bethe-su3-pbc: periodic, J=1, balanced singlet for L>=3 divisible by three, with finite real roots. The state keeps explicit populations and two separate root/label arrays, with M1=2L/3 and M2=L/3. Implementation commit: 3970675. See the guide for the equations, normalization, ULS conversion, and numerical limits. The equation audit uses Doikou–Nepomechie, including the filled-sea selection in Sec. 2.3; our energy is twice the paper's plus L.

Tests cover three-/six-site analytic roots or energies in every precision, independent color-space ED and translation through L=9, original multiplicative and logarithmic equations, Jacobians, the SU(2)/XXX reduction, and the spin-1 permutation identity. Finite chains through L=192 approach the known bulk energy density. The implementation checkpoint passed 315 tests with GCC 13 and fp128, 219 with Clang 20 Release without MPLAPACK, and the new frontend and citation checks against the published Uni20 pin in an app-only build.

The thermodynamic excitation frontend now supplies native 3/bar3 dispersions, distinct two- and four-soliton bounds, representation labels and three-site folding. It retains the lower multiparticle threshold between the soft momenta; a two-particle envelope is not the full local-response spectrum.

Next slice: audit other finite-ring color sectors and excited-root families, including lengths not divisible by three. General n adds n-1 nesting levels; complex strings, descendants, twists, and open ends need their own state and equation treatment. The two-level SU(3) state does not change the Hubbard API or claim an arbitrary-rank solver.

gaudin-yang: the continuum counterpart of nested Hubbard¶

This is the equal-mass spin-1/2 Fermi gas with delta interactions, solved by Gaudin and Yang; Yang's scattering construction also treats attraction. It combines continuum charge momenta with an auxiliary spin-rapidity family.

The first slice should be repulsive periodic ground states in explicitly validated particle/spin sectors, followed by polarization and charge/spin excitations. Reuse nested Newton and continuation concepts, not Hubbard's sin(k) kernels, energy formula, or finite-ring shell selection. Validate the noninteracting and fully polarized gases, the two-body problem, and strong-coupling behavior; the dilute Hubbard limit is an additional check only after matching units and taking a controlled continuum limit.

Attraction introduces paired complex charge roots. The bipartite-lattice Shiba shortcut used for Hubbard is not a corresponding continuum sign-change mapping; finite-size paired states need their own treatment. Multicomponent fermions add more nesting levels and, for attraction, larger bound complexes; see Lee–Guan–Batchelor.

Implemented first slice: commit 6b7fc3c adds bethe-gaudin-yang-pbc and the scalar-templated bethe::gaudin_yang::ground_state(N_up,N_down,ell,c) API. Interacting mixed-spin states require odd populations of both spins; c=0 and full polarization use exact free occupations for any particle count. The model guide specifies physical units, nested labels, free-current degeneracy, spin reversal, and incomplete-continuation diagnostics. The explicit equations and sector choice follow Oelkers et al., especially Eq. (25) and Sec. 5.

Validation includes the original rational equations, an independent two-body jump-condition oracle, exact free energies, weak/strong-coupling coefficients, the XXX spin-root limit, controlled dilute-Hubbard convergence, analytic-Jacobian checks, and fp64/long-double/fp128 precision tests. The complete suite at this checkpoint passes 344 GCC Debug tests with fp128 and 239 Clang Release tests without MPLAPACK; the front end also passes its CLI checks against the published Uni20 pin without a sibling-source override.

Next slice: other periodic shell branches need a separate finite-ring state-selection audit, not just shifted centered labels. Then consider charge/spin excitations or hard-wall reflection equations. Attraction still requires paired complex roots; no lattice particle-hole shortcut applies.

tj-susy: a useful strongly correlated lattice benchmark¶

The local states are empty, up, and down: double occupancy is projected out. For the convention H=-t sum(projected hopping+h.c.) + J sum(S_i.S_(i+1)-n_i*n_(i+1)/4), target the supersymmetric J=2t point, not arbitrary J/t. Use the explicit alternative nested Bethe ansätze in Essler–Korepin.

Implemented in tj.hpp and bethe-tj-pbc, using Sutherland's BFF grading: \(M_1 =N_{h} +\min (N_{\mathrm{up}},N_{\mathrm{down}})\), \(M_2 =N_{h}\). The doped real-root family requires odd populations of both spins, on odd or even L. No-hole states use \(H_{\mathrm{tJ}} =2\,H_{\mathrm{XXX}} -L /2\); fully polarized states are exact free fermions for every particle count. The guide derives the label parities, energy shift, and fermionic translation phase and states the unsupported sectors explicitly.

Tests compare energies and momenta with an independent projected Fock-space Hamiltonian through L=8, check the original rational equations and analytic Jacobian, and retain native precision in analytic limits and solves through L=96. Invalid shell branches are rejected, not replaced by a nearby filling or spin. There is no mu-mu self-scattering term; SU(3)'s nested equations cannot be reused unchanged.

Next slice: audit other doped population parities and their real/complex root families before extending the public state selector. Excitations and integrable open boundaries need separate labels/equations. Arbitrary J/t is outside this model's implemented integrable point.

spin-s-tb: spin-1 first, with genuine complex-root support¶

The integrable higher-spin chains of Babujian have specially chosen polynomial exchange interactions. At spin 1 the Takhtajan–Babujian (TB) point is proportional to sum[S_i.S_(i+1) - (S_i.S_(i+1))^2]. It is neither the ULS point above nor the generic bilinear spin-1 chain.

Although there is only one nesting level, the antiferromagnetic ground state already involves complex two-string patterns. Finite-size deviations matter: Vlijm–Caux provides a numerical starting point. Solving ideal string centers alone must be labelled an approximation, not an exact finite-chain energy calculation.

Implemented in takhtajan_babujian.hpp and bethe-tb-pbc: even L>=4, zero-field singlet, bilinear coefficient 1 (J=4 in Vlijm–Caux). The filled sea's centres and positive deviations are solved together with an analytic Jacobian; ideal strings are not substituted for the finite roots. The guide records the branch, equations, normalization, precision and failure contract.

Tests check original complex equations through L=128 in all scalar types, independent spin-basis energies and translation at L=4,6,8, native-precision E_4=-11-sqrt(41), the Jacobian and incomplete-solve diagnostics.

The thermodynamic frontend, bethe-tb-dispersion, supplies native-precision spin-1/2 spinon lines and two-/four-spinon energy envelopes, with total-spin selection rules, two-site folding and the explicit factor-four conversion from Vlijm–Caux. It reuses the common spinon-band kinematics; SU(2)_2 state counting and spectral weights are not inferred from those bounds.

Next slice: finite-ring broken-string excitations require real and three-string roots, singular-solution handling and new label branches. Other spin, magnetization, odd lengths and open boundaries are not covered by this ground-state implementation.

temperley-lieb: shared energies, different representation multiplicities¶

The spin-1 pure biquadratic chain H=-sum(S.S)^2 realizes the open TL algebra at loop weight 3, with \(e_{i} =(S_{i} .S _{i +1})^{2}-1\). The corresponding spin-1/2 XXZ representation has Delta=3/2 and opposite end fields: ordinary zero-field bethe-xxz-obc is not the reference Hamiltonian. The physical energy is \(2\,E_{\mathrm{ref}} -7\,(N -1)/4\) in our spin-half exchange-1 normalization. Within a TL module the energies agree after this mapping, but representation multiplicities and physical spin labels do not.

Implemented in temperley_lieb.hpp, biquadratic.hpp, and bethe-biquadratic-obc: even N>=2, free-end ground state, TL module minima and restricted real-root excitations. --through-lines selects a module, --sectors lists minima, and --excitations COUNT|all enumerates the supported label family (default ell=2). Each level carries the spin-1 representation multiplicity, while gaps refer to the global singlet ground state. Here all never denotes the full module spectrum. A separate Q-system solver adds selected complex-root levels (--q-seed) and bounded small-chain module searches (--q-spectrum, validated through N=8; larger N experimental); missing/unverified levels produce an explicitly incomplete result, not a lowest-level guarantee. The lower TL layer supports the same real-root slice at general lambda>2 and a checked integer multiplicity helper for singlet-projector spin-chain representations. See the guide for the Bethe equations, energy shifts, precision contract, and full small-chain ED spectral checks. The separate two-string solver targets a low-lying complex-root singlet on long chains (--singlet-excitation), retaining finite string deviations in logarithmic coordinates; it does not enumerate singlets.

For H=+sum(S.S)^2, ferromagnetic excitations reuse the same root equations with reversed physical energy ordering and the exact degenerate ground reference. The full one-defect module and global positive gap are analytic, for odd and even lengths. General module minima are not obtained by reversing a truncated AF list: real-root scans can miss complex-root minima, while Q-system coverage remains budget-dependent. The bound-pair solver targets the ell=N-4 two-string family directly on odd/even long chains, retaining both signs of the finite deviation. The three-string solver adds ell=N-6 droplets with a complex finite-size deviation, sharing the Newton driver and reporting code. Neither enumerates the scattering spectrum. Real-root scattering windows reuse the existing equations with a bounded high-label range, avoiding a chain-length-sized enumeration. Direct gaps also preserve ordering when total energies round to the same value. Selected states and bounded pair-plus-real-root scans reuse the two-string solver; combined with the other two three-defect families, it reproduces the entire ell=N-6 module spectrum for N=6,...,10. The mixed CLI uses the same cluster tables and native-precision exports, with candidate budgets and explicit partial-convergence reporting. The library and CLI extend to one pair plus several selected real roots, with shared budgeted combination scans; four-/five-defect examples are validated as ED subsets, not full spectra. A two-bound-pair solver and CLI scans add another four-defect subset, retaining both signed logarithmic deviations and sharing the single-pair equations, energy mapping and Newton driver. A three-string plus real-root solver and CLI scans reuse the isolated triple and a general external-scattering kernel; the four-string droplet solver and CLI completes the five four-defect topologies, with joint module-spectrum validation through N=10 (not a general completeness proof).

Literature: Barber–Batchelor, Albertini, and Aufgebauer–Klümper.

The physical SU(2) decomposition of open spin-1 TL multiplicity spaces is available in the shared library and optional --spin-content table, separately from auxiliary XXZ spin. Next slice: higher-defect complex-root families and state-dependent spectral weights. Odd free-end chains require a one-spinon/domain-wall branch, not a doubled dimer ground state. PBC requires twisted XXZ references and different representation bookkeeping; general TL, RSOS and boundary-algebra models are not automatically covered by this first spin-chain implementation.

richardson: finite pairing spectra without a spatial chain¶

The reduced BCS Hamiltonian has specified single-particle levels and a uniform pair-scattering coupling. Richardson's solution and its Gaudin generalizations are surveyed by the model developers in Dukelsky–Pittel–Sierra. This would broaden the library to pairing benchmarks at fixed particle number.

Implemented in richardson.hpp and bethe-richardson for g>=0, distinct ascending single-particle energies, one time-reversed doublet per level, and specified pair/blocked sectors. The diagonal pair-scattering term is included. The guide derives the energy convention and regularized quadratic equations from Faribault et al..

Adaptive ground-state continuation uses a number-constrained rectangular QR correction in native precision, with branch-distance and energy-bound checks. Tests include all small pair sectors of irregular/clustered levels, blocked levels, analytic limits and the exact four-level g=2/3 root collision. Incomplete results explicitly retain their reached coupling; they are not reported as energies at the requested target.

Next slice: optional rapidity recovery, excited occupation seeds, and the derivative equations needed for repeated levels/higher degeneracies. PBC/OBC and lattice momentum are not appropriate interface concepts here.

gaudin-magnet: a central-spin realization¶

Implemented in central_spin.hpp and bethe-central-spin: H=B*S0^z+sum A_j*S0.Sj, all spins 1/2, distinct nonzero A_j of either sign, fixed total Sz, and any finite central field including B=0. There are no bath fields/interactions. See the guide for the rational Bethe equations, normalization and compactified eigenvalue-variable continuation. Implementation checkpoint: 8ff2f52.

This reuses the regularized-equation and native QR machinery developed for Richardson, but uses a central-spin-specific high-field ground seed. The connected star's sign-gauged exchange matrix gives a noncrossing sector-ground branch. Tests compare all small sectors with independent spin-basis diagonalization, check the two-spin formula and original one- and two-root rational equations, and cover zero-field multiplets, clustered couplings, larger baths and all three scalar types. Incomplete solves report only a reached-field energy; the infinite-field seed has none. The implementation checkpoint passed 747 tests with GCC 13 and fp128, 511 with Clang 20 Release without MPLAPACK, and the new CLI/citation checks in an apps-only build using the published Uni20 pin. An additional 180 fixed-seed random small-sector checks agreed with independent diagonalization.

Next slice: repeated couplings/grouped spins, decoupled zero-coupling bath spins, excited high-field seeds or observable matrix elements. This does not implement arbitrary Gaudin Hamiltonians or central-spin dynamics from the reference paper.

multicomponent-gas: arbitrary-rank repulsive fermions¶

Implemented in su_fermions.hpp and bethe-sun-fermions-pbc for equal masses, equal positive contact couplings 2c delta, periodic circumference ell, and fixed component populations. Every occupied interacting population must be odd; c=0 and single-component limits allow arbitrary counts. Empty components are retained as metadata but removed from the nested problem. The guide derives the label parity and equations from Sutherland and Lee et al..

Strong-to-weak continuation solves all real-root seas in native precision, with analytic Jacobians and relative weak-cluster residuals at every level. Incomplete solves retain only a previously converged coupling, never a seed energy or an intermediate energy mislabeled as the requested c. Tests include rational equations, the Gaudin–Yang reduction, the one-particle- per-component Lieb–Liniger equivalence, free/weak/strong limits, a separate plane-wave Hamiltonian for populations 3,1,1, and six-component 30-particle sweeps. The spin-chain SU(3) frontend remains a different model. The implementation checkpoint passed 774 tests with GCC 13 and fp128, 530 with Clang 20 Release without MPLAPACK, and the new CLI/citation checks in an apps-only build using the published Uni20 pin.

Next slice: other finite-ring shell branches and excited seas/strings. The distinct equal-coupling Bose–Fermi mixture library now implements odd-fermion ground shells using its own graded equations, not by treating bosons as another fermionic color.

integrable-ladder: singlet/triplet sector competition¶

Implemented in ladder.hpp and bethe-ladder-pbc: periodic L>=2 rungs, spin-1/2 leg coefficient 1, four-spin coefficient 4, any finite rung exchange J_r and longitudinal field h. The guide gives the exact SU(4) permutation identity, energy constants, shifted finite-ring labels and state-selection rules. The rung coupling is a chemical potential for singlets; all triplet populations are minimized within each specified singlet-count sector, including their Zeeman energy. Nonzero fields select extremal triplet weights by SU(4)-to-SU(3) interlacing; zero field preserves a balanced representative.

Three nested real seas are solved in native precision for the packed ground branches of compatible Young diagrams, including displaced seas and SU(4) descendants. This extra bookkeeping is essential: already at L=6, the populations 4,1,1,0 have a lower descendant from the 4,2,0,0 multiplet than their own highest-weight sea. Reports preserve this distinction rather than claiming descendant rapidities are finite. Incomplete scans retain candidate upper bounds only. The all-singlet product for J_r-|h|>=4 and the polarized triplet product for |h|>=4+max(J_r,0) have direct analytic ground-state paths.

Tests compare all singlet-count sectors through seven rungs against independent permutation matrices and small literal spin-basis ladder Hamiltonians, as well as the original rational equations, momentum, SU(2)/SU(3) reductions and algebraic native-precision regressions. This is not a complete excited-state solver or a general nested-Bethe completeness proof; budgets cover the entire multiplet scan. The implementation checkpoint passed 795 tests with GCC 13 and fp128, 545 with Clang 20 Release without MPLAPACK, and the new CLI/citation checks in an apps-only build using the published Uni20 pin. A 32-rung fp128 global scan also converged within the default budgets.

Field-dependent populations and magnetization are checked against exhaustive weight enumeration and independent finite-ring Hamiltonians. Fixed-Sz constraints are also implemented, optionally combined with fixed singlet count. Integer weight-membership bounds select compatible multiplets without changing the nested equations; independent population and literal spin-basis sector matrices validate the results. Next slice: explicit excited branches, with new finite-ring state-selection checks. The ordinary two-leg Heisenberg ladder at generic couplings is not integrable here.

Extensions of current models, rather than new solvers¶

• Wider XXZ anisotropy: the periodic ground-state/sector path now includes \(\Delta \gt 1\), retaining a continuous atan2 scattering phase in scaled real coordinates. The source is Dugave et al., Eqs. (1.1)-(1.2), with energy normalized from Pauli matrices to spin operators. Tests cover odd/even sector energies and momentum against ED, original trigonometric equations, native precision, continuity to XXX, and Ising limits. The massive free-end module now solves the ground-state sectors through the same ground-state API and bethe-xxz-obc, retaining the finite-size boundary-root deviation explicitly. The negative-anisotropy engine now covers \(-1\lt \Delta \lt 0\) sector ground roots for even rings and open chains, with rank-subtracted equations scaled to remain discriminating near Delta=-1. Both paths are exposed through the ground-state APIs and existing frontends, with explicit hyperbolic coordinates and scaled residuals. The periodic ground result is distinct from the real-excitation type; negative odd rings remain internal and are deferred until a concrete calculation needs them. The polynomial equations and an internal momentum-constrained adaptive driver now handle conjugate-pair formation without extracting roots, with independent spin-basis energy checks through 21 sites at selected couplings. A separate quantum-Wronskian diagnostic tests generic-q consistency; nonzero projected spin helices cover the phantom collision without incorrectly applying the finite-root theorem there. An all-sector candidate scan now compares every folded sector and withholds the minimum if any solve fails, with all-sector ED checks through 17 sites at selected couplings. A regular-state criterion now tests the Gaudin nonzero-vector hypotheses directly in coefficient space. Projected spin helices are available as explicit eigenstates at commensurate couplings; a separate diagnostic recognizes the all-phantom odd-ring collision. The mixed-phantom reduction checks the twisted finite equations after endpoint deflation; general nonzero lifting remains open. A coordinate dressing map now constructs lifted amplitudes and exposes the nonzero-lift issue with explicit kernel tests. A finite-root amplitude evaluator supplies its input using subset sums, with native-precision direct Hamiltonian checks. Native root recovery now connects the continued and reduced polynomials to explicit vectors, including tested mixed-phantom lifts with three and four finite roots. It reports unresolved clusters instead of treating them as distinct roots. A bounded nonzero-amplitude diagnostic now adds numerical mixed-phantom witnesses to the sector scan, with propagated root-uncertainty estimates and visible work limits. Independent free-sea and projected-helix variational upper bounds now reject continuation energies incompatible with a sector minimum; passing these necessary checks is not a proof of minimality. Deferred: do not extend this internal investigation or expose it as a public ground-state solver without a concrete need. Preserve the code and tests; the restart checklist records the branch-selection, singular-state, numerical-failure, and API issues. This work does not block other models. Negative-Delta excitation classification remains a separate later extension. The broader family is established by Yang–Yang, but the old real-coordinate domain and excitation window do not extend unchanged. Treat \(\Delta \le -1\) and polarized/degenerate limits separately. These remain XXZ-module extensions, not differently named models.
• Spinless t–V fermions / nearest-neighbor hard-core bosons: useful physical interfaces to XXZ, not independent Bethe engines. Under the usual convention the anisotropy is V/(2t), but the hopping-sign gauge, fermionic parity twist on a ring, density-dependent constants, and OBC endpoint terms must be derived for the declared Hamiltonian. Never reuse a spin-chain energy or momentum without this translation.
• Uniform fields and chemical potential: a commuting term gives \(E (h,\mu)=E (0,0)-h \,S^z -\mu \,N\) within a solved sector. The global minimum still requires comparison across all relevant sectors; incomplete PBC Hubbard coverage cannot give an unrestricted grand-canonical minimum. This needs sector scanning/reporting, not new Bethe equations.
• Flux/twists: useful for persistent currents and stiffness; the boundary phases enter the equations and can change the lowest branch. See Shastry–Sutherland. Track crossings and symmetry mappings at the requested twist instead of retaining the zero-flux quantum numbers unconditionally.
• Integrable boundary fields: start with diagonal boundaries preserving the conserved projection; consult the reflection-matrix construction of de Vega–González-Ruiz and the existing open Hubbard reference. Boundary bound states can change the root content. General boundary fields are not obtained by merely adding a post-solve energy term.
• Hubbard excitations and missing ring sectors: start with explicitly admissible nested label changes and small-ring ED; add complex spin and charge–spin bound states only with appropriate equations. Keep energies produced by symmetry mappings distinct from physical attractive roots. The Hubbard guide and its literature are the starting point. Half-filled repulsive thermodynamic elementary lines and doped zero-field lines are now separate implemented functionality, with both interaction conventions and Fermi energy references. The half-filled two-spinon continuum library and frontend now supply both edges by reusing the elementary spinon evaluator. A native charge-containing continuum library now resolves three additional two-particle families, exposed through the same frontend's --channel option. The elementary holon is not automatically a sector minimum.

Wider catalogue: useful, but not the next default targets¶

An additional non-unitary target is now underway: the quantum-group-invariant XXZ chain with imaginary boundary fields. Its positive finite-real-root library and bethe-xxz-qg-obc frontend cover 0<Delta<1 in native precision, with independent non-Hermitian spin-basis checks. --excitations COUNT|all scans bounded regular label families for low-lying converged states, with explicit failures and gaps relative to the selected sea. A separate native Delta=0 construction, exposed by the same frontend with --delta 0 --sz ..., enumerates complete fixed-magnetization spectra with size-one/two Hamiltonian Jordan blocks and budgeted output. Complex branches, other roots of unity, and explicit spin-basis Jordan vectors remain distinct checkpoints. This must not be confused with the zero-field free-end XXZ frontend or with a restricted RSOS/loop representation.

The following entries deliberately remain short until selected for an equation-level feasibility study. Each has a concrete restriction and an initial deliverable, rather than an unqualified claim of model support.

Other recognized families can be added as research needs arise: anisotropic multicomponent/Perk–Schultz chains, integrable higher-spin anisotropic chains, supersymmetric extended Hubbard models, and quantum Toda systems. They are not yet individual proposals here: choose an explicit Hamiltonian, representation, boundary, and source before creating a tracked entry.

Thermodynamics is a separate capability¶

There are two different questions: "what is the energy of this finite-chain state?" and "what is the bulk energy density or finite-temperature free energy?" Root-density equations and TBA answer the second question without enumerating finite-system eigenstates. The natural first target is the repulsive Lieb–Liniger Yang–Yang equation, Yang–Yang (1969); it has a much simpler hierarchy than spinful/nested thermodynamics.

The grand-canonical Lieb–Liniger library now implements this first TBA slice, with native-precision quadrature and independent nonlinear, mesh, and cutoff checks. Pressure derivatives, the zero-temperature limit, and the Tonks fugacity series provide validation. Canonical fixed-density inversion and a temperature-scan frontend are also available. This model-specific layer is not a universal TBA engine, and thermodynamic answers must never silently replace finite-system eigenstates.

Shared machinery and module boundaries¶

Continue with one model module and thin, boundary-appropriate front ends. Share numerical mechanisms when their contracts really agree:

Keep scalar precision, presentation, timing, and citation rendering shared. Continue using Uni20 for numerical linear algebra; if complex solves or special functions expose a genuine missing facility, specify its precision, failure semantics, and tests in cooperation with Uni20 development. Do not introduce a silent double-precision dependency into a high-precision model. No language change or giant runtime-switched "all models" solver is needed.

Suggested sequence and first acceptance evidence¶

1. Repulsive Lieb–Liniger PBC: ground state and explicit labels, followed by finite-window excitations; two-body and limiting-case checks in every precision. Hard walls are the next boundary slice, not part of the first implementation by implication.
2. SU(3) PBC balanced singlet: first slice complete, with small-chain ED, native-precision analytic checks, and documented nested labels. Gaudin–Yang PBC: the first odd-population sector slice is also complete, with independent two-body/limiting-case checks, dilute-Hubbard convergence, and documented physical and auxiliary labels.
3. Wider XXZ ground-state coverage and t–J at J=2t: extend lattice benchmarks while keeping branch/parameter restrictions explicit.
4. A focused complex-root project: start with a small known XXX string and the spin-1 TB ground state, or Richardson pairing if that application matters more. Success means finite-size deviations and collisions are tested, not just that an ideal-string energy looks plausible.
5. Lieb–Liniger thermodynamics, then whichever wider entry a concrete Uni20/MPToolkit calculation needs. The catalogue can grow independently of this suggested order.

For each implementation, require an independent Hamiltonian or limiting-case check, original-equation residual checks, native long-double/fp128 tests that would detect narrowing, and explicit failure reporting. Ground-state claims need state-selection evidence, not just a converged root set. Completeness claims additionally need counting, degeneracy, and singular-state tests.

What this catalogue must not imply¶

Generic spin-1 bilinear exchange, arbitrary bilinear–biquadratic angle, generic Bose–Hubbard chains, arbitrary t–J ratios, and arbitrary ladder or boundary couplings are not supplied with a Bethe solver merely by their relation to an integrable example. An exactly known ground state (such as an MPS parent-Hamiltonian state) is also not an exact Bethe spectrum. The tracked objects are explicit integrable Hamiltonians and well-defined solution sectors, not broad model names stripped of their restrictions.