.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "examples/mda/plot_residual_as_observable.py"
.. LINE NUMBERS ARE GIVEN BELOW.

.. only:: html

    .. note::
        :class: sphx-glr-download-link-note

        :ref:`Go to the end <sphx_glr_download_examples_mda_plot_residual_as_observable.py>`
        to download the full example code

.. rst-class:: sphx-glr-example-title

.. _sphx_glr_examples_mda_plot_residual_as_observable.py:


MDA residuals
=============

This example illustrates how to retrieve the normed residual of a given MDA.

The residual of an MDA is a vector
defined by :math:`\mathrm{couplings}_k - \mathrm{couplings}_{k+1}`,
where :math:`k` and :math:`k+1` are two successive iterations of the MDA algorithm
and :math:`\mathrm{couplings}` is the coupling vector.

The normed residual is the normalized value of :math:`\norm{\mathrm{residuals}}`.
When the normed residual is smaller than a given tolerance value,
the MDA has converged.
It is a simple way to quantify the MDA convergence.

This normed residual can be seen as an MDA output.
Therefore, it can be used as a constraint in an MDO scenario,
or can simply be retrieved as a scenario observable.
It is a simple way to determine
whether a given solution has a feasible design (MDA convergence) or not.

.. GENERATED FROM PYTHON SOURCE LINES 42-50

.. code-block:: default

    from __future__ import annotations

    from gemseo import configure_logger
    from gemseo import create_discipline
    from gemseo import create_mda

    configure_logger()





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

 .. code-block:: none


    <RootLogger root (INFO)>



.. GENERATED FROM PYTHON SOURCE LINES 51-58

Create and execute the MDA
--------------------------
We do not need to specify the inputs, the default inputs
of the :class:`.MDA` will be used and computed from the
default inputs of the disciplines.

Here, we could have replaced :class:`.MDAGaussSeidel` by any other MDA.

.. GENERATED FROM PYTHON SOURCE LINES 58-70

.. code-block:: default


    disciplines = create_discipline(
        [
            "SobieskiStructure",
            "SobieskiPropulsion",
            "SobieskiAerodynamics",
            "SobieskiMission",
        ]
    )
    mda = create_mda("MDAGaussSeidel", disciplines)
    output_data = mda.execute()








.. GENERATED FROM PYTHON SOURCE LINES 71-81

MDA convergence analysis
------------------------
The MDA algorithm will stop if one of the following criteria is fulfilled:

    - The normed residual is lower than the MDA tolerance.
      This case appears when the design is feasible.
    - The maximal number of iterations is reached.
      In that case, the design is not feasible.

The normed residual can be seen by the :class:`.MDA` attribute :attr:`~.MDA.normed_residual`.

.. GENERATED FROM PYTHON SOURCE LINES 81-83

.. code-block:: default

    mda.normed_residual





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

 .. code-block:: none


    5.50839275306244e-07



.. GENERATED FROM PYTHON SOURCE LINES 84-91

The evolution of its value can be plotted with :meth:`~.MDA.plot_residual_history`,
or accessed by :attr:`~.MDA.residual_history`.

When an MDA is called more than once (by a DOE driver for instance),
the :attr:`~.MDA.residual_history`
stores the different values of the normed residual
in a single list.

.. GENERATED FROM PYTHON SOURCE LINES 91-94

.. code-block:: default

    residual_history = mda.residual_history
    residual_history





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

 .. code-block:: none


    [1.0, 0.709008476835191, 0.09279601629441475, 0.012492524096475305, 0.0016808042405903614, 0.0002261485507646748, 3.0427816889922925e-05, 4.0940000680510455e-06, 5.50839275306244e-07]



.. GENERATED FROM PYTHON SOURCE LINES 95-99

The normed MDA residual can be seen as an MDA output,
just like the couplings.
To get the normed MDA residual,
the key registered by :attr:`~.MDA.RESIDUALS_NORM` (``""MDA residuals norm"``) can be used.

.. GENERATED FROM PYTHON SOURCE LINES 99-101

.. code-block:: default

    f"The normed residual key is: {mda.RESIDUALS_NORM}."





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

 .. code-block:: none


    'The normed residual key is: MDA residuals norm.'



.. GENERATED FROM PYTHON SOURCE LINES 102-104

This normed residual can be used as a constraint in an MDO scenario,
or can simply be retrieved as a scenario observable.

.. GENERATED FROM PYTHON SOURCE LINES 104-106

.. code-block:: default

    normed_residual = output_data[mda.RESIDUALS_NORM]
    normed_residual




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

 .. code-block:: none


    array([5.50839275e-07])




.. rst-class:: sphx-glr-timing

   **Total running time of the script:** (0 minutes 0.089 seconds)


.. _sphx_glr_download_examples_mda_plot_residual_as_observable.py:

.. only:: html

  .. container:: sphx-glr-footer sphx-glr-footer-example




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

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

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

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


.. only:: html

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

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