# 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](../notebooks/01_basics/02_jaxvacua_overview). ```{raw} html
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](https://huggingface.co/datasets/aschachner/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.