jaxvacua.flux_bounding

jaxvacua.flux_bounding#

Flux-bounding algorithm for finite-region vacuum enumeration.

Purpose#

Implement the flux-bounding strategy of arXiv:2501.03984 for systematic enumeration of Type IIB flux candidates in bounded regions of moduli space.

Main public API#

Module-level JIT kernels for processing NSNS-flux batches and ISD-completed flux candidates without recompiling per bounded_fluxes instance.
bounded_fluxes: computes local/global eigenvalue bounds, enumerates or samples admissible fluxes, applies tadpole and dilaton constraints, and refines candidates with the vacuum solver.
Cluster/export helpers for splitting large enumeration jobs and merging results.

Design notes#

The implementation is performance-oriented. Expensive kernels are kept at module scope with static shape arguments so models with matching dimensions can share compiled XLA code.

Pipeline overview#

Systematic flux enumeration is the heaviest pipeline in the package. Given an upstream jaxvacua.flux_eft.FluxEFT instance and a flux radius $N_{\max}$, bounded_fluxes enumerates every integer flux

\[G_3 = F_3 - \tau H_3, \qquad (F_3, H_3) \in \mathbb{Z}^{2(h^{1,2}+1)},\]

inside a bounding box subject to physical constraints — the s-bound $s_{\max}$, the D3-tadpole budget $N_{\text{flux}} \leq Q_{\text{O3}}$, and modular reduction along the $\mathrm{SL}(2,\mathbb{Z})$ orbit. Phases 1–4 are filters and lattice operations; phase 5 produces the actual vacua via per-batch ISD completion and multi-start Newton refinement.

In the diagram, the inherited jaxvacua.flux_eft.FluxEFT instance is shown light grey, the user-supplied $N_{\max}$ and the moduli samples for the eigenvalue bounds are shown dashed (external), and the deduplicated output catalogue is highlighted in orange.

jaxvacua.flux_bounding.bounded_fluxes — 5-phase pipeline

Inputs

FluxEFT instance

inherited model
provides $W$, $K$, $\Pi$, ISD matrix

$N_{\max}$

flux radius
$\| h \|, \| f \| \leq N_{\max}$

moduli samples

for eigenvalue bounds in Phase 1

Phase 1 — Eigenvalue convergence sampling

Eigenvalue bounds

Sample moduli, evaluate $\Im\mathcal{N}$ at each
monitor convergence of $\lambda_{\max},\; \widetilde{\lambda}_{\min},\; \widetilde{\lambda}_{\max}$
bounded_fluxes.compute_evs · compute_evs_vmap

Phase 2 — $s_{\max}$ + tadpole filter on $h$

Bounding boxes for $h$

Apply $s_{\max}$, dilaton bound, tadpole budget $N_{\rm flux} \leq Q_{\rm O3}$
$\Longrightarrow$ box of integer $h$-vectors
bounded_fluxes.compute_bounding_box · get_h_box

$h_2$ pool (small)

$\sim 10^3$ candidates
tight bounding box
bound_h2_local

$h_1$ candidates (large)

$\sim 10^6$ candidates
looser bounding box
bound_h1_global

Phase 3 — Streaming flux assembly

Stream $h$ pairs into chunks

$h_2$-outer × $h_1$-inner concat, buffer $\sim 10^5$ rows
to prevent JIT recompilation across chunk shapes
bounded_fluxes.get_h_candidates

Phase 4 — Monodromy reduction

SL$(2,\mathbb{Z})$ orbit reduction

For each candidate $h$, apply monodromy matrices $M_{(n_1, n_2)}$, $n_a \in [-10, 10]$
keep the minimal-$\| h \|^2$ representative; $\sim 1\%$ reduction

Phase 5 — Per-batch ISD completion + Newton

ISD completion + multi-start Newton refinement

