jaxvacua.sampling.data_sampler

jaxvacua.sampling.data_sampler#

class data_sampler(model, flux_bounds=(-10, 10), axion_bounds=(-0.5, 0.5), dilaton_bounds=(2.0, 10.0), moduli_bounds=(1.0, 5.0), stretching=0.0, exclude_walls=None, cone_cutoff=None, use_jax=False, seed=42)#

Bases: object

__init__(model, flux_bounds=(-10, 10), axion_bounds=(-0.5, 0.5), dilaton_bounds=(2.0, 10.0), moduli_bounds=(1.0, 5.0), stretching=0.0, exclude_walls=None, cone_cutoff=None, use_jax=False, seed=42)#

A class to sample initial data for the construction of flux vacua.

Parameters:

  • self.model (jaxvacua.flux_eft.FluxEFT) – Model class for flux compactifications.

  • flux_bounds (Tuple[float, float]) – Bounds for fluxes.

  • axion_bounds (Tuple[float, float]) – Bounds for axions.

  • dilaton_bounds (Tuple[float, float]) – Bounds for dilaton.

  • moduli_bounds (Any) –

    Per-direction box bounds on \(\operatorname{Im}(z_i)\). Accepted forms:

    • Scalar pair (lo, hi) or [lo, hi] — broadcast to all \(h^{1,2}\) directions.

    • (lower_vec, upper_vec) with each element a length-\(h^{1,2}\) sequence — per-direction bounds.

    Example: moduli_bounds=([1., 2.], [3., 5.]) at \(h^{1,2}=2\) gives \(\operatorname{Im}(z_1) \in [1,3]\), \(\operatorname{Im}(z_2) \in [2,5]\). Defaults to (1., 5.).

  • stretching (float) – Distance from each Kähler-cone hyperplane used by cone-mode sampling; points with \((H_k \cdot \operatorname{Im}(z)) < \texttt{stretching}\) are rejected, except for walls listed in exclude_walls. Defaults to 0.0.

  • exclude_walls (Any) – Optional sequence identifying hyperplanes to exempt from the stretching threshold. Accepts a list of integer indices into lcs_tree.hyperplanes, a list of explicit hyperplane-row vectors (matched against that array), or None (no exemption). Excluded walls get a soft check (H_k \cdot Im(z)) > 0 — points arbitrarily close to those walls are allowed (useful for coniLCS limits).

  • cone_cutoff (Any) – Scalar upper cap on the \(L^2\) norm of sampled moduli points in cone / ray modes. None (default) auto- resolves to float(max(moduli_upper)) — preserving the legacy behaviour of using the scalar moduli_bounds[1].

  • use_jax (bool) – Use JAX environment for random number generation.

  • seed (int) – Seed for the internal PRNG used when rns_key is not passed explicitly to sampling methods. Defaults to 42.

axion_lower#

Lower bound universal axion.

Type:

float

axion_upper#

Upper bound universal axion.

Type:

float

axions_lower#

Lower bound complex structure axions.

Type:

float

axions_upper#

Upper bound complex structure axions.

Type:

float

flux_lower#

Lower bound fluxes.

Type:

int

flux_upper#

Upper bound fluxes.

Type:

int

moduli_lower#

Per-direction lower bounds on \(\operatorname{Im}(z_i)\), shape (h12,).

Type:

jnp.ndarray

moduli_upper#

Per-direction upper bounds on \(\operatorname{Im}(z_i)\), shape (h12,).

Type:

jnp.ndarray

stretching#

Stored hyperplane-distance threshold.

Type:

float

exclude_walls#

Boolean mask of shape (n_hyperplanes,); True entries are exempt from the stretching threshold.

Type:

jnp.ndarray

cone_cutoff#

Resolved cone L² cap.

Type:

float

s_lower#

Lower bound dilaton.

Type:

float

s_upper#

Lower bound dilaton.

Type:

float

_n_fluxes#

Number of fluxes.

Type:

int

_generators_kahler_cone#

Generators Kähler cone.

Type:

Array

_h12#

Number of complex structure moduli.

Type:

float

_rays_kahler_cone#

Rays Kähler cone.

