update linear.rst and associated doc files and function docstrings

Author: murrayrm

control/lti.py

@@ -124,9 +124,8 @@ def frequency_response(self, omega=None, squeeze=None):
             outputs=self.output_labels, plot_type='bode')
 
     def dcgain(self):
-        """Return the zero-frequency gain"""
-        raise NotImplementedError("dcgain not implemented for %s objects" %
-                                  str(self.__class__))
+        """Return the zero-frequency (DC) gain."""
+        return NotImplemented
 
     def _dcgain(self, warn_infinite):
         zeroresp = self(0 if self.isctime() else 1,

control/margins.py

@@ -267,13 +267,14 @@ def stability_margins(sysdata, returnall=False, epsw=0.0, method='best'):
         and not returned as margin.
     method : string, optional
         Method to use (default is 'best'):
-        'poly': use polynomial method if passed a :class:`LTI` system.
-        'frd': calculate crossover frequencies using numerical interpolation
-        of a :class:`FrequencyResponseData` representation of the system if
-        passed a :class:`LTI` system.
-        'best': use the 'poly' method if possible, reverting to 'frd' if it is
-        detected that numerical inaccuracy is likey to arise in the 'poly'
-        method for for discrete-time systems.
+
+        * 'poly': use polynomial method if passed a :class:`LTI` system.
+        * 'frd': calculate crossover frequencies using numerical
+          interpolation of a :class:`FrequencyResponseData` representation
+          of the system if passed a :class:`LTI` system.
+        * 'best': use the 'poly' method if possible, reverting to 'frd' if
+          it is detected that numerical inaccuracy is likey to arise in the
+          'poly' method for for discrete-time systems.
 
     Returns
     -------

control/robust.py

@@ -2,42 +2,10 @@
 #
 # Author: Steve Brunton, Kevin Chen, Lauren Padilla
 # Date: 24 Dec 2010
-#
-# This file contains routines for obtaining reduced order models
-#
-# Copyright (c) 2010 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.
-#
-# $Id$
+
+"""
+This file contains routines for obtaining reduced order models.
+"""
 
 import warnings
 

control/statesp.py

@@ -1293,7 +1293,7 @@ def sample(self, Ts, method='zoh', alpha=None, prewarp_frequency=None,
         return StateSpace(sysd, **kwargs)
 
     def dcgain(self, warn_infinite=False):
-        """Return the zero-frequency gain.
+        """Return the zero-frequency ("DC") gain.
 
         The zero-frequency gain of a continuous-time state-space
         system is given by:
@@ -1841,9 +1841,6 @@ def ssdata(sys):
 def linfnorm(sys, tol=1e-10):
     """L-infinity norm of a linear system.
 
-    .. deprecated:: 0.10.2
-        This functionality is now available in :func:`sysnorm`.
-
     Parameters
     ----------
     sys : LTI (StateSpace or TransferFunction)
@@ -1867,8 +1864,6 @@ def linfnorm(sys, tol=1e-10):
     --------
     slycot.ab13dd : the Slycot routine linfnorm that does the calculation
     """
-    warn("linfnorm() is deprecated; use sysnorm(sys, p='inf')", FutureWarning)
-
     if ab13dd is None:
         raise ControlSlycot("Can't find slycot module 'ab13dd'")
 

control/sysnorm.py

@@ -18,7 +18,7 @@
 
 import control as ct
 
-__all__ = ['norm']
+__all__ = ['system_norm', 'norm']
 
 #------------------------------------------------------------------------------
 
@@ -83,24 +83,26 @@ def _h2norm_slycot(sys, print_warning=True):
 
 #------------------------------------------------------------------------------
 
-def norm(system, p=2, tol=1e-6, print_warning=True, method=None):
-    """Computes norm of system.
+def system_norm(system, p=2, tol=1e-6, print_warning=True, method=None):
+    """Computes the input/output norm of system.
     
     Parameters
     ----------
     system : LTI (:class:`StateSpace` or :class:`TransferFunction`)
-        System in continuous or discrete time for which the norm should be computed.
+        System in continuous or discrete time for which the norm should
+        be computed.
     p : int or str
-        Type of norm to be computed. ``p=2`` gives the H2 norm, and ``p='inf'`` gives the L-infinity norm.
+        Type of norm to be computed. `p=2` gives the H2 norm, and
+        `p='inf'` gives the L-infinity norm.
     tol : float
         Relative tolerance for accuracy of L-infinity norm computation. Ignored
-        unless ``p='inf'``.
+        unless `p='inf'`.
     print_warning : bool
         Print warning message in case norm value may be uncertain.
     method : str, optional
         Set the method used for computing the result.  Current methods are
-        ``'slycot'`` and ``'scipy'``. If set to ``None`` (default), try ``'slycot'`` first
-        and then ``'scipy'``.
+        'slycot' and 'scipy'. If set to `None` (default), try 'slycot' first
+        and then 'scipy'.
     
     Returns
     -------
@@ -121,7 +123,8 @@ def norm(system, p=2, tol=1e-6, print_warning=True, method=None):
     """
 
     if not isinstance(system, (ct.StateSpace, ct.TransferFunction)):
-        raise TypeError('Parameter ``system``: must be a ``StateSpace`` or ``TransferFunction``')
+        raise TypeError(
+            "Parameter `system`: must be a `StateSpace` or `TransferFunction`")
 
     G = ct.ss(system)
     A = G.A
@@ -292,3 +295,5 @@ def _Hamilton_matrix(gamma):
     else:
         raise ct.ControlArgument(f"Norm computation for p={p} currently not supported.")           
 
+
+norm = system_norm

control/xferfcn.py

@@ -1202,7 +1202,7 @@ def sample(self, Ts, method='zoh', alpha=None, prewarp_frequency=None,
         return TransferFunction(sysd, name=name, **kwargs)
 
     def dcgain(self, warn_infinite=False):
-        """Return the zero-frequency (or DC) gain.
+        """Return the zero-frequency ("DC") gain.
 
         For a continous-time transfer function G(s), the DC gain is G(0)
         For a discrete-time transfer function G(z), the DC gain is G(1)

doc/conf.py

@@ -121,6 +121,9 @@
 # Set the default role to render items in backticks as code
 default_role = 'py:obj'
 
+# Align inline math with text
+imgmath_use_preview = True
+
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.

doc/functions.rst

@@ -112,11 +112,12 @@ Control system analysis
     get_input_ff_index
     get_output_fb_index
     ispassive
+    linfnorm
     margin
-    norm
     solve_passivity_LMI
     stability_margins
     step_info
+    system_norm
     phase_crossover_frequencies
     poles
     zeros

doc/intro.rst

@@ -7,6 +7,7 @@ Guide.  This guide contains information on using the python-control
 package, including documentation for all functions in the package and
 examples illustrating their use.
 
+
 Package overview
 ================
 
@@ -16,6 +17,7 @@ Package overview
    :no-inherited-members:
    :no-special-members:
 
+
 Installation
 ============
 
@@ -82,6 +84,35 @@ control package::
 Note that Google colab does not currently support Slycot, so some
 functionality may not be available.
 
+
+Package conventions
+===================
+
+The python-control package makes use of a few naming and calling conventions:
+
+* Function names are written in lower case with underscores between
+  words ('frequency_response').
+
+* Class names use camel case ('StateSpace', 'ControlPlot', etc) and
+  instances of the class are created with "factory functions" ('ss')
+  or as the output of an operation ('bode_plot').
+
+* Functions that return multiple values use either objects (with
+  elements for each return value) or tuples.  For those functions that
+  return tuples, the underscore variable can be used if only some of
+  the return values are needed::
+
+    K, _, _ = lqr(sys)
+
+* Python-control supports both single-input, single-output (SISO)
+  systems and mullti-input, multi-output (MIMO) systems, including
+  time and frequency responses.  By default, SISO systems will
+  typically generate objects that have the input and output dimensions
+  supressed (using the NumPy :func:`~numpy.squeeze` function).  The
+  `squeeze` keyword can be set to `False` to force functions to return
+  objects that include the input and output dimensions.
+
+
 Some differences from MATLAB
 ============================
 
@@ -102,11 +133,11 @@ some things to keep in mind:
   vectors implemented as nested list .  So [1 2 3] must be written as
   [1, 2, 3] and matrices are written using 2D nested lists, e.g., [[1,
   2], [3, 4]].
-* Functions that return multiple values use either objects (with
-  elements for each return value) or tuples.  The number of elements
-  in a tuple is fixed and so functions that return variable numbers of
-  return values will have a parameter of the form `return_<val>`
-  that is used to return additional data.
+* Functions that in MATLAB would return variable numbers of values
+  will have a parameter of the form `return_<val>` that is used to
+  return additional data.  (These functions usually return an object of
+  a class that has attributpes that can be used to access the
+  information and this is the preferred usage pattern.)
 * You cannot use braces for collections; use tuples instead.
 * Time series data have time as the final index (see
   :ref:`time-series-convention`).