bilevel module¶
A Bilevel formulation.
Classes:

A bilevel 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, grammar_type='JSONGrammar', **mda_options)[source]¶
Bases:
gemseo.core.formulation.MDOFormulation
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:
a first MDA to compute the coupling variables,
several disciplinary optimizations on the local design variables in parallel,
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.
By default it is set to False.
mda_name (str) –
The name of the MDA class to be used.
By default it is set to MDAChain.
parallel_scenarios (bool) –
Whether to run the subscenarios in parallel.
By default it is set to False.
multithread_scenarios (bool) –
If True and parallel_scenarios=True, the subscenarios are run in parallel using multithreading; 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 subscenario 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 (str) –
The type of the input and output grammars, either
MDODiscipline.JSON_GRAMMAR_TYPE
orMDODiscipline.SIMPLE_GRAMMAR_TYPE
.By default it is set to JSONGrammar.
**mda_options (Any) – The options passed to the MDA at construction.
 Return type
None
Attributes:
The design space on which the formulation is applied.
The MDA1 instance.
The MDA2 instance.
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)Return the options value of the selected MDA.
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 subdisciplines.
get_sub_options_grammar
(**options)Return the grammar of the selected MDA.
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', 'subscenarios')¶
 NAME = 'MDOFormulation'¶
 SUBSCENARIOS_LEVEL = 'subscenarios'¶
 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.
By default it is set to eq.
constraint_name (Optional[str]) –
The name of the constraint to be stored, If None, the name is generated from the output name.
By default it is set to None.
value (Optional[float]) –
The value of activation of the constraint. If None, the value is equal to 0.
By default it is set to None.
positive (bool) –
If True, the inequality constraint is positive.
By default it is set to False.
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.
By default it is set to None.
 Raises
ValueError – When the constraint levels are not a sublist of BiLevel.LEVELS.
 Return type
None
 add_observable(output_names, observable_name=None, discipline=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.
By default it is set to None.
discipline (Optional[gemseo.core.discipline.MDODiscipline]) –
The discipline computing the observed outputs. If None, the discipline is detected from inner disciplines.
By default it is set to None.
 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]¶
Return the options value of the selected MDA.
 Parameters
**options (str) – The options of the BiLevel formulation.
 Returns
The MDA options values.
 Raises
ValueError – When the MDA name is not provided.
 Return type
Optional[Mapping[str, Optional[Union[str, int, float, bool]]]]
 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 ith 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 ofExecutionSequence
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 subdisciplines.
This method lists the sub scenarios’ disciplines.
 Returns
The subdisciplines.
 Return type
 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
 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_x(masking_data_names, x_vect, all_data_names=None)¶
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.
By default it is set to None.
 Returns
A boolean mask with the same shape as the input vector.
 Return type
numpy.ndarray
 mask_x_swap_order(masking_data_names, x_vect, all_data_names=None)¶
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.
By default it is set to None.
 Returns
The masked version of the input vector.
 Return type
numpy.ndarray
 property mda1¶
The MDA1 instance.
 property mda2¶
The MDA2 instance.
 unmask_x(masking_data_names, x_masked, all_data_names=None, x_full=None)¶
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.
x_masked (numpy.ndarray) – The boolean vector to unmask.
all_data_names (Optional[Iterable[str]]) –
The set of all names. If None, use the design variables stored in the design space.
By default it is set to None.
x_full (Optional[numpy.ndarray]) –
The default values for the full vector. If None, use the zero vector.
By default it is set to None.
 Returns
The vector related to the input mask.
 Return type
numpy.ndarray
 unmask_x_swap_order(masking_data_names, x_masked, all_data_names=None, x_full=None)¶
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.
x_masked (numpy.ndarray) – The boolean vector to unmask.
all_data_names (Optional[Iterable[str]]) –
The set of all names. If None, use the design variables stored in the design space.
By default it is set to None.
x_full (Optional[numpy.ndarray]) –
The default values for the full vector. If None, use the zero vector.
By default it is set to None.
 Returns
The vector related to the input mask.
 Return type
numpy.ndarray