gemseo_umdo / statistics / multilevel / mlmc_mlcv

Hide inherited members

mlmc_mlcv module

Multilevel Monte Carlo with multilevel control variates (MLMC-MLCV).

class gemseo_umdo.statistics.multilevel.mlmc_mlcv.mlmc_mlcv.MLMCMLCV(levels, uncertain_space, n_samples, pilot='Mean', variant=Variant.MLMC_MLCV, seed=0)[source]

Bases: MLMC

Multilevel Monte Carlo with multilevel control variates (MLMC-MLCV).

Parameters:

  • levels (Sequence[Level]) – The levels defined in terms of model, evaluation cost and initial number of calls.

  • uncertain_space (ParameterSpace) – The uncertain space on which to sample the functions.

  • n_samples (float) – The sampling budget expressed as the number of model evaluations equivalent to evaluations of the finest model. This number is not necessarily an integer; for instance, if $f_L$ is twice as expensive as $f_{L-1}$, then n_samples=1.5 can correspond to 1 evaluation of $f_L$ and 1 evaluation of $f_{L-1}$.

  • pilot_statistic_name – The name of the statistic used to drive the algorithm.

  • seed (int) –

    The initial random seed for reproducibility. Then, the seed is incremented at each level of the telescopic sum and at each algorithm iteration.

    By default it is set to 0.

  • pilot (str) –

    By default it is set to “Mean”.

  • variant (Variant) –

    By default it is set to “MLMC-MLCV”.

Raises:

ValueError – When the minimum cost is greater than the maximum cost.

class Variant(value)[source]

Bases: StrEnum

A variant of the MLMC-MLCV algorithm.

MLMC_CV = 'MLMC-CV'
MLMC_CV_0 = 'MLMC-CV[0]'
MLMC_MLCV = 'MLMC-MLCV'
MLMC_MLCV_0 = 'MLMC-MLCV[0]'
execute()

Execute the algorithm.

Return type:

None

classmethod get_surrogate_positions(level, n_levels, variant)[source]

Return the positions of the surrogate models for given level and variant.

These are their positions in a sequence starting to count at 0. So, the position of $g_ell$ is $ell$ for $ellin{0,ldots,L}$ while the position of $h_ell$ is $ell-1$ for $ellin{1,ldots,L}$.

Parameters:

  • level (int) – The level of the telescopic sum.

  • n_levels (int) – The number of levels.

  • variant (Variant) – The variant of the algorithm.

Returns:

The positions of the surrogate models.

Return type:

slice

See also

El Amri et al., Table 1, Multilevel Surrogate-based Control Variates, 2023.

plot_evaluation_history(show=True, file_path=None, log_n_evaluations=True, log_budget=False)

Plot the history of the model evaluations in terms of sample size and budget.

Parameters:

  • show (bool) –

    Whether to display the graph.

    By default it is set to True.

  • file_path (str | Path) – The file path to save the graph.

  • log_n_evaluations (bool) –

    Whether to use a log-scale for the number of evaluations.

    By default it is set to True.

  • log_budget (bool) –

    Whether to use a log-scale for the budget.

    By default it is set to False.

Return type:

None

property budget_history: ndarray[Any, dtype[float]]

The history of the budget.

algo.budget_history[i] is the budget at iteration i+1.

property level_costs: ndarray[Any, dtype[float]]

The evaluation costs of the different levels.

algo.level_costs[l] is the cost of one evaluation of the l-th level.

property model_costs: ndarray[Any, dtype[float]]

The evaluation costs of the different models.

algo.model_costs[l] is the cost of one evaluation of the l-th model.

property n_total_samples: ndarray[Any, dtype[int]]

The total numbers of samples per level.

algo.n_total_samples[l] is the total number of samples at level l.

property pilot_statistic_estimation: ndarray[Any, dtype[float]]

The estimation of the pilot statistic.

property sampling_history: ndarray[Any, dtype[int]]

The history of the numbers of samples of each level of the telescopic sum.

algo.sampling_size_history[i, l] is the number of samples at iteration i+1 and level l.