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
  • DEFAULT_BREED = 3

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 both static and dynamic 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.

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.

generator()

Generates the parameters for each simulation.

Returns
  • Any: An iterator that yields the generated parameters.

draw() abstractmethod

Draws the next set of parameters. This method must call sample(nb_samples) that returns the parameters in their raw format. But, user can perform post-processing here.

Make sure that you return an iterable and not a single type. The returned parameters will be used by server's client script generation phase which converts each parameter in this returned iterable into a string to be attached. Therefore, the return type must have defined __str__.

Returns
  • List[Any]: The generated set of parameters.

sample(nb_samples) abstractmethod

Samples the specified number of parameter sets.

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

melissa.server.parameters.StaticExperiment

Bases: BaseExperiment

StaticExperiment class generates and stores fixed parameters for simulations. It overrides the draw() method to provide parameters sequentially, and stores them in the parameters, indexed by simulation id.

When instantiated it will set parameters of shape (nb_sims, nb_params).

Attributes
  • _current_idx (int): The current index for selecting the next set of parameters.
  • parameters (NDArray): The pre-generated parameter values stored as a NumPy array for each simulation.

draw()

Draws the next set of static parameters.

Returns
  • NDArray: The next set of parameters from the pre-generated list.

set_parameters(parameters)

Sets the static parameters.

Parameters
  • parameters (Union[List, NDArray]): A list or array of parameters to set.
Raises
  • ValueError: If the parameters list is empty.

checkpoint_state()

Saves the current state for checkpointing.

restart_from_checkpoint()

Restores the state from a checkpoint.

melissa.server.parameters.SobolBaseExperiment

Bases: PickFreezeMixIn, BaseExperiment

A Base class with pick-freeze methods and dynamic parameters.

MixIn Classes

melissa.server.parameters.PickFreezeMixIn

Mixin class for implementing pick-freeze sampling method.

This method is useful for generating parameter sets for multiple clients (or a group of clients), often used in Sobol groups for sensitivity analysis. The class provides functionality to apply the pick-freeze technique, which combines two sets of samples by freezing one parameter from one set while changing others based on the second set.

Attributes
  • nb_params (int): The number of parameters in the sample.
  • apply_pick_freeze (bool): A flag to enable or disable the pick-freeze method.
  • second_order (bool): A flag to indicate if second-order interactions.

pick_freeze(sample_a, sample_b)

Applies the pick-freeze method to construct the set of input parameters.

This method generates a new set of samples by combining two input samples (sample_a and sample_b). It freezes one parameter from each sample and then combines them with the others.

Parameters
  • sample_a (NDArray): The first set of sample parameters.
  • sample_b (NDArray): The second set of sample parameters.
Returns
  • NDArray: A new set of generated samples using the pick-freeze method.

__pf_draw()

Generates dynamic parameters for the current simulation using the pick-freeze method.

If the pick-freeze method is enabled, two samples are generated and combined using the pick-freeze technique. Otherwise, a single sample is drawn.

Returns
  • NDArray: The generated parameter set for the current simulation.

draw()

Draws the next set of parameters, applying the pick-freeze method if enabled.

If the pick-freeze method is enabled, it calls the __pf_draw method to generate the parameter set. Otherwise, it uses the base class method to generate parameters.

Returns
  • NDArray: The drawn parameter set.

sample(nb_samples) abstractmethod

Abstract method to sample parameters.

Parameters
  • nb_samples (int): The number of samples to generate.
Returns
  • NDArray: The drawn samples as a numpy array.

melissa.server.parameters.RandomUniformSamplerMixIn

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

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

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.qmc.Halton sampler.

melissa.server.parameters.LatinHypercubeSamplerMixIn

Bases: QMCSamplerMixIn

MixIn class for scipy.qmc.LatinHypercube sampler.