Skip to content

Commit ecf6a38

Browse files
murrayrmmurrayrm
authored
Merge pull request #1038 from murrayrm/doc-comment_fixes-11May2024
Documentation updates and docstring unit tests
2 parents 3d79ce3 + c3ea6dc commit ecf6a38

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

48 files changed

+803
-363
lines changed

‎Pending‎

Lines changed: 0 additions & 63 deletions
This file was deleted.

‎control/bdalg.py‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -73,7 +73,7 @@ def series(sys1, *sysn, **kwargs):
7373
7474
Parameters
7575
----------
76-
sys1, sys2, ..., sysn: scalar, array, or :class:`InputOutputSystem`
76+
sys1, sys2, ..., sysn : scalar, array, or :class:`InputOutputSystem`
7777
I/O systems to combine.
7878
7979
Returns
@@ -145,7 +145,7 @@ def parallel(sys1, *sysn, **kwargs):
145145
146146
Parameters
147147
----------
148-
sys1, sys2, ..., sysn: scalar, array, or :class:`InputOutputSystem`
148+
sys1, sys2, ..., sysn : scalar, array, or :class:`InputOutputSystem`
149149
I/O systems to combine.
150150
151151
Returns
@@ -213,7 +213,7 @@ def negate(sys, **kwargs):
213213
214214
Parameters
215215
----------
216-
sys: scalar, array, or :class:`InputOutputSystem`
216+
sys : scalar, array, or :class:`InputOutputSystem`
217217
I/O systems to negate.
218218
219219
Returns
@@ -265,9 +265,9 @@ def feedback(sys1, sys2=1, sign=-1, **kwargs):
265265
266266
Parameters
267267
----------
268-
sys1, sys2: scalar, array, or :class:`InputOutputSystem`
268+
sys1, sys2 : scalar, array, or :class:`InputOutputSystem`
269269
I/O systems to combine.
270-
sign: scalar
270+
sign : scalar
271271
The sign of feedback. `sign` = -1 indicates negative feedback, and
272272
`sign` = 1 indicates positive feedback. `sign` is an optional
273273
argument; it assumes a value of -1 if not specified.
@@ -412,8 +412,8 @@ def connect(sys, Q, inputv, outputv):
412412
"""Index-based interconnection of an LTI system.
413413
414414
.. deprecated:: 0.10.0
415-
`connect` will be removed in a future version of python-control in
416-
favor of `interconnect`, which works with named signals.
415+
`connect` will be removed in a future version of python-control.
416+
Use :func:`interconnect` instead, which works with named signals.
417417
418418
The system `sys` is a system typically constructed with `append`, with
419419
multiple inputs and outputs. The inputs and outputs are connected
@@ -465,7 +465,7 @@ def connect(sys, Q, inputv, outputv):
465465
466466
"""
467467
# TODO: maintain `connect` for use in MATLAB submodule (?)
468-
warn("`connect` is deprecated; use `interconnect`", DeprecationWarning)
468+
warn("connect() is deprecated; use interconnect()", FutureWarning)
469469

470470
inputv, outputv, Q = \
471471
np.atleast_1d(inputv), np.atleast_1d(outputv), np.atleast_1d(Q)

‎control/canonical.py‎

Lines changed: 13 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -204,7 +204,7 @@ def similarity_transform(xsys, T, timescale=1, inverse=False):
204204
The matrix `T` defines the new set of coordinates z = T x.
205205
timescale : float, optional
206206
If present, also rescale the time unit to tau = timescale * t
207-
inverse: boolean, optional
207+
inverse : bool, optional
208208
If True (default), transform so z = T x. If False, transform
209209
so x = T z.
210210
@@ -397,21 +397,21 @@ def bdschur(a, condmax=None, sort=None):
397397
398398
Parameters
399399
----------
400-
a : (M, M) array_like
401-
Real matrix to decompose
402-
condmax : None or float, optional
403-
If None (default), use 1/sqrt(eps), which is approximately 1e8
404-
sort : {None, 'continuous', 'discrete'}
405-
Block sorting; see below.
400+
a : (M, M) array_like
401+
Real matrix to decompose
402+
condmax : None or float, optional
403+
If None (default), use 1/sqrt(eps), which is approximately 1e8
404+
sort : {None, 'continuous', 'discrete'}
405+
Block sorting; see below.
406406
407407
Returns
408408
-------
409-
amodal : (M, M) real ndarray
410-
Block-diagonal Schur decomposition of `a`
411-
tmodal : (M, M) real ndarray
412-
Similarity transform relating `a` and `amodal`
413-
blksizes : (N,) int ndarray
414-
Array of Schur block sizes
409+
amodal : (M, M) real ndarray
410+
Block-diagonal Schur decomposition of `a`
411+
tmodal : (M, M) real ndarray
412+
Similarity transform relating `a` and `amodal`
413+
blksizes : (N,) int ndarray
414+
Array of Schur block sizes
415415
416416
Notes
417417
-----

