gemseo / core

doe_scenario module¶

A scenario whose driver is a design of experiments.

class gemseo.core.doe_scenario.DOEScenario(disciplines, formulation, objective_name, design_space, name=None, grammar_type='JSONGrammar', maximize_objective=False, **formulation_options)[source]¶

Bases: Scenario

A multidisciplinary scenario to be executed by a design of experiments (DOE).

A DOEScenario is a particular Scenario whose driver is a DOE. This DOE must be implemented in a DOELibrary.

Parameters:

disciplines (Sequence[MDODiscipline]) – The disciplines used to compute the objective, constraints and observables from the design variables.
formulation (str) – The class name of the MDOFormulation, e.g. "MDF", "IDF" or "BiLevel".
objective_name (str | Sequence[str]) – The name(s) of the discipline output(s) used as objective. If multiple names are passed, the objective will be a vector.
design_space (DesignSpace) – The search space including at least the design variables (some formulations requires additional variables, e.g. IDF with the coupling variables).
name (str | None) – The name to be given to this scenario. If None, use the name of the class.
grammar_type (str) –
The type of grammar to declare the input and output variables either JSON_GRAMMAR_TYPE or SIMPLE_GRAMMAR_TYPE.

By default it is set to “JSONGrammar”.
maximize_objective (bool) –
Whether to maximize the objective.

By default it is set to False.
**formulation_options (Any) – The options of the MDOFormulation.

classmethod activate_time_stamps()¶

Activate the time stamps.

For storing start and end times of execution and linearizations.

Return type:: None

add_constraint(output_name, constraint_type='eq', constraint_name=None, value=None, positive=False, **kwargs)¶

Add a design constraint.

This constraint is in addition to those created by the formulation, e.g. consistency constraints in IDF.

The strategy of repartition of the constraints is defined by the formulation.

Parameters:

output_name (str | Sequence[str]) – The names of the outputs to be used as constraints. For instance, if “g_1” is given and constraint_type=”eq”, g_1=0 will be added as constraint to the optimizer. If several names are given, a single discipline must provide all outputs.
constraint_type (str) –
The type of constraint, “eq” for equality constraint and “ineq” for inequality constraint.

By default it is set to “eq”.
constraint_name (str | None) – The name of the constraint to be stored. If None, the name of the constraint is generated from the output name.
value (float | None) – The value for which the constraint is active. If None, this value is 0.
positive (bool) –
If True, the inequality constraint is positive.

By default it is set to False.

Raises:

ValueError – If the constraint type is neither ‘eq’ or ‘ineq’.

Return type:

None

add_differentiated_inputs(inputs=None)¶

Add the inputs against which to differentiate the outputs.

If the discipline grammar type is MDODiscipline.JSON_GRAMMAR_TYPE and an input is either a non-numeric array or not an array, it will be ignored. If an input is declared as an array but the type of its items is not defined, it is assumed as a numeric array.

If the discipline grammar type is MDODiscipline.SIMPLE_GRAMMAR_TYPE and an input is not an array, it will be ignored. Keep in mind that in this case the array subtype is not checked.

Parameters:: inputs (Iterable[str] | None) – The input variables against which to differentiate the outputs. If None, all the inputs of the discipline are used.
Raises:: ValueError – When the inputs wrt which differentiate the discipline are not inputs of the latter.
Return type:: None

add_differentiated_outputs(outputs=None)¶

Add the outputs to be differentiated.

If the discipline grammar type is MDODiscipline.JSON_GRAMMAR_TYPE and an output is either a non-numeric array or not an array, it will be ignored. If an output is declared as an array but the type of its items is not defined, it is assumed as a numeric array.

If the discipline grammar type is MDODiscipline.SIMPLE_GRAMMAR_TYPE and an output is not an array, it will be ignored. Keep in mind that in this case the array subtype is not checked.

Parameters:: outputs (Iterable[str] | None) – The output variables to be differentiated. If None, all the outputs of the discipline are used.
Raises:: ValueError – When the outputs to differentiate are not discipline outputs.
Return type:: None

add_namespace_to_input(name, namespace)¶

Add a namespace prefix to an existing input grammar element.

The updated input grammar element name will be namespace + namespaces_separator + name.

Parameters:

name (str) – The element name to rename.
namespace (str) – The name of the namespace.

add_namespace_to_output(name, namespace)¶

Add a namespace prefix to an existing output grammar element.

The updated output grammar element name will be namespace + namespaces_separator + name.

Parameters:

name (str) – The element name to rename.
namespace (str) – The name of the namespace.

add_observable(output_names, observable_name=None, discipline=None)¶

Add an observable to the optimization problem.

