jaxvacua.flux_vacua_finder.FluxVacuaFinder

jaxvacua.flux_vacua_finder.FluxVacuaFinder#

class FluxVacuaFinder(h12=None, model_ID=None, model_type='KS', limit='LCS', maximum_degree=0, mirror_cy=None, model_data=None, lcs_tree=None, model_file='', use_cytools=False, basis_change=None, ncf=None, conifold_curve=None, conifold_basis=True, grading_vector=None, period_input=None, Q=None, prepotential_input=None, gauge_choice=1 + 0j, prange=5, use_gvs=True, save_file=False, flux_bounds=(-10, 10), axion_bounds=(-0.5, 0.5), dilaton_bounds=(2.0, 10.0), moduli_bounds=(1.0, 5.0), seed=42, map_to_fd=False, **kwargs)#

Bases: FluxEFT

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

Class relationship. FluxVacuaFinder is a subclass of jaxvacua.flux_eft.FluxEFT — it is the EFT model, with vacuum-finding methods bolted on. There is no separate “model” attribute: every physics method (scalar_potential, V_x, DW, ddV_x, hessian, tadpole, ISD_matrix, …) is inherited and callable directly on the finder instance. Existing code that uses FluxEFT works unchanged if you swap in a FluxVacuaFinder — Liskov-substitutable.

Use from_eft() to construct a finder from an existing FluxEFT instance without re-doing the geometry computation (useful when running multiple finders against the same model).

Headline capabilities (post-merge, 2026-05-17):

Newton solver with B1+B2 guards (newton_method_flux_vacua()). Handles SUSY (mode="SUSY") and general extrema (mode=None). Optional runaway escape via moduli_max= kwarg + automatic singular-Hessian protection.

SUSY workflow — sample_SUSY_flux_vacua(), sample_SUSY_vacua_from_fluxes(), linearised_shifts_*(), deduplicate_vacua(). Solves \(D_I W = 0\).

Non-SUSY workflow — sample_critical_points(). Six solver backends: "newton" (default), "adam", "lbfgs", "adam_v", "hybrid", "scipy". Solves \(\partial_I V = 0\).

Gaussian-M prior calibration — _precompute_M_eigensystem() → _estimate_sigmas() → calibrate_priors() → save_calibration() / load_calibration(). Tunes the integer-flux sampling prior per ISD mode.

Shared utilities — classify_solution(), is_physical(), dedup_key(), to_fd(). Stateless helpers for post-hoc analysis of any converged candidate.

Quickstart:

import jax.numpy as jnp
import jaxvacua as jvc

finder = jvc.FluxVacuaFinder(h12=2, model_ID=1)

# 1. SUSY vacuum from a starting point:
fluxes = jnp.array([4.,-3.,-2.,-2.,3.,2.,39.,-13.,-4.,0.,0.,0.])
mod, tau, res = finder.newton_method_flux_vacua(
    jnp.array([2.+3j, 1.5+2j]), -0.3+5j, fluxes,
    mode="SUSY",
)

# 2. Non-SUSY scan (~100 critical points from a Gaussian-M prior):
vacua = finder.sample_critical_points(
    Q=200, n_target=100, n_batch=2000, max_batches=5,
    solver="hybrid", isd_mode="ISD-", verbose=False,
)

# 3. Post-hoc classification of any converged (x, flux):
info = finder.classify_solution(x_sol, fluxes)
# → {'V', '|DW|', 'eigenvalues', 'is_susy', 'is_minimum', 'Nflux'}

See documentation/source/notebooks/02_vacuum_finding/ for full tutorials.

__init__(h12=None, model_ID=None, model_type='KS', limit='LCS', maximum_degree=0, mirror_cy=None, model_data=None, lcs_tree=None, model_file='', use_cytools=False, basis_change=None, ncf=None, conifold_curve=None, conifold_basis=True, grading_vector=None, period_input=None, Q=None, prepotential_input=None, gauge_choice=1 + 0j, prange=5, use_gvs=True, save_file=False, flux_bounds=(-10, 10), axion_bounds=(-0.5, 0.5), dilaton_bounds=(2.0, 10.0), moduli_bounds=(1.0, 5.0), seed=42, map_to_fd=False, **kwargs)#

Initializes a flux EFT class representing the effective field theory of the flux sector in 4D Type IIB string theory compactified on Calabi-Yau threefolds with 3-form flux backgrounds.

This class provides tools for computing and analyzing flux vacua, including superpotentials, Kähler potentials, F-term conditions, and various properties of the moduli space.

Parameters:

h12 (int | None) – Number of complex structure moduli \(h^{1,2}\) for the compactified geometry.
model_type (str) – Type of Calabi-Yau manifold. Currently supports "KS" (Kreuzer-Skarke)
"CICY" (and)
model_ID (int | None) – Identifier for a specific model within the database.
limit (str) – Type of moduli space limit for the periods. Currently supports "LCS"
"LCS". ((Large Complex Structure limit). Defaults to)
model_data (dict | None) – Dictionary containing topological data of the Calabi-Yau, such as
numbers (triple intersection)
class (second Chern)
etc.
instanton_data (list, optional) – List of Gopakumar-Vafa (GV) and Gromov-Witten (GW) invariants
corrections. (for instanton)
maximum_degree (int) – Maximum degree cutoff for instanton sum expansions. Defaults to 0.
use_cytools (bool) – Whether to use CYTools library to compute topological data of the
False. (Defaults to)
mirror_cy (Any | None) – Mirror Calabi-Yau threefold object (from CYTools).
basis_change (Array | None) – Basis transformation matrix to be applied to the topological
Calabi-Yau. (data of the)
ncf (int | None) – Conifold number for conifold-enhanced models.
conifold_curve (Any | None) – Specification of the conifold curve in the moduli space.
grading_vector (Array | None) – Grading vector used for computing Gopakumar-Vafa invariants.
period_input (Optional[Callable]) – Custom function for computing periods.
Q (int | None) – D3-brane tadpole bound constraint.
prepotential_input (Optional[Callable]) – Custom function for computing the prepotential.
gauge_choice (complex) – Gauge choice parameter for the periods. Defaults to 1.0+0.0j.
prange (int) – Period range parameter for convergence. Defaults to 500.
use_gvs (bool) – Whether to use Gopakumar-Vafa invariants for instanton corrections.
False.
save_file (bool) – Whether to save model data to disk for future use. Defaults to False.
flux_bounds (tuple) – (min, max) integer range for flux sampling. Defaults to (-10, 10).
axion_bounds (tuple) – (min, max) range for axion sampling. Defaults to (-0.5, 0.5).
dilaton_bounds (tuple) – (min, max) range for the axio-dilaton \(s = \mathrm{Im}(\tau)\). Defaults to (2., 10.).
moduli_bounds (tuple) – (min, max) range for the imaginary parts of the complex structure moduli. Defaults to (1., 5.).
seed (int) – Random seed for the sampler. Defaults to 42.
map_to_fd (bool) – If True, all returned vacua are mapped to the fundamental domain via map_to_fd(). Defaults to False.
**kwargs – Additional keyword arguments passed to parent class FluxEFT.

Methods

