Command-line calculations and diagnostics¶

Back to the overview

The programs share precision selection and report formatting; convergence controls depend on the solver. Start with the periodic XXX example below, then follow a model guide for its Hamiltonian, supported states and limitations.

• Choose a calculation
• Help, references and option syntax
• Select arithmetic precision
• Read and save the report
• CPU time and convergence
• Model-specific entry points

Choose a calculation¶

Examples assume the executables are on PATH. From a build directory, you can instead use ./bethe-xxx-pbc etc.; see running the programs. No particular source or build directory is required for a calculation.

bethe-xxx-pbc 16
bethe-xxx-pbc 64 --precision fp64 --tolerance 1e-12
bethe-xxx-pbc 6 --precision long-double --roots
bethe-xxx-pbc 15 --sz 1/2
bethe-xxx-pbc 16 --sectors
bethe-xxx-pbc 65 --spinons
bethe-xxx-pbc 32 --excitations 10 --spin 1
bethe-xxx-pbc 5 --quantum-numbers -1,1 --roots
# In a binary128-enabled build:
bethe-xxx-pbc 16 --precision fp128 --tolerance 1e-30

XXX state-selection modes¶

The default is a ground state; odd lengths return one of the degenerate \(S^z =1/2\) representatives. The five explicit modes are mutually exclusive:

Add --roots to print the roots and exact Bethe quantum numbers.

For spectral weights, use the separate bethe-xxx-structure-factor frontend on an even ring. It always scans the complete supported two-spinon family, and reports its contribution to the zz or raising-channel sum rules. For an infinite-chain spectral density, use bethe-xxx-structure-factor-thermo, with --momentum Q for a frequency cut or --momentum-points N for a heat-map grid. It supports scalar MPFR with --precision bits-N; quadrature order and evaluation budgets are independent of the selected arithmetic precision. It defaults to two spinons; selected-sector controls add four and six with separate quadrature, sampling and cutoff diagnostics. For frequency moments, use bethe-xxx-moments-thermo with either --momentum Q or --global to integrate the moment measure directly. Both thermodynamic XXX tools also accept --momentum-from-pi D and --momentum-beta B; see momentum input near an endpoint for conversion diagnostics and scalar-geometry limits.

XXZ uses the same common precision and output controls, but different mode combinations: --excitations selects a family at fixed --sz, not --spin. See periodic XXZ excitations or free-end XXZ excitations before transferring XXX commands directly to the anisotropic model.

Help, references and option syntax¶

Information without calculation¶

All frontends use Uni20's shared CLI and presentation module. These options need no model parameters and do not start a calculation:

Only --references includes a bibliography. Color and width follow Uni20's terminal policy; redirected help is plain by default. No arguments print help to stderr and exit 1.

References include links and applicability notes. Normal numerical output contains no bibliography; CITATIONS.md collects the full bibliography and explains the conventions.

Parsing rules¶

Both --u 4 and --u=4 are accepted. Scalar options reject duplicate occurrences; --csv, --tsv, and --json remain repeatable, with one path per occurrence. A value such as --csv=--help or --csv=--references is a filename, not an information request.

Real-valued parameters remain strings until precision selection, so putting --precision fp128 last cannot lose digits. Help/version/build information and references are handled before required-option and value validation, without opening exports; a missing value detected while gathering arguments can still be an error. If both --help and --references are given, ordinary help takes precedence. Invalid arguments produce a concise stderr diagnostic rather than full help.

Existing positional arguments and scientific option names remain available; options may also precede positional arguments. Integer counts and half-integers are parsed exactly, with negative counts, trailing junk and overflow rejected. An explicitly empty list remains distinct from an omitted option. All frontends support typed tables and file exports; see the output guide for table names, metadata, and numeric encoding.

Select arithmetic precision¶

--precision selects the arithmetic, independently of output formatting. Use the numerical accuracy guide to choose a practical setting and separate arithmetic checks from quadrature, sampling and tails:

All numerical frontends accept bits-N and digits-N in an MPFR-enabled build. Their physical state families and numerical work limits are unchanged; consult the app capability inventory and the individual model guide. These examples demonstrate the syntax and supported frontends, rather than recommended precision for ordinary runs:

bethe-xxx-pbc 32 --precision digits-100
bethe-xxx-pbc 17 --spinons --precision bits-256
bethe-xxx-pbc 16 --excitations all --threads 4 --precision bits-256
bethe-xxx-obc 16 --sectors --precision digits-100
bethe-lieb-liniger-obc 2 --length 1 --c 1e-50 --precision digits-100
bethe-xxz-obc 16 --delta 3 --precision bits-256 --roots
bethe-lieb-liniger-dispersion --c 4 --points 33 --precision digits-100 --threads 4
bethe-xxx-structure-factor 32 --precision bits-256
bethe-hubbard-pbc 6 --u -4 --precision digits-100
bethe-richardson --levels 0,1,2,3 --pairs 2 --g 1 --precision digits-100
bethe-central-spin --couplings 1,0.7,0.3 --field 1 --sz 0 --precision bits-256
bethe-su3-dispersion --branch four-soliton --folded --precision digits-100
bethe-sine-gordon-dispersion --p 0.4 --momentum 0.7 --precision digits-100
bethe-su3-pbc 24 --precision digits-100

All currently supported MPFR frontends need Uni20's arbitrary-precision scalar family (GMP, MPFR and MPC). MPLAPACK matrix kernels are optional: normal Uni20 dispatch supplies CPU LU/QR when needed. The capability inventory records each frontend's precision support, provider requirements and state-family restrictions. More arithmetic precision does not expand those state families.

bethe-tb-pbc supports the even-ring singlet ground state with finite two-string deviations; see the model documentation.

digits-100 resolves to 333 bits through Uni20's decimal-precision conversion. bits-128 is not fp128: the former has 128 significand bits, the latter 113. These select working precision, not guaranteed accurate digits or printed decimal places. Positive integer counts are required; unsupported formats, out-of-range counts and unsupported frontends fail without falling back.

long-double remains platform-dependent. fp80 selects that same native type only when its significand and exponent range match extended80; a padded 16-byte representation does not make it binary128. Bethe's native fp80 selection does not require Uni20's optional float80 alias or binary80 MPLAPACK provider. fp128 uses Uni20's configured MPLAPACK binary128 type. The fp128 CLI currently requires MPLAPACK's native _Float128/strfromf128 mode: other modes are rejected at compile time because the pinned Uni20's scalar I/O narrows them to long double. Calculations, tolerance parsing, and output retain the selected precision; displayed digits are not a guarantee of energy accuracy.

Exports record the requested precision, resolved arithmetic format and significand bits. Arbitrary-precision JSON cells contain {"value":"...","precision":256}; CSV/TSV retain round-trip decimal values. MPFR/MPC are implementation providers, not precision option names.

Inspect the build¶

bethe-info
bethe-info --format json

bethe-info reports Bethe/Uni20 revisions, configured numerical providers, available precision choices and which frontends support arbitrary precision. Its precisions table includes significand bits, decimal precision, exponent range and native storage size (including padding). Exponents follow numeric_limits: the smallest normal value is 2^(min_exponent-1) and the largest finite magnitude is less than 2^max_exponent. Variable-precision properties are left unspecified until a working precision is chosen. The decimal_digits column is the conservative numeric_limits::digits10 decimal round-trip guarantee (15 for binary64), not the approximate significand_bits * log10(2) digit count (about 16 for binary64). Use bethe-info --build-info for additional compiler and dependency details.

For setup details and the supported MPLAPACK configuration, see building with binary128.

Read and save the report¶

Output uses Uni20's presentation layer on terminals: aligned fields and tables, decimal half-integer labels, and semantic convergence markers. --format auto (the default) selects this report on a terminal and a plain human-readable report when redirected. Use --format pretty to save a formatted report, or --format csv|tsv|json for scripts. Add repeatable --csv FILE, --tsv FILE or --json FILE exports independently of screen output. All retain the selected type's full round-trip precision, including binary128; no displayed values are narrowed to double.

