Scalable models

A scalable methodology to test MDO formulation on benchmark or real problems.

This API facilitates the use of the gemseo.problems.mdo.scalable.data_driven.study package implementing classes to benchmark MDO formulations based on scalable disciplines.

ScalabilityStudy class implements the concept of scalability study:

1. By instantiating a ScalabilityStudy, the user defines the MDO problem in terms of design parameters, objective function and constraints.

2. For each discipline, the user adds a dataset stored in a Dataset and select a type of ScalableModel to build the ScalableDiscipline associated with this discipline.

3. The user adds different optimization strategies, defined in terms of both optimization algorithms and MDO formulation.

4. The user adds different scaling strategies, in terms of sizes of design parameters, coupling variables and equality and inequality constraints. The user can also define a scaling strategies according to particular parameters rather than groups of parameters.

5. Lastly, the user executes the ScalabilityStudy and the results are written in several files and stored into directories in a hierarchical way, where names depend on both MDO formulation, scaling strategy and replications when it is necessary. Different kinds of files are stored: optimization graphs, dependency matrix plots and of course, scalability results by means of a dedicated class: ScalabilityResult.

create_scalability_study(objective, design_variables, directory='study', prefix='', eq_constraints=None, ineq_constraints=None, maximize_objective=False, fill_factor=0.7, active_probability=0.1, feasibility_level=0.8, start_at_equilibrium=True, early_stopping=True, coupling_variables=None)

This method creates a ScalabilityStudy.

It requires two mandatory arguments:

• the 'objective' name,

• the list of 'design_variables' names.

Concerning output files, we can specify:

• the directory which is 'study' by default,

• the prefix of output file names (default: no prefix).

Regarding optimization parametrization, we can specify:

• the list of equality constraints names (eq_constraints),

• the list of inequality constraints names (ineq_constraints),

• the choice of maximizing the objective function (maximize_objective).

By default, the objective function is minimized and the MDO problem is unconstrained.

Last but not least, with regard to the scalability methodology, we can overwrite:

• the default fill factor of the input-output dependency matrix ineq_constraints,

• the probability to set the inequality constraints as active at initial step of the optimization active_probability,

• the offset of satisfaction for inequality constraints feasibility_level,

• the use of a preliminary MDA to start at equilibrium start_at_equilibrium,

• the post-processing of the optimization database to get results earlier than final step early_stopping.

Parameters:

• objective (str) -- The name of the objective.

• design_variables (Iterable[str]) -- The names of the design variables.

• directory (str) --

  The working directory of the study.

  By default it is set to "study".

• prefix (str) --

  The prefix for the output filenames.

  By default it is set to "".

• eq_constraints (Iterable[str] | None) -- The names of the equality constraints, if any.

• ineq_constraints (Iterable[str] | None) -- The names of the inequality constraints, if any.

• maximize_objective (bool) --

  Whether to maximize the objective.

  By default it is set to False.

• fill_factor (float) --

  The default fill factor of the input-output dependency matrix.

  By default it is set to 0.7.

• active_probability (float) --

  The probability to set the inequality constraints as active at initial step of the optimization.

  By default it is set to 0.1.

• feasibility_level (float) --

  The offset of satisfaction for the inequality constraints.

  By default it is set to 0.8.

• start_at_equilibrium (bool) --

  Whether to start at equilibrium using a preliminary MDA.

  By default it is set to True.

• early_stopping (bool) --

  Whether to post-process the optimization database to get results earlier than final step.

  By default it is set to True.

• coupling_variables (Iterable[str] | None) -- The names of the coupling variables.

Return type:

ScalabilityStudy

plot_scalability_results(study_directory)

Plot ScalabilityResult`s generated by a :class:.ScalabilityStudy`.

Parameters:

study_directory (str) -- The directory of the scalability study.

Return type:

PostScalabilityStudy

Scalable MDO problem.

This module implements the concept of scalable problem by means of the ScalableProblem class.

Given

• an MDO scenario based on a set of sampled disciplines with a particular problem dimension,

• a new problem dimension (= number of inputs and outputs),

a scalable problem:

1. makes each discipline scalable based on the new problem dimension,

2. creates the corresponding MDO scenario.

Then, this MDO scenario can be executed and post-processed.

We can repeat this tasks for different sizes of variables and compare the scalability, which is the dependence of the scenario results on the problem dimension.

See also

Discipline, ScalableDiscipline and Scenario

class ScalableProblem(datasets, design_variables, objective_function, eq_constraints=None, ineq_constraints=None, maximize_objective=False, sizes=None, **parameters)

