Skip to content

Commit 8f6bba4

Browse files
murrayrmmurrayrm
committed
update docstrings to fix missing arguments, incorrect format
1 parent 6c492a7 commit 8f6bba4

27 files changed

Lines changed: 394 additions & 203 deletions

‎control/bdalg.py‎

Lines changed: 5 additions & 5 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.

‎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: 7 additions & 0 deletions
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']

‎control/ctrlplot.py‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -207,7 +207,8 @@ 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(
@@ -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 a control plot `cplt`.
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
@@ -268,6 +273,9 @@ def pole_zero_subplots(
268273
Scaling to apply to the subplots.
269274
fig : :class:`matplotlib.figure.Figure`
270275
Figure to use for creating subplots.
276+
rcParams : dict
277+
Override the default parameters used for generating plots.
278+
Default is set up config.default['freqplot.rcParams'].
271279
272280
Returns
273281
-------

‎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: 15 additions & 1 deletion
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
-------
@@ -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/freqplot.py‎

Lines changed: 33 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -147,6 +147,8 @@ def bode_plot(
147147
figure with the correct number and shape of axes, a new figure is
148148
created. The shape of the array must match the shape of the
149149
plotted data.
150+
freq_label, magnitude_label, phase_label : str, optional
151+
Labels to use for the frequency, magnitude, and phase axes.
150152
grid : bool, optional
151153
If True, plot grid lines on gain and phase plots. Default is set by
152154
`config.defaults['freqplot.grid']`.
@@ -179,19 +181,34 @@ def bode_plot(
179181
Number of samples to use for the frequeny range. Defaults to
180182
config.defaults['freqplot.number_of_samples']. Ignored if data is
181183
not a list of systems.
184+
overlay_inputs, overlay_outputs : bool, optional
185+
If set to True, combine input and/or output signals onto a single
186+
plot and use line colors, labels, and a legend to distinguish them.
182187
plot : bool, optional
183188
(legacy) If given, `bode_plot` returns the legacy return values
184189
of magnitude, phase, and frequency. If False, just return the
185190
values with no plot.
191+
plot_magnitude, plot_phase : bool, optional
192+
If set to `False`, don't plot the magnitude or phase, respectively.
186193
rcParams : dict
187194
Override the default parameters used for generating plots.
188195
Default is set by config.default['ctrlplot.rcParams'].
196+
share_frequency, share_magnitude, share_phase : str or bool, optional
197+
Determine whether and how axis limits are shared between the
198+
indicated variables. Can be set set to 'row' to share across all
199+
subplots in a row, 'col' to set across all subplots in a column, or
200+
`False` to allow independent limits.
189201
show_legend : bool, optional
190202
Force legend to be shown if ``True`` or hidden if ``False``. If
191203
``None``, then show legend when there is more than one line on an
192204
axis or ``legend_loc`` or ``legend_map`` has been specified.
193205
title : str, optional
194206
Set the title of the plot. Defaults to plot type and system name(s).
207+
title_frame : str, optional
208+
Set the frame of reference used to center the plot title. If set to
209+
'axes' (default), the horizontal position of the title will
210+
centered relative to the axes. If set to `figure`, it will be
211+
centered with respect to the figure (faster execution).
195212
wrap_phase : bool or float
196213
If wrap_phase is `False` (default), then the phase will be unwrapped
197214
so that it is continuously increasing or decreasing. If wrap_phase is
@@ -1137,7 +1154,7 @@ def plot(self, *args, **kwargs):
11371154

11381155

11391156
def nyquist_response(
1140-
sysdata, omega=None, plot=None, omega_limits=None, omega_num=None,
1157+
sysdata, omega=None, omega_limits=None, omega_num=None,
11411158
return_contour=False, warn_encirclements=True, warn_nyquist=True,
11421159
_check_kwargs=True, **kwargs):
11431160
"""Nyquist response for a system.
@@ -1215,8 +1232,7 @@ def nyquist_response(
12151232
right of stable poles and the left of unstable poles. If a pole is
12161233
exactly on the imaginary axis, the `indent_direction` parameter can be
12171234
used to set the direction of indentation. Setting `indent_direction`
1218-
to `none` will turn off indentation. If `return_contour` is True, the
1219-
exact contour used for evaluation is returned.
1235+
to `none` will turn off indentation.
12201236
12211237
3. For those portions of the Nyquist plot in which the contour is
12221238
indented to avoid poles, resuling in a scaling of the Nyquist plot,
@@ -1617,7 +1633,7 @@ def nyquist_plot(
16171633
determined by config.defaults['nyquist.mirror_style'].
16181634
rcParams : dict
16191635
Override the default parameters used for generating plots.
1620-
Default is set by config.default['freqplot.rcParams'].
1636+
Default is set by config.default['ctrlplot.rcParams'].
16211637
return_contour : bool, optional
16221638
(legacy) If 'True', return the encirclement count and Nyquist
16231639
contour used to generate the Nyquist plot.
@@ -1634,6 +1650,11 @@ def nyquist_plot(
16341650
4 and can be set using config.defaults['nyquist.start_marker_size'].
16351651
title : str, optional
16361652
Set the title of the plot. Defaults to plot type and system name(s).
1653+
title_frame : str, optional
1654+
Set the frame of reference used to center the plot title. If set to
1655+
'axes' (default), the horizontal position of the title will
1656+
centered relative to the axes. If set to `figure`, it will be
1657+
centered with respect to the figure (faster execution).
16371658
warn_nyquist : bool, optional
16381659
If set to 'False', turn off warnings about frequencies above Nyquist.
16391660
warn_encirclements : bool, optional
@@ -2200,6 +2221,7 @@ def gangof4_plot(
22002221
*args, omega=omega, omega_limits=omega_limits,
22012222
omega_num=omega_num, Hz=Hz).plot(**kwargs)
22022223

2224+
22032225
#
22042226
# Singular values plot
22052227
#
@@ -2333,6 +2355,8 @@ def singular_values_plot(
23332355
The matplotlib axes to draw the figure on. If not specified and
23342356
the current figure has a single axes, that axes is used.
23352357
Otherwise, a new figure is created.
2358+
color : matplotlib color spec
2359+
Color to use for singular values (or None for matplotlib default).
23362360
grid : bool
23372361
If True, plot grid lines on gain and phase plots. Default is set by
23382362
`config.defaults['freqplot.grid']`.
@@ -2364,6 +2388,11 @@ def singular_values_plot(
23642388
axis or ``legend_loc`` or ``legend_map`` has been specified.
23652389
title : str, optional
23662390
Set the title of the plot. Defaults to plot type and system name(s).
2391+
title_frame : str, optional
2392+
Set the frame of reference used to center the plot title. If set to
2393+
'axes' (default), the horizontal position of the title will
2394+
centered relative to the axes. If set to `figure`, it will be
2395+
centered with respect to the figure (faster execution).
23672396
23682397
See Also
23692398
--------

0 commit comments

Comments
 (0)