Skip to content

Commit 60433e0

Browse files
sawyerbfullersawyerbfuller
committed
better docstrings conforming to numpydoc
1 parent 94322c8 commit 60433e0

4 files changed

Lines changed: 77 additions & 46 deletions

File tree

‎control/frdata.py‎

Lines changed: 17 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -100,6 +100,7 @@ def __init__(self, *args, **kwargs):
100100
object, other than an FRD, call FRD(sys, omega)
101101
102102
"""
103+
# TODO: discrete-time FRD systems?
103104
smooth = kwargs.get('smooth', False)
104105

105106
if len(args) == 2:
@@ -386,29 +387,33 @@ def eval(self, omega, squeeze=True):
386387
return out
387388

388389
def __call__(self, s, squeeze=True):
389-
"""Evaluate the system's transfer function at complex frequencies s.
390+
"""Evaluate system's transfer function at complex frequencies.
391+
392+
Returns the complex frequency response `sys(x)` where `x` is `s` for
393+
continuous-time systems and `x` is `z` for discrete-time systems.
390394
391-
For a SISO system, returns the complex value of the
392-
transfer function. For a MIMO transfer fuction, returns a
393-
matrix of values.
395+
To evaluate at a frequency omega in radians per second, enter
396+
x = omega*j.
394397
395398
Parameters
396399
----------
397-
s : scalar or array_like
398-
Complex frequencies
400+
x: complex scalar or array_like
401+
Complex frequency(s)
399402
squeeze: bool, optional (default=True)
400-
If True and sys is single input, single output (SISO), return a
401-
1D array or scalar depending on omega's length.
402-
403+
If True and sys is single input single output (SISO), returns a
404+
1D array or scalar depending on the length of x.
405+
403406
Returns
404407
-------
405-
ndarray or scalar
406-
Frequency response
408+
fresp : (num_outputs, num_inputs, len(x)) or len(x) complex ndarray
409+
The frequency response of the system. Array is len(x) if and only if
410+
system is SISO and squeeze=True.
407411
408412
Raises
409413
------
410414
ValueError
411-
If `s` is not purely imaginary.
415+
If `s` is not purely imaginary, because FrequencyDomainData systems
416+
are only defined at imaginary frequency values.
412417
413418
"""
414419
if any(abs(np.array(s, ndmin=1).real) > 0):

‎control/lti.py‎

Lines changed: 17 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -428,23 +428,29 @@ def damp(sys, doprint=True):
428428
def evalfr(sys, x, squeeze=True):
429429
"""
430430
Evaluate the transfer function of an LTI system for complex frequency x.
431+
432+
Returns the complex frequency response `sys(x)` where `x` is `s` for
433+
continuous-time systems and `x` is `z` for discrete-time systems.
431434
432-
To evaluate at a frequency, enter x = omega*j, where omega is the
433-
frequency in radians per second
435+
To evaluate at a frequency omega in radians per second, enter x = omega*j,
436+
for continuous-time systems, or x = exp(j*omega*dt) for discrete-time
437+
systems.
434438
435439
Parameters
436440
----------
437441
sys: StateSpace or TransferFunction
438442
Linear system
439-
x: scalar or array_like
440-
Complex number
443+
x: complex scalar or array_like
444+
Complex frequency(s)
441445
squeeze: bool, optional (default=True)
442-
If True and sys is single input, single output (SISO), return a
443-
1D array or scalar depending on omega's length.
444-
446+
If True and sys is single input single output (SISO), returns a
447+
1D array or scalar depending on the length of x.
448+
445449
Returns
446450
-------
447-
fresp: ndarray
451+
fresp : (num_outputs, num_inputs, len(x)) or len(x) complex ndarray
452+
The frequency response of the system. If system is SISO and squeezeThe size of the array depends on
453+
whether system is SISO and squeeze keyword.
448454
449455
See Also
450456
--------
@@ -453,8 +459,8 @@ def evalfr(sys, x, squeeze=True):
453459
454460
Notes
455461
-----
456-
This function is a wrapper for StateSpace.evalfr and
457-
TransferFunction.evalfr.
462+
This function is a wrapper for StateSpace.__call__ and
463+
TransferFunction.__call__.
458464
459465
Examples
460466
--------
@@ -465,15 +471,7 @@ def evalfr(sys, x, squeeze=True):
465471
466472
.. todo:: Add example with MIMO system
467473
"""
468-
out = sys.horner(x)
469-
if not hasattr(x, '__len__'):
470-
# received a scalar x, squeeze down the array along last dim
471-
out = np.squeeze(out, axis=2)
472-
if squeeze and issiso(sys):
473-
return out[0][0]
474-
else:
475-
return out
476-
474+
return sys.__call__(x, squeeze=squeeze)
477475

478476
def freqresp(sys, omega, squeeze=True):
479477
"""

‎control/statesp.py‎

Lines changed: 20 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -440,12 +440,26 @@ def __rdiv__(self, other):
440440
def __call__(self, x, squeeze=True):
441441
"""Evaluate system's transfer function at complex frequencies.
442442
443-
Evaluates at complex frequency x, where x is s or z dependong on
444-
whether the system is continuous or discrete-time.
445-
446-
If squeeze is True (default) and sys is single input, single output
447-
(SISO), return a 1D array or scalar depending on the size of x.
448-
For a MIMO system, returns an (n_outputs, n_inputs, n_x) array.
443+
Returns the complex frequency response `sys(x)` where `x` is `s` for
444+
continuous-time systems and `x` is `z` for discrete-time systems.
445+
446+
To evaluate at a frequency omega in radians per second, enter
447+
x = omega*j, for continuous-time systems, or x = exp(j*omega*dt) for
448+
discrete-time systems.
449+
450+
Parameters
451+
----------
452+
x: complex scalar or array_like
453+
Complex frequency(s)
454+
squeeze: bool, optional (default=True)
455+
If True and sys is single input single output (SISO), returns a
456+
1D array or scalar depending on the length of x.
457+
458+
Returns
459+
-------
460+
fresp : (num_outputs, num_inputs, len(x)) or len(x) complex ndarray
461+
The frequency response of the system. Array is len(x) if and only if
462+
system is SISO and squeeze=True.
449463
450464
"""
451465
# Use Slycot if available

‎control/xferfcn.py‎

Lines changed: 23 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -207,14 +207,28 @@ def __init__(self, *args):
207207
def __call__(self, x, squeeze=True):
208208
"""Evaluate system's transfer function at complex frequencies.
209209
210-
Evaluates at complex frequencies x, where x is s or z dependong on
211-
whether the system is continuous or discrete-time.
212-
213-
If squeeze is True (default) and sys is single input, single output
214-
(SISO), return a 1D array or scalar depending on the shape of x.
215-
For a MIMO system, returns an (n_outputs, n_inputs, n_x) array.
210+
Returns the complex frequency response `sys(x)` where `x` is `s` for
211+
continuous-time systems and `x` is `z` for discrete-time systems.
212+
213+
To evaluate at a frequency omega in radians per second, enter
214+
x = omega*j, for continuous-time systems, or x = exp(j*omega*dt) for
215+
discrete-time systems.
216+
217+
Parameters
218+
----------
219+
x: complex scalar or array_like
220+
Complex frequency(s)
221+
squeeze: bool, optional (default=True)
222+
If True and sys is single input single output (SISO), returns a
223+
1D array or scalar depending on the length of x.
224+
225+
Returns
226+
-------
227+
fresp : (num_outputs, num_inputs, len(x)) or len(x) complex ndarray
228+
The frequency response of the system. Array is len(x) if and only if
229+
system is SISO and squeeze=True.
216230
217-
"""
231+
"""
218232
out = self.horner(x)
219233
if not hasattr(x, '__len__'):
220234
# received a scalar x, squeeze down the array along last dim
@@ -226,15 +240,15 @@ def __call__(self, x, squeeze=True):
226240
return out
227241

228242
def horner(self, s):
229-
"""Evaluate system's transfer function at complex frequencies s
243+
"""Evaluates system's transfer function at complex frequencies s
230244
using Horner's method.
231245
232246
Expects inputs and outputs to be formatted correctly. Use __call__
233247
for a more user-friendly interface.
234248
235249
Parameters
236250
----------
237-
s : array_like
251+
s : array_like or scalar
238252
Complex frequencies
239253
240254
Returns

0 commit comments

Comments
 (0)