make _isstatic internal; updated doc/ for descfcn

murrayrm · murrayrm · commit 2ac5d9df128d · 2021-02-06T13:16:09.000-08:00
diff --git a/control/descfcn.py b/control/descfcn.py
@@ -21,7 +21,8 @@
 from .freqplot import nyquist_plot
 
 __all__ = ['describing_function', 'describing_function_plot',
-           'DescribingFunctionNonlinearity']
+           'DescribingFunctionNonlinearity', 'backlash_nonlinearity',
+           'relay_hysteresis_nonlinearity', 'saturation_nonlinearity']
 
 # Class for nonlinearities with a built-in describing function
 class DescribingFunctionNonlinearity():
@@ -31,7 +32,7 @@ class DescribingFunctionNonlinearity():
     that have a analytically defined describing function (accessed via the
     :meth:`describing_function` method).  Objects using this class should also
     implement a `call` method that evaluates the nonlinearity at a given point
-    and an `isstatic` method that is `True` if the nonlinearity has no
+    and an `_isstatic` method that is `True` if the nonlinearity has no
     internal state.
 
     """
@@ -54,10 +55,10 @@ def describing_function(self, A):
         raise NotImplementedError(
             "describing function not implemented for this function")
 
-    def isstatic(self):
+    def _isstatic(self):
         """Return True if the function has not internal state"""
         raise NotImplementedError(
-            "isstatic() not implemented for this function (internal error)")
+            "_isstatic() not implemented for this function (internal error)")
 
     # Utility function used to compute common describing functions
     def _f(self, x):
@@ -157,7 +158,7 @@ def describing_function(
     cos_theta = np.cos(theta)
 
     # See if this is a static nonlinearity (assume not, just in case)
-    if not hasattr(F, 'isstatic') or not F.isstatic():
+    if not hasattr(F, '_isstatic') or not F._isstatic():
         # Initialize any internal state by going through an initial cycle
         [F(x) for x in np.atleast_1d(A).min() * sin_theta]
 
@@ -223,6 +224,14 @@ def describing_function_plot(
         given by the first value of the tuple and frequency given by the
         second value.
 
+    Example
+    -------
+    >>> H_simple = ct.tf([8], [1, 2, 2, 1])
+    >>> F_saturation = ct.descfcn.saturation_nonlinearity(1)
+    >>> amp = np.linspace(1, 4, 10)
+    >>> ct.describing_function_plot(H_simple, F_saturation, amp)
+    [(3.344008947853124, 1.414213099755523)]
+
     """
     # Start by drawing a Nyquist curve
     H_real, H_imag, H_omega = nyquist_plot(H, omega, plot=True, **kwargs)
@@ -346,7 +355,7 @@ def __init__(self, ub=1, lb=None):
     def __call__(self, x):
         return np.maximum(self.lb, np.minimum(x, self.ub))
 
-    def isstatic(self):
+    def _isstatic(self):
         return True
 
     def describing_function(self, A):
