Skip to content

Commit c888b6e

Browse files
sawyerbfullersawyerbfuller
committed
numpydoc convention updates
1 parent 4e4b97f commit c888b6e

4 files changed

Lines changed: 72 additions & 49 deletions

File tree

‎control/frdata.py‎

Lines changed: 24 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -355,14 +355,14 @@ def eval(self, omega, squeeze=True):
355355
omega: float or array_like
356356
Frequencies in radians per second
357357
squeeze: bool, optional (default=True)
358-
If True and sys is single input single output (SISO), returns a
359-
1D array or scalar depending on the length of omega
358+
If True and `sys` is single input single output (SISO), returns a
359+
1D array or scalar depending on the length of `omega`
360360
361361
Returns
362362
-------
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.
363+
fresp : (self.outputs, self.inputs, len(x)) or len(x) complex ndarray
364+
The frequency response of the system. Array is ``len(x)`` if and only
365+
if system is SISO and ``squeeze=True``.
366366
367367
"""
368368
omega_array = np.array(omega, ndmin=1) # array-like version of omega
@@ -398,27 +398,28 @@ def __call__(self, s, squeeze=True):
398398
Returns the complex frequency response `sys(s)`.
399399
400400
To evaluate at a frequency omega in radians per second, enter
401-
x = omega*1j or use FRD.eval(omega)
401+
``x = omega * 1j`` or use ``sys.eval(omega)``
402402
403403
Parameters
404404
----------
405405
s: complex scalar or array_like
406406
Complex frequencies
407407
squeeze: bool, optional (default=True)
408-
If True and sys is single input single output (SISO), returns a
409-
1D array or scalar depending on the length of x.
408+
If True and `sys` is single input single output (SISO), returns a
409+
1D array or scalar depending on the length of x`.
410410
411411
Returns
412412
-------
413-
fresp : (num_outputs, num_inputs, len(x)) or len(x) complex ndarray
414-
The frequency response of the system. Array is len(x) if and only if
415-
system is SISO and squeeze=True.
413+
fresp : (self.outputs, self.inputs, len(s)) or len(s) complex ndarray
414+
The frequency response of the system. Array is ``len(s)`` if and
415+
only if system is SISO and ``squeeze=True``.
416416
417417
Raises
418418
------
419419
ValueError
420-
If `s` is not purely imaginary, because FrequencyDomainData systems
421-
are only defined at imaginary frequency values.
420+
If `s` is not purely imaginary, because
421+
:class:`FrequencyDomainData` systems are only defined at imaginary
422+
frequency values.
422423
423424
"""
424425
if any(abs(np.array(s, ndmin=1).real) > 0):
@@ -431,11 +432,18 @@ def __call__(self, s, squeeze=True):
431432
return self.eval(complex(s).imag, squeeze=squeeze)
432433

433434
def freqresp(self, omega):
434-
warn("FrequencyResponseData.freqresp(omega) will be deprecated in a "
435+
"""(deprecated) Evaluate transfer function at complex frequencies.
436+
437+
.. deprecated::0.9.0
438+
Method has been given the more pythonic name
439+
:meth:`FrequencyResponseData.frequency_response`. Or use
440+
:func:`freqresp` in the MATLAB compatibility module.
441+
"""
442+
warn("FrequencyResponseData.freqresp(omega) will be removed in a "
435443
"future release of python-control; use "
436-
"FrequencyResponseData.frequency_response(sys, omega), or "
444+
"FrequencyResponseData.frequency_response(omega), or "
437445
"freqresp(sys, omega) in the MATLAB compatibility module "
438-
"instead", PendingDeprecationWarning)
446+
"instead", DeprecationWarning)
439447
return self.frequency_response(omega)
440448

441449
def feedback(self, other=1, sign=-1):

‎control/lti.py‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -432,9 +432,10 @@ def evalfr(sys, x, squeeze=True):
432432
Returns the complex frequency response `sys(x)` where `x` is `s` for
433433
continuous-time systems and `z` for discrete-time systems.
434434
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
437-
systems.
435+
To evaluate at a frequency omega in radians per second, enter
436+
``x = omega * 1j`` for continuous-time systems, or
437+
``x = exp(1j * omega * dt)`` for discrete-time systems, or use
438+
``freqresp(sys, omega)``.
438439
439440
Parameters
440441
----------

‎control/statesp.py‎

