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

        Click :ref:`here <sphx_glr_download_examples_api_plot_formulation.py>`
        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-38

.. code-block:: default

    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()






.. rst-class:: sphx-glr-script-out

 Out:

 .. code-block:: none


    <RootLogger root (INFO)>



.. GENERATED FROM PYTHON SOURCE LINES 39-44

Get available formulations
--------------------------

The :meth:`~gemseo.api.get_available_formulations` function returns the list
of MDO formulations available in |g| or in external modules

.. GENERATED FROM PYTHON SOURCE LINES 44-46

.. code-block:: default

    print(get_available_formulations())





.. rst-class:: sphx-glr-script-out

 Out:

 .. code-block:: none

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




.. GENERATED FROM PYTHON SOURCE LINES 47-53

Get formulation schemas for (sub-)options
-----------------------------------------
For a given MDO formulation, e.g. :code:`"MDF"`, we can:

- get the options of an MDO formulation using the
  :meth:`~gemseo.api.get_formulation_options_schema` function; e.g.

.. GENERATED FROM PYTHON SOURCE LINES 53-55

.. code-block:: default

    print(get_formulation_options_schema("MDF"))





.. rst-class:: sphx-glr-script-out

 Out:

 .. code-block:: none

    {'$schema': 'http://json-schema.org/schema#', 'type': 'object', 'properties': {'maximize_objective': {'description': 'If True, the objective function is maximized.', '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']}




.. GENERATED FROM PYTHON SOURCE LINES 56-58

- get the default option values using the
  :meth:`~gemseo.api.get_formulations_options_defaults` function; e.g.

.. GENERATED FROM PYTHON SOURCE LINES 58-60

.. code-block:: default

    print(get_formulations_options_defaults("MDF"))





.. rst-class:: sphx-glr-script-out

 Out:

 .. code-block:: none

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




.. GENERATED FROM PYTHON SOURCE LINES 61-63

- get sub-options of an MDO formulation using the
  :meth:`~gemseo.api.get_formulation_sub_options_schema` function; e.g.

.. GENERATED FROM PYTHON SOURCE LINES 63-65

.. code-block:: default

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





.. rst-class:: sphx-glr-script-out

 Out:

 .. code-block:: none

    {'$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']}




.. GENERATED FROM PYTHON SOURCE LINES 66-68

- get the sub-option values using the
  :meth:`~gemseo.api.get_formulations_sub_options_defaults` function; e.g.

.. GENERATED FROM PYTHON SOURCE LINES 68-69

.. code-block:: default

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




.. rst-class:: sphx-glr-script-out

 Out:

 .. code-block:: none

    {'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}





.. 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
    :class: sphx-glr-footer-example



  .. container:: sphx-glr-download sphx-glr-download-python

     :download:`Download Python source code: plot_formulation.py <plot_formulation.py>`



  .. container:: sphx-glr-download sphx-glr-download-jupyter

     :download:`Download Jupyter notebook: plot_formulation.ipynb <plot_formulation.ipynb>`


.. only:: html

 .. rst-class:: sphx-glr-signature

    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_