The repartition strategy of the observable is defined in the formulation class. When more than one output name is provided, the observable function returns a concatenated array of the output values.

Parameters:

output_names (Sequence[str]) – The names of the outputs to observe.
observable_name (Sequence[str] | None) – The name to be given to the observable. If None, the output name is used by default.
discipline (MDODiscipline | None) – The discipline used to build the observable function. If None, detect the discipline from the inner disciplines.

Return type:

None

add_status_observer(obs)¶

Add an observer for the status.

Add an observer for the status to be notified when self changes of status.

Parameters:: obs (Any) – The observer to add.
Return type:: None

auto_get_grammar_file(is_input=True, name=None, comp_dir=None)¶

Use a naming convention to associate a grammar file to the discipline.

Search in the directory comp_dir for either an input grammar file named name + "_input.json" or an output grammar file named name + "_output.json".

Parameters:

is_input (bool) –
Whether to search for an input or output grammar file.

By default it is set to True.
name (str | None) – The name to be searched in the file names. If None, use the name of the discipline class.
comp_dir (str | Path | None) – The directory in which to search the grammar file. If None, use the GRAMMAR_DIRECTORY if any, or the directory of the discipline class module.

Returns:

The grammar file path.

Return type:

str

check_input_data(input_data, raise_exception=True)¶

Check the input data validity.

Parameters:

input_data (dict[str, Any]) – The input data needed to execute the discipline according to the discipline input grammar.
raise_exception (bool) –
Whether to raise on error.

By default it is set to True.

Return type:

None

check_jacobian(input_data=None, derr_approx='finite_differences', step=1e-07, threshold=1e-08, linearization_mode='auto', inputs=None, outputs=None, parallel=False, n_processes=2, use_threading=False, wait_time_between_fork=0, auto_set_step=False, plot_result=False, file_path='jacobian_errors.pdf', show=False, fig_size_x=10, fig_size_y=10, reference_jacobian_path=None, save_reference_jacobian=False, indices=None)¶

Check if the analytical Jacobian is correct with respect to a reference one.

If reference_jacobian_path is not None and save_reference_jacobian is True, compute the reference Jacobian with the approximation method and save it in reference_jacobian_path.

If reference_jacobian_path is not None and save_reference_jacobian is False, do not compute the reference Jacobian but read it from reference_jacobian_path.

If reference_jacobian_path is None, compute the reference Jacobian without saving it.

Parameters:

input_data (dict[str, ndarray] | None) – The input data needed to execute the discipline according to the discipline input grammar. If None, use the MDODiscipline.default_inputs.
derr_approx (str) –
The approximation method, either “complex_step” or “finite_differences”.

By default it is set to “finite_differences”.
threshold (float) –
The acceptance threshold for the Jacobian error.

By default it is set to 1e-08.
linearization_mode (str) –
the mode of linearization: direct, adjoint or automated switch depending on dimensions of inputs and outputs (Default value = ‘auto’)

By default it is set to “auto”.
inputs (Iterable[str] | None) – The names of the inputs wrt which to differentiate the outputs.
outputs (Iterable[str] | None) – The names of the outputs to be differentiated.
step (float) –
The differentiation step.

By default it is set to 1e-07.
parallel (bool) –
Whether to differentiate the discipline in parallel.

By default it is set to False.
n_processes (int) –
The maximum simultaneous number of threads, if use_threading is True, or processes otherwise, used to parallelize the execution.

By default it is set to 2.
use_threading (bool) –
Whether to use threads instead of processes to parallelize the execution; multiprocessing will copy (serialize) all the disciplines, while threading will share all the memory This is important to note if you want to execute the same discipline multiple times, you shall use multiprocessing.

By default it is set to False.
wait_time_between_fork (float) –
The time waited between two forks of the process / thread.

By default it is set to 0.
auto_set_step (bool) –
Whether to compute the optimal step for a forward first order finite differences gradient approximation.

By default it is set to False.
plot_result (bool) –
Whether to plot the result of the validation (computed vs approximated Jacobians).

By default it is set to False.
file_path (str | Path) –
The path to the output file if plot_result is True.

By default it is set to “jacobian_errors.pdf”.
show (bool) –
Whether to open the figure.

By default it is set to False.
fig_size_x (float) –
The x-size of the figure in inches.

By default it is set to 10.
fig_size_y (float) –
The y-size of the figure in inches.

By default it is set to 10.
reference_jacobian_path (str | Path | None) – The path of the reference Jacobian file.
save_reference_jacobian (bool) –
Whether to save the reference Jacobian.