Type:

Array

_tip_ray#

Tip of c=1 stretched Kähler cone.

Type:

Array

_F_inst#

Instanton prepotential.

Type:

callable

_prepot#

Prepotential.

Type:

callable

_tadpole#

D3-tadpole contribution of fluxes.

Type:

callable

_rng#

Internal PRNG sequence used as default key source.

Type:

PRNGSequence

Methods

ISD_sampling(moduli, moduli_c, tau, tau_c, flux0)

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\).

__init__(model[, flux_bounds, axion_bounds, ...])

A class to sample initial data for the construction of flux vacua.

filter_by_instantons(moduli[, inst_cutoff])

Filters starting points based on their instanton contributions to ensure they are sufficiently small.

filter_by_km(moduli, tau)

Filters starting points based on their Kähler metric to ensure they are positive definite.

filter_moduli(moduli, tau[, inst_cutoff])

Filters starting points for moduli based on both instanton contributions and Kähler metric positivity.

filter_points(x[, filter, stretching, ...])

Filters points to ensure they lie within the Kähler cone and applies an optional custom filter.

find_interior_points([N, stretching, ...])

Finds interior points of the Kähler cone using integer programming.

get_axion(num_pts[, rns_key, minval, ...])

Generates random samples of axion values within specified bounds using a selected sampling mode.

get_axions(num_pts[, rns_key, minval, ...])

Generates random samples of axion values within specified bounds using the selected sampling mode.

get_complex_moduli(N[, rns_key, ...])

Generates complex samples for moduli, combining axion and moduli values.

get_complex_tau(N[, rns_key, minval_axion, ...])

Generates complex samples for tau, which is a combination of axion and dilaton values.

get_dilaton(num_pts[, rns_key, minval, ...])

Generates random samples of dilaton values within specified bounds using the selected sampling mode.

get_fluxes(num_pts[, mode, rns_key, minval, ...])

Returns a random sample of flux choices used for ISD biased sampling.

get_moduli(num_pts[, rns_key, minval, ...])

Samples moduli values within specified bounds using the selected sampling mode.

initial_guesses(N[, rns_key, ...])

Generates initial guesses for moduli, dilaton, and optionally fluxes for sampling in moduli space.

initial_guesses_ISD(N[, rns_key, ...])

Generates initial guesses for moduli, dilaton, and fluxes using ISD (Imaginary Self-Dual) sampling.

rescale_points(pts[, norm, maxval, rns_key])

Rescales points to ensure they lie within a specified norm bound.

sample_interior_point([rns_key])

Samples a random interior point of the Kähler cone.

sample_ray([rns_key])

Samples a random ray from the Kähler cone.

sample_rays(k[, rns_key])

Samples k random rays from the Kähler cone.

sample_sphere(num_pts[, dim, rns_key, ...])

Samples points uniformly from the surface of a sphere or within a spherical volume.

update_interior_points(num_pts[, rns_key, ...])

Updates the interior points used for sampling in the Kähler cone.
ISD_sampling(moduli, moduli_c, tau, tau_c, flux0, mode='ISD+', output='full', return_integer_flux=False, in_axes=(0, 0, 0), vmap=False)#

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\).

Details

This function implements ISD sampling as described in <>. The basic idea is to fix points in moduli space together with a subset of flux quanta, and fix the remaining fluxes through the ISD condition.

There are four modi to solve the ISD condition for a given choices of half of the fluxes. Either we use the following form of the ISD condition (see ISD_condition())

\[f_1-\tau h_1=\overline{\mathcal{N}}(z^i,\overline{z}^i)\, (f_2-\tau h_2)\, .\]

This expression can be solved for fluxes \((f_1,h_1)\) (corresponding to mode="ISD+") or \((f_2,h_2)\) (associated to mode="ISD-") corresponding to the components of the RR-flux vector \(f=(f_1,f_2)\) and the NSNS-flux vector \(h=(h_1,h_2)\) for given input values for the moduli \(z^i\) and the axio-dilaton \(\tau\). The other two modi are obtained by rewriting the above expression in the following form

