gemseo / algos / doe

lib_custom module

Design of experiments from custom data.

class gemseo.algos.doe.lib_custom.CustomDOE[source]

Bases: gemseo.algos.doe.doe_lib.DOELibrary

A design of experiments from samples provided as a file or an array.

The samples are provided either as a file in text or csv format or as a sequence of sequences of numbers, e.g. a 2D numpy array.

A csv file format is assumed to have a header whereas a text file (extension .txt) does not.

Constructor Abstract class.

Return type


compute_doe(variables_space, size=None, unit_sampling=False, **options)

Compute a design of experiments (DOE) in a variables space.

  • variables_space (DesignSpace) – The variables space to be sampled.

  • size (int | None) –

    The size of the DOE. If None, the size is deduced from the options.

    By default it is set to None.

  • unit_sampling (bool) –

    Whether to sample in the unit hypercube.

    By default it is set to False.

  • **options (DOELibraryOptionType) – The options of the DOE algorithm.


The design of experiments whose rows are the samples and columns the variables.

Return type


static compute_phip_criteria(samples, power=10.0)

Compute the \(\phi^p\) space-filling criterion.

See Morris & Mitchell, Exploratory designs for computational experiments, 1995.

  • samples (numpy.ndarray) – The samples of the input variables.

  • power (float) –

    The power \(p\) of the \(\phi^p\) criterion.

    By default it is set to 10.0.


The \(\phi^p\) space-filling criterion.

Return type



Deactivate the progress bar.

Return type



Check the existence of an option.


option_name (str) – The name of the option.


Whether the option exists.

Return type


ensure_bounds(orig_func, normalize=True)

Project the design vector onto the design space before execution.

  • orig_func – The original function.

  • normalize

    Whether to use the normalized design space.

    By default it is set to True.


A function calling the original function with the input data projected onto the design space.

evaluate_samples(eval_jac=False, n_processes=1, wait_time_between_samples=0.0)

Evaluate all the functions of the optimization problem at the samples.

  • eval_jac (bool) –

    Whether to evaluate the Jacobian.

    By default it is set to False.

  • n_processes (int) –

    The maximum simultaneous number of processes used to parallelize the execution.

    By default it is set to 1.

  • wait_time_between_samples (float) –

    The time to wait between each sample evaluation, in seconds.

    By default it is set to 0.0.


This class relies on multiprocessing features when n_processes > 1, it is therefore necessary to protect its execution with an if __name__ == '__main__': statement when working on Windows.

execute(problem, algo_name=None, eval_obs_jac=False, skip_int_check=False, **options)

Execute the driver.

  • problem (OptimizationProblem) – The problem to be solved.

  • algo_name (str | None) –

    The name of the algorithm. If None, use the algo_name attribute which may have been set by the factory.

    By default it is set to None.

  • eval_obs_jac (bool) –

    Whether to evaluate the Jacobian of the observables.

    By default it is set to False.

  • skip_int_check (bool) –

    Whether to skip the integer variable handling check of the selected algorithm.

    By default it is set to False.

  • **options (DriverLibOptionType) – The options for the algorithm.


The optimization result.


ValueError – If algo_name was not either set by the factory or given as an argument.

Return type



Export the samples generated by DOE library to a CSV file.


doe_output_file (Path | str) – The path to the output file.

Return type



Filter the algorithms capable of solving the problem.


problem (Any) – The problem to be solved.


The names of the algorithms adapted to this problem.

Return type



Finalize the iteration observer.

Return type


get_optimum_from_database(message=None, status=None)

Retrieves the optimum from the database and builds an optimization result object from it.


Gets x0, bounds, normalized or not depending on algo options, all as numpy arrays.


normalize_ds – Whether to normalize the input variables that are not integers, according to the normalization policy of the design space.


The current value, the lower bounds and the upper bounds.

init_iter_observer(max_iter, message)

Initialize the iteration observer.

It will handle the stopping criterion and the logging of the progress bar.

  • max_iter (int) – The maximum number of iterations.

  • message (str) – The message to display at the beginning.


ValueError – If the max_iter is not greater than or equal to one.

Return type



Initialize the options grammar.


algo_name (str) – The name of the algorithm.

Return type



Returns True if the algorithm requires a gradient evaluation.


algo_name – The name of the algorithm.

static is_algorithm_suited(algorithm_description, problem)

Check if the algorithm is suited to the problem according to its description.


Whether the algorithm is suited to the problem.

Return type



Callback called at each new iteration, i.e. every time a design vector that is not already in the database is proposed by the optimizer.

Iterate the progress bar, implement the stop criteria.


x_vect (ndarray | None) –

The design variables values. If None, use the values of the last iteration.

By default it is set to None.


MaxTimeReached – If the elapsed time is greater than the maximum execution time.

Return type


read_file(doe_file, delimiter=',', comments='#', skiprows=0)[source]

Read a file containing several samples (one per line) and return them.

  • doe_file (str | Path | TextIO) – Either the file, the filename, or the generator to read.

  • delimiter (str | None) –

    The character used to separate values. If None, use whitespace.

    By default it is set to ,.

  • comments (str | Sequence[str] | None) –

    The characters or list of characters used to indicate the start of a comment. None implies no comments.

    By default it is set to #.

  • skiprows (int) –

    Skip the first skiprows lines.

    By default it is set to 0.


The samples.

Return type


COMMENTS_KEYWORD: ClassVar[str] = 'comments'

The name given to the string indicating a comment line.

COMPLEX_STEP_METHOD = 'complex_step'
DELIMITER_KEYWORD: ClassVar[str] = 'delimiter'

The name given to the string separating two fields.

DESIGN_ALGO_NAME = 'Design algorithm'
DIFFERENTIATION_METHODS = ['user', 'complex_step', 'finite_differences']
DIMENSION = 'dimension'
DOE_FILE: ClassVar[str] = 'doe_file'

The name given to the DOE file.

EQ_TOLERANCE = 'eq_tolerance'
EVAL_JAC = 'eval_jac'
EVAL_OBS_JAC_OPTION = 'eval_obs_jac'
FINITE_DIFF_METHOD = 'finite_differences'
INEQ_TOLERANCE = 'ineq_tolerance'
LEVEL_KEYWORD = 'levels'
LIBRARY_NAME: ClassVar[str | None] = 'GEMSEO'

The name of the interfaced library.

MAX_TIME = 'max_time'
NORMALIZE_DESIGN_SPACE_OPTION = 'normalize_design_space'
N_PROCESSES = 'n_processes'
N_SAMPLES = 'n_samples'
OPTIONS_DIR: Final[str] = 'options'

The name of the directory containing the files of the grammars of the options.

OPTIONS_MAP: dict[str, str] = {}

The names of the options in GEMSEO mapping to those in the wrapped library.

ROUND_INTS_OPTION = 'round_ints'
SAMPLES: ClassVar[str] = 'samples'

The name given to the samples.

SAMPLES_TAG = 'samples'
SEED = 'seed'
SKIPROWS_KEYWORD: ClassVar[str] = 'skiprows'

The name given to the number of skipped rows in the DOE file.

USE_DATABASE_OPTION = 'use_database'
WAIT_TIME_BETWEEN_SAMPLES = 'wait_time_between_samples'
activate_progress_bar: ClassVar[bool] = True

Whether to activate the progress bar in the optimization log.

algo_name: str | None

The name of the algorithm used currently.

property algorithms: list[str]

The available algorithms.

descriptions: dict[str, AlgorithmDescription]

The description of the algorithms contained in the library.

internal_algo_name: str | None

The internal name of the algorithm used currently.

It typically corresponds to the name of the algorithm in the wrapped library if any.

opt_grammar: JSONGrammar | None

The grammar defining the options of the current algorithm.

problem: Any | None

The problem to be solved.

samples: ndarray | None

The input samples.

seed: int

The seed to be used for replicability reasons.

It increments with each generation of samples so that repeating the generation of sets of \(N\) leads to different sets.

unit_samples: ndarray | None

The input samples transformed in \([0,1]\).