Skip to content

Commit 6c8da96

Browse files
murrayrmmurrayrm
committed
update docstrings for LTI.__call__: clearer language + consistency
1 parent acaa417 commit 6c8da96

4 files changed

Lines changed: 135 additions & 137 deletions

File tree

‎control/frdata.py‎

Lines changed: 45 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -679,37 +679,38 @@ def eval(self, omega, squeeze=None):
679679

680680
return _process_frequency_response(self, omega, out, squeeze=squeeze)
681681

682-
def __call__(self, s=None, squeeze=None, return_magphase=None):
683-
"""Evaluate system's transfer function at complex frequencies.
684-
685-
Returns the complex frequency response ``sys(s)`` of system `sys`
686-
with ``m = sys.ninputs`` number of inputs and ``p = sys.noutputs``
687-
number of outputs.
688-
689-
To evaluate at a frequency omega in radians per second, enter
690-
``s = omega * 1j`` or use ``sys.eval(omega)``.
691-
692-
For a frequency response data object, the argument must be an
693-
imaginary number (since only the frequency response is defined).
694-
695-
If `s` is not given, this function creates a copy of a frequency
682+
def __call__(self, x=None, squeeze=None, return_magphase=None):
683+
"""Evaluate system transfer function at point in complex plane.
684+
685+
Returns the value of the system's transfer function at a point `x`
686+
in the complex plane, where `x` is `s` for continuous-time systems
687+
and `z` for discrete-time systems. For a frequency response data
688+
object, the argument should be an imaginary number (since only the
689+
frequency response is defined) and only the imaginary component of
690+
`x` will be used.
691+
692+
By default, a (complex) scalar will be returned for SISO systems
693+
and a p x m array will be return for MIMO systems with m inputs and
694+
p outputs. This can be changed using the `squeeze` keyword.
695+
696+
To evaluate at a frequency `omega` in radians per second, enter ``x
697+
= omega * 1j`` for continuous-time systems, ``x = exp(1j * omega *
698+
dt)`` for discrete-time systems, or use the
699+
`~LTI.frequency_response` method.
700+
701+
If `x` is not given, this function creates a copy of a frequency
696702
response data object with a different set of output settings.
697703
698704
Parameters
699705
----------
700-
s : complex scalar or 1D array_like
701-
Complex frequencies. If not specified, return a copy of the
702-
frequency response data object with updated settings for output
703-
processing (`squeeze`, `return_magphase`).
704-
706+
x : complex scalar or 1D array_like
707+
Imaginary value(s) at which frequency response will be evaluated.
708+
The real component of `x` is ignored. If not specified, return
709+
a copy of the frequency response data object with updated
710+
settings for output processing (`squeeze`, `return_magphase`).
705711
squeeze : bool, optional
706-
If `squeeze` = True, remove single-dimensional entries from the
707-
shape of the output even if the system is not SISO. If
708-
`squeeze` = False, keep all indices (output, input and, if
709-
omega is array_like, frequency) even if the system is SISO. The
710-
default value can be set using
711-
`config.defaults['control.squeeze_frequency_response']`.
712-
712+
Squeeze output, as described below. Default value can be set
713+
using `config.defaults['control.squeeze_frequency_response']`.
713714
return_magphase : bool, optional
714715
If True, then a frequency response data object will
715716
enumerate as a tuple of the form ``(mag, phase, omega)`` where
@@ -721,12 +722,12 @@ def __call__(self, s=None, squeeze=None, return_magphase=None):
721722
Returns
722723
-------
723724
fresp : complex ndarray
724-
The frequency response of the system. If the system is SISO and
725-
squeeze is not True, the shape of the array matches the shape of
726-
omega. If the system is not SISO or squeeze is False, the first
727-
two dimensions of the array are indices for the output and input
728-
and the remaining dimensions match omega. If `squeeze` is True
729-
then single-dimensional axes are removed.
725+
The value of the system transfer function at `x`. If the system
726+
is SISO and `squeeze` is not True, the shape of the array matches
727+
the shape of `x`. If the system is not SISO or `squeeze` is
728+
False, the first two dimensions of the array are indices for the
729+
output and input and the remaining dimensions match `x`. If
730+
`squeeze` is True then single-dimensional axes are removed.
730731
731732
Raises
732733
------
@@ -736,7 +737,7 @@ def __call__(self, s=None, squeeze=None, return_magphase=None):
736737
real frequencies).
737738
738739
"""
739-
if s is None:
740+
if x is None:
740741
# Create a copy of the response with new keywords
741742
response = copy(self)
742743

@@ -748,18 +749,18 @@ def __call__(self, s=None, squeeze=None, return_magphase=None):
748749
return response
749750

750751
# Make sure that we are operating on a simple list
751-
if len(np.atleast_1d(s).shape) > 1:
752+
if len(np.atleast_1d(x).shape) > 1:
752753
raise ValueError("input list must be 1D")
753754

754-
if any(abs(np.atleast_1d(s).real) > 0):
755+
if any(abs(np.atleast_1d(x).real) > 0):
755756
raise ValueError("__call__: FRD systems can only accept "
756757
"purely imaginary frequencies")
757758

758759
# need to preserve array or scalar status
759-
if hasattr(s, '__len__'):
760-
return self.eval(np.asarray(s).imag, squeeze=squeeze)
760+
if hasattr(x, '__len__'):
761+
return self.eval(np.asarray(x).imag, squeeze=squeeze)
761762
else:
762-
return self.eval(complex(s).imag, squeeze=squeeze)
763+
return self.eval(complex(x).imag, squeeze=squeeze)
763764

764765
# Implement iter to allow assigning to a tuple
765766
def __iter__(self):
@@ -800,7 +801,7 @@ def freqresp(self, omega):
800801
"""(deprecated) Evaluate transfer function at complex frequencies.
801802
802803
.. deprecated::0.9.0
803-
Method has been given the more pythonic name
804+
Method has been given the more Pythonic name
804805
`FrequencyResponseData.frequency_response`. Or use
805806
`freqresp` in the MATLAB compatibility module.
806807
@@ -818,7 +819,7 @@ def feedback(self, other=1, sign=-1):
818819
Parameters
819820
----------
820821
other : `LTI`
821-
System in the feedack path.
822+
System in the feedback path.
822823
823824
sign : float, optional
824825
Gain to use in feedback path. Defaults to -1.
@@ -928,8 +929,8 @@ def to_pandas(self):
928929
# Note: This class was initially given the name "FRD", but this caused
929930
# problems with documentation on MacOS platforms, since files were generated
930931
# for control.frd and control.FRD, which are not differentiated on most MacOS
931-
# filesystems, which are case insensitive. Renaming the FRD class to be
932-
# FrequenceResponseData and then assigning FRD to point to the same object
932+
# file systems, which are case insensitive. Renaming the FRD class to be
933+
# FrequencyResponseData and then assigning FRD to point to the same object
933934
# fixes this problem.
934935
#
935936
FRD = FrequencyResponseData
@@ -1026,7 +1027,7 @@ def frd(*args, **kwargs):
10261027
A linear system that will be evaluated for frequency response data.
10271028
response : array_like or LTI system
10281029
Complex vector with the system response or an LTI system that can
1029-
be used to copmute the frequency response at a list of frequencies.
1030+
be used to compute the frequency response at a list of frequencies.
10301031
omega : array_like
10311032
Vector of frequencies at which the response is evaluated.
10321033
dt : float, True, or None
@@ -1057,7 +1058,7 @@ def frd(*args, **kwargs):
10571058
by adding the prefix and suffix strings in
10581059
`config.defaults['iosys.sampled_system_name_prefix']` and
10591060
`config.defaults['iosys.sampled_system_name_suffix']`, with the
1060-
default being to add the suffix '$ampled'. Otherwise, a generic
1061+
default being to add the suffix '$sampled'. Otherwise, a generic
10611062
name 'sys[id]' is generated with a unique integer id
10621063
10631064
See Also

‎control/lti.py‎

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@ def __init__(self, inputs=1, outputs=1, states=None, name=None, **kwargs):
4040

4141
# TODO: update ss, tf docstrings to use this one as the primary
4242
def __call__(self, x, squeeze=None, warn_infinite=True):
43-
"""Evaluate system's frequency response at complex frequencies.
43+
"""Evaluate system transfer function at point in complex plane.
4444
4545
See `StateSpace.__call__` and `TransferFunction.__call__` for details.
4646
@@ -443,7 +443,8 @@ def evalfr(sys, x, squeeze=None):
443443
444444
See Also
445445
--------
446-
frequency_response, bode_plot
446+
StateSpace.__call__, TransferFunction.__call__, frequency_response, \
447+
bode_plot
447448
448449
Notes
449450
-----
@@ -455,8 +456,6 @@ def evalfr(sys, x, squeeze=None):
455456
>>> G = ct.ss([[-1, -2], [3, -4]], [[5], [7]], [[6, 8]], [[9]])
456457
>>> fresp = ct.evalfr(G, 1j) # evaluate at s = 1j
457458
458-
.. todo:: Add example with MIMO system
459-
460459
"""
461460
return sys(x, squeeze=squeeze)
462461

0 commit comments

Comments
 (0)