`A`(moduli, moduli_c)	Returns the value of the mirror dual Calabi-Yau volume.
`DDW`(moduli, moduli_c, tau, tau_c, fluxes[, ...])	Returns a matrix the second holomorphic Kähler derivatives \(D_I D_J W\) of the superpotential.
`DDW_SUSY`(moduli, moduli_c, tau, tau_c, fluxes)	Returns a matrix containing the second holomorphic Kähler derivative of the superpotential assuming that the F-flatness conditions \(D_{i}W=D_{\tau}W=0\) are satisfied.
`DDW_general`(moduli, moduli_c, tau, tau_c, fluxes)	Returns the second Kähler covariant derivatives \(D_I D_J W\) of the superpotential \(W\) with respect to the axio-dilaton \(\tau\) and the complex structure moduli \(z^{i}\).
`DDW_matrix`(moduli, moduli_c, tau, tau_c, fluxes)	Returns the matrix of masses for chiral fermions.
`DDW_matrix_SUSY`(moduli, moduli_c, tau, ...)	Returns the matrix of second Kähler derivatives of the superpotential assuming that the F-term conditions are satisfied for all fields.
`DDW_matrix_general`(moduli, moduli_c, tau, ...)	Returns the matrix of second Kähler derivatives of the superpotential.
`DDW_tau_ctau`(moduli, moduli_c, tau, tau_c, ...)	Returns the Kähler covariant derivative \(D_{\overline{\tau}}D_{\tau}W\) of the \(F\)-term \(D_{\tau}W\) with respect to the complex conjugate axio-dilaton \(\overline{\tau}\).
`DDW_tau_cz`(moduli, moduli_c, tau, tau_c, fluxes)	Returns the Kähler covariant derivative \(D_{\overline{z}^i}D_{\tau}W\) of the \(F\)-term \(D_{\tau}W\) with respect to the complex conjugate complex structure moduli \(\overline{z}^i\).
`DDW_tau_tau`(moduli, moduli_c, tau, tau_c, fluxes)	Returns the Kähler covariant derivative \(D_{\tau}D_{\tau}W\) of the \(F\)-term \(D_{\tau}W\) with respect to the axio-dilaton \(\tau\).
`DDW_tau_z`(moduli, moduli_c, tau, tau_c, fluxes)	Returns the Kähler covariant derivative \(D_{z^i}D_{\tau}W\) of the \(F\)-term \(D_{\tau}W\) with respect to the complex structure moduli \(z^i\).
`DDW_z_ctau`(moduli, moduli_c, tau, tau_c, fluxes)	Returns the Kähler covariant derivative \(D_{\overline{\tau}}D_{z^j}W\) of the \(F\)-term \(D_{z^j}W\) with respect to the complex conjugate axio-dilaton \(\overline{\tau}\).
`DDW_z_cz`(moduli, moduli_c, tau, tau_c, fluxes)	Returns the Kähler covariant derivative \(D_{\overline{z}^i}D_{z^j}W\) of the \(F\)-term \(D_{z^j}W\) with respect to the complex conjugate complex structure moduli \(\overline{z}^i\).
`DDW_z_tau`(moduli, moduli_c, tau, tau_c, fluxes)	Returns the Kähler covariant derivative \(D_{\tau}D_{z^j}W\) of the \(F\)-term \(D_{z^j}W\) with respect to the axio-dilaton \(\tau\).
`DDW_z_z`(moduli, moduli_c, tau, tau_c, fluxes)	Returns the Kähler covariant derivative \(D_{z^i}D_{z^j}W\) of the \(F\)-term \(D_{z^j}W\) with respect to the complex structure moduli \(z^i\).
`DW`(moduli, moduli_c, tau, tau_c, fluxes[, conj])	Returns the holomorphic Kähler covariant derivatives of the superpotential with respect to the complex structure moduli \(z^{i}\) and the axio-dilaton \(\tau\).
`DW_tau`(moduli, moduli_c, tau, tau_c, fluxes)	Calculates the Kähler covariant derivative of the superpotential with respect to the axio-dilaton \(\tau\).
`DW_x`(x, fluxes)	Calculates the real and imaginary parts of the \(F\)-term conditions.
`DW_z`(moduli, moduli_c, tau, tau_c, fluxes[, ...])	Calculates the Kähler covariant derivative of the superpotential \(W\) with respect to the complex structure moduli \(z^{i}\).
`DcDW`(moduli, moduli_c, tau, tau_c, fluxes[, ...])	Returns a matrix containing the mixed second Kähler derivatives \(D_{\overline{I}}D_{J}W\).
`F`(moduli[, conj])	Computes the pre-potential for given values of the moduli.
`F_LCS`(moduli[, conj])	Calculates the value of the LCS prepotential in terms of the complex structure moduli \(z^{i}\).
`F_LCS_poly`(moduli[, conj])	Computes the polynomial contribution \(F_{\mathrm{poly}}\) to the LCS prepotential \(F_{\mathrm{LCS}}\) in terms of the complex structure moduli \(z^i\).
`F_inst`(moduli[, conj])	Returns the instanton part \(F_{\mathrm{inst}}\) of the LCS prepotential \(F_{\mathrm{LCS}}\) in terms of the complex structure moduli \(z^i\).
`H`(moduli, moduli_c, tau, tau_c, fluxes[, ...])	Returns the Hessian of the scalar potential.
`ISD_condition`(moduli, moduli_c, tau, tau_c, ...)	Checks whether the fluxes satisfy the ISD condition \(\star G_3=\text{i}G_3\).
`ISD_matrix`(moduli, moduli_c)	Computes the value of the ISD-matrix \(\mathcal{M}\).
`K`(moduli, moduli_c, tau, tau_c)	Returns the value of the Kähler potential.
`M`(moduli, moduli_c)	Computes the value of the ISD-matrix \(\mathcal{M}\).
`N`(moduli, moduli_c[, conj])	Computes the value of the gauge kinetic matrix \(\mathcal{N}\).
`N_matrix`(M)	The N-matrix \(N_{ab} = \kappa_{abc}\, M^c\).
`Pi`(moduli[, conj])	Returns the period vector \(\Pi\) at a given point in moduli space.
`Pi_vec`(moduli[, conj])	Returns the period vector \(\Pi\) at a given point in moduli space.
`Q`()	Returns the D3-tadpole for the flux sector.
`V`(moduli, moduli_c, tau, tau_c, fluxes[, ...])	Returns the value of the \(F\)-term scalar potential.
`V_tilde`(moduli, moduli_c)	Returns the value of the mirror dual Calabi-Yau volume.
`V_x`(x, fluxes[, noscale])	Returns the value of the real part of the F-term scalar potential \(V\) for input of the real scalar fields.
`W`(moduli, tau, fluxes[, conj, normalise])	Calculates the value of the superpotential for given flux, moduli and axio-dilaton.
`W0`(moduli, tau, fluxes[, conj, normalise])	Calculates the value of the gauge invariant version of the flux superpotential.
`__init__`([h12, model_ID, model_type, limit, ...])	Initializes a flux EFT class representing the effective field theory of the flux sector in 4D Type IIB string theory compactified on Calabi-Yau threefolds with 3-form flux backgrounds.
`apply_monodromy`(moduli, fluxes, n)	Apply a monodromy shift \(z^a \to z^a + n^a\) to the moduli and transform the fluxes accordingly via the monodromy matrix \(M(n)\).
`calibrate_priors`([Q, modes, n_test, ...])	Empirically refine the Gaussian-prior σ per ISD mode by binary-search.
`canonical_fterms`(moduli, moduli_c, tau, ...)	Returns the canonically normalised \(F\)-term conditions \(F_I,\, F^I\).
`christoffel_symbols`(moduli, moduli_c, tau, tau_c)	Returns the Christoffel symbols \(\Gamma^E_{AC}\) of the Levi-Civita connection on the Kähler moduli space.
`classify_solution`(x, flux[, noscale, min_tol])	Classify a converged critical-point candidate `(x, flux)`: returns `{V, \|DW\|, eigenvalues, is_susy, is_minimum, Nflux}`.
`compute_residual`(x[, axis])	Computes residual.
`compute_tau_vev`(moduli, flux)	Computes the value of the axio-dilaton \(\tau\) from the fluxes and complex structure moduli as a solution to the corresponding \(F\)-term condition \(D_{\tau}W=0\).
`conifold_monodromy_matrix`([conifold_curve, ...])	Picard-Lefschetz monodromy matrix around a conifold singularity where a 3-cycle \(\gamma = \sum_a c_a A^a\) shrinks to zero.
`dDW`(moduli, moduli_c, tau, tau_c, fluxes[, conj])	Returns the holomorphic derivative \(\partial_{I}D_{J}W\) of the \(F\)-terms \(D_{J}W\) with respect to the complex structure moduli \(z^i\) and the axio-dilaton \(\tau\).
`dDW_c`(moduli, moduli_c, tau, tau_c, fluxes)	Returns the holomorphic derivative \(\partial_{\overline{I}}D_{J}W\) of the \(F\)-terms \(D_{J}W\) with respect to the complex conjugate complex structure moduli \(\overline{z}^i\) and the axio-dilaton \(\overline{\tau}\).
`dDW_ctau`(moduli, moduli_c, tau, tau_c, fluxes)	Returns the holomorphic derivative \(\partial_{\overline{\tau}}D_{J}W\) of the \(F\)-term \(D_{J}W\) with respect to the complex conjugate axio-dilaton \(\overline{\tau}\).
`dDW_cz`(moduli, moduli_c, tau, tau_c, fluxes)	Returns the holomorphic derivative \(\partial_{\overline{z}^i}D_{J}W\) of the \(F\)-term \(D_{J}W\) with respect to the complex conjugate complex structure moduli \(\overline{z}^i\).
`dDW_real`(moduli, tau, fluxes)	Returns the Jacobian \(\partial_{\phi^\alpha}(D_J W)\) of the \(F\)-terms with respect to the real scalar fields \(\phi^\alpha = (a^i, v^i, c_0, s)\).
`dDW_tau`(moduli, moduli_c, tau, tau_c, fluxes)	Returns the holomorphic derivative \(\partial_{\tau}D_{J}W\) of the \(F\)-terms \(D_{J}W\) with respect to the the axio-dilaton \(\tau\).
`dDW_tau_ctau`(moduli, moduli_c, tau, tau_c, ...)	Returns the holomorphic derivative \(\partial_{\overline{\tau}}D_{\tau}W\) of the \(F\)-term \(D_{\overline{\tau}}W\) with respect to the complex conjugate axio-dilaton \(\overline{\tau}\).
`dDW_tau_cz`(moduli, moduli_c, tau, tau_c, fluxes)	Returns the holomorphic derivative \(\partial_{\overline{z}^i}D_{\tau}W\) of the \(F\)-term \(D_{\tau}W\) with respect to the complex conjugate complex structure moduli \(\overline{z}^i\).
`dDW_tau_tau`(moduli, moduli_c, tau, tau_c, fluxes)	Returns the holomorphic derivative \(\partial_{\tau}D_{\tau}W\) of the \(F\)-term \(D_{\tau}W\) with respect to the axio-dilaton \(\tau\).
`dDW_tau_z`(moduli, moduli_c, tau, tau_c, fluxes)	Returns the holomorphic derivative \(\partial_{z^i}D_{\tau}W\) of the \(F\)-term \(D_{\tau}W\) with respect to the complex structure moduli \(z^i\).
`dDW_x`(x, fluxes)	Returns the first derivatives of the F-term conditions by differentiating with respect to the real fields.
`dDW_z`(moduli, moduli_c, tau, tau_c, fluxes)	Returns the holomorphic derivative \(\partial_{z^i}D_{J}W\) of the \(F\)-terms \(D_{J}W\) with respect to the complex structure moduli \(z^i\).
`dDW_z_ctau`(moduli, moduli_c, tau, tau_c, fluxes)	Returns the holomorphic derivative \(\partial_{\overline{\tau}}D_{z^j}W\) of the \(F\)-term \(D_{z^j}W\) with respect to the complex conjugate axio-dilaton \(\overline{\tau}\).
`dDW_z_cz`(moduli, moduli_c, tau, tau_c, fluxes)	Returns the holomorphic derivative \(\partial_{\overline{z}^i}D_{z^j}W\) of the \(F\)-term \(D_{z^j}W\) with respect to the complex conjugate complex structure moduli \(\overline{z}^i\).
`dDW_z_tau`(moduli, moduli_c, tau, tau_c, fluxes)	Returns the holomorphic derivative \(\partial_{\tau}D_{z^j}W\) of the \(F\)-term \(D_{z^j}W\) with respect to the axio-dilaton \(\tau\).
`dDW_z_z`(moduli, moduli_c, tau, tau_c, fluxes)	Returns the holomorphic derivative \(\partial_{z^i}D_{z^j}W\) of the \(F\)-term \(D_{z^j}W\) with respect to the complex structure moduli \(z^i\).
`dF`(moduli[, conj])	Computes the holomorphic derivative \(\partial_{z^i} F\) of the prepotential \(F\) for given values of the moduli.
`dGamma`(moduli, moduli_c, tau, tau_c)	Returns the holomorphic derivative of the Christoffel symbols \(\partial_B \Gamma^E_{AC}\).
`dIKM_c`(moduli, moduli_c, tau, tau_c)	Returns the anti-holomorphic derivative of the inverse Kähler metric \(\partial_{\bar{B}} K^{I\bar{J}}\).
`dK`(moduli, moduli_c, tau, tau_c)	Returns the holomorphic derivative \(\partial_I K\) of the Kähler potential \(K\) with respect to the complex structure moduli \(z^{i}\) and the axio-dilaton \(\tau\).
`dK_c`(moduli, moduli_c, tau, tau_c)	Returns the holomorphic derivative \(\partial_{\overline{I}} K\) of the Kähler potential \(K\) with respect to the complex conjugate complex structure moduli \(\overline{z}^{i}\) and the axio-dilaton \(\overline{\tau}\).
`dK_ctau`(moduli, moduli_c, tau, tau_c)	Returns the anti-holomorphic derivative \(\partial_{\overline{\tau}}K\) of the Kähler potential \(K\) with respect to the conjugate axio-dilaton \(\overline{\tau}\).
`dK_cz`(moduli, moduli_c, tau, tau_c)	Returns the anti-holomorphic derivative \(\partial_{\overline{z}^i}K\) of the Kähler potential \(K\) with respect to the conjugate complex structure moduli \(\overline{z}^i\).
`dK_tau`(moduli, moduli_c, tau, tau_c)	Returns the holomorphic derivative \(\partial_{\tau}K\) of the Kähler potential \(K\) with respect to the axio-dilaton \(\tau\).
`dK_z`(moduli, moduli_c, tau, tau_c)	Returns the holomorphic derivative \(\partial_{z^i}K\) of the Kähler potential \(K\) with respect to the complex structure moduli \(z^i\).
`dM`(moduli, moduli_c)	Returns the holomorphic derivative \(\partial_{z^i}\mathcal{M}\) of the ISD-matrix \(\mathcal{M}\) with respect to the complex structure moduli \(z^i\).
`dM_X`(moduli, moduli_c)	Returns the holomorphic derivative \(\partial_{X^I}\mathcal{M}\) of the ISD-matrix \(\mathcal{M}\) with respect to the periods \(X^I\).
`dM_c`(moduli, moduli_c)	Returns the anti-holomorphic derivative \(\partial_{\overline{z}^i}\mathcal{M}\) of the ISD-matrix \(\mathcal{M}\) with respect to the complex conjugate complex structure moduli \(\overline{z}^i\).
`dM_cX`(moduli, moduli_c)	Returns the anti-holomorphic derivative \(\partial_{\overline{X}^I}\mathcal{M}\) of the ISD-matrix \(\mathcal{M}\) with respect to the complex conjugate periods \(\overline{X}^I\).
`dN`(moduli, moduli_c[, conj])	Returns the holomorphic derivative \(\partial_{z^i}\mathcal{N}\) of the gauge kinetic matrix \(\mathcal{N}\) with respect to the complex structure moduli \(z^i\).
`dN_X`(moduli, moduli_c[, conj])	Returns the holomorphic derivative \(\partial_{X^I}\mathcal{N}\) of the gauge kinetic matrix \(\mathcal{N}\) with respect to the periods \(X^I\).
`dN_c`(moduli, moduli_c[, conj])	Returns the anti-holomorphic derivative \(\partial_{\overline{z}^i}\mathcal{N}\) of the gauge kinetic matrix \(\mathcal{N}\) with respect to the complex conjugate complex structure moduli \(\overline{z}^i\).
`dN_cX`(moduli, moduli_c[, conj])	Returns the anti-holomorphic derivative \(\partial_{\overline{X}^I}\mathcal{N}\) of the gauge kinetic matrix \(\mathcal{N}\) with respect to the complex conjugate periods \(\overline{X}^I\).
`dV`(moduli, moduli_c, tau, tau_c, fluxes[, ...])	Returns the first holomorphic derivative \(\partial_{I}V\) of the \(F\)-term scalar potential \(V\).
`dV_tau`(moduli, moduli_c, tau, tau_c, fluxes)	Returns the first holomorphic derivative \(\partial_{\tau}V\) of the \(F\)-term scalar potential \(V\) with respect to the axio-dilaton \(\tau\).
`dV_x`(x, fluxes[, noscale])	Returns the gradients of the F-term scalar potential \(V\) with respect to the real scalar fields for real inputs.
`dV_z`(moduli, moduli_c, tau, tau_c, fluxes[, ...])	Returns the first holomorphic derivative \(\partial_{z^i}V\) of the \(F\)-term scalar potential \(V\) with respect to the complex structure moduli \(z^i\).
`dW`(moduli, tau, fluxes[, conj])	Calculates the holomorphic derivative \(W_I\) of the superpotential \(W\) with respect to all moduli \((z^i, \tau)\).
`dW_tau`(moduli, tau, fluxes[, conj])	Calculates the holomorphic derivative \(W_\tau=\partial_{\tau}W\) of the superpotential \(W\) with respect to the axio-dilaton \(\tau\).
`dW_z`(moduli, tau, fluxes[, conj])	Calculates the holomorphic derivative \(W_i=\partial_{z^i}W\) of the superpotential \(W\) with respect to the complex structure moduli \(z^{i}\).
`ddDW`(moduli, moduli_c, tau, tau_c, fluxes[, ...])	Returns the second derivative of the \(F\)-terms \(\partial_A(D_I W)\).
`ddDW_x`(x, fluxes)	Returns the second derivatives of the F-term conditions by differentiating with respect to the real fields.
`ddIKM`(moduli, moduli_c, tau, tau_c)	Returns the mixed second derivative of the inverse Kähler metric \(\partial_A\partial_{\bar{B}} K^{I\bar{J}}\).
`ddK_ctau_ctau`(moduli, moduli_c, tau, tau_c)	Returns the second holomorphic derivatives of the Kähler potential with respect to the axio-dilaton \(\tau\).
`ddK_cz_ctau`(moduli, moduli_c, tau, tau_c)	Returns the second derivatives \(K_{\bar{\imath}\overline{\tau}}=\partial_{\overline{z}^i}\partial_{\overline{\tau}}K\) of the Kähler potential \(K\) with respect to the complex conjugate complex structure moduli \(\overline{z}^i\) and the axio-dilaton \(\overline{\tau}\).
`ddK_cz_cz`(moduli, moduli_c, tau, tau_c)	Returns the second anti-holomorphic derivatives of the Kähler potential with respect to the complex structure moduli \(z^i\).
`ddK_cz_tau`(moduli, moduli_c, tau, tau_c)	Returns the second derivatives \(K_{\tau\overline{j}}=\partial_{\tau}\partial_{\overline{z}^{j}}K\) of the Kähler potential \(K\) with respect to the conjugate complex structure moduli \(\overline{z}^i\) and the axio-dilaton \(\tau\).
`ddK_cz_z`(moduli, moduli_c, tau, tau_c)	Returns the second derivatives \(K_{\bar{\jmath}i}=\partial_{\overline{z}^j}\partial_{z^i}K\) of the Kähler potential \(K\) with respect to the complex structure moduli \(z^i\) and their conjugate.
`ddK_tau_ctau`(moduli, moduli_c, tau, tau_c)	Returns the second derivatives \(\partial_{\tau}\partial_{\overline{\tau}}K\) of the Kähler potential \(K\) with respect to the axio-dilaton \(\tau\) and its conjugate.
`ddK_tau_tau`(moduli, moduli_c, tau, tau_c)	Returns the second holomorphic derivatives of the Kähler potential with respect to the axio-dilaton \(\tau\).
`ddK_z_ctau`(moduli, moduli_c, tau, tau_c)	Returns the second derivatives \(K_{i\overline{\tau}}=\partial_{z^i}\partial_{\overline{\tau}}K\) of the Kähler potential \(K\) with respect to the complex structure moduli \(z^i\) and the conjugate axio-dilaton \(\overline{\tau}\).
`ddK_z_cz`(moduli, moduli_c, tau, tau_c)	Returns the second derivatives \(K_{i\bar{\jmath}}=\partial_{z^i}\partial_{\overline{z}^j}K\) of the Kähler potential \(K\) with respect to the complex structure moduli \(z^i\) and their conjugate.
`ddK_z_tau`(moduli, moduli_c, tau, tau_c)	Returns the second holomorphic derivatives of the Kähler potential with respect to the complex structure moduli \(z^i\) and the axio-dilaton \(\tau\).
`ddK_z_z`(moduli, moduli_c, tau, tau_c)	Returns the second holomorphic derivatives of the Kähler potential with respect to the complex structure moduli \(z^i\).
`ddV`(moduli, moduli_c, tau, tau_c, fluxes[, ...])	Returns the second derivatives \((\partial_I\partial_J V,\,\partial_I\partial_{\bar J}V)\) of the \(F\)-term scalar potential.
`ddV_ctau`(moduli, moduli_c, tau, tau_c, fluxes)	Returns the mixed second derivatives \(\partial_{I}\partial_{\bar\tau}V\) of the \(F\)-term scalar potential.
`ddV_cz`(moduli, moduli_c, tau, tau_c, fluxes)	Returns the mixed second derivatives \(\partial_{I}\partial_{\bar{z}^j}V\) of the \(F\)-term scalar potential.
`ddV_tau`(moduli, moduli_c, tau, tau_c, fluxes)	Returns the second derivatives \(\partial_{I}\partial_{\tau}V\) of the \(F\)-term scalar potential.
`ddV_x`(x, fluxes[, noscale])	Returns the second derivatives of the F-term scalar potential \(V\) with respect to the real scalar fields for real inputs.
`ddV_z`(moduli, moduli_c, tau, tau_c, fluxes)	Returns the holomorphic second derivatives \(\partial_{I}\partial_{z^j}V\) of the \(F\)-term scalar potential.
`ddW`(moduli, tau, fluxes[, conj])	Calculates the full second holomorphic derivatives \(W_{IJ}=\partial_I\partial_J W\) of the superpotential.
`ddW_tau_tau`(moduli, tau, fluxes[, conj])	Calculates \(W_{\tau\tau}=\partial_\tau^2 W\).
`ddW_z_tau`(moduli, tau, fluxes[, conj])	Calculates the mixed second derivative \(W_{i\tau}=\partial_{z^i}\partial_{\tau}W\) of the superpotential.
`ddW_z_z`(moduli, tau, fluxes[, conj])	Calculates the second holomorphic derivatives \(W_{ij}=\partial_{z^i}\partial_{z^j}W\) of the superpotential.
`dddK`(moduli, moduli_c, tau, tau_c)	Returns the third holomorphic-mixed Kähler derivative \(\partial_{A} K_{C\bar{F}}\) with respect to the combined field-space index \(A = (z^i, \tau)\).
`dddK_c`(moduli, moduli_c, tau, tau_c)	Returns the third anti-holomorphic-mixed Kähler derivative \(\partial_{\bar{B}} K_{C\bar{F}}\) with respect to the combined anti-holomorphic field-space index \(\bar{B} = (\bar{z}^i, \bar{\tau})\).
`dedup_key`(moduli, tau, fluxes[, n_digits])	Hashable dedup key for a single `(moduli, tau, fluxes)` triple. Suitable for incremental `set` / `dict` membership tests in a streaming sampling loop.
`deduplicate_vacua`(moduli, tau, fluxes[, ...])	Removes duplicate vacua from a batch of solutions.
`flux_to_pfv`(flux)	Returns M- and K-vector specifying PFV from full flux vector.
`from_eft`(eft[, sampler, map_to_fd, ...])	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.
`from_model`([model])	Deprecated alias for `from_eft()`, kept for backward compatibility. The classmethod and its first argument were renamed from `from_model(model, ...)` to `from_eft(eft, ...)` because the argument is a `FluxEFT`, not a generic "model". The old `model=` keyword still works; a `DeprecationWarning` is emitted.
`fterm_solver`(moduli, tau, fluxes[, ...])	Solves F-term conditions for a given optimiser.
`gauge_kinetic_matrix`(moduli, moduli_c[, conj])	Computes the value of the gauge kinetic matrix \(\mathcal{N}\).
`hessian`(moduli, moduli_c, tau, tau_c, fluxes)	Returns the Hessian of the scalar potential.
`inverse_kahler_metric`(moduli, moduli_c, tau, ...)	Returns the inverse Kähler metric \(K^{\overline{I}J}\).
`inverse_kahler_metric_grad`(moduli, moduli_c, ...)	Returns the gradient of the inverse Kähler metric.
`is_physical`(x[, moduli_max, verbose])	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`.
`kahler_metric`(moduli, moduli_c, tau, tau_c)	Computes the Kähler metric \(K_{\overline{I}J}\).
`kahler_potential`(moduli, moduli_c, tau, tau_c)	Returns the value of the Kähler potential.
`linearised_shifts`(moduli, tau, fluxes[, Q, ...])	Computes the linearised shifts for the complex structure moduli and the axio-dilaton.
`linearised_shifts_F`(moduli, tau, fluxes[, ...])	Computes linearised shifts for the complex structure moduli and axio-dilaton based on given F-flux.
`linearised_shifts_H`(moduli, tau, fluxes[, ...])	Computes linearised shifts for the complex structure moduli and axio-dilaton based on given H-flux.
`linearised_shifts_ISD`(moduli, tau, fluxes[, ...])	Computes the linearised shifts for the complex structure moduli and the axio-dilaton based on \(ISD_+\)-sampling for fluxes.
`load_calibration`(path)	Load calibrated prior parameters from a JSON file produced by `save_calibration()`.
`map_to_fd`(moduli, tau, fluxes[, axion_fd, ...])	Maps a vacuum solution `(moduli, tau, fluxes)` to the fundamental domain by:
`map_to_fd_tau`(tau, fluxes[, ...])	Map of the axio-dilaton value and the flux vector to the fundamental domain (FD) of \(\text{SL}(2,\mathbb{Z})\).
`mass_matrix`(moduli, moduli_c, tau, tau_c, fluxes)	Returns the mass matrix after canonical normalisation of the kinetic terms.
`mirror_volume`(moduli, moduli_c)	Returns the value of the mirror dual Calabi-Yau volume.
`moduli_to_periods`(moduli[, conj])	Transforms complex structure moduli to periods for the global choice of gauge.
`monodromy_matrix`(n)	Computes the monodromy matrix \(T(\vec{n})\) for a general integer shift \(z^a \to z^a + n^a\).
`monodromy_matrix_single`(b)	Computes the monodromy matrix \(T_b\) for the shift \(z^b \to z^b + 1\).
`newton_method_flux_vacua`(moduli, tau, fluxes)	Solves the minimum conditions for flux vacua using Newton's method.
`period_vector`(moduli[, conj])	Returns the period vector \(\Pi\) at a given point in moduli space.
`periods_to_moduli`(XPer)	Transforms periods to complex structure moduli.
`pfv_conditions`(M, K)	Evaluate the perturbatively-flat-vacuum conditions of arXiv:2512.17095 for the flux quanta `(M, K)`; accepts batches.
`pfv_data`(M, K)	Return a `PFVData` for this model and the flux quanta `(M, K)`.
`pfv_p_vector`(M, K)	The PFV p-vector. For LCS this is \(p = N^{-1}K\) (length `h12`); for coniLCS it is the bulk-only \(\hat{p} = \hat{N}^{-1} K_{\rm bulk}\) (length `h12-1`), for which \(z = \hat{p}\,\tau\) holds only in the bulk (`z_cf` is the separate exponential throat).
`pfv_racetrack`(M, K)	Leading-order analytic estimate of the PFV effective-theory vacuum from the 2-term racetrack (arXiv:2512.17095 §6.2 eqs 6.28, 6.38, 6.40).
`pfv_to_flux`(M, K)	Returns full flux vector from M- and K-vector specifying PFV.
`pfv_to_moduli`(M, K, tau)	Returns values of the complex structure moduli at the level of the PFV.
`prepot`(moduli[, conj])	Computes the pre-potential for given values of the moduli.
`projection_fluxes`(moduli, tau, fluxes[, mode])	Computes the Hodge decomposition of the 3-form flux \(G_3 = F_3 - \tau H_3\) into its \((p,q)\)-components on the Calabi-Yau threefold.
`riemann_tensor`(moduli, moduli_c, tau, tau_c)	Returns the Riemann curvature tensor \(R_{i\bar{\jmath}k\bar{l}}\) of the Kähler moduli space.
`run_calibration`([Q, n_sample, n_test, ...])	Convenience wrapper that runs the full Gaussian-M-prior calibration pipeline in one call:
`sample_SUSY_flux_vacua`([N, sampler, ...])	Samples SUSY flux vacua.
`sample_SUSY_vacua_from_fluxes`([fluxes_init, ...])	Samples SUSY flux vacua for given input fluxes.
`sample_critical_points`([Q, n_target, ...])	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.
`save_calibration`(Q[, path, flux_prior])	Save calibrated prior parameters to a JSON file for reuse.
`scalar_potential`(moduli, moduli_c, tau, ...)	Returns the value of the \(F\)-term scalar potential.
`superpotential`(moduli, tau, fluxes[, conj, ...])	Calculates the value of the superpotential for given flux, moduli and axio-dilaton.
`superpotential_gauge_invariant`(moduli, tau, ...)	Calculates the value of the gauge invariant version of the flux superpotential.
`tadpole`(fluxes)	Calculates the D3-charge for given fluxes.
`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.
`verify_monodromy`(b[, z, tol, mode])	Numerically verify the monodromy matrix by checking \(T_b \cdot \Pi(z) = \Pi(z + e_b)\).

