Skip to content

Commit b37c16b

Browse files
sawyerbfullersawyerbfuller
committed
docs more consistent
1 parent 4c3ed0b commit b37c16b

4 files changed

Lines changed: 64 additions & 57 deletions

File tree

‎control/frdata.py‎

Lines changed: 18 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -344,21 +344,27 @@ def __pow__(self, other):
344344
# update Sawyer B. Fuller 2020.08.14: __call__ added to provide a uniform
345345
# interface to systems in general and the lti.frequency_response method
346346
def eval(self, omega, squeeze=True):
347-
"""Evaluate a transfer function at a single angular frequency.
348-
349-
self.evalfr(omega) returns the value of the frequency response
350-
at frequency omega.
347+
"""Evaluate a transfer function at angular frequency omega.
351348
352349
Note that a "normal" FRD only returns values for which there is an
353350
entry in the omega vector. An interpolating FRD can return
354351
intermediate values.
355352
356353
Parameters
357354
----------
355+
omega: float or array_like
356+
Frequencies in radians per second
358357
squeeze: bool, optional (default=True)
359-
If True and sys is single input, single output (SISO), return a
360-
1D array or scalar the same length as omega.
361-
"""
358+
If True and sys is single input single output (SISO), returns a
359+
1D array or scalar depending on the length of omega
360+
361+
Returns
362+
-------
363+
fresp : (num_outputs, num_inputs, len(x)) or len(x) complex ndarray
364+
The frequency response of the system. Array is len(x) if and only if
365+
system is SISO and squeeze=True.
366+
367+
"""
362368
omega_array = np.array(omega, ndmin=1) # array-like version of omega
363369
if any(omega_array.imag > 0):
364370
raise ValueError("FRD.eval can only accept real-valued omega")
@@ -389,16 +395,15 @@ def eval(self, omega, squeeze=True):
389395
def __call__(self, s, squeeze=True):
390396
"""Evaluate system's transfer function at complex frequencies.
391397
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.
398+
Returns the complex frequency response `sys(s)`.
394399
395400
To evaluate at a frequency omega in radians per second, enter
396-
x = omega*j.
397-
401+
x = omega*1j or use FRD.eval(omega)
402+
398403
Parameters
399404
----------
400-
x: complex scalar or array_like
401-
Complex frequency(s)
405+
s: complex scalar or array_like
406+
Complex frequencies
402407
squeeze: bool, optional (default=True)
403408
If True and sys is single input single output (SISO), returns a
404409
1D array or scalar depending on the length of x.

‎control/lti.py‎

Lines changed: 13 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -134,10 +134,10 @@ def frequency_response(self, omega, squeeze=True):
134134
135135
Returns
136136
-------
137-
mag : (self.outputs, self.inputs, len(omega)) ndarray
137+
mag : (self.outputs, self.inputs, len(omega)) or len(omega) ndarray
138138
The magnitude (absolute value, not dB or log10) of the system
139139
frequency response.
140-
phase : (self.outputs, self.inputs, len(omega)) ndarray
140+
phase : (self.outputs, self.inputs, len(omega)) or len(omega) ndarray
141141
The wrapped phase in radians of the system frequency response.
142142
omega : ndarray
143143
The (sorted) frequencies at which the response was evaluated.
@@ -430,10 +430,10 @@ def evalfr(sys, x, squeeze=True):
430430
Evaluate the transfer function of an LTI system for complex frequency x.
431431
432432
Returns the complex frequency response `sys(x)` where `x` is `s` for
433-
continuous-time systems and `x` is `z` for discrete-time systems.
433+
continuous-time systems and `z` for discrete-time systems.
434434
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
435+
To evaluate at a frequency omega in radians per second, enter x = omega*1j,
436+
for continuous-time systems, or x = exp(1j*omega*dt) for discrete-time
437437
systems.
438438
439439
Parameters
@@ -448,9 +448,9 @@ def evalfr(sys, x, squeeze=True):
448448
449449
Returns
450450
-------
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.
451+
fresp : (sys.outputs, sys.inputs, len(x)) or len(x) complex ndarray
452+
The frequency response of the system. Array is len(x) if and only if
453+
system is SISO and squeeze=True.
454454
455455
See Also
456456
--------
@@ -481,22 +481,22 @@ def freqresp(sys, omega, squeeze=True):
481481
----------
482482
sys: StateSpace or TransferFunction
483483
Linear system
484-
omega: array_like
484+
omega: float or array_like
485485
A list of frequencies in radians/sec at which the system should be
486486
evaluated. The list can be either a python list or a numpy array
487487
and will be sorted before evaluation.
488488
squeeze: bool, optional (default=True)
489-
If True and sys is single input, single output (SISO), return a
489+
If True and sys is single input, single output (SISO), returns
490490
1D array or scalar depending on omega's length.
491491
492492
Returns
493493
-------
494-
mag : (self.outputs, self.inputs, len(omega)) ndarray
494+
mag : (sys.outputs, sys.inputs, len(omega)) or len(omega) ndarray
495495
The magnitude (absolute value, not dB or log10) of the system
496496
frequency response.
497-
phase : (self.outputs, self.inputs, len(omega)) ndarray
497+
phase : (sys.outputs, sys.inputs, len(omega)) or len(omega) ndarray
498498
The wrapped phase in radians of the system frequency response.
499-
omega : ndarray or list or tuple
499+
omega : ndarray
500500
The list of sorted frequencies at which the response was
501501
evaluated.
502502

‎control/statesp.py‎

Lines changed: 19 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -438,26 +438,26 @@ def __rdiv__(self, other):
438438
raise NotImplementedError("StateSpace.__rdiv__ is not implemented yet.")
439439

440440
def __call__(self, x, squeeze=True):
441-
"""Evaluate system's transfer function at complex frequencies.
441+
"""Evaluate system's transfer function at complex frequency.
442442
443443
Returns the complex frequency response `sys(x)` where `x` is `s` for
444-
continuous-time systems and `x` is `z` for discrete-time systems.
444+
continuous-time systems and `z` for discrete-time systems.
445445
446446
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
447+
x = omega*1j, for continuous-time systems, or x = exp(1j*omega*dt) for
448448
discrete-time systems.
449449
450450
Parameters
451451
----------
452-
x: complex scalar or array_like
453-
Complex frequency(s)
452+
x: complex or complex array_like
453+
Complex frequencies
454454
squeeze: bool, optional (default=True)
455455
If True and sys is single input single output (SISO), returns a
456456
1D array or scalar depending on the length of x.
457457
458458
Returns
459459
-------
460-
fresp : (num_outputs, num_inputs, len(x)) or len(x) complex ndarray
460+
fresp : (self.outputs, self.inputs, len(x)) or len(x) complex ndarray
461461
The frequency response of the system. Array is len(x) if and only if
462462
system is SISO and squeeze=True.
463463
@@ -472,36 +472,34 @@ def __call__(self, x, squeeze=True):
472472
else:
473473
return out
474474

475-
def slycot_laub(self, s):
476-
"""Evaluate system's transfer function at complex frequencies s
475+
def slycot_laub(self, x):
476+
"""Evaluate system's transfer function at complex frequency
477477
using Laub's method from Slycot.
478478
479479
Expects inputs and outputs to be formatted correctly. Use __call__
480480
for a more user-friendly interface.
481481
482482
Parameters
483483
----------
484-
s : array_like
484+
x : complex array_like or complex
485485
Complex frequency
486486
487487
Returns
488488
-------
489-
output : (outputs, inputs, len(s)) complex ndarray
489+
output : (number_outputs, number_inputs, len(x)) complex ndarray
490490
Frequency response
491491
"""
492492
from slycot import tb05ad
493493

494494
# preallocate
495-
s_arr = np.array(s, ndmin=1) # array-like version of s
496-
out = np.empty((self.outputs, self.inputs, len(s_arr)),
497-
dtype=complex)
495+
x_arr = np.array(x, ndmin=1) # array-like version of s
498496
n = self.states
499497
m = self.inputs
500498
p = self.outputs
499+
out = np.empty((p, m, len(x_arr)), dtype=complex)
501500
# The first call both evaluates C(sI-A)^-1 B and also returns
502501
# Hessenberg transformed matrices at, bt, ct.
503-
result = tb05ad(n, m, p, s_arr[0], self.A,
504-
self.B, self.C, job='NG')
502+
result = tb05ad(n, m, p, x_arr[0], self.A, self.B, self.C, job='NG')
505503
# When job='NG', result = (at, bt, ct, g_i, hinvb, info)
506504
at = result[0]
507505
bt = result[1]
@@ -514,8 +512,8 @@ def slycot_laub(self, s):
514512
# transformed state matrices, at, bt, ct.
515513

516514
# Start at the second frequency, already have the first.
517-
for kk, s_kk in enumerate(s_arr[1:len(s_arr)]):
518-
result = tb05ad(n, m, p, s_kk, at, bt, ct, job='NH')
515+
for kk, x_kk in enumerate(x_arr[1:len(x_arr)]):
516+
result = tb05ad(n, m, p, x_kk, at, bt, ct, job='NH')
519517
# When job='NH', result = (g_i, hinvb, info)
520518

521519
# kk+1 because enumerate starts at kk = 0.
@@ -524,23 +522,23 @@ def slycot_laub(self, s):
524522
return out
525523

526524
def horner(self, x):
527-
"""Evaluate system's transfer function at complex frequencies x
525+
"""Evaluate system's transfer function at complex frequency
528526
using Laub's or Horner's method.
529527
530-
Evaluates sys(x) where `x` is `s` for continuous-time systems and `z`
528+
Evaluates `sys(x)` where `x` is `s` for continuous-time systems and `z`
531529
for discrete-time systems.
532530
533531
Expects inputs and outputs to be formatted correctly. Use __call__
534532
for a more user-friendly interface.
535533
536534
Parameters
537535
----------
538-
x : array_like
536+
x : complex array_like or complex
539537
Complex frequencies
540538
541539
Returns
542540
-------
543-
output : (outputs, inputs, len(s)) complex ndarray
541+
output : (number_outputs, number_inputs, len(x)) complex ndarray
544542
Frequency response
545543
546544
Notes

‎control/xferfcn.py‎

Lines changed: 14 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -208,23 +208,23 @@ def __call__(self, x, squeeze=True):
208208
"""Evaluate system's transfer function at complex frequencies.
209209
210210
Returns the complex frequency response `sys(x)` where `x` is `s` for
211-
continuous-time systems and `x` is `z` for discrete-time systems.
211+
continuous-time systems and `z` for discrete-time systems.
212212
213213
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
214+
x = omega*1j, for continuous-time systems, or x = exp(1j*omega*dt) for
215215
discrete-time systems.
216216
217217
Parameters
218218
----------
219-
x: complex scalar or array_like
220-
Complex frequency(s)
219+
x: complex array_like or complex
220+
Complex frequencies
221221
squeeze: bool, optional (default=True)
222222
If True and sys is single input single output (SISO), returns a
223223
1D array or scalar depending on the length of x.
224224
225225
Returns
226226
-------
227-
fresp : (num_outputs, num_inputs, len(x)) or len(x) complex ndarray
227+
fresp : (self.outputs, self.inputs, len(x)) or len(x) complex ndarray
228228
The frequency response of the system. Array is len(x) if and only if
229229
system is SISO and squeeze=True.
230230
@@ -239,22 +239,26 @@ def __call__(self, x, squeeze=True):
239239
else:
240240
return out
241241

242-
def horner(self, s):
243-
"""Evaluates system's transfer function at complex frequencies s
244-
using Horner's method.
242+
def horner(self, x):
243+
"""Evaluate system's transfer function at complex frequency
244+
using Horner's method.
245245
246+
Evaluates `sys(x)` where `x` is `s` for continuous-time systems and `z`
247+
for discrete-time systems.
248+
246249
Expects inputs and outputs to be formatted correctly. Use __call__
247250
for a more user-friendly interface.
248251
249252
Parameters
250253
----------
251-
s : array_like or scalar
254+
x : complex array_like or complex
252255
Complex frequencies
253256
254257
Returns
255258
-------
256-
output : (outputs, inputs, len(s)) complex ndarray
259+
output : (self.outputs, self.inputs, len(x)) complex ndarray
257260
Frequency response
261+
258262
"""
259263
s_arr = np.array(s, ndmin=1) # force to be an array
260264
out = empty((self.outputs, self.inputs, len(s_arr)), dtype=complex)

0 commit comments

Comments
 (0)