updated iosys class/factory function documentation + docstring unit testing

Author: murrayrm

control/flatsys/flatsys.py

@@ -1,42 +1,5 @@
 # flatsys.py - trajectory generation for differentially flat systems
 # RMM, 10 Nov 2012
-#
-# This file contains routines for computing trajectories for differentially
-# flat nonlinear systems.  It is (very) loosely based on the NTG software
-# package developed by Mark Milam and Kudah Mushambi, but rewritten from
-# scratch in python.
-#
-# Copyright (c) 2012 by California Institute of Technology
-# All rights reserved.
-#
-# Redistribution and use in source and binary forms, with or without
-# modification, are permitted provided that the following conditions
-# are met:
-#
-# 1. Redistributions of source code must retain the above copyright
-#    notice, this list of conditions and the following disclaimer.
-#
-# 2. Redistributions in binary form must reproduce the above copyright
-#    notice, this list of conditions and the following disclaimer in the
-#    documentation and/or other materials provided with the distribution.
-#
-# 3. Neither the name of the California Institute of Technology nor
-#    the names of its contributors may be used to endorse or promote
-#    products derived from this software without specific prior
-#    written permission.
-#
-# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
-# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
-# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
-# FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL CALTECH
-# OR THE CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
-# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
-# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
-# USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
-# ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
-# OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
-# OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
-# SUCH DAMAGE.
 
 import itertools
 import numpy as np

control/frdata.py

@@ -3,11 +3,11 @@
 # Author: M.M. (Rene) van Paassen (using xferfcn.py as basis)
 # Date: 02 Oct 12
 
-"""
-Frequency response data representation and functions.
+"""Frequency response data representation and functions.
+
+This module contains the FrequencyResponseData (FRD) class and also
+functions that operate on FRD data.
 
