quadrature_nd

quadrature_nd(
    f,
    min,
    max,
    method='monte_carlo',
    seed=None,
    use_sobol=True,
    max_function_evaluations=None,
    min_iterations=None,
    max_iterations=None,
    relative_tolerance=None,
    fraction=None,
    min_subregion_points=None,
    min_bisections=None,
    dither=None,
    independent_evaluations=None,
    function_calls=None,
    alpha=None,
    number_of_bins=None,
    tail_focus_parameter=None,
    initialize=None,
    check_convergence=None,
    target_probability=None,
)

Integrate a user-written function over a multidimensional box.

Computes the definite integral of f over the hyper-rectangle [min, max] (P2 “math extras”) with one of three ported stochastic multidimensional integrators: plain Monte Carlo (method="monte_carlo", the default), Miser (recursive stratified-sampling Monte Carlo, Press et al. “Numerical Recipes” Sec. 7.9), or Vegas (Lepage’s adaptive importance sampling, Sec. 7.8, with an optional Power Transform for rare tail-event sampling). min/max give both the per-dimension bounds and, via their length, the number of dimensions.

method="vegas" takes f(x, weight) – x the sample point and weight the importance weight Vegas has already computed for it – rather than f(x), matching the upstream C# Vegas constructor’s own integrand shape; a weight-ignoring wrapper (lambda x, w: g(x)) reproduces an f(x)-only integrand under Vegas, exactly as the upstream unit tests wrap theirs.

The SAMPLE STREAM – which points f is called at – reproduces bit-for-bit against the same run in corehydror, EXCEPT that seed has no effect on method="monte_carlo" or a Sobol-sampled run of "miser"/"vegas" (the default, use_sobol=True): Miser and Vegas draw their sample points from a Sobol low-discrepancy sequence rather than the Mersenne Twister seed seeds, and MonteCarloIntegration‘s own UseSobolSequence flag is a documented DEAD property upstream – declared but never consulted by Integrate() – so a "monte_carlo" run always draws from the generator seed seeds. use_sobol=False reroutes Miser/Vegas through that same seeded generator instead. AN HONEST LIMIT, measured rather than assumed: the AGGREGATED numbers this function returns are not always bit-identical between R and Python the way the sample stream is. MonteCarloIntegration/Miser/ Vegas are ported CORE code, so – unlike the callback surface’s own catalog tests, which the C++ side compiles with -ffp-contract=off for exactly this reason – they compile with whatever fused-multiply-add behavior each package’s own build flags happen to produce (R’s -O2 and corehydropy’s CMake default are not guaranteed to agree), and the picture is different per method rather than uniform across the surface. method="monte_carlo" is the one case measured to reproduce integral bit-for-bit across ALL FOUR runners – this package, corehydror, the C++ fixture runner under both FMA settings, and the real C# library – because its own arithmetic (a running sum of hit/miss weights divided by the sample count) has no near-cancelling subtraction for a fused-multiply-add ULP to hide in; fixtures/callback/callback_cross_language.json pins it at zero tolerance for exactly that reason. "miser" and "vegas" do not reproduce that cleanly – measured directly, "miser"’s own integral misses the C# value by 1 ULP under this package’s shipped build, and "vegas"’s integral, while itself exact against C#, sits beside a standard_error (both methods) and chi_squared ("vegas" only) that are not: both are built from a near-cancelling subtraction (avg2 - avg*avg-shaped for Monte Carlo/Miser, sum_chi_squared - sum_weighted_results * result for Vegas) that amplifies a fused-multiply-add ULP difference, and a live R-vs-corehydropy comparison of "vegas" at these settings showed integral itself, not just standard_error/chi_squared, moving by a few ULP language to language. This is a property of the classes’ own arithmetic, not a bug in either binding, and it is why fixtures/callback/callback_cross_language.json’s own quadrature_nd/quadrature_vegas digest asserts function_evaluations and status on every method, integral ADDITIONALLY on "monte_carlo" alone, and nothing else – see that file’s reference note for the measurements.

Parameters