$f = s\,M\,\sigma\, h + c_0\, h$, multi-start Newton on $D_I W = 0$
per-batch JIT (_process_h_at_modulus_jit, _process_h_all_moduli_jit)
bounded_fluxes.sample_bounded_fluxes() · newton_refine_batch

Output: Deduplicated catalogue of vacua $(z^*, \tau^*, f, h)$ · $|W_0|$, $g_s$, tadpole, residual.

Cluster-scale execution#

Large flux-bounding runs can be split into independent chunk files and processed on a cluster. export_cluster_job prepares the search once, serialises the pipeline state to pipeline.npz and config.json, writes pre-filtered h-flux chunks under chunks/, and creates a worker script. With generate_slurm=True it also writes a SLURM array submission script.

Each worker calls process_chunk_from_disk for one chunk. The worker reconstructs the saved pipeline, ISD-completes and filters that chunk, and writes a compressed result file under results/. Since chunks are independent, failed or slow array tasks can be rerun without repeating the export step.

After the array finishes, merge_cluster_results reads the result files, reports missing chunk IDs, deduplicates flux vectors, and optionally maps solutions to the fundamental domain before comparison. If a model is supplied it can Newton-refine the merged candidates; if a database handle is supplied it can write the merged batch through the database integration hooks.

bounded_fluxes cluster execution — prepare, process, merge

Phase 1 — prepare on the head node

export_cluster_job

