Introduction

JAXVacua provides a unified, JAX-native pipeline from Calabi–Yau compactification data to four-dimensional flux-vacuum solutions. The introduction chapters below cover the physics and mathematics that the rest of the documentation builds on. This page sketches the end-to-end user workflow at a glance.

The user workflow at a glance

The diagram below traces the typical use of the package from geometric input to vacuum analysis. The four numbered stages map onto the section captions of this overview tutorial.

jaxvacua — Workflow Overview

Step 1  —  Geometry Input

CYTools

Polytope / Triangulation
CalabiYau object

Python dictionary

$\kappa_{ijk}$,  $a$-matrix,  $c_2$,  $\chi$
GV / GW invariants

Saved model file

Pickle / zipped pickle
from prior computation

Hugging Face

stringforge cy-database
aschachner/cy-database

lcs_tree  (preferred)

Central geometry data container  ·  JAX pytree
from_cytools()  ·  from_dict()  ·  from_file()

or

Direct input  (alternative)

Provide $\Pi(z)$ or $\mathcal{F}(X)$
directly as callable functions
period_input=...
prepotential_input=...

Step 2  —  Model Construction

periods

Period vector $\Pi(z) = (\mathcal{F}_I,\, X^I)$  ·  Prepotential $\mathcal{F}(X)$
Kähler potential $K = -\!\log\!\bigl(-i\,\Pi^\dagger \Sigma\,\Pi\bigr)$  ·  Gauge kinetic matrix $\mathcal{N}_{IJ}$

inherits ↓

css

Kähler metric $G_{i\bar\jmath} = \partial_i \partial_{\bar\jmath} K$  ·  ISD matrix $M$
Complex-structure sector  ·  Special-Kähler structure

inherits ↓

FluxEFT

Superpotential $W = \int G_3 \wedge \Omega = (F - \tau H) \cdot \Pi$  ·  F-terms $D_I W = \partial_I W + (\partial_I K)\,W$
Scalar potential $V$  ·  Tadpole $N_{\rm flux} = f^T \Sigma\, h$  ·  D3-charge constraint $N_{\rm flux} \leq Q_{\rm O3}$

inherits ↓

FluxVacuaFinder

Kähler cone  ·  Conifold loci  ·  EFT validity constraints
Moduli-space limits  ·  Perturbatively flat vacua  ·  Vacuum-search entry point

Step 3  —  Vacuum Search

Freezer

Freeze heavy moduli
Reduced EFT for
light-sector fields

data_sampler

Kähler-cone moduli sampling  ·  Axion / dilaton bounds
Tadpole constraint $N_{\rm flux} \leq N_{\max}$  ·  Vmapped scan kernels

Stochastic ISD sampling

ISD completion: $f = s\,M\,\sigma\, h + c_0\, h$
Random $h \in \mathbb{Z}^{2 (h^{1,2}+1)}$ with $N_{\rm flux} \leq N_{\max}$
data_sampler.ISD_sampling()

Systematic flux enumeration

Eigenvalue bounding boxes for $h$
Integer lattice scan + ISD filter
bounded_fluxes.sample_bounded_fluxes()

Step 4  —  Refinement & Analysis

Vacuum refinement

Solve $D_I W = 0 \;\Longrightarrow\; (z^*,\, \tau^*)$
Newton method  ·  FluxVacuaFinder.newton_method_flux_vacua()  ·  scipy.optimize.root
Hessian / mass matrix via FluxEFT.hessian and FluxEFT.mass_matrix

Output:  Flux vacua $(z^*,\, \tau^*,\, f,\, h)$,  residual,  $|W_0|$,  $g_s$,  tadpole,  mass spectrum,  EFT validity checks  ·  optionally written to the stringforge vacua storage layer.

The four stages are:

1. Geometry input — load topological data through any of four on-ramps (CYTools polytope, the stringforge cy-database, a local CICY identifier, or an explicit dictionary). All four feed an lcs_tree — JAXVacua’s data interface for a Calabi–Yau threefold.

2. Build the EFT — the linear pipeline periods → css → FluxEFT → FluxVacuaFinder constructs the period vector, complex-structure Kähler geometry, GVW superpotential, and vacuum solver from the lcs_tree.

3. Search for vacua — data_sampler provides ISD-biased initial guesses; bounded_fluxes enumerates fluxes inside a box subject to physical constraints. Both feed FluxVacuaFinder’s Newton solver.

4. Analyse and store — extract observables (\(\lvert W_0 \rvert\), \(g_s\), tadpole, mass spectrum) and persist them to a local or community vacua vault via the stringforge.vacua_writer layer. The optional Freezer branch produces a reduced EFT when heavy moduli are integrated out.

Reading order

The chapters that follow in the Introduction caption of the master TOC cover the physics in the order you will encounter it when constructing a model: supergravity background, Calabi–Yau geometries, flux compactifications, moduli stabilisation, periods, and perturbatively flat vacua. For the corresponding code-level walkthroughs, see the Tutorials — Basics chapter.