Attributes

`F_coniLCS_bulk`	** Class-level descriptor: surfaces a method only when the instance's limit is in the coniLCS family. Otherwise raises AttributeError so hasattr() returns False.
`F_coniLCS_exp`	** Class-level descriptor: surfaces a method only when the instance's limit is in the coniLCS family. Otherwise raises AttributeError so hasattr() returns False.
`F_coniLCS_series`	** Class-level descriptor: surfaces a method only when the instance's limit is in the coniLCS family. Otherwise raises AttributeError so hasattr() returns False.
`W_bulk`	** Class-level descriptor: surfaces a method only when the instance's limit is in the coniLCS family. Otherwise raises AttributeError so hasattr() returns False.
`W_log_coeff`	** Class-level descriptor: surfaces a method only when the instance's limit is in the coniLCS family. Otherwise raises AttributeError so hasattr() returns False.
`compute_zcf`	** Class-level descriptor: surfaces a method only when the instance's limit is in the coniLCS family. Otherwise raises AttributeError so hasattr() returns False.
`compute_zcf_x`	** Class-level descriptor: surfaces a method only when the instance's limit is in the coniLCS family. Otherwise raises AttributeError so hasattr() returns False.
`conifold_fluxes`	** Class-level descriptor: surfaces a method only when the instance's limit is in the coniLCS family. Otherwise raises AttributeError so hasattr() returns False.
`dF_coniLCS_exp`	** Class-level descriptor: surfaces a method only when the instance's limit is in the coniLCS family. Otherwise raises AttributeError so hasattr() returns False.
`dK_cf_bulk`	** Class-level descriptor: surfaces a method only when the instance's limit is in the coniLCS family. Otherwise raises AttributeError so hasattr() returns False.
`lcs_tree`	Description: The `lcs_tree` object containing the topological data (intersection numbers, second Chern class, GV invariants, etc.) for the underlying Calabi-Yau geometry.
`log_coeff_K_corr`	** Class-level descriptor: surfaces a method only when the instance's limit is in the coniLCS family. Otherwise raises AttributeError so hasattr() returns False.
`log_prefactor`	** Class-level descriptor: surfaces a method only when the instance's limit is in the coniLCS family. Otherwise raises AttributeError so hasattr() returns False.
`sampler`	Description: Lazily-initialised `data_sampler` for this model.
`zcf_handling`	** Class-level descriptor: surfaces a method only when the instance's limit is in the coniLCS family. Otherwise raises AttributeError so hasattr() returns False.

