gemseo.formulations.bilevel module#

A BiLevel formulation.

class BiLevel(disciplines, objective_name, design_space, settings_model=None, **settings)[source]#

Bases: BaseMDOFormulation

A BiLevel 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 BiLevel 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.

The residual norm of MDA1 and MDA2 can be captured into scenario observables thanks to different namespaces BiLevel.MDA1_RESIDUAL_NAMESPACE and BiLevel.MDA2_RESIDUAL_NAMESPACE.

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

Parameters:

  • disciplines (Sequence[Discipline]) -- 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.

  • settings_model (BiLevel_Settings | None) -- The settings of the formulation as a Pydantic model. If None, use **settings.

  • **settings (Any) -- The settings of the formulation. This argument is ignored when settings_model is not None.

Settings#

alias of BiLevel_Settings

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

ValueError -- When the MDA name is not provided.

Parameters:

options (str)

Return type:

StrKeyMapping

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

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

get_top_level_disciplines(include_sub_formulations=False)[source]#

Return the top level disciplines that are executed in the foreground.

A formulation structures the optimization problem into multiple levels of disciplines. The top level disciplines map from the design_space to the objective, constraint and observable spaces. They can be composed of both user disciplines and process disciplines added by the formulation, e.g. MDOChain. These process disciplines may also include both user disciplines and process disciplines, and so on.

Parameters:

include_sub_formulations (bool) --

Whether to include the top level disciplines of the formulations that make up the current one.

By default it is set to False.

Returns:

The top level disciplines.

Return type:

tuple[Discipline, ...]

CHAIN_NAME: ClassVar[str] = 'bilevel_chain'#

The name of the internal chain.

DEFAULT_SCENARIO_RESULT_CLASS_NAME: ClassVar[str] = 'BiLevelScenarioResult'#

The default name of the scenario results.

LEVELS = ('system', 'sub-scenarios')#

The collection of levels.

MDA1_RESIDUAL_NAMESPACE: ClassVar[str] = 'MDA1'#

The name of the namespace for the MDA1 residuals.

MDA2_RESIDUAL_NAMESPACE: ClassVar[str] = 'MDA2'#

The name of the namespace for the MDA2 residuals.

SUBSCENARIOS_LEVEL: ClassVar[str] = 'sub-scenarios'#

The name of the sub-scenarios level.

SYSTEM_LEVEL: ClassVar[str] = 'system'#

The name of the system level.

chain: MDOChain#

The chain of the inner problem of the BiLevel formulation (MDA1 -> sub-scenarios -> MDA2)

coupling_structure: CouplingStructure#

The coupling structure between the involved disciplines.

property mda1: BaseMDA | None#

The MDA1 instance.

property mda2: BaseMDA#

The MDA2 instance.

property scenario_adapters: list[MDOScenarioAdapter]#

All the adapters that wrap sub-scenarios.