Scalable problem.

Parameters:

• datasets (Iterable[IODataset]) -- One input-output dataset per discipline.

• design_variables (Iterable[str]) -- The names of the design variables.

• objective_function (str) -- The name of the objective.

• eq_constraints (Iterable[str] | None) -- The names of the equality constraints, if any.

• ineq_constraints (Iterable[str] | None) -- The names of the inequality constraints, if any.

• maximize_objective (bool) --

  Whether to maximize the objective.

  By default it is set to False.

• sizes (Mapping[str, int] | None) -- The sizes of the inputs and outputs. If None, use the original sizes.

• **parameters (Any) -- The optional parameters of the scalable model.

create_scenario(formulation_name='DisciplinaryOpt', scenario_type='MDO', start_at_equilibrium=False, active_probability=0.1, feasibility_level=0.5, **formulation_settings)

Create a Scenario from the scalable disciplines.

Parameters:

• formulation_name (str) --

  The MDO formulation to use for the scenario.

  By default it is set to "DisciplinaryOpt".

• scenario_type (str) --

  The type of scenario, either MDO or DOE.

  By default it is set to "MDO".

• start_at_equilibrium (bool) --

  Whether to start at equilibrium using a preliminary MDA.

  By default it is set to False.

• active_probability (float) --

  The probability to set the inequality constraints as active at the initial step of the optimization.

  By default it is set to 0.1.

• feasibility_level (float) --

  The offset of satisfaction for inequality constraints.

  By default it is set to 0.5.

• **formulation_settings (Any) -- The formulation settings.

Returns:

The Scenario from the scalable disciplines.

Return type:

BaseScenario

get_execution_duration(do_sum=True)

Get the total execution time.

Parameters:

do_sum (bool) --

Whether to sum the disciplinary execution times.

By default it is set to True.

Returns:

Either the total execution time or the total execution times per disciplines.

Return type:

float | list[float]

plot_1d_interpolations(save=True, show=False, step=0.01, varnames=None, directory='.', png=False)

Plot 1d interpolations.

Parameters:

• save (bool) --

  Whether to save the figure.

  By default it is set to True.

• show (bool) --

  Whether to display the figure.

  By default it is set to False.

• step (float) --

  The step to evaluate the 1d interpolation function.

  By default it is set to 0.01.

• varnames (Sequence[str] | None) -- The names of the variable to plot. If None, all the variables are plotted.

• directory (Path | str) --

  The directory path.

  By default it is set to ".".

• png (bool) --

  Whether to use PNG file format instead of PDF.

  By default it is set to False.

plot_coupling_graph()

Plot a coupling graph.

Return type:

None

plot_dependencies(save=True, show=False, directory='.')

Plot dependency matrices.

Parameters:

• save (bool) --

  Whether to save the figure.

  By default it is set to True.

• show (bool) --

  Whether to display the figure.

  By default it is set to False.

• directory (str) --

  The directory path.

  By default it is set to ".".

plot_n2_chart(save=True, show=False)

Plot a N2 chart.

Parameters:

• save (bool) --

  Whether to save the figure.

  By default it is set to True.

• show (bool) --

  Whether to display the figure.

  By default it is set to False.

Return type:

None

property is_feasible: bool

Whether the solution is feasible.

property n_calls: dict[str, int]

The number of disciplinary calls per discipline.

property n_calls_linearize: dict[str, int]

The number of disciplinary linearizations per discipline.

property n_calls_linearize_top_level: dict[str, int]

The number of top-level disciplinary linearizations per discipline.

property n_calls_top_level: dict[str, int]

The number of top-level disciplinary calls per discipline.

property status: int

The status of the scenario.

Scalable discipline.

The discipline implements the concept of scalable discipline. This is a particular discipline built from an input-output learning dataset associated with a function and generalizing its behavior to a new user-defined problem dimension, that is to say new user-defined input and output dimensions.

Alone or in interaction with other objects of the same type, a scalable discipline can be used to compare the efficiency of an algorithm applying to disciplines with respect to the problem dimension, e.g. optimization algorithm, surrogate model, MDO formulation, MDA, ...

The ScalableDiscipline class implements this concept. It inherits from the Discipline class in such a way that it can easily be used in a Scenario. It is composed of a ScalableModel.

The user only needs to provide:

• the name of a class overloading ScalableModel,

• a dataset as an Dataset

• variables sizes as a dictionary whose keys are the names of inputs and outputs and values are their new sizes. If a variable is missing, its original size is considered.

