.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "api/gallery/control_systems/frequency/plot_02_bode_stability_margins.py"
.. LINE NUMBERS ARE GIVEN BELOW.

.. only:: html

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

        :ref:`Go to the end <sphx_glr_download_api_gallery_control_systems_frequency_plot_02_bode_stability_margins.py>`
        to download the full example code or to run this example in your browser via JupyterLite.

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

.. _sphx_glr_api_gallery_control_systems_frequency_plot_02_bode_stability_margins.py:


Bode's gain and phase margins
=============================

Hendrik Bode (1940, 1945) turned Nyquist's criterion into design numbers
read off a logarithmic plot of gain and phase
(:func:`~engineeringkit.control_systems.bode`). The *gain margin* is how
much the loop gain can grow before the phase-crossover point reaches
:math:`-1`; the *phase margin* is how much extra lag the loop tolerates at
the gain crossover (:func:`~engineeringkit.control_systems.stability_margins`).
For :math:`L = 2/(s(s+1)(s+2))` the phase crosses :math:`-180^\circ` at
:math:`\omega = \sqrt2`, where :math:`|L| = 1/3`, so the gain margin is 3.

.. GENERATED FROM PYTHON SOURCE LINES 16-27

.. code-block:: Python

    import matplotlib.pyplot as plt
    import numpy as np
    from scipy.optimize import brentq

    from engineeringkit.control_systems import feedback, poles, stability_margins, transfer_function
    from engineeringkit.control_systems.visualizers import plot_bode

    loop = transfer_function([2], [1, 3, 2, 0])
    m = stability_margins(loop)
    print({k: round(v, 4) for k, v in m.items()})





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

 .. code-block:: none

    {'gain_margin': 3.0, 'phase_margin_deg': 32.6131, 'gain_cross_frequency': 0.7494, 'phase_cross_frequency': 1.4142}




.. GENERATED FROM PYTHON SOURCE LINES 28-30

Independent checks
------------------

.. GENERATED FROM PYTHON SOURCE LINES 30-49

.. code-block:: Python


    wc = brentq(lambda w: 2 / (w * np.hypot(w, 1) * np.hypot(w, 2)) - 1, 0.1, 2)
    pm = 180 - np.degrees(np.pi / 2 + np.arctan(wc) + np.arctan(wc / 2))
    assert np.isclose(m["gain_margin"], 3, rtol=1e-4) and np.isclose(m["phase_cross_frequency"], np.sqrt(2), rtol=1e-4)
    assert np.isclose(m["gain_cross_frequency"], wc, rtol=1e-4) and np.isclose(m["phase_margin_deg"], pm, atol=0.01)
    # Multiplying the gain by the gain margin puts closed-loop poles on the axis.
    edge = poles(feedback(transfer_function([2 * m["gain_margin"]], [1, 3, 2, 0])))
    assert np.isclose(np.abs(edge.imag).max(), np.sqrt(2), rtol=1e-3) and abs(edge.real.max()) < 1e-3

    ax_mag, ax_phase = plot_bode(loop, np.logspace(-2, 2, 500))
    ax_mag.axhline(0, color="k", lw=0.8)
    ax_phase.axhline(-180, color="k", lw=0.8)
    ax_mag.vlines(m["phase_cross_frequency"], -20 * np.log10(m["gain_margin"]), 0, color="C3", lw=2, label=f"GM = {m['gain_margin']:.2f}")
    pm_label = f"PM = {m['phase_margin_deg']:.1f} deg"
    ax_phase.vlines(m["gain_cross_frequency"], -180, -180 + m["phase_margin_deg"], color="C2", lw=2, label=pm_label)
    ax_mag.legend()
    ax_phase.legend()

    plt.show()



.. image-sg:: /api/gallery/control_systems/frequency/images/sphx_glr_plot_02_bode_stability_margins_001.png
   :alt: plot 02 bode stability margins
   :srcset: /api/gallery/control_systems/frequency/images/sphx_glr_plot_02_bode_stability_margins_001.png
   :class: sphx-glr-single-img






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

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


.. _sphx_glr_download_api_gallery_control_systems_frequency_plot_02_bode_stability_margins.py:

.. only:: html

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

    .. container:: lite-badge

      .. image:: images/jupyterlite_badge_logo.svg
        :target: ../../../../lite/lab/index.html?path=api/gallery/control_systems/frequency/plot_02_bode_stability_margins.ipynb
        :alt: Launch JupyterLite
        :width: 150 px

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

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

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

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

    .. container:: sphx-glr-download sphx-glr-download-zip

      :download:`Download zipped: plot_02_bode_stability_margins.zip <plot_02_bode_stability_margins.zip>`


.. only:: html

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

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