jaxvacua.freezer

jaxvacua.freezer#

Reduced EFT interfaces for integrating out heavy moduli.

Purpose#

Provide abstractions for solving heavy-field equations of motion and evaluating a reduced flux EFT on the remaining light fields.

Main public API#

Freezer: abstract base class defining the reduced-EFT interface, including heavy/light index bookkeeping, reconstruction and light-field derivatives.
ConifoldFreezer: concrete implementation for freezing the conifold modulus z_cf in coniLCS models.
Freezer.light_mass_spectrum / LightSpectrum: the reduced light-field mass spectrum, obtained by integrating out the heavy moduli and solving the generalised eigenproblem $H_{\rm eff}\,v = \lambda\,K_{\rm eff}\,v$ in the real interleaved basis – which avoids the ill-conditioning of the full FluxEFT.mass_matrix near a conifold.

Design notes#

Freezers wrap an existing flux model. They do not own the underlying geometry; instead they solve heavy fields as functions of light moduli, axio-dilaton and fluxes, then reuse the model’s superpotential and derivative methods on the reconstructed full field point.

The reduced light-field theory exposes four Hessian-reduction schemes (the reduction argument of Freezer.ddV_x_light() and Freezer.light_mass_spectrum()): "frozen" (the bare leading-order block, no back-reaction – a diagnostic), "schur" (the Schur complement of the heavy block – integrating the moduli out at their V-minimum, the right reduction for a genuinely heavy modulus), "autodiff" (the Hessian of the scalar potential differentiated through the on-shell heavy solve) and "tangent" (the same F-flat reduced Hessian as "autodiff" at a vacuum, from the first-order on-shell tangent – fast). For a PFVEFT the moduli are slaved along the flat direction, not held at a V-minimum, so "tangent"/"autodiff" give the racetrack mass while "schur" gives a different V-minimum value. Masses are formed in the real interleaved basis from a generalised eigenproblem rather than through mass_matrix. The mass-spectrum entry points are eager host-side helpers (NumPy/SciPy at the eigensolve), i.e. not jit/vmap-able; batch over vacua with a Python loop.

When to use this module#

Use a freezer after constructing a full flux effective theory, when one or more complex-structure fields are treated as heavy and should be solved away before scanning the remaining light directions. Freezer provides the base reduced-EFT interface; ConifoldFreezer is the specialised implementation for integrating out a conifold modulus with the coniLCS z_cf equation of motion.

Reduced-EFT workflow#

Wrap the full model with ConifoldFreezer and specify the conifold modulus through conifold_index.
Call solve_heavy to determine the heavy modulus for fixed light moduli, axio-dilaton, and fluxes.
Use reconstruct_full_moduli when a full moduli vector is needed again, for example before evaluating quantities defined on the original model.
Evaluate reduced quantities with superpotential, DW_light, DW_x_light, dDW_x_light, V_x_light, dV_x_light, and ddV_x_light.
Compute the reduced light-field mass spectrum with light_mass_spectrum (aliased as bulk_mass_spectrum on ConifoldFreezer), passing the stored vacuum point through x_full so the reduced Hessian is evaluated with the heavy modulus on-shell.

Index conventions#

heavy_indices names the frozen complex-structure moduli and light_indices is its complement. The counters n_heavy and n_light refer to complex moduli, while real light-field vectors used by the *_x_light methods contain real and imaginary parts of the light moduli plus the real and imaginary parts of tau.

jaxvacua.freezer — heavy/light reduction

Full EFT inputs

full model

FluxEFT data for $W$, $D_IW$, $V$ and derivatives

flux vector

integral $(F_3,H_3)$ data held fixed during reduction

light fields

$z_{\rm light}$ and $\tau$, or real vector $x_{\rm light}$

↓

Index split

heavy_indices

moduli solved away analytically
n_heavy

light_indices

remaining moduli kept in the reduced EFT
n_light

↓

Heavy-field equation of motion

solve_heavy

For ConifoldFreezer, compute $z_{\rm cf}$ from compute_zcf / zcf_handling
optional Kähler-covariant correction included through the coniLCS solver

↓

Reduced evaluation path

reconstruct_full_moduli

insert $z_{\rm heavy}(z_{\rm light},\tau,\mathrm{flux})$ back into the full vector

light-field EFT

superpotential, DW_light, DW_x_light, V_x_light, derivatives

Output: a lower-dimensional Newton or analysis problem on $2\,n_{\rm light}+2$ real fields, with heavy moduli solved consistently at each evaluation.

Freezer base class#

Freezer(model)

Abstract base class for a reduced effective field theory obtained by integrating out a set of heavy moduli.

Light-field EFT interface#

`Freezer.solve_heavy`(z_light, tau, fluxes, ...)	Solve the leading-order EOM for the heavy moduli as functions of the light moduli, axio-dilaton, and fluxes.
`Freezer.reconstruct_full_moduli`(z_light, ...)	Reconstruct the full moduli array by solving for the heavy moduli and inserting them at the correct positions.
`Freezer.superpotential`(z_light, tau, fluxes, ...)	Superpotential of the reduced theory.
`Freezer.DW_light`(z_light, z_light_c, tau, ...)	Covariant derivatives $D_i W$ with respect to the light moduli, with heavy moduli on-shell.
`Freezer.DW_x_light`(x_light, fluxes, **kwargs)	Gradient of the superpotential $\partial_{x^a} W$ in real coordinates for the light moduli, with heavy moduli on-shell.
`Freezer.dDW_x_light`(x_light, fluxes, **kwargs)	Hessian $\partial_{x^a}\partial_{x^b} W$ in real coordinates for the light moduli.
`Freezer.V_x_light`(x_light, fluxes[, noscale])	Scalar potential $V$ evaluated at the light-field coordinates, with heavy moduli on-shell.
`Freezer.dV_x_light`(x_light, fluxes[, noscale])	Gradient of the scalar potential $\nabla_\phi V$ with respect to the real light-field coordinates, with heavy moduli on-shell.
`Freezer.ddV_x_light`(x_light, fluxes[, ...])	Reduced Hessian of the scalar potential $\partial_{\phi^\alpha}\partial_{\phi^\beta} V$ with respect to the real light-field coordinates, with the heavy moduli on-shell.

Reduced mass spectrum#

The reduced light-field masses follow from integrating out the heavy moduli and solving the generalised eigenproblem $H_{\rm eff}\,v = \lambda\,K_{\rm eff}\,v$ in the real interleaved basis, which avoids the ill-conditioning of the full FluxEFT.mass_matrix near a conifold. ddV_x_light supplies the reduced Hessian $H_{\rm eff}$ (through the reduction schemes "frozen", "schur" and "autodiff"), K_x_light and G_x_light the substituted Kähler potential and reduced metric $K_{\rm eff}$, and light_mass_spectrum returns the spectrum together with its stability diagnostics as a LightSpectrum.

`Freezer.K_x_light`(x_light, fluxes, **kwargs)	Real Kähler potential $\mathrm{Re}\,K$ evaluated at the light-field coordinates, with the heavy moduli integrated out on-shell.
`Freezer.G_x_light`(x_light, fluxes[, x_full, ...])	Reduced Kähler metric of the light fields in the real interleaved basis, obtained by integrating out the heavy moduli at the level of the Kähler potential.
`Freezer.light_mass_spectrum`(x_light, fluxes)	Mass spectrum of the light fields with the heavy moduli integrated out.

LightSpectrum(masses, eigenvalues, m2_min, ...)

Container for the light (reduced) mass spectrum returned by Freezer.light_mass_spectrum().

Conifold freezer#

ConifoldFreezer(model[, conifold_index])

Integrates out the conifold modulus $z_{\text{cf}}$ (index 0) in coniLCS models.

Conifold EOM and spectrum#

`ConifoldFreezer.solve_heavy`(z_light, tau, fluxes)	Solve for $z_{\text{cf}}$ from its leading-order EOM by delegating to `jaxvacua.conifold.zcf_solver.compute_zcf()` (the unified complex-coord dispatcher attached to the model).
`ConifoldFreezer.reconstruct_full_moduli`(...)	Reconstruct the full modulus vector from the light (bulk) moduli with the conifold modulus on-shell. Aligned: index scatter (base class). General: $z_{\rm full} = z_{\rm cf}\,e_q + \text{bulk\_embedding}\,z_{\rm light}$.
`ConifoldFreezer.light_mass_spectrum`(x_light, ...)	Conifold-aware override of `Freezer.light_mass_spectrum()`: defaults the z_cf solve to `apply_correction=True` (the Kähler-covariant correction needed for the analytic seed to reproduce the stored vacuum), then defers to the base implementation.
`ConifoldFreezer.bulk_mass_spectrum`(x_light, ...)	Bulk mass spectrum of a coniLCS vacuum with the conifold modulus integrated out. Identical to `light_mass_spectrum()` (here the "bulk" fields are the base-class "light" fields); the alias provides the conifold/throat vocabulary used in the literature. The on-shell `apply_correction=True` z_cf-solve default is applied.

`Freezer.K_x_light`(x_light, fluxes, **kwargs)	Real Kähler potential \(\mathrm{Re}\,K\) evaluated at the light-field coordinates, with the heavy moduli integrated out on-shell.
`Freezer.G_x_light`(x_light, fluxes[, x_full, ...])	Reduced Kähler metric of the light fields in the real interleaved basis, obtained by integrating out the heavy moduli at the level of the Kähler potential.
`Freezer.light_mass_spectrum`(x_light, fluxes)	Mass spectrum of the light fields with the heavy moduli integrated out.

`ConifoldFreezer.solve_heavy`(z_light, tau, fluxes)	Solve for \(z_{\text{cf}}\) from its leading-order EOM by delegating to `jaxvacua.conifold.zcf_solver.compute_zcf()` (the unified complex-coord dispatcher attached to the model).
`ConifoldFreezer.reconstruct_full_moduli`(...)	Reconstruct the full modulus vector from the light (bulk) moduli with the conifold modulus on-shell. Aligned: index scatter (base class). General: \(z_{\rm full} = z_{\rm cf}\,e_q + \text{bulk\_embedding}\,z_{\rm light}\).
`ConifoldFreezer.light_mass_spectrum`(x_light, ...)	Conifold-aware override of `Freezer.light_mass_spectrum()`: defaults the z_cf solve to `apply_correction=True` (the Kähler-covariant correction needed for the analytic seed to reproduce the stored vacuum), then defers to the base implementation.
`ConifoldFreezer.bulk_mass_spectrum`(x_light, ...)	Bulk mass spectrum of a coniLCS vacuum with the conifold modulus integrated out. Identical to `light_mass_spectrum()` (here the "bulk" fields are the base-class "light" fields); the alias provides the conifold/throat vocabulary used in the literature. The on-shell `apply_correction=True` z_cf-solve default is applied.