Parameter types and pre-defined classes

melissa.server.parameters.ParameterSamplerType

Bases: Enum

Enum to choose the paramter sampler type.

  • RANDOM_UNIFORM = 0
  • HALTON = 1
  • LHS = 2

melissa.server.parameters.RandomUniform

Bases: RandomUniformSamplerMixIn, SobolBaseExperiment

Random uniform sampling experiment that integrates Sobol and uniform sampling methods.

melissa.server.parameters.HaltonGenerator

Bases: HaltonSamplerMixIn, SobolBaseExperiment

Deterministic sample generator based on scipy Halton sequence https://docs.scipy.org/doc/scipy/reference/generated/scipy.stats.qmc.Halton.html

melissa.server.parameters.LHSGenerator

Bases: LatinHypercubeSamplerMixIn, SobolBaseExperiment

Non-deterministic sample generator based on scipy LHS sampling https://docs.scipy.org/doc/scipy/reference/generated/scipy.stats.qmc.LatinHypercube.html

Creating a parameter sampler

melissa.server.parameters.make_parameter_sampler(sampler_t, **kwargs)

Creates and returns an instance of a parameter sampler based on the specified sampler type.

This function supports both predefined sampler types from ParameterSamplerType and custom sampler classes passed directly. It instantiates the appropriate sampler class with the provided keyword arguments.

Parameters:
  • sampler_t (Union[ParameterSamplerType, Type[ParameterSamplerClass]]):
    • ParameterSamplerType: An enum value from ParameterSamplerType. (RANDOM_UNIFORM, HALTON, LHS)
    • Type[ParameterSamplerClass]: A predefined or a custom class type to be instantiated (Not an object).
  • kwargs: Additional keyword arguments passed to the sampler class constructor.
Returns:
  • BaseExperiment: An instance of the chosen parameter sampler.
Raises:
  • ValueError: If sampler_t is not one of the supported enum values or a valid subclass of BaseExperiement.

Base classes

These parent classes can be used for creating a custom parameter sampler. The inherited server must set the sampler via set_parameter_sampler method.

melissa.server.parameters.BaseExperiment

Bases: ABC

A base class for parameter generation strategies for simulations.

  • This class serves as the common parent for different methods of sampling simulation parameters. The draw() method, which is implemented by subclasses, is called from the server when creating client scripts to generate parameter values.
  • The sample() method samples parameters in their raw form that must be post-processed.
Attributes
  • nb_params (int): The number of parameters to be generated.
  • nb_sims (int): The number of simulations to be run.
  • l_bounds (List[Union[float, int]]): The lower bounds for the parameter values.
  • u_bounds (List[Union[float, int]]): The upper bounds for the parameter values.
  • seed (int): The seed value for random number generation to ensure reproducibility (Default is None).
  • dtype (DTypeLike): The data type for the generated parameters. (Default is np.float64)
  • rng Generator: A NumPy random number generator initialized with either the given seed or a random seed.
  • parameters (MemmapWrapper): The pre-generated parameter values stored as a NumPy array or memmap.
  • _current_idx (int): The current index for selecting the next set of parameters.

checkpoint_state()

Saves the current state for checkpointing.

restart_from_checkpoint()

Restores the state from a checkpoint.

__initialize_memmap()

Initializes a numpy.memmap to store the parameters to be sampled in a file such that we share a common set of attributes across a parallel server.

The sampling rank performs the sampling and writes to a file. Usually, the sampling rank is the last MPI rank but the decision is made at runtime for multi-node studies.

set_seeds()

Sets the random seeds for ensuring reproducibility across experiments.

This method initializes the random seed for,

-Python's random module - NumPy's random number generator - Default random number generator (RNG) using NumPy's default_rng.

Behavior
  • If self.seed is specified, it sets the same seed across random, NumPy's random module, and np.random.default_rng for consistent results.
  • If self.seed is not specified (None or 0), it initializes self.rng with a random seed provided by the system.

process_drawn(parameters)

Processes the next set of parameters before generating client scripts.

Parameters:
  • parameters (NDArray): A row of parameters obtained from a pre-generated parameters matrix of shape (nb_sims, nb_params).
Returns
  • Any: Processed parameter compatible with the client scripts.

For example, if your client script requires the inputs in a certain way

python3 solver.py --arg1=<p0> --arg2=<p1>

Then, process_drawn can be overriden such that it returns

def process_drawn(self, parameters: NDArray) -> List[str]:
    return [f"--arg1={parameters[0]}", "--arg2=parameters[1]"]

draw(sim_id)

Draws the next set of parameters.

Parameters

sim_id (int): The simulation id for which the parameter set returned.

Returns
  • Any: The set of processed parameters from the pre-generated array.

set_parameters(parameters)

Sets the static parameters.

Parameters
  • parameters (Union[List, NDArray]): A list or array of parameters to set.

flush_to_disk()

Writes current parameter map to memmap_file on the disk.

base_sample(nb_samples) abstractmethod

Generates the specified number of parameter sets.

Parameters
  • nb_samples (int): The number of parameter sets to generate.
Returns
  • Any: The generated set of parameters.

sample(nb_samples)

Generates parameter sets using the base sampling method.

Parameters
  • nb_samples (int): The number of parameter sets to generate.
Returns
  • Any: The generated set of parameters.

finalize(exit_=0)

Finalizes the experiment by cleaning up resources.

Parameters
  • exit_ (int): Exit code indicating the status of the experiment.
Behavior
  • Removes the memory-mapped file (memmap_file) if it exists and the exit code is 0.

melissa.server.parameters.SobolBaseExperiment

Bases: BaseExperiment

SobolBaseExperiment is an extension of the BaseExperiment class designed to support Sobol sensitivity analysis. It introduces the concept of the pick-freeze method for generating samples and supports both first-order and second-order Sobol indices.

Attributes

apply_pick_freeze (bool): Indicates whether to use the pick-freeze method for sample generation. second_order (bool): Specifies whether to include second-order Sobol indices in the pick-freeze matrix generation.

generate_pick_freeze_matrix(sample_a, sample_b)

Returns a pick-freeze matrix given the set of input parameters.

pick_freeze_sample(nb_samples)

Generates samples using the pick-freeze method.

MixIn Classes

melissa.server.parameters.RandomUniformSamplerMixIn

This class defines sample() method for random sampling with numpy.

base_sample(nb_samples)

Generates random samples uniformly distributed between specified bounds.

Parameters
  • nb_samples (int): The number of samples to generate.
Returns
  • NDArray: A numpy array of shape (nb_samples, nb_params) containing the sampled parameters.

melissa.server.parameters.QMCSamplerMixIn

Mixin class for samplers based on scipy.stats.qmc methods, such as Halton and Latin Hypercube.

This class defines the sample() method specifically for generating samples using quasi-Monte Carlo methods, including Halton and Latin Hypercube samplers

base_sample(nb_samples)

Generates scaled samples using the chosen quasi-Monte Carlo sampler.

Returns
  • NDArray: A numpy array of shape (nb_samples, nb_params) containing the sampled parameters.

melissa.server.parameters.HaltonSamplerMixIn

Bases: QMCSamplerMixIn

Mixin class for scipy.stats.qmc.Halton sampler to be set.

melissa.server.parameters.LatinHypercubeSamplerMixIn

Bases: QMCSamplerMixIn

Mixin class for scipy.stats.qmc.LatinHypercube sampler to be set.