Running the variational program

Use

Python 3.12 or later, with uv:

# numpy, scipy, python-flint, pytest
uv sync
# the state of the paper's earlier code addendum -> state file
uv run bfss import-reference tests/data/reference -o reference.json
# norm, E, Haux, F_lb, <T>, <u>, <Y>, <R^2>..<R^8>, canonical blocks
uv run bfss measure reference.json
# its basis as an ansatz file
uv run bfss ansatz reference.json -o ansatz.json
# optimize from scratch, over the dilation or at a given one
uv run bfss optimize ansatz.json -o optimized.json
uv run bfss optimize ansatz.json -o at3.json --dilation 3
# also store the observables in the state file
uv run bfss measure --store at3.json
# 128-bit balls (default 256), or exact rational matrix elements
uv run bfss --prec 128 measure optimized.json
uv run bfss --exact measure optimized.json

bfss contract precomputes the contraction table of an ansatz; tables and the operator library are cached in .cache/ (--cache DIR). --threads, --workers and --verbose set the FLINT threads, the contraction workers and progress output.

On 14 CPUs the first contraction table of the published basis (1951 functions) takes about 11 min; with it cached, bfss measure takes 30 s and 4 GB and bfss optimize 2 min and 5 GB. The reported basis (19652 functions) took 3.1 h on 48 CPUs and 113 GiB (bfss --prec 128 optimize results/seeded_ansatz.json -o seeded_state.json --dilation 3).

Tests

uv run pytest takes about 20 s with a warm cache and suits every change. uv run pytest --slow, about 9 min, adds brute-force Fock-space and quadrature oracles, the long algebraic identities and end-to-end checks against the state of the earlier addendum.

Generated from the sections Use and Tests of variational/README.md at the tag release.