‎control/config.py‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -83,6 +83,13 @@ def set_defaults(module, **keywords):
8383
The set_defaults() function can be used to modify multiple parameter
8484
values for a module at the same time, using keyword arguments.
8585
86+
Parameters
87+
----------
88+
module : str
89+
Name of the module for which the defaults are being given.
90+
**keywords : keyword arguments
91+
Parameter value assignments.
92+
8693
Examples
8794
--------
8895
>>> ct.defaults['freqplot.number_of_samples']
@@ -355,7 +362,7 @@ def _process_legacy_keyword(kwargs, oldkey, newkey, newval):
355362
if kwargs.get(oldkey) is not None:
356363
warnings.warn(
357364
f"keyword '{oldkey}' is deprecated; use '{newkey}'",
358-
DeprecationWarning)
365+
FutureWarning)
359366
if newval is not None:
360367
raise ControlArgument(
361368
f"duplicate keywords '{oldkey}' and '{newkey}'")

‎control/ctrlplot.py‎

Lines changed: 12 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -207,11 +207,12 @@ def suptitle(
207207
title, fig=None, frame='axes', **kwargs):
208208
"""Add a centered title to a figure.
209209
210-
This function is deprecated. Use :func:`ControlPlot.set_plot_title`.
210+
.. deprecated:: 0.10.1
211+
Use :func:`ControlPlot.set_plot_title`.
211212
212213
"""
213214
warnings.warn(
214-
"suptitle is deprecated; use cplt.set_plot_title", FutureWarning)
215+
"suptitle() is deprecated; use cplt.set_plot_title()", FutureWarning)
215216
_update_plot_title(
216217
title, fig=fig, frame=frame, use_existing=False, **kwargs)
217218

@@ -220,6 +221,10 @@ def suptitle(
220221
def get_plot_axes(line_array):
221222
"""Get a list of axes from an array of lines.
222223
224+
.. deprecated:: 0.10.1
225+
This function will be removed in a future version of python-control.
226+
Use `cplt.axes` to obtain axes for an instance of :class:`ControlPlot`.
227+
223228
This function can be used to return the set of axes corresponding
224229
to the line array that is returned by `time_response_plot`. This
225230
is useful for generating an axes array that can be passed to
@@ -242,7 +247,8 @@ def get_plot_axes(line_array):
242247
Only the first element of each array entry is used to determine the axes.
243248
244249
"""
245-
warnings.warn("get_plot_axes is deprecated; use cplt.axes", FutureWarning)
250+
warnings.warn(
251+
"get_plot_axes() is deprecated; use cplt.axes()", FutureWarning)
246252
_get_axes = np.vectorize(lambda lines: lines[0].axes)
247253
if isinstance(line_array, ControlPlot):
248254
return _get_axes(line_array.lines)
@@ -268,6 +274,9 @@ def pole_zero_subplots(
268274
Scaling to apply to the subplots.
269275
fig : :class:`matplotlib.figure.Figure`
270276
Figure to use for creating subplots.
277+
rcParams : dict
278+
Override the default parameters used for generating plots.
279+
Default is set up config.default['ctrlplot.rcParams'].
271280
272281
Returns
273282
-------

‎control/ctrlutil.py‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -88,7 +88,8 @@ def unwrap(angle, period=2*math.pi):
8888
def issys(obj):
8989
"""Deprecated function to check if an object is an LTI system.
9090
91-
Use isinstance(obj, ct.LTI)
91+
.. deprecated:: 0.10.0
92+
Use isinstance(obj, ct.LTI)
9293
9394
"""
9495
warnings.warn("issys() is deprecated; use isinstance(obj, ct.LTI)",

‎control/delay.py‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -57,10 +57,10 @@ def pade(T, n=1, numdeg=None):
5757
time delay
5858
n : positive integer
5959
degree of denominator of approximation
60-
numdeg: integer, or None (the default)
61-
If None, numerator degree equals denominator degree
62-
If >= 0, specifies degree of numerator
63-
If < 0, numerator degree is n+numdeg
60+
numdeg : integer, or None (the default)
61+
If numdeg is `None`, numerator degree equals denominator degree.
62+
If numdeg >= 0, specifies degree of numerator.
63+
If numdeg < 0, numerator degree is n+numdeg.
6464
6565
Returns
6666
-------

‎control/descfcn.py‎

Lines changed: 16 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -102,6 +102,10 @@ def describing_function(
102102
A : array_like
103103
The amplitude(s) at which the describing function should be calculated.
104104
105+
num_points : int, optional
106+
Number of points to use in computing describing function (default =
107+
100).
108+
105109
zero_check : bool, optional
106110
If `True` (default) then `A` is zero, the function will be evaluated
107111
and checked to make sure it is zero. If not, a `TypeError` exception
@@ -271,7 +275,7 @@ def __len__(self):
271275
# Compute the describing function response + intersections
272276
def describing_function_response(
273277
H, F, A, omega=None, refine=True, warn_nyquist=None,
274-
plot=False, check_kwargs=True, **kwargs):
278+
_check_kwargs=True, **kwargs):
275279
"""Compute the describing function response of a system.
276280
277281
This function uses describing function analysis to analyze a closed
@@ -294,6 +298,10 @@ def describing_function_response(
294298
Set to True to turn on warnings generated by `nyquist_plot` or False
295299
to turn off warnings. If not set (or set to None), warnings are
296300
turned off if omega is specified, otherwise they are turned on.
301+
refine : bool, optional
302+
If `True`, :func:`scipy.optimize.minimize` to refine the estimate
303+
of the intersection of the frequency response and the describing
304+
function.
297305
298306
Returns
299307
-------
@@ -328,7 +336,7 @@ def describing_function_response(
328336
# Start by drawing a Nyquist curve
329337
response = nyquist_response(
330338
H, omega, warn_encirclements=warn_nyquist, warn_nyquist=warn_nyquist,
331-
check_kwargs=check_kwargs, **kwargs)
339+
_check_kwargs=_check_kwargs, **kwargs)
332340
H_omega, H_vals = response.contour.imag, H(response.contour)
333341

334342
# Compute the describing function
@@ -420,6 +428,8 @@ def describing_function_plot(
420428
If True (default), refine the location of the intersection of the
421429
Nyquist curve for the linear system and the describing function to
422430
determine the intersection point
431+
label : str or array_like of str, optional
432+
If present, replace automatically generated label with the given label.
423433
point_label : str, optional
424434
Formatting string used to label intersection points on the Nyquist
425435
plot. Defaults to "%5.2g @ %-5.2g". Set to `None` to omit labels.
@@ -429,6 +439,10 @@ def describing_function_plot(
429439
Otherwise, a new figure is created.
430440
title : str, optional
431441
Set the title of the plot. Defaults to plot type and system name(s).
442+
warn_nyquist : bool, optional
443+
Set to True to turn on warnings generated by `nyquist_plot` or False
444+
to turn off warnings. If not set (or set to None), warnings are
445+
turned off if omega is specified, otherwise they are turned on.
432446
**kwargs : :func:`matplotlib.pyplot.plot` keyword properties, optional
433447
Additional keywords passed to `matplotlib` to specify line properties
434448
for Nyquist curve.

‎control/dtime.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -82,7 +82,7 @@ def sample_system(sysc, Ts, method='zoh', alpha=None, prewarp_frequency=None,
8282
Other Parameters
8383
----------------
8484
inputs : int, list of str or None, optional
85-
Description of the system inputs. If not specified, the origional
85+
Description of the system inputs. If not specified, the original
8686
system inputs are used. See :class:`InputOutputSystem` for more
8787
information.
8888
outputs : int, list of str or None, optional

‎control/frdata.py‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -597,12 +597,13 @@ def freqresp(self, omega):
597597
Method has been given the more pythonic name
598598
:meth:`FrequencyResponseData.frequency_response`. Or use
599599
:func:`freqresp` in the MATLAB compatibility module.
600+
600601
"""
601602
warn("FrequencyResponseData.freqresp(omega) will be removed in a "
602603
"future release of python-control; use "
603604
"FrequencyResponseData.frequency_response(omega), or "
604605
"freqresp(sys, omega) in the MATLAB compatibility module "
605-
"instead", DeprecationWarning)
606+
"instead", FutureWarning)
606607
return self.frequency_response(omega)
607608

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

0 commit comments

Comments
 (0)