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 gemseo.api import configure_logger
from gemseo.api import get_available_formulations
from gemseo.api import get_formulation_options_schema
from gemseo.api import get_formulation_sub_options_schema
from gemseo.api import get_formulations_options_defaults
from gemseo.api 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

print(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.

print(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, either :attr:`.MDODiscipline.JSON_GRAMMAR_TYPE` or :attr:`.MDODiscipline.SIMPLE_GRAMMAR_TYPE`.', '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'}}, 'required': ['grammar_type', 'inner_mda_name', 'main_mda_name', 'maximize_objective']}

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

print(get_formulations_options_defaults("MDF"))

{'maximize_objective': False, 'grammar_type': 'JSONGrammar', 'main_mda_name': 'MDAChain', 'inner_mda_name': 'MDAJacobi'}

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

print(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 None, use the name of the class.', 'type': 'null'}, 'max_mda_iter': {'description': 'The maximum iterations number for the MDA algorithm.', 'type': 'integer'}, 'grammar_type': {'description': 'The type of the input and output grammars, either :attr:`.MDODiscipline.JSON_GRAMMAR_TYPE` or :attr:`.MDODiscipline.SIMPLE_GRAMMAR_TYPE`.', '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'}, 'over_relax_factor': {'description': 'The relaxation coefficient, used to make the method more robust, if ``0<over_relax_factor<1`` or faster if ``1<over_relax_factor<=2``. If ``over_relax_factor =1.``, it is deactivated.', 'type': 'number'}, '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': 'null'}}, 'required': ['grammar_type', 'linear_solver', 'linear_solver_tolerance', 'log_convergence', 'max_mda_iter', 'over_relax_factor', 'tolerance', 'use_lu_fact', 'warm_start']}

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

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

{'name': None, 'max_mda_iter': 10, 'grammar_type': 'JSONGrammar', 'tolerance': 1e-06, 'linear_solver_tolerance': 1e-12, 'warm_start': False, 'use_lu_fact': False, 'over_relax_factor': 1.0, 'coupling_structure': None, 'log_convergence': False, 'linear_solver': 'DEFAULT', 'linear_solver_options': None}