\[f=(s \, M(z^i,\overline{z}^i)\Sigma + c_0)\, h\; ,\quad \tau=c_0 + \text{i} s \, .\]

This can then be solved for RR-flux vector \(f=(f_1,f_2)\) (mode="F") or the NSNS-flux vector \(h=(h_1,h_2)\) (mode="H")

In general, the fluxes constructed in this way are non-integer. Upon rounding the fluxes to integers, the ISD condition is approximately satisfied: \(\star G_3 \approx \text{i}G_3\) for given inputs.

Cached vmapped kernel

When vmap=True, this method delegates to vmapping_func_cached() rather than constructing a new jax.jit(jax.vmap(...)) closure on each call. vmapping_func_cached() stores the compiled XLA kernel in an LRU cache keyed on (func, in_axes, frozen_kwargs). Subsequent calls with the same arguments retrieve the pre-compiled kernel directly, avoiding recompilation overhead — particularly important when this method is called repeatedly inside the while loop of initial_guesses_ISD().

Parameters:

  • moduli (Array) – Complex structure moduli values with shape (h12,) or (N, h12) if vmapped.

  • moduli_c (Array) – Complex conjugate of moduli, same shape as moduli.

  • tau (Array) – Axio-dilaton value; scalar or shape (N,) if vmapped.

  • tau_c (Array) – Complex conjugate of tau, same shape as tau.

  • flux0 (Array) – Input flux array with shape (n_fluxes,) or (N, n_fluxes) if vmapped.

  • mode (str) – ISD sampling mode. One of "ISD+", "ISD-", "F", "H". Defaults to "ISD+".

  • output (str) – Output format — "full" for the complete flux vector, "half" for only the ISD-fixed half. Defaults to "full".

  • return_integer_flux (bool) – Round fluxes to nearest integers. Defaults to False.

  • in_axes (Tuple[int, int, int]) – Batch axes for vmap in the order (moduli_axis, tau_axis, flux_axis). Defaults to (0, 0, 0).

  • vmap (bool) – Vectorise over the batch dimension. Defaults to False.

Returns:

Array – Sampled flux array. Shape (4*(h12+1),) or (2*(h12+1),) depending on output; (N, flux_dim) when vmapped.

Raises:

ValueError – If mode or output are not among the recognised values.

Return type:

Array

See also: ISD_condition(), vmapping_func_cached(),

initial_guesses_ISD(), _ISD_sampling_PM(), _ISD_sampling_FH()

filter_by_instantons(moduli, inst_cutoff=0.1)#

Filters starting points based on their instanton contributions to ensure they are sufficiently small.

Parameters:

  • moduli (Array) – Array containing starting points for moduli.

  • inst_cutoff (float) – Cutoff on the ratio of instanton to perturbative contributions to the pre-potential. Default is 1e-1.

Returns:

Array – Array containing starting points with sufficiently small instanton contributions.

Return type:

Array

filter_by_km(moduli, tau)#

Filters starting points based on their Kähler metric to ensure they are positive definite.

Parameters:

  • moduli (Array) – Array containing starting points for moduli.

  • tau (Array) – Array containing starting points for the axio-dilaton.

Returns:

Array – Array containing starting points with positive definite Kähler metric.

Return type:

Array

filter_moduli(moduli, tau, inst_cutoff=0.1)#

Filters starting points for moduli based on both instanton contributions and Kähler metric positivity.

Parameters:

  • moduli (Array) – Array containing starting points for moduli.

  • tau (Array) – Array containing starting points for the axio-dilaton.

  • inst_cutoff (float) – Cutoff on the ratio of instanton to perturbative contributions to the pre-potential. Default is 1e-1.

Returns:

Array – Array containing starting points for moduli that satisfy both instanton and Kähler metric criteria.

Return type:

Array

filter_points(x, filter=None, stretching=0.0, exclude_walls=None)#

Filters points to ensure they lie within the Kähler cone and applies an optional custom filter.

For each hyperplane row \(H_k\), a point \(x\) is kept when \((H_k \cdot x) \geq \texttt{threshold}_k\). The threshold is stretching for all walls except those flagged by exclude_walls, which use threshold 0 — i.e. bare cone membership. This lets users sample arbitrarily close to one specific wall (e.g. the conifold wall in coniLCS limits) while keeping a non-zero distance from all others.

