Merge pull request #123 from murrayrm/doc-update

slivingston · web-flow · commit 99cc2e93acf9 · 2016-12-31T15:47:17.000-05:00
Small documentation updates
diff --git a/README.rst b/README.rst
@@ -41,7 +41,7 @@ functionality is limited or absent, and installation of slycot is recommended
 (see below).  Note that in order to install slycot, you will need a FORTRAN
 compiler on your machine.  The Slycot wrapper can be found at:
 
-https://github.com/jgoppert/Slycot
+https://github.com/python-control/Slycot
 
 Installation
 ============
diff --git a/control/__init__.py b/control/__init__.py
@@ -65,6 +65,8 @@
 from .ctrlutil import *
 from .frdata import *
 from .canonical import *
+from .robust import *
+from .config import *
 
 # Exceptions
 from .exception import *
diff --git a/control/config.py b/control/config.py
@@ -16,13 +16,22 @@
 
 # Set defaults to match MATLAB
 def use_matlab_defaults():
+    """
+    Use MATLAB compatible configuration settings
+        * Bode plots plot gain in dB, phase in degrees, frequency in Hertz
+    """
     # Bode plot defaults
     global bode_dB; bode_dB = True
     global bode_deg; bode_deg = True
     global bode_Hz; bode_Hz = True
 
 # Set defaults to match FBS (Astrom and Murray)
 def use_fbs_defaults():
+    """
+    Use `Astrom and Murray <http://fbsbook.org>`_ compatible settings
+        * Bode plots plot gain in powers of ten, phase in degrees, 
+          frequency in Hertz
+    """
     # Bode plot defaults
     global bode_dB; bode_dB = False
     global bode_deg; bode_deg = True
diff --git a/control/dtime.py b/control/dtime.py
@@ -65,7 +65,7 @@ def sample_system(sysc, Ts, method='zoh', alpha=None):
     Ts : real
         Sampling period
     method : string
-        Method to use for conversion: 'matched' (default), 'tustin', 'zoh'
+        Method to use for conversion: 'matched', 'tustin', 'zoh' (default)
 
     Returns
     -------
diff --git a/control/frdata.py b/control/frdata.py
@@ -469,7 +469,7 @@ def _convertToFRD(sys, omega, inputs=1, outputs=1):
                     sys.__class__)
 
 def frd(*args):
-    '''
+    """
     Construct a Frequency Response Data model, or convert a system
 
     frd models store the (measured) frequency response of a system.
@@ -501,5 +501,5 @@ def frd(*args):
     See Also
     --------
     ss, tf
-    '''
+    """
     return FRD(*args)
diff --git a/control/timeresp.py b/control/timeresp.py
@@ -1,78 +1,12 @@
 # timeresp.py - time-domain simulation routes
-"""
-Time domain simulation.
-
-This file contains a collection of functions that calculate
-time responses for linear systems.
-
-.. _time-series-convention:
-
-Convention for Time Series
---------------------------
-
-This is a convention for function arguments and return values that
-represent time series: sequences of values that change over time. It
-is used throughout the library, for example in the functions
-:func:`forced_response`, :func:`step_response`, :func:`impulse_response`,
-and :func:`initial_response`.
-
-.. note::
-    This convention is different from the convention used in the library
-    :mod:`scipy.signal`. In Scipy's convention the meaning of rows and columns
-    is interchanged.  Thus, all 2D values must be transposed when they are
-    used with functions from :mod:`scipy.signal`.
-
-Types:
-
-    * **Arguments** can be **arrays**, **matrices**, or **nested lists**.
-    * **Return values** are **arrays** (not matrices).
-
-The time vector is either 1D, or 2D with shape (1, n)::
-
-      T = [[t1,     t2,     t3,     ..., tn    ]]
-
-Input, state, and output all follow the same convention. Columns are different
-points in time, rows are different components. When there is only one row, a
-1D object is accepted or returned, which adds convenience for SISO systems::
-
-      U = [[u1(t1), u1(t2), u1(t3), ..., u1(tn)]
-           [u2(t1), u2(t2), u2(t3), ..., u2(tn)]
-           ...
-           ...
-           [ui(t1), ui(t2), ui(t3), ..., ui(tn)]]
+"""Time domain simulation.
 
-      Same for X, Y
+This file contains a collection of functions that calculate time
+responses for linear systems.  
 
-So, U[:,2] is the system's input at the third point in time; and U[1] or U[1,:]
-is the sequence of values for the system's second input.
+See doc/conventions.rst#time-series-conventions_ for more information
+on how time series data are represented.
 
-The initial conditions are either 1D, or 2D with shape (j, 1)::
-
-     X0 = [[x1]
-           [x2]
-           ...
-           ...
-           [xj]]
-
-As all simulation functions return *arrays*, plotting is convenient::
-
-    t, y = step(sys)
-    plot(t, y)
-
-The output of a MIMO system can be plotted like this::
-
-    t, y, x = lsim(sys, u, t)
-    plot(t, y[0], label='y_0')
-    plot(t, y[1], label='y_1')
-
-The convention also works well with the state space form of linear systems. If
-``D`` is the feedthrough *matrix* of a linear system, and ``U`` is its input
-(*matrix* or *array*), then the feedthrough part of the system's response,
-can be computed like this::
-
-    ft = D * U
-
-----------------------------------------------------------------
 """
 
 """Copyright (c) 2011 by California Institute of Technology
@@ -453,6 +387,9 @@ def step_response(sys, T=None, X0=0., input=None, output=None,
         If True, transpose all input and output arrays (for backward
         compatibility with MATLAB and scipy.signal.lsim)
 
+    return_x: bool
+        If True, return the state vector (default = False).
+
     Returns
     -------
     T: array
@@ -529,6 +466,9 @@ def initial_response(sys, T=None, X0=0., input=0, output=None,
         If True, transpose all input and output arrays (for backward
         compatibility with MATLAB and scipy.signal.lsim)
 
+    return_x: bool
+        If True, return the state vector (default = False).
+
     Returns
     -------
     T: array
@@ -599,6 +539,9 @@ def impulse_response(sys, T=None, X0=0., input=0, output=None,
         If True, transpose all input and output arrays (for backward
         compatibility with MATLAB and scipy.signal.lsim)
 
+    return_x: bool
+        If True, return the state vector (default = False).
+
     Returns
     -------
     T: array
diff --git a/doc/control.rst b/doc/control.rst
@@ -17,22 +17,31 @@ System creation
 
     ss
     tf
+    frd
     rss
     drss
 
+System interconnections
+=======================
+.. autosummary::
+   :toctree: generated/
+
+   append
+   connect
+   feedback
+   negate
+   parallel
+   series
+
 Frequency domain plotting
 =========================
 
 .. autosummary::
     :toctree: generated/
 
-    bode
     bode_plot
-    nyquist
     nyquist_plot
-    gangof4
     gangof4_plot
-    nichols
     nichols_plot
 
 Time domain simulation
@@ -47,74 +56,6 @@ Time domain simulation
     step_response
     phase_plot
 
-.. _time-series-convention:
-
-Convention for Time Series
---------------------------
-
-This is a convention for function arguments and return values that
-represent time series: sequences of values that change over time. It
-is used throughout the library, for example in the functions
-:func:`forced_response`, :func:`step_response`, :func:`impulse_response`,
-and :func:`initial_response`.
-
-.. note::
-    This convention is different from the convention used in the library
-    :mod:`scipy.signal`. In Scipy's convention the meaning of rows and columns
-    is interchanged.  Thus, all 2D values must be transposed when they are
-    used with functions from :mod:`scipy.signal`.
-
-Types:
-
-    * **Arguments** can be **arrays**, **matrices**, or **nested lists**.
-    * **Return values** are **arrays** (not matrices).
-
-The time vector is either 1D, or 2D with shape (1, n)::
-
-      T = [[t1,     t2,     t3,     ..., tn    ]]
-
-Input, state, and output all follow the same convention. Columns are different
-points in time, rows are different components. When there is only one row, a
-1D object is accepted or returned, which adds convenience for SISO systems::
-
-      U = [[u1(t1), u1(t2), u1(t3), ..., u1(tn)]
-           [u2(t1), u2(t2), u2(t3), ..., u2(tn)]
-           ...
-           ...
-           [ui(t1), ui(t2), ui(t3), ..., ui(tn)]]
-
-      Same for X, Y
-
-So, U[:,2] is the system's input at the third point in time; and U[1] or U[1,:]
-is the sequence of values for the system's second input.
-
-The initial conditions are either 1D, or 2D with shape (j, 1)::
-
-     X0 = [[x1]
-           [x2]
-           ...
-           ...
-           [xj]]
-
-As all simulation functions return *arrays*, plotting is convenient::
-
-    t, y = step(sys)
-    plot(t, y)
-
-The output of a MIMO system can be plotted like this::
-
-    t, y, x = lsim(sys, u, t)
-    plot(t, y[0], label='y_0')
-    plot(t, y[1], label='y_1')
-
-The convention also works well with the state space form of linear systems. If
-``D`` is the feedthrough *matrix* of a linear system, and ``U`` is its input
-(*matrix* or *array*), then the feedthrough part of the system's response,
-can be computed like this::
-
-    ft = D * U
-
-
 Block diagram algebra
 =====================
 .. autosummary::
@@ -160,6 +101,8 @@ Control system synthesis
     :toctree: generated/
 
     acker
+    h2syn
+    hinfsyn
     lqr
     place
 
@@ -183,12 +126,15 @@ Utility functions and conversions
     unwrap
     db2mag
     mag2db
+    damp
     isctime
     isdtime
+    issiso
     issys
     pade
     sample_system
     canonical_form
+    observable_form
     reachable_form
     ss2tf
     ssdata
diff --git a/doc/conventions.rst b/doc/conventions.rst
diff --git a/doc/index.rst b/doc/index.rst
diff --git a/doc/intro.rst b/doc/intro.rst
