python-control · murrayrm · Jan 4, 2020 · Nov 17, 2019 · Jan 1, 2020 · Jan 1, 2020
diff --git a/control/bdalg.py b/control/bdalg.py
@@ -62,12 +62,12 @@
 
 
 def series(sys1, *sysn):
-    """Return the series connection (... \\* sys3 \\*) sys2 \\* sys1
+    """Return the series connection (sysn \\* ... \\*) sys2 \\* sys1
 
     Parameters
     ----------
     sys1 : scalar, StateSpace, TransferFunction, or FRD
-    sysn : other scalars, StateSpaces, TransferFunctions, or FRDs
+    *sysn : other scalars, StateSpaces, TransferFunctions, or FRDs
 
     Returns
     -------
@@ -108,7 +108,7 @@ def series(sys1, *sysn):
 
 def parallel(sys1, *sysn):
     """
-    Return the parallel connection sys1 + sys2 (+ sys3 + ...)
+    Return the parallel connection sys1 + sys2 (+ ... + sysn)
 
     Parameters
     ----------
@@ -263,7 +263,7 @@ def append(*sys):
 
     Parameters
     ----------
-    sys1, sys2, ... sysn: StateSpace or Transferfunction
+    sys1, sys2, ..., sysn: StateSpace or Transferfunction
         LTI systems to combine
 
 

diff --git a/control/freqplot.py b/control/freqplot.py
@@ -110,8 +110,10 @@ def bode_plot(syslist, omega=None,
         config.defaults['freqplot.number_of_samples'].
     margins : bool
         If True, plot gain and phase margin.
-    \\*args, \\*\\*kwargs:
-        Additional options to matplotlib (color, linestyle, etc)
+    *args
+        Additional arguments for :func:`matplotlib.plot` (color, linestyle, etc)
+    **kwargs:
+        Additional keywords (passed to `matplotlib`)
 
     Returns
     -------
@@ -450,8 +452,10 @@ def nyquist_plot(syslist, omega=None, Plot=True, color=None,
         Used to specify the color of the plot
     labelFreq : int
         Label every nth frequency on the plot
-    \\*args, \\*\\*kwargs:
-        Additional options to matplotlib (color, linestyle, etc)
+    *args
+        Additional arguments for :func:`matplotlib.plot` (color, linestyle, etc)
+    **kwargs:
+        Additional keywords (passed to `matplotlib`)
 
     Returns
     -------

diff --git a/control/iosys.py b/control/iosys.py
@@ -22,52 +22,6 @@
 Input/output systems can be simulated and also used to compute equilibrium
 points and linearizations.
 
-An input/output system is defined as a dynamical system that has a system
-state as well as inputs and outputs (either inputs or states can be empty).
-The dynamics of the system can be in continuous or discrete time.  To simulate
-an input/output system, use the :func:`~control.input_output_response`
-function::
-
-  t, y = input_output_response(io_sys, T, U, X0, params)
-
-An input/output system can be linearized around an equilibrium point to obtain
-a :class:`~control.StateSpace` linear system.  Use the
-:func:`~control.find_eqpts` function to obtain an equilibrium point and the
-:func:`~control.linearize` function to linearize about that equilibrium point::
-
-  xeq, ueq = find_eqpt(io_sys, X0, U0)
-  ss_sys = linearize(io_sys, xeq, ueq)
-
-Input/output systems can be created from state space LTI systems by using the
-:class:`~control.LinearIOSystem` class`::
-
-  io_sys = LinearIOSystem(ss_sys)
-
-Nonlinear input/output systems can be created using the
-:class:`~control.NonlinearIoSystem` class, which requires the definition of an
-update function (for the right hand side of the differential or different
-equation) and and output function (computes the outputs from the state)::
-
-  io_sys = NonlinearIOSystem(updfcn, outfcn, inputs=M, outputs=P, states=N)
-
-More complex input/output systems can be constructed by using the
-:class:`~control.InterconnectedSystem` class, which allows a collection of
-input/output subsystems to be combined with internal connections between the
-subsystems and a set of overall system inputs and outputs that link to the
-subsystems::
-
-    steering = ct.InterconnectedSystem(
-        (plant, controller), name='system',
-        connections=(('controller.e', '-plant.y')),
-        inplist=('controller.e'), inputs='r',
-        outlist=('plant.y'), outputs='y')
-
-Interconnected systems can also be created using block diagram manipulations
-such as the :func:`~control.series`, :func:`~control.parallel`, and
-:func:`~control.feedback` functions.  The :class:`~control.InputOutputSystem`
-class also supports various algebraic operations such as `*` (series
-interconnection) and `+` (parallel interconnection).
-
 """
 
 __author__ = "Richard Murray"