-This module contains the FRD class and also functions that operate on
-FRD data.
 """
 
 from collections.abc import Iterable
@@ -35,38 +35,29 @@ class FrequencyResponseData(LTI):
 
     The FrequencyResponseData (FRD) class is used to represent systems in
     frequency response data form.  It can be created manually using the
-    class constructor, using the :func:`~control.frd` factory function or
+    class constructor, using the :func:`~control.frd` factory function, or
     via the :func:`~control.frequency_response` function.
 
     Parameters
     ----------
-    d : 1D or 3D complex array_like
+    response : 1D or 3D complex array_like
         The frequency response at each frequency point.  If 1D, the system is
         assumed to be SISO.  If 3D, the system is MIMO, with the first
         dimension corresponding to the output index of the FRD, the second
         dimension corresponding to the input index, and the 3rd dimension
         corresponding to the frequency points in omega
-    w : iterable of real frequencies
+    omega : iterable of real frequencies
         List of frequency points for which data are available.
-    sysname : str or None
-        Name of the system that generated the data.
     smooth : bool, optional
         If ``True``, create an interpolation function that allows the
         frequency response to be computed at any frequency within the range of
         frequencies give in ``w``.  If ``False`` (default), frequency response
         can only be obtained at the frequencies specified in ``w``.
-
-    Attributes
-    ----------
-    ninputs, noutputs : int
-        Number of input and output variables.
-    omega : 1D array
-        Frequency points of the response.
-    fresp : 3D array
-        Frequency response, indexed by output index, input index, and
-        frequency point.
-    dt : float, True, or None
-        System timebase.
+    dt : None, True or float, optional
+        System timebase. 0 (default) indicates continuous time, True
+        indicates discrete time with unspecified sampling time, positive
+        number is discrete time with specified sampling time, None
+        indicates unspecified timebase (either continuous or discrete time).
     squeeze : bool
         By default, if a system is single-input, single-output (SISO) then
         the outputs (and inputs) are returned as a 1D array (indexed by
@@ -79,16 +70,46 @@ class constructor, using the :func:`~control.frd` factory function or
         returned as a 3D array (indexed by the output, input, and
         frequency) even if the system is SISO. The default value can be set
         using config.defaults['control.squeeze_frequency_response'].
-    ninputs, noutputs, nstates : int
-        Number of inputs, outputs, and states of the underlying system.
+    sysname : str or None
+        Name of the system that generated the data.
+
+    Attributes
+    ----------
+    fresp : 3D array
+        Frequency response, indexed by output index, input index, and
+        frequency point.
+    frequency : 1D array
+        Array of frequency points for which data are available.
+    ninputs, noutputs : int
+        Number of inputs and outputs signals.
+    shape : tuple
+        2-tuple of I/O system dimension, (noutputs, ninputs).
     input_labels, output_labels : array of str
-        Names for the input and output variables.
-    sysname : str, optional
-        Name of the system.  For data generated using
-        :func:`~control.frequency_response`, stores the name of the system
-        that created the data.
+        Names for the input and output signals.
+    name : str
+        System name.  For data generated using
+        :func:`~control.frequency_response`, stores the name of the
+        system that created the data.
+    magnitude : array
+        Magnitude of the frequency response, indexed by frequency.
+    phase : array
+        Magnitude of the frequency response, indexed by frequency.
+
+    Other Parameters
+    ----------------
+    plot_type : str, optional
+        Set the type of plot to generate with ``plot()`` ('bode', 'nichols').
     title : str, optional
         Set the title to use when plotting.
+    plot_magnitude, plot_phase : bool, optional
+        If set to `False`, don't plot the magnitude or phase, respectively.
+    return_magphase : bool, optional
+        If True, then a frequency response data object will enumerate as a
+        tuple of the form (mag, phase, omega) where where ``mag`` is the
+        magnitude (absolute value, not dB or log10) of the system
+        frequency response, ``phase`` is the wrapped phase in radians of
+        the system frequency response, and ``omega`` is the (sorted)
+        frequencies at which the response was evaluated.
 
     See Also
     --------
@@ -148,22 +169,26 @@ class constructor, using the :func:`~control.frd` factory function or
     _epsw = 1e-8                #: Bound for exact frequency match
 
     def __init__(self, *args, **kwargs):
-        """Construct an FRD object.
-
-        The default constructor is FRD(d, w), where w is an iterable of
-        frequency points, and d is the matching frequency data.
+        """FrequencyResponseData(d, w[, dt])
 
-        If d is a single list, 1D array, or tuple, a SISO system description
-        is assumed. d can also be
+        Construct a frequency response data (FRD) object.
 
-        To call the copy constructor, call FRD(sys), where sys is a
-        FRD object.
+        The default constructor is FrequencyResponseData(d, w), where w is
+        an iterable of frequency points, and d is the matching frequency
+        data.  If d is a single list, 1D array, or tuple, a SISO system
+        description is assumed. d can also be a 2D array, in which case a
+        MIMO response is created.  To call the copy constructor, call
+        FrequencyResponseData(sys), where sys is a FRD object.  The
+        timebase for the frequency response can be provided using an
+        optional third argument or the 'dt' keyword.
 
-        To construct frequency response data for an existing LTI
-        object, other than an FRD, call FRD(sys, omega).
+        To construct frequency response data for an existing LTI object,
+        other than an FRD, call FrequencyResponseData(sys, omega).  This
+        functionality can also be obtained using :func:`frequency_response`
+        (which has additional options available).
 
-        The timebase for the frequency response can be provided using an
-        optional third argument or the 'dt' keyword.
+        See :class:`FrequencyResponseData` and :func:`frd` for more
+        information.
 
         """
         smooth = kwargs.pop('smooth', False)
@@ -182,11 +207,12 @@ def __init__(self, *args, **kwargs):
 
         if len(args) == 2:
             if not isinstance(args[0], FRD) and isinstance(args[0], LTI):
-                # not an FRD, but still a system, second argument should be
-                # the frequency range
+                # not an FRD, but still an LTI system, second argument
+                # should be the frequency range
                 otherlti = args[0]
                 self.omega = sort(np.asarray(args[1], dtype=float))