@@ -369,8 +378,8 @@ class relay_hysteresis_nonlinearity(DescribingFunctionNonlinearity):
     This class creates a nonlinear function representing a a relay with
     symmetric upper and lower bounds of magnitude `b` and a hysteretic region
     of width `c` (using the notation from [FBS2e](https://fbsbook.org),
-    Example 10.12,including the describing function for the nonlinearity.  The
-    following call creates a nonlinear function suitable for describing
+    Example 10.12, including the describing function for the nonlinearity.
+    The following call creates a nonlinear function suitable for describing
     function analysis:
 
         F = relay_hysteresis_nonlinearity(b, c)
@@ -402,7 +411,7 @@ def __call__(self, x):
             y = self.b
         return y
 
-    def isstatic(self):
+    def _isstatic(self):
         return False
 
     def describing_function(self, A):
@@ -457,7 +466,7 @@ def __call__(self, x):
             y.append(self.center)
         return(np.array(y).reshape(x_array.shape))
 
-    def isstatic(self):
+    def _isstatic(self):
         return False
 
     def describing_function(self, A):
diff --git a/doc/classes.rst b/doc/classes.rst
@@ -30,12 +30,3 @@ that allow for linear, nonlinear, and interconnected elements:
    LinearICSystem
    LinearIOSystem
    NonlinearIOSystem
-
-Additional classes
-==================
-
-.. autosummary::
-   :toctree: generated/
-
-   DescribingFunctionNonlinearity
-
diff --git a/doc/descfcn.rst b/doc/descfcn.rst
@@ -0,0 +1,86 @@
+.. _descfcn-module:
+
+********************
+Describing functions
+********************
+
+For nonlinear systems consisting of a feedback connection between a
+linear system and a static nonlinearity, it is possible to obtain a
+generalization of Nyquist's stability criterion based on the idea of
+describing functions.  The basic concept involves approximating the
+response of a static nonlinearity to an input :math:`u = A e^{\omega
+t}` as an output :math:`y = N(A) (A e^{\omega t})`, where :math:`N(A)
+\in \mathbb{C}` represents the (amplitude-dependent) gain and phase
+associated with the nonlinearity.
+
+Stability analysis of a linear system :math:`H(s)` with a feedback
+nonlinearity :math:`F(x)` is done by looking for amplitudes :math:`A`
+and frequencies :math:`\omega` such that
+
+.. math::
+
+   H(j\omega) N(A) = -1
+
+If such an intersection exists, it indicates that there may be a limit
+cycle of amplitude :math:`A` with frequency :math:`\omega`.
+
+Describing function analysis is a simple method, but it is approximate
+because it assumes that higher harmonics can be neglected. 
+
+Module usage
+============
+
+The function :func:`~control.describing_function` can be used to
+compute the describing function of a nonlinear function::
+
+  N = ct.describing_function(F, A)
+
+Stability analysis using describing functions is done by looking for
+amplitudes :math:`a` and frequencies :math`\omega` such that
+
+.. math::
+
+   H(j\omega) = \frac{-1}{N(A)}
+
+These points can be determined by generating a Nyquist plot in which the
+transfer function :math:`H(j\omega)` intersections the negative
+reciprocal of the describing function :math:`N(A)`.  The
+:func:`~control.describing_function_plot` function generates this plot
+and returns the amplitude and frequency of any points of intersection::
+
+    ct.describing_function_plot(H, F, amp_range[, omega_range])
+
+
+Pre-defined nonlinearities
+==========================
+
+To facilitate the use of common describing functions, the following
+nonlinearity constructors are predefined:
+
+.. code:: python
+
+  backlash_nonlinearity(b)		# backlash nonlinearity with width b
+  relay_hysteresis_nonlinearity(b, c)   # relay output of amplitude b with
+					# hysteresis of half-width c
+  saturation_nonlinearity(ub[, lb])	# saturation nonlinearity with upper
+					# bound and (optional) lower bound
+
+Calling these functions will create an object `F` that can be used for
+describing function analysis.  For example, to create a saturation
+nonlinearity::
+
+  F = ct.saturation_nonlinearity(1)
+
+These functions use the
+:class:`~control.DescribingFunctionNonlinearity`, which allows an
+analytical description of the describing function.
+
+Module classes and functions
+============================
+.. autosummary::
+   :toctree: generated/
+
+   ~control.DescribingFunctionNonlinearity
+   ~control.backlash_nonlinearity
+   ~control.relay_hysteresis_nonlinearity
+   ~control.saturation_nonlinearity
diff --git a/doc/describing_functions.ipynb b/doc/describing_functions.ipynb
@@ -0,0 +1 @@
+../examples/describing_functions.ipynb
diff --git a/doc/examples.rst b/doc/examples.rst
@@ -42,5 +42,6 @@ using running examples in FBS2e.
    :maxdepth: 1
 
    cruise
+   describing_functions
    steering
    pvtol-lqr-nested
diff --git a/doc/index.rst b/doc/index.rst
@@ -29,6 +29,7 @@ implements basic operations for analysis and design of feedback control systems.
    matlab
    flatsys
    iosys
+   descfcn
    examples
 
 * :ref:`genindex`
diff --git a/examples/describing_functions.ipynb b/examples/describing_functions.ipynb
@@ -4,9 +4,10 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Describing Function Analysis Using the Python Control Toolbox (python-control)\n",
-    "### Richard M. Murray, 27 Jan 2021\n",
-    "This Jupyter notebook shows how to use the `nltools` module of the Python Control Toolbox to perform describing function analysis of a nonlinear system.  A brief introduction to describing functions can be found in [Feedback Systems](https://fbsbook.org), Section 10.5 (Generalized Notions of Gain and Phase)."
+    "# Describing function analysis\n",
+    "Richard M. Murray, 27 Jan 2021\n",
+    "\n",
+    "This Jupyter notebook shows how to use the `descfcn` module of the Python Control Toolbox to perform describing function analysis of a nonlinear system.  A brief introduction to describing functions can be found in [Feedback Systems](https://fbsbook.org), Section 10.5 (Generalized Notions of Gain and Phase)."
    ]
   },
   {
@@ -35,7 +36,7 @@
    "source": [
     "### Saturation nonlinearity\n",
     "\n",
-    "A saturation nonlinearity can be obtained using the `ct.nltools.saturation_nonlinearity` function.  This function takes the saturation level as an argument."
+    "A saturation nonlinearity can be obtained using the `ct.saturation_nonlinearity` function.  This function takes the saturation level as an argument."
    ]
   },
   {
@@ -57,7 +58,7 @@
     }
    ],
    "source": [
-    "saturation=ct.nltools.saturation_nonlinearity(0.75)\n",
+    "saturation=ct.saturation_nonlinearity(0.75)\n",
     "x = np.linspace(-2, 2, 50)\n",
     "plt.plot(x, saturation(x))\n",
     "plt.xlabel(\"Input, x\")\n",
@@ -96,7 +97,7 @@
    "metadata": {},
    "source": [
     "### Backlash nonlinearity\n",
-    "A backlash nonlinearity can be obtained using the `ct.nltools.backlash_nonlinearity` function.  This function takes as is argument the size of the backlash region."
+    "A backlash nonlinearity can be obtained using the `ct.backlash_nonlinearity` function.  This function takes as is argument the size of the backlash region."
    ]
   },
   {
@@ -118,7 +119,7 @@
     }
    ],
    "source": [
-    "backlash = ct.nltools.backlash_nonlinearity(0.5)\n",
+    "backlash = ct.backlash_nonlinearity(0.5)\n",
     "theta = np.linspace(0, 2*np.pi, 50)\n",
     "x = np.sin(theta)\n",
     "plt.plot(x, backlash(x))\n",
@@ -232,7 +233,9 @@
     "\n",
     "Consider a nonlinear feedback system consisting of a third-order linear system with transfer function $H(s)$ and a saturation nonlinearity having describing function $N(a)$.  Stability can be assessed by looking for points at which \n",
     "\n",
-    "$$ H(j\\omega) N(a) = −1$$\n",
+    "$$\n",
+    "H(j\\omega) N(a) = -1",
+    "$$\n",
     "\n",
     "The `describing_function_plot` function plots $H(j\\omega)$ and $-1/N(a)$ and prints out the the amplitudes and frequencies corresponding to intersections of these curves. "
    ]
