jaxvacua.freezer.ConifoldFreezer

jaxvacua.freezer.ConifoldFreezer#

class ConifoldFreezer(model, conifold_index=0)#

Bases: Freezer

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

Near the conifold locus, the conifold modulus acquires a parametrically large mass from the flux superpotential. Its leading-order EOM gives

(3)#\[z_{\text{cf}} = -\frac{1}{2\pi i} \exp\!\Bigl(-\frac{2\pi i\,\widetilde{W}_1}{n_{\text{cf}}(M_1 - \tau H_1)}\Bigr)\]

where \(\widetilde{W}_1\) is the effective superpotential contribution from the bulk moduli and \(n_{\text{cf}}\) is the conifold degree.

Parameters:

model (Any) – A flux EFT model with "coniLCS" in model.periods.limit.
conifold_index (int) – Index of the conifold modulus in the moduli array. Defaults to 0.

Note

The conifold degree \(n_{\text{cf}}\) is not a constructor argument; it is exposed read-only through the ncf property (sourced from model.lcs_tree.conifold.ncf).

__init__(model, conifold_index=0)#

Initialise the ConifoldFreezer.

Parameters:

model (Any) – A flux EFT model with "coniLCS" in model.periods.limit.
conifold_index (int) – Index of the conifold modulus in the moduli array. Defaults to 0.

_conifold_index#

Stored index of the conifold modulus.

Type:: int

Methods

