jaxvacua.periods

Period and prepotential machinery for Calabi-Yau threefolds.

Purpose

Define the periods class, the low-level object that evaluates period vectors, prepotentials and derived special-geometry data in supported regions of complex-structure moduli space.

Main public API

• periods: loads or constructs model data from lcs_tree, dictionaries, saved model files, CYTools input or custom period/prepotential callables.

• LCS, coniLCS and one-modulus hypergeometric period/prepotential implementations, including polynomial and instanton contributions.

• Period vectors, derivatives, gauge-kinetic matrices and projective/affine coordinate conversions consumed by css and FluxEFT.

Design notes

This is the numerical core below the geometry classes. It is JAX-pytree compatible and keeps model data in forms suitable for JIT-compiled downstream calculations.

Computational graph

This layer assembles the prepotential, the period vector and the Kähler potential from the topological data carried on lcs_tree. At large complex structure (LCS) the prepotential decomposes into a cubic polynomial part (driven by the intersection numbers \(\kappa_{ijk}\), the linear coefficients \(a_{ij}\), the constant \(b_i\) and the Euler characteristic \(\chi\)) and a non-perturbative instanton sum (driven by the genus-zero Gopakumar–Vafa invariants \(n_\beta^0\)):

\begin{align*} F_{\text{poly}}(z) &= -\tfrac{1}{6}\, \kappa_{ijk}\, z^i z^j z^k + \tfrac{1}{2}\, a_{ij}\, z^i z^j + b_i\, z^i + K_0, \\[2pt] F_{\text{inst}}(z) &= -\,\frac{1}{(2\pi i)^3} \sum_{\beta \in H_2(X, \mathbb{Z})_{>0}} n_\beta^0\, \mathrm{Li}_3\!\bigl(q^{\beta}\bigr), \quad q^{\beta} = e^{\,2\pi i\, \beta \cdot z}, \\[2pt] F(z) &= F_{\text{poly}}(z) + F_{\text{inst}}(z). \end{align*}

The period vector and the Kähler potential then read

\begin{align*} \Pi(z) &= \bigl( X^0,\ X^i,\ F_i,\ F_0 \bigr), \quad X^0 = 1,\ X^i = z^i,\ F_i = \partial_i F,\ F_0 = 2 F - z^i \partial_i F, \\[2pt] K(z, \bar z) &= -\log\!\bigl(\, i\, \Pi^\dagger \cdot \Sigma \cdot \Pi \,\bigr), \end{align*}

with \(\Sigma\) the symplectic intersection form on \(H^3(X, \mathbb{Z})\). In the diagram, inherited inputs (light grey) come straight from lcs_tree; the public outputs of the layer (orange) are \(F\), \(\Pi\) and \(K\).

jaxvacua.periods — Computational graph

Inputs (inherited from lcs_tree)

topological data

$\kappa_{ijk}$ ·  $c_2$ ·  $n_\beta^0$
(triple intersections,  second Chern class,  genus-0 GV invariants)

Prepotential

$F_{\rm poly}(z)$

cubic + sub-leading terms
$-\tfrac{1}{6}\, \kappa_{ijk}\, z^i z^j z^k + \tfrac{1}{2}\, a_{ij}(c_2)\, z^i z^j + b_i\, z^i + K_0(\chi)$

$F_{\rm inst}(z)$

non-perturbative instanton sum (jaxpolylog)
$-\dfrac{1}{(2\pi i)^3} \displaystyle\sum_\beta n_\beta^0\, \mathrm{Li}_3\!\bigl(q^{\beta}\bigr),\; q^{\beta} = e^{2\pi i\, \beta \cdot z}$

prepotential $\mathcal{F}(X)$

$X^0\, F(z) = X^0\,\bigl(F_{\rm poly}(z) + F_{\rm inst}(z)\bigr)$
(in projective coordinates $X^I$, with $z^i = X^i / X^0$)

