Formulation

In this example, we will discover the different functions of the API related to MDO formulations: their names, their options and their sub-options.

from __future__ import annotations

from gemseo import configure_logger
from gemseo import get_available_formulations
from gemseo import get_formulation_options_schema
from gemseo import get_formulation_sub_options_schema
from gemseo import get_formulations_options_defaults
from gemseo import get_formulations_sub_options_defaults

configure_logger()

<RootLogger root (INFO)>

Get available formulations

The get_available_formulations() function returns the list of MDO formulations available in GEMSEO or in external modules

get_available_formulations()

['BiLevel', 'DisciplinaryOpt', 'IDF', 'MDF']

Get formulation schemas for (sub-)options

For a given MDO formulation, e.g. "MDF", we can:

• get the options of an MDO formulation using the get_formulation_options_schema() function; e.g.

get_formulation_options_schema("MDF")

{'$schema': 'http://json-schema.org/schema#', 'type': 'object', 'properties': {'maximize_objective': {'description': 'Whether to maximize the objective.', 'type': 'boolean'}, 'grammar_type': {'description': 'The type of the input and output grammars.', 'type': 'string'}, 'main_mda_name': {'description': 'The name of the class used for the main MDA, typically the :class:`.MDAChain`, but one can force to use :class:`.MDAGaussSeidel` for instance.', 'type': 'string'}, 'inner_mda_name': {'description': 'The name of the class used for the inner-MDA of the main MDA, if any; typically when the main MDA is an :class:`.MDAChain`.', 'type': 'string'}, 'differentiated_input_names_substitute': {'description': '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 :class:`.MDOFunction` is built from the ``disciplines``, which depend on input variables :math:`x_1,\\ldots,x_d,x_{d+1}`, and over an input space spanned by the input variables :math:`x_1,\\ldots,x_d` and depending on both the MDO formulation and the ``design_space``. Then, the methods :meth:`.MDOFunction.evaluate` and :meth:`.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 :math:`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. :math:`x_{d-1}` and :math:`x_{d+1}`. Mathematically speaking, this matrix returned by :meth:`.MDOFunction.jac` is no longer a Jacobian.', 'type': 'array'}}}

• get the default option values using the get_formulations_options_defaults() function; e.g.

get_formulations_options_defaults("MDF")

{'maximize_objective': False, 'grammar_type': <GrammarType.JSON: 'JSONGrammar'>, 'main_mda_name': 'MDAChain', 'inner_mda_name': 'MDAJacobi', 'differentiated_input_names_substitute': ()}

• get sub-options of an MDO formulation using the get_formulation_sub_options_schema() function; e.g.

get_formulation_sub_options_schema("MDF", main_mda_name="MDAGaussSeidel")

{'$schema': 'http://json-schema.org/schema#', 'type': 'object', 'properties': {'name': {'description': 'The name to be given to the MDA. If empty, use the name of the class.', 'type': 'string'}, 'max_mda_iter': {'description': 'The maximum iterations number for the MDA algorithm. If 0, evaluate the coupling the coupling process without trying to solve the coupling equations.', 'type': 'integer'}, 'grammar_type': {'description': 'The type of the input and output grammars.', 'type': 'string'}, 'tolerance': {'description': 'The tolerance of the iterative direct coupling solver; the norm of the current residuals divided by initial residuals norm shall be lower than the tolerance to stop iterating.', 'type': 'number'}, 'linear_solver_tolerance': {'description': 'The tolerance of the linear solver in the adjoint equation.', 'type': 'number'}, 'warm_start': {'description': 'Whether the second iteration and ongoing start from the previous coupling solution.', 'type': 'boolean'}, 'use_lu_fact': {'description': 'Whether to store a LU factorization of the matrix when using adjoint/forward differentiation. to solve faster multiple RHS problem.', 'type': 'boolean'}, 'coupling_structure': {'description': 'The coupling structure to be used by the MDA. If ``None``, it is created from `disciplines`.', 'type': 'null'}, 'log_convergence': {'description': 'Whether to log the MDA convergence, expressed in terms of normed residuals.', 'type': 'boolean'}, 'linear_solver': {'description': 'The name of the linear solver.', 'type': 'string'}, 'linear_solver_options': {'description': 'The options passed to the linear solver factory.', 'type': 'object'}, 'acceleration_method': {'description': 'The acceleration method to be used to improve the convergence rate of the fixed point iteration method.', 'type': 'string'}, 'over_relaxation_factor': {'description': 'The over-relaxation factor.', 'type': 'number'}}}

• get the sub-option values using the get_formulations_sub_options_defaults() function; e.g.

get_formulations_sub_options_defaults("MDF", main_mda_name="MDAGaussSeidel")

{'name': '', 'max_mda_iter': 10, 'grammar_type': <GrammarType.JSON: 'JSONGrammar'>, 'tolerance': 1e-06, 'linear_solver_tolerance': 1e-12, 'warm_start': False, 'use_lu_fact': False, 'coupling_structure': None, 'log_convergence': False, 'linear_solver': 'DEFAULT', 'linear_solver_options': mappingproxy({}), 'acceleration_method': <AccelerationMethod.NONE: 'NoTransformation'>, 'over_relaxation_factor': 1.0}