The pretty report honors UNI20_COLOR, NO_COLOR, UNI20_GLYPHS, and UNI20_CHARSET. For example, UNI20_GLYPHS=ascii UNI20_COLOR=never selects ASCII table rules and status markers without ANSI color. Terminal width (or COLUMNS) selects aligned tables or labeled records; numeric strings are never split or truncated, so a single long value can still exceed a very narrow terminal. Root and auxiliary rows link to state records through state_id; excitation scans keep the ground reference and failed estimates separate from ranked levels. See the table schemas.

CPU time and convergence¶

Timing¶

Output includes energy, momentum (periodic systems only), normalized equation residual, convergence status, update count, and solver CPU time in seconds. CPU time measures process CPU consumption during state construction and solving, not elapsed wall time (parallel workers' CPU times add together); for scans it covers the whole scan, including the ground reference and energy ordering for excitations. Report formatting and output are excluded except for continuous observable grids, as described above. Human reports include it once; exports carry it in the table summary (trailing comments for CSV/TSV). Very short runs may report zero at the clock's resolution; an unavailable or wrapped CPU clock is reported as unavailable.

Iteration budgets and exit status¶

For the finite-root solvers below, --max-iterations defaults to 10000 per state; zero evaluates only the initial guess. Other solvers have their own controls: for example, the exact sine-Gordon excited solver defaults to 32768 nonlinear updates per state. Check the frontend's --help.

The iteration count depends on the model:

• XXX/XXZ: accepted Newton updates, sharing one budget across any continuation stages. XXX and gapless nonnegative XXZ start from zero roots; supported negative-Delta XXZ uses a free-fermion hyperbolic seed, and massive open XXZ uses coupling continuation.
• Hubbard: accepted Newton updates across all continuation stages, from a large-U seed. The exact U=0 path needs no updates.
• SU(3): accepted Newton updates from a filled-sea density seed.
• Gaudin–Yang: accepted updates across strong-to-weak continuation. The exact free path needs no updates.

Exit codes distinguish numerical failure from invalid input:

A nonconverged estimate is explicitly marked; some solvers withhold failed quantities entirely. There is no silent precision fallback.

Residuals and tolerances¶

The residual measures how closely the rapidities satisfy the Bethe equations; it is not a bound on the error in the energy. The finite-root solvers described here default to 32 times the selected type's epsilon; integral-equation and NLIE solvers have their own error budgets and refinement checks.

The logarithmic spin-chain solvers normalize by N (periodic) or 2N (open). Supported negative-Delta XXZ instead uses rank-subtracted, scaled equations; massive open XXZ includes a regularized boundary residual when needed. These conventions are explicitly reported and are not interchangeable.

Hubbard normalizes both equation families by L for periodic rings or 2(L+1) for free ends, and reports their maximum. Even a stopped continuation reports residuals at the requested root-sector U.

Lieb–Liniger uses a component-scaled dimensionless residual, with a weak-coupling scale that resolves roots of order sqrt(c*ell); see its numerical-method guide.

SU(3) normalizes both nested equation families by L and reports the maximum over its independent reflection-reduced equations, as explained in the SU(3) guide.

Gaudin–Yang scales weak-coupling charge residuals by their root or sqrt(c*ell) and otherwise uses N; see its diagnostics guide.

See the model guides for the equations. Increasing precision can help resolve closely spaced levels, but always inspect the convergence status before treating an energy as an eigenvalue.

Parallel calculations¶

See parallel CLI calculations for state scans, observable grids, thread limits and the two-task finite-volume frontend path.

Parallel state scans.

Parallel observable grids.

Model-specific entry points.

Spin-1/2 chains.

Hubbard electrons.

Continuum gases.

Supersymmetric t–J chain.

SU(3)/ULS and spin-1 TB chains.

Biquadratic chains and TL modules.

Pairing and central spin.

Integrable ladder.

Sine-Gordon field theory.