-                # calculate frequency response at my points
+
+                # calculate frequency response at specified points
                 if otherlti.isctime():
                     s = 1j * self.omega
                     self.fresp = otherlti(s, squeeze=False)
@@ -270,10 +296,9 @@ def __init__(self, *args, **kwargs):
                 arg_dt = common_timebase(args[0].dt, arg_dt)
             kwargs['dt'] = arg_dt
 
+        # Process signal names
         name, inputs, outputs, states, dt = _process_iosys_keywords(
                 kwargs, defaults, end=True)
-
-        # Process signal names
         InputOutputSystem.__init__(
             self, name=name, inputs=inputs, outputs=outputs, dt=dt)
 
@@ -284,17 +309,17 @@ def __init__(self, *args, **kwargs):
                 raise ValueError("can't smooth with only 1 frequency")
             degree = 3 if self.omega.size > 3 else self.omega.size - 1
 
-            self.ifunc = empty((self.fresp.shape[0], self.fresp.shape[1]),
+            self._ifunc = empty((self.fresp.shape[0], self.fresp.shape[1]),
                                dtype=tuple)
             for i in range(self.fresp.shape[0]):
                 for j in range(self.fresp.shape[1]):
-                    self.ifunc[i, j], u = splprep(
+                    self._ifunc[i, j], u = splprep(
                         u=self.omega, x=[real(self.fresp[i, j, :]),
                                          imag(self.fresp[i, j, :])],
                         w=1.0/(absolute(self.fresp[i, j, :]) + 0.001),
                         s=0.0, k=degree)
         else:
-            self.ifunc = None
+            self._ifunc = None
 
     #
     # Frequency response properties
@@ -424,7 +449,7 @@ def iosys_repr(self, format='loadable'):
         # Loadable format
         out = "FrequencyResponseData(\n{d},\n{w}{smooth}".format(
             d=repr(self.fresp), w=repr(self.omega),
-            smooth=(self.ifunc and ", smooth=True") or "")
+            smooth=(self._ifunc and ", smooth=True") or "")
 
         if config.defaults['control.default_dt'] != self.dt:
             out += ",\ndt={dt}".format(
@@ -493,7 +518,7 @@ def __mul__(self, other):
         # Convert the second argument to a transfer function.
         if isinstance(other, (int, float, complex, np.number)):
             return FRD(self.fresp * other, self.omega,
-                       smooth=(self.ifunc is not None))
+                       smooth=(self._ifunc is not None))
         else:
             other = _convert_to_frd(other, omega=self.omega)
 
@@ -511,16 +536,16 @@ def __mul__(self, other):
         for i in range(len(self.omega)):
             fresp[:, :, i] = self.fresp[:, :, i] @ other.fresp[:, :, i]
         return FRD(fresp, self.omega,
-                   smooth=(self.ifunc is not None) and
-                          (other.ifunc is not None))
+                   smooth=(self._ifunc is not None) and
+                          (other._ifunc is not None))
 
     def __rmul__(self, other):
         """Right Multiply two LTI objects (serial connection)."""
 
         # Convert the second argument to an frd function.
         if isinstance(other, (int, float, complex, np.number)):
             return FRD(self.fresp * other, self.omega,
-                       smooth=(self.ifunc is not None))
+                       smooth=(self._ifunc is not None))
         else:
             other = _convert_to_frd(other, omega=self.omega)
 
@@ -539,16 +564,16 @@ def __rmul__(self, other):
         for i in range(len(self.omega)):
             fresp[:, :, i] = other.fresp[:, :, i] @ self.fresp[:, :, i]
         return FRD(fresp, self.omega,
-                   smooth=(self.ifunc is not None) and
-                          (other.ifunc is not None))
+                   smooth=(self._ifunc is not None) and
+                          (other._ifunc is not None))
 
     # TODO: Division of MIMO transfer function objects is not written yet.
     def __truediv__(self, other):
         """Divide two LTI objects."""
 
         if isinstance(other, (int, float, complex, np.number)):
             return FRD(self.fresp * (1/other), self.omega,
-                       smooth=(self.ifunc is not None))
+                       smooth=(self._ifunc is not None))
         else:
             other = _convert_to_frd(other, omega=self.omega)
 
