gemseo / algos / doe

Hide inherited members

lib_custom module

Design of experiments from custom data.

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

Bases: 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.

class ApproximationMode(value)

Bases: StrEnum

The approximation derivation modes.

COMPLEX_STEP = 'complex_step'

The complex step method used to approximate the Jacobians by perturbing each variable with a small complex number.

FINITE_DIFFERENCES = 'finite_differences'

The finite differences method used to approximate the Jacobians by perturbing each variable with a small real number.

class DifferentiationMethod(value)

Bases: StrEnum

The differentiation methods.

COMPLEX_STEP = 'complex_step'
FINITE_DIFFERENCES = 'finite_differences'
USER_GRAD = 'user'
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.

  • 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:



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 (bool) –

    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.

Return type:



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.

  • 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)

Retrieve the optimum from the database and build an optimization.

Return type:



Return x0 and bounds.


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.

    By default it is set to “…”.


ValueError – If max_iter is lower than one.

Return type:



Initialize the options’ grammar.


algo_name (str) – The name of the algorithm.

Return type:


classmethod is_algorithm_suited(algorithm_description, problem)

Check if an algorithm is suited to a problem according to its description.

  • algorithm_description (AlgorithmDescription) – The description of the algorithm.

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


Whether the algorithm is suited to the problem.

Return type:



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.


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:



Check if a driver requires the gradient.


driver_name (str) – The name of the driver.


Whether the driver requires the gradient.

Return type:


COMMENTS_KEYWORD: ClassVar[str] = 'comments'

The name given to the string indicating a comment line.

DELIMITER_KEYWORD: ClassVar[str] = 'delimiter'

The name given to the string separating two fields.

DESIGN_ALGO_NAME = 'Design algorithm'
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'
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.

eval_jac: bool

Whether to evaluate the Jacobian.

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

The input samples with the design space variable types stored as dtype metadata.

seed: int

The seed to be used for reproducibility reasons.

This seed is initialized at 0 and each call to execute() increments it before using it.

unit_samples: ndarray

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