calibrate_priors(Q=None, modes=None, n_test=200, target_acceptance=0.8, sampler=None, verbose=True)#

Empirically refine the Gaussian-prior σ per ISD mode by binary-search.

For each mode in modes, scans σ in [0.1, 20.0] over 12 binary- search iterations to find the σ where the measured ISD-completion acceptance rate ≈ target_acceptance. “Acceptance” = fraction of random N(0, σ²I) inputs that, when ISD-completed via the sampler and tadpole-filtered against Q, give a valid flux.

Result overrides the analytical defaults from _estimate_sigmas() (C2). This is the empirical refinement step: ~1–5 s per mode, produces model-adaptive parameters that can be cached via save_calibration().

Note: calibrate_priors ends with an optional “runaway diagnostic” that calls sample_critical_points on 50 candidates. That is omitted here — the σ-calibration math is byte-for-byte equivalent; only the diagnostic print is dropped. Users wanting runaway stats can run sample_critical_points() directly after calibration.

Parameters:

Q (int) – tadpole bound (required; method-level here, per the C-cluster convention).
modes (list[str], optional) – modes to calibrate. Default: ["F", "H", "ISD+", "ISD-"].
n_test (int) – number of candidates per σ trial. Default: 200.
target_acceptance (float) – target acceptance rate. Default: 0.8.
sampler (data_sampler, optional) – sampler instance. If None (default), uses self.sampler.
verbose (bool) – print per-mode results.

