baybe.simulation.simulate_experiment

baybe.simulation.simulate_experiment(campaign: Campaign, lookup: DataFrame | Callable | None = None, /, *, batch_size: int = 1, n_doe_iterations: int | None = None, initial_data: DataFrame | None = None, random_seed: int = 1337, impute_mode: Literal['error', 'worst', 'best', 'mean', 'random', 'ignore'] = 'error', noise_percent: float | None = None)[source]

Simulate a Bayesian optimization loop.

The most basic type of simulation. Runs a single execution of the loop either for a specified number of steps or until there are no more configurations left to be tested.

Parameters:

  • campaign (Campaign) – The DOE setting to be simulated.

  • lookup (Union[DataFrame, Callable, None]) – The lookup used to close the loop, provided in the form of a dataframe or callable that define the targets for the queried parameter settings: First, a dataframe containing experimental settings and their target results can be chosen. Second, A callable, providing target values for the given parameter settings. can be chosen. The callable is assumed to return either a float or a tuple of floats and to accept an arbitrary number of floats as input. Finally,``None`` can be chosen, producing fake results.

  • batch_size (int) – The number of recommendations to be queried per iteration.

  • n_doe_iterations (Optional[int]) – The number of iterations to run the design-of-experiments loop. If not specified, the simulation proceeds until there are no more testable configurations left.

  • initial_data (Optional[DataFrame]) – The initial measurement data to be ingested before starting the loop.

  • random_seed (int) – The random seed used for the simulation.

  • impute_mode (Literal['error', 'worst', 'best', 'mean', 'random', 'ignore']) –

    Specifies how a missing lookup will be handled. There are six different options available.

    • "error": An error will be thrown.

    • "worst": Imputation uses the worst available value for each target.

    • "best": Imputation uses the best available value for each target.

    • "mean": Imputation uses the mean value for each target.

    • "random": A random row will be used as lookup.

    • "ignore": The search space is stripped before recommendations are made so that unmeasured experiments will not be recommended.

  • noise_percent (Optional[float]) – If not None, relative noise in percent of noise_percent will be applied to the parameter measurements.

Return type:

DataFrame

Returns:

A dataframe ready for plotting, see the Note for details.

Raises:

  • TypeError – If a non-suitable lookup is chosen.

  • ValueError – If the impute mode ignore is chosen for non-dataframe lookup.

  • ValueError – If a setup is provided that would run indefinitely.

Note

The returned dataframe contains the following columns:

  • Iteration: Corresponds to the DOE iteration (starting at 0)

  • Num_Experiments: Corresponds to the running number of experiments performed (usually x-axis)

  • for each target a column {targetname}_IterBest: Corresponds to the best result for that target at the respective iteration

  • for each target a column {targetname}_CumBest: Corresponds to the best result for that target up to including respective iteration

  • for each target a column {targetname}_Measurements: The individual measurements obtained for the respective target and iteration