DOC: update docstrings for system creation (see PR #163)

murrayrm · murrayrm · commit b19ca118dd99 · 2017-12-28T17:33:42.000-08:00
diff --git a/control/ctrlutil.py b/control/ctrlutil.py
@@ -45,6 +45,11 @@
 import numpy as np
 from numpy import pi
 
+# Hack for sphinx.ext.autodoc: if numpy is a mock import, then numpy.pi 
+# will be assigned to _Mock() and this generates a type error
+if not isinstance(pi, float):
+    pi = 3.14
+
 __all__ = ['unwrap', 'issys', 'db2mag', 'mag2db']
 
 # Utility function to unwrap an angle measurement
diff --git a/control/frdata.py b/control/frdata.py
@@ -57,7 +57,9 @@
 __all__ = ['FRD', 'frd']
 
 class FRD(LTI):
-    """A class for models defined by Frequency Response Data (FRD)
+    """FRD(d, w)
+
+    A class for models defined by frequency response data (FRD)
 
     The FRD class is used to represent systems in frequency response data form.
 
@@ -80,7 +82,9 @@ class FRD(LTI):
     epsw = 1e-8
 
     def __init__(self, *args, **kwargs):
-        """Construct an FRD object
+        """FRD(d, w)
+
+        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.
@@ -469,8 +473,9 @@ def _convertToFRD(sys, omega, inputs=1, outputs=1):
                     sys.__class__)
 
 def frd(*args):
-    """
-    Construct a Frequency Response Data model, or convert a system
+    """frd(d, w)
+
+    Construct a frequency response data model
 
     frd models store the (measured) frequency response of a system.
 
@@ -500,6 +505,6 @@ def frd(*args):
 
     See Also
     --------
-    ss, tf
+    FRD, ss, tf
     """
     return FRD(*args)
diff --git a/control/margins.py b/control/margins.py
@@ -48,7 +48,6 @@
 Date: 14 July 2011
 
 $Id$
-
 """
 
 import numpy as np
@@ -62,7 +61,7 @@
 # helper functions for stability_margins
 def _polyimsplit(pol):
     """split a polynomial with (iw) applied into a real and an
-       imaginary part with w applied"""
+    imaginary part with w applied"""
     rpencil = np.zeros_like(pol)
     ipencil = np.zeros_like(pol)
     rpencil[-1::-4] = 1.
@@ -294,8 +293,7 @@ def dstab(w):
 # Contributed by Steffen Waldherr <waldherr@ist.uni-stuttgart.de>
 #! TODO - need to add test functions
 def phase_crossover_frequencies(sys):
-    """
-    Compute frequencies and gains at intersections with real axis
+    """Compute frequencies and gains at intersections with real axis
     in Nyquist plot.
 
     Call as:
@@ -360,8 +358,8 @@ def margin(*args):
     Wcp : float
         Phase crossover frequency (corresponding to gain margin) (in rad/sec)
 
-   Margins are of SISO open-loop. If more than one crossover frequency is
-   detected, returns the lowest corresponding margin.
+    Margins are of SISO open-loop. If more than one crossover frequency is
+    detected, returns the lowest corresponding margin.
 
     Examples
     --------
diff --git a/control/robust.py b/control/robust.py
@@ -72,7 +72,6 @@ def h2syn(P,nmeas,ncon):
     >>> K = h2syn(P,nmeas,ncon)
 
     """
-
     #Check for ss system object, need a utility for this?
 
     #TODO: Check for continous or discrete, only continuous supported right now
@@ -116,11 +115,11 @@ def hinfsyn(P,nmeas,ncon):
     CL: closed loop system (State-space sys)
     gam: infinity norm of closed loop system
     rcond: 4-vector, reciprocal condition estimates of:
-           1: control transformation matrix
-           2: measurement transformation matrix
-           3: X-Ricatti equation
-           4: Y-Ricatti equation
-      TODO: document significance of rcond
+        1: control transformation matrix
+        2: measurement transformation matrix
+        3: X-Ricatti equation
+        4: Y-Ricatti equation
+    TODO: document significance of rcond
 
     Raises
     ------
diff --git a/control/statesp.py b/control/statesp.py
@@ -68,7 +68,9 @@
 __all__ = ['StateSpace', 'ss', 'rss', 'drss', 'tf2ss', 'ssdata']
 
 class StateSpace(LTI):
-    """A class for representing state-space models
+    """StateSpace(A, B, C, D[, dt])
+
+    A class for representing state-space models
 
     The StateSpace class is used to represent state-space realizations of linear
     time-invariant (LTI) systems:
@@ -88,15 +90,19 @@ class StateSpace(LTI):
     means the system timebase is not specified.  If 'dt' is set to True, the
     system will be treated as a discrete time system with unspecified
     sampling time.
-
     """
 
     def __init__(self, *args):
-        """Construct a state space object.
+        """
+        StateSpace(A, B, C, D[, dt])
 
-        The default constructor is StateSpace(A, B, C, D), where A, B, C, D are
-        matrices or equivalent objects.  To call the copy constructor, call
-        StateSpace(sys), where sys is a StateSpace object.
+        Construct a state space object.
+
+        The default constructor is StateSpace(A, B, C, D), where A, B, C, D
+        are matrices or equivalent objects.  To create a discrete time system,
+        use StateSpace(A, B, C, D, dt) where 'dt' is the sampling time (or
+        True for unspecified sampling time).  To call the copy constructor,
+        call StateSpace(sys), where sys is a StateSpace object.
 
         """
 
@@ -110,8 +116,7 @@ def __init__(self, *args):
         elif len(args) == 1:
             # Use the copy constructor.
             if not isinstance(args[0], StateSpace):
-                raise TypeError("The one-argument constructor can only take in \
-a StateSpace object.  Recived %s." % type(args[0]))
+               raise TypeError("The one-argument constructor can only take in a StateSpace object.  Received %s." % type(args[0]))
             A = args[0].A
             B = args[0].B
             C = args[0].C
@@ -956,7 +961,8 @@ def _mimo2simo(sys, input, warn_conversion=False):
     return sys
 
 def ss(*args):
-    """
+    """ss(A, B, C, D[, dt])
+
     Create a state space system.
 
     The function accepts either 1, 4 or 5 parameters:
@@ -1014,6 +1020,7 @@ def ss(*args):
 
     See Also
     --------
+    StateSpace
     tf
     ss2tf
     tf2ss
diff --git a/control/statesp.py+ b/control/statesp.py+
diff --git a/control/xferfcn.py b/control/xferfcn.py