Returns:

``dict[str, float]`` – copy of the calibrated σ values per mode.

Return type:

dict

Side effects:

Writes self._calibrated_sigmas[mode] = σ for each mode.

Writes self._calibration_isd_modes = tuple(modes) to record which modes are empirically calibrated.

classify_solution(x, flux, noscale=True, min_tol=1e-06)#

Classify a converged critical-point candidate (x, flux): returns {V, |DW|, eigenvalues, is_susy, is_minimum, Nflux}.

Thin delegator over jaxvacua.flux_utils.classify_solution(). See its docstring for argument and return-value detail.

Return type:: dict

compute_residual(x, axis=1)#

Computes residual.

Parameters:: x (Array) – Array.
Returns:: Array – Sum of absolute values.

dedup_key(moduli, tau, fluxes, n_digits=6)#

Hashable dedup key for a single (moduli, tau, fluxes) triple. Suitable for incremental set / dict membership tests in a streaming sampling loop.

Distinct from deduplicate_vacua(), which is a batched jnp.unique pass over an entire solution set.

Thin delegator over jaxvacua.flux_utils.dedup_key(). See its docstring for argument and return-value detail.

Note (2026-05-17 arg-order change): flipped from legacy (flux, moduli, tau) to (moduli, tau, fluxes) for project-wide consistency.

deduplicate_vacua(moduli, tau, fluxes, n_digits=8, boundary_tol=1e-08, axion_fd=None)#

Removes duplicate vacua from a batch of solutions.

If map_to_fd=True (set at construction), vacua are first mapped to the fundamental domain via map_to_fd() (monodromy + \(\text{SL}(2,\mathbb{Z})\)), so that monodromy-equivalent solutions are identified. If map_to_fd=False, deduplication is performed on the raw (moduli, tau, fluxes) values directly.

In both cases, duplicates are identified by rounding to n_digits decimal places. Note that a single flux vector can admit multiple distinct vacua, so the fingerprint always includes moduli and tau.

Parameters:

moduli (Array) – Complex structure moduli, shape (N, h12).
tau (Array) – Axio-dilaton values, shape (N,).
fluxes (Array) – Flux vectors, shape (N, 2*n_fluxes).
n_digits (int) – Number of decimal digits for rounding when identifying duplicates. Default 8.
boundary_tol (float) – Points within this tolerance of the FD boundary are snapped to the boundary. Default 1e-8. Only used when map_to_fd=True.
axion_fd (Optional[Tuple[float, float]]) – Axion fundamental domain (lo, hi). If None, uses self.axion_fd. Only used when map_to_fd=True.

Returns:

Tuple[Array, Array, Array, Array] – (moduli_unique, tau_unique, fluxes_unique, keep_indices)

Return type:

Tuple[Array, Array, Array, Array]

See also: map_to_fd()

classmethod from_eft(eft, sampler=None, map_to_fd=False, flux_bounds=(-10, 10), axion_bounds=(-0.5, 0.5), dilaton_bounds=(2.0, 10.0), moduli_bounds=(1.0, 5.0), seed=42)#

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.

Use this when:

You already have a FluxEFT and want to run a finder on it without rebuilding the geometry (which can be slow for large h12).
You want multiple finders on the same FluxEFT (e.g. different sampler bounds, different map_to_fd).
You have a custom FluxEFT subclass and want the finder methods on top of it.

Internally clones the eft’s __dict__ into a freshly allocated FluxVacuaFinder instance. The two instances thereafter share references to the same arrays / sub-objects (lcs_tree, periods, css, …). Mutating the eft will be visible on the finder; mutating finder-only state (_map_to_fd, _calibrated_sigmas, …) does not leak back into the eft.

Parameters:

eft (FluxEFT) – Instance whose state to clone.
sampler (data_sampler) – If given, used instead of lazy-constructing one from the bounds kwargs.
map_to_fd (bool) – Whether to map results to the fundamental domain. Defaults to False.
flux_bounds (tuple) – Forwarded to data_sampler; only used if sampler is None.
axion_bounds (tuple) – Forwarded to data_sampler; only used if sampler is None.
dilaton_bounds (tuple) – Forwarded to data_sampler; only used if sampler is None.
moduli_bounds (tuple) – Forwarded to data_sampler; only used if sampler is None.
seed (int) – Forwarded to data_sampler; only used if sampler is None.

Returns:

FluxVacuaFinder – New instance sharing geometry with eft.

Return type:

FluxVacuaFinder

Example:

eft    = jvc.FluxEFT(h12=2, model_ID=1, maximum_degree=5)
# ... use eft for some FluxEFT-only work ...
finder = jvc.FluxVacuaFinder.from_eft(eft)
vacua  = finder.sample_critical_points(Q=200, n_target=10)

classmethod from_model(model=None, *args, **kwargs)#

Deprecated alias for from_eft(), kept for backward compatibility. The classmethod and its first argument were renamed from from_model(model, ...) to from_eft(eft, ...) because the argument is a FluxEFT, not a generic “model”. The old model= keyword still works; a DeprecationWarning is emitted.

Return type:: FluxVacuaFinder

fterm_solver(moduli, tau, fluxes, objective_fct=None, optimiser=None, tol=1e-10, max_iters=100, print_progress=False, mode=None)#

Solves F-term conditions for a given optimiser.

Parameters:

moduli (Array) – Complex structure moduli values.
tau (complex) – Value of axio-dilaton.
fluxes (Array) – Array of fluxes. The ordering starts with RR-fluxes, then the NSNS-fluxes.
objective_fct (Optional[Callable]) – Objective function to miminise.
optimiser (Optional[Callable]) – Optimiser to be used for the minimisation.
tol (float) – Tolerance for the residual. Defaults to 1e-10.
max_iters (int) – Maximum number of iterations. Defaults to 100.
print_progress (bool) – Whether to print the progress of the minimisation. Defaults to False.
mode (str) – Mode for running the solver. Defaults to None.

Returns:

int – Number of iterations.
Array – Complex structure moduli values.
Array – Value of axio-dilaton.
Array – Array of fluxes. The ordering starts with RR-fluxes, then the NSNS-fluxes.
Array – Boolean array specifying whether constraints are satisfied.
Array – Residuals \(\sum_A |D_A W|\) of the \(F\)-terms.

Return type:

Tuple[int, Array, Array, Array, Array, Array]

is_physical(x, moduli_max=None, verbose=False)#

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.

Thin delegator over jaxvacua.flux_utils.is_physical(), passing self as both the model and the source of the sampler (via self.sampler). See the helper’s docstring for full cascade detail.

Pass verbose=True to print which check rejected the point (useful for debugging “why was my candidate filtered?”).

Return type:: bool

linearised_shifts(moduli, tau, fluxes, Q=None, mode='ISD', return_flag=True, constraints=None, remove_NANs=False, step_size=1.0)#

Computes the linearised shifts for the complex structure moduli and the axio-dilaton.

Parameters:

moduli (Array) – Starting point for the complex structure moduli.
tau (complex) – Starting point for the axio-dilaton.
fluxes (Array) – Array of fluxes. The ordering starts with RR-fluxes, then the NSNS-fluxes.
Q (int | None) – Tadpole bound to be used in the computation for the constraints.
mode (str) – Computation mode for obtaining the linearised shifts.
constraints (Optional[Callable]) – Additional constraints to be imposed on the solutions.
remove_NANs (bool) – Whether to remove NaN values from input. Defaults to False.
step_size (float) – Damping factor applied to the linearised shift; the moduli/axio-dilaton are updated by step_size times the computed shift. 1.0 recovers the full (undamped) step. Defaults to 1.0.

Returns:

Array – Shifted values for the complex structure moduli \(Z^i\).
complex – Shifted value for the axio-dilaton \(\tau\).
Array – Updated values for the fluxes based on the ISD-condition.
bool, optional – Boolean specifying whether the constraints are satisfied.

Return type:

Union[Tuple[Array, complex, Array], Tuple[Array, complex, Array, Array]]

linearised_shifts_F(moduli, tau, fluxes, mode='Fflux', return_shifts=False, remove_NANs=False, step_size=1.0)#

Computes linearised shifts for the complex structure moduli and axio-dilaton based on given F-flux.

Parameters:

moduli (Array) – Starting point for the complex structure moduli.
tau (complex) – Starting point for the axio-dilaton.
fluxes (Array) – Array of fluxes. The ordering starts with RR-fluxes, then the NSNS-fluxes.
mode (str) – Computation mode for obtaining the linearised shifts. Defaults to "Fflux".
return_shifts (bool) – Whether to return the shifts for the moduli or the shifted moduli. Defaults to False.
remove_NANs (bool) – Whether to remove NaN values from input. Defaults to False.
step_size (float) – Damping factor applied to the linearised shift; the moduli/axio-dilaton are updated by step_size times the computed shift. 1.0 recovers the full (undamped) step. Defaults to 1.0.

