gemseo / problems / scalable

api module

Benchmark MDO formulations based on scalable disciplines

The api implements several classes to benchmark MDO formulations based on scalable disciplines.

The 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 AbstractFullCache 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 depends 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.

The PostScalabilityStudy class implements the way as the set of ScalabilityResult-based result files contained in the study directory are graphically post-processed. This class provides several methods to easily change graphical properties, notably the plot labels. It also makes it possible to define a cost function per MDO formulation, converting the numbers of executions and linearizations of the different disciplines required by a MDO process in an estimation of the computational cost associated with what would be a scaled version of the true problem.

Warning

Comparing MDO formulations in terms of estimated true computational time rather than CPU time of the ScalabilityStudy is highly recommended. Indeed, time is often an obviousness criterion to distinguish between MDO formulations having the same performance in terms of distance to the optimum: look at our calculation budget and choose the best formulation that satisfies this budget, or even saves us time. Thus, it is important to carefully define these cost functions.

class gemseo.problems.scalable.api.PostScalabilityStudy(study_directory)[source]

Bases: object

The PostScalabilityStudy class aims to post-process a list of scalability results stored in a directory.

Constructor.

Parameters

study (str) – directory of the scalability study.”

NOMENCLATURE = {'exec_time': 'Execution time (s)', 'is_feasible': 'Feasibility of the solution (0 or 1)', 'n_calls': 'Number of discipline evaluations', 'n_calls_linearize': 'Number of gradient evaluations', 'original_exec_time': 'Pseudo-original execution time', 'scaling_strategy': 'Scaling strategy index', 'status': 'Optimizatin status', 'total_calls': 'Total number of evaluations'}
get_optimization_strategies(unique=False)[source]

Get the names of the optimization strategies.

Parameters

unique (bool) – return either unique values if True or one value per scalability result if False (default: False).

Returns

names of the optimization stategies.

Return type

list(str)

get_replicates(unique=False)[source]

Get the replicate identifiants.

Parameters

unique (bool) – return either unique values if True or one value per scalability result if False (default: False).

Returns

identifiants of replicates.

Return type

list(int)

get_scaling_strategies(unique=False)[source]

Get the identificants of the scaling strategies.

Parameters

unique (bool) – return either unique values if True or one value per scalability result if False (default: False).

Returns

identifiants of scaling strategies

Return type

list(int)

labelize_exec_time(description)[source]

Change the description of execution time, used in plotting methods notably.

Parameters

description (str) – description.

labelize_is_feasible(description)[source]

Change the description of feasibility, used in plotting methods notably.

Parameters

description (str) – description.

labelize_n_calls(description)[source]

Change the description of number of calls, used in plotting methods notably.

Parameters

description (str) – description.

labelize_n_calls_linearize(description)[source]

Change the description of number of calls for linearization, used in plotting methods notably.

Parameters

description (str) – description.

labelize_original_exec_time(description)[source]

Change the description of original execution time, used in plotting methods notably.

Parameters

description (str) – description.

labelize_scaling_strategy(description)[source]

Change the description of scaling strategy, used in plotting methods notably.

Parameters

description (str) – description.

labelize_status(description)[source]

Change the description of status, used in plotting methods notably.

Parameters

description (str) – description.

property n_samples

Number of samples

property names

Get the names of the scalability results.

plot(legend_loc='upper left', xticks=None, xticks_labels=None, xmargin=0.0, **options)[source]

Plot the results using different methods according to the presence or absence of replicate values.

Parameters

  • legend_loc (str) – legend localization

  • xticks (list(float)) – list of xticks (default: None)

  • xticks_labels (list(str)) – list of xticks labels (default: None)

  • xmargin (float) – margin on left and right sides of the x-axis

  • options – options for the specialized plot methods

set_cost_function(formulation, cost)[source]

Set cost function for each formulation.

Parameters

  • formulation (str) – name of the formulation.

  • cost (function) – cost function

set_cost_unit(cost_unit)[source]

Set the measurement unit for cost evaluation.

Parameters

cost_unit (str) – cost unit, e.g. ‘h’, ‘min’, …

class gemseo.problems.scalable.api.ScalabilityResult(name, id_scaling, id_sample)[source]

Bases: object

Scalability Result.

Constructor.

Parameters

  • name (str) – name of the scalability result.

  • id_scaling (int) – scaling identifiant

  • id_sample (int) – sample identifiant

get(algo, algo_options, formulation, formulation_options, scaling, n_calls, n_calls_linearize, n_calls_top_level, n_calls_linearize_top_level, exec_time, status, is_feasible, disc_names, output_names, old_varsizes, new_varsizes)[source]