precompute ISD pipeline, serialise config, generate filtered $h$-chunks
pipeline.npz · config.json · worker.py · chunks/*.npy

↓

Phase 2 — process independent chunks

worker 0

process_chunk_from_disk(0)
ISD-complete and filter chunk 0

worker 1

process_chunk_from_disk(1)
same saved pipeline, different file

worker N

SLURM array or manual rerun
failed chunks are isolated

↓

Phase 3 — merge on the head node

merge_cluster_results

read results/result_*.npz, report missing chunk IDs, deduplicate fluxes, optionally map to FD, Newton-refine, and write database batches

Output: final deduplicated vacua list or catalogue, assembled without rerunning the export step.

Bounded fluxes class#

bounded_fluxes(model[, sampler, Nmax, ...])

Implements the flux-bounding algorithm of arXiv:2501.03984 for systematic enumeration of Type IIB flux vacua in finite regions of moduli space. Integrates with a model class (jaxvacua.flux_eft.FluxEFT) and optionally a sampler (jaxvacua.sampling.data_sampler).

Bounding box computation#

`bounded_fluxes.compute_bounding_box`(...[, ...])	Computes global eigenvalue bounds over a sample of moduli points and returns the bounding box dimensions for the NSNS-flux vector $h = (h_1, h_2)$.
`bounded_fluxes.get_h_box`()	Returns the cached bounding box dimensions `(h1_box, h2_box, h_box)` set by `compute_bounding_box()`.
`bounded_fluxes.compute_evs`(moduli)	Computes the eigenvalue quantities at a single moduli point.
`bounded_fluxes.compute_evs_vmap`(moduli_batch)	Batched version of `compute_evs()` via `vmap`.
`bounded_fluxes.update_global`()	Updates the global eigenvalue extrema from the current local values. Should be called after `update_evs()` or `update_local()`.
`bounded_fluxes.update_evs`(moduli)	Computes eigenvalues at moduli, sets the local eigenvalue attributes, and updates the global extrema via `update_global()`.
`bounded_fluxes.update_local`(moduli, tau, flux)	Updates the full local state — eigenvalues, axio-dilaton components, and flux norms — for a given point `(moduli, tau, flux)`. Also calls `update_global()`.

Flux enumeration#

`bounded_fluxes.enumerate_fluxes`([n_sample, ...])	Main flux enumeration algorithm (Algorithm 1 of arXiv:2501.03984).
`bounded_fluxes.sample_bounded_fluxes`([...])	Stochastic flux search guided by the eigenvalue bounds of arXiv:2501.03984.
`bounded_fluxes.get_h_candidates`([max_candidates])	Enumerates all integer NSNS-flux vectors $h = (h_1, h_2)$ inside the bounding box computed by `compute_bounding_box()`, pre-filtered by the $L^2$-norm constraints on $h_1$ and $h_2$ separately.

Cluster execution API#

`bounded_fluxes.export_cluster_job`(output_dir)	Export the flux search pipeline to disk for cluster-parallel execution.
`bounded_fluxes.process_chunk_from_disk`(...)	Process a single h-chunk from disk using a reconstructed pipeline. Designed to be called from a cluster worker script.
`bounded_fluxes.merge_cluster_results`(output_dir)	Merge results from all cluster workers, deduplicate, optionally Newton-refine, and optionally write to the vacua database.

Batch flux checking#

`bounded_fluxes.check_bounds_batch`(evs_batch, ...)	JIT-compiled, vmapped bound checking for a batch of flux candidates. Replaces the per-candidate Python loop over `update_local()` + `check_bounds_flat()` with a single vectorized JAX call.
`bounded_fluxes.compute_tadpole_batch`(flux_batch)	Batched tadpole computation via `vmap`.
`bounded_fluxes.newton_refine_batch`(...[, ...])	JIT-compiled, vmapped Newton refinement for a batch of flux candidates. Solves $D_I W = 0$ simultaneously for all `(moduli, tau, flux)` triples.
`bounded_fluxes.in_patch_batch`(moduli_batch, ...)	Vmapped patch-membership check.

Flux bounds#

`bounded_fluxes.bound_h1_local`()	Checks the local bound on $\\|h_1\\|^2$:
`bounded_fluxes.bound_h1_global`()	Checks the global bound on $\\|h_1\\|^2$:
`bounded_fluxes.bound_h2_local`()	Checks the local bound on $\\|h_2\\|^2$:
`bounded_fluxes.bound_h2_global`()	Checks the global bound on $\\|h_2\\|^2$:
`bounded_fluxes.bound_f1_local`()	Checks the four local bounds on the $f_1$ sector derived from the ISD condition (arXiv:2501.03984). Uses $\tilde f_1 = f_1 - c_0 h_1$ and $\tilde\mu_{\min/\max}$ — the extreme eigenvalues of $\operatorname{Im}(\mathcal{N}^{-1})$.
`bounded_fluxes.bound_f1_global`()	Checks the two global bounds on the $f_1$ sector using the global eigenvalue extrema $\tilde\mu_{\min/\max}^{\rm gl}$.
`bounded_fluxes.bound_f2_local`()	Checks the four local bounds on the $f_2$ sector derived from the ISD condition (arXiv:2501.03984). Uses $\tilde f_2 = f_2 - c_0 h_2$ and $\mu_{\min/\max}$ — the extreme eigenvalues of $-\operatorname{Im}(\mathcal{N})$.
`bounded_fluxes.bound_f2_global`()	Checks the two global bounds on the $f_2$ sector using the global eigenvalue extrema $\mu_{\min/\max}^{\rm gl}$.
`bounded_fluxes.bound_s_local`()	Checks the local bounds on $s = \operatorname{Im}(\tau)$:
`bounded_fluxes.bound_s_global`()	Checks the global bounds on $s$.
`bounded_fluxes.bound_h_local`()	Checks the local bound on $\\|h\\|^2$:
`bounded_fluxes.bound_h_global`()	Checks the global bound on $\\|h\\|^2$:
`bounded_fluxes.bound_f_local`()	Checks the local bounds on $\\|f\\|^2$:
`bounded_fluxes.bound_f_global`()	Checks the global bounds on $\\|f\\|^2$.

Flux utilities#

`bounded_fluxes.get_nflux`(flux)	Computes the D3-tadpole charge $N_{\rm flux}$ for a flux vector.
`bounded_fluxes.get_fh`(flux)	Splits the full flux vector into its RR- and NSNS-flux components.
`bounded_fluxes.get_flux_split`(flux_half)	Splits a half-flux vector `f` or `h` (length `n_fluxes`) into its two sub-sector components.
`bounded_fluxes.get_subvector`(flux)	Splits the full flux vector into all four sub-components $(h_1, h_2, f_1, f_2)$.
`bounded_fluxes.compute_norm`(v)	Computes the squared Euclidean norm $\\|v\\|^2 = v \cdot v$.
`bounded_fluxes.check_bounds`(moduli, tau, flux)	Checks all eigenvalue bounds for a given flux configuration.
`bounded_fluxes.check_bounds_flat`()	Evaluates all `bound_` methods using the current* local state (set by a prior `update_local()` call) and returns an aggregate pass/fail flag alongside the detailed results.

`bounded_fluxes.bound_h1_local`()	Checks the local bound on \(\\|h_1\\|^2\):
`bounded_fluxes.bound_h1_global`()	Checks the global bound on \(\\|h_1\\|^2\):
`bounded_fluxes.bound_h2_local`()	Checks the local bound on \(\\|h_2\\|^2\):
`bounded_fluxes.bound_h2_global`()	Checks the global bound on \(\\|h_2\\|^2\):
`bounded_fluxes.bound_f1_local`()	Checks the four local bounds on the \(f_1\) sector derived from the ISD condition (arXiv:2501.03984). Uses \(\tilde f_1 = f_1 - c_0 h_1\) and \(\tilde\mu_{\min/\max}\) — the extreme eigenvalues of \(\operatorname{Im}(\mathcal{N}^{-1})\).
`bounded_fluxes.bound_f1_global`()	Checks the two global bounds on the \(f_1\) sector using the global eigenvalue extrema \(\tilde\mu_{\min/\max}^{\rm gl}\).
`bounded_fluxes.bound_f2_local`()	Checks the four local bounds on the \(f_2\) sector derived from the ISD condition (arXiv:2501.03984). Uses \(\tilde f_2 = f_2 - c_0 h_2\) and \(\mu_{\min/\max}\) — the extreme eigenvalues of \(-\operatorname{Im}(\mathcal{N})\).
`bounded_fluxes.bound_f2_global`()	Checks the two global bounds on the \(f_2\) sector using the global eigenvalue extrema \(\mu_{\min/\max}^{\rm gl}\).
`bounded_fluxes.bound_s_local`()	Checks the local bounds on \(s = \operatorname{Im}(\tau)\):
`bounded_fluxes.bound_s_global`()	Checks the global bounds on \(s\).
`bounded_fluxes.bound_h_local`()	Checks the local bound on \(\\|h\\|^2\):
`bounded_fluxes.bound_h_global`()	Checks the global bound on \(\\|h\\|^2\):
`bounded_fluxes.bound_f_local`()	Checks the local bounds on \(\\|f\\|^2\):
`bounded_fluxes.bound_f_global`()	Checks the global bounds on \(\\|f\\|^2\).

`bounded_fluxes.get_nflux`(flux)	Computes the D3-tadpole charge \(N_{\rm flux}\) for a flux vector.
`bounded_fluxes.get_fh`(flux)	Splits the full flux vector into its RR- and NSNS-flux components.
`bounded_fluxes.get_flux_split`(flux_half)	Splits a half-flux vector `f` or `h` (length `n_fluxes`) into its two sub-sector components.
`bounded_fluxes.get_subvector`(flux)	Splits the full flux vector into all four sub-components \((h_1, h_2, f_1, f_2)\).
`bounded_fluxes.compute_norm`(v)	Computes the squared Euclidean norm \(\\|v\\|^2 = v \cdot v\).
`bounded_fluxes.check_bounds`(moduli, tau, flux)	Checks all eigenvalue bounds for a given flux configuration.
`bounded_fluxes.check_bounds_flat`()	Evaluates all `bound_` methods using the current* local state (set by a prior `update_local()` call) and returns an aggregate pass/fail flag alongside the detailed results.