.. DO NOT EDIT. .. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY. .. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE: .. "examples/api/plot_formulation.py" .. LINE NUMBERS ARE GIVEN BELOW. .. only:: html .. note:: :class: sphx-glr-download-link-note :ref:`Go to the end ` to download the full example code. .. rst-class:: sphx-glr-example-title .. _sphx_glr_examples_api_plot_formulation.py: 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. .. GENERATED FROM PYTHON SOURCE LINES 28-41 .. code-block:: Python 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() .. rst-class:: sphx-glr-script-out .. code-block:: none .. GENERATED FROM PYTHON SOURCE LINES 42-47 Get available formulations -------------------------- The :func:`.get_available_formulations` function returns the list of MDO formulations available in |g| or in external modules .. GENERATED FROM PYTHON SOURCE LINES 47-49 .. code-block:: Python get_available_formulations() .. rst-class:: sphx-glr-script-out .. code-block:: none ['BiLevel', 'BiLevelBCD', 'DisciplinaryOpt', 'IDF', 'MDF'] .. GENERATED FROM PYTHON SOURCE LINES 50-56 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 :func:`.get_formulation_options_schema` function; e.g. .. GENERATED FROM PYTHON SOURCE LINES 56-58 .. code-block:: Python get_formulation_options_schema("MDF") .. rst-class:: sphx-glr-script-out .. code-block:: none {'$schema': 'http://json-schema.org/schema#', 'type': 'object', 'properties': {'differentiated_input_names_substitute': {'type': 'array', 'description': 'The names of the discipline inputs with respect to 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.'}, 'main_mda_name': {'type': 'string', 'description': 'The name of the class of the main MDA. Typically the :class:`.MDAChain`, but one can force to use :class:`.MDAGaussSeidel` for instance. This field is ignored when ``main_mda_settings`` is a Pydantic model.'}, 'main_mda_settings': {'type': 'object', 'description': 'The settings of the main MDA. These settings may include those of the inner-MDA.'}}} .. GENERATED FROM PYTHON SOURCE LINES 59-61 - get the default option values using the :func:`.get_formulations_options_defaults` function; e.g. .. GENERATED FROM PYTHON SOURCE LINES 61-63 .. code-block:: Python get_formulations_options_defaults("MDF") .. rst-class:: sphx-glr-script-out .. code-block:: none {'differentiated_input_names_substitute': (), 'main_mda_name': 'MDAChain', 'main_mda_settings': {}} .. GENERATED FROM PYTHON SOURCE LINES 64-66 - get sub-options of an MDO formulation using the :func:`.get_formulation_sub_options_schema` function; e.g. .. GENERATED FROM PYTHON SOURCE LINES 66-68 .. code-block:: Python get_formulation_sub_options_schema("MDF", main_mda_name="MDAGaussSeidel") .. rst-class:: sphx-glr-script-out .. code-block:: none {'$schema': 'http://json-schema.org/schema#', 'type': 'object', 'properties': {'coupling_structure': {'type': 'null', 'description': 'The coupling structure to be used by the MDA. If ``None``, the coupling structure is created from the disciplines.'}, 'linear_solver': {'type': 'string', 'description': 'The name of the linear solver. This field is ignored when ``linear_solver_settings`` is a Pydantic model.'}, 'linear_solver_settings': {'type': 'object', 'description': 'The settings of the linear solver.'}, 'linear_solver_tolerance': {'type': 'number', 'description': 'The linear solver tolerance.'}, 'log_convergence': {'type': 'boolean', 'description': 'Whether to log the MDA convergence. The log displays the normalized residual norm.'}, 'max_mda_iter': {'type': 'integer', 'description': 'The maximum number of iterations for the MDA algorithm. If 0, evaluate the coupling variables without trying to solve the coupling equations.'}, 'max_consecutive_unsuccessful_iterations': {'type': 'integer', 'description': 'The maximum number of consecutive unsuccessful iterations. Iterations are considered unsuccessful if the normalized residual norm increases.'}, 'name': {'type': 'string', 'description': 'The name to be given to the MDA. If empty, use the name of the class.'}, 'tolerance': {'type': 'number', 'description': 'The tolerance for the MDA algorithm residual. The available normalization strategies for the residual are described in :attr:`.BaseMDA.ResidualScaling`.'}, 'use_lu_fact': {'type': 'boolean', 'description': 'Whether to perform an LU factorization. The factorization is used to solve the linear systems arising in the computation of the total derivatives. Since there are possibly several right-hand side, if affordable, such a factorization may improve the solution time.'}, 'warm_start': {'type': 'boolean', 'description': 'Whether to warm start the execution of the MDA algorithm. The warm start strategy consists in using the last cached values for the coupling variables as an initial guess. This is expected to reduce the number of iteration of the MDA algorithm required to reach convergence.'}, 'acceleration_method': {'type': 'string', 'description': 'The acceleration method used within the fixed point iterations.'}, 'over_relaxation_factor': {'type': 'number', 'description': 'The over-relaxation factor.'}}} .. GENERATED FROM PYTHON SOURCE LINES 69-71 - get the sub-option values using the :func:`.get_formulations_sub_options_defaults` function; e.g. .. GENERATED FROM PYTHON SOURCE LINES 71-73 .. code-block:: Python get_formulations_sub_options_defaults("MDF", main_mda_name="MDAGaussSeidel") .. rst-class:: sphx-glr-script-out .. code-block:: none {'coupling_structure': None, 'linear_solver': , 'linear_solver_settings': {}, 'linear_solver_tolerance': 1e-12, 'log_convergence': False, 'max_mda_iter': 20, 'max_consecutive_unsuccessful_iterations': 8, 'name': '', 'tolerance': 1e-06, 'use_lu_fact': False, 'warm_start': False, 'acceleration_method': , 'over_relaxation_factor': 1.0} .. GENERATED FROM PYTHON SOURCE LINES 74-76 Or import its settings model and pass it directly with the keyword "formulation_settings_model". .. GENERATED FROM PYTHON SOURCE LINES 76-80 .. code-block:: Python from gemseo.settings.formulations import MDF_Settings # noqa: E402 settings_model = MDF_Settings() .. GENERATED FROM PYTHON SOURCE LINES 81-82 See :ref:`formulation_settings` for more information on how to use settings models. .. rst-class:: sphx-glr-timing **Total running time of the script:** (0 minutes 0.004 seconds) .. _sphx_glr_download_examples_api_plot_formulation.py: .. only:: html .. container:: sphx-glr-footer sphx-glr-footer-example .. container:: sphx-glr-download sphx-glr-download-jupyter :download:`Download Jupyter notebook: plot_formulation.ipynb ` .. container:: sphx-glr-download sphx-glr-download-python :download:`Download Python source code: plot_formulation.py ` .. container:: sphx-glr-download sphx-glr-download-zip :download:`Download zipped: plot_formulation.zip ` .. only:: html .. rst-class:: sphx-glr-signature `Gallery generated by Sphinx-Gallery `_