Get a scalability result for a given optimization strategy and a given scaling strategy.

Parameters

  • algo (str) – name of the optimization algorithm

  • algo_options (dict) – options of the optimization algorithm

  • formulation (str) – name of the MDO formulation

  • formulation_options (dict) – options of the MDO formulation

  • scaling – scaling strategy

  • n_calls (list(int)) – number of calls for each discipline

  • n_calls_linearize (list(int)) – number of linearization for each discipline

  • n_calls_top_level (list(int)) – number of calls for each discipline

  • n_calls_linearize_top_level (list(int)) – number of linearization for each discipline

  • exec_time (float) – execution time

  • status (int) – status of the optimization scenario

  • is_feasible (bool) – feasibility of the optimization solution

  • disc_names (list(str)) – list of discipline names

  • output_names (dict) – list of output names

  • old_varsizes (dict) – old variable sizes

  • new_varsizes (dict) – new variable sizes

load(study_directory)[source]

Load a scalability result from a pickle file whose name is the name of the ScalabilityResult instance.

save(study_directory)[source]

Save a scalability result into a pickle file whose name is the name of the ScalabilityResult instance.

class gemseo.problems.scalable.api.ScalabilityStudy(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)[source]

Bases: object

Scalability Study.

The constructor of the ScalabilityStudy class 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) – name of the objective

  • design_variables (list(str)) – names of the design variables

  • directory (str) – working directory of the study. Default: ‘study’.

  • prefix (str) – prefix for the output filenames. Default: ‘’.

  • eq_constraints (list(str)) – names of the equality constraints. Default: None.

  • ineq_constraints (list(str)) – names of the inequality constraints Default: None.

  • maximize_objective (bool) – maximizing objective. Default: False.

  • fill_factor (float) – default fill factor of the input-output dependency matrix. Default: 0.7.

  • active_probability (float) – probability to set the inequality constraints as active at initial step of the optimization. Default: 0.1

  • feasibility_level (float) – offset of satisfaction for inequality constraints. Default: 0.8.

  • start_at_equilibrium (bool) – start at equilibrium using a preliminary MDA. Default: True.

  • early_stopping (bool) – post-process the optimization database to get results earlier than final step.

add_discipline(name, data)[source]

This method adds a disciplinary dataset from:

  • its name,

  • its data,

Parameters

  • name (str) – name of the discipline.

  • data (AbstractFullCache) – dataset provided as a cache.

add_optimization_strategy(algo, max_iter, formulation='DisciplinaryOpt', algo_options=None, formulation_options=None, top_level_diff='auto')[source]

Add both optimization algorithm and MDO formulation, as well as their options.

Parameters

  • algo (str) – name of the optimization algorithm.

  • max_iter (int) – maximum number of iterations for the optimization algorithm.

  • formulation (str) – name of the MDO formulation. Default: ‘DisciplinaryOpt’.

  • algo_options (dict) – options of the optimization algorithm.

  • formulation_options (dict) – options of the MDO formulation.

  • top_level_diff (str) – differentiation method for the top level disciplines. Default: ‘auto’.

add_scaling_strategies(design_size=None, coupling_size=None, eq_cstr_size=None, ineq_cstr_size=None, variables=None)[source]

Add different scaling strategies.

Parameters

  • design_size (int or list(int)) – size of the design variables. Default: None.

  • coupling_size (int or list(int)) – size of the coupling variables. Default: None.

  • eq_cstr_size (int or list(int)) – size of the equality constraints. Default: None.

  • ineq_cstr_size (int or list(int)) – size of the inequality constraints. Default: None.

property disciplines_names

Get discipline names.

Returns

list of discipline names

Return type

list(str)

execute(n_replicates=1)[source]

Execute the scalability study, one or several times to take into account the random features of the scalable problems.

Parameters

n_replicates (int) – number of times the scalability study is repeated. Default: 1.

print_optimization_strategies()[source]

Print the list of the optimization strategies.

print_scaling_strategies()[source]

Print the list of the scaling strategies.

set_early_stopping()[source]

Enable early stopping.

set_fill_factor(discipline, output, fill_factor)[source]
Parameters

  • discipline (str) – name of the discipline

  • output (str) – name of the output function

  • fill_factor (float) – fill factor

set_input_output_dependency(discipline, output, inputs)[source]

Set the dependency between an output and a set of inputs for a given discipline.

Parameters

  • discipline (str) – name of the discipline

  • output (str) – name of the output

  • inputs (list(str)) – list of inputs names

unset_early_stopping()[source]

Disable early stopping.