`DW_light`(z_light, z_light_c, tau, tau_c, fluxes)	Covariant derivatives \(D_i W\) for the light moduli (+ \(D_\tau W\)) with the conifold modulus on-shell. General basis: project the full \(D_i W\) onto the bulk directions, \(D_a W = D_i W\, \text{bulk\_embedding}^{i}{}_{a}\) (the conifold component \(D_i W\,e_q^i = \partial_{z_{\rm cf}}W \approx 0\) on-shell).
`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.
`G_x_light`(x_light, fluxes[, x_full, method])	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.
`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.
`V_x_light`(x_light, fluxes[, noscale])	Scalar potential \(V\) evaluated at the light-field coordinates, with heavy moduli on-shell.
`__init__`(model[, conifold_index])	Initialise the ConifoldFreezer.
`bulk_mass_spectrum`(x_light, fluxes, **kwargs)	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.
`dDW_x_light`(x_light, fluxes, **kwargs)	Hessian \(\partial_{x^a}\partial_{x^b} W\) in real coordinates for the light moduli.
`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.
`ddV_x_light`(x_light, fluxes[, noscale, ...])	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.
`full_real_point`(x_light, fluxes, **kwargs)	Full real coordinate vector with the heavy moduli on-shell -- the value accepted by the `x_full` argument of `ddV_x_light()` and `light_mass_spectrum()`.
`light_mass_spectrum`(x_light, fluxes, **kwargs)	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.
`reconstruct_full_moduli`(z_light, tau, ...)	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}\).
`solve_heavy`(z_light, tau, fluxes[, conj, ...])	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).
`superpotential`(z_light, tau, fluxes, **kwargs)	Superpotential of the reduced theory.

Attributes

`heavy_indices`	Description: Indices of the heavy (conifold) modulus; always a length-1 tuple.
`lcs_tree`	Description: The bound model's period tree, `model.lcs_tree`.
`light_indices`	Description: Indices of the light moduli (complement of `heavy_indices`).
`n_heavy`	Description: Number of heavy moduli.
`n_light`	Description: Number of light moduli.
`ncf`	Description: Conifold degree \(n_{\text{cf}}\), sourced from `self.model.lcs_tree.conifold.ncf` (single source of truth).

DW_light(z_light, z_light_c, tau, tau_c, fluxes, assume_conjugate=False, **kwargs)#

Covariant derivatives \(D_i W\) for the light moduli (+ \(D_\tau W\)) with the conifold modulus on-shell. General basis: project the full \(D_i W\) onto the bulk directions, \(D_a W = D_i W\, \text{bulk\_embedding}^{i}{}_{a}\) (the conifold component \(D_i W\,e_q^i = \partial_{z_{\rm cf}}W \approx 0\) on-shell).

Parameters:

z_light (Array) – Complex light (bulk) moduli, length n_light.
z_light_c (Array) – Complex conjugate of z_light.
tau (complex) – Axio-dilaton.
tau_c (complex) – Complex conjugate of tau.
fluxes (Array) – Full flux vector.
assume_conjugate (bool) – Reuse \(\overline{z_{\rm full}}\) instead of a second heavy solve – evaluation only, see the warning on Freezer.DW_light(). Defaults to False.
**kwargs – Forwarded to reconstruct_full_moduli() / solve_heavy().

Returns:

Array – Complex vector [D_a W (light moduli), D_tau W] of length
``n_light + 1``.

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.

This is the analogue of model.DW_x but restricted to the light degrees of freedom.

Parameters:

x_light (Array) – Real variables for light moduli and axio-dilaton.
fluxes (Array) – Full flux vector.

Returns:

Array – Real gradient restricted to light directions.

Return type:

Array

G_x_light(x_light, fluxes, x_full=None, method='pullback', **kwargs)#

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.

Details

The reduced metric is the mixed second derivative of the substituted Kähler potential \(K(z_{\rm heavy}^\ast(\phi), \phi)\), NOT the light submatrix of the full metric. The substitution couples the light moduli through the heavy solution, so the reduced metric carries chain-rule terms (e.g. complex-structure–dilaton mixing) absent from the bare bulk block.

Concretely, the real symmetric Hessian \(H_K = \partial_{\phi^\alpha}\partial_{\phi^\beta} \mathrm{Re}\,K\) of K_x_light() is taken by automatic differentiation, the complex Hermitian metric \(G_{A\bar B}\) is extracted via _G_from_real_hessian(), and the real metric is rebuilt with _kahler_metric_real_interleaved().

Two equivalent routes – method

"pullback" (default): the reduced metric is the pullback of the full Kähler metric along the on-shell tangent, \(G_{\rm eff} = J^T G_{\rm full} J\), with \(J = \partial x_{\rm full}/\partial\phi\) from _onshell_tangent(). This is exact whenever the heavy solve is holomorphic in the light fields – which F-flatness provides, since \(W\) is holomorphic, so \(z^\ast(\phi)\) is too and the mixed derivative \(\partial\bar\partial K\) picks up no second-derivative term. Cost: one metric evaluation plus one first-order tangent.

"autodiff": the original route, jax.hessian of the substituted K_x_light() straight through the heavy solve. Kept as the reference – it makes no holomorphy assumption – but for PFVEFT(mode="eom") it differentiates through a Newton iteration, which is ~5 orders of magnitude more expensive.

Measured equivalence, and its one caveat. The two routes were compared directly:

PFVEFT (LCS reference PFV, 2x2 reduced metric): relative 4.9e-08, masses agreeing to 8 significant figures.
ConifoldFreezer ("aule" coniLCS, n_light=4, 10x10 reduced metric) with apply_correction=False – i.e. a pure F-term z_cf solve, which is strictly holomorphic: relative 2.9e-16, machine precision, as the argument predicts exactly.
the same with apply_correction=True (the ConifoldFreezer default): relative 1.7e-07.

That last case is not exact, and the reason is physical: the Kähler-covariant z_cf correction depends on \(\bar z\) as well as \(z\), so the heavy solve is no longer strictly holomorphic and the second-derivative term no longer cancels identically. The residual is nine orders of magnitude larger than the holomorphic case, yet still far below the EFT’s own truncation error – so "pullback" remains the sensible default. If you need the assumption-free value (for a convergence study, or a deep throat where the correction is large), use method="autodiff".

Parameters:

x_light (Array) – Real coordinates for light moduli and axio-dilaton.
fluxes (Array) – Full flux vector.
x_full (Optional[Array]) – Full real point with the heavy moduli on-shell (see full_real_point()). Supplying it skips the heavy solve entirely; "autodiff" ignores it, since it must differentiate through that solve.
method (str) – "pullback" (default, first-order) or "autodiff" (the through-the-solve reference).
**kwargs – Forwarded to the heavy solve / K_x_light().

Returns:

Array – Reduced Kähler metric in the real interleaved basis, of shape
`` (2 * n_light + 2, 2 * n_light + 2)

Raises:

ValueError – If method is not one of {"pullback", "autodiff"}.

Return type:

Array

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.

Details

The heavy field is substituted at the level of the potential: the light real coordinates are mapped to the full point via _real_light_to_full() (heavy moduli on-shell), converted to complex moduli, and inserted into the model’s Kähler potential. Using the actual conjugate (rather than an independent \(\bar\phi\)) keeps the result a genuinely real scalar, so its real Hessian — the reduced Kähler metric of G_x_light() — is symmetric and the extracted metric Hermitian by construction.

Parameters:

x_light (Array) – Real coordinates for light moduli and axio-dilaton.
fluxes (Array) – Full flux vector.

Returns:

float – \(\mathrm{Re}\,K(z_{\rm heavy}^\ast(\phi), \phi)\).

Return type:

float

V_x_light(x_light, fluxes, noscale=True, **kwargs)#

Scalar potential \(V\) evaluated at the light-field coordinates, with heavy moduli on-shell.

Parameters:

x_light (Array) – Real coordinates for light moduli and axio-dilaton.
fluxes (Array) – Full flux vector.
noscale (bool) – If True, uses the no-scale scalar potential \(V = e^K K^{I\bar J} D_I W D_{\bar J}\bar W\). Defaults to True.

Returns:

float – Value of \(V\) with heavy moduli at their on-shell values.

Return type:

float

bulk_mass_spectrum(x_light, fluxes, **kwargs)#

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.

Parameters:

x_light (Array) – Real bulk-field coordinates (moduli + axio-dilaton).
fluxes (Array) – Full flux vector.
**kwargs – Forwarded to light_mass_spectrum() (reduction, dw_tol, x_full, eig_backend, …).

Returns:

LightSpectrum – The reduced bulk-field spectrum with its stability
diagnostics.

Return type:: LightSpectrum

dDW_x_light(x_light, fluxes, **kwargs)#

Hessian \(\partial_{x^a}\partial_{x^b} W\) in real coordinates for the light moduli.

Parameters:

x_light (Array) – Real variables for light moduli and axio-dilaton.
fluxes (Array) – Full flux vector.

Returns:

Array – Hessian restricted to light directions.

Return type:

Array

dV_x_light(x_light, fluxes, noscale=True, **kwargs)#

Gradient of the scalar potential \(\nabla_\phi V\) with respect to the real light-field coordinates, with heavy moduli on-shell.

Details

Let \(\phi^\alpha = (a^1, v^1, \ldots, a^{n_{\rm light}}, v^{n_{\rm light}}, c_0, s)\) denote the real light-field coordinates, where \(z^i = a^i + \mathrm{i}\,v^i\) and \(\tau = c_0 + \mathrm{i}\,s\). This function returns the restriction

(6)#\[\nabla_\phi V \big|_{\phi^\alpha} = \partial_{\phi^\alpha} V(x_{\rm full}(\phi))\]

where \(x_{\rm full}(\phi)\) substitutes the on-shell heavy moduli via _real_light_to_full().

Parameters:

x_light (Array) – Real coordinates for light moduli and axio-dilaton.
fluxes (Array) – Full flux vector.
noscale (bool) – If True, uses the no-scale scalar potential. Defaults to True.

Returns:

Array – Gradient \(\partial_{\phi^\alpha} V\), restricted to
light directions, of shape `` (2 * n_light + 2,)

Return type:

Array

ddV_x_light(x_light, fluxes, noscale=True, reduction='frozen', x_full=None, **kwargs)#

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.

Details

The real light-field coordinates are \(\phi^\alpha = (a^1, v^1, \ldots, a^{n_{\rm light}}, v^{n_{\rm light}}, c_0, s)\) (with \(z^i = a^i + \mathrm{i}\,v^i\) and \(\tau = c_0 + \mathrm{i}\,s\)). Four reduction schemes are provided via reduction:

"frozen" (default): the selection block \(J^T (\nabla\nabla V) J\), with the heavy moduli held at their on-shell values but WITHOUT the back-reaction of the light fields on the heavy solution.
"schur": the Schur complement on the heavy block,

(7)#\[H_{\rm eff} = H_{\ell\ell} - H_{\ell h} H_{hh}^{-1} H_{h\ell}\, ,\]

which integrates the heavy moduli out at their V-minimum (\(\partial_{z_{\rm heavy}} V = 0\), obtained by extremising the quadratic form over the heavy directions). This is the right reduction when a genuinely heavy modulus really is integrated out at its potential minimum (ConifoldFreezer); it is exact only where that heavy direction is on-shell, so pass x_full (the stored full point) — otherwise the heavy field is reconstructed from the analytic solve, which is on-shell only deep in the throat, and schur can return a spurious tachyon at moderate throats.

Important

For a PFVEFT the moduli are not at a V-minimum: they are slaved along the flat direction (\(\partial_z W = 0\)), which is not a V-valley. "schur" then computes a genuinely different reduction from the racetrack \(\tau\)-mass and lands a few \(\times\) off it (verified against a finite-difference reference and the racetrack). Use "tangent" / "autodiff" (the F-flat slaving) for a PFV mass; "schur" there is a V-minimum diagnostic, not the physical mass.

Only the heavy block \(H_{hh}\) is inverted, so it is well conditioned at a genuine vacuum, but the back-reaction is a difference of large nearly cancelling terms once the heavy/light mass hierarchy approaches 1/eps (deep in a conifold throat); there it loses precision.
"autodiff": the Hessian of \(V(x_{\rm full}(\phi))\) differentiated directly through the on-shell heavy solve, so the back-reaction enters automatically via the chain rule. This builds a fresh jax.hessian trace on each call (the inner kernels are cached, the outer transform is not), so jit/loop accordingly for repeated use. Exact everywhere but the most expensive option.
"tangent": the same physical reduced Hessian as "autodiff" at a genuine vacuum, built from the first-order on-shell tangent \(J = \partial x_{\rm full}/\partial\phi\) (one jax.jacfwd of the heavy solve): \(H_{\rm eff} = J^T(\nabla\nabla V)J\). Avoiding the second-order jax.hessian makes it orders of magnitude cheaper (a warm call is ~instant). Unlike "schur" — which integrates the moduli out at their V-minimum — it follows the physical F-flat slaving (\(\partial_z W = 0\), the racetrack direction) and carries no large-cancellation precision loss. It differs from "frozen" only in that \(J\) is the true on-shell tangent (with the heavy back-reaction), not the constant leading-order one. Drops the \(O(\partial V)\) term, so it is exact only at a critical point — the recommended choice for masses at a vacuum.

Warning

reduction="frozen" omits the integrate-out back-reaction \(-H_{\ell h} H_{hh}^{-1} H_{h\ell}\), which can dominate (or flip the sign of) the lightest light mass in a conifold throat. It equals "autodiff" only for LCS in mode="ansatz" (the linear ansatz map, where \(\partial^2 x_{\rm full}/\partial\phi^2 = 0\)); in mode="eom" it keeps the constant ansatz tangent at the on-shell point, so on an exponentially small mass it can be \(O(10^2)\) off. For any vacuum mass prefer reduction="tangent" (fast + exact) or "autodiff" (robust off-shell); "schur" computes the V-minimum reduction (right for a genuinely heavy modulus, but off the racetrack mass for a PFV) and also loses precision when the heavy/light hierarchy is large. Note light_mass_spectrum() pairs the frozen Hessian with the substituted reduced metric, so its eigenvalues are a hybrid (a no-back-reaction Hessian against a with-back-reaction metric), not the naive frozen masses.

Parameters:

x_light (Array) – Real coordinates for light moduli and axio-dilaton.
fluxes (Array) – Full flux vector.
noscale (bool) – If True, uses the no-scale scalar potential. Defaults to True.
reduction (str) – Reduction scheme, one of {"frozen", "schur", "autodiff", "tangent"}. Defaults to "frozen" (the backwards-compatible leading-order block; note light_mass_spectrum() resolves its own, per-class default instead). For a mass at a vacuum "tangent" is the fast + exact choice; "schur" gives the V-minimum reduction (right for a genuinely heavy modulus, not for a PFV flat direction). Distinct from the mode keyword (forwarded via **kwargs to the heavy solve).
x_full (Optional[Array]) – Full real point at which to evaluate the Hessian for "frozen"/"schur" (e.g. the stored vacuum, with the heavy field on-shell). If None (default) the heavy field is reconstructed from the analytic solve via _real_light_to_full(). Ignored by "autodiff" (which differentiates through the solve).

Returns:

Array – Reduced Hessian restricted to light directions, of shape
`` (2 * n_light + 2, 2 * n_light + 2)

Return type:

Array

full_real_point(x_light, fluxes, **kwargs)#

Full real coordinate vector with the heavy moduli on-shell – the value accepted by the x_full argument of ddV_x_light() and light_mass_spectrum().

Why you want this

The heavy solve is by far the most expensive part of a reduced-EFT evaluation (for PFVEFT(mode="eom") it is a Newton iteration). Reconstruct the point once and pass it as x_full to evaluate several reductions – or a whole mass spectrum – at the same vacuum without repeating the solve. When you already have a certified vacuum (e.g. from a root find, or a stored jaxvacua.vacuum.Vacuum), pass that instead of reconstructing at all.

Parameters:

x_light (Array) – Real coordinates for light moduli and axio-dilaton.
fluxes (Array) – Full flux vector.
**kwargs – Forwarded to the heavy solve.

Returns:

Array – Full real coordinate vector of length 2*(h12+1).

Return type:

Array

property heavy_indices: Tuple[int, ...]#

Description: Indices of the heavy (conifold) modulus; always a length-1 tuple.

Returns:: tuple[int, …] – The single conifold-modulus index.

property lcs_tree: Any#

Description: The bound model’s period tree, model.lcs_tree.

A delegating property rather than a stored attribute on purpose. Storing it would (i) duplicate the entire period/GV payload as a second set of traced children in every compiled kernel (freezers are registered pytrees, see _register_freezer_pytree()), and (ii) freeze a snapshot of a mutable object, so an in-place lcs_tree edit would leave the freezer disagreeing with its own model.

Returns:: Any – The model’s lcs_tree.

property light_indices: Tuple[int, ...]#

Description: Indices of the light moduli (complement of heavy_indices).

Returns:: tuple[int, …] – The light-modulus indices.

light_mass_spectrum(x_light, fluxes, **kwargs)#

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.

Parameters:

x_light (Array) – Real light-field coordinates (moduli + axio-dilaton).
fluxes (Array) – Full flux vector.
**kwargs – Forwarded to Freezer.light_mass_spectrum() (reduction, noscale, dw_tol, x_full, eig_backend, …); apply_correction defaults to True.

Returns:

LightSpectrum – The reduced light-field spectrum with its stability
diagnostics.

jaxvacua.freezer.ConifoldFreezer

Contents

jaxvacua.freezer.ConifoldFreezer#