Name	Type	Description	Default
f	callable	A function taking a sequence of numbers and returning one number (`method="monte_carlo"` /`"miser"`), or a function taking a sequence of numbers and a number (the sample weight) and returning one number (`method="vegas"`).	required
min	sequence of float	Sequences of the same length giving the per-dimension lower and upper bounds; their common length is the number of dimensions. Every `max` entry must be above the matching `min` entry.	required
max	sequence of float	Sequences of the same length giving the per-dimension lower and upper bounds; their common length is the number of dimensions. Every `max` entry must be above the matching `min` entry.	required
method	str	One of `"monte_carlo"` (the default), `"miser"`, or `"vegas"`.	`'monte_carlo'`
seed	int	A seed for the class’s random number generator. Left unset, the ported class’s own clock-seeded default applies – see the note above on when that still reproduces.	`None`
use_sobol	bool	Whether to draw sample points from a Sobol low-discrepancy sequence rather than the (possibly seeded) generator. Default `True`. Only `"miser"` and `"vegas"` read this.	`True`
max_function_evaluations	int	The cap on evaluations of `f`. Left unset, the ported class’s own default applies. Applies to `"monte_carlo"` and `"miser"` alone – `"miser"`’s own recursion is bounded directly by it, where `"monte_carlo"`’s loop is bounded by `max_iterations` instead (see below); supplying it for `method="vegas"` raises `ValueError`.	`None`
min_iterations	optional	`method="monte_carlo"` alone: the floor on iterations before the convergence check is consulted, the ceiling on iterations (`"monte_carlo"`’s real throttle, since `max_function_evaluations` is checked only after the loop ends to choose the reported status), and the relative-error convergence threshold. Left unset, the ported class’s own defaults apply. Supplying any for another `method` raises `ValueError`.	`None`
max_iterations	optional	`method="monte_carlo"` alone: the floor on iterations before the convergence check is consulted, the ceiling on iterations (`"monte_carlo"`’s real throttle, since `max_function_evaluations` is checked only after the loop ends to choose the reported status), and the relative-error convergence threshold. Left unset, the ported class’s own defaults apply. Supplying any for another `method` raises `ValueError`.	`None`
relative_tolerance	optional	`method="monte_carlo"` alone: the floor on iterations before the convergence check is consulted, the ceiling on iterations (`"monte_carlo"`’s real throttle, since `max_function_evaluations` is checked only after the loop ends to choose the reported status), and the relative-error convergence threshold. Left unset, the ported class’s own defaults apply. Supplying any for another `method` raises `ValueError`.	`None`
fraction	optional	`method="miser"` alone: the fraction of remaining evaluations spent exploring variance at each stage, the minimum points per terminal subregion, the minimum evaluations before a subregion is bisected further, and the dither applied when the integrand’s active region falls on a subdivision boundary. Left unset, the ported class’s own defaults apply. Supplying any for another `method` raises `ValueError`.	`None`
min_subregion_points	optional	`method="miser"` alone: the fraction of remaining evaluations spent exploring variance at each stage, the minimum points per terminal subregion, the minimum evaluations before a subregion is bisected further, and the dither applied when the integrand’s active region falls on a subdivision boundary. Left unset, the ported class’s own defaults apply. Supplying any for another `method` raises `ValueError`.	`None`
min_bisections	optional	`method="miser"` alone: the fraction of remaining evaluations spent exploring variance at each stage, the minimum points per terminal subregion, the minimum evaluations before a subregion is bisected further, and the dither applied when the integrand’s active region falls on a subdivision boundary. Left unset, the ported class’s own defaults apply. Supplying any for another `method` raises `ValueError`.	`None`
dither	optional	`method="miser"` alone: the fraction of remaining evaluations spent exploring variance at each stage, the minimum points per terminal subregion, the minimum evaluations before a subregion is bisected further, and the dither applied when the integrand’s active region falls on a subdivision boundary. Left unset, the ported class’s own defaults apply. Supplying any for another `method` raises `ValueError`.	`None`
independent_evaluations	int \| None		`None`
function_calls	int \| None		`None`
alpha	int \| None		`None`
number_of_bins	int \| None		`None`
tail_focus_parameter	int \| None		`None`
initialize	optional	`method="vegas"` alone. `independent_evaluations` and `function_calls` bound the run (their product is the maximum total evaluations); `alpha` is the grid-refinement damping exponent; `number_of_bins` the stratification bin count; `tail_focus_parameter` the Power Transform exponent (1.0, the default, is standard uniform sampling); `initialize` selects a cold start (0, the default), inheriting the grid alone (1), or inheriting the grid and its answers (2); `check_convergence` whether to exit early on convergence. `target_probability`, if supplied, calls the ported `configure_for_rare_events()` helper – applied AFTER every other option, so it may override `number_of_bins`/`alpha`/`tail_focus_parameter`, exactly as the C# helper does. Left unset, the ported class’s own defaults apply. Supplying any for another `method` raises `ValueError`.	`None`
check_convergence	optional	`method="vegas"` alone. `independent_evaluations` and `function_calls` bound the run (their product is the maximum total evaluations); `alpha` is the grid-refinement damping exponent; `number_of_bins` the stratification bin count; `tail_focus_parameter` the Power Transform exponent (1.0, the default, is standard uniform sampling); `initialize` selects a cold start (0, the default), inheriting the grid alone (1), or inheriting the grid and its answers (2); `check_convergence` whether to exit early on convergence. `target_probability`, if supplied, calls the ported `configure_for_rare_events()` helper – applied AFTER every other option, so it may override `number_of_bins`/`alpha`/`tail_focus_parameter`, exactly as the C# helper does. Left unset, the ported class’s own defaults apply. Supplying any for another `method` raises `ValueError`.	`None`
target_probability	optional	`method="vegas"` alone. `independent_evaluations` and `function_calls` bound the run (their product is the maximum total evaluations); `alpha` is the grid-refinement damping exponent; `number_of_bins` the stratification bin count; `tail_focus_parameter` the Power Transform exponent (1.0, the default, is standard uniform sampling); `initialize` selects a cold start (0, the default), inheriting the grid alone (1), or inheriting the grid and its answers (2); `check_convergence` whether to exit early on convergence. `target_probability`, if supplied, calls the ported `configure_for_rare_events()` helper – applied AFTER every other option, so it may override `number_of_bins`/`alpha`/`tail_focus_parameter`, exactly as the C# helper does. Left unset, the ported class’s own defaults apply. Supplying any for another `method` raises `ValueError`.	`None`

Returns

Name	Type	Description
	QuadratureResult	The integral, carrying `status`, `function_evaluations`, and `standard_error`, and, for `method="vegas"` alone, `chi_squared`. An upstream quirk, verified against the real C# source rather than assumed: `method="miser"` always reports `status` `"None"` on success – unlike `"monte_carlo"` and `"vegas"`, the ported `Miser::integrate()` (faithfully mirroring C#’s `Miser.Integrate()`) never assigns a success status, only ever writing `"Failure"` from its catch block.

Examples

>>> import corehydropy as ch
>>> round(ch.quadrature_nd(lambda x: 1.0 if x[0]**2 + x[1]**2 < 1 else 0.0,
...                        [-1, -1], [1, 1], seed=12345), 1)
3.1