Thermodynamic XXX two-spinon structure factor¶

See momentum input near endpoints for distance and beta inputs, conversion warnings, and the current scalar-geometry limit.

XXX family · Supported models

bethe-xxx-structure-factor-thermo evaluates the spectral density of the infinite spin-1/2 antiferromagnetic XXX chain at zero field and temperature. The default is the exact two-spinon contribution. Explicit --sectors 2,4,6 adds finite-domain four- and six-spinon estimates; see selected sectors and numerical controls. Any selection is a partial response, not the full structure factor. Unlike the finite-ring tool, there are no Bethe roots to solve, intermediate states to enumerate, or delta functions to broaden.

See the heat-map tutorial for an iMPS-oriented introduction.

Run a frequency cut or a heat map¶

bethe-xxx-structure-factor-thermo --momentum 1.5 --points 501 --csv cut.csv
bethe-xxx-structure-factor-thermo --sectors 2 --momentum 1.5 --omega 1.8 \
  --precision fp64 --tolerance 1e-12
bethe-xxx-structure-factor-thermo --momentum-points 129 --points 401 \
  --threads 4 --csv spectrum.csv --csv-table continuum=edges.csv

The point example uses the binary64 setting checked in the precision audit. Commands assume an installed executable on PATH; from its build directory, use ./bethe-xxx-structure-factor-thermo. The common precision and export controls apply, including optional fp128 and scalar MPFR (--precision bits-N or digits-N). MPFR does not require MPLAPACK for this scalar integral. For an optional wider-arithmetic comparison of the same point, keep the kernel tolerance fixed:

bethe-xxx-structure-factor-thermo --sectors 2 --momentum 1.5 --omega 1.8 \
  --precision bits-192 --tolerance 1e-12

--max-quadrature-order bounds the Gauss–Legendre refinement (a power of two from 32 to 2048; default 64 for native formats and 256 for MPFR). The separate --max-evaluations budget applies to each spectral point. Raising arithmetic precision does not remove either limit: unmet tolerances produce numerical_failure, with no density or error value. The default absolute transition-integral tolerance is 4096 times the working-precision epsilon. --threads uses the Uni20 scheduler for independent spectral points; output order and numerical results do not depend on the worker count. The bounded observable grid groups 16 adjacent points per task for formats up to a 64-bit significand, amortizing scheduling for cheap samples. Wider formats use individual-point tasks to balance variable quadrature costs. The window holds 128 points or two tasks per requested worker, whichever is larger; metadata reports task size and the resulting point bound. Collection runs on the calling thread in momentum-major order, without a whole-window barrier or a separate full-grid result vector. Tables retain their rows by default; use --no-retain with a machine format, --stream or --quiet to disable that storage.

The final summary of both tables reports Failed points and Divergent threshold points; these counts are not available in the initial metadata. CPU timing scope identifies the complete spectral-grid calculation, including ordered row output. Continuum-table output is outside that interval.

Option	Meaning
`--momentum Q`	One momentum in radians/site, in \([0,2\pi]\)
`--momentum-points N`	Uniform momentum grid including both endpoints; default 65
`--omega W`	One frequency, instead of a frequency grid
`--points N`	Uniform frequency grid including both endpoints; default 201
`--omega-min W`, `--omega-max W`	Frequency range; default \([0,\pi J]\)
`--exchange J`	Positive antiferromagnetic coupling; default 1
`--channel zz\\|raising`	Longitudinal density or \(S^{-+}=2S^{zz}\); default zz
`--tolerance T`	Absolute error target for the transition-rate logarithm; default 4096 machine epsilon
`--max-evaluations N`	Kernel integrand evaluations per point; default 200000

Single-point options exclude their corresponding grid options. Grids are limited to one million total points. Inputs are validated before opening output files.

For the default two-spinon calculation the frontend produces two tables:

spectrum (primary): q, omega, sector, density, estimated_error, evaluations, status.
continuum: q, lower, upper at each momentum.

For example, --csv-table continuum=edges.csv exports the named auxiliary table. An unknown or unavailable table name is an error. Higher-sector calculations also support the explicitly requested diagnostics and replicates tables; see selected sectors. See output and exports.

Conventions and exact expression¶

\[ H=J\sum_j \mathbf S_j\cdot\mathbf S_{j+1},\qquad J\gt0, \qquad S_q^z=\frac1{\sqrt N}\sum_j e^{-iqj}S_j^z. \]

