# Finite periodic XXX experiment

This experiment supports `/learn/test-finite-chain-bethe-solutions/`. It constructs
the finite spin Hamiltonian in two independent ways and verifies selected regular
two-magnon coordinate Bethe states. It does not enumerate all Bethe states or prove
completeness, the existence of commuting transfer matrices, or a thermodynamic limit.

## Reproduce

The saved run uses Python 3.9.6, NumPy 2.0.2 and IEEE 754 binary64 arithmetic
(`complex128` wavefunctions). The pinned NumPy release supports Python 3.9–3.12;
see the [official release notes](https://github.com/numpy/numpy/releases/tag/v2.0.2).
From the repository root:

```sh
python3 -m venv .tmp/xxx-venv
.tmp/xxx-venv/bin/python -m pip install -r public/computations/xxx/requirements.txt
.tmp/xxx-venv/bin/python public/computations/xxx/experiment.py --check
```

If the dependency is already available, run
`python3 public/computations/xxx/experiment.py --check`. Downloaded copies of
`experiment.py`, `inputs.json`, and `results.json` work together in any directory;
the paths resolve relative to the script rather than the working directory.

With no option, the script prints fresh results as JSON. `--check` recomputes the
experiment, tests the mathematical checks and negative controls, and compares the
saved data without writing any files. `--write` explicitly regenerates
`results.json`; use it only when intentionally updating the experiment, and review
the inputs, results and article numbers together. Routine site builds do not run
this calculation. For an extension, copy this folder and keep the original inputs.

## Fixed system and coordinate convention

There are `N >= 3` sites on a periodic ring, indexed `0,...,N-1`, with spin
`S = sigma/2`, hbar and lattice spacing one. The ferromagnetic coupling is `J > 0`:

```text
H = J sum_i [1/4 - S_i dot S_(i+1)] = (J/2) sum_i (1 - P_(i,i+1)).
```

The all-up vacuum has energy zero. `M` is the number of down spins. `P` in the
Hamiltonian denotes a two-site permutation. Each ring bond occurs once; `N=2`
is excluded because it needs a separate bond-counting convention. Full tensor
construction is limited to `N <= 10` to keep an educational dense-matrix example
bounded; the recorded results use `N=4,5,6,7,8`.

For ordered positions `x < y` and `z_j = exp(i*k_j)`, the unnormalized coefficients
are

```text
psi(x,y) = z1^x z2^y + S12 z2^x z1^y,
S12 = -(1 + z1*z2 - 2*z2)/(1 + z1*z2 - 2*z1).
```

The two periodic equations are `z1^N = 1/S12`, `z2^N = S12`. The selected branch
has `k1=-k2=k=2*pi*mode/(N-1)`, so `S12=exp(-i*k)` and `z1^(N-1)=1`.
Require `1 <= mode < (N-1)/2`, excluding the zero-momentum singular ratio and
the coincident phase at `k=pi`. These are explicitly selected zero-total-momentum
real-root states, not a numerical search for all Bethe roots. Their energy is
`E/J=2*(1-cos(k))`. The nine recorded cases use modes `1`, `1`, `1,2`, `1,2`, and
`1,2,3` at the five successive chain lengths.

## Independent Hamiltonians and checks

- `tensor_hamiltonian` uses Kronecker products of explicit Pauli matrices on the
  full `2**N` dimensional Hilbert space. Site zero is the leftmost tensor factor;
  the local basis is up `(1,0)`, down `(0,1)`.
- `sector_hamiltonian` uses the swap action on lexicographically ordered increasing
  tuples of down-spin positions. It does not use Pauli matrices or the tensor
  routine's bond iterator. An unlike neighboring spin pair contributes diagonal
  `J/2` and an off-diagonal swap amplitude `-J/2`; like spins contribute zero.
- Extract the `M=1,2` blocks from the tensor Hamiltonian and compare with the
  independent sector matrices. Also check full-matrix Hermiticity, conservation
  of total `Sz`, and zero vacuum energy.
- Diagonalize the complete one-magnon sector at each size and compare every energy
  with `J*(1-cos(2*pi*m/N))`, including multiplicities. Check each plane wave as a
  vector as well as comparing the spectrum.
- Normalize each selected complex two-magnon vector. Compare its raw squared norm
  with the independent finite-sum identity `N*(N-1)` on the stated branch. Check
  the contact equation, both algebraic Bethe equations, and the cyclic seam
  `psi(x,y)=psi(y,x+N)` for every ordered pair.
- Apply both Hamiltonians to the reconstructed state. Independently diagonalize
  the sector matrix, find the nearest energy, and project the state onto the whole
  eigenspace within the equation tolerance. This last operation avoids arbitrary
  eigenvector phases and bases inside a degenerate eigenspace.

All Hamiltonian/energy residuals are divided by `J`. A vector residual is the
Euclidean norm `||H psi - E psi||_2/J` for a unit vector. A matrix discrepancy is
the maximum absolute entry, not a matrix operator norm. A Bethe residual is
`max(|z1^N-1/S12|, |z2^N-S12|)`. The seam residual is the maximum absolute difference
of the two coefficients divided by the raw vector norm. These definitions are
retained in result field names and in the project article.

No time step, spatial approximation, or iterative root tolerance enters this
experiment: the finite matrices are the stated model, and the selected roots are
given analytically. Binary64 rounding limits the numerical residuals. The equation
threshold `1e-11` is a regression tolerance, not a rigorous error bound. Saved-data
comparison allows absolute tolerance `5e-12` and relative tolerance `1e-10` for
platform-dependent last digits. Inputs must match exactly; environment versions
are descriptive and are not compared as scientific data.

## Negative controls and excluded cases

The script replaces `S12` by `1/S12` while retaining the same root ordering and
amplitude convention. It also deletes the closing ring bond while retaining the
original periodic state and predicted energy. Both errors must produce dimensionless
vector residuals larger than `0.01` in every selected case. In the recorded run the
minimum residuals are about `0.676` and `0.307`, far above roundoff. The wrong
ratio test is deliberately not a consistent simultaneous relabeling of roots.

Two guards distinguish formal roots from physical vectors. For `z1=z2=1`, the
displayed scattering ratio is `0/0` and is rejected. For `N=5`, exact
`z1=z2=-1`, `S12=-1` satisfies both algebraic equations but every coefficient
cancels. Its norm is exactly zero, and normalization is rejected. This example
does not analyze which other singular root limits can be regularized into physical
states; that requires a separate construction.

The tensor calculation also forms `(S_total^-)^2 |vacuum>`, normalizes it, and
checks its zero energy and agreement with the uniform `M=2` vector. It is a
concrete descendant omitted from the selected nonzero real-root branch. Together
with the sector dimension `binomial(N,2)`, this makes the limited coverage visible.
In particular, the two tested six-site Bethe states do not span its 15-dimensional
two-magnon sector. Complex roots and other momentum sectors are not enumerated.

## Result contents and sources

`results.json` retains the input data, runtime versions, all one- and two-magnon
sector eigenvalues, equation/vector residuals, negative controls, regularity
examples, and the complex normalized coefficients of both six-site states. Every
reported number is recomputed by the original code. A short table in the article
is more useful here than a plot of roundoff-sized residuals.

Michael Karbach and Gerhard Müller, *Introduction to the Bethe ansatz I*,
Computers in Physics **11**, 36–43 (1997),
[DOI](https://doi.org/10.1063/1.4822511); author version
[arXiv:cond-mat/9809162v1](https://arxiv.org/abs/cond-mat/9809162v1), submitted 1998.
[PDF](https://arxiv.org/pdf/cond-mat/9809162v1), printed pp. 1–3, equations
(1), (3)–(18), supplies the model and coordinate construction. Their Hamiltonian
is `-J sum S.S`, with vacuum energy `E0=-JN/4`; our energy is their `E-E0`.
Their amplitude ratio `A/A'` is the inverse of our `S12=A21/A12`. The finite-size
code, selected-state calculations and negative controls are independently written.