jaxvacua.sampling

Random and structured sampling utilities for flux-vacuum searches.

Purpose

Define data_sampler and supporting parsers for generating flux vectors, axio-dilaton values and complex-structure moduli initial data used by FluxVacuaFinder and related workflows.

Main public API

• _parse_box_bounds and _parse_exclude_walls: normalise sampling bounds and wall-exclusion options with clear validation errors.

• data_sampler: samples integer fluxes, Kähler-cone-compatible moduli, axio-dilaton values, ISD/PFV-inspired seeds and batched initial conditions.

• JAX and NumPy random helpers integrated with PRNGSequence from jaxvacua.util.

Design notes

Sampling routines are performance-sensitive but user-facing. Bounds and shape handling are kept explicit so failed runs report input problems near the source rather than inside compiled search kernels.

When to use this module

Use data_sampler when a workflow needs reproducible batches of fluxes, axions, dilaton values, complex-structure moduli, or solver initial guesses. It is usually the preparation layer before calling jaxvacua.flux_vacua_finder.FluxVacuaFinder, but it is also useful on its own for probing cone geometry and checking how filtering cuts affect a sample.

Common workflow

1. Prepare cone-compatible real moduli with find_interior_points, sample_ray, sample_rays, sample_interior_point, and rescale_points.

2. Convert these real samples into moduli data with get_moduli and apply geometric or instanton-control cuts with filter_by_instantons, filter_by_km, filter_points, or filter_moduli.

3. Combine moduli with axion, dilaton, and flux batches from get_axions, get_axion, get_dilaton, get_complex_tau, and get_fluxes.

4. Build solver seeds with initial_guesses. Use ISD_sampling and initial_guesses_ISD when the search should start from ISD- or PFV-informed data.

Choosing an entry point

• get_moduli samples geometric moduli only.

• get_fluxes samples integral flux batches only.

• initial_guesses assembles general flux/moduli/tau starting points for numerical vacuum searches.

• initial_guesses_ISD assembles starting points from the specialised ISD sampling pipeline.

• filter_moduli post-processes existing moduli samples without drawing a new batch.

jaxvacua.sampling.data_sampler — seed-generation workflow

Inputs

model data

Kähler cone, rays, periods, ISD matrix
FluxEFT / FluxVacuaFinder

sampling bounds

moduli, axions, dilaton, flux box or radius
moduli_bounds, flux_bounds

random state

JAX / NumPy draw control
seed, PRNGSequence

↓

Geometry-aware sampling

moduli samples

cone / stretched-cone / ray / box modes
get_moduli, sample_ray, filter_moduli

axio-dilaton samples

axions and $s=\operatorname{Im}\tau$
get_axions, get_dilaton, get_complex_tau

↓

Two seed-generation routes

generic random seeds

draw full fluxes independently
get_fluxes → initial_guesses

ISD-informed seeds

draw half the flux data, solve the rest from ISD
ISD_sampling → initial_guesses_ISD

↓

ISD modes

ISD+

given $(f_2,h_2)$
solve $(f_1,h_1)$ via $\overline{\mathcal{N}}$

ISD-

given $(f_1,h_1)$
solve $(f_2,h_2)$ via $\overline{\mathcal{N}}^{-1}$

F

given RR flux $f$
solve NSNS flux $h$

H

given NSNS flux $h$
solve RR flux $f$

Output:  batched starting points $(z_0,\tau_0,\mathrm{flux}_0)$ for Newton refinement, bounded searches, or exploratory filtering.

Sampling class

data_sampler(model[, flux_bounds, ...])

Moduli sampling

data_sampler.get_axion(num_pts[, rns_key, ...])	Generates random samples of axion values within specified bounds using a selected sampling mode.
data_sampler.get_axions(num_pts[, rns_key, ...])	Generates random samples of axion values within specified bounds using the selected sampling mode.
data_sampler.get_complex_moduli(N[, ...])	Generates complex samples for moduli, combining axion and moduli values.
data_sampler.get_complex_tau(N[, rns_key, ...])	Generates complex samples for tau, which is a combination of axion and dilaton values.
data_sampler.get_dilaton(num_pts[, rns_key, ...])	Generates random samples of dilaton values within specified bounds using the selected sampling mode.
data_sampler.get_moduli(num_pts[, rns_key, ...])	Samples moduli values within specified bounds using the selected sampling mode.
data_sampler.sample_sphere(num_pts[, dim, ...])	Samples points uniformly from the surface of a sphere or within a spherical volume.
data_sampler.sample_ray([rns_key])	Samples a random ray from the Kähler cone.
data_sampler.sample_rays(k[, rns_key])	Samples k random rays from the Kähler cone.
data_sampler.sample_interior_point([rns_key])	Samples a random interior point of the Kähler cone.
data_sampler.find_interior_points([N, ...])	Finds interior points of the Kähler cone using integer programming.
data_sampler.filter_points(x[, filter, ...])	Filters points to ensure they lie within the Kähler cone and applies an optional custom filter.
data_sampler.filter_moduli(moduli, tau[, ...])	Filters starting points for moduli based on both instanton contributions and Kähler metric positivity.
data_sampler.rescale_points(pts[, norm, ...])	Rescales points to ensure they lie within a specified norm bound.

Flux sampling

data_sampler.get_fluxes(num_pts[, mode, ...])	Returns a random sample of flux choices used for ISD biased sampling.
data_sampler.ISD_sampling(moduli, moduli_c, ...)	Determines half of the flux numbers such that the ISD condition \(\star G_3 = \text{i}G_3\) is satisfied for given input values for the moduli \(z^i\) and the axio-dilaton \(\tau\).

Initial guesses

data_sampler.initial_guesses(N[, rns_key, ...])	Generates initial guesses for moduli, dilaton, and optionally fluxes for sampling in moduli space.
data_sampler.initial_guesses_ISD(N[, ...])	Generates initial guesses for moduli, dilaton, and fluxes using ISD (Imaginary Self-Dual) sampling.