Parameters:

  • x (ndarray) – Points to be filtered.

  • filter (Optional[Callable]) – Custom filter function. Defaults to None.

  • stretching (float) – Distance from each Kähler-cone wall for non-excluded walls. Default is 0.

  • exclude_walls (Any) – Optional per-wall exemption mask. When None, defaults to self.exclude_walls (set at construction time). Accepts the same forms as the constructor kwarg: boolean mask, list of ints, or list of hyperplane row vectors.

Returns:

np.ndarray or Array – Filtered points.

Return type:

ndarray | Array

find_interior_points(N=1, stretching=0.1, normalise=False, verbosity=0)#

Finds interior points of the Kähler cone using integer programming.

Parameters:

  • N (int) – Number of interior points to find. Default is 1.

  • stretching (float) – Stretching parameter for the Kähler cone. Default is 0.1.

  • normalise (bool) – Whether to normalise the points to L2-norm = 1. Default is False.

  • verbosity (int) – Verbosity level for logging. Default is 0.

Returns:

np.ndarray or Array – Array of interior points.

Raises:

RuntimeError – If the optimization fails.

Return type:

ndarray | Array

get_axion(num_pts, rns_key=None, minval=None, maxval=None, sampling_mode='box')#

Generates random samples of axion values within specified bounds using a selected sampling mode.

Parameters:

  • num_pts (int) – Number of points to sample.

  • rns_key (Any | None) – Random number seed key used for reproducibility. Default is None.

  • minval (float) – Minimum value for axion sampling. If None, defaults to self.axion_lower.

  • maxval (float) – Maximum value for axion sampling. If None, defaults to self.axion_upper.

  • sampling_mode (str) – Mode of sampling, either “box” or “sphere”. Default is “box”.

Returns:

np.ndarray or Array – Array of sampled axion values.

Raises:

ValueError – If sampling_mode is not one of the supported modes (“box” or “sphere”).

Return type:

ndarray | Array

get_axions(num_pts, rns_key=None, minval=None, maxval=None, sampling_mode='box')#

Generates random samples of axion values within specified bounds using the selected sampling mode.

Parameters:

  • num_pts (int) – Number of points to sample.

  • rns_key (Any | None) – Random number seed key used for reproducibility. Default is None.

  • minval (float) – Minimum value for axion sampling. If None, defaults to self.axions_lower.

  • maxval (float) – Maximum value for axion sampling. If None, defaults to self.axions_upper.

  • sampling_mode (str) – Mode of sampling, either “box” or “sphere”. Default is “box”.

Returns:

np.ndarray or Array – Array of sampled axion values with shape (num_pts, self._h12).

Raises:

ValueError – If sampling_mode is not one of the supported modes (“box” or “sphere”).

Return type:

ndarray | Array

get_complex_moduli(N, rns_key=None, minval_axions=None, maxval_axions=None, minval_moduli=None, maxval_moduli=None, axion_sampling_mode='box', moduli_sampling_mode='cone')#

Generates complex samples for moduli, combining axion and moduli values.

Parameters:

  • N (int) – Number of complex moduli values to generate.

  • rns_key (Any | None) – Random number seed key used for reproducibility. Default is None.

  • minval_axions (float) – Minimum value for axion part of the moduli. Default is None.

  • maxval_axions (float) – Maximum value for axion part of the moduli. Default is None.

  • minval_moduli (Any) – Minimum value for the imaginary part of the moduli. Scalar or length-h12 sequence (per-direction). None (default) → falls back to the sampler’s moduli_lower (box mode) or 0 (cone / ray modes).

  • maxval_moduli (Any) – Maximum value for the imaginary part of the moduli. Scalar or length-h12 sequence. None (default) → falls back to moduli_upper (box mode) or cone_cutoff (cone / ray modes).

  • axion_sampling_mode (str) – Sampling mode for axion values. Default is “box”.

  • moduli_sampling_mode (str) – Sampling mode for moduli values. Default is “box”.

Returns:

np.ndarray or Array – Array of complex moduli values.

Return type:

ndarray | Array

get_complex_tau(N, rns_key=None, minval_axion=None, maxval_axion=None, minval_dilaton=None, maxval_dilaton=None, axion_sampling_mode='box', dilaton_sampling_mode='box')#

Generates complex samples for tau, which is a combination of axion and dilaton values.

Parameters:

  • N (int) – Number of complex tau values to generate.

  • rns_key (Any | None) – Random number seed key used for reproducibility. Default is None.

  • minval_axion (float) – Minimum value for axion part of tau. Default is None.

  • maxval_axion (float) – Maximum value for axion part of tau. Default is None.

  • minval_dilaton (float) – Minimum value for dilaton part of tau. Default is None.

  • maxval_dilaton (float) – Maximum value for dilaton part of tau. Default is None.

  • axion_sampling_mode (str) – Sampling mode for axion. Default is “box”.

  • dilaton_sampling_mode (str) – Sampling mode for dilaton. Default is “box”.

Returns:

np.ndarray or Array – Array of complex tau values.

Return type:

ndarray | Array

get_dilaton(num_pts, rns_key=None, minval=None, maxval=None, sampling_mode='box')#

Generates random samples of dilaton values within specified bounds using the selected sampling mode.

Parameters:

  • num_pts (int) – Number of points to sample.

  • rns_key (Any | None) – Random number seed key used for reproducibility. Default is None.

  • minval (float) – Minimum value for dilaton sampling. If None, defaults to self.s_lower.

  • maxval (float) – Maximum value for dilaton sampling. If None, defaults to self.s_upper.

  • sampling_mode (str) – Mode of sampling, either “box” or “sphere”. Default is “box”.

Returns:

np.ndarray or Array – Array of sampled dilaton values.

Raises:

ValueError – If sampling_mode is not one of the supported modes (“box” or “sphere”).

Return type:

ndarray | Array

get_fluxes(num_pts, mode='full', rns_key=None, minval=None, maxval=None, sampling_mode='box', radius=10.0)#

Returns a random sample of flux choices used for ISD biased sampling.

Note

Note that, even though this function is not jit-compiled, it is faster than the equivalent function using jax.random.randint (at least for more than 100 fluxes)!

Parameters:

  • num_pts (int) – Number of points to sample.

  • mode (str) – Mode of sampling (“full”, “half”, or None). Default is “full”.

  • rns_key (Any | None) – PRNG random key. Defaults to None.

  • minval (int | None) – Minimum value for flux sampling. Default is None.

  • maxval (int | None) – Maximum value for flux sampling. Default is None.

  • sampling_mode (str) – Mode of sampling (“box”, “sphere”, “tadpole_bound”, “tadpole_cancel”). Default is “box”.

  • radius (float) – Radius constraint for certain sampling modes. Default is 10.0.

Returns:

ArrayLike – Array of sampled fluxes.

Raises:

ValueError – If sampling_mode or mode is not recognized.

Return type:

Array

get_moduli(num_pts, rns_key=None, minval=None, maxval=None, sampling_mode='cone', stretching=0.0, filter=None, n_rays=2, perturbation=0.1, use_rays=False, time_out=60.0, verbosity=0)#

Samples moduli values within specified bounds using the selected sampling mode.

The minval / maxval kwargs carry different meanings depending on sampling_mode:

  • "box" — per-direction bounds on Im(z_i). Accepts scalars (broadcast to all directions) or length-h12 sequences. Default None → falls back to moduli_lower / moduli_upper.

  • "cone" / "stretched_cone" / "random_rays" — scalar bounds on the ray-coefficient used to build a positive combination of the cone generators. Default None → 0.0 / cone_cutoff.

  • "tip_ray" / "random_ray" — scalar range for the single-ray coefficient. Default None → 0.0 / cone_cutoff.

When stretching is positive and / or the sampler has any exclude_walls flagged, a rejection-sampling loop is used to enforce the per-wall distance constraints. The fast path (one-shot matmul, no filtering) is taken only for stretching == 0 with no excluded walls.