The ScalableModel parameters can also be filled in, otherwise the model uses default values.

class ScalableDiscipline(name, data, sizes=mappingproxy({}), **parameters)

A scalable discipline.

Initialize self. See help(type(self)) for accurate signature.

Parameters:

• name (str) -- The name of the class of the scalable model.

• data (IODataset) -- The learning dataset.

• sizes (Mapping[str, int]) --

  The sizes of the input and output variables. If empty, use the original sizes.

  By default it is set to {}.

• **parameters (Any) -- The parameters for the model.

A factory of scalable models.

class ScalableModelFactory

A factory of scalable models.

Return type:

Any

Scalable model.

This module implements the abstract concept of scalable model which is used by scalable disciplines. A scalable model is built from an input-output learning dataset associated with a function and generalizing its behavior to a new user-defined problem dimension, that is to say new user-defined input and output dimensions.

The concept of scalable model is implemented through ScalableModel, an abstract class which is instantiated from:

• data provided as a Dataset

• variables sizes provided as a dictionary whose keys are the names of inputs and outputs and values are their new sizes. If a variable is missing, its original size is considered.

Scalable model parameters can also be filled in. Otherwise, the model uses default values.

See also

The ScalableDiagonalModel class overloads ScalableModel.

class ScalableModel(data, sizes=mappingproxy({}), **parameters)

A scalable model.

Parameters:

• data (IODataset) -- The learning dataset.

• sizes (Mapping[str, int]) --

  The sizes of the input and output variables. If empty, use the original sizes.

  By default it is set to {}.

• **parameters (Any) -- The parameters of the model.

build_model()

Build model with original sizes for input and output variables.

Return type:

None

compute_bounds()

Compute lower and upper bounds of both input and output variables.

Returns:

The lower and upper bounds.

Return type:

tuple[dict[str, int], dict[str, int]]

normalize_data()

Normalize the dataset from lower and upper bounds.

Return type:

None

scalable_derivatives(input_value=None)

Evaluate the scalable derivatives.

Parameters:

input_value -- The input values. If None, use the default inputs.

Returns:

The evaluations of the scalable derivatives.

Return type:

None

scalable_function(input_value=None)

Evaluate the scalable function.

Parameters:

input_value -- The input values. If None, use the default inputs.

Returns:

The evaluations of the scalable function.

Return type:

None

data: IODataset

The learning dataset.

property input_names: list[str]

The input names.

property original_sizes: Mapping[str, int]

The original sizes of variables.

property output_names: list[str]

The output names.

Scalable diagonal model.

This module implements the concept of scalable diagonal model, which is a particular scalable model built from an input-output dataset relying on a diagonal design of experiments (DOE) where inputs vary proportionally from their lower bounds to their upper bounds, following the diagonal of the input space.

So for every output, the dataset catches its evolution with respect to this proportion, which makes it a mono dimensional behavior. Then, for a new user-defined problem dimension, the scalable model extrapolates this mono dimensional behavior to the different input directions.

The concept of scalable diagonal model is implemented through the ScalableDiagonalModel class which is composed of a ScalableDiagonalApproximation. With regard to the diagonal DOE, GEMSEO proposes the DiagonalDOE class.

class ScalableDiagonalApproximation(sizes, output_dependency, io_dependency)

Methodology that captures the trends of a physical problem.

It also extends it into a problem that has scalable input and outputs dimensions. The original and the resulting scalable problem have the same interface:

all inputs and outputs have the same names; only their dimensions vary.

Parameters:

• sizes (Mapping[str, int]) -- The sizes of the inputs and outputs.

• output_dependency -- The dependency between the original and new outputs.

• io_dependency -- The dependency between the new inputs and outputs.

build_scalable_function(function_name, dataset, input_names, degree=3)

Create the interpolation functions for a specific output.

Parameters:

• function_name (str) -- The name of the output.

• dataset (IODataset) -- The input-output dataset.

• input_names (Iterable[str]) -- The names of the inputs.

• degree (int) --

  The degree of interpolation.

  By default it is set to 3.

Returns:

The input and output samples scaled in [0, 1].

Return type:

tuple[list[NDArray[float]], NDArray[float]]

get_scalable_derivative(output_function)

Return the function computing the derivatives of an output.

Parameters:

output_function (str) -- The name of the output.

Returns:

The function computing the derivatives of this output.

Return type:

Callable[[Iterable[float]], NDArray[float]]

get_scalable_function(output_function)

Return the function computing an output.

