* Made fixes to documentation (intro, matlab)

murrayrm · murrayrm · commit 701e83ec95f7 · 2011-06-26T02:44:09.000Z
* Got rid of unit test error in hsvd (convert slycot args to numpy array)
* Tracked down possible errors in convert_test (still in progress)

See ChangeLog for more detailed list of code that was modified
diff --git a/ChangeLog b/ChangeLog
@@ -1,3 +1,27 @@
+2011-06-25  Richard Murray  <murray@malabar.local>
+
+	* src/xferfcn.py (TransferFunction._common_den): changed tolerance
+	for detecting complex valued poles to a user-settable parameter,
+	with default value 1e-8.  This was an attempt to fix errors in the
+	convert_test.py unittest script (conversion routine was
+	misclassifying some poles as imaginary when they weren't).
+
+	* src/xferfcn.py (_convertToTransferFunction): converted arguments
+	to tb04ad to numpy arrays; fixes a unit test error in convert_test.py.
+
+	* src/statefbk.py (gram): convert system matrix passed to sb03md to
+	numpy array; this fixes a unit test error in modelsimp_test.py.
+
+	* src/matlab.py (impulse): got rid of X0 argument for impulse
+	response (not implemented in MATLAB).
+
+	* doc/intro.rst: added some quick start information
+
+	* src/matlab.py: added documentation for step, impulse, initial, lsim
+
+	* src/timeresp.py: fixed some MATLAB specific function names in
+	function doc strings
+
 2011-06-22  Richard Murray  <murray@malabar.local>
 
 	* doc/intro.rst: fixed some small types
diff --git a/doc/intro.rst b/doc/intro.rst
@@ -8,9 +8,10 @@ The python-control package is a set of python classes and functions
 that implement common operations for the analysis and design of
 feedback control systems.  The initial goal is to implement all of the
 functionality required to work through the examples in the textbook
-Feedback Systems by �str�m and Murray. A MATLAB compatibility package
-(control.matlab) is available that provides functions corresponding to
-the commands available in the MATLAB Control Systems Toolbox.
+Feedback Systems by Astrom and Murray. A MATLAB compatibility package
+(control.matlab) is available that provides many of the common
+functions corresponding to commands available in the MATLAB Control
+Systems Toolbox.
 
 In addition to the documentation here, there is a project wiki that
 contains some additional information about how to use the package
@@ -26,3 +27,19 @@ Some Differences from MATLAB
 * Transfer functions are only implemented for SISO systems (due to
   limitations in the underlying signals.lti class); use state space
   representations for MIMO systems.
+
+Getting Started
+---------------
+1. Download the latest release from http:sf.net/projects/python-control/files.
+2. Untar the source code in a temporary directory and run 'python setup.py
+   install' to build and install the code
+3. To see if things are working correctly, run ipython -pylab and run the 
+   script 'examples/secord-matlab.py'.  This should generate a set response,
+   Bode plot and Nyquist plot for a simple second order system.
+4. To see the commands that are available, run the following commands in
+   ipython::
+     >>> import control
+     >>> ?control.matlab
+5. If you want to have a MATLAB-like environment for running the control
+   toolbox, use::
+     >>> from control.matlab import *
diff --git a/src/matlab.py b/src/matlab.py
@@ -1128,21 +1128,217 @@ def dcgain(*args):
 # Call corresponding functions in timeresp, with arguments transposed
 
 def step(sys, T=None, X0=0., input=0, output=0, **keywords):
+    '''
+    Step response of a linear system
+    
+    If the system has multiple inputs or outputs (MIMO), one input and one 
+    output have to be selected for the simulation. The parameters `input` 
+    and `output` do this. All other inputs are set to 0, all other outputs 
+    are ignored.
+    
+    Parameters
+    ----------
+    sys: StateSpace, or TransferFunction
+        LTI system to simulate
+
+    T: array-like object, optional
+        Time vector (argument is autocomputed if not given)
+
+    X0: array-like or number, optional
+        Initial condition (default = 0)
+
+        Numbers are converted to constant arrays with the correct shape.
+
+    input: int
+        Index of the input that will be used in this simulation.
+
+    output: int
+        Index of the output that will be used in this simulation.
+
+    **keywords:
+        Additional keyword arguments control the solution algorithm for the 
+        differential equations. These arguments are passed on to the function
+        :func:`control.ForcedResponse`, which in turn passes them on to
+        :func:`scipy.integrate.odeint`. See the documentation for
+        :func:`scipy.integrate.odeint` for information about these
+        arguments.
+
+    Returns
+    -------
+    T: array
+        Time values of the output
+
+    yout: array
+        Response of the system
+    
+    See Also
+    --------
+    lsim, initial, impulse
+
+    Examples
+    --------
+    >>> T, yout = step(sys, T, X0)
+    '''
     T, yout = timeresp.StepResponse(sys, T, X0, input, output, 
                                    transpose = True, **keywords)
     return T, yout
 
-def impulse(sys, T=None, X0=0., input=0, output=0, **keywords):
-    T, yout = timeresp.ImpulseResponse(sys, T, X0, input, output, 
+def impulse(sys, T=None, input=0, output=0, **keywords):
+    '''
+    Impulse response of a linear system
+    
+    If the system has multiple inputs or outputs (MIMO), one input and
+    one output must be selected for the simulation. The parameters
+    `input` and `output` do this. All other inputs are set to 0, all
+    other outputs are ignored.
+    
+    Parameters
+    ----------
+    sys: StateSpace, TransferFunction
+        LTI system to simulate
+
+    T: array-like object, optional
+        Time vector (argument is autocomputed if not given)
+
+    input: int
+        Index of the input that will be used in this simulation.
+
+    output: int
+        Index of the output that will be used in this simulation.
+
+    **keywords:
+        Additional keyword arguments control the solution algorithm for the 
+        differential equations. These arguments are passed on to the function
+        :func:`lsim`, which in turn passes them on to
+        :func:`scipy.integrate.odeint`. See the documentation for
+        :func:`scipy.integrate.odeint` for information about these
+        arguments.
+
+    Returns
+    -------
+    T: array
+        Time values of the output
+    yout: array
+        Response of the system
+    
+    See Also
+    --------
+    lsim, step, initial
+
+    Examples
+    --------
+    >>> T, yout = impulse(sys, T) 
+    '''
+    T, yout = timeresp.ImpulseResponse(sys, T, 0, input, output, 
                                    transpose = True, **keywords)
     return T, yout
 
 def initial(sys, T=None, X0=0., input=0, output=0, **keywords):
+    '''
+    Initial condition response of a linear system
+    
+    If the system has multiple inputs or outputs (MIMO), one input and one 
+    output have to be selected for the simulation. The parameters `input` 
+    and `output` do this. All other inputs are set to 0, all other outputs 
+    are ignored.
+    
+    Parameters
+    ----------
+    sys: StateSpace, or TransferFunction
+        LTI system to simulate
+
+    T: array-like object, optional
+        Time vector (argument is autocomputed if not given)
+
+    X0: array-like object or number, optional
+        Initial condition (default = 0)
+
+        Numbers are converted to constant arrays with the correct shape.
+
+    input: int
+        Index of the input that will be used in this simulation.
+
+    output: int
+        Index of the output that will be used in this simulation.
+
+    **keywords:
+        Additional keyword arguments control the solution algorithm for the 
+        differential equations. These arguments are passed on to the function
+        :func:`lsim`, which in turn passes them on to
+        :func:`scipy.integrate.odeint`. See the documentation for
+        :func:`scipy.integrate.odeint` for information about these
+        arguments.
+
+
+    Returns
+    -------
+    T: array
+        Time values of the output
+    yout: array
+        Response of the system
+    
+    See Also
+    --------
+    lsim, step, impulse
+
+    Examples
+    --------
+    >>> T, yout = initial(sys, T, X0)
+    '''
     T, yout = timeresp.InitialResponse(sys, T, X0, input, output, 
                                    transpose = True, **keywords)
     return T, yout
 
 def lsim(sys, U=0., T=None, X0=0., **keywords):
+    '''
+    Simulate the output of a linear system.
+    
+    As a convenience for parameters `U`, `X0`:
+    Numbers (scalars) are converted to constant arrays with the correct shape.
+    The correct shape is inferred from arguments `sys` and `T`. 
+    
+    Parameters
+    ----------
+    sys: Lti (StateSpace, or TransferFunction)
+        LTI system to simulate
+        
+    U: array-like or number, optional
+        Input array giving input at each time `T` (default = 0).
+        
+        If `U` is ``None`` or ``0``, a special algorithm is used. This special 
+        algorithm is faster than the general algorithm, which is used otherwise.
+        
+    T: array-like 
+        Time steps at which the input is defined, numbers must be (strictly 
+        monotonic) increasing. 
+        
+    X0: array-like or number, optional
+        Initial condition (default = 0). 
+
+    **keywords:
+        Additional keyword arguments control the solution algorithm for the 
+        differential equations. These arguments are passed on to the function
+        :func:`scipy.integrate.odeint`. See the documentation for
+        :func:`scipy.integrate.odeint` for information about these
+        arguments.
+
+    Returns
+    -------
+    T: array
+        Time values of the output. 
+    yout: array
+        Response of the system. 
+    xout: array
+        Time evolution of the state vector. 
+    
+    See Also
+    --------
+    step, initial, impulse
+    
+    Examples
+    --------
+    >>> T, yout, xout = lsim(sys, U, T, X0)
+    '''
     T, yout, xout = timeresp.ForcedResponse(sys, T, U, X0,
                                              transpose = True, **keywords)
     return T, yout, xout
diff --git a/src/statefbk.py b/src/statefbk.py
@@ -328,7 +328,7 @@ def gram(sys,type):
         raise ControlSlycot("can't find slycot module 'sb03md'")
     n = sys.states
     U = np.zeros((n,n))
-    A = sys.A    
+    A = np.array(sys.A)         # convert to NumPy array for slycot
     X,scale,sep,ferr,w = sb03md(n, C, A, U, dico, job='X', fact='N', trana=tra)
     gram = X
     return gram
diff --git a/src/timeresp.py b/src/timeresp.py
@@ -419,11 +419,11 @@ def StepResponse(sys, T=None, X0=0., input=0, output=0, \
     
     See Also
     --------
-    lsim, initial, impulse
+    ForcedResponse, InitialResponse, ImpulseResponse
 
     Examples
     --------
-    >>> T, yout = step(sys, T, X0)
+    >>> T, yout = StepResponse(sys, T, X0)
     """
     sys = _convertToStateSpace(sys)
     sys = _mimo2siso(sys, input, output, warn_conversion=True)
@@ -491,11 +491,11 @@ def InitialResponse(sys, T=None, X0=0., input=0, output=0, transpose=False,
     
     See Also
     --------
-    lsim, step, impulse
+    ForcedResponse, ImpulseResponse, StepResponse
 
     Examples
     --------
-    >>> T, yout = InitialResponsesys, T, X0)
+    >>> T, yout = InitialResponse(sys, T, X0)
     """
     sys = _convertToStateSpace(sys) 
     sys = _mimo2siso(sys, input, output, warn_conversion=True)
@@ -564,7 +564,7 @@ def ImpulseResponse(sys, T=None, X0=0., input=0, output=0,
     
     See Also
     --------
-    lsim, step, initial
+    ForcedReponse, InitialResponse, StepResponse
 
     Examples
     --------
diff --git a/src/xferfcn.py b/src/xferfcn.py
diff --git a/tests/convert_test.py b/tests/convert_test.py