Parameters:

  • num_pts (int) – Number of points to sample.

  • rns_key (Any | None) – PRNG random key for reproducibility. Defaults to None.

  • minval (Any) – Minimum value for sampling. See per-mode notes above. Default None.

  • maxval (Any) – Maximum value for sampling. See per-mode notes above. Default None.

  • sampling_mode (str) – Mode of sampling ("box", "sphere", "cone", "stretched_cone", "tip_ray", "random_ray", "random_rays"). Default "cone".

  • stretching (float) – Distance from each Kähler-cone hyperplane used by cone modes. Default 0 (bare cone membership only). Method argument; if left at 0 while stretching on the sampler is non-zero, the sampler attribute is used instead.

  • n_rays (int) – Number of rays to use if use_rays is True. Default is 2.

  • perturbation (float) – Perturbation applied to interior points. Default is 1e-1.

  • use_rays (bool) – Whether to use rays for sampling. Default is False.

  • time_out (float) – Time-out duration in seconds (raised if the rejection loop cannot meet the target count). Default is 60.

  • verbosity (int) – Verbosity level for logging. Default is 0.

Returns:

  • np.ndarray or Array – Array of sampled moduli, shape

  • `` (num_pts, h12)

Raises:

  • ValueError – If sampling_mode is not recognized or required data is missing.

  • RuntimeError – If the rejection-sampling loop times out (reduce stretching or loosen exclude_walls).

Return type:

ndarray | Array

initial_guesses(N, rns_key=None, minval_dilaton=None, maxval_dilaton=None, minval_axions=None, maxval_axions=None, minval_moduli=None, maxval_moduli=None, moduli_sampling_mode='cone', minval_fluxes=None, maxval_fluxes=None, fluxes_sampling_mode='box', flux_mode='full', flux_radius=10.0, filter_moduli=False, include_fluxes=True)#

Generates initial guesses for moduli, dilaton, and optionally fluxes for sampling in moduli space.

Note

This function generates initial guesses for the complex structure moduli, dilaton, and fluxes for a given number of samples, N. The function utilizes random sampling within specified bounds and modes for dilaton, axions, moduli, and fluxes. If filter_moduli is set to True, the generated moduli are filtered based on instanton effects. If include_fluxes is set to True, fluxes are also generated and returned.

Warning

For \(h^{1,2}>15\), we may not have the generators of the Kähler cone available. In this case, we use the rays to sample points in the Kähler cone. Generically, this could lead to a strong sampling bias in the starting points because we sample more points in the regions of highest density of rays.

Parameters:

  • N (int) – The number of initial points to generate.

  • rns_key (Any | None) – Random number seed key used for reproducibility. Default is None.

  • minval_dilaton (float | None) – Minimum value for dilaton sampling. Default is None.

  • maxval_dilaton (float | None) – Maximum value for dilaton sampling. Default is None.

  • minval_axions (float | None) – Minimum value for axion sampling. Default is None.

  • maxval_axions (float | None) – Maximum value for axion sampling. Default is None.

  • minval_moduli (Any) – Minimum value for moduli sampling. Scalar or length-h12 sequence (per-direction, only used by moduli_sampling_mode="box"). Default None → routes to the sampler’s moduli_lower (box mode) or 0.0 (cone / ray modes).

  • maxval_moduli (Any) – Maximum value for moduli sampling. Scalar or length-h12 sequence. Default None → moduli_upper (box mode) or cone_cutoff (cone / ray modes).

  • moduli_sampling_mode (str) – Sampling mode for moduli (“box”, “cone”, “stretched_cone”, etc.). Default is “box”.

  • minval_fluxes (float | None) – Minimum value for flux sampling. Default is None.

  • maxval_fluxes (float | None) – Maximum value for flux sampling. Default is None.

  • fluxes_sampling_mode (str) – Sampling mode for fluxes (“box”, “sphere”, “tadpole_bound”, “tadpole_cancel”). Default is “box”.

  • flux_mode (str) – Mode for flux generation (“full” or “half”). Default is “full”.

  • flux_radius (float) – Radius constraint for certain flux sampling modes. Default is 10.0.

  • filter_moduli (bool) – Whether to filter moduli based on instanton contributions. Default is False.

  • include_fluxes (bool) – Whether to include fluxes in the output. Default is True.

