* Restructured documentation (not completed)

murrayrm · murrayrm · commit 61d203c18fb0 · 2012-01-08T03:33:41.000Z
* Added in code from Ryan Krauss for operation when slycot is missing
* Updated version number to 0.5b
* See ChangeLog for a more detailed list of changes
diff --git a/ChangeLog b/ChangeLog
@@ -1,3 +1,57 @@
+2012-01-07  Richard Murray  <murray@malabar.local>
+
+	* doc/modules.rst: added new sections for analysis, synthesis,
+	frequency plots and time response.
+
+	* doc/index.rst (Contents): added modules and examples.
+
+	* src/xferfcn.py (_convertToTransferFunction): added check for
+	slycot import error.  If not present, use signal.lti to perform the
+	conversion.  Only works for SISO.
+
+	* src/statesp.py (_convertToStateSpace): added check for slycot
+	import error, to allow basic functionality without the presence of
+	slycot (contributed by Ryan Krauss).
+
+	* tests/slycot_convert_test.py (TestSlycot.testTF): moved slycot
+	import into test function, so that test script still works even if
+	time response is not present.
+
+2011-08-09  Richard Murray  <murray@malabar.local>
+
+	* src/timeresp.py: fixed doc reference to time-series-convention
+
+2011-08-08  Richard Murray  <murray@malabar.local>
+
+	* doc/index.rst, doc/modules.rst: Moved MATLAB section into
+	python-control modules file
+
+2011-08-07  Richard Murray  <murray@malabar.local>
+
+	* doc/conf.py: added autosummary extension
+
+	* doc/timeresp.rst: New file containing listing of functions for
+	time responses (step, initial, etc)
+
+	* doc/freqplot.rst: New file listing functions for frequency
+	plots (bode, nyquist, etc)
+
+	* doc/modules.rst: New file that contains a listing of the major
+	modules in the toolbox
+
+	* doc/index.rst (Contents): Rearranged contents to put modules
+	documentation in a separate section.  Also added examples section
+	(not quite ready yet).
+
+2011-08-07  Richard Murray  <murray@malabar.local>
+
+	* examples/rss-balred.py: reordered outputs from call to matlab.step
+	(missed this the first time around)
+
+	* doc/matlab_strings.rst: Matlab -> MATLAB (proper spelling)
+
+	* setup.py, doc/conf.py: updated version to 0.5b
+
 2011-08-07  Richard Murray  <murray@malabar.local>
 
 	* doc/conf.py: Updated version numbers to 0.5a, regenerated
diff --git a/doc/analysis.rst b/doc/analysis.rst
@@ -0,0 +1,2 @@
+Control System Analysis
+***********************
diff --git a/doc/bdalg_strings.rst b/doc/bdalg_strings.rst
@@ -1,7 +1,7 @@
-Block Diagram Algebra Routines
-******************************
+Block Diagram Algebra
+*********************
+
+.. toctree::
 
-The Block Diagram Algebra Module
-================================
 .. automodule:: bdalg
    :members:
diff --git a/doc/class_strings.rst b/doc/class_strings.rst
@@ -1,12 +1,12 @@
 Python-Control Classes
 ********************** 
 
-The State Space Module
-======================
+State Space Class
+=================
 .. automodule:: statesp
    :members:
 
-The Transfer Function Module
-============================
+Transfer Function Class
+=======================
 .. automodule:: xferfcn
-   :members:
+   :members:
diff --git a/doc/conf.py b/doc/conf.py
@@ -34,7 +34,8 @@
 #   ``sphinx.ext.viewcode``    : Include highlighted source code in the 
 #                                documentation
 extensions = ['sphinx.ext.autodoc', 'numpydoc', 'sphinx.ext.pngmath', 
-              'sphinx.ext.intersphinx', 'sphinx.ext.todo']
+              'sphinx.ext.intersphinx', 'sphinx.ext.todo',
+              'sphinx.ext.autosummary']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -49,17 +50,17 @@
 master_doc = 'index'
 
 # General information about the project.
-project = u'Python Control'
+project = u'Python Control Systems Library'
 copyright = u'2011, Richard M. Murray et al.'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = '0.5a'