@@ -559,15 +584,15 @@ def __truediv__(self, other):
                 "systems.")
 
         return FRD(self.fresp/other.fresp, self.omega,
-                   smooth=(self.ifunc is not None) and
-                          (other.ifunc is not None))
+                   smooth=(self._ifunc is not None) and
+                          (other._ifunc is not None))
 
     # TODO: Division of MIMO transfer function objects is not written yet.
     def __rtruediv__(self, other):
         """Right divide two LTI objects."""
         if isinstance(other, (int, float, complex, np.number)):
             return FRD(other / self.fresp, self.omega,
-                       smooth=(self.ifunc is not None))
+                       smooth=(self._ifunc is not None))
         else:
             other = _convert_to_frd(other, omega=self.omega)
 
@@ -584,7 +609,7 @@ def __pow__(self, other):
             raise ValueError("Exponent must be an integer")
         if other == 0:
             return FRD(ones(self.fresp.shape), self.omega,
-                       smooth=(self.ifunc is not None))  # unity
+                       smooth=(self._ifunc is not None))  # unity
         if other > 0:
             return self * (self**(other-1))
         if other < 0:
@@ -637,7 +662,7 @@ def eval(self, omega, squeeze=None):
         if any(omega_array.imag > 0):
             raise ValueError("FRD.eval can only accept real-valued omega")
 
-        if self.ifunc is None:
+        if self._ifunc is None:
             elements = np.isin(self.omega, omega)  # binary array
             if sum(elements) < len(omega_array):
                 raise ValueError(
@@ -651,7 +676,7 @@ def eval(self, omega, squeeze=None):
             for i in range(self.noutputs):
                 for j in range(self.ninputs):
                     for k, w in enumerate(omega_array):
-                        frraw = splev(w, self.ifunc[i, j], der=0)
+                        frraw = splev(w, self._ifunc[i, j], der=0)
                         out[i, j, k] = frraw[0] + 1.0j * frraw[1]
 
         return _process_frequency_response(self, omega, out, squeeze=squeeze)
@@ -806,7 +831,7 @@ def feedback(self, other=1, sign=-1):
         resfresp = (myfresp @ linalg.inv(I_AB))
         fresp = np.moveaxis(resfresp, 0, 2)
 
-        return FRD(fresp, other.omega, smooth=(self.ifunc is not None))
+        return FRD(fresp, other.omega, smooth=(self._ifunc is not None))
 
     # Plotting interface
     def plot(self, plot_type=None, *args, **kwargs):
@@ -956,6 +981,8 @@ def frd(*args, **kwargs):
 
     Parameters
     ----------
+    sys : LTI (StateSpace or TransferFunction)
+        A linear system that will be evaluated for frequency response data.
     response : array_like or LTI system
         Complex vector with the system response or an LTI system that can
         be used to copmute the frequency response at a list of frequencies.
@@ -972,7 +999,7 @@ def frd(*args, **kwargs):
 
     Returns
     -------
-    sys : :class:`FrequencyResponseData`
+    sys : FrequencyResponseData
         New frequency response data system.
 
     Other Parameters

control/freqplot.py

@@ -1305,7 +1305,7 @@ def nyquist_response(
                 "Nyquist plot currently only supports SISO systems.")
 
         # Figure out the frequency range
-        if isinstance(sys, FrequencyResponseData) and sys.ifunc is None \
+        if isinstance(sys, FrequencyResponseData) and sys._ifunc is None \
            and not omega_range_given:
             omega_sys = sys.omega               # use system frequencies
         else: