gemseo / formulations

# bilevel module¶

A Bi-level formulation.

Classes:

 BiLevel(disciplines, objective_name, …[, …]) A bi-level formulation.
class gemseo.formulations.bilevel.BiLevel(disciplines, objective_name, design_space, maximize_objective=False, mda_name='MDAChain', parallel_scenarios=False, multithread_scenarios=True, apply_cstr_tosub_scenarios=True, apply_cstr_to_system=True, reset_x0_before_opt=False, **mda_options)[source]

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.

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

Parameters
• disciplines (Sequence[MDODiscipline]) – The disciplines.

• objective_name (str) – The name of the objective function.

• design_space (DesignSpace) – The design space.

• maximize_objective (bool) – If True, the objective function is maximized.

• **options – The options of the formulation.

• mda_name (str) – The name of the MDA class to be used.

• parallel_scenarios (bool) – If True, the sub-scenarios are run in parallel.

• 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, multi-processing is used.

• apply_cstr_tosub_scenarios (bool) – If True, the add_constraint() method adds the constraint to the optimization problem of the sub-scenario capable of computing the constraint.

• apply_cstr_to_system (bool) – If True, the add_constraint() method adds the constraint to the optimization problem of the system scenario.

• reset_x0_before_opt (bool) – If True, restart the sub optimizations from the initial guesses, otherwise warm start them.

• **mda_options – The options passed to the MDA at construction.

• mda_options (Any) –

Return type

None

Attributes:

 LEVELS NAME SUBSCENARIOS_LEVEL SYSTEM_LEVEL design_space The design space on which the formulation is applied.

Methods:

 add_constraint(output_name[, …]) Add a constraint to the formulation. add_observable(output_names[, …]) Add an observable to the optimization problem. check_disciplines(disciplines) Check that the disciplines are provided as a list. get_default_sub_options_values(**options) Get the default values of the sub-options of the formulation. Get the expected data exchange sequence. Get the expected sequence of execution of the disciplines. Get the optimization unknown names to be provided to the optimizer. Accessor to the sub-disciplines. get_sub_options_grammar(**options) Get the sub-options grammar. List the disciplines that are actually scenarios. Return the disciplines which inputs are required to run the scenario. get_x_names_of_disc(discipline) Get the design variables names of a given discipline. mask_x(masking_data_names, x_vect[, …]) Mask a vector from a subset of names, with respect to a set of names. mask_x_swap_order(masking_data_names, x_vect) Mask a vector from a subset of names, with respect to a set of names. unmask_x(masking_data_names, x_masked[, …]) Unmask a vector from a subset of names, with respect to a set of names. unmask_x_swap_order(masking_data_names, x_masked) Unmask a vector from a subset of names, with respect to a set of names.
LEVELS = ('system', 'sub-scenarios')
NAME = 'MDOFormulation'
SUBSCENARIOS_LEVEL = 'sub-scenarios'
SYSTEM_LEVEL = 'system'
add_constraint(output_name, constraint_type='eq', constraint_name=None, value=None, positive=False, levels=None)[source]

Add a constraint to the formulation.

Parameters
• output_name (str) – The name of the output to be used as a constraint. For instance, if g_1 is given and constraint_type=”eq”, g_1=0 will be added as a constraint to the optimizer.

• constraint_type (str) – The type of constraint, either “eq” for equality constraint or “ineq” for inequality constraint.

• constraint_name (Optional[str]) – The name of the constraint to be stored, If None, the name is generated from the output name.

• value (Optional[float]) – The value of activation of the constraint. If None, the value is equal to 0.

• positive (bool) – If True, the inequality constraint is positive.

• levels (Optional[List[str]]) – The levels at which the constraint is to be added (sublist of Bilevel.LEVELS). By default the policy set at the initialization of the formulation is enforced.

Return type

None

Add an observable to the optimization problem.

The repartition strategy of the observable is defined in the formulation class.

Parameters
• output_names (Union[str, Sequence[str]]) – The name(s) of the output(s) to observe.

• observable_name (Optional[str]) – The name of the observable.

• discipline (Optional[gemseo.core.discipline.MDODiscipline]) – The discipline computing the observed outputs. If None, the discipline is detected from inner disciplines.

Return type

None

static check_disciplines(disciplines)

Check that the disciplines are provided as a list.

Parameters

disciplines (Any) – The disciplines.

Return type

None

property design_space

The design space on which the formulation is applied.

classmethod get_default_sub_options_values(**options)[source]

Get the default values of the sub-options of the formulation.

When some options of the formulation depend on higher level options, the default values of these sub-options may be obtained here, mainly for use in the API.

Parameters
• **options – The options required to deduce the sub-options grammar.

• options (str) –

Returns

Either None or the sub-options default values.

Return type

Optional[Dict[str, Optional[Union[bool, int, float, str]]]]

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[gemseo.core.discipline.MDODiscipline, gemseo.core.discipline.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]]

get_optim_variables_names()

Get the optimization unknown names to be provided to the optimizer.

This is different from the design variable names provided by the user, since it depends on the formulation, and can include target values for coupling for instance in IDF.

Returns

The optimization variable names.

Return type

List[str]

get_sub_disciplines()

Accessor to the sub-disciplines.

This method lists the sub scenarios’ disciplines.

Returns

The sub-disciplines.

Return type
classmethod get_sub_options_grammar(**options)[source]

Get the sub-options grammar.

When some options of the formulation depend on higher level options, the schema of the sub-options may be obtained here, mainly for use in the API.

Parameters
• **options – The options required to deduce the sub-options grammar.

• options (str) –

Returns

Either None or the sub-options grammar.

Return type

gemseo.core.grammars.json_grammar.JSONGrammar

get_sub_scenarios()

List the disciplines that are actually scenarios.

Returns

The scenarios.

Return type

List[Scenario]

get_top_level_disc()[source]

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

A formulation seeks to evaluate objective function and constraints from inputs. 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
get_x_names_of_disc(discipline)

Get the design variables names of a given discipline.

Parameters

discipline (gemseo.core.discipline.MDODiscipline) – The discipline.

Returns

The names of the design variables.

Return type

List[str]

Mask a vector from a subset of names, with respect to a set of names.

Parameters
• masking_data_names (Iterable[str]) – The names of data to keep.

• x_vect (numpy.ndarray) – The vector of float to mask.

• all_data_names (Optional[Iterable[str]]) – The set of all names. If None, use the design variables stored in the design space.

Returns

A boolean mask with the same shape as the input vector.

Return type

numpy.ndarray

Mask a vector from a subset of names, with respect to a set of names.

This method eventually swaps the order of the values if the order of the data names is inconsistent between these sets.

Parameters
• masking_data_names (Iterable[str]) – The names of the kept data.

• x_vect (numpy.ndarray) – The vector to mask.

• all_data_names (Optional[Iterable[str]]) – The set of all names. If None, use the design variables stored in the design space.

Returns

The masked version of the input vector.

Return type

numpy.ndarray

Unmask a vector from a subset of names, with respect to a set of names.

Parameters
• masking_data_names (Iterable[str]) – The names of the kept data.

• all_data_names (Optional[Iterable[str]]) – The set of all names. If None, use the design variables stored in the design space.

• x_full (Optional[numpy.ndarray]) – The default values for the full vector. If None, use the zero vector.

Returns

The vector related to the input mask.

Return type

numpy.ndarray

Unmask a vector from a subset of names, with respect to a set of names.

This method eventually swaps the order of the values if the order of the data names is inconsistent between these sets.

Parameters
• masking_data_names (Iterable[str]) – The names of the kept data.

• all_data_names (Optional[Iterable[str]]) – The set of all names. If None, use the design variables stored in the design space.

• x_full (Optional[numpy.ndarray]) – The default values for the full vector. If None, use the zero vector.

Returns

The vector related to the input mask.

Return type

numpy.ndarray