JAXVacua - Flux Vacua in String Theory with JAX

JAXVacua is a Python library designed for the systematic exploration of flux vacua in string theory through the numerical analysis of supergravity scalar potentials. It leverages automatic differentiation and just-in-time compilation tools provided by the JAX library to efficiently locate and analyse critical points of highly non-linear potentials. The package is intended to be accessible both as a high-level user-facing library and as a flexible collection of modular components that can be reused or extended for custom workflows. In particular, JAXVacua is well suited for the study of flux compactifications in string theory, where large parameter spaces and intricate scalar potentials make traditional analytic approaches challenging.

The introduction gives a summary of the physical and mathematical context and aim of the library, which serves to give a broad overview to the structure and code of the library. The tutorials show how to use the library on a code level and give several examples.

Installation

You may want to install the code in a new virtual environment. This can be created using python -m venv jaxvacua-env and activated using source jaxvacua-env/bin/activate from within the terminal at a desired working directory.

The recommended way to install the package is via pip. Before installing, make sure your packaging tools are up to date by running:

pip install --upgrade pip setuptools

Next, choose the installation method that best fits your use case:

• Editable install directly from GitHub: If you only want to use the package or make light modifications, you can install it directly from the repository with: pip install -e git+https://github.com/StringJAX/jaxvacua.git#egg=jaxvacua

• Editable install from a local clone (recommended for development):
  If you plan to actively develop or experiment with the code, first download or clone the repository. Then navigate to the root directory of the project in a terminal and run: pip install -e .
  The -e (editable) option ensures that any local code changes take effect immediately without requiring reinstallation.

Requirements

Currently, the code supports Python versions >= 3.12, both with and without JAX GPU support.

The required packages, which are listed in setup.py, are automatically installed with the above installation process. Otherwise, they have to be installed manually.

Documentation

The documentation of this repository is generated with sphinx. Following the installation of the jaxvacua package, install the additional requirements in documentation/requirements.txt by running pip install -r documentation/requirements.txt from the repository root. Then cd documentation && make html generates the html version, which is placed in documentation/build/html.

Quick start

A geometry can be loaded in several ways — pick whichever is most convenient:

1. Bundled local models. A small selection of Kreuzer-Skarke (KS) and complete-intersection (CICY) models ships with the package under jaxvacua/models/, indexed by $h^{1,2}$ and a model_ID:

import jaxvacua as jvc
model = jvc.FluxEFT(h12=2, model_ID=1)

2. Directly from CYTools. Given a cytools.CalabiYau object, the topological data at LCS is extracted automatically:

# Assuming `cy` is a cytools.CalabiYau object
tree = jvc.lcs_tree.from_cytools(cy, maximum_degree=1)
model = jvc.FluxEFT(lcs_tree=tree)

3. From the CY database (new). The cy-database HuggingFace dataset hosts precomputed topological data for millions of Calabi-Yau geometries. The database stack lives in the stringforge umbrella package: TDFDatabase / CICYDatabase for pure I/O, and LCSDatabase for ready-to-use FluxVacuaFinder instances. The interface downloads only the catalog (~10 MB) upfront and pulls individual model shards on demand:

from stringforge.lcs_database import LCSDatabase
db = LCSDatabase(dataset="tdf")
df = db.query(h12=2, has_conifolds=True)             # catalog-only filter
model = db.load_model(ks_id=int(df.iloc[0]["ks_id"]),
                      triang_id=int(df.iloc[0]["triang_id"]),
                      include_gv=True, include_conifolds=True)

For offline / HPC use, pass offline=True; cached shards are then served locally. Flux-vacuum solutions can be stored in a local vacua vault and, optionally, pushed to the community vacua_vault repository. The database stack, the vacua_vault subpackage, and the corresponding tutorials live in the sibling stringforge package — see stringforge/documentation/source/tutorials/database_and_infrastructure/ for the full walkthrough.

Repository structure

.
├── jaxvacua/                       # main package
│   ├── __init__.py                 # backend detection, precision setup (float32/float64)
│   ├── periods.py                  # period vector, prepotential, Kähler potential
│   ├── css.py                      # complex structure sector (Kähler geometry, gauge kinetic matrix)
│   ├── flux_eft.py                 # FluxEFT: superpotential, F-terms, scalar potential, Hessian
│   ├── flux_vacua_finder.py        # FluxVacuaFinder: Newton solver, vacuum sampling
│   ├── flux_bounding.py            # bounded_fluxes: flux enumeration, cluster parallelisation
│   ├── flux_utils.py               # PFV algebra (flux ↔ PFV ↔ moduli)
│   ├── sampling.py                 # moduli / flux sampling, ISD sampling
│   ├── freezer.py                  # Freezer / ConifoldFreezer: light-field EFT
│   ├── conifold/                   # conifold-limit subpackage
│   │   ├── coni.py                 #   Conifold class
│   │   ├── coniLCS_prepotential.py #   coniLCS-limit prepotential
│   │   ├── conifold_utils.py       #   basis changes, find_conifolds, helpers
│   │   └── zcf_solver.py           #   conifold-coordinate z_cf solver
│   ├── hypergeometric_models.py    # closed-form hypergeometric one-modulus models
│   ├── lcs.py                      # lcs_tree: topological data container
│   ├── cytools_interface.py        # CYTools interface
│   ├── util.py                     # utilities (pytree flatten/unflatten, IO helpers)
│   └── models/                     # bundled pre-computed model data (grouped by h12)
├── documentation/
│   ├── source/
│   │   ├── intro/                  # physics / maths background
│   │   ├── applications/           # papers using jaxvacua
│   │   ├── notebooks/              # tutorials (quickstart + 4 thematic subdirs)
│   │   └── jaxvacua.*.rst          # API reference pages
│   ├── build/                      # generated html (gitignored)
│   └── requirements.txt
├── tests/                          # pytest suite (test_periods, test_css, test_flux_eft, ...)
├── setup.py
├── environment.yml                 # conda env (CPU)
├── environment_metal.yml           # conda env (Apple Silicon, falls back to CPU for complex)
├── pytest.ini
├── CHANGELOG.md
├── CITATION.cff
├── LICENSE
└── README.md

Tutorials are grouped by theme under documentation/source/notebooks/:

notebooks/
├── quickstart.ipynb                # shortest end-to-end workflow
├── 01_basics/                      # JAX intro, jaxvacua overview, CYTools interface
├── 02_vacuum_finding/              # flux vacua finder, ISD sampling, flux bounding
├── 03_geometry_and_limits/         # moduli limits, conifolds, hypergeometric models
└── 04_analysis_and_pipelines/      # freezer, visualisation, Hessian, landscape statistics

Contact

For questions or feedback, please get in touch: as3475@cornell.edu.

License

JAXVacua is released under the GNU General Public License v3.0.

Citation

If you find this software useful, please cite the following paper:

@article{Dubey:2023dvu,
    author = "Dubey, Abhishek and Krippendorf, Sven and Schachner, Andreas",
    title = "{JAXVacua \textemdash{} a framework for sampling string vacua}",
    eprint = "2306.06160",
    archivePrefix = "arXiv",
    primaryClass = "hep-th",
    doi = "10.1007/JHEP12(2023)146",
    journal = "JHEP",
    volume = "12",
    pages = "146",
    year = "2023"
}