Returns:

Tuple[Array, Array] | Tuple[Array, Array, Array] – If include_fluxes is True, returns (moduli, tau, fluxes) where moduli has shape (N, h12), tau has shape (N,), and fluxes has shape (N, 2*n_fluxes). If include_fluxes is False, returns (moduli, tau).

Return type:

Union[Tuple[Array, Array], Tuple[Array, Array, Array]]

initial_guesses_ISD(N, rns_key=None, minval_dilaton=None, maxval_dilaton=None, minval_axions=None, maxval_axions=None, minval_moduli=None, maxval_moduli=None, moduli_sampling_mode='cone', minval_fluxes=None, maxval_fluxes=None, fluxes_sampling_mode='box', flux_mode='full', Nmax=None, filter_moduli=False, mode='ISD+', vmap_dim=None, ISD_oversample_factor=10, print_progress=False)#

Generates initial guesses for moduli, dilaton, and fluxes using ISD (Imaginary Self-Dual) sampling.

Note

This function generates initial guesses for the complex structure moduli, dilaton, and fluxes for a given number of samples, N using ISD sampling. The function utilizes random sampling within specified bounds and modes for dilaton, axions, moduli, and fluxes. ISD sampling enforces the condition \(\star G_3 = \text{i}G_3\) by fixing half of the flux quanta and deriving the remaining fluxes. If filter_moduli is set to True, the generated moduli are filtered based on instanton effects.

Warning

For \(h^{1,2}>15\), we may not have the generators of the Kähler cone available. In this case, we use the rays to sample points in the Kähler cone. Generically, this could lead to a strong sampling bias in the starting points because we sample more points in the regions of highest density of rays. To account for this, we assign a weight to each ray given by the inverse of the number of non-zero entries.

Warning

The fluxes generated via ISD sampling are generally non-integer. They are rounded to integers, so the ISD condition is only approximately satisfied: \(\star G_3 \approx \text{i}G_3\).

Implementation notes

(a) Cached vmapped kernel via vmapping_func_cached() . The vmapped+jitted ISD kernel is built once before the loop using vmapping_func_cached(), which stores the compiled XLA kernel in an LRU cache keyed on (func, in_axes, frozen_kwargs). Subsequent iterations retrieve the cached callable directly, avoiding recompilation overhead on every loop iteration.

(b) O(N) list accumulation with jnp.concatenate . Filtered batch arrays are accumulated in Python lists and concatenated exactly once after the loop via jnp.concatenate, reducing total memory allocation to O(N) rather than the O(N²) behaviour of repeated jnp.append / np.append calls.

(c) Plain Python counter for async dispatch. The collected-sample count is tracked with a plain Python int rather than evaluating len on a growing JAX array, which would force a device synchronisation on every iteration and stall JAX’s asynchronous dispatch pipeline.

Parameters:

  • N (int) – Number of initial points to generate.

  • rns_key (Any | None) – Random number seed key. Default is None.

  • minval_dilaton (float | None) – Lower bound for dilaton. Default None.

  • maxval_dilaton (float | None) – Upper bound for dilaton. Default None.

  • minval_axions (float | None) – Lower bound for axions. Default None.

  • maxval_axions (float | None) – Upper bound for axions. Default None.

  • minval_moduli (Any) – Lower bound for moduli. Default None.

  • maxval_moduli (Any) – Upper bound for moduli. Default None.

  • moduli_sampling_mode (str) – Sampling mode for moduli. Default "box".

  • minval_fluxes (float | None) – Lower bound for flux sampling. Default None.

  • maxval_fluxes (float | None) – Upper bound for flux sampling. Default None.

  • fluxes_sampling_mode (str) – Sampling mode for fluxes. Default "box".

  • flux_mode (str) – Flux generation mode ("full" or "half"). Default "full".

  • Nmax (float | None) – Maximum D3-tadpole. If None, uses the model’s D3_tadpole value. Default None.

  • filter_moduli (bool) – Filter moduli by instanton effects. Default False.

  • mode (str) – ISD mode — "ISD+", "ISD-", "F", or "H". Default "ISD+".

  • vmap_dim (int | None) – Batch size for vmapped operations. Defaults to N.

  • ISD_oversample_factor (int) – When use_jax=True, process vmap_dim * ISD_oversample_factor points per outer iteration. More points per iteration → fewer iterations → fewer device syncs. Ignored when use_jax=False. Default 10.

  • print_progress (bool) – Print a running sample count. Default False.

