Skip to content

Commit 472b376

Browse files
murrayrmmurrayrm
committed
Added Eike Welk's documenation changes + a few small tweaks (see ChangeLog)
1 parent c63dee8 commit 472b376

15 files changed

Lines changed: 830 additions & 434 deletions

‎ChangeLog‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,21 @@
1+
2011-06-21 Richard Murray <murray@malabar.local>
2+
3+
* src/statesp.py (_mimo2siso): Moved function from matlab.py.
4+
5+
* src/timeresp.py: added file documentation + split out and updated
6+
copyright info. Small corrections to documentation.
7+
(InitialResponse): Added missing transpose argument in call to
8+
ForcedResponse
9+
10+
* src/matlab.py: minor changes to documentation to avoid line wraps
11+
on standard (80 col) terminal window
12+
13+
* src/matlab.py: removed time-series convention documentation from
14+
matlab.py since current MATLAB version uses standard conventions.
15+
This documentation is currently in timeresp.py.
16+
17+
* src/*, doc/*: added Eike Welk's documentation modifications
18+
119
2011-06-18 Richard Murray <murray@malabar.local>
220

321
* src/timeresp.py, src/matlab.py: moved documentation about time

‎doc/conf.py‎

Lines changed: 15 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -19,15 +19,22 @@
1919
sys.path.insert(0, os.path.abspath('.'))
2020
sys.path.append(os.path.abspath('../src'))
2121

22+
2223
# -- General configuration -----------------------------------------------------
2324

2425
# If your documentation needs a minimal Sphinx version, state it here.
2526
#needs_sphinx = '1.0'
2627

2728
# Add any Sphinx extension module names here, as strings. They can be extensions
2829
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
30+
# Additional interesting extensions:
31+
# ``sphinx.ext.autosummary`` : Generate function/method/attribute summary
32+
# lists
33+
# ``sphinx.ext.extlinks`` : Shorten external links
34+
# ``sphinx.ext.viewcode`` : Include highlighted source code in the
35+
# documentation
2936
extensions = ['sphinx.ext.autodoc', 'numpydoc', 'sphinx.ext.pngmath',
30-
'sphinx.ext.intersphinx']
37+
'sphinx.ext.intersphinx', 'sphinx.ext.todo']
3138

3239
# Add any paths that contain templates here, relative to this directory.
3340
templates_path = ['_templates']
@@ -90,7 +97,13 @@
9097

9198
#This config value contains the locations and names of other projects that
9299
#should be linked to in this documentation.
93-
intersphinx_mapping = {'scipy':('http://docs.scipy.org/doc/scipy/reference/', None)}
100+
intersphinx_mapping = \
101+
{'scipy':('http://docs.scipy.org/doc/scipy/reference/', None),
102+
'numpy':('http://docs.scipy.org/doc/numpy/reference/', None)}
103+
104+
#If this is True, todo and todolist produce output, else they produce nothing.
105+
#The default is False.
106+
todo_include_todos = True
94107

95108

96109
# -- Options for HTML output ---------------------------------------------------

‎doc/index.rst‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,3 +23,6 @@ Indices and tables
2323
* :ref:`modindex`
2424
* :ref:`search`
2525

26+
----------------------------------
27+
28+
.. todolist::

‎doc/matlab_strings.rst‎

Lines changed: 21 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,4 +4,24 @@ Matlab-like Routines
44
The Matlab Module
55
=================
66
.. automodule:: matlab
7-
:members:
7+
:members:
8+
9+
.. todo::
10+
The following functions should be documented in their own modules!
11+
This is only a temporary solution.
12+
13+
.. autofunction:: pzmap.pzmap
14+
.. autofunction:: freqplot.nyquist
15+
.. autofunction:: nichols.nichols
16+
.. autofunction:: statefbk.place
17+
.. autofunction:: statefbk.lqr
18+
.. autofunction:: statefbk.ctrb
19+
.. autofunction:: statefbk.obsv
20+
.. autofunction:: statefbk.gram
21+
.. autofunction:: delay.pade
22+
.. autofunction:: freqplot.gangof4
23+
.. autofunction:: ctrlutil.unwrap
24+
.. autofunction:: mateqn.lyap
25+
.. autofunction:: mateqn.dlyap
26+
.. autofunction:: mateqn.care
27+
.. autofunction:: mateqn.dare

‎src/ctrlutil.py‎

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -52,8 +52,6 @@
5252

5353
def unwrap(angle, period=2*pi):
5454
"""Unwrap a phase angle to give a continuous curve
55-
56-
Usage: Y = unwrap(X, period=2``*``pi)
5755
5856
Parameters
5957
----------
@@ -66,6 +64,14 @@ def unwrap(angle, period=2*pi):
6664
-------
6765
Y : array_like
6866
Output array, with jumps of period/2 eliminated
67+
68+
Examples
69+
--------
70+
>>> import numpy as np
71+
>>> X = [5.74, 5.97, 6.19, 0.13, 0.35, 0.57]
72+
>>> unwrap(X, period=2 * np.pi)
73+
[5.74, 5.97, 6.19, 6.413185307179586, 6.633185307179586, 6.8531853071795865]
74+
6975
"""
7076
wrap = 0;
7177
last = angle[0];

‎src/delay.py‎

Lines changed: 18 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -40,17 +40,29 @@
4040
#
4141
# $Id$
4242

43+
from __future__ import division
44+
45+
4346
def pade(T, n=1):
4447
"""
48+
Create a linear system that approximates a delay.
49+
4550
Return the numerator and denominator coefficients of the Pade approximation.
4651
47-
Inputs:
48-
T --> time delay
49-
n --> order of approximation
52+
Parameters
53+
----------
54+
T : number
55+
time delay
56+
n : integer
57+
order of approximation
5058
51-
Outputs:
52-
num, den --> arrays in descending powers of s.
53-
59+
Returns
60+
-------
61+
num, den : array
62+
Polynomial coefficients of the delay model, in descending powers of s.
63+
64+
Notes
65+
-----
5466
Based on an algorithm in Golub and van Loan, "Matrix Computation" 3rd.
5567
Ed. pp. 572-574.
5668
"""

‎src/freqplot.py‎

Lines changed: 44 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -59,10 +59,6 @@ def bode(syslist, omega=None, dB=False, Hz=False, deg=True,
5959
color=None, Plot=True):
6060
"""Bode plot for a system
6161
62-
Usage
63-
=====
64-
(mag, phase, omega) = bode(syslist, omega=None, dB=False, Hz=False, color=None, deg=True, Plot=True)
65-
6662
Plots a Bode plot for the system over a (optional) frequency range.
6763
6864
Parameters
@@ -82,17 +78,26 @@ def bode(syslist, omega=None, dB=False, Hz=False, deg=True,
8278
Plot : boolean
8379
If True, plot magnitude and phase
8480
85-
Return values
86-
-------------
87-
mag : magnitude array (list if len(syslist) > 1)
88-
phase : phase array (list if len(syslist) > 1)
89-
omega : frequency array (list if len(syslist) > 1)
90-
81+
Returns
82+
-------
83+
mag : array (list if len(syslist) > 1)
84+
magnitude
85+
phase : array (list if len(syslist) > 1)
86+
phase
87+
omega : array (list if len(syslist) > 1)
88+
frequency
89+
9190
Notes
9291
-----
9392
1. Alternatively, you may use the lower-level method
9493
(mag, phase, freq) = sys.freqresp(freq) to generate the frequency
9594
response for a system, but it returns a MIMO response.
95+
96+
Examples
97+
--------
98+
>>> from matlab import ss
99+
>>> sys = ss("1. -2; 3. -4", "5.; 7", "6. 8", "9.")
100+
>>> mag, phase, omega = bode(sys)
96101
"""
97102
# If argument was a singleton, turn it into a list
98103
if (not getattr(syslist, '__iter__', False)):
@@ -176,26 +181,31 @@ def bode(syslist, omega=None, dB=False, Hz=False, deg=True,
176181
def nyquist(syslist, omega=None, Plot=True):
177182
"""Nyquist plot for a system
178183
179-
Usage
180-
=====
181-
real, imag, freq = nyquist(sys, omega=None, Plot=True)
182-
183184
Plots a Nyquist plot for the system over a (optional) frequency range.
184185
185186
Parameters
186187
----------
187-
syslist : linsys
188+
syslist : list of Lti
188189
List of linear input/output systems (single system is OK)
189190
omega : freq_range
190191
Range of frequencies (list or bounds) in rad/sec
191192
Plot : boolean
192193
if True, plot magnitude
193194
194-
Return values
195-
-------------
196-
real : real part of the frequency response array
197-
imag : imaginary part of the frequency response array
198-
freq : frequencies
195+
Returns
196+
-------
197+
real : array
198+
real part of the frequency response array
199+
imag : array
200+
imaginary part of the frequency response array
201+
freq : array
202+
frequencies
203+
204+
Examples
205+
--------
206+
>>> from matlab import ss
207+
>>> sys = ss("1. -2; 3. -4", "5.; 7", "6. 8", "9.")
208+
>>> real, imag, freq = nyquist(sys)
199209
"""
200210
# If argument was a singleton, turn it into a list
201211
if (not getattr(syslist, '__iter__', False)):
@@ -238,22 +248,18 @@ def nyquist(syslist, omega=None, Plot=True):
238248
def gangof4(P, C, omega=None):
239249
"""Plot the "Gang of 4" transfer functions for a system
240250
241-
Usage
242-
=====
243-
gangof4(P, C, omega=None)
244-
245251
Generates a 2x2 plot showing the "Gang of 4" sensitivity functions
246252
[T, PS; CS, S]
247253
248254
Parameters
249255
----------
250-
P, C : linsys
256+
P, C : Lti
251257
Linear input/output systems (process and control)
252-
omega : freq_range
258+
omega : array
253259
Range of frequencies (list or bounds) in rad/sec
254260
255-
Return values
256-
-------------
261+
Returns
262+
-------
257263
None
258264
"""
259265
if (P.inputs > 1 or P.outputs > 1 or C.inputs > 1 or C.outputs >1):
@@ -400,22 +406,24 @@ def default_frequency_range(syslist):
400406
"""Compute a reasonable default frequency range for frequency
401407
domain plots.
402408
403-
Usage
404-
=====
405-
omega = default_frequency_range(syslist)
406-
407409
Finds a reasonable default frequency range by examining the features
408410
(poles and zeros) of the systems in syslist.
409411
410412
Parameters
411413
----------
412-
syslist : linsys
414+
syslist : list of Lti
413415
List of linear input/output systems (single system is OK)
414416
415-
Return values
416-
-------------
417-
omega : freq_range
417+
Return
418+
------
419+
omega : array
418420
Range of frequencies in rad/sec
421+
422+
Examples
423+
--------
424+
>>> from matlab import ss
425+
>>> sys = ss("1. -2; 3. -4", "5.; 7", "6. 8", "9.")
426+
>>> omega = default_frequency_range(sys)
419427
"""
420428
# This code looks at the poles and zeros of all of the systems that
421429
# we are plotting and sets the frequency range to be one decade above

‎src/mateqn.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -38,9 +38,9 @@
3838
"""
3939

4040
from numpy.linalg import inv
41-
from scipy import shape,size,asarray,copy,zeros,eye,dot
41+
from scipy import shape, size, asarray, copy, zeros, eye, dot
4242

43-
from control.exception import ControlSlycot,ControlArgument
43+
from exception import ControlSlycot, ControlArgument
4444

4545
#### Lyapunov equation solvers lyap and dlyap
4646

0 commit comments

Comments
 (0)