Experimental numerical components¶

The selected finite-four-spinon solver adds explicit finite deviations and stabilized raising weights to the common finite-XXX foundation. The finite-four scanner adds bounded catalogues, Async execution and an experimental table/export frontend.

Experimental components live under experimental/ and have explicitly limited API or scientific coverage. They use the supported library and Uni20; supported headers do not depend on them. They are disabled by default and are not installed with Bethe's command-line programs.

Build and use¶

From your chosen build directory, enable the additional include target:

cmake /path/to/bethe -DBETHE_BUILD_EXPERIMENTAL=ON -DBETHE_BUILD_TESTS=ON
cmake --build . --target bethe_experimental_singlet_tests
ctest -L experimental --output-on-failure

For a CMake consumer, set the option before adding Bethe and link bethe::experimental. Linking bethe::bethe alone does not expose the experimental headers. Library-only builds can leave applications and tests disabled; the experimental library target itself does not require GoogleTest or CLI parsing. Its headers currently use namespace bethe::experimental.

The CI presets opt in and run bounded experimental tests alongside the existing native, wide-precision and sanitizer coverage. Ordinary source builds retain the default OFF setting. General test dependencies and Uni20's optional sanitizer policy are shared between the two test directories. CI also removes the explicit opt-in temporarily and checks that default-OFF removes only experimental tests, retaining every supported test, then restores the original configuration.

Prepared finite-XXX singlet¶

#include <bethe/experimental/xxx_singlet.hpp>

auto ground = bethe::heisenberg::ground_state<double>(8);
bethe::experimental::xxx::PreparedSinglet<double> prepared(8, ground);
if (!prepared.ready()) {
    // Retain the failed request and inspect prepared.status()/ground_residual().
    throw std::runtime_error("singlet preparation failed");
}
auto energy = *prepared.energy();
auto standard_roots = prepared.aba_rapidities();
auto zero = *prepared.working_zero();

This snapshot is for the even periodic XXX chain with J=1 and spin operators sigma/2. Its input is the existing real-root RealState, whose coordinate is z=2 lambda. It exposes standard ABA lambda. The energy is recomputed from the validated roots rather than trusting the caller's saved energy.

Preparation reuses PreparedRaisingFormFactors: the ground Gaudin determinant and ground-only products are calculated once. The read-only ground_log_prefactor() is

\[ \log N-\log|\det G_0|+\sum_a\log(\lambda_a^2+1/4) -\sum_{a\gt b}\log\left(1+(\lambda_a-\lambda_b)^2\right). \]

It is the ground-only contribution to a Fourier raising weight, not a complete norm or form factor. Excited-state determinants and products are still needed. The four-site analytic singlet provides an independent check: E=-2, det(G_0)=108 and this prefactor is -log(324). Its pi-momentum triplet has Fourier raising weight 4/3. See finite-chain conventions.

The same snapshot can evaluate existing real-root triplets through real_raising_form_factor(excited). It does not yet solve complex-root states itself. The separate regular complex-root helpers supply unreduced form factors. The general numerical formulas and physical normalization must be validated for each added family. The selected six-spinon families add a solver and a fresh-state example on this foundation. Six-spinon catalogues and scans enumerate bounded label sets and reuse that solver through owned Async operations, preserving failed candidates and the distinction between state and transfer momentum.

Use working_zero() to create scratch with the prepared precision. MPFR inputs must already have one explicit finite precision; mixed, exact or unset root precision is rejected. The context owns its snapshot, so later input mutation or destruction cannot invalidate it. Const evaluations use local scratch. Failed and moved-from contexts expose no usable energy, roots, prefactor, pivot diagnostic or working exemplar. Failed preparations retain a measured residual when available; moved-from contexts report an absent residual and unavailable status. The pivot value is a rejection indicator, not a condition number or error bound.

This interface intentionally has no disk-cache reader. Historical serialized factors with a different determinant method or precision contract must not be silently substituted for validated preparation.

Independent QTM references¶

The isotropic QTM reference package compares JMP quadrature with an analytic PRL hypergeometric limit, then checks complete complex partition sums against the public spinon vertex controls. These are optional Python source-checkout tools, separate from the C++ build option. They need mpmath, but no private data or C++ build. Detailed limiting algebra is in the derivation.

Open XXX boundary weights¶

The boundary form-factor guide describes local singlet-to-triplet weights, an owned prepared normalization, the fixed-imaginary-root construction, explicit precision and independent small-chain checks. These free-end weights carry no periodic Fourier factor. Build the standalone example with BETHE_BUILD_EXPERIMENTAL=ON and BETHE_BUILD_EXAMPLES=ON.

Free-end XXX time correlations¶

The boundary-dynamics guide adds an owned real-root triplet scan, local and signed end-to-end time correlations, full ground-state boundary density and first-moment references. It includes a fresh CLI with explicit failed records and declared exports.

Massive XXZ vertex amplitudes and spectra¶

The finite-q XXZ package evaluates two- and four-spinon complex amplitudes, fixed-order integrated moments and Gaussian frequency cuts. It supports native formats and explicit MPFR/MPC precision. Its independent residue and NumPy/SciPy controls run without research data. Product/residue truncation, outer quadrature and arithmetic precision require separate checks; the four-spinon calculation is not a certified spectral density.

Restartable density controls¶

The spinon recovery store binds a bounded chunk of decimal inputs to a numerical policy and producer provenance. It publishes completed controls atomically for process restart, preserving precision and the original deadline. Its portable example needs no research archive; POSIX locking and filesystem limitations are documented separately.

Scope and promotion¶

Each experimental feature must document supported inputs, numerical controls, precision coverage and failure behavior. A limited but validated family can later become a supported API; this requires independent physical checks, precision/conditioning evidence, documentation and normal packaging. Supported code cannot acquire a hidden dependency on experimental headers during that promotion. Known wrong results are not acceptable experimental output.

The boundary-magnetization guide adds signed same-sector endpoint elements and magnetization after a boundary spin flip.