Installation

pip install stringjax            # CPU; JAXVacua engine + CYTools + bundled models
pip install "stringjax[all]"     # + databases (StringForge) and the flux-bounding extra

stringjax is an install-only metapackage: it pulls in a mutually-compatible set of member packages and provides the stringjax command. Import the member packages directly (import jaxvacua as jvc).

Choosing the right JAX build

JAX is the dependency most often misconfigured. The default install gives the CPU build, which works everywhere. For accelerators, install the matching JAX wheel after stringjax:

CPU (default)

pip install stringjax

NVIDIA GPU (CUDA 12)

pip install stringjax pip install -U “jax[cuda12]”

Google TPU

pip install stringjax pip install -U “jax[tpu]” -f https://storage.googleapis.com/jax-releases/libtpu_releases.html

Apple Silicon (Metal)

pip install stringjax pip install jax-metal # experimental; see the float64 caveat below

64-bit precision

Flux-vacuum searches require 64-bit arithmetic. Enable it before JAX is imported, either programmatically

import jaxvacua as jvc
jvc.set_precision("float64")

or via the environment:

export JAXVACUA_PRECISION=float64

Warning

Some accelerators — notably Apple Metal — have limited or slow float64 support and may fall back to the CPU. Run stringjax doctor to confirm whether float64 is actually enabled on your device.

Optional features

• Flux bounding (Gurobi). Systematic flux enumeration uses Gurobi, which needs a (free, for academics) licence. Install with pip install "jaxvacua[bounding]" and activate the licence; everything else works without it.

• Databases & vacua vault (StringForge). Included via stringjax[all], or pip install stringforge. Large datasets are fetched on demand and cached locally; set STRINGFORGE_DATA_DIR to relocate the cache and pin dataset versions for reproducibility.

Reproducible environments

Pinned specifications are shipped in the repository:

pip install -r requirements-cpu.txt          # or requirements-gpu.txt
pip install -r requirements-cpu.txt -c constraints.txt   # exact, pinned versions
# or, with conda/mamba:
mamba env create -f environment-cpu.yml

Verify

stringjax doctor

prints the member versions, the active JAX backend and devices, whether float64 is enabled, and whether Gurobi is available, with suggestions when something is off.