Merge pull request #633 from murrayrm/docstring_updates

Documentation updates:
* Make documentation for classes more consistent
* Include documentation for __call__
* Correct documentation for iosys updfcn and outfcn

control/descfcn.py

@@ -26,7 +26,7 @@
 
 # Class for nonlinearities with a built-in describing function
 class DescribingFunctionNonlinearity():
-    """Base class for nonlinear systems with a describing function
+    """Base class for nonlinear systems with a describing function.
 
     This class is intended to be used as a base class for nonlinear functions
     that have an analytically defined describing function.  Subclasses should
@@ -36,16 +36,16 @@ class DescribingFunctionNonlinearity():
 
     """
     def __init__(self):
-        """Initailize a describing function nonlinearity (optional)"""
+        """Initailize a describing function nonlinearity (optional)."""
         pass
 
     def __call__(self, A):
-        """Evaluate the nonlinearity at a (scalar) input value"""
+        """Evaluate the nonlinearity at a (scalar) input value."""
         raise NotImplementedError(
             "__call__() not implemented for this function (internal error)")
 
     def describing_function(self, A):
-        """Return the describing function for a nonlinearity
+        """Return the describing function for a nonlinearity.
 
         This method is used to allow analytical representations of the
         describing function for a nonlinearity.  It turns the (complex) value
@@ -56,7 +56,7 @@ def describing_function(self, A):
             "describing function not implemented for this function")
 
     def _isstatic(self):
-        """Return True if the function has no internal state (memoryless)
+        """Return True if the function has no internal state (memoryless).
 
         This internal function is used to optimize numerical computation of
         the describing function.  It can be set to `True` if the instance
@@ -329,7 +329,7 @@ def _find_intersection(L1a, L1b, L2a, L2b):
 
 # Saturation nonlinearity
 class saturation_nonlinearity(DescribingFunctionNonlinearity):
-    """Create a saturation nonlinearity for use in describing function analysis
+    """Create saturation nonlinearity for use in describing function analysis.
 
     This class creates a nonlinear function representing a saturation with
     given upper and lower bounds, including the describing function for the
@@ -381,7 +381,7 @@ def describing_function(self, A):
 
 # Relay with hysteresis (FBS2e, Example 10.12)
 class relay_hysteresis_nonlinearity(DescribingFunctionNonlinearity):
-    """Relay w/ hysteresis nonlinearity for use in describing function analysis
+    """Relay w/ hysteresis nonlinearity for describing function analysis.
 
     This class creates a nonlinear function representing a a relay with
     symmetric upper and lower bounds of magnitude `b` and a hysteretic region
@@ -437,7 +437,7 @@ def describing_function(self, A):
 
 # Friction-dominated backlash nonlinearity (#48 in Gelb and Vander Velde, 1968)
 class friction_backlash_nonlinearity(DescribingFunctionNonlinearity):
-    """Backlash nonlinearity for use in describing function analysis
+    """Backlash nonlinearity for describing function analysis.
 
     This class creates a nonlinear function representing a friction-dominated
     backlash nonlinearity ,including the describing function for the

control/flatsys/basis.py

@@ -47,6 +47,11 @@ class BasisFamily:
 
       :math:`z_i^{(q)}(t)` = basis.eval_deriv(self, i, j, t)
 
+    Parameters
+    ----------
+    N : int
+        Order of the basis set.
+
     """
     def __init__(self, N):
         """Create a basis family of order N."""

control/flatsys/bezier.py

@@ -43,7 +43,7 @@
 from .basis import BasisFamily
 
 class BezierFamily(BasisFamily):
-    r"""Polynomial basis functions.
+    r"""Bezier curve basis functions.
 
     This class represents the family of polynomials of the form
 

control/flatsys/flatsys.py

@@ -54,8 +54,59 @@ class FlatSystem(NonlinearIOSystem):
     """Base class for representing a differentially flat system.
 
     The FlatSystem class is used as a base class to describe differentially
-    flat systems for trajectory generation.  The class must implement two
-    functions:
+    flat systems for trajectory generation.  The output of the system does not
+    need to be the differentially flat output.
+
+    Parameters
+    ----------
+    forward : callable
+        A function to compute the flat flag given the states and input.
+    reverse : callable
+        A function to compute the states and input given the flat flag.
+    updfcn : callable, optional
+        Function returning the state update function
+
+            `updfcn(t, x, u[, param]) -> array`
+
+        where `x` is a 1-D array with shape (nstates,), `u` is a 1-D array
+        with shape (ninputs,), `t` is a float representing the currrent
+        time, and `param` is an optional dict containing the values of
+        parameters used by the function.  If not specified, the state
+        space update will be computed using the flat system coordinates.
+    outfcn : callable
+        Function returning the output at the given state
+
+            `outfcn(t, x, u[, param]) -> array`
+
+        where the arguments are the same as for `upfcn`.  If not
+        specified, the output will be the flat outputs.
+    inputs : int, list of str, or None
+        Description of the system inputs.  This can be given as an integer
+        count or as a list of strings that name the individual signals.
+        If an integer count is specified, the names of the signal will be
+        of the form `s[i]` (where `s` is one of `u`, `y`, or `x`).  If
+        this parameter is not given or given as `None`, the relevant
+        quantity will be determined when possible based on other
+        information provided to functions using the system.
+    outputs : int, list of str, or None
+        Description of the system outputs.  Same format as `inputs`.
+    states : int, list of str, or None
+        Description of the system states.  Same format as `inputs`.
+    dt : None, True or float, optional
+        System timebase.  None (default) indicates continuous
+        time, True indicates discrete time with undefined sampling
+        time, positive number is discrete time with specified
+        sampling time.
+    params : dict, optional
+        Parameter values for the systems.  Passed to the evaluation
+        functions for the system as default values, overriding internal
+        defaults.
+    name : string, optional
+        System name (used for specifying signals)
+
+    Notes
+    -----
+    The class must implement two functions:
 
     zflag = flatsys.foward(x, u)
         This function computes the flag (derivatives) of the flat output.
@@ -83,65 +134,13 @@ def __init__(self,
                  updfcn=None, outfcn=None,      # I/O system
                  inputs=None, outputs=None,
                  states=None, params={}, dt=None, name=None):
-        """Create a differentially flat input/output system.
+        """Create a differentially flat I/O system.
 
         The FlatIOSystem constructor is used to create an input/output system
-        object that also represents a differentially flat system.  The output
-        of the system does not need to be the differentially flat output.
-
-        Parameters
-        ----------
-        forward : callable
-            A function to compute the flat flag given the states and input.
-        reverse : callable
-            A function to compute the states and input given the flat flag.
-        updfcn : callable, optional
-            Function returning the state update function
-
-                `updfcn(t, x, u[, param]) -> array`
-
-            where `x` is a 1-D array with shape (nstates,), `u` is a 1-D array
-            with shape (ninputs,), `t` is a float representing the currrent
-            time, and `param` is an optional dict containing the values of
-            parameters used by the function.  If not specified, the state
-            space update will be computed using the flat system coordinates.
-        outfcn : callable
-            Function returning the output at the given state
-
-                `outfcn(t, x, u[, param]) -> array`
-
-            where the arguments are the same as for `upfcn`.  If not
-            specified, the output will be the flat outputs.
-        inputs : int, list of str, or None
-            Description of the system inputs.  This can be given as an integer
-            count or as a list of strings that name the individual signals.
-            If an integer count is specified, the names of the signal will be
-            of the form `s[i]` (where `s` is one of `u`, `y`, or `x`).  If
-            this parameter is not given or given as `None`, the relevant
-            quantity will be determined when possible based on other
-            information provided to functions using the system.
-        outputs : int, list of str, or None
-            Description of the system outputs.  Same format as `inputs`.
-        states : int, list of str, or None
-            Description of the system states.  Same format as `inputs`.
-        dt : None, True or float, optional
-            System timebase.  None (default) indicates continuous
-            time, True indicates discrete time with undefined sampling
-            time, positive number is discrete time with specified
-            sampling time.
-        params : dict, optional
-            Parameter values for the systems.  Passed to the evaluation
-            functions for the system as default values, overriding internal
-            defaults.
-        name : string, optional
-            System name (used for specifying signals)
-
-        Returns
-        -------
-        InputOutputSystem
-            Input/output system object
+        object that also represents a differentially flat system.
 
         """
+
         # TODO: specify default update and output functions
         if updfcn is None: updfcn = self._flat_updfcn
         if outfcn is None: outfcn = self._flat_outfcn
@@ -158,6 +157,7 @@ def __init__(self,
         # Save the length of the flat flag
 
     def forward(self, x, u, params={}):
+
         """Compute the flat flag given the states and input.
 
         Given the states and inputs for a system, compute the flat

control/flatsys/linflat.py

@@ -42,46 +42,48 @@
 
 
 class LinearFlatSystem(FlatSystem, LinearIOSystem):
+    """Base class for a linear, differentially flat system.
+
+    This class is used to create a differentially flat system representation
+    from a linear system.
+
+    Parameters
+    ----------
+    linsys : StateSpace
+        LTI StateSpace system to be converted
+    inputs : int, list of str or None, optional
+        Description of the system inputs.  This can be given as an integer
+        count or as a list of strings that name the individual signals.
+        If an integer count is specified, the names of the signal will be
+        of the form `s[i]` (where `s` is one of `u`, `y`, or `x`).  If
+        this parameter is not given or given as `None`, the relevant
+        quantity will be determined when possible based on other
+        information provided to functions using the system.
+    outputs : int, list of str or None, optional
+        Description of the system outputs.  Same format as `inputs`.
+    states : int, list of str, or None, optional
+        Description of the system states.  Same format as `inputs`.
+    dt : None, True or float, optional
+        System timebase.  None (default) indicates continuous
+        time, True indicates discrete time with undefined sampling
+        time, positive number is discrete time with specified
+        sampling time.
+    params : dict, optional
+        Parameter values for the systems.  Passed to the evaluation
+        functions for the system as default values, overriding internal
+        defaults.
+    name : string, optional
+        System name (used for specifying signals)
+
+    """
+
     def __init__(self, linsys, inputs=None, outputs=None, states=None,
                  name=None):
         """Define a flat system from a SISO LTI system.
 
         Given a reachable, single-input/single-output, linear time-invariant
         system, create a differentially flat system representation.
 
-        Parameters
-        ----------
-        linsys : StateSpace
-            LTI StateSpace system to be converted
-        inputs : int, list of str or None, optional
-            Description of the system inputs.  This can be given as an integer
-            count or as a list of strings that name the individual signals.
-            If an integer count is specified, the names of the signal will be
-            of the form `s[i]` (where `s` is one of `u`, `y`, or `x`).  If
-            this parameter is not given or given as `None`, the relevant
-            quantity will be determined when possible based on other
-            information provided to functions using the system.
-        outputs : int, list of str or None, optional
-            Description of the system outputs.  Same format as `inputs`.
-        states : int, list of str, or None, optional
-            Description of the system states.  Same format as `inputs`.
-        dt : None, True or float, optional
-            System timebase.  None (default) indicates continuous
-            time, True indicates discrete time with undefined sampling
-            time, positive number is discrete time with specified
-            sampling time.
-        params : dict, optional
-            Parameter values for the systems.  Passed to the evaluation
-            functions for the system as default values, overriding internal
-            defaults.
-        name : string, optional
-            System name (used for specifying signals)
-
-        Returns
-        -------
-        iosys : LinearFlatSystem
-            Linear system represented as an flat input/output system
-
         """
         # Make sure we can handle the system
         if (not control.isctime(linsys)):

control/flatsys/systraj.py

@@ -41,30 +41,29 @@
 class SystemTrajectory:
     """Class representing a system trajectory.
 
-    The `SystemTrajectory` class is used to represent the trajectory of
-    a (differentially flat) system.  Used by the
-    :func:`~control.trajsys.point_to_point` function to return a
-    trajectory.
+    The `SystemTrajectory` class is used to represent the
+    trajectory of a (differentially flat) system.  Used by the
+    :func:`~control.trajsys.point_to_point` function to return a trajectory.
 
-    """
-    def __init__(self, sys, basis, coeffs=[], flaglen=[]):
-        """Initilize a system trajectory object.
+    Parameters
+    ----------
+    sys : FlatSystem
+        Flat system object associated with this trajectory.
+    basis : BasisFamily
+        Family of basis vectors to use to represent the trajectory.
+    coeffs : list of 1D arrays, optional
+        For each flat output, define the coefficients of the basis
+        functions used to represent the trajectory.  Defaults to an empty
+        list.
+    flaglen : list of ints, optional
+        For each flat output, the number of derivatives of the flat
+        output used to define the trajectory.  Defaults to an empty
+        list.
 
-        Parameters
-        ----------
-        sys : FlatSystem
-            Flat system object associated with this trajectory.
-        basis : BasisFamily
-            Family of basis vectors to use to represent the trajectory.
-        coeffs : list of 1D arrays, optional
-            For each flat output, define the coefficients of the basis
-            functions used to represent the trajectory.  Defaults to an empty
-            list.
-        flaglen : list of ints, optional
-            For each flat output, the number of derivatives of the flat output
-            used to define the trajectory.  Defaults to an empty list.
+    """
 
-        """
+    def __init__(self, sys, basis, coeffs=[], flaglen=[]):
+        """Initilize a system trajectory object."""
         self.nstates = sys.nstates
         self.ninputs = sys.ninputs
         self.system = sys