jaxvacua.flux_vacua_finder

jaxvacua.flux_vacua_finder#

Canonical flux-vacuum search interface.

Purpose#

Define FluxVacuaFinder, the main entry point for constructing, sampling and classifying flux vacua in Type IIB compactifications on Calabi-Yau threefolds.

Main public API#

FluxVacuaFinder: a subclass of FluxEFT. A finder is the EFT model, with vacuum-search methods added; inherited physics methods such as V_x, DW, ddV_x, hessian and tadpole are callable directly on the finder.
SUSY workflow: newton_method_flux_vacua(mode="SUSY"), sample_SUSY_flux_vacua, sample_SUSY_vacua_from_fluxes, linearised_shifts_* and deduplicate_vacua.
Non-SUSY workflow: sample_critical_points with Newton, Adam, L-BFGS, Adam-on-potential, hybrid and SciPy backends.
Gaussian-M prior calibration and persistence through calibrate_priors, save_calibration and load_calibration.

Design notes#

Stateless post-processing helpers delegate to jaxvacua.flux_utils. Use FluxVacuaFinder.from_model(model, sampler=None) to reuse an existing FluxEFT geometry without recomputing it.

Computational graph#

The vacuum-search loop wraps a jaxvacua.flux_eft.FluxEFT instance and runs a Newton iteration on the F-term residual

\begin{align*} r_I(z, \bar z, \tau, \bar\tau;\, \mathrm{flux}) &= D_I W = \partial_I W + (\partial_I K)\, W, \quad I = (z^i,\, \tau), \\[2pt] \text{converged when } \; \lVert r \rVert_\infty &< \texttt{tol}. \end{align*}

For each converged point the layer also computes the bosonic mass-squared spectrum,

\[m^2 = \operatorname{eig}\!\left(M^2_{IJ}\right), \qquad M^2_{IJ} = \frac{\partial^2 V}{\partial \phi^I \partial \phi^J} \Big|_{D_I W = 0},\]

via jaxvacua.flux_eft.FluxEFT.hessian() and jaxvacua.flux_eft.FluxEFT.mass_matrix(). Inherited input (the upstream jaxvacua.flux_eft.FluxEFT instance) is shown light grey; the diamond is the convergence filter; orange callouts are the public outputs of the layer.

jaxvacua.flux_vacua_finder.FluxVacuaFinder — Newton refinement

Inputs (inherited + runtime)

Inherited

FluxEFT instance

provides $W$, $D_I W$, $V$, $K$, $K_{i\bar\jmath}$

External (runtime)

flux $(F_3, H_3)$

integer flux pair to refine for

Layer 2 — Initial guess

data_sampler + linearised shifts

ISD-biased seeds $(z_0, \tau_0)$ at fixed flux
ISD completion: $f = s\,M\,\sigma\, h + c_0\, h$
data_sampler.initial_guesses_ISD() · FluxVacuaFinder.linearised_shifts_ISD

Layer 3 — Newton iteration

Newton step

SUSY residual $r_I = D_I W$; non-SUSY searches use $r_I = \partial_I V$
Jacobian $J_{IJ} = \partial_J\, D_I W$, or the scalar-potential Hessian for critical points
shift $\Delta = -J^{-1} r$, update $(z, \tau) \mathrel{+}= \Delta$
FluxVacuaFinder.newton_method_flux_vacua() · scipy.optimize.root(method='hybr')

converged?

$\lVert r \rVert_\infty < \texttt{tol}$

Layer 5 — Store converged vacuum

Per-vacuum row

$(z^*, \tau^*, f, h)$, residual, $|W_0| = |W(z^*, \tau^*; f, h)|$, $g_s = (\Im\tau^*)^{-1}$
FluxVacuaFinder.fterm_solver() · sample_SUSY_flux_vacua()

Layer 6 — Mass spectrum

Hessian / mass matrix

$M^2_{IJ} = \partial_I \partial_J V \big|_{D_I W = 0}$, with metric-normalised eigenvalues for the mass spectrum
FluxEFT.mass_matrix · FluxEFT.hessian

Output: Per-vacuum row $(z^*, \tau^*, f, h)$, residual, $|W_0|$, $g_s$, tadpole, mass spectrum.

Flux vacua finder#

