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.

class ApproximationMode(value)

Bases: StrEnum

The approximation derivation modes.

CENTERED_DIFFERENCES = 'centered_differences'

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

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.

CENTERED_DIFFERENCES = 'centered_differences'
COMPLEX_STEP = 'complex_step'
FINITE_DIFFERENCES = 'finite_differences'
USER_GRAD = 'user'
clear_listeners()

Remove the listeners from the database.

Return type:

None

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

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

Parameters:

  • variables_space (DesignSpace | int) – Either the variables space to be sampled or its dimension.

  • n_samples (int | None) – The number of samples. If None, it is deduced from the variables_spaces and the options.

  • unit_sampling (bool) –

    Whether to sample in the unit hypercube. If the value provided in variables_space is the dimension, the samples will be generated in the unit hypercube whatever the value of unit_sampling.

    By default it is set to False.

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

Returns:

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

Return type:

RealArray

deactivate_progress_bar()

Deactivate the progress bar.

Return type:

None

driver_has_option(option_name)

Check the existence of an option.

Parameters:

option_name (str) – The name of the option.

Returns:

Whether the option exists.

Return type:

bool

ensure_bounds(orig_func, normalize=True)

Project the design vector onto the design space before execution.

Parameters:

  • orig_func – The original function.

  • normalize (bool) –

    Whether to use the normalized design space.

    By default it is set to True.

Returns:

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, use_database=True, callbacks=())

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

Parameters:

  • eval_jac (bool) –

    Whether to evaluate the Jacobian function.

    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.

  • use_database (bool) –

    Whether to store the evaluations in the database.

    By default it is set to True.

  • callbacks (Iterable[CallbackType]) –

    The functions to be evaluated after each call to OptimizationProblem.evaluate_functions(); to be called as callback(index, (output, jacobian)).

    By default it is set to ().

Return type:

None

Warning

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, max_design_space_dimension_to_log=40, **options)

Execute the driver.

Parameters:

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

  • max_design_space_dimension_to_log (int) –

    The maximum dimension of a design space to be logged. If this number is higher than the dimension of the design space then the design space will not be logged.

    By default it is set to 40.

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

Returns:

The optimization result.

Raises:

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

Return type:

OptimizationResult

export_samples(doe_output_file)

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

Parameters:

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

Return type:

None

filter_adapted_algorithms(problem)

Filter the algorithms capable of solving the problem.

Parameters:

problem (Any) – The problem to be solved.

Returns:

The names of the algorithms adapted to this problem.

Return type:

list[str]

finalize_iter_observer()

Finalize the iteration observer.

Return type:

None

get_optimum_from_database(message=None, status=None)

Return the optimization result from the database.

Return type:

OptimizationResult

get_x0_and_bounds_vects(normalize_ds, as_dict=False)

Return the initial design variable values and their lower and upper bounds.

Parameters:

  • normalize_ds (bool) – Whether to normalize the design variables.

  • as_dict (bool) –

    Whether to return dictionaries instead of NumPy arrays.

    By default it is set to False.

Returns:

The initial values of the design variables, their lower bounds, and their upper bounds.

Return type:

tuple[ndarray, ndarray, ndarray] | tuple[dict[str, ndarray], dict[str, ndarray], dict[str, ndarray]]

init_iter_observer(max_iter, message='')

Initialize the iteration observer.

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

Parameters:

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

  • message (str) –

    The message to display at the beginning of the progress bar status.

    By default it is set to “”.

Raises:

ValueError – If max_iter is lower than one.

Return type:

None

init_options_grammar(algo_name)

Initialize the options’ grammar.

Parameters:

algo_name (str) – The name of the algorithm.

Return type:

JSONGrammar

classmethod is_algorithm_suited(algorithm_description, problem)

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

Parameters:

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

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

Returns:

Whether the algorithm is suited to the problem.

Return type:

bool

new_iteration_callback(x_vect)

Iterate the progress bar, implement the stop criteria.

Parameters:

x_vect (ndarray) – The design variables values.

Raises:

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

Return type:

None

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

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

Parameters:

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

  • dimension (int) –

    The dimension of the variables space if known.

    By default it is set to 0.

Returns:

The samples.

Return type:

RealArray

requires_gradient(driver_name)

Check if a driver requires the gradient.

Parameters:

driver_name (str) – The name of the driver.

Returns:

Whether the driver requires the gradient.

Return type:

bool

COMMENTS_KEYWORD: Final[str] = 'comments'

The name given to the string indicating a comment line.

DELIMITER_KEYWORD: Final[str] = 'delimiter'

The name given to the string separating two fields.

DESIGN_ALGO_NAME = 'Design algorithm'
DIMENSION = 'dimension'
DOE_FILE: Final[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] = '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: ClassVar[str | Path] = 'options'

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

OPTIONS_MAP: ClassVar[dict[str, str]] = {}

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

PHIP_CRITERIA = 'phi^p'
ROUND_INTS_OPTION = 'round_ints'
SAMPLES: Final[str] = 'samples'

The name given to the samples.

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

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

USE_DATABASE_OPTION = 'use_database'
USE_ONE_LINE_PROGRESS_BAR: ClassVar[bool] = False

Whether to use a one line progress bar.

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

The optimization problem the driver library is bonded to.

samples: RealArray

The design vector samples in the design space.

The design space variable types stored as dtype metadata.

To access those in the unit hypercube, use unit_samples.

property seed: int

The default seed used for reproducibility reasons.

unit_samples: RealArray

The design vector samples projected in the unit hypercube.

In the case of a design space of dimension \(d\), the unit hypercube is \([0,1]^d\).

To access those in the design space, use samples.