Skip to content

Commit c913c8f

Browse files
henklaakmurrayrm
henklaak
authored and
murrayrm
committed
Docs update
1 parent 562701c commit c913c8f

28 files changed

Lines changed: 789 additions & 189 deletions

‎control/bdalg.py‎

Lines changed: 63 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -99,9 +99,19 @@ def series(sys1, *sysn):
9999
100100
Examples
101101
--------
102-
>>> sys3 = series(sys1, sys2) # Same as sys3 = sys2 * sys1
102+
>>> from control import rss, series
103103
104-
>>> sys5 = series(sys1, sys2, sys3, sys4) # More systems
104+
>>> G1 = rss(3)
105+
>>> G2 = rss(4)
106+
>>> G = series(G1, G2) # Same as sys3 = sys2 * sys1
107+
>>> G.ninputs, G.noutputs, G.nstates
108+
(1, 1, 7)
109+
110+
>>> G1 = rss(2, inputs=2, outputs=3)
111+
>>> G2 = rss(3, inputs=3, outputs=1)
112+
>>> G = series(G1, G2) # Same as sys3 = sys2 * sys1
113+
>>> G.ninputs, G.noutputs, G.nstates
114+
(2, 1, 5)
105115
106116
"""
107117
from functools import reduce
@@ -146,9 +156,19 @@ def parallel(sys1, *sysn):
146156
147157
Examples
148158
--------
149-
>>> sys3 = parallel(sys1, sys2) # Same as sys3 = sys1 + sys2
159+
>>> from control import parallel, rss
160+
161+
>>> G1 = rss(3)
162+
>>> G2 = rss(4)
163+
>>> G = parallel(G1, G2) # Same as sys3 = sys1 + sys2
164+
>>> G.ninputs, G.noutputs, G.nstates
165+
(1, 1, 7)
150166
151-
>>> sys5 = parallel(sys1, sys2, sys3, sys4) # More systems
167+
>>> G1 = rss(3, inputs=3, outputs=4)
168+
>>> G2 = rss(4, inputs=3, outputs=4)
169+
>>> G = parallel(G1, G2) # Add another system
170+
>>> G.ninputs, G.noutputs, G.nstates
171+
(3, 4, 7)
152172
153173
"""
154174
from functools import reduce
@@ -174,7 +194,15 @@ def negate(sys):
174194
175195
Examples
176196
--------
177-
>>> sys2 = negate(sys1) # Same as sys2 = -sys1.
197+
>>> from control import negate, tf
198+
199+
>>> G = tf([2],[1, 1])
200+
>>> G.dcgain() > 0
201+
True
202+
203+
>>> Gn = negate(G) # Same as sys2 = -sys1.
204+
>>> Gn.dcgain() < 0
205+
True
178206
179207
"""
180208
return -sys
@@ -222,6 +250,16 @@ def feedback(sys1, sys2=1, sign=-1):
222250
the corresponding feedback function is used. If `sys1` and `sys2` are both
223251
scalars, then TransferFunction.feedback is used.
224252
253+
Examples
254+
--------
255+
>>> from control import feedback, rss
256+
257+
>>> G = rss(3, inputs=2, outputs=5)
258+
>>> C = rss(4, inputs=5, outputs=2)
259+
>>> T = feedback(G, C, sign=1)
260+
>>> T.ninputs, T.noutputs, T.nstates
261+
(2, 5, 7)
262+
225263
"""
226264
# Allow anything with a feedback function to call that function
227265
try:
@@ -278,9 +316,19 @@ def append(*sys):
278316
279317
Examples
280318
--------
281-
>>> sys1 = ss([[1., -2], [3., -4]], [[5.], [7]], [[6., 8]], [[9.]])
282-
>>> sys2 = ss([[-1.]], [[1.]], [[1.]], [[0.]])
283-
>>> sys = append(sys1, sys2)
319+
>>> from control import append, rss
320+
>>> G1 = rss(3)
321+
322+
>>> G2 = rss(4)
323+
>>> G = append(G1, G2)
324+
>>> G.ninputs, G.noutputs, G.nstates
325+
(2, 2, 7)
326+
327+
>>> G1 = rss(3, inputs=2, outputs=4)
328+
>>> G2 = rss(4, inputs=1, outputs=4)
329+
>>> G = append(G1, G2)
330+
>>> G.ninputs, G.noutputs, G.nstates
331+
(3, 8, 7)
284332
285333
"""
286334
s1 = ss._convert_to_statespace(sys[0])
@@ -323,11 +371,13 @@ def connect(sys, Q, inputv, outputv):
323371
324372
Examples
325373
--------
326-
>>> sys1 = ss([[1., -2], [3., -4]], [[5.], [7]], [[6, 8]], [[9.]])
327-
>>> sys2 = ss([[-1.]], [[1.]], [[1.]], [[0.]])
328-
>>> sys = append(sys1, sys2)
329-
>>> Q = [[1, 2], [2, -1]] # negative feedback interconnection
330-
>>> sysc = connect(sys, Q, [2], [1, 2])
374+
>>> from control import append, connect, rss
375+
376+
>>> G = rss(7, inputs=2, outputs=2)
377+
>>> K = [[1, 2], [2, -1]] # negative feedback interconnection
378+
>>> T = connect(G, K, [2], [1, 2])
379+
>>> T.ninputs, T.noutputs, T.nstates
380+
(1, 2, 7)
331381
332382
Notes
333383
-----

‎control/bench/time_freqresp.py‎

Lines changed: 11 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -3,12 +3,14 @@
33
from numpy import logspace
44
from timeit import timeit
55

6-
nstates = 10
7-
sys = rss(nstates)
8-
sys_tf = tf(sys)
9-
w = logspace(-1,1,50)
10-
ntimes = 1000
11-
time_ss = timeit("sys.freqquency_response(w)", setup="from __main__ import sys, w", number=ntimes)
12-
time_tf = timeit("sys_tf.frequency_response(w)", setup="from __main__ import sys_tf, w", number=ntimes)
13-
print("State-space model on %d states: %f" % (nstates, time_ss))
14-
print("Transfer-function model on %d states: %f" % (nstates, time_tf))
6+
7+
if __name__ == '__main__':
8+
nstates = 10
9+
sys = rss(nstates)
10+
sys_tf = tf(sys)
11+
w = logspace(-1,1,50)
12+
ntimes = 1000
13+
time_ss = timeit("sys.freqquency_response(w)", setup="from __main__ import sys, w", number=ntimes)
14+
time_tf = timeit("sys_tf.frequency_response(w)", setup="from __main__ import sys_tf, w", number=ntimes)
15+
print("State-space model on %d states: %f" % (nstates, time_ss))
16+
print("Transfer-function model on %d states: %f" % (nstates, time_tf))

‎control/canonical.py‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,28 @@ def canonical_form(xsys, form='reachable'):
3636
System in desired canonical form, with state 'z'
3737
T : (M, M) real ndarray
3838
Coordinate transformation matrix, z = T * x
39+
40+
Examples
41+
--------
42+
>>> from control import canonical_form, tf, tf2ss
43+
44+
>>> G = tf([1],[1, 3, 2])
45+
>>> Gs = tf2ss(G)
46+
47+
>>> Gc, T = canonical_form(Gs) # default reachable
48+
>>> Gc.B # doctest: +SKIP
49+
matrix([[1.],
50+
[0.]])
51+
52+
>>> Gc, T = canonical_form(Gs, 'observable')
53+
>>> Gc.C # doctest: +SKIP
54+
matrix([[1., 0.]])
55+
56+
>>> Gc, T = canonical_form(Gs, 'modal')
57+
>>> Gc.A # doctest: +SKIP
58+
matrix([[-2., 0.],
59+
[ 0., -1.]])
60+
3961
"""
4062

4163
# Call the appropriate tranformation function
@@ -65,6 +87,19 @@ def reachable_form(xsys):
6587
System in reachable canonical form, with state `z`
6688
T : (M, M) real ndarray
6789
Coordinate transformation: z = T * x
90+
91+
Examples
92+
--------
93+
>>> from control import reachable_form, tf, tf2ss
94+
95+
>>> G = tf([1],[1, 3, 2])
96+
>>> Gs = tf2ss(G)
97+
98+
>>> Gc, T = reachable_form(Gs) # default reachable
99+
>>> Gc.B # doctest: +SKIP
100+
matrix([[1.],
101+
[0.]])
102+
68103
"""
69104
# Check to make sure we have a SISO system
70105
if not issiso(xsys):
@@ -119,6 +154,18 @@ def observable_form(xsys):
119154
System in observable canonical form, with state `z`
120155
T : (M, M) real ndarray
121156
Coordinate transformation: z = T * x
157+
158+
Examples
159+
--------
160+
>>> from control import observable_form, tf, tf2ss
161+
162+
>>> G = tf([1],[1, 3, 2])
163+
>>> Gs = tf2ss(G)
164+
165+
>>> Gc, T = observable_form(Gs)
166+
>>> Gc.C # doctest: +SKIP
167+
matrix([[1., 0.]])
168+
122169
"""
123170
# Check to make sure we have a SISO system
124171
if not issiso(xsys):
@@ -177,6 +224,24 @@ def similarity_transform(xsys, T, timescale=1, inverse=False):
177224
zsys : StateSpace object
178225
System in transformed coordinates, with state 'z'
179226
227+
228+
Examples
229+
--------
230+
>>> import numpy as np
231+
>>> from control import similarity_transform, tf, tf2ss
232+
233+
>>> G = tf([1],[1, 3, 2])
234+
>>> Gs = tf2ss(G)
235+
>>> Gs.A # doctest: +SKIP
236+
matrix([[-3., -2.],
237+
[ 1., 0.]])
238+
239+
>>> T = np.array([[0,1],[1,0]])
240+
>>> Gt = similarity_transform(Gs, T)
241+
>>> Gt.A # doctest: +SKIP
242+
matrix([[ 0., 1.],
243+
[-2., -3.]])
244+
180245
"""
181246
# Create a new system, starting with a copy of the old one
182247
zsys = StateSpace(xsys)
@@ -370,6 +435,18 @@ def bdschur(a, condmax=None, sort=None):
370435
If `sort` is 'discrete', the blocks are sorted as for
371436
'continuous', but applied to log of eigenvalues
372437
(i.e., continuous-equivalent eigenvalues).
438+
439+
Examples
440+
--------
441+
>>> from control import bdschur, tf, tf2ss
442+
443+
>>> G = tf([1],[1, 3, 2])
444+
>>> Gs = tf2ss(G)
445+
>>> amodal, tmodal, blksizes = bdschur(Gs.A)
446+
>>> amodal #doctest: +SKIP
447+
array([[-2., 0.],
448+
[ 0., -1.]])
449+
373450
"""
374451
if condmax is None:
375452
condmax = np.finfo(np.float64).eps ** -0.5
@@ -436,6 +513,19 @@ def modal_form(xsys, condmax=None, sort=False):
436513
System in modal canonical form, with state `z`
437514
T : (M, M) ndarray
438515
Coordinate transformation: z = T * x
516+
517+
Examples
518+
--------
519+
>>> from control import modal_form, tf, tf2ss
520+
521+
>>> G = tf([1],[1, 3, 2])
522+
>>> Gs = tf2ss((G))
523+
524+
>>> Gc, T = modal_form(Gs) # default reachable
525+
>>> Gc.A # doctest: +SKIP
526+
matrix([[-2., 0.],
527+
[ 0., -1.]])
528+
439529
"""
440530

441531
if sort:

‎control/config.py‎

Lines changed: 68 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -65,9 +65,22 @@ def set_defaults(module, **keywords):
6565
"""Set default values of parameters for a module.
6666
6767
The set_defaults() function can be used to modify multiple parameter
68-
values for a module at the same time, using keyword arguments:
68+
values for a module at the same time, using keyword arguments.
6969
70-
control.set_defaults('module', param1=val, param2=val)
70+
Examples
71+
--------
72+
>>> from control import defaults, reset_defaults, set_defaults
73+
74+
>>> defaults['freqplot.number_of_samples']
75+
1000
76+
>>> set_defaults('freqplot', number_of_samples=100)
77+
>>> defaults['freqplot.number_of_samples']
78+
100
79+
80+
>>> # do some customized freqplotting
81+
>>> reset_defaults()
82+
>>> defaults['freqplot.number_of_samples']
83+
1000
7184
7285
"""
7386
if not isinstance(module, str):
@@ -80,7 +93,24 @@ def set_defaults(module, **keywords):
8093

8194

8295
def reset_defaults():
83-
"""Reset configuration values to their default (initial) values."""
96+
"""Reset configuration values to their default (initial) values.
97+
98+
Examples
99+
--------
100+
>>> from control import defaults, reset_defaults, set_defaults
101+
102+
>>> defaults['freqplot.number_of_samples']
103+
1000
104+
>>> set_defaults('freqplot', number_of_samples=100)
105+
>>> defaults['freqplot.number_of_samples']
106+
100
107+
108+
>>> # do some customized freqplotting
109+
>>> reset_defaults()
110+
>>> defaults['freqplot.number_of_samples']
111+
1000
112+
113+
"""
84114
# System level defaults
85115
defaults.update(_control_defaults)
86116

@@ -181,6 +211,14 @@ def use_matlab_defaults():
181211
rad/sec, with grids
182212
* State space class and functions use Numpy matrix objects
183213
214+
Examples
215+
--------
216+
>>> from control import use_matlab_defaults, reset_defaults
217+
218+
>>> use_matlab_defaults()
219+
>>> # do some matlab style plotting
220+
>>> reset_defaults()
221+
184222
"""
185223
set_defaults('freqplot', dB=True, deg=True, Hz=False, grid=True)
186224
set_defaults('statesp', use_numpy_matrix=True)
@@ -195,6 +233,14 @@ def use_fbs_defaults():
195233
frequency in rad/sec, no grid
196234
* Nyquist plots use dashed lines for mirror image of Nyquist curve
197235
236+
Examples
237+
--------
238+
>>> from control import use_fbs_defaults, reset_defaults
239+
240+
>>> use_fbs_defaults()
241+
>>> # do some FBS style plotting
242+
>>> reset_defaults()
243+
198244
"""
199245
set_defaults('freqplot', dB=False, deg=True, Hz=False, grid=False)
200246
set_defaults('nyquist', mirror_style='--')
@@ -222,6 +268,15 @@ class and functions. If flat is `False`, then matrices are
222268
Prior to release 0.9.x, the default type for 2D arrays is the Numpy
223269
`matrix` class. Starting in release 0.9.0, the default type for state
224270
space operations is a 2D array.
271+
272+
Examples
273+
--------
274+
>>> from control import use_numpy_matrix, reset_defaults
275+
276+
>>> use_numpy_matrix(True, False)
277+
>>> # do some legacy calculations using np.matrix
278+
>>> reset_defaults()
279+
225280
"""
226281
if flag and warn:
227282
warnings.warn("Return type numpy.matrix is deprecated.",
@@ -236,6 +291,16 @@ def use_legacy_defaults(version):
236291
----------
237292
version : string
238293
Version number of the defaults desired. Ranges from '0.1' to '0.8.4'.
294+
295+
Examples
296+
--------
297+
>>> from control import use_legacy_defaults, reset_defaults
298+
299+
>>> use_legacy_defaults("0.9.0")
300+
(0, 9, 0)
301+
>>> # do some legacy style plotting
302+
>>> reset_defaults()
303+
239304
"""
240305
import re
241306
(major, minor, patch) = (None, None, None) # default values

0 commit comments

Comments
 (0)