FluxVacuaFinder([h12, model_ID, model_type, ...])

Canonical entry point for searching, sampling, and classifying flux vacua in Type IIB string theory on a Calabi--Yau threefold.

Newton minimisation#

`FluxVacuaFinder.newton_method_flux_vacua`(...)	Solves the minimum conditions for flux vacua using Newton's method.
`FluxVacuaFinder.compute_residual`(x[, axis])	Computes residual.

Linearised shifts#

`FluxVacuaFinder.linearised_shifts`(moduli, ...)	Computes the linearised shifts for the complex structure moduli and the axio-dilaton.
`FluxVacuaFinder.linearised_shifts_ISD`(...[, ...])	Computes the linearised shifts for the complex structure moduli and the axio-dilaton based on $ISD_+$-sampling for fluxes.
`FluxVacuaFinder.linearised_shifts_H`(moduli, ...)	Computes linearised shifts for the complex structure moduli and axio-dilaton based on given H-flux.
`FluxVacuaFinder.linearised_shifts_F`(moduli, ...)	Computes linearised shifts for the complex structure moduli and axio-dilaton based on given F-flux.

Flux vacuum sampling#

`FluxVacuaFinder.fterm_solver`(moduli, tau, fluxes)	Solves F-term conditions for a given optimiser.
`FluxVacuaFinder.sample_SUSY_flux_vacua`([N, ...])	Samples SUSY flux vacua.
`FluxVacuaFinder.sample_SUSY_vacua_from_fluxes`([...])	Samples SUSY flux vacua for given input fluxes.
`FluxVacuaFinder.deduplicate_vacua`(moduli, ...)	Removes duplicate vacua from a batch of solutions.

Critical-point sampling (non-SUSY)#

The non-SUSY workflow — sampling Gaussian-M-prior fluxes, ISD-completing them, refining via Newton / optax / scipy, and filtering — lives directly on FluxVacuaFinder post-merge.

`FluxVacuaFinder.sample_critical_points`([...])	Sample critical points of the scalar potential $V$ by drawing Gaussian-M-prior flux candidates, ISD-completing them, refining via the chosen solver, then filtering by physicality and deduplicating.
`FluxVacuaFinder.run_calibration`([Nmax, ...])	Convenience wrapper that runs the full Gaussian-M-prior calibration pipeline in one call:
`FluxVacuaFinder.calibrate_priors`([Nmax, ...])	Empirically refine the Gaussian-prior σ per ISD mode by binary-search.
`FluxVacuaFinder.save_calibration`(Nmax[, ...])	Save calibrated prior parameters to a JSON file for reuse.
`FluxVacuaFinder.load_calibration`(path)	Load calibrated prior parameters from a JSON file produced by `save_calibration()`.
`FluxVacuaFinder.from_model`(model[, sampler, ...])	Construct a `FluxVacuaFinder` from an existing `FluxEFT` instance, reusing all of its geometry data (period vector, prepotential, conifold tree, …) — no recomputation. Composition-style alternative to the standard `FluxVacuaFinder(h12=..., model_ID=...)` constructor.

Shared finder utilities#

Thin delegators over the stateless helpers in jaxvacua.flux_utils. Useful for post-hoc analysis of any converged candidate, regardless of which solver produced it.

`FluxVacuaFinder.dedup_key`(moduli, tau, fluxes)	Hashable dedup key for a single `(moduli, tau, fluxes)` triple. Suitable for incremental `set` / `dict` membership tests in a streaming sampling loop.
`FluxVacuaFinder.classify_solution`(x, flux[, ...])	Classify a converged critical-point candidate `(x, flux)`: returns `{V, \|DW\|, eigenvalues, is_susy, is_minimum, Nflux}`.
`FluxVacuaFinder.is_physical`(x[, moduli_max, ...])	Decide whether the converged candidate `x` lies in the physical region of moduli space. Runs a five-tier cascade: runaway bound → dilaton floor → Kähler-cone hyperplanes → Kähler-metric positivity → basic `Im(z_i) > 0`.
`FluxVacuaFinder.to_fd`(moduli, tau, fluxes)	Optionally map `(moduli, tau, fluxes)` to the fundamental domain via `map_to_fd()`, with numpy/JAX marshalling at the boundary.