MonteCarloOptimizer

class MonteCarloOptimizer(population_size=10, n_best_sets=3, keep_best_params=False)

Bases: Optimizer

Monte Carlo-based parameter search optimizer.

This optimizer samples parameter space randomly, selects the best-performing samples, and uses them as centers for the next generation of samples with decreasing variance. This implements a simple but effective evolutionary strategy.

Initialize a Monte Carlo optimizer.

Parameters:

• population_size (int) – Size of the population for the algorithm. Defaults to 10.

• n_best_sets (int) – Number of top-performing parameter sets to use as seeds for the next generation. Defaults to 3.

• keep_best_params (bool) – If True, includes the best parameter sets directly in the new population. If False, generates all new parameters by sampling around the best ones. Defaults to False.

Raises:

• ValueError – If n_best_sets is greater than population_size.

• ValueError – If keep_best_params is True and n_best_sets equals population_size.

Attributes Summary

keep_best_params	Get whether the best parameters are kept in the new population.
n_best_sets	Get the number of best parameter sets used for seeding the next generation.
n_param_sets	Number of parameter sets (population size), per the Optimizer interface.
population_size	Get the size of the population.

Methods Summary

get_config()	Get optimizer configuration for checkpoint reconstruction.
load_state(checkpoint_dir)	Load the optimizer's internal state from a checkpoint directory.
optimize(cost_fn[, initial_params, callback_fn])	Perform Monte Carlo optimization on the cost function.
reset()	Reset the optimizer's internal state.
save_state(checkpoint_dir)	Save the optimizer's internal state to a checkpoint directory.

Attributes Documentation

keep_best_params

Get whether the best parameters are kept in the new population.

Returns:

True if best parameters are included in new population, False otherwise.

Return type:

bool

n_best_sets

Get the number of best parameter sets used for seeding the next generation.

Returns:

Number of best-performing sets kept.

Return type:

int

n_param_sets

Number of parameter sets (population size), per the Optimizer interface.

Returns:

The population size.

Return type:

int

population_size

Get the size of the population.

Returns:

Size of the population.

Return type:

int

Methods Documentation

get_config()

Get optimizer configuration for checkpoint reconstruction.

Returns:

Dictionary containing optimizer type and configuration parameters.

Return type:

dict[str, Any]

classmethod load_state(checkpoint_dir)

Load the optimizer’s internal state from a checkpoint directory.

Creates a new MonteCarloOptimizer instance with the state restored from the checkpoint.

Parameters:

checkpoint_dir (Path | str) – Directory path where the optimizer state is saved.

Returns:

A new optimizer instance with restored state.

Return type:

MonteCarloOptimizer

Raises:

FileNotFoundError – If the checkpoint file does not exist.

optimize(cost_fn, initial_params=None, callback_fn=None, **kwargs)

Perform Monte Carlo optimization on the cost function.

Parameters:

• cost_fn (Callable[[ndarray[tuple[Any, ...], dtype[double]]], float | ndarray[tuple[Any, ...], dtype[double]]]) – The cost function to minimize.

• initial_params (ndarray[tuple[Any, ...], dtype[double]] | None) – Initial parameters for the optimization.

• callback_fn (Callable[[OptimizeResult], Any] | None) – Optional callback function to monitor progress.

• **kwargs –

  Additional keyword arguments:

  • max_iterations (int, optional): Total desired number of iterations. When resuming from a checkpoint, this represents the total iterations desired across all runs. The optimizer will automatically calculate and run only the remaining iterations needed. Defaults to 5.

  • rng (np.random.Generator, optional): Random number generator for parameter sampling. Defaults to a new generator if not provided.

Return type:

OptimizeResult

Returns:

Optimized parameters.

reset()

Reset the optimizer’s internal state.

Clears all current optimization state (population, losses, iteration, RNG state), allowing the optimizer to be reused for fresh optimization runs.

Return type:

None

save_state(checkpoint_dir)

Save the optimizer’s internal state to a checkpoint directory.

Parameters:

checkpoint_dir (Path | str) – Directory path where the optimizer state will be saved.

Raises:

RuntimeError – If optimization has not been run (no state to save).

Return type:

None