gemseo / formulations

Show inherited members

bilevel module

A Bi-level formulation.

class gemseo.formulations.bilevel.BiLevel(disciplines, objective_name, design_space, maximize_objective=False, main_mda_name='MDAChain', inner_mda_name='MDAJacobi', parallel_scenarios=False, multithread_scenarios=True, apply_cstr_tosub_scenarios=True, apply_cstr_to_system=True, reset_x0_before_opt=False, grammar_type=GrammarType.JSON, sub_scenarios_log_level=None, differentiated_input_names_substitute=(), **main_mda_options)[source]

Bases: BaseMDOFormulation

A bi-level formulation.

This formulation draws an optimization architecture that involves multiple optimization problems to be solved to obtain the solution of the MDO problem.

Here, at each iteration on the global design variables, the bi-level MDO formulation implementation performs:

  1. a first MDA to compute the coupling variables,

  2. several disciplinary optimizations on the local design variables in parallel,

  3. a second MDA to update the coupling variables.

Parameters:

  • disciplines (list[MDODiscipline]) – The disciplines.

  • objective_name (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 design space.

  • maximize_objective (bool) –

    Whether to maximize the objective.

    By default it is set to False.

  • main_mda_name (str) –

    The name of the class used for the main MDA, typically the MDAChain, but one can force to use MDAGaussSeidel for instance.

    By default it is set to “MDAChain”.

  • inner_mda_name (str) –

    The name of the class used for the inner-MDA of the main MDA, if any; typically when the main MDA is an MDAChain.

    By default it is set to “MDAJacobi”.

  • parallel_scenarios (bool) –

    Whether to run the sub-scenarios in parallel.

    By default it is set to False.

  • multithread_scenarios (bool) –

    If True and parallel_scenarios=True, the sub-scenarios are run in parallel using multi-threading; if False and parallel_scenarios=True, multiprocessing is used.

    By default it is set to True.

  • apply_cstr_tosub_scenarios (bool) –

    Whether the add_constraint() method adds the constraint to the optimization problem of the sub-scenario capable of computing the constraint.

    By default it is set to True.

  • apply_cstr_to_system (bool) –

    Whether the add_constraint() method adds the constraint to the optimization problem of the system scenario.

    By default it is set to True.

  • reset_x0_before_opt (bool) –

    Whether to restart the sub optimizations from the initial guesses, otherwise warm start them.

    By default it is set to False.

  • grammar_type (MDODiscipline.GrammarType) –

    The type of the input and output grammars.

    By default it is set to “JSONGrammar”.

  • sub_scenarios_log_level (int | None) – The level of the root logger during the sub-scenarios executions. If None, do not change the level of the root logger.

  • differentiated_input_names_substitute (Iterable[str]) –

    The names of the discipline inputs against which to differentiate the discipline outputs used as objective, constraints and observables. If empty, consider the inputs of these functions. More precisely, for each function, an MDOFunction is built from the disciplines, which depend on input variables \(x_1,\ldots,x_d,x_{d+1}\), and over an input space spanned by the input variables \(x_1,\ldots,x_d\) and depending on both the MDO formulation and the design_space. Then, the methods MDOFunction.evaluate() and MDOFunction.jac() are called at a given point of the input space and return the output value and the Jacobian matrix, i.e. the matrix concatenating the partial derivatives with respect to the inputs \(x_1,\ldots,x_d\) at this point of the input space. This argument can be used to compute the matrix concatenating the partial derivatives at the same point of the input space but with respect to custom inputs, e.g. \(x_{d-1}\) and \(x_{d+1}\). Mathematically speaking, this matrix returned by MDOFunction.jac() is no longer a Jacobian.

    By default it is set to ().

  • **main_mda_options (Any) – The options of the main MDA, which may include those of the inner-MDA.

add_constraint(output_name, constraint_type=ConstraintType.EQ, constraint_name='', value=0, positive=False, levels=())[source]

Add a constraint to the formulation.

Parameters:

  • output_name (str) – The name(s) of the outputs computed by \(c(x)\). If several names are given, a single discipline must provide all outputs.

  • constraint_type (ConstraintType) –

    The type of constraint.

    By default it is set to “eq”.

  • constraint_name (str) –

    The name of the constraint to be stored. If empty, the name of the constraint is generated from output_name, constraint_type, value and positive.

    By default it is set to “”.

  • value (float) –

    The value \(a\).

    By default it is set to 0.

  • positive (bool) –

    Whether the inequality constraint is positive.

    By default it is set to False.

  • levels (list[str]) –

    The levels at which the constraint is to be added (sublist of LEVELS). By default, the policy set at the initialization of the formulation is enforced.

    By default it is set to ().

Raises:

ValueError – When the constraint levels are not a sublist of BiLevel.LEVELS.

Return type:

None

classmethod get_default_sub_option_values(**options)[source]
Raises:

ValueError – When the MDA name is not provided.

Parameters:

options (str)

Return type:

StrKeyMapping

get_expected_dataflow()[source]

Get the expected data exchange sequence.

This method is used for the XDSM representation and can be overloaded by subclasses.

Returns:

The expected sequence of data exchange where the i-th item is described by the starting discipline, the ending discipline and the coupling variables.

Return type:

list[tuple[MDODiscipline, MDODiscipline, list[str]]]

get_expected_workflow()[source]

Get the expected sequence of execution of the disciplines.

This method is used for the XDSM representation and can be overloaded by subclasses.

For instance:

  • [A, B] denotes the execution of A, then the execution of B

  • (A, B) denotes the concurrent execution of A and B

  • [A, (B, C), D] denotes the execution of A, then the concurrent execution of B and C, then the execution of D.

Returns:

A sequence of elements which are either an ExecutionSequence or a tuple of ExecutionSequence for concurrent execution.

Return type:

list[ExecutionSequence, tuple[ExecutionSequence]]

classmethod get_sub_options_grammar(**options)[source]

Return the grammar of the selected MDA.

Parameters:

**options (str) – The options of the BiLevel formulation.

Returns:

The MDA grammar.

Raises:

ValueError – When the MDA name is not provided.

Return type:

JSONGrammar

get_top_level_disc()[source]

Return the disciplines which inputs are required to run the scenario.

A formulation seeks to compute the objective and constraints from the input variables. It structures the optimization problem into multiple levels of disciplines. The disciplines directly depending on these inputs are called top level disciplines.

By default, this method returns all disciplines. This method can be overloaded by subclasses.

Returns:

The top level disciplines.

Return type:

list[MDODiscipline]

DEFAULT_SCENARIO_RESULT_CLASS_NAME: ClassVar[str] = 'BiLevelScenarioResult'

The name of the ScenarioResult class to be used for post-processing.

LEVELS = ('system', 'sub-scenarios')
SUBSCENARIOS_LEVEL = 'sub-scenarios'
SYSTEM_LEVEL = 'system'
property mda1: MDODiscipline

The MDA1 instance.

property mda2: MDODiscipline

The MDA2 instance.

optimization_problem: OptimizationProblem

The optimization problem generated by the formulation from the disciplines.

variable_sizes: dict[str, int]

The sizes of the design variables and differentiated inputs substitutes.