The returned density has the same convention as the finite tool: \(S(q,\omega)=2\pi\sum_n w_n\delta(\omega-E_n+E_0)\) before taking the thermodynamic limit. It is not \(S/(2\pi)\) and is not a discrete weight.

For \(J=1\), write

\[ L(q)=\frac\pi2|\sin q|,\qquad U(q)=\pi\sin(q/2),\qquad \cosh(\pi\rho)=\sqrt{\frac{U^2-L^2}{\omega^2-L^2}}. \]

Inside \(L\lt\omega\lt U\),

\[ S^{zz}_2(q,\omega)=\frac{e^{-I(\rho)}}{2\sqrt{U^2-\omega^2}},\qquad I(\rho)=\int_0^\infty\frac{e^x}{x} \frac{\cosh(2x)\cos(4\rho x)-1}{\cosh x\sinh(2x)}\,dx. \]

These are Eqs. (9)–(12) of Caux and Hagemans. Coupling scales energies and the density as \(S_{2,J}(q,\omega)=S_{2,1}(q,\omega/J)/J\).

Thresholds are not numerical failures¶

The density vanishes outside the continuum and approaches zero at its upper edge. At the lower edge it diverges, with a logarithmic enhancement of the inverse-square-root singularity. At \(q=\pi\) the low-frequency behavior is \(\sqrt{\log(1/\omega)}/\omega\). Karbach, Müller and Bougourzi analyze these limits.

Status	Density/error fields	Exit status
`converged`	Finite value and estimated numerical error; upper-edge limit is zero	0
`outside_continuum`	Exactly zero	0
`lower_threshold`	Empty (JSON null): no finite point value exists	0
`numerical_failure`	Empty (JSON null): budget, precision or representable-range limitation	2

At \(q=0,2\pi\), the density is zero by total-spin conservation, including at zero frequency. Negative frequencies are zero at zero temperature. The continuum can become unresolvably narrow near zero momentum; this is not silently treated as a computed peak.

The numerical error is an estimate for the evaluated point, not an interval certificate. It does not account for uncertainty in the supplied frequency or its distance from a threshold. Raising the precision is useful near an edge. A plotted point grid is not an integration rule for these singular functions; do not infer sum-rule saturation from a coarse rectangular sum. In particular, the fixed-\(q=\pi\) zeroth moment diverges even though the momentum-integrated intensity is finite. Frequency-bin integrals and broadening are not yet provided by this frontend.

Stable evaluation and validation¶

The original integral has a conditionally convergent oscillatory tail. With \(a=4|\rho|\), the implementation subtracts \(2(1-e^{-2x})\cos(ax)/x\) and integrates that part analytically: \(\log(1+4/a^2)\). With \(u=e^{-2x}\), the remainder is

\[ R(x,a)=\frac{2u^2(3-u^2)\cos(ax)-4u}{x(1-u)(1+u)^2}. \]

Near zero, an equivalent expression using sin, tanh and expm1 avoids cancellation. Beyond \(X\ge1\), its absolute tail is bounded by \(8e^{-2X}/X\). Composite Gauss–Legendre rules generated at the requested precision use panels no wider than half an oscillation. Rule differences, a roundoff allowance and the tail bound supply the error estimate. Energies are compared through factored differences and the transition rate is assembled logarithmically.

Tests cover independent quadrature references, all enabled scalar precisions, reflection symmetry, coupling scaling, threshold behavior and failure statuses. MPFR accuracy grows at 80/160/256/333 bits against separate 105- and 130-decimal-digit tanh-sinh evaluations with a different analytic subtraction and panel spacing. Tests also check the published two-spinon fractions: approximately 72.89% of the full integrated intensity and 71.30% of the first frequency moment. These are physical partial-sum fractions, not tolerances or fitted scale factors. The optional reference script uses mpmath and a different analytic tail subtraction.

The C++ entry point is bethe::heisenberg::ThermodynamicTwoSpinonStructureFactor<Real> in xxx_thermodynamic_structure_factor.hpp. MPFR callers construct StructureFactorOptions<uni20::mpreal> with a finite uni20::Precision, then supply exchange, momentum and frequency at that same precision. The evaluator owns its controls and quadrature rules; it is immutable and can be shared between scheduler jobs. The rapidity-difference kernel is separate from continuum kinematics.

Scope¶

This tool implements only the exact two-spinon contribution. Higher-spinon spectral weights are not provided; numerical integration errors must remain distinct from the physical weight absent from this partial contribution.