gemseo / algos / doe

# doe_lib module¶

## DOE library base class wrapper¶

class gemseo.algos.doe.doe_lib.DOEAlgorithmDescription(algorithm_name, internal_algorithm_name, library_name='', description='', website='', handle_integer_variables=True, require_gradient=False, minimum_dimension=1)[source]

The description of a DOE algorithm.

Parameters
• algorithm_name (str) –

• internal_algorithm_name (str) –

• library_name (str) –

By default it is set to .

• description (str) –

By default it is set to .

• website (str) –

By default it is set to .

• handle_integer_variables (bool) –

By default it is set to True.

• require_gradient (bool) –

By default it is set to False.

• minimum_dimension (int) –

By default it is set to 1.

Return type

None

algorithm_name: str

The name of the algorithm in GEMSEO.

description: str = ''

A description of the algorithm.

handle_integer_variables: bool = True

Whether the optimization algorithm handles integer variables.

internal_algorithm_name: str

The name of the algorithm in the wrapped library.

library_name: str = ''

The name of the wrapped library.

minimum_dimension: int = 1

The minimum dimension of the parameter space.

require_gradient: bool = False

Whether the optimization algorithm requires the gradient.

website: str = ''

The website of the wrapped library or algorithm.

class gemseo.algos.doe.doe_lib.DOELibrary[source]

Abstract class to use for DOE library link See DriverLib.

Constructor Abstract class.

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

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

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

Returns

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

Return type

ndarray

static compute_phip_criteria(samples, power=10.0)[source]

Compute the $$\phi^p$$ space-filling criterion.

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

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

Returns

The $$\phi^p$$ space-filling criterion.

Return type

float

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

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)[source]

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

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

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, **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.

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.

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)[source]

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

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

get_x0_and_bounds_vects(normalize_ds)

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

Parameters

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

Returns

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.

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

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

Raises

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

Return type

None

init_options_grammar(algo_name)

Initialize the options grammar.

Parameters

algo_name (str) – The name of the algorithm.

Return type

gemseo.core.grammars.json_grammar.JSONGrammar

Returns True if the algorithm requires a gradient evaluation.

Parameters

algo_name – The name of the algorithm.

static is_algorithm_suited(algorithm_description, problem)[source]

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

Parameters
Returns

Whether the algorithm is suited to the problem.

Return type

bool

new_iteration_callback(x_vect=None)

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.

Parameters

x_vect (ndarray | None) –

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

By default it is set to None.

Raises

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

Return type

None

COMPLEX_STEP_METHOD = 'complex_step'
DESIGN_ALGO_NAME = 'Design algorithm'
DIFFERENTIATION_METHODS = ['user', 'complex_step', 'finite_differences']
DIMENSION = 'dimension'
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] = None

The name of the interfaced library.

MAX_DS_SIZE_PRINT = 40
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.

PHIP_CRITERIA = 'phi^p'
ROUND_INTS_OPTION = 'round_ints'
SAMPLES_TAG = 'samples'
SEED = 'seed'
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]$$.