Outputs (consumed by css and FluxEFT)

$\Pi(z) = (\mathcal{F}_I, X^I)$

$X^0=1,\; X^i = z^i$,  $\mathcal{F}_i = \partial_i \mathcal{F},\; \mathcal{F}_0 = 2\mathcal{F} - z^i \partial_i \mathcal{F}$
periods.period_vector_per

$K(z, \bar z)$

$K = -\!\log\!\bigl(-i\, \Pi^\dagger \Sigma\, \Pi\bigr)$
periods.kahler_potential_per

$\mathcal{N}_{IJ}(X)$

gauge-kinetic matrix in projective coordinates
periods.gauge_kinetic_matrix

Period class

periods([h12, model_ID, model_type, limit, ...])

Period class for Calabi-Yau threefold compactifications. Provides functions to compute periods, prepotential, Kähler potential, gauge kinetic matrix, and derived objects at various moduli space limits (LCS, coniLCS, etc.).

Prepotential

periods.prepot_per(XPer[, conj])	Computes the prepotential \(F\) in terms of the periods \(X^I\).
periods.prepot_grad_per(XPer[, conj])	Computes the holomorphic derivatives \(F_{I}=\partial_{X^I}F\) of the prepotential \(F\) with respect to the periods \(X^I\).
periods.prepot_grad_grad_per(XPer[, conj])	Computes the second holomorphic derivatives \(F_{IJ}=\partial_{X^I}\partial_{X^J}F\) of the prepotential \(F\) with respect to the periods \(X^I\).

Period vector and derivatives

periods.period_vector_per(XPer[, conj])	Computes the period vector \(\Pi\) in terms of the periods \(X^I\).
periods.grad_period_vector_per(XPer[, conj])	Computes derivatives \(\partial_{X^I}\Pi\) of the period vector \(\Pi\) with respect to the periods :mathh`X^I`.
periods.D_period_vector_per(XPer, cXPer[, conj])	Computes the Kähler convariant derivative \(D_I\Pi\). of the period vector \(\Pi\).
periods.PQ_per(XPer, cXPer[, conj])	Computes the matrices \(P_{IJ}\) and \(Q^{I}\,_{J}\).
periods.P_per(XPer, cXPer[, conj])	Computes the matrix \(P_{IJ}\).
periods.Q_inv_per(XPer, cXPer[, conj])	Computes the inverse of the matrix \(Q^{I}\,_{J}\).
periods.Q_per(XPer, cXPer[, conj])	Computes the matrix \(Q^{I}\,_{J}\).

Mirror dual volume and Kähler potential

periods.A_per(XPer, cXPer)	Computes the value of the mirror CY volume \(\tilde{\mathcal{V}}\) as a function of the periods \(X^I\).
periods.kahler_potential_per(XPer, cXPer)	Computes the value of the Kähler potential \(K\) as a function of the periods \(X^I\).
periods.grad_kahler_potential_per(XPer, cXPer)	Computes derivatives \(\partial_{X^I}K\) of the Kähler potential \(K\) with respect to the periods :mathh`X^I`.
periods.sigma()	Returns the symplectic matrix
periods.compute_a_shift_monodromy(shift)	Symplectic monodromy matrix induced by a shift of the prepotential \(a\)-matrix, \(a \to a + S\).

Gauge kinetic matrix

periods.gauge_kinetic_matrix(XPer, cXPer[, conj])	Computes the value of the gauge kinetic matrix \(\mathcal{N}\).
periods.gauge_kinetic_matrix_periods(XPer, cXPer)	Computes value of the gauge kinetic matrix \(\mathcal{N}\) from periods.
periods.gauge_kinetic_matrix_prepotential(...)	Computes value of the gauge kinetic matrix \(\mathcal{N}\) from prepotential.

ISD matrix

periods.ISD_matrix(XPer, cXPer)

Computes the value of the ISD-matrix \(\mathcal{M}\).