Lines changed: 24 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -444,22 +444,23 @@ def __call__(self, x, squeeze=True):
444444
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*1j, for continuous-time systems, or x = exp(1j*omega*dt) for
448-
discrete-time systems.
447+
``x = omega * 1j``, for continuous-time systems, or
448+
``x = exp(1j * omega * dt)`` for discrete-time systems. Or use
449+
:meth:`StateSpace.frequency_response`.
449450
450451
Parameters
451452
----------
452453
x: complex or complex array_like
453454
Complex frequencies
454455
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.
456+
If True and `sys` is single input single output (SISO), returns a
457+
1D array or scalar depending on the length of `x`.
457458
458459
Returns
459460
-------
460461
fresp : (self.outputs, self.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.
462+
The frequency response of the system. Array is ``len(x)`` if and
463+
only if system is SISO and ``squeeze=True``.
463464
464465
"""
465466
# Use Slycot if available
@@ -476,7 +477,7 @@ def slycot_laub(self, x):
476477
"""Evaluate system's transfer function at complex frequency
477478
using Laub's method from Slycot.
478479
479-
Expects inputs and outputs to be formatted correctly. Use __call__
480+
Expects inputs and outputs to be formatted correctly. Use ``sys(x)``
480481
for a more user-friendly interface.
481482
482483
Parameters
@@ -492,7 +493,7 @@ def slycot_laub(self, x):
492493
from slycot import tb05ad
493494

494495
# preallocate
495-
x_arr = np.array(x, ndmin=1) # array-like version of s
496+
x_arr = np.atleast_1d(x) # array-like version of x
496497
n = self.states
497498
m = self.inputs
498499
p = self.outputs
@@ -528,7 +529,7 @@ def horner(self, x):
528529
Evaluates `sys(x)` where `x` is `s` for continuous-time systems and `z`
529530
for discrete-time systems.
530531
531-
Expects inputs and outputs to be formatted correctly. Use __call__
532+
Expects inputs and outputs to be formatted correctly. Use ``sys(x)``
532533
for a more user-friendly interface.
533534
534535
Parameters
@@ -538,20 +539,20 @@ def horner(self, x):
538539
539540
Returns
540541
-------
541-
output : (number_outputs, number_inputs, len(x)) complex ndarray
542+
output : (self.outputs, self.inputs, len(x)) complex ndarray
542543
Frequency response
543544
544545
Notes
545546
-----
546-
Attempts to use Laub's method from Slycot library, with a
547-
fall-back to python code.
547+
Attempts to use Laub's method from Slycot library, with a
548+
fall-back to python code.
548549
"""
549550
try:
550551
out = self.slycot_laub(x)
551552
except (ImportError, Exception):
552553
# Fall back because either Slycot unavailable or cannot handle
553554
# certain cases.
554-
x_arr = np.array(x, ndmin=1) # force to be an array
555+
x_arr = np.atleast_1d(x) # force to be an array
555556
# Preallocate
556557
out = empty((self.outputs, self.inputs, len(x_arr)), dtype=complex)
557558

@@ -564,11 +565,17 @@ def horner(self, x):
564565
return out
565566

566567
def freqresp(self, omega):
567-
warn("StateSpace.freqresp(omega) will be deprecated in a "
568+
"""(deprecated) Evaluate transfer function at complex frequencies.
569+
570+
.. deprecated::0.9.0
571+
Method has been given the more pythonic name
572+
:meth:`StateSpace.frequency_response`. Or use
573+
:func:`freqresp` in the MATLAB compatibility module.
574+
"""
575+
warn("StateSpace.freqresp(omega) will be removed in a "
568576
"future release of python-control; use "
569-
"StateSpace.frequency_response(sys, omega), or "
570-
"freqresp(sys, omega) in the MATLAB compatibility module "
571-
"instead", PendingDeprecationWarning)
577+
"sys.frequency_response(omega), or freqresp(sys, omega) in the "
578+
"MATLAB compatibility module instead", DeprecationWarning)
572579
return self.frequency_response(omega)
573580

574581
# Compute poles and zeros

‎control/xferfcn.py‎

Lines changed: 20 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -211,22 +211,23 @@ def __call__(self, x, squeeze=True):
211211
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*1j, for continuous-time systems, or x = exp(1j*omega*dt) for
215-
discrete-time systems.
214+
``x = omega * 1j``, for continuous-time systems, or
215+
``x = exp(1j * omega * dt)`` for discrete-time systems. Or use
216+
:meth:`TransferFunction.frequency_response`.
216217
217218
Parameters
218219
----------
219220
x: complex array_like or complex
220221
Complex frequencies
221222
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.
223+
If True and `sys` is single input single output (SISO), returns a
224+
1D array or scalar depending on the length of `x`.
224225
225226
Returns
226227
-------
227228
fresp : (self.outputs, self.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.
229+
The frequency response of the system. Array is `len(x)` if and
230+
only if system is SISO and ``squeeze=True``.
230231
231232
"""
232233
out = self.horner(x)
@@ -246,7 +247,7 @@ def horner(self, x):
246247
Evaluates `sys(x)` where `x` is `s` for continuous-time systems and `z`
247248
for discrete-time systems.
248249
249-
Expects inputs and outputs to be formatted correctly. Use __call__
250+
Expects inputs and outputs to be formatted correctly. Use ``sys(x)``
250251
for a more user-friendly interface.
251252
252253
Parameters
@@ -260,8 +261,8 @@ def horner(self, x):
260261
Frequency response
261262
262263
"""
263-
s_arr = np.array(x, ndmin=1) # force to be an array
264-
out = empty((self.outputs, self.inputs, len(s_arr)), dtype=complex)
264+
x_arr = np.atleast_1d(x) # force to be an array
265+
out = empty((self.outputs, self.inputs, len(x_arr)), dtype=complex)
265266
for i in range(self.outputs):
266267
for j in range(self.inputs):
267268
out[i][j] = (polyval(self.num[i][j], x) /
@@ -659,11 +660,17 @@ def __getitem__(self, key):
659660
return TransferFunction(num, den, self.dt)
660661

661662
def freqresp(self, omega):
662-
warn("TransferFunction.freqresp(omega) will be deprecated in a "
663+
"""(deprecated) Evaluate transfer function at complex frequencies.
664+
665+
.. deprecated::0.9.0
666+
Method has been given the more pythonic name
667+
:meth:`TransferFunction.frequency_response`. Or use
668+
:func:`freqresp` in the MATLAB compatibility module.
669+
"""
670+
warn("TransferFunction.freqresp(omega) will be removed in a "
663671
"future release of python-control; use "
664-
"TransferFunction.frequency_response(sys, omega), or "
665-
"freqresp(sys, omega) in the MATLAB compatibility module "
666-
"instead", PendingDeprecationWarning)
672+
"sys.frequency_response(omega), or freqresp(sys, omega) in the "
673+
"MATLAB compatibility module instead", DeprecationWarning)
667674
return self.frequency_response(omega)
668675

669676
def pole(self):

0 commit comments

Comments
 (0)