@@ -271,7 +274,7 @@
     "omega = np.logspace(-3, 3, 500)\n",
     "\n",
     "# Nonlinearity\n",
-    "F_saturation = ct.nltools.saturation_nonlinearity(1)\n",
+    "F_saturation = ct.saturation_nonlinearity(1)\n",
     "amp = np.linspace(00, 5, 50)\n",
     "\n",
     "# Describing function plot (return value = amp, freq)\n",
@@ -362,7 +365,7 @@
     "omega = np.logspace(-3, 3, 500)\n",
     "\n",
     "# Nonlinearity\n",
-    "F_backlash = ct.nltools.backlash_nonlinearity(1)\n",
+    "F_backlash = ct.backlash_nonlinearity(1)\n",
     "amp = np.linspace(0.6, 5, 50)\n",
     "\n",
     "# Describing function plot\n",
diff --git a/examples/steering.ipynb b/examples/steering.ipynb
@@ -5,23 +5,12 @@
    "metadata": {},
    "source": [
     "# Vehicle steering\n",
-    "Karl J. Astrom and Richard M. Murray  \n",
+    "Karl J. Astrom and Richard M. Murray\n",
     "23 Jul 2019\n",
     "\n",
     "This notebook contains the computations for the vehicle steering running example in *Feedback Systems*."
    ]
   },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "RMM comments to Karl, 27 Jun 2019\n",
-    "* I'm using this notebook to walk through all of the vehicle steering examples and make sure that all of the parameters, conditions, and maximum steering angles are consitent and reasonable.\n",
-    "* Please feel free to send me comments on the contents as well as the bulletted notes, in whatever form is most convenient.\n",
-    "* Once we have sorted out all of the settings we want to use, I'll copy over the changes into the MATLAB files that we use for creating the figures in the book.\n",
-    "* These notes will be removed from the notebook once we have finalized everything."
-   ]
-  },
   {
    "cell_type": "code",
    "execution_count": 1,
