Skip to content

Commit fa43936

Browse files
cwrowleycwrowley
committed
Reorganize documentation
Previously, the modules were documented on separate pages (in the html version), with one html page per module. This commit changes the organization of the documentation, so that there are concise tables of functions (or classes), plus one html page per function or class. This is consistent with how numpy, scipy, and other projects handle their documentation.
1 parent f498f0f commit fa43936

23 files changed

Lines changed: 379 additions & 290 deletions

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,3 +11,4 @@ build.log
1111
*.egg-info/
1212
.coverage
1313
doc/_build
14+
doc/generated

‎control/__init__.py‎

Lines changed: 193 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -39,21 +39,200 @@
3939
#
4040
# $Id$
4141

42-
"""Control System Library
42+
"""
43+
==============================
44+
Python Control Systems Library
45+
==============================
4346
44-
The Python Control System Library (control) provides common functions
47+
The Python Control Systems Library (`control`) provides common functions
4548
for analyzing and designing feedback control systems.
4649
47-
Common functions
48-
----------------
49-
tf create a transfer function from num, den coefficients
50-
ss create a state space system from A, B, C, D matrices
51-
pzk create a transfer function from pole, zero, gain
52-
frd create a system description as frequency response
53-
bode generate a Bode plot for a linear I/O system
54-
nyquist generate a Nyquist plot for a linear I/O system
55-
lqr linear quadratic regulator
56-
lqe linear quadratic estimator
50+
System creation
51+
===============
52+
.. autosummary::
53+
:toctree: generated/
54+
55+
ss
56+
tf
57+
58+
Frequency domain plotting
59+
=========================
60+
61+
.. autosummary::
62+
:toctree: generated/
63+
64+
bode
65+
bode_plot
66+
nyquist
67+
nyquist_plot
68+
gangof4
69+
gangof4_plot
70+
nichols
71+
nichols_plot
72+
73+
Time domain simulation
74+
======================
75+
76+
.. autosummary::
77+
:toctree: generated/
78+
79+
forced_response
80+
impulse_response
81+
initial_response
82+
step_response
83+
phase_plot
84+
85+
.. _time-series-convention:
86+
87+
Convention for Time Series
88+
--------------------------
89+
90+
This is a convention for function arguments and return values that
91+
represent time series: sequences of values that change over time. It
92+
is used throughout the library, for example in the functions
93+
:func:`forced_response`, :func:`step_response`, :func:`impulse_response`,
94+
and :func:`initial_response`.
95+
96+
.. note::
97+
This convention is different from the convention used in the library
98+
:mod:`scipy.signal`. In Scipy's convention the meaning of rows and columns
99+
is interchanged. Thus, all 2D values must be transposed when they are
100+
used with functions from :mod:`scipy.signal`.
101+
102+
Types:
103+
104+
* **Arguments** can be **arrays**, **matrices**, or **nested lists**.
105+
* **Return values** are **arrays** (not matrices).
106+
107+
The time vector is either 1D, or 2D with shape (1, n)::
108+
109+
T = [[t1, t2, t3, ..., tn ]]
110+
111+
Input, state, and output all follow the same convention. Columns are different
112+
points in time, rows are different components. When there is only one row, a
113+
1D object is accepted or returned, which adds convenience for SISO systems::
114+
115+
U = [[u1(t1), u1(t2), u1(t3), ..., u1(tn)]
116+
[u2(t1), u2(t2), u2(t3), ..., u2(tn)]
117+
...
118+
...
119+
[ui(t1), ui(t2), ui(t3), ..., ui(tn)]]
120+
121+
Same for X, Y
122+
123+
So, U[:,2] is the system's input at the third point in time; and U[1] or U[1,:]
124+
is the sequence of values for the system's second input.
125+
126+
The initial conditions are either 1D, or 2D with shape (j, 1)::
127+
128+
X0 = [[x1]
129+
[x2]
130+
...
131+
...
132+
[xj]]
133+
134+
As all simulation functions return *arrays*, plotting is convenient::
135+
136+
t, y = step(sys)
137+
plot(t, y)
138+
139+
The output of a MIMO system can be plotted like this::
140+
141+
t, y, x = lsim(sys, u, t)
142+
plot(t, y[0], label='y_0')
143+
plot(t, y[1], label='y_1')
144+
145+
The convention also works well with the state space form of linear systems. If
146+
``D`` is the feedthrough *matrix* of a linear system, and ``U`` is its input
147+
(*matrix* or *array*), then the feedthrough part of the system's response,
148+
can be computed like this::
149+
150+
ft = D * U
151+
152+
153+
Block diagram algebra
154+
=====================
155+
.. autosummary::
156+
:toctree: generated/
157+
158+
series
159+
parallel
160+
feedback
161+
negate
162+
163+
Control system analysis
164+
=======================
165+
.. autosummary::
166+
:toctree: generated/
167+
168+
dcgain
169+
evalfr
170+
freqresp
171+
margin
172+
stability_margins
173+
phase_crossover_frequencies
174+
pole
175+
zero
176+
pzmap
177+
root_locus
178+
179+
Matrix computations
180+
===================
181+
.. autosummary::
182+
:toctree: generated/
183+
184+
care
185+
dare
186+
lyap
187+
dlyap
188+
ctrb
189+
obsv
190+
gram
191+
192+
Control system synthesis
193+
========================
194+
.. autosummary::
195+
:toctree: generated/
196+
197+
acker
198+
lqr
199+
place
200+
201+
Model simplification tools
202+
==========================
203+
.. autosummary::
204+
:toctree: generated/
205+
206+
minreal
207+
balred
208+
hsvd
209+
modred
210+
era
211+
markov
212+
213+
Utility functions and conversions
214+
=================================
215+
.. autosummary::
216+
:toctree: generated/
217+
218+
unwrap
219+
db2mag
220+
mag2db
221+
drss
222+
isctime
223+
isdtime
224+
issys
225+
pade
226+
sample_system
227+
canonical_form
228+
reachable_form
229+
ss2tf
230+
ssdata
231+
tf2ss
232+
tfdata
233+
timebase
234+
timebaseEqual
235+
57236
"""
58237

59238
# Import functions from within the control system library
@@ -66,9 +245,10 @@
66245
from .lti import issiso, timebase, timebaseEqual, isdtime, isctime
67246
from .margins import stability_margins, phase_crossover_frequencies
68247
from .mateqn import lyap, dlyap, care, dare
69-
from .modelsimp import hsvd, modred, balred, era, markov
248+
from .modelsimp import hsvd, modred, balred, era, markov, minreal
70249
from .nichols import nichols_plot, nichols
71250
from .phaseplot import phase_plot, box_grid
251+
from .pzmap import pzmap
72252
from .rlocus import root_locus
73253
from .statefbk import place, lqr, ctrb, obsv, gram, acker
74254
from .statesp import StateSpace

0 commit comments

Comments
 (0)