Returns:

Tuple[Array, Array, Array] – (moduli, tau, fluxes) where moduli has shape (N, h12), tau has shape (N,), and fluxes has shape (N, 2*n_fluxes) with integer fluxes satisfying the ISD condition (approximately, after rounding).

Raises:

KeyboardInterrupt – Returns partial results if interrupted.

Return type:

Tuple[Array, Array, Array]

See also: ISD_sampling(), vmapping_func_cached(),

initial_guesses()

rescale_points(pts, norm='l2', maxval=None, rns_key=None)#

Rescales points to ensure they lie within a specified norm bound.

When maxval is None (default), the cap is read from cone_cutoff — the dedicated scalar cone cut-off set at construction time. This is the one knob that decouples cone sampling from the per-direction box bounds (moduli_lower / moduli_upper); before the direction- aware refactor both concepts shared a single scalar upper bound, which led to confusing semantics when per-direction bounds were introduced.

Parameters:

  • pts (np.ndarray) – Points to be rescaled.

  • norm (str, optional) – Norm type for rescaling (“l2”, “l1”, or “inf”). Default is “l2”.

  • maxval (float, optional) – Maximum value for the norm. None (default) → uses cone_cutoff. Pass a scalar to override for a single call.

  • rns_key (Any | None) – PRNG random key for reproducibility. Default is None.

Returns:

np.ndarray or Array – Rescaled points.

Raises:

ValueError – If norm is not one of the supported types.

sample_interior_point(rns_key=None)#

Samples a random interior point of the Kähler cone.

Returns:

np.ndarray or Array – A random interior point of the Kähler cone.

sample_ray(rns_key=None)#

Samples a random ray from the Kähler cone.

Returns:

np.ndarray or Array – A random ray from the Kähler cone.

sample_rays(k, rns_key=None)#

Samples k random rays from the Kähler cone.

Parameters:

k (int) – Number of rays to sample.

Returns:

np.ndarray or Array – Array of sampled rays.

Raises:

  • RuntimeError – If ray data is not available.

  • ValueError – If k is larger than the number of available rays.

sample_sphere(num_pts, dim=1, rns_key=None, angles=(0.0, 6.283185307179586), radius=1.0)#

Samples points uniformly from the surface of a sphere or within a spherical volume.

Parameters:

  • num_pts (int) – Number of points to sample.

  • dim (int) – Dimension of the sphere (1 for circle, 2 for sphere, etc.). Default is 1.

  • rns_key (Any | None) – Random number seed key used for reproducibility. Default is None.

  • angles (Tuple[float, float]) – Range of angles for sampling. Default is (0., 2.*pi).

  • radius (float) – Radius of the sphere for sampling points. Default is 1.

Returns:

np.ndarray or Array – Array of sampled complex values representing points on the sphere.

Return type:

ndarray | Array

update_interior_points(num_pts, rns_key=None, maxval=None, stretching=0.0, perturbation=0.1, time_out=60.0, verbosity=0)#

Updates the interior points used for sampling in the Kähler cone.

Parameters:

  • num_pts (int) – Number of interior points to sample.

  • rns_key (Any | None) – PRNG random key. Defaults to None.

  • maxval (float | None) – Maximum value for rescaling points. Default is None.

  • stretching (float) – Stretching parameter for the Kähler cone. Default is 0.

  • perturbation (float) – Perturbation applied to interior points. Default is 1e-1.

  • time_out (float) – Time-out duration in seconds. Default is 60.

  • verbosity (int) – Verbosity level for logging. Default is 0.

Raises:

RuntimeError – If sampling points in the cone fails within the time-out duration.

Returns:

None

Return type:

None