Parameters:

output_function (str) -- The name of the output.

Returns:

The function computing the output.

Return type:

Callable[[Iterable[float]], NDArray[float]]

static scale_samples(samples)

Scale array samples into [0, 1].

Parameters:

samples (Iterable[NDArray[float]]) -- The samples.

Returns:

The samples with components scaled in [0, 1].

Return type:

NDArray[float]

class ScalableDiagonalModel(data, sizes=mappingproxy({}), fill_factor=-1, comp_dep=None, inpt_dep=None, force_input_dependency=False, allow_unused_inputs=True, seed=0, group_dep=mappingproxy({}))

Scalable diagonal model.

Parameters:

• data (IODataset) -- The learning dataset.

• sizes (Mapping[str, int]) --

  The sizes of the input and output variables. If empty, use the original sizes.

  By default it is set to {}.

• fill_factor (float) --

  The degree of sparsity of the dependency matrix.

  By default it is set to -1.

• comp_dep (NDArray[float] | None) -- The matrix defining the selection of a single original component for each scalable component. If None, generate a random matrix.

• inpt_dep (NDArray[float] | None) -- The input-output dependency matrix. If None, generate a random matrix.

• force_input_dependency (bool) --

  Whether to force the dependency of each output with at least one input.

  By default it is set to False.

• allow_unused_inputs (bool) --

  The description is missing.

  By default it is set to True.

• seed (int) --

  The seed for reproducible results.

  By default it is set to 0.

• group_dep (Mapping[str, Iterable[str]]) --

  The dependency between the inputs and outputs.

  By default it is set to {}.

build_model()

Build the model with the original sizes for input and output variables.

Returns:

The scalable approximation.

Return type:

ScalableDiagonalApproximation

generate_random_dependency()

Generate a random dependency structure for use in scalable discipline.

Returns:

The dependency structure.

Return type:

tuple[dict[str, NDArray[int]], dict[str, dict[str, NDArray[float]]]]

plot_1d_interpolations(save=False, show=False, step=0.01, varnames=None, directory='.', png=False)

Plot the scaled 1D interpolations, a.k.a. the basis functions.

A basis function is a mono dimensional function interpolating the samples of a given output component over the input sampling line \(t\in[0,1]\mapsto \\underline{x}+t(\overline{x}-\\underline{x})\).

There are as many basis functions as there are output components from the discipline. Thus, for a discipline with a single output in dimension 1, there is 1 basis function. For a discipline with a single output in dimension 2, there are 2 basis functions. For a discipline with an output in dimension 2 and an output in dimension 13, there are 15 basis functions. And so on. This method allows to plot the basis functions associated with all outputs or only part of them, either on screen (show=True), in a file (save=True) or both. We can also specify the discretization step whose default value is 0.01.

Parameters:

• save (bool) --

  Whether to save the figure.

  By default it is set to False.

• show (bool) --

  Whether to display the figure.

  By default it is set to False.

• step (float) --

  The step to evaluate the 1d interpolation function.

  By default it is set to 0.01.

• varnames (Sequence[str] | None) -- The names of the variable to plot. If None, all the variables are plotted.

• directory (str) --

  The directory path.

  By default it is set to ".".

• png (bool) --

  Whether to use PNG file format instead of PDF.

  By default it is set to False.

Returns:

The names of the files.

Return type:

list[str]

plot_dependency(add_levels=True, save=True, show=False, directory='.', png=False)

Plot the dependency matrix of a discipline in the form of a chessboard.

The rows represent inputs, columns represent output and gray scale represents the dependency level between inputs and outputs.

Parameters:

• add_levels (bool) --

  Whether to add the dependency levels in percentage.

  By default it is set to True.

• save (bool) --

  Whether to save the figure.

  By default it is set to True.

• show (bool) --

  Whether to display the figure.

  By default it is set to False.

• directory (str) --

  The directory path.

  By default it is set to ".".

• png (bool) --

  Whether to use PNG file format instead of PDF.

  By default it is set to False.

Return type:

str

scalable_derivatives(input_value=None)

Compute the derivatives.

Parameters:

input_value (Mapping[str, NDArray[float]] | None) -- The input values.

Returns:

The values of the derivatives.

Return type:

dict[str, NDArray[float]]

scalable_function(input_value=None)

Compute the outputs.

Parameters:

input_value (Mapping[str, NDArray[float]] | None) -- The input values.

Returns:

The values of the outputs.

Return type:

dict[str, NDArray[float]]

data: IODataset

The learning dataset.