@@ -1585,6 +1539,11 @@ def find_eqpt(sys, x0, u0=[], y0=None, t=0, params={},
     ninputs = _find_size(sys.ninputs, u0)
     noutputs = _find_size(sys.noutputs, y0)
 
+    # Convert x0, u0, y0 to arrays, if needed
+    if np.isscalar(x0): x0 = np.ones((nstates,)) * x0
+    if np.isscalar(u0): u0 = np.ones((ninputs,)) * u0
+    if np.isscalar(y0): y0 = np.ones((ninputs,)) * y0
+
     # Discrete-time not yet supported
     if isdtime(sys, strict=True):
         raise NotImplementedError(
@@ -1680,7 +1639,7 @@ def rootfun(z):
         # * output_vars: indices of outputs that must be constrained
         #
         # This index lists can all be precomputed based on the `iu`, `iy`,
-        # `ix`, and `idx` lists that were passed as arguments to `find_eqpts`
+        # `ix`, and `idx` lists that were passed as arguments to `find_eqpt`
         # and were processed above.
 
         # Get the states and inputs that were not listed as fixed

diff --git a/control/phaseplot.py b/control/phaseplot.py
@@ -56,8 +56,7 @@ def _find(condition):
 def phase_plot(odefun, X=None, Y=None, scale=1, X0=None, T=None,
               lingrid=None, lintime=None, logtime=None, timepts=None,
               parms=(), verbose=True):
-    """
-    Phase plot for 2D dynamical systems
+    """Phase plot for 2D dynamical systems
 
     Produces a vector field or stream line plot for a planar system.
 
@@ -98,20 +97,19 @@ def phase_plot(odefun, X=None, Y=None, scale=1, X0=None, T=None,
         len(X0) that gives the simulation time for each initial
         condition.  Default value = 50.
 
-    lingrid = N or (N, M): integer or 2-tuple of integers, optional
-        If X0 is given and X, Y are missing, a grid of arrows is
-        produced using the limits of the initial conditions, with N
-        grid points in each dimension or N grid points in x and M grid
-        points in y.
-
-    lintime = N: integer, optional
-        Draw N arrows using equally space time points
+    lingrid : integer or 2-tuple of integers, optional
+        Argument is either N or (N, M).  If X0 is given and X, Y are missing,
+        a grid of arrows is produced using the limits of the initial
+        conditions, with N grid points in each dimension or N grid points in x
+        and M grid points in y.
 
-    logtime = (N, lambda): (integer, float), optional
-        Draw N arrows using exponential time constant lambda
+    lintime : integer or tuple (integer, float), optional
+        If a single integer N is given, draw N arrows using equally space time
+        points.  If a tuple (N, lambda) is given, draw N arrows using
+        exponential time constant lambda
 
-    timepts = [t1, t2, ...]: array-like, optional
-        Draw arrows at the given list times
+    timepts : array-like, optional
+        Draw arrows at the given list times [t1, t2, ...]
 
     parms: tuple, optional
         List of parameters to pass to vector field: `func(x, t, *parms)`
@@ -122,6 +120,7 @@ def phase_plot(odefun, X=None, Y=None, scale=1, X0=None, T=None,
 
     Examples
     --------
+
     """
 
     #

diff --git a/control/timeresp.py b/control/timeresp.py
@@ -242,6 +242,15 @@ def forced_response(sys, T=None, U=0., X0=0., transpose=False,
     --------
     step_response, initial_response, impulse_response
 
+    Notes
+    -----
+    For discrete time systems, the input/output response is computed using the
+    :scipy-signal:ref:`scipy.signal.dlsim` function.
+
+    For continuous time systems, the output is computed using the matrix
+    exponential `exp(A t)` and assuming linear interpolation of the inputs
+    between time points.
+
     Examples
     --------
     >>> T, yout, xout = forced_response(sys, T, u, X0)
@@ -488,9 +497,15 @@ def step_response(sys, T=None, X0=0., input=None, output=None,
     --------
     forced_response, initial_response, impulse_response
 
+    Notes
+    -----
+    This function uses the `forced_response` function with the input set to a
+    unit step.
+
     Examples
     --------
     >>> T, yout = step_response(sys, T, X0)
+
     """
     sys = _get_ss_simo(sys, input, output)
     if T is None:
@@ -665,6 +680,11 @@ def initial_response(sys, T=None, X0=0., input=0, output=None,
     --------
     forced_response, impulse_response, step_response
 
+    Notes
+    -----
+    This function uses the `forced_response` function with the input set to
+    zero.
+
     Examples
     --------
     >>> T, yout = initial_response(sys, T, X0)
@@ -749,9 +769,16 @@ def impulse_response(sys, T=None, X0=0., input=0, output=None,
     --------
     forced_response, initial_response, step_response
 
+    Notes
+    -----
+    This function uses the `forced_response` function to compute the time
+    response. For continuous time systems, the initial condition is altered to
+    account for the initial impulse.
+
     Examples
     --------
     >>> T, yout = impulse_response(sys, T, X0)
+
     """
     sys = _get_ss_simo(sys, input, output)
 

diff --git a/doc-requirements.txt b/doc-requirements.txt
@@ -3,3 +3,5 @@ scipy
 matplotlib
 sphinx_rtd_theme
 numpydoc
+ipykernel
+nbsphinx
diff --git a/doc/classes.rst b/doc/classes.rst
@@ -16,10 +16,11 @@ these directly.
    TransferFunction
    StateSpace
    FrequencyResponseData
-   InputOutputSystem
+   ~iosys.InputOutputSystem
 
-Input/Output system subclasses
+Input/output system subclasses
 ==============================
+.. currentmodule:: control.iosys
 
 Input/output systems are accessed primarily via a set of subclasses
 that allow for linear, nonlinear, and interconnected elements:

diff --git a/doc/conf.py b/doc/conf.py
@@ -56,7 +56,7 @@
 extensions = [
     'sphinx.ext.autodoc', 'sphinx.ext.todo', 'sphinx.ext.napoleon',
     'sphinx.ext.intersphinx', 'sphinx.ext.imgmath', 
-    'sphinx.ext.autosummary',
+    'sphinx.ext.autosummary', 'nbsphinx',
 ]
 
 # scan documents for autosummary directives and generate stub pages for each.
@@ -88,15 +88,16 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path .
-exclude_patterns = [u'_build', 'Thumbs.db', '.DS_Store']
+exclude_patterns = [u'_build', 'Thumbs.db', '.DS_Store',
+                    '*.ipynb_checkpoints']
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
 
 #This config value contains the locations and names of other projects that 
 #should be linked to in this documentation.
 intersphinx_mapping = \
-    {'scipy':('https://docs.scipy.org/doc/scipy/reference/', None),
+    {'scipy':('https://docs.scipy.org/doc/scipy/reference', None),
      'numpy':('https://docs.scipy.org/doc/numpy', None)}
 
 #If this is True, todo and todolist produce output, else they produce nothing. 

diff --git a/doc/control.rst b/doc/control.rst
@@ -32,6 +32,9 @@ System interconnections
     parallel
     series
 
+See also the :ref:`iosys-module` module, which can be used to create and
+interconnect nonlinear input/output systems.
+
 Frequency domain plotting
 =========================
 
@@ -134,8 +137,9 @@ Nonlinear system support
 .. autosummary::
    :toctree: generated/
 
-   find_eqpt
-   linearize
+   ~iosys.find_eqpt
+   ~iosys.linearize
+   flatsys.point_to_point
 
 .. _utility-and-conversions:
 

diff --git a/doc/conventions.rst b/doc/conventions.rst
@@ -107,13 +107,6 @@ constructor for the desired data type using the original system as the sole
 argument or using the explicit conversion functions :func:`ss2tf` and
 :func:`tf2ss`.
 
-Input/output systems
-====================
-
-.. automodule:: control.iosys
-   :no-members:
-   :no-inherited-members:
-
 .. currentmodule:: control
 .. _time-series-convention:
 

diff --git a/doc/cruise-control.py b/doc/cruise-control.py
@@ -0,0 +1 @@
+../examples/cruise-control.py
diff --git a/doc/cruise-control.rst b/doc/cruise-control.rst
@@ -0,0 +1,14 @@
+Cruise control design example (as a nonlinear I/O system)
+---------------------------------------------------------
+
+Code
+....
+.. literalinclude:: cruise-control.py
+   :language: python
+   :linenos:
+
+
+Notes
+.....
+1. The environment variable `PYCONTROL_TEST_EXAMPLES` is used for
+testing to turn off plotting of the outputs.
diff --git a/doc/cruise.ipynb b/doc/cruise.ipynb
@@ -0,0 +1 @@
+../examples/cruise.ipynb
diff --git a/doc/examples.rst b/doc/examples.rst
@@ -0,0 +1,46 @@
+.. _examples:
+.. currentmodule:: control
+
+********
+Examples
+********
+
+The source code for the examples below are available in the `examples/`
+subdirecory of the source code distribution.  The can also be accessed online
+via the [python-control GitHub repository](https://github.com/python-control/python-control/tree/master/examples).
+
+
+Python scripts
+==============
+
+The following Python scripts document the use of a variety of methods in the
+Python Control Toolbox on examples drawn from standard control textbooks and
+other sources.
+
+.. toctree::
+   :maxdepth: 1
+
+   secord-matlab
+   pvtol-nested
+   pvtol-lqr
+   rss-balred
+   phaseplots
+   robust_siso
+   robust_mimo
+   cruise-control
+   steering-gainsched
+   kincar-flatsys
+
+Jupyter notebooks
+=================
+
+The examples below use `python-control` in a Jupyter notebook environment.
+These notebooks demonstrate the use of modeling, anaylsis, and design tools
+using running examples in FBS2e.
+
+.. toctree::
+   :maxdepth: 1
+
+   cruise
+   steering
+   pvtol-lqr-nested