+version = '0.5b'
 # The full version, including alpha/beta/rc tags.
-release = '0.5a'
+release = '0.5b'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -99,7 +100,7 @@
 #should be linked to in this documentation.
 intersphinx_mapping = \
     {'scipy':('http://docs.scipy.org/doc/scipy/reference/', None),
-     'numpy':('http://docs.scipy.org/doc/numpy/reference/', None)}
+     'numpy':('http://docs.scipy.org/doc/numpy', None)}
 
 #If this is True, todo and todolist produce output, else they produce nothing. 
 #The default is False.
diff --git a/doc/examples.rst b/doc/examples.rst
@@ -0,0 +1,2 @@
+Examples
+********
diff --git a/doc/freqplot.rst b/doc/freqplot.rst
@@ -0,0 +1,15 @@
+Frequency Domain Plotting
+*************************
+
+.. toctree::
+
+Plotting routines
+=================
+.. autofunction:: freqplot.bode_plot
+.. autofunction:: freqplot.nyquist_plot
+.. autofunction:: freqplot.gangof4_plot
+.. autofunction:: nichols.nichols_plot
+
+Utility functions
+=================
+.. autofunction:: freqplot.default_frequency_range
diff --git a/doc/index.rst b/doc/index.rst
@@ -3,18 +3,23 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to Python-Control's documentation!
-==========================================
+Python Control User's Manual
+============================
+
+Welcome to the Python Control Systems Library (python-control) User's
+Manual.  This manual describes the python-control package, including
+all of the functions defined in the package and examples showing how
+to use the package.
 
 Contents:
 
 .. toctree::
+   :maxdepth: 2
    
    intro
    class_strings
-   modsimp_strings
-   matlab_strings
-   bdalg_strings
+   modules
+   examples
 
 Indices and tables
 ==================
diff --git a/doc/intro.rst b/doc/intro.rst
@@ -2,7 +2,13 @@
 Introduction
 ============
 
-Welcome to the Python-Control project.
+Welcome to the Python Control Systems Toolbox (python-control) User's
+Manual.  This manual contains information on using the python-control
+package, including documentation for all functions in the package and
+examples illustrating their use.
+
+Overview of the Toolbox
+-----------------------
 
 The python-control package is a set of python classes and functions
 that implement common operations for the analysis and design of
@@ -39,15 +45,22 @@ some thing to keep in mind:
 Getting Started
 ---------------
 1. Download 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.
+
+3. To see if things are working correctly, run ipython -pylab and run
+   the script 'examples/secord-matlab.py'.  This should generate a
+   step 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/doc/matlab_strings.rst b/doc/matlab_strings.rst
@@ -1,8 +1,6 @@
-Matlab-like Routines
-********************
+MATLAB Compatibility Module
+***************************
 
-The Matlab Module
-=================
 .. automodule:: matlab
     :members:
     
diff --git a/doc/modsimp_strings.rst b/doc/modsimp_strings.rst
@@ -1,7 +1,5 @@
 Model Simplification Tools
 **************************
 
-The modelsimp Module
-====================
 .. automodule:: modelsimp
     :members:
diff --git a/doc/modules.rst b/doc/modules.rst
@@ -0,0 +1,12 @@
+Python-Control Modules
+**********************
+
+.. toctree::
+
+   bdalg_strings
+   analysis
+   freqplot
+   timeresp
+   synthesis
+   modsimp_strings
+   matlab_strings
diff --git a/doc/synthesis.rst b/doc/synthesis.rst
@@ -0,0 +1,2 @@
+Control System Synthesis
+************************
diff --git a/doc/timeresp.rst b/doc/timeresp.rst
@@ -0,0 +1,8 @@
+Time Domain Simulation
+**********************
+
+.. automodule:: timeresp
+    :members:
+
+.. autofunction:: phaseplot.phase_plot
+.. autofunction:: phaseplot.box_grid
diff --git a/examples/rss-balred.py b/examples/rss-balred.py
@@ -26,8 +26,8 @@
 
 # Comparison of the step responses of the full and reduced systems
 plt.figure(1)
-t, y = mt.step(fsys)
-tr, yr = mt.step(rsys)
+y, t = mt.step(fsys)
+yr, tr = mt.step(rsys)
 plt.plot(t.T, y.T)
 plt.hold(True)
 plt.plot(tr.T, yr.T)
diff --git a/setup.py b/setup.py
@@ -4,7 +4,7 @@
 from setuptools import setup
 
 setup(name = 'control',
-      version = '0.5a',
+      version = '0.5b',
       description = 'Python Control Systems Library',
       author = 'Richard Murray',
       author_email = 'murray@cds.caltech.edu',
diff --git a/src/statesp.py b/src/statesp.py
@@ -75,7 +75,7 @@
 
 from numpy import all, angle, any, array, asarray, concatenate, cos, delete, \
     dot, empty, exp, eye, matrix, ones, pi, poly, poly1d, roots, shape, sin, \
-    zeros
+    zeros, squeeze
 from numpy.random import rand, randn
 from numpy.linalg import inv, det, solve
 from numpy.linalg.linalg import LinAlgError
@@ -459,28 +459,37 @@ def _convertToStateSpace(sys, **kw):
         # Already a state space system; just return it
         return sys
     elif isinstance(sys, xferfcn.TransferFunction):
-        from slycot import td04ad
-        if len(kw):
-            raise TypeError("If sys is a TransferFunction, _convertToStateSpace \
-cannot take keywords.")
+        try:
+            from slycot import td04ad
+            if len(kw):
+                raise TypeError("If sys is a TransferFunction, _convertToStateSpace \
+    cannot take keywords.")
+
+            # Change the numerator and denominator arrays so that the transfer
+            # function matrix has a common denominator.
+            num, den = sys._common_den()
+            # Make a list of the orders of the denominator polynomials.
+            index = [len(den) - 1 for i in range(sys.outputs)]
+            # Repeat the common denominator along the rows.
+            den = array([den for i in range(sys.outputs)])
+            # TODO: transfer function to state space conversion is still buggy!
+            #print num
+            #print shape(num)
+            ssout = td04ad('R',sys.inputs, sys.outputs, index, den, num,tol=0.0)
+
+            states = ssout[0]
+            return StateSpace(ssout[1][:states, :states],
+                ssout[2][:states, :sys.inputs], 
+                ssout[3][:sys.outputs, :states], 
+                ssout[4])
+        except ImportError:
+            lti_sys = lti(squeeze(sys.num), squeeze(sys.den))#<-- do we want to squeeze first
+                                                               # and check dimenations?  I think
+                                                               # this will fail if num and den aren't 1-D
+                                                               # after the squeeze
+            return StateSpace(lti_sys.A, lti_sys.B, lti_sys.C, lti_sys.D)
+            
 
-        # Change the numerator and denominator arrays so that the transfer
-        # function matrix has a common denominator.
-        num, den = sys._common_den()
-        # Make a list of the orders of the denominator polynomials.
-        index = [len(den) - 1 for i in range(sys.outputs)]
-        # Repeat the common denominator along the rows.
-        den = array([den for i in range(sys.outputs)])
-        # TODO: transfer function to state space conversion is still buggy!
-        #print num
-        #print shape(num)
-        ssout = td04ad('R',sys.inputs, sys.outputs, index, den, num,tol=0.0)
-    
-        states = ssout[0]
-        return StateSpace(ssout[1][:states, :states],
-            ssout[2][:states, :sys.inputs], 
-            ssout[3][:sys.outputs, :states], 
-            ssout[4])
     elif isinstance(sys, (int, long, float, complex)):
         if "inputs" in kw:
             inputs = kw["inputs"]
@@ -627,8 +636,8 @@ def _mimo2siso(sys, input, output, warn_conversion):
     
     If ``sys`` is already a SISO system, it will be returned unaltered. 
     
-    Parameters:
-    
+    Parameters
+    ----------
     sys: StateSpace
         Linear (MIMO) system that should be converted.
     input: int
diff --git a/src/xferfcn.py b/src/xferfcn.py
diff --git a/tests/slycot_convert_test.py b/tests/slycot_convert_test.py

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+Control System Analysis`
	`2`	`+***********************`