By default it is set to False.
indices (Iterable[int] | None) – The indices of the inputs and outputs for the different sub-Jacobian matrices, formatted as {variable_name: variable_components} where variable_components can be either an integer, e.g. 2 a sequence of integers, e.g. [0, 3], a slice, e.g. slice(0,3), the ellipsis symbol (…) or None, which is the same as ellipsis. If a variable name is missing, consider all its components. If None, consider all the components of all the inputs and outputs.

Returns:

Whether the analytical Jacobian is correct with respect to the reference one.

check_output_data(raise_exception=True)¶

Check the output data validity.

Parameters:

raise_exception (bool) –

Whether to raise an exception when the data is invalid.

By default it is set to True.

Return type:

None

classmethod deactivate_time_stamps()¶

Deactivate the time stamps.

For storing start and end times of execution and linearizations.

Return type:: None

static deserialize(file_path)¶

Deserialize a discipline from a file.

Parameters:: file_path (str | Path) – The path to the file containing the discipline.
Returns:: The discipline instance.
Return type:: MDODiscipline

execute(input_data=None)¶

Execute the discipline.

This method executes the discipline:

Adds the default inputs to the input_data if some inputs are not defined in input_data but exist in MDODiscipline.default_inputs.
Checks whether the last execution of the discipline was called with identical inputs, i.e. cached in MDODiscipline.cache; if so, directly returns self.cache.get_output_cache(inputs).
Caches the inputs.
Checks the input data against MDODiscipline.input_grammar.
If MDODiscipline.data_processor is not None, runs the preprocessor.
Updates the status to MDODiscipline.STATUS_RUNNING.
Calls the MDODiscipline._run() method, that shall be defined.
If MDODiscipline.data_processor is not None, runs the postprocessor.
Checks the output data.
Caches the outputs.
Updates the status to MDODiscipline.STATUS_DONE or MDODiscipline.STATUS_FAILED.
Updates summed execution time.

Parameters:: input_data (Mapping[str, Any] | None) – The input data needed to execute the discipline according to the discipline input grammar. If None, use the MDODiscipline.default_inputs.
Returns:: The discipline local data after execution.
Raises:: RuntimeError – When residual_variables are declared but self.run_solves_residuals is False. This is not supported yet.
Return type:: dict[str, Any]

export_to_dataset(name=None, by_group=True, categorize=True, opt_naming=True, export_gradients=False)[source]¶

Export the database of the optimization problem to a Dataset.

The variables can be classified into groups: Dataset.DESIGN_GROUP or Dataset.INPUT_GROUP for the design variables and Dataset.FUNCTION_GROUP or Dataset.OUTPUT_GROUP for the functions (objective, constraints and observables).

Parameters:

name (str | None) – The name to be given to the dataset. If None, use the name of the OptimizationProblem.database.
by_group (bool) –
Whether to store the data by group in Dataset.data, in the sense of one unique NumPy array per group. If categorize is False, there is a unique group: Dataset.PARAMETER_GROUP`. If categorize is True, the groups can be either Dataset.DESIGN_GROUP and Dataset.FUNCTION_GROUP if opt_naming is True, or Dataset.INPUT_GROUP and Dataset.OUTPUT_GROUP. If by_group is False, store the data by variable names.

By default it is set to True.
categorize (bool) –
Whether to distinguish between the different groups of variables. Otherwise, group all the variables in Dataset.PARAMETER_GROUP`.

By default it is set to True.
opt_naming (bool) –
Whether to use Dataset.DESIGN_GROUP and Dataset.FUNCTION_GROUP as groups. Otherwise, use Dataset.INPUT_GROUP and Dataset.OUTPUT_GROUP.

By default it is set to True.
export_gradients (bool) –
Whether to export the gradients of the functions (objective function, constraints and observables) if the latter are available in the database of the optimization problem.

By default it is set to False.

Returns:

A dataset built from the database of the optimization problem.

Return type:

Dataset

get_all_inputs()¶

Return the local input data as a list.

The order is given by MDODiscipline.get_input_data_names().

Returns:: The local input data.
Return type:: list[Any]

get_all_outputs()¶

Return the local output data as a list.

The order is given by MDODiscipline.get_output_data_names().

Returns:: The local output data.
Return type:: list[Any]

get_attributes_to_serialize()¶

Define the names of the attributes to be serialized.

Shall be overloaded by disciplines

Returns:: The names of the attributes to be serialized.
Return type:: list[str]

get_available_driver_names()¶

The available drivers.

Return type:: list[str]

static get_data_list_from_dict(keys, data_dict)¶

Filter the dict from a list of keys or a single key.

If keys is a string, then the method return the value associated to the key. If keys is a list of strings, then the method returns a generator of value corresponding to the keys which can be iterated.

Parameters: