8000 Merge pull request #804 from sawyerbfuller/update-docs · python-control/python-control@b4cd96b · GitHub
[go: up one dir, main page]
Skip to content

Commit b4cd96b

Browse files
murrayrmmurrayrm
authored
Merge pull request #804 from sawyerbfuller/update-docs
docstring improvements
2 parents 2d0d513 + 16457d7 commit b4cd96b

File tree

11 files changed

+57
-69
lines changed

11 files changed

+57
-69
lines changed

‎control/dtime.py

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -90,11 +90,11 @@ def sample_system(sysc, Ts, method='zoh', alpha=None, prewarp_frequency=None,
9090
sysd : linsys
9191
Discrete time system, with sampling rate Ts
9292
93-
Additional Parameters
94-
---------------------
93+
Other Parameters
94+
----------------
9595
inputs : int, list of str or None, optional
9696
Description of the system inputs. If not specified, the origional
97-
system inputs are used. See :class:`NamedIOSystem` for more
97+
system inputs are used. See :class:`InputOutputSystem` for more
9898
information.
9999
outputs : int, list of str or None, optional
100100
Description of the system outputs. Same format as `inputs`.

‎control/iosys.py

Lines changed: 10 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -2223,17 +2223,16 @@ def linearize(sys, xeq, ueq=None, t=0, params=None, **kw):
22232223
The linearization of the system, as a :class:`~control.LinearIOSystem`
22242224
object (which is also a :class:`~control.StateSpace` object.
22252225
2226-
Additional Parameters
2227-
---------------------
2226+
Other Parameters
2227+
----------------
22282228
inputs : int, list of str or None, optional
22292229
Description of the system inputs. If not specified, the origional
2230-
system inputs are used. See :class:`NamedIOSystem` for more
2230+
system inputs are used. See :class:`InputOutputSystem` for more
22312231
information.
22322232
outputs : int, list of str or None, optional
22332233
Description of the system outputs. Same format as `inputs`.
22342234
states : int, list of str, or None, optional
22352235
Description of the system states. Same format as `inputs`.
2236-
22372236
"""
22382237
if not isinstance(sys, InputOutputSystem):
22392238
raise TypeError("Can only linearize InputOutputSystem types")
@@ -2442,7 +2441,10 @@ def rss(states=1, outputs=1, inputs=1, strictly_proper=False, **kwargs):
24422441

24432442

24442443
def drss(*args, **kwargs):
2445-
"""Create a stable, discrete-time, random state space system
2444+
"""
2445+
drss([states, outputs, inputs, strictly_proper])
2446+
2447+
Create a stable, discrete-time, random state space system
24462448
24472449
Create a stable *discrete time* random state space object. This
24482450
function calls :func:`rss` using either the `dt` keyword provided by
@@ -2480,7 +2482,7 @@ def ss2io(*args, **kwargs):
24802482

24812483
# Convert a transfer function into an input/output system (wrapper)
24822484
def tf2io(*args, **kwargs):
2483-
"""tf2io(sys)
2485+
"""tf2io(sys[, ...])
24842486
24852487
Convert a transfer function into an I/O system
24862488
@@ -2729,8 +2731,8 @@ def interconnect(syslist, connections=None, inplist=None, outlist=None,
27292731
:func:`~control.summing_block` function and the ability to automatically
27302732
interconnect signals with the same names:
27312733
2732-
>>> P = control.tf2io(control.tf(1, [1, 0]), inputs='u', outputs='y')
2733-
>>> C = control.tf2io(control.tf(10, [1, 1]), inputs='e', outputs='u')
2734+
>>> P = control.tf(1, [1, 0], inputs='u', outputs='y')
2735+
>>> C = control.tf(10, [1, 1], inputs='e', outputs='u')
27342736
>>> sumblk = control.summing_junction(inputs=['r', '-y'], output='e')
27352737
>>> T = control.interconnect([P, C, sumblk], inputs='r', outputs='y')
27362738

‎control/mateqn.py

Lines changed: 12 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -88,7 +88,9 @@ def sb03md(n, C, A, U, dico, job='X', fact='N', trana='N', ldwork=None):
8888

8989

9090
def lyap(A, Q, C=None, E=None, method=None):
91-
"""X = lyap(A, Q) solves the continuous-time Lyapunov equation
91+
"""Solves the continuous-time Lyapunov equation
92+
93+
X = lyap(A, Q) solves
9294
9395
:math:`A X + X A^T + Q = 0`
9496
@@ -217,7 +219,9 @@ def lyap(A, Q, C=None, E=None, method=None):
217219

218220

219221
def dlyap(A, Q, C=None, E=None, method=None):
220-
"""dlyap(A, Q) solves the discrete-time Lyapunov equation
222+
"""Solves the discrete-time Lyapunov equation
223+
224+
X = dlyap(A, Q) solves
221225
222226
:math:`A X A^T - X + Q = 0`
223227
@@ -348,8 +352,9 @@ def dlyap(A, Q, C=None, E=None, method=None):
348352

349353
def care(A, B, Q, R=None, S=None, E=None, stabilizing=True, method=None,
350354
A_s="A", B_s="B", Q_s="Q", R_s="R", S_s="S", E_s="E"):
351-
"""X, L, G = care(A, B, Q, R=None) solves the continuous-time
352-
algebraic Riccati equation
355+
"""Solves the continuous-time algebraic Riccati equation
356+
357+
X, L, G = care(A, B, Q, R=None) solves
353358
354359
:math:`A^T X + X A - X B R^{-1} B^T X + Q = 0`
355360
@@ -505,9 +510,11 @@ def care(A, B, Q, R=None, S=None, E=None, stabilizing=True, method=None,
505510

506511
def dare(A, B, Q, R, S=None, E=None, stabilizing=True, method=None,
507512
A_s="A", B_s="B", Q_s="Q", R_s="R", S_s="S", E_s="E"):
508-
"""X, L, G = dare(A, B, Q, R) solves the discrete-time algebraic Riccati
513+
"""Solves the discrete-time algebraic Riccati
509514
equation
510515
516+
X, L, G = dare(A, B, Q, R) solves
517+
511518
:math:`A^T X A - X - A^T X B (B^T X B + R)^{-1} B^T X A + Q = 0`
512519
513520
where A and Q are square matrices of the same dimension. Further, Q

‎control/matlab/__init__.py

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -84,6 +84,7 @@
8484
from ..rlocus import rlocus
8585
from ..dtime import c2d
8686
from ..sisotool import sisotool
87+
from ..stochsys import lqe, dlqe
8788

8889
# Functions that are renamed in MATLAB
8990
pole, zero = poles, zeros

‎control/matlab/timeresp.py

Lines changed: 5 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,7 @@
77
__all__ = ['step', 'stepinfo', 'impulse', 'initial', 'lsim']
88

99
def step(sys, T=None, X0=0., input=0, output=None, return_x=False):
10-
'''
11-
Step response of a linear system
10+
'''Step response of a linear system
1211
1312
If the system has multiple inputs or outputs (MIMO), one input has
1413
to be selected for the simulation. Optionally, one output may be
@@ -20,35 +19,27 @@ def step(sys, T=None, X0=0., input=0, output=None, return_x=False):
2019
----------
2120
sys: StateSpace, or TransferFunction
2221
LTI system to simulate
23-
2422
T: array-like or number, optional
2523
Time vector, or simulation time duration if a number (time vector is
2624
autocomputed if not given)
27-
2825
X0: array-like or number, optional
2926
Initial condition (default = 0)
30-
3127
Numbers are converted to constant arrays with the correct shape.
32-
3328
input: int
3429
Index of the input that will be used in this simulation.
35-
3630
output: int
3731
If given, index of the output that is returned by this simulation.
3832
3933
Returns
4034
-------
4135
yout: array
4236
Response of the system
43-
4437
T: array
4538
Time values of the output
46-
4739
xout: array (if selected)
4840
Individual response of each x variable
4941
5042
51-
5243
See Also
5344
--------
5445
lsim, initial, impulse
@@ -67,8 +58,7 @@ def step(sys, T=None, X0=0., input=0, output=None, return_x=False):
6758

6859
def stepinfo(sysdata, T=None, yfinal=None, SettlingTimeThreshold=0.02,
6960
RiseTimeLimits=(0.1, 0.9)):
70-
"""
71-
Step response characteristics (Rise time, Settling Time, Peak and others).
61+
"""Step response characteristics (Rise time, Settling Time, Peak and others)
7262
7363
Parameters
7464
----------
@@ -137,8 +127,7 @@ def stepinfo(sysdata, T=None, yfinal=None, SettlingTimeThreshold=0.02,
137127
return S
138128

139129
def impulse(sys, T=None, X0=0., input=0, output=None, return_x=False):
140-
'''
141-
Impulse response of a linear system
130+
'''Impulse response of a linear system
142131
143132
If the system has multiple inputs or outputs (MIMO), one input has
144133
to be selected for the simulation. Optionally, one output may be
@@ -150,30 +139,24 @@ def impulse(sys, T=None, X0=0., input=0, output=None, return_x=False):
150139
----------
151140
sys: StateSpace, TransferFunction
152141
LTI system to simulate
153-
154142
T: array-like or number, optional
155143
Time vector, or simulation time duration if a number (time vector is
156144
autocomputed if not given)
157-
158145
X0: array-like or number, optional
159146
Initial condition (default = 0)
160147
161148
Numbers are converted to constant arrays with the correct shape.
162-
163149
input: int
164150
Index of the input that will be used in this simulation.
165-
166151
output: int
167152
Index of the output that will be used in this simulation.
168153
169154
Returns
170155
-------
171156
yout: array
172157
Response of the system
173-
174158
T: array
175159
Time values of the output
176-
177160
xout: array (if selected)
178161
Individual response of each x variable
179162
@@ -193,8 +176,7 @@ def impulse(sys, T=None, X0=0., input=0, output=None, return_x=False):
193176
return (out[1], out[0], out[2]) if return_x else (out[1], out[0])
194177

195178
def initial(sys, T=None, X0=0., input=None, output=None, return_x=False):
196-
'''
197-
Initial condition response of a linear system
179+
'''Initial condition response of a linear system
198180
199181
If the system has multiple outputs (?IMO), optionally, one output
200182
may be selected. If no selection is made for the output, all
@@ -204,31 +186,25 @@ def initial(sys, T=None, X0=0., input=None, output=None, return_x=False):
204186
----------
205187
sys: StateSpace, or TransferFunction
206188
LTI system to simulate
207-
208189
T: array-like or number, optional
209190
Time vector, or simulation time duration if a number (time vector is
210191
autocomputed if not given)
211-
212192
X0: array-like object or number, optional
213193
Initial condition (default = 0)
214194
215195
Numbers are converted to constant arrays with the correct shape.
216-
217196
input: int
218197
This input is ignored, but present for compatibility with step
219198
and impulse.
220-
221199
output: int
222200
If given, index of the output that is returned by this simulation.
223201
224202
Returns
225203
-------
226204
yout: array
227205
Response of the system
228-
229206
T: array
230207
Time values of the output
231-
232208
xout: array (if selected)
233209
Individual response of each x variable
234210
@@ -250,8 +226,7 @@ def initial(sys, T=None, X0=0., input=None, output=None, return_x=False):
250226

251227

252228
def lsim(sys, U=0., T=None, X0=0.):
253-
'''
254-
Simulate the output of a linear system.
229+
'''Simulate the output of a linear system
255230
256231
As a convenience for parameters `U`, `X0`:
257232
Numbers (scalars) are converted to constant arrays with the correct shape.
@@ -261,16 +236,13 @@ def lsim(sys, U=0., T=None, X0=0.):
261236
----------
262237
sys: LTI (StateSpace, or TransferFunction)
263238
LTI system to simulate
264-
265239
U: array-like or number, optional
266240
Input array giving input at each time `T` (default = 0).
267241
268242
If `U` is ``None`` or ``0``, a special algorithm is used. This special
269243
algorithm is faster than the general algorithm, which is used otherwise.
270-
271244
T: array-like, optional for discrete LTI `sys`
272245
Time steps at which the input is defined; values must be evenly spaced.
273-
274246
X0: array-like or number, optional
275247
Initial condition (default = 0).
276248

‎control/matlab/wrappers.py

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -178,8 +178,7 @@ def ngrid():
178178

179179

180180
def dcgain(*args):
181-
'''
182-
Compute the gain of the system in steady state.
181+
'''Compute the gain of the system in steady state
183182
184183
The function takes either 1, 2, 3, or 4 parameters:
185184

‎control/sisotool.py

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -228,10 +228,6 @@ def rootlocus_pid_designer(plant, gain='P', sign=+1, input_signal='r',
228228
229229
C_f = Kp + Ki/s + Kd*s/(tau*s + 1).
230230
231-
If `plant` is a discrete-time system, then the proportional, integral, and
232-
derivative terms are given instead by Kp, Ki*dt/2*(z+1)/(z-1), and
233-
Kd/dt*(z-1)/z, respectively.
234-
235231
::
236232
237233
------> C_ff ------ d
@@ -243,6 +239,10 @@ def rootlocus_pid_designer(plant, gain='P', sign=+1, input_signal='r',
243239
| ----- C_b <-------|
244240
---------------------------------
245241
242+
If `plant` is a discrete-time system, then the proportional, integral, and
243+
derivative terms are given instead by Kp, Ki*dt/2*(z+1)/(z-1), and
244+
Kd/dt*(z-1)/z, respectively.
245+
246246
It is also possible to move the derivative term into the feedback path
247247
`C_b` using `derivative_in_feedback_path=True`. This may be desired to
248248
avoid that the plant is subject to an impulse function when the reference

‎control/statesp.py

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -808,7 +808,7 @@ def __truediv__(self, other):
808808

809809

810810
def __call__(self, x, squeeze=None, warn_infinite=True):
811-
"""Evaluate system's transfer function at complex frequency.
811+
"""Evaluate system's frequency response at complex frequencies.
812812
813813
Returns the complex frequency response `sys(x)` where `x` is `s` for
814814
continuous-time systems and `z` for discrete-time systems.
@@ -1345,8 +1345,8 @@ def sample(self, Ts, method='zoh', alpha=None, prewarp_frequency=None,
13451345
sysd : StateSpace
13461346
Discrete-time system, with sampling rate Ts
13471347
1348-
Additional Parameters
1349-
---------------------
1348+
Other Parameters
1349+
----------------
13501350
inputs : int, list of str or None, optional
13511351
Description of the system inputs. If not specified, the origional
13521352
system inputs are used. See :class:`InputOutputSystem` for more
@@ -1521,6 +1521,7 @@ def output(self, t, x, u=None, params=None):
15211521

15221522

15231523
# TODO: add discrete time check
1524+
# TODO: copy signal names
15241525
def _convert_to_statespace(sys):
15251526
"""Convert a system to state space form (if needed).
15261527

‎control/xferfcn.py

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1128,11 +1128,11 @@ def sample(self, Ts, method='zoh', alpha=None, prewarp_frequency=None,
11281128
sysd : TransferFunction system
11291129
Discrete-time system, with sample period Ts
11301130
1131-
Additional Parameters
1132-
---------------------
1131+
Other Parameters
1132+
----------------
11331133
inputs : int, list of str or None, optional
11341134
Description of the system inputs. If not specified, the origional
1135-
system inputs are used. See :class:`NamedIOSystem` for more
1135+
system inputs are used. See :class:`InputOutputSystem` for more
11361136
information.
11371137
outputs : int, list of str or None, optional
11381138
Description of the system outputs. Same format as `inputs`.
@@ -1577,7 +1577,7 @@ def tf(*args, **kwargs):
15771577
else:
15781578
raise ValueError("Needs 1 or 2 arguments; received %i." % len(args))
15791579

1580-
1580+
# TODO: copy signal names
15811581
def ss2tf(*args, **kwargs):
15821582
"""ss2tf(sys)
15831583

0 commit comments

Comments
 (0)
0