Skip to content

Commit 724adc0

Browse files
murrayrmmurrayrm
committed
Add matlab docstring testing + fix section label capitalization
1 parent 884e865 commit 724adc0

8 files changed

Lines changed: 128 additions & 95 deletions

File tree

‎control/matlab/timeresp.py‎

Lines changed: 56 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -17,25 +17,26 @@ def step(sys, T=None, input=0, output=None, return_x=False):
1717
1818
Parameters
1919
----------
20-
sys: StateSpace, or TransferFunction
21-
LTI system to simulate
22-
T: array-like or number, optional
20+
sys : StateSpace, or TransferFunction
21+
LTI system to simulate.
22+
T : array-like or number, optional
2323
Time vector, or simulation time duration if a number (time vector is
24-
autocomputed if not given)
25-
input: int
24+
autocomputed if not given).
25+
input : int
2626
Index of the input that will be used in this simulation.
27-
output: int
27+
output : int
2828
If given, index of the output that is returned by this simulation.
29+
return_x : bool, optional
30+
If True, return the state vector in addition to outputs.
2931
3032
Returns
3133
-------
32-
yout: array
33-
Response of the system
34-
T: array
35-
Time values of the output
36-
xout: array (if selected)
37-
Individual response of each x variable
38-
34+
yout : array
35+
Response of the system.
36+
T : array
37+
Time values of the output.
38+
xout : array (if selected)
39+
Individual response of each x variable.
3940
4041
See Also
4142
--------
@@ -59,7 +60,8 @@ def step(sys, T=None, input=0, output=None, return_x=False):
5960

6061
def stepinfo(sysdata, T=None, yfinal=None, SettlingTimeThreshold=0.02,
6162
RiseTimeLimits=(0.1, 0.9)):
62-
"""Step response characteristics (Rise time, Settling Time, Peak and others)
63+
"""
64+
Step response characteristics (rise time, settling time, etc).
6365
6466
Parameters
6567
----------
@@ -76,9 +78,9 @@ def stepinfo(sysdata, T=None, yfinal=None, SettlingTimeThreshold=0.02,
7678
used for a given time series of response data. Scalar for SISO,
7779
(noutputs, ninputs) array_like for MIMO systems.
7880
SettlingTimeThreshold : float, optional
79-
Defines the error to compute settling time (default = 0.02)
81+
Defines the error to compute settling time (default = 0.02).
8082
RiseTimeLimits : tuple (lower_threshold, upper_theshold)
81-
Defines the lower and upper threshold for RiseTime computation
83+
Defines the lower and upper threshold for RiseTime computation.
8284
8385
Returns
8486
-------
@@ -109,7 +111,6 @@ def stepinfo(sysdata, T=None, yfinal=None, SettlingTimeThreshold=0.02,
109111
To get the step response characteristics from the j-th input to the
110112
i-th output, access ``S[i][j]``
111113
112-
113114
See Also
114115
--------
115116
step, lsim, initial, impulse
@@ -142,24 +143,26 @@ def impulse(sys, T=None, input=0, output=None, return_x=False):
142143
143144
Parameters
144145
----------
145-
sys: StateSpace, TransferFunction
146-
LTI system to simulate
147-
T: array-like or number, optional
146+
sys : StateSpace, TransferFunction
147+
LTI system to simulate.
148+
T : array-like or number, optional
148149
Time vector, or simulation time duration if a number (time vector is
149-
autocomputed if not given)
150-
input: int
150+
autocomputed if not given).
151+
input : int
151152
Index of the input that will be used in this simulation.
152-
output: int
153+
output : int
153154
Index of the output that will be used in this simulation.
155+
return_x : bool, optional
156+
If True, return the state vector in addition to outputs.
154157
155158
Returns
156159
-------
157-
yout: array
158-
Response of the system
159-
T: array
160-
Time values of the output
161-
xout: array (if selected)
162-
Individual response of each x variable
160+
yout : array
161+
Response of the system.
162+
T : array
163+
Time values of the output.
164+
xout : array (if selected)
165+
Individual response of each x variable.
163166
164167
See Also
165168
--------
@@ -189,27 +192,29 @@ def initial(sys, T=None, X0=0., input=None, output=None, return_x=False):
189192
190193
Parameters
191194
----------
192-
sys: StateSpace, or TransferFunction
193-
LTI system to simulate
194-
T: array-like or number, optional
195+
sys : StateSpace, or TransferFunction
196+
LTI system to simulate.
197+
T : array-like or number, optional
195198
Time vector, or simulation time duration if a number (time vector is
196-
autocomputed if not given)
197-
X0: array-like object or number, optional
198-
Initial condition (default = 0)
199-
input: int
199+
autocomputed if not given).
200+
X0 : array-like object or number, optional
201+
Initial condition (default = 0).
202+
input : int
200203
This input is ignored, but present for compatibility with step
201204
and impulse.
202-
output: int
205+
output : int
203206
If given, index of the output that is returned by this simulation.
207+
return_x : bool, optional
208+
If True, return the state vector in addition to outputs.
204209
205210
Returns
206211
-------
207-
yout: array
208-
Response of the system
209-
T: array
210-
Time values of the output
211-
xout: array (if selected)
212-
Individual response of each x variable
212+
yout : array
213+
Response of the system.
214+
T : array
215+
Time values of the output.
216+
xout : array (if selected)
217+
Individual response of each x variable.
213218
214219
See Also
215220
--------
@@ -240,25 +245,25 @@ def lsim(sys, U=0., T=None, X0=0.):
240245
241246
Parameters
242247
----------
243-
sys: LTI (StateSpace, or TransferFunction)
244-
LTI system to simulate
245-
U: array-like or number, optional
248+
sys : LTI (StateSpace, or TransferFunction)
249+
LTI system to simulate.
250+
U : array-like or number, optional
246251
Input array giving input at each time `T` (default = 0).
247252
248253
If `U` is ``None`` or ``0``, a special algorithm is used. This special
249254
algorithm is faster than the general algorithm, which is used otherwise.
250-
T: array-like, optional for discrete LTI `sys`
255+
T : array-like, optional for discrete LTI `sys`
251256
Time steps at which the input is defined; values must be evenly spaced.
252-
X0: array-like or number, optional
257+
X0 : array-like or number, optional
253258
Initial condition (default = 0).
254259
255260
Returns
256261
-------
257-
yout: array
262+
yout : array
258263
Response of the system.
259-
T: array
264+
T : array
260265
Time values of the output.
261-
xout: array
266+
xout : array
262267
Time evolution of the state vector.
263268
264269
See Also

‎control/matlab/wrappers.py‎

Lines changed: 57 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@
1515
__all__ = ['bode', 'nyquist', 'ngrid', 'rlocus', 'pzmap', 'dcgain', 'connect']
1616

1717
def bode(*args, **kwargs):
18-
"""bode(syslist[, omega, dB, Hz, deg, ...])
18+
"""bode(sys[, omega, dB, Hz, deg, ...])
1919
2020
Bode plot of the frequency response.
2121
@@ -28,23 +28,22 @@ def bode(*args, **kwargs):
2828
a list of systems can be entered, or several systems can be
2929
specified (i.e. several parameters). The sys arguments may also be
3030
interspersed with format strings. A frequency argument (array_like)
31-
may also be added, some examples::
32-
33-
>>> bode(sys, w) # one system, freq vector # doctest: +SKIP
34-
>>> bode(sys1, sys2, ..., sysN) # several systems # doctest: +SKIP
35-
>>> bode(sys1, sys2, ..., sysN, w) # doctest: +SKIP
36-
>>> bode(sys1, 'plotstyle1', ..., sysN, 'plotstyleN') # + plot formats # doctest: +SKIP
37-
38-
omega: freq_range
39-
Range of frequencies in rad/s
31+
may also be added (see Examples).
32+
omega : array
33+
Range of frequencies in rad/s.
4034
dB : boolean
41-
If True, plot result in dB
35+
If True, plot result in dB.
4236
Hz : boolean
43-
If True, plot frequency in Hz (omega must be provided in rad/sec)
37+
If True, plot frequency in Hz (omega must be provided in rad/sec).
4438
deg : boolean
45-
If True, return phase in degrees (else radians)
39+
If True, return phase in degrees (else radians).
4640
plot : boolean
47-
If True, plot magnitude and phase
41+
If True, plot magnitude and phase.
42+
43+
Returns
44+
-------
45+
mag, phase, omega : array
46+
Magnitude, phase, and frequencies represented in the Bode plot.
4847
4948
Examples
5049
--------
@@ -61,6 +60,12 @@ def bode(*args, **kwargs):
6160
* >>> bode(sys1, sys2, ..., sysN) # doctest: +SKIP
6261
* >>> bode(sys1, sys2, ..., sysN, w) # doctest: +SKIP
6362
* >>> bode(sys1, 'plotstyle1', ..., sysN, 'plotstyleN') # doctest: +SKIP
63+
64+
>>> bode(sys, w) # one system, freq vector # doctest: +SKIP
65+
>>> bode(sys1, sys2, ..., sysN) # several systems # doctest: +SKIP
66+
>>> bode(sys1, sys2, ..., sysN, w) # doctest: +SKIP
67+
>>> bode(sys1, 'plotstyle1', ..., sysN, 'plotstyleN') # doctest: +SKIP
68+
6469
"""
6570
from ..freqplot import bode_plot
6671

@@ -99,19 +104,25 @@ def nyquist(*args, plot=True, **kwargs):
99104
100105
Parameters
101106
----------
102-
sys1, ..., sysn : list of LTI
107+
syslist : list of LTI
103108
List of linear input/output systems (single system is OK).
104109
omega : array_like
105110
Set of frequencies to be evaluated, in rad/sec.
111+
omega_limits : array_like of two values
112+
Set limits for plotted frequency range. If Hz=True the limits are
113+
in Hz otherwise in rad/s. Specifying ``omega`` as a list of two
114+
elements is equivalent to providing ``omega_limits``.
115+
plot : bool
116+
If `False`, do not generate a plot.
106117
107118
Returns
108119
-------
109120
real : ndarray (or list of ndarray if len(syslist) > 1))
110-
real part of the frequency response array
121+
Real part of the frequency response array.
111122
imag : ndarray (or list of ndarray if len(syslist) > 1))
112-
imaginary part of the frequency response array
123+
Imaginary part of the frequency response array.
113124
omega : ndarray (or list of ndarray if len(syslist) > 1))
114-
frequencies in rad/s
125+
Frequencies in rad/s.
115126
116127
"""
117128
from ..freqplot import nyquist_response, nyquist_plot
@@ -217,6 +228,8 @@ def rlocus(*args, **kwargs):
217228
ylim : tuple or list, optional
218229
Set limits of y axis, normally with tuple
219230
(see :doc:`matplotlib:api/axes_api`).
231+
plot : bool
232+
If `False`, do not generate a plot.
220233
221234
Returns
222235
-------
@@ -257,19 +270,19 @@ def pzmap(*args, **kwargs):
257270
258271
Parameters
259272
----------
260-
sys: LTI (StateSpace or TransferFunction)
273+
sys : LTI (StateSpace or TransferFunction)
261274
Linear system for which poles and zeros are computed.
262-
plot: bool, optional
275+
plot : bool, optional
263276
If ``True`` a graph is generated with Matplotlib,
264277
otherwise the poles and zeros are only computed and returned.
265-
grid: boolean (default = False)
278+
grid : boolean (default = False)
266279
If True plot omega-damping grid.
267280
268281
Returns
269282
-------
270-
poles: array
283+
poles : array
271284
The system's poles.
272-
zeros: array
285+
zeros : array
273286
The system's zeros.
274287
275288
Notes
@@ -302,26 +315,36 @@ def ngrid():
302315

303316

304317
def dcgain(*args):
305-
'''Compute the gain of the system in steady state.
318+
'''dcgain(sys) \
319+
dcgain(num, den) \
320+
dcgain(Z, P, k) \
321+
dcgain(A, B, C, D)
322+
323+
Compute the gain of the system in steady state.
306324
307325
The function takes either 1, 2, 3, or 4 parameters:
308326
327+
* dcgain(sys)
328+
* dcgain(num, den)
329+
* dcgain(Z, P, k)
330+
* dcgain(A, B, C, D)
331+
309332
Parameters
310333
----------
311-
A, B, C, D: array-like
334+
A, B, C, D : array-like
312335
A linear system in state space form.
313-
Z, P, k: array-like, array-like, number
336+
Z, P, k : array-like, array-like, number
314337
A linear system in zero, pole, gain form.
315-
num, den: array-like
338+
num, den : array-like
316339
A linear system in transfer function form.
317-
sys: LTI (StateSpace or TransferFunction)
340+
sys : LTI (StateSpace or TransferFunction)
318341
A linear system object.
319342
320343
Returns
321344
-------
322-
gain: ndarray
345+
gain : ndarray
323346
The gain of each output versus each input:
324-
:math:`y = gain \\cdot u`
347+
:math:`y = gain \\cdot u`.
325348
326349
Notes
327350
-----
@@ -354,8 +377,9 @@ def dcgain(*args):
354377

355378
from ..bdalg import connect as ct_connect
356379
def connect(*args):
380+
"""connect(sys, Q, inputv, outputv)
357381
358-
"""Index-based interconnection of an LTI system.
382+
Index-based interconnection of an LTI system.
359383
360384
The system `sys` is a system typically constructed with `append`, with
361385
multiple inputs and outputs. The inputs and outputs are connected
@@ -378,9 +402,9 @@ def connect(*args):
378402
values mean the feedback is negative. A zero value is ignored. Inputs
379403
and outputs are indexed starting at 1 to communicate sign information.
380404
inputv : 1D array
381-
list of final external inputs, indexed starting at 1
405+
List of final external inputs, indexed starting at 1.
382406
outputv : 1D array
383-
list of final external outputs, indexed starting at 1
407+
List of final external outputs, indexed starting at 1.
384408
385409
Returns
386410
-------

‎control/nlsys.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1467,7 +1467,7 @@ def input_output_response(
14671467
system signals are named, these names will be used as labels for the
14681468
time response.
14691469
1470-
Other parameters
1470+
Other Parameters
14711471
----------------
14721472
ignore_errors : bool, optional
14731473
If ``False`` (default), errors during computation of the trajectory

0 commit comments

Comments
 (0)