Returns:

Array – Moduli shifts or shifted values of the complex structure moduli \(Z^i\).
complex – Axio-dilaton shift or shifted value of the axio-dilaton \(\tau\).
Array – Values of the fluxes.

Return type:

Union[Tuple[Array, complex, Array], Tuple[Array, complex, Array, Array]]

linearised_shifts_H(moduli, tau, fluxes, mode='Hflux', return_shifts=False, remove_NANs=False, step_size=1.0)#

Computes linearised shifts for the complex structure moduli and axio-dilaton based on given H-flux.

Parameters:

moduli (Array) – Starting point for the complex structure moduli.
tau (complex) – Starting point for the axio-dilaton.
fluxes (Array) – Array of fluxes. The ordering starts with RR-fluxes, then the NSNS-fluxes.
mode (str) – Computation mode for obtaining the linearised shifts.
return_shifts (bool) – Whether to return the shifts for the moduli or the shifted moduli. Defaults to False.
remove_NANs (bool) – Whether to remove NaN values from input. Defaults to False.
step_size (float) – Damping factor applied to the linearised shift; the moduli/axio-dilaton are updated by step_size times the computed shift. 1.0 recovers the full (undamped) step. Defaults to 1.0.

Returns:

Array – Moduli shifts or shifted values of the complex structure moduli \(Z^i\).
complex – Axio-dilaton shift or shifted value of the axio-dilaton :math:` au`.
Array – Values of the fluxes.

Return type:

Union[Tuple[Array, complex, Array], Tuple[Array, complex, Array, Array]]

linearised_shifts_ISD(moduli, tau, fluxes, mode='ISD', return_shifts=False, remove_NANs=False, step_size=1.0)#

Computes the linearised shifts for the complex structure moduli and the axio-dilaton based on \(ISD_+\)-sampling for fluxes.

Parameters:

moduli (Array) – Values for the complex structure moduli.
tau (complex) – Value of the axio-dilaton.
fluxes (Array) – Array of fluxes. The ordering starts with RR-fluxes, then the NSNS-fluxes.
mode (str) – Computation mode for obtaining the linearised shifts.
return_shifts (bool) – Whether to return the shifts for the moduli or the shifted moduli. Defaults to False.
remove_NANs (bool) – Whether to remove NaN values from input. Defaults to False.
step_size (float) – Damping factor applied to the linearised shift; the moduli/axio-dilaton are updated by step_size times the computed shift. 1.0 recovers the full (undamped) step. Defaults to 1.0.

Returns:

Array – Moduli shifts or shifted values of the complex structure moduli \(Z^i\).
complex – Axio-dilaton shift or shifted value of the axio-dilaton :math:` au`.
Array – Values of the fluxes.

Return type:

Union[Tuple[Array, complex, Array], Tuple[Array, complex, Array, Array]]

load_calibration(path)#

Load calibrated prior parameters from a JSON file produced by save_calibration().

Sets self._calibrated_sigmas from the loaded "sigmas" block; also restores self._calibration_isd_modes so subsequent code can tell which modes were calibrated.

Parameters:

path (str) – JSON file path.

Returns:

``dict[str, float]`` – the loaded σ values per mode (also stored
on ``self``).

Return type:

dict

newton_method_flux_vacua(moduli, tau, fluxes, mode=None, step_size_Newton=0.1, tol=1e-10, max_iters=100, print_progress=False, solver_mode='complex', moduli_max=None)#

Solves the minimum conditions for flux vacua using Newton’s method.

Parameters:

moduli (Array) – Complex structure moduli values.
tau (complex) – Value of axio-dilaton.
fluxes (Array) – Array of fluxes. The ordering starts with RR-fluxes, then the NSNS-fluxes.
mode (str) – Whether to solve F-term conditions \(D_IW=0\) for SUSY minima or instead \(\partial_IV=0\) for general minima. Defaults to None.
step_size_Newton (float) – Step size to be used in Newton’s method. Defaults to 0.1.
tol (float) – Tolerance for the residual. Defaults to 1e-10.
max_iters (int) – Maximum number of iterations. Defaults to 100.
print_progress (bool) – Whether to print the progress of the minimisation. Defaults to False.
solver_mode (str) – Solver mode to use for the computation. Available options are "real" or "complex" to solve equations in terms of real or complex fields. Defaults to "complex".

Returns:

Array – Complex structure moduli values.
Array – Value of axio-dilaton.
float – Residual \(\sum_A |D_A W|\) of the \(F\)-terms.

Return type:

Tuple[int, Array, Array, float]

run_calibration(Q=None, n_sample=50, n_test=200, target_acceptance=0.8, modes=None, sampler=None, verbose=True)#

Convenience wrapper that runs the full Gaussian-M-prior calibration pipeline in one call:

_precompute_M_eigensystem() — eigen-decomposes the best-conditioned ISD matrix across n_sample moduli points.
_estimate_sigmas() — analytical σ-per-mode defaults from the eigensystem.
calibrate_priors() — empirical binary-search refinement to hit target_acceptance.

Roughly 1-5 s per ISD mode on h12=2 (longer for larger geometries). Recommended before any sample_critical_points() run with flux_prior="gaussian" (the default) for non-trivial Q.

Parameters:

Q (int) – tadpole bound for both stages. Default: self.Q().
n_sample (int) – moduli points scanned in step 1. Default: 50.
n_test (int) – candidates per σ trial in step 3. Default: 200.
target_acceptance (float) – target acceptance rate for the binary-search. Default: 0.8.
modes (list) – ISD modes to calibrate. Default: ["F", "H", "ISD+", "ISD-"].
sampler (data_sampler, optional) – defaults to self.sampler.
verbose (bool) – print per-step progress.

Returns:

``dict[str, float]`` – the calibrated σ per ISD mode (also
stored on ``self._calibrated_sigmas``).

Return type:

dict

Example:

finder = jvc.FluxVacuaFinder(h12=2, model_ID=1)
finder.run_calibration(Q=200)
vacua = finder.sample_critical_points(
    Q=200, n_target=100, solver="hybrid",
)

sample_SUSY_flux_vacua(N=100, sampler=None, rns_key=None, max_iters=10, moduli_sampling_mode='cone', Q=None, objective_fct=None, optimiser=None, optimisers=None, constraints=None, mode=None, tol=1e-10, vmap_dim=100, print_progress=False, deduplicate=True, step_size=1.0, max_resample_attempts=200, max_batches=1000, errors='raise')#

Samples SUSY flux vacua.

Parameters:

N (int) – Defaults to 100.
sampler (data_sampler, optional) – Defaults to None.
rns_key (PRNGKey, optional) – PRNG random key. Defaults to None.
max_iters (int) – Maximum number of iterations. Defaults to 100.
moduli_sampling_mode (str) – Sampling mode for the moduli values. Defaults to "cone".
Q (int | None) – Maximum tadpole to use for the sampling. Defaults to None.
objective_fct (Optional[Callable]) – Objective function to miminise.
optimiser (Optional[Callable]) – Optimiser to be used for the minimisation.
optimisers (list | None) – List of optimisers to be used for the minimisation.
tol (float) – Tolerance for the residual. Defaults to 1e-10.
print_progress (bool) – Whether to print the progress of the minimisation. Defaults to False.
constraints (Optional[Callable]) – Defaults to None.
mode (str | None) – Solving mode specifying we want to solve F-term conditions with random fluxes (mode="random") or using ISD bias (mode="ISD") for the fluxes. Defaults to None.
vmap_dim (int) – Array dimension to use in vmapping. Defaults to 100.
step_size (float) – Damping factor forwarded to linearised_shifts(); the moduli/axio-dilaton are updated by step_size times the linearised shift each iteration. 1.0 is the full step. Defaults to 1.0.
max_resample_attempts (int) – Maximum number of times initial guesses are re-sampled while searching for a batch in which at least one candidate passes the one-step filter. Bounds the inner loop so a geometry/mode that rarely yields passing candidates cannot spin forever. Defaults to 200.
max_batches (int) – Maximum number of outer sampling batches before giving up on reaching N. Defaults to 1000.
errors (str) – Behaviour when max_resample_attempts or max_batches is exhausted — "raise" raises a RuntimeError (fail fast), "warn" emits a warning and returns the partial result. Defaults to "raise".

Returns:

Tuple[Array, Array, Array, Array] – Complex structure moduli, axio-dilaton values, fluxes, and residuals.

Return type:

Tuple[Array, Array, Array, Array]

sample_SUSY_vacua_from_fluxes(fluxes_init=None, initial_guesses=None, N=100, sampler=None, rns_key=None, max_iters=10, moduli_sampling_mode='cone', Q=None, objective_fct=None, optimiser_init=None, optimiser_steps=None, constraints=None, mode=None, tol=1e-10, vmap_dim_flux=10, vmap_dim_pts=10, print_progress=False, deduplicate=True, step_size=1.0, max_batches=1000, errors='raise')#

Samples SUSY flux vacua for given input fluxes.

Parameters:

fluxes_init (Array, optional) – Input fluxes.
initial_guesses (Tuple[Array,Array], optional) – Initial guesses. Format: (moduli,tau).
N (int, optional) – Defaults to 100.
sampler (data_sampler, optional) – Defaults to None.
rns_key (PRNGKey, optional) – PRNG random key. Defaults to None.
max_iters (int, optional) – Maximum number of iterations. Defaults to 100.
moduli_sampling_mode (str, optional) – Sampling mode for the moduli values. Defaults to "cone".
Q (int, optional) – Maximum tadpole to use for the sampling. Defaults to None.
objective_fct (Callable, optional) – Objective function to miminise.
optimiser (Callable, optional) – Optimiser to be used for the minimisation.
optimisers (list, optional) – List of optimisers to be used for the minimisation.
tol (float, optional) – Tolerance for the residual. Defaults to 1e-10.
print_progress (bool, optional) – Whether to print the progress of the minimisation. Defaults to False.
constraints (Callable, optional) – Defaults to None.
mode (str, optional) – Solving mode specifying we want to solve F-term conditions with random fluxes (mode="random") or using ISD bias (mode="ISD") for the fluxes. Defaults to None.
vmap_dim_flux (int, optional) – Array dimension to use in vmapping over fluxes. Defaults to 10.
vmap_dim_pts (int, optional) – Array dimension to use in vmapping over initial guesses. Defaults to 10.
step_size (float) – Damping factor forwarded to linearised_shifts(); the moduli/axio-dilaton are updated by step_size times the linearised shift each iteration. 1.0 is the full step. Defaults to 1.0.
max_batches (int) – Maximum number of sampling batches before giving up on reaching N. Bounds the loop so it cannot spin forever. Defaults to 1000.
errors (str) – Behaviour when max_batches is exhausted — "raise" raises a RuntimeError (fail fast), "warn" emits a warning and returns the partial result. Defaults to "raise".

Returns:

int – Number of iterations.
Array – Complex structure moduli values.
Array – Value of axio-dilaton.
Array – Boolean array specifying whether constraints are satisfied.
Array – Residuals \(\sum_A |D_A W|\) of the \(F\)-terms.

Return type:

Tuple[Array, Array, Array, Array]

sample_critical_points(Q=None, n_target=100, n_batch=10000, max_batches=20, isd_mode='ISD-', solver='newton', step_size=1.0, newton_tol=1e-10, newton_max_iters=300, optax_steps=1000, optax_objective='dV2', optimiser=None, classify=True, deduplicate=True, noscale=True, flux_prior='gaussian', flux_prior_sigma=None, moduli_max=None, map_to_fd=None, sampler=None, verbose=True)#

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.

Ties together _generate_flux_candidates() (C3), the chosen refinement solver, is_physical() (A3), to_fd() (A4), dedup_key() (A1), and classify_solution() (A2).

Solver dispatch (solver kwarg):

"newton" — FVF Newton via jax.vmap() over the converged batch. Uses the B1+B2 guards (runaway escape + singular-Hessian protection). Best when starting points are already near a critical point (e.g. SUSY-mode initialisations).

"adam" / "lbfgs" — per-candidate _solve_dV_optax_single(). Python loop; slow but robust to bad initial conditions. Useful for one-off debugging or when optax-only convergence is desired.

"adam_v" — batched _solve_dV_optax_batch() with cosine-decay schedule + gradient clipping. Vectorised via lax.scan + vmap. First-order so wider basin of attraction; pair with optax_steps in the high hundreds.

"hybrid" — adam_v warm-start (fast vmapped optax) followed by per-candidate Newton polish on the near-converged subset. Default-recommended for large non-SUSY scans — combines the robustness of optax with Newton’s quadratic convergence.

"scipy" — per-candidate scipy.optimize.root(method='hybr') with analytical Jacobian. Sequential Python loop. Robust; useful when the JAX-side solvers struggle.

Quick decision table (typical for h12=2, Q=200, n_batch≈1000):

solver	speed	robustness	when to use
newton	fastest	moderate	warm starts; SUSY-like inits
adam_v	fast	high (1st- order)	cold starts; large batch
hybrid	moderate	very high	default for non-SUSY sampling at scale
scipy	slow (no JAX)	very high	small N, debugging, when JAX paths fail
adam, lbfgs	slowest (per-cand)	high (1st- order)	single-candidate diagnostics

The C-cluster convention applies: formerly-instance kwargs are now method-level.

Parameters:

Q (int) – tadpole bound. Default: self.Q() (the geometry’s natural maximum).
n_target (int) – stop once this many critical points are found. Default: 100.
n_batch (int) – candidates per batch. Default: 10_000.
max_batches (int) – batch cap. Default: 20.
isd_mode (str) – one of "F", "H", "ISD+", "ISD-". Default: "ISD-".
solver (str) – see dispatch table above. Default: "newton".
step_size (float) – Newton step size. Default: 1.0.
newton_tol (float) – convergence tolerance. Default: 1e-10.
newton_max_iters (int) – Newton iteration cap. Default: 300.
optax_steps (int) – step count for optax solvers. Default: 1000.
optax_objective (str) – "dV2", "log_dV2", or "V". Default: "dV2".
optimiser (optax.GradientTransformation, optional) – custom optimiser overrides solver.
classify (bool) – attach Hessian classification. Default: True.
deduplicate (bool) – streaming dedup via dedup_key(). Default: True.
noscale (bool) – pass-through to V/dV/ddV. Default: True.
flux_prior (str) – "gaussian" (default), "M_weighted", or "uniform".
flux_prior_sigma (float) – per-call σ override.
moduli_max (float) – runaway bound for Newton’s B1 guard. Also used post-warm-start in solver="hybrid".
map_to_fd (bool) – if None (default), uses self._map_to_fd. Explicit True/False overrides.
sampler (data_sampler, optional) – defaults to self.sampler.
verbose (bool) – print per-batch + final summary. Default: True.

Returns:

``list[dict]`` – one dict per surviving critical point with keys
``flux``, ``moduli``, ``tau``, ``residual``, and (when
``classify=True``) ``V``, ``|DW|``, ``eigenvalues``,
``is_susy``, ``is_minimum``, ``Nflux``.

Return type:

list

property sampler: data_sampler#

Description: Lazily-initialised data_sampler for this model.

The sampler is constructed on first access and cached for subsequent calls. Sampling bounds are configured via the constructor arguments flux_bounds, axion_bounds, dilaton_bounds, moduli_bounds, and seed. To use a custom sampler instead, pass it explicitly to methods that accept a sampler keyword argument.

save_calibration(Q, path=None, flux_prior='gaussian')#

Save calibrated prior parameters to a JSON file for reuse.

Parameters:

Q (int) – tadpole bound the calibration is for. Required; used in the default filename and recorded in the JSON.
path (str) – explicit save path. If None (default), uses jaxvacua/models/{model_type}/h12_{h12}/critical_points_prior_Q{Q}.json, falling back to the current directory.
flux_prior (str) – "gaussian", "M_weighted", or "uniform" — recorded in the JSON. Default: "gaussian".

Returns:

str – path to the saved file.

Return type:

str

Pre-requisite:

self._calibrated_sigmas must be populated (via _estimate_sigmas() or calibrate_priors()).

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.

Whether the mapping is applied is controlled by the constructor flag self._map_to_fd (set via map_to_fd= kwarg at finder construction). If False, the inputs are returned unchanged.

Thin delegator over jaxvacua.flux_utils.map_to_fd(). See its docstring for full detail and the rationale for keeping this as a separate wrapper over map_to_fd() (the actual math method).

Return type:: tuple

jaxvacua.flux_vacua_finder.FluxVacuaFinder

Contents

jaxvacua.flux_vacua_finder.FluxVacuaFinder#