Merge pull request #228 from murrayrm/doc_updates

murrayrm · web-flow · commit 4b0101cf00a4 · 2018-07-29T15:17:20.000-07:00
Documentation updates
diff --git a/README.rst b/README.rst
@@ -24,7 +24,7 @@ Features
 Links
 =====
 
-- Project home page: http://python-control.sourceforge.net
+- Project home page: http://python-control.org
 - Source code repository: https://github.com/python-control/python-control
 - Documentation: http://python-control.readthedocs.org/
 - Issue tracker: https://github.com/python-control/python-control/issues
@@ -46,7 +46,7 @@ https://github.com/python-control/Slycot
 Installation
 ============
 
-The package may be installed using pip or distutils.
+The package may be installed using pip, conda, or distutils.
 
 Pip
 ---
@@ -56,6 +56,14 @@ To install using pip::
   pip install slycot   # optional
   pip install control
 
+conda-forge
+-----------
+
+Binaries are available from conda-forge for selected platforms (Linux and
+MacOS).  Install using
+
+  conda install -c conda-forge control
+
 Distutils
 ---------
 
diff --git a/control/config.py b/control/config.py
@@ -18,6 +18,8 @@
 def use_matlab_defaults():
     """
     Use MATLAB compatible configuration settings
+
+    The following conventions are used:
         * Bode plots plot gain in dB, phase in degrees, frequency in Hertz
     """
     # Bode plot defaults
@@ -28,7 +30,9 @@ def use_matlab_defaults():
 # Set defaults to match FBS (Astrom and Murray)
 def use_fbs_defaults():
     """
-    Use `Astrom and Murray <http://fbsbook.org>`_ compatible settings
+    Use `Feedback Systems <http://fbsbook.org>`_ (FBS) compatible settings
+
+    The following conventions are used:
         * Bode plots plot gain in powers of ten, phase in degrees,
           frequency in Hertz
     """
diff --git a/control/frdata.py b/control/frdata.py
@@ -452,8 +452,8 @@ def _convertToFRD(sys, omega, inputs=1, outputs=1):
     scalar, then the number of inputs and outputs can be specified
     manually, as in:
 
-    >>> sys = _convertToFRD(3.) # Assumes inputs = outputs = 1
-    >>> sys = _convertToFRD(1., inputs=3, outputs=2)
+    >>> frd = _convertToFRD(3., omega) # Assumes inputs = outputs = 1
+    >>> frd = _convertToFRD(1., omegs, inputs=3, outputs=2)
 
     In the latter example, sys's matrix transfer function is [[1., 1., 1.]
                                                               [1., 1., 1.]].
diff --git a/control/freqplot.py b/control/freqplot.py
@@ -70,8 +70,8 @@ def bode_plot(syslist, omega=None, dB=None, Hz=None, deg=None,
     ----------
     syslist : linsys
         List of linear input/output systems (single system is OK)
-    omega : freq_range
-        Range of frequencies in rad/sec
+    omega : list
+        List of frequencies in rad/sec to be used for frequency response
     dB : boolean
         If True, plot result in dB
     Hz : boolean
@@ -106,7 +106,7 @@ def bode_plot(syslist, omega=None, dB=None, Hz=None, deg=None,
     2. If a discrete time model is given, the frequency response is plotted
     along the upper branch of the unit circle, using the mapping z = exp(j
     \omega dt) where omega ranges from 0 to pi/dt and dt is the discrete
-    time base.  If not timebase is specified (dt = True), dt is set to 1.
+    timebase.  If not timebase is specified (dt = True), dt is set to 1.
 
     Examples
     --------
diff --git a/control/lti.py b/control/lti.py
@@ -82,9 +82,21 @@ def isctime(self, strict=False):
         return self.dt == 0
 
     def issiso(self):
+        '''Check to see if a system is single input, single output'''
         return self.inputs == 1 and self.outputs == 1
 
     def damp(self):
+        '''Natural frequency, damping ratio of system poles
+
+        Returns
+        -------
+        wn : array
+            Natural frequencies for each system pole
+        zeta : array
+            Damping ratio for each system pole
+        poles : array
+            Array of system poles
+        '''
         poles = self.pole()
 
         if isdtime(self, strict=True):
@@ -102,6 +114,16 @@ def dcgain(self):
 
 # Test to see if a system is SISO
 def issiso(sys, strict=False):
+    """
+    Check to see if a system is single input, single output
+
+    Parameters
+    ----------
+    sys : LTI system
+        System to be checked
+    strict: bool (default = False)
+        If strict is True, do not treat scalars as SISO
+    """
     if isinstance(sys, (int, float, complex, np.number)) and not strict:
         return True
     elif not isinstance(sys, LTI):
diff --git a/control/statesp.py b/control/statesp.py
@@ -1248,7 +1248,7 @@ def tf2ss(*args):
 
 def rss(states=1, outputs=1, inputs=1):
     """
-    Create a stable **continuous** random state space object.
+    Create a stable *continuous* random state space object.
 
     Parameters
     ----------
@@ -1285,7 +1285,7 @@ def rss(states=1, outputs=1, inputs=1):
 
 def drss(states=1, outputs=1, inputs=1):
     """
-    Create a stable **discrete** random state space object.
+    Create a stable *discrete* random state space object.
 
     Parameters
     ----------
diff --git a/control/xferfcn.py b/control/xferfcn.py
@@ -1017,7 +1017,7 @@ def _convertToTransferFunction(sys, **kw):
     If sys is an array-like type, then it is converted to a constant-gain
     transfer function.
 
-    >>> sys = _convertToTransferFunction([[1. 0.], [2. 3.]])
+    >>> sys = _convertToTransferFunction([[1., 0.], [2., 3.]])
 
     In this example, the numerator matrix will be
        [[[1.0], [0.0]], [[2.0], [3.0]]]
diff --git a/doc/README b/doc/README
@@ -1,7 +1,11 @@
 Sphinx Documentation
 --------------------
+This directory contains the user manual for the python-control
+toolbox.  The documentation is built using sphinx.  The master toctree
+document is index.rst.
 
-Note: Sphinx actually runs and imports python code, so broken code, or code not in conf.py sys.path, cannot be documented!
+Note: Sphinx actually runs and imports python code, so broken code, or
+code not in conf.py sys.path, cannot be documented!
 
 1.  Get Sphinx [http://sphinx.pocoo.org/]
     [python setup.py build/install]
@@ -14,7 +18,8 @@ Note: Sphinx actually runs and imports python code, so broken code, or code not
 4.  >> touch *.rst
     >> make html  [or make latex]
 
-Creating/updating manual on sourceforge:
-
-5.  >> rsync -rav _build/html/ user@shell.sourceforge.net:/home/project-web/python-control/htdocs/manual-N.mx/
+Creating/updating manual on readthedocs.org:
 
+5.  Log in to readthedocs.org and go to the 'Admin' menu for
+python-control.  Choose 'Versions' from the sidebar and mark the
+latest release as 'Active'.  Update the default version if needed.
diff --git a/doc/control.rst b/doc/control.rst
@@ -154,3 +154,5 @@ Utility functions and conversions
     timebase
     timebaseEqual
     unwrap
+    use_fbs_defaults
+    use_matlab_defaults
diff --git a/doc/conventions.rst b/doc/conventions.rst
@@ -45,8 +45,8 @@ transfer functions
 .. math::
 
   G(s) = \frac{\text{num}(s)}{\text{den}(s)}
-       = \frac{a_0 s^n + a_1 s^{n-1} + \cdots + a_n}
-              {b_0 s^m + b_1 s^{m-1} + \cdots + b_m},
+       = \frac{a_0 s^m + a_1 s^{m-1} + \cdots + a_m}
+              {b_0 s^n + b_1 s^{n-1} + \cdots + b_n},
 
 where n is generally greater than or equal to m (for a proper transfer
 function).
@@ -77,23 +77,27 @@ performed.
 
 Discrete time systems
 ---------------------
-By default, all systems are considered to be continuous time systems.  A
-discrete time system is created by specifying the 'time base' dt.  The time
-base argument can be given when a system is constructed:
+A discrete time system is created by specifying a nonzero 'timebase', dt.
+The timebase argument can be given when a system is constructed:
 
-* dt = None: no timebase specified
+* dt = None: no timebase specified (default)
 * dt = 0: continuous time system
 * dt > 0: discrete time system with sampling period 'dt'
 * dt = True: discrete time with unspecified sampling period
 
 Only the :class:`StateSpace` and :class:`TransferFunction` classes allow
 explicit representation of discrete time systems.
 
-Systems must have the same time base in order to be combined.  For
-continuous time systems, the :func:`sample_system` function or the
-:meth:`StateSpace.sample` and :meth:`TransferFunction.sample` methods can be
-used to create a discrete time system from a continuous time system.  See
-:ref:`utility-and-conversions`.
+Systems must have compatible timebases in order to be combined.  A system
+with timebase `None` can be combined with a system having a specified
+timebase; the result will have the timebase of the latter system.
+Similarly, a discrete time system with unspecified sampling time (`dt =
+True`) can be combined with a system having a specified sampling time;
+the result will be a discrete time system with the sample time of the latter
+system.  For continuous time systems, the :func:`sample_system` function or
+the :meth:`StateSpace.sample` and :meth:`TransferFunction.sample` methods
+can be used to create a discrete time system from a continuous time system.
+See :ref:`utility-and-conversions`.
 
 Conversion between representations
 ----------------------------------
@@ -106,18 +110,23 @@ argument or using the explicit conversion functions :func:`ss2tf` and
 
 Time series data
 ================
-
-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
+A variety of functions in the library return time series data: sequences of
+values that change over time.  A common set of conventions is used for
+returning such data: columns represent different points in time, rows are
+different components (e.g., inputs, outputs or states).  For return
+arguments, an array of times is given as the first returned argument,
+followed by one or more arrays of variable values.  This convention 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`.
+    The convention used by python-control is different from the convention
+    used in the `scipy.signal
+    <https://docs.scipy.org/doc/scipy/reference/signal.html>`_ library. 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 `scipy.signal`_.
 
 Types:
 
@@ -177,7 +186,7 @@ conventions.  The currently configurable options allow the units for Bode
 plots to be set as dB for gain, degrees for phase and Hertz for frequency
 (MATLAB conventions) or the gain can be given in magnitude units (powers of
 10), corresponding to the conventions used in `Feedback Systems
-<http://www.cds.caltech.edu/~murray/FBSwiki>`_.
+<http://fbsbook.org>`_ (FBS).
 
 Variables that can be configured, along with their default values:
   * bode_dB (False): Bode plot magnitude plotted in dB (otherwise powers of 10)
@@ -190,6 +199,7 @@ Variables that can be configured, along with their default values:
 Functions that can be used to set standard configurations:
 
 .. autosummary::
-
+    :toctree: generated/
+    
     use_fbs_defaults
     use_matlab_defaults
diff --git a/doc/index.rst b/doc/index.rst
@@ -12,7 +12,8 @@ implements basic operations for analysis and design of feedback control systems.
 - Time response: initial, step, impulse
 - Frequency response: Bode and Nyquist plots
 - Control analysis: stability, reachability, observability, stability margins
-- Control design: eigenvalue placement, linear quadratic regulator
+- Control design: eigenvalue placement, LQR, H2, Hinf
+- Model reduction: balanced realizations, Hankel singular values
 - Estimator design: linear quadratic estimator (Kalman filter)
 
 .. rubric:: Documentation
diff --git a/doc/intro.rst b/doc/intro.rst
@@ -7,36 +7,41 @@ 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
+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 feedback control
 systems.  The initial goal is to implement all of the functionality required
 to work through the examples in the textbook `Feedback Systems
-<http://www.cds.caltech.edu/~murray/FBSwiki>`_ 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.
+<http://fbsbook.org>`_ by Astrom and Murray. A :ref:`matlab-module` is
+available that provides many of the common functions corresponding to
+commands available in the MATLAB Control Systems Toolbox.
 
-Some Differences from MATLAB
+Some differences from MATLAB
 ============================
-The python-control package makes use of NumPy and SciPy.  A list of general
-differences between NumPy and MATLAB can be found `here
+The python-control package makes use of `NumPy <http://www.numpy.org>`_ and
+`SciPy <https://www.scipy.org>`_.  A list of general differences between
+NumPy and MATLAB can be found `here
 <http://www.scipy.org/NumPy_for_Matlab_Users>`_.
 
 In terms of the python-control package more specifically, here are
 some thing to keep in mind:
 
 * You must include commas in vectors.  So [1 2 3] must be [1, 2, 3].
-* Functions that return multiple arguments use tuples
-* You cannot use braces for collections; use tuples instead
+* Functions that return multiple arguments use tuples.  
+* You cannot use braces for collections; use tuples instead.
 
 Installation
 ============
 
-The `python-control` package may be installed using pip, conda or the
-standard distutils/setuptools mechanisms.
+The `python-control` package can be installed using pip, conda or the
+standard distutils/setuptools mechanisms.  The package requires `numpy`_ and
+`scipy`_, and the plotting routines require `matplotlib
+<https://matplotlib.org>`_.  In addition, some routines require the `slycot
+<https://github.com/python-control/Slycot>`_ library in order to implement
+more advanced features (including some MIMO functionality).
+
 
 To install using pip::
 
@@ -54,22 +59,23 @@ correctly by running the command::
   python -c "import slycot"
 
 and verifying that no error message appears.  It may be necessary to install
-`slycot` from source, which requires a working FORTRAN compiler and the
-`lapack` library.  More information on the slycot package can be obtained
-from the `slycot project page <https://github.com/python-control/Slycot>`_.
+`slycot` from source, which requires a working FORTRAN compiler and either
+the `lapack` or `openplas` library.  More information on the slycot package
+can be obtained from the `slycot project page
+<https://github.com/python-control/Slycot>`_.
 
 For users with the Anaconda distribution of Python, the following
 commands can be used::
 
   conda install numpy scipy matplotlib    # if not yet installed
-  conda install -c python-control -c cyclus slycot control
+  conda install -c conda-forge control
 
-This installs `slycot` and `python-control` from the `python-control`
-channel and uses the `cyclus` channel to obtain the required `lapack`
-package. 
+This installs `slycot` and `python-control` from conda-forge, including the
+`openblas` package.
 
-Alternatively, to use setuptools, first `download the source <https://github.com/python-control/python-control/releases>`_ and unpack
-it.  To install in your home directory, use::
+Alternatively, to use setuptools, first `download the source
+<https://github.com/python-control/python-control/releases>`_ and unpack it.
+To install in your home directory, use::
 
   python setup.py install --user
 
@@ -78,11 +84,7 @@ or to install for all users (on Linux or Mac OS)::
   python setup.py build
   sudo python setup.py install
 
-The package requires `numpy` and `scipy`, and the plotting routines require
-`matplotlib`.  In addition, some routines require the `slycot` module,
-described above.
-
-Getting Started
+Getting started
 ===============
 
 There are two different ways to use the package.  For the default interface
diff --git a/setup.py b/setup.py
@@ -19,9 +19,8 @@
 Programming Language :: Python :: 2
 Programming Language :: Python :: 2.7
 Programming Language :: Python :: 3
-Programming Language :: Python :: 3.3
-Programming Language :: Python :: 3.4
 Programming Language :: Python :: 3.5
+Programming Language :: Python :: 3.6
 Topic :: Software Development
 Topic :: Scientific/Engineering
 Operating System :: Microsoft :: Windows
