Skip to content

Commit ec8cbf0

Browse files
murrayrmmurrayrm
authored
Documentation updates (#360)
* add info on methods for time responses * add script and Jupyter notebook examples to documentation * updated I/O systems documentation (with example) * fix *args, *kwargs* in freqplot docstrings to fix issue #358 * update series() and paralle() docstrings to fix issue #358 * fix docstring for phase_plot of fix issue #358
1 parent 53d340b commit ec8cbf0

40 files changed

+2628
-125
lines changed

‎control/bdalg.py

+4-4
Original file line numberDiff line numberDiff line change
@@ -62,12 +62,12 @@
6262

6363

6464
def series(sys1, *sysn):
65-
"""Return the series connection (... \\* sys3 \\*) sys2 \\* sys1
65+
"""Return the series connection (sysn \\* ... \\*) sys2 \\* sys1
6666
6767
Parameters
6868
----------
6969
sys1 : scalar, StateSpace, TransferFunction, or FRD
70-
sysn : other scalars, StateSpaces, TransferFunctions, or FRDs
70+
*sysn : other scalars, StateSpaces, TransferFunctions, or FRDs
7171
7272
Returns
7373
-------
@@ -108,7 +108,7 @@ def series(sys1, *sysn):
108108

109109
def parallel(sys1, *sysn):
110110
"""
111-
Return the parallel connection sys1 + sys2 (+ sys3 + ...)
111+
Return the parallel connection sys1 + sys2 (+ ... + sysn)
112112
113113
Parameters
114114
----------
@@ -263,7 +263,7 @@ def append(*sys):
263263
264264
Parameters
265265
----------
266-
sys1, sys2, ... sysn: StateSpace or Transferfunction
266+
sys1, sys2, ..., sysn: StateSpace or Transferfunction
267267
LTI systems to combine
268268
269269

‎control/freqplot.py

+8-4
Original file line numberDiff line numberDiff line change
@@ -110,8 +110,10 @@ def bode_plot(syslist, omega=None,
110110
config.defaults['freqplot.number_of_samples'].
111111
margins : bool
112112
If True, plot gain and phase margin.
113-
\\*args, \\*\\*kwargs:
114-
Additional options to matplotlib (color, linestyle, etc)
113+
*args
114+
Additional arguments for :func:`matplotlib.plot` (color, linestyle, etc)
115+
**kwargs:
116+
Additional keywords (passed to `matplotlib`)
115117
116118
Returns
117119
-------
@@ -450,8 +452,10 @@ def nyquist_plot(syslist, omega=None, Plot=True, color=None,
450452
Used to specify the color of the plot
451453
labelFreq : int
452454
Label every nth frequency on the plot
453-
\\*args, \\*\\*kwargs:
454-
Additional options to matplotlib (color, linestyle, etc)
455+
*args
456+
Additional arguments for :func:`matplotlib.plot` (color, linestyle, etc)
457+
**kwargs:
458+
Additional keywords (passed to `matplotlib`)
455459
456460
Returns
457461
-------

‎control/iosys.py

+6-47
Original file line numberDiff line numberDiff line change
@@ -22,52 +22,6 @@
2222
Input/output systems can be simulated and also used to compute equilibrium
2323
points and linearizations.
2424
25-
An input/output system is defined as a dynamical system that has a system
26-
state as well as inputs and outputs (either inputs or states can be empty).
27-
The dynamics of the system can be in continuous or discrete time. To simulate
28-
an input/output system, use the :func:`~control.input_output_response`
29-
function::
30-
31-
t, y = input_output_response(io_sys, T, U, X0, params)
32-
33-
An input/output system can be linearized around an equilibrium point to obtain
34-
a :class:`~control.StateSpace` linear system. Use the
35-
:func:`~control.find_eqpts` function to obtain an equilibrium point and the
36-
:func:`~control.linearize` function to linearize about that equilibrium point::
37-
38-
xeq, ueq = find_eqpt(io_sys, X0, U0)
39-
ss_sys = linearize(io_sys, xeq, ueq)
40-
41-
Input/output systems can be created from state space LTI systems by using the
42-
:class:`~control.LinearIOSystem` class`::
43-
44-
io_sys = LinearIOSystem(ss_sys)
45-
46-
Nonlinear input/output systems can be created using the
47-
:class:`~control.NonlinearIoSystem` class, which requires the definition of an
48-
update function (for the right hand side of the differential or different
49-
equation) and and output function (computes the outputs from the state)::
50-
51-
io_sys = NonlinearIOSystem(updfcn, outfcn, inputs=M, outputs=P, states=N)
52-
53-
More complex input/output systems can be constructed by using the
54-
:class:`~control.InterconnectedSystem` class, which allows a collection of
55-
input/output subsystems to be combined with internal connections between the
56-
subsystems and a set of overall system inputs and outputs that link to the
57-
subsystems::
58-
59-
steering = ct.InterconnectedSystem(
60-
(plant, controller), name='system',
61-
connections=(('controller.e', '-plant.y')),
62-
inplist=('controller.e'), inputs='r',
63-
outlist=('plant.y'), outputs='y')
64-
65-
Interconnected systems can also be created using block diagram manipulations
66-
such as the :func:`~control.series`, :func:`~control.parallel`, and
67-
:func:`~control.feedback` functions. The :class:`~control.InputOutputSystem`
68-
class also supports various algebraic operations such as `*` (series
69-
interconnection) and `+` (parallel interconnection).
70-
7125
"""
7226

7327
__author__ = "Richard Murray"
@@ -1585,6 +1539,11 @@ def find_eqpt(sys, x0, u0=[], y0=None, t=0, params={},
15851539
ninputs = _find_size(sys.ninputs, u0)
15861540
noutputs = _find_size(sys.noutputs, y0)
15871541

1542+
# Convert x0, u0, y0 to arrays, if needed
1543+
if np.isscalar(x0): x0 = np.ones((nstates,)) * x0
1544+
if np.isscalar(u0): u0 = np.ones((ninputs,)) * u0
1545+
if np.isscalar(y0): y0 = np.ones((ninputs,)) * y0
1546+
15881547
# Discrete-time not yet supported
15891548
if isdtime(sys, strict=True):
15901549
raise NotImplementedError(
@@ -1680,7 +1639,7 @@ def rootfun(z):
16801639
# * output_vars: indices of outputs that must be constrained
16811640
#
16821641
# This index lists can all be precomputed based on the `iu`, `iy`,
1683-
# `ix`, and `idx` lists that were passed as arguments to `find_eqpts`
1642+
# `ix`, and `idx` lists that were passed as arguments to `find_eqpt`
16841643
# and were processed above.
16851644

16861645
# Get the states and inputs that were not listed as fixed

‎control/phaseplot.py

+13-14
Original file line numberDiff line numberDiff line change
@@ -56,8 +56,7 @@ def _find(condition):
5656
def phase_plot(odefun, X=None, Y=None, scale=1, X0=None, T=None,
5757
lingrid=None, lintime=None, logtime=None, timepts=None,
5858
parms=(), verbose=True):
59-
"""
60-
Phase plot for 2D dynamical systems
59+
"""Phase plot for 2D dynamical systems
6160
6261
Produces a vector field or stream line plot for a planar system.
6362
@@ -98,20 +97,19 @@ def phase_plot(odefun, X=None, Y=None, scale=1, X0=None, T=None,
9897
len(X0) that gives the simulation time for each initial
9998
condition. Default value = 50.
10099
101-
lingrid = N or (N, M): integer or 2-tuple of integers, optional
102-
If X0 is given and X, Y are missing, a grid of arrows is
103-
produced using the limits of the initial conditions, with N
104-
grid points in each dimension or N grid points in x and M grid
105-
points in y.
106-
107-
lintime = N: integer, optional
108-
Draw N arrows using equally space time points
100+
lingrid : integer or 2-tuple of integers, optional
101+
Argument is either N or (N, M). If X0 is given and X, Y are missing,
102+
a grid of arrows is produced using the limits of the initial
103+
conditions, with N grid points in each dimension or N grid points in x
104+
and M grid points in y.
109105
110-
logtime = (N, lambda): (integer, float), optional
111-
Draw N arrows using exponential time constant lambda
106+
lintime : integer or tuple (integer, float), optional
107+
If a single integer N is given, draw N arrows using equally space time
108+
points. If a tuple (N, lambda) is given, draw N arrows using
109+
exponential time constant lambda
112110
113-
timepts = [t1, t2, ...]: array-like, optional
114-
Draw arrows at the given list times
111+
timepts : array-like, optional
112+
Draw arrows at the given list times [t1, t2, ...]
115113
116114
parms: tuple, optional
117115
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,
122120
123121
Examples
124122
--------
123+
125124
"""
126125

127126
#

‎control/timeresp.py

+27
Original file line numberDiff line numberDiff line change
@@ -242,6 +242,15 @@ def forced_response(sys, T=None, U=0., X0=0., transpose=False,
242242
--------
243243
step_response, initial_response, impulse_response
244244
245+
Notes
246+
-----
247+
For discrete time systems, the input/output response is computed using the
248+
:scipy-signal:ref:`scipy.signal.dlsim` function.
249+
250+
For continuous time systems, the output is computed using the matrix
251+
exponential `exp(A t)` and assuming linear interpolation of the inputs
252+
between time points.
253+
245254
Examples
246255
--------
247256
>>> T, yout, xout = forced_response(sys, T, u, X0)
@@ -491,9 +500,15 @@ def step_response(sys, T=None, X0=0., input=None, output=None,
491500
--------
492501
forced_response, initial_response, impulse_response
493502
503+
Notes
504+
-----
505+
This function uses the `forced_response` function with the input set to a
506+
unit step.
507+
494508
Examples
495509
--------
496510
>>> T, yout = step_response(sys, T, X0)
511+
497512
"""
498513
sys = _get_ss_simo(sys, input, output)
499514
if T is None:
@@ -668,6 +683,11 @@ def initial_response(sys, T=None, X0=0., input=0, output=None,
668683
--------
669684
forced_response, impulse_response, step_response
670685
686+
Notes
687+
-----
688+
This function uses the `forced_response` function with the input set to
689+
zero.
690+
671691
Examples
672692
--------
673693
>>> T, yout = initial_response(sys, T, X0)
@@ -752,9 +772,16 @@ def impulse_response(sys, T=None, X0=0., input=0, output=None,
752772
--------
753773
forced_response, initial_response, step_response
754774
775+
Notes
776+
-----
777+
This function uses the `forced_response` function to compute the time
778+
response. For continuous time systems, the initial condition is altered to
779+
account for the initial impulse.
780+
755781
Examples
756782
--------
757783
>>> T, yout = impulse_response(sys, T, X0)
784+
758785
"""
759786
sys = _get_ss_simo(sys, input, output)
760787

‎doc-requirements.txt

+2
Original file line numberDiff line numberDiff line change
@@ -3,3 +3,5 @@ scipy
33
matplotlib
44
sphinx_rtd_theme
55
numpydoc
6+
ipykernel
7+
nbsphinx

‎doc/classes.rst

+3-2
Original file line numberDiff line numberDiff line change
@@ -16,10 +16,11 @@ these directly.
1616
TransferFunction
1717
StateSpace
1818
FrequencyResponseData
19-
InputOutputSystem
19+
~iosys.InputOutputSystem
2020

21-
Input/Output system subclasses
21+
Input/output system subclasses
2222
==============================
23+
.. currentmodule:: control.iosys
2324

2425
Input/output systems are accessed primarily via a set of subclasses
2526
that allow for linear, nonlinear, and interconnected elements:

‎doc/conf.py

+4-3
Original file line numberDiff line numberDiff line change
@@ -56,7 +56,7 @@
5656
extensions = [
5757
'sphinx.ext.autodoc', 'sphinx.ext.todo', 'sphinx.ext.napoleon',
5858
'sphinx.ext.intersphinx', 'sphinx.ext.imgmath',
59-
'sphinx.ext.autosummary',
59+
'sphinx.ext.autosummary', 'nbsphinx',
6060
]
6161

6262
# scan documents for autosummary directives and generate stub pages for each.
@@ -88,15 +88,16 @@
8888
# List of patterns, relative to source directory, that match files and
8989
# directories to ignore when looking for source files.
9090
# This pattern also affects html_static_path and html_extra_path .
91-
exclude_patterns = [u'_build', 'Thumbs.db', '.DS_Store']
91+
exclude_patterns = [u'_build', 'Thumbs.db', '.DS_Store',
92+
'*.ipynb_checkpoints']
9293

9394
# The name of the Pygments (syntax highlighting) style to use.
9495
pygments_style = 'sphinx'
9596

9697
#This config value contains the locations and names of other projects that
9798
#should be linked to in this documentation.
9899
intersphinx_mapping = \
99-
{'scipy':('https://docs.scipy.org/doc/scipy/reference/', None),
100+
{'scipy':('https://docs.scipy.org/doc/scipy/reference', None),
100101
'numpy':('https://docs.scipy.org/doc/numpy', None)}
101102

102103
#If this is True, todo and todolist produce output, else they produce nothing.

‎doc/control.rst

+6-2
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,9 @@ System interconnections
3232
parallel
3333
series
3434

35+
See also the :ref:`iosys-module` module, which can be used to create and
36+
interconnect nonlinear input/output systems.
37+
3538
Frequency domain plotting
3639
=========================
3740

@@ -134,8 +137,9 @@ Nonlinear system support
134137
.. autosummary::
135138
:toctree: generated/
136139

137-
find_eqpt
138-
linearize
140+
~iosys.find_eqpt
141+
~iosys.linearize
142+
flatsys.point_to_point
139143

140144
.. _utility-and-conversions:
141145

‎doc/conventions.rst

-7
Original file line numberDiff line numberDiff line change
@@ -107,13 +107,6 @@ constructor for the desired data type using the original system as the sole
107107
argument or using the explicit conversion functions :func:`ss2tf` and
108108
:func:`tf2ss`.
109109

110-
Input/output systems
111-
====================
112-
113-
.. automodule:: control.iosys
114-
:no-members:
115-
:no-inherited-members:
116-
117110
.. currentmodule:: control
118111
.. _time-series-convention:
119112

‎doc/cruise-control.py

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../examples/cruise-control.py

‎doc/cruise-control.rst

+14
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
Cruise control design example (as a nonlinear I/O system)
2+
---------------------------------------------------------
3+
4+
Code
5+
....
6+
.. literalinclude:: cruise-control.py
7+
:language: python
8+
:linenos:
9+
10+
11+
Notes
12+
.....
13+
1. The environment variable `PYCONTROL_TEST_EXAMPLES` is used for
14+
testing to turn off plotting of the outputs.

‎doc/cruise.ipynb

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../examples/cruise.ipynb

‎doc/examples.rst

+46
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
.. _examples:
2+
.. currentmodule:: control
3+
4+
********
5+
Examples
6+
********
7+
8+
The source code for the examples below are available in the `examples/`
9+
subdirecory of the source code distribution. The can also be accessed online
10+
via the [python-control GitHub repository](https://github.com/python-control/python-control/tree/master/examples).
11+
12+
13+
Python scripts
14+
==============
15+
16+
The following Python scripts document the use of a variety of methods in the
17+
Python Control Toolbox on examples drawn from standard control textbooks and
18+
other sources.
19+
20+
.. toctree::
21+
:maxdepth: 1
22+
23+
secord-matlab
24+
pvtol-nested
25+
pvtol-lqr
26+
rss-balred
27+
phaseplots
28+
robust_siso
29+
robust_mimo
30+
cruise-control
31+
steering-gainsched
32+
kincar-flatsys
33+
34+
Jupyter notebooks
35+
=================
36+
37+
The examples below use `python-control` in a Jupyter notebook environment.
38+
These notebooks demonstrate the use of modeling, anaylsis, and design tools
39+
using running examples in FBS2e.
40+
41+
.. toctree::
42+
:maxdepth: 1
43+
44+
cruise
45+
steering
46+
pvtol-lqr-nested

0 commit comments

Comments
 (0)