Skip to content

Commit 7f48535

Browse files
murrayrmmurrayrm
committed
update docstrings to fix missing arguments, incorrect format
1 parent 4d9f57d commit 7f48535

27 files changed

Lines changed: 395 additions & 205 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: 34 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -147,8 +147,9 @@ 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: str, optional
151-
Frequency label (defaults to "rad/sec" or "Hertz")
150+
freq_label, magnitude_label, phase_label : str, optional
151+
Labels to use for the frequency, magnitude, and phase axes.
152+
Defaults are set by `config.defaults['freqplot.<keyword>']`.
152153
grid : bool, optional
153154
If True, plot grid lines on gain and phase plots. Default is set by
154155
`config.defaults['freqplot.grid']`.
@@ -183,21 +184,36 @@ def bode_plot(
183184
Number of samples to use for the frequeny range. Defaults to
184185
config.defaults['freqplot.number_of_samples']. Ignored if data is
185186
not a list of systems.
187+
overlay_inputs, overlay_outputs : bool, optional
188+
If set to True, combine input and/or output signals onto a single
189+
plot and use line colors, labels, and a legend to distinguish them.
186190
phase_label : str, optional
187191
Label to use for phase axis. Defaults to "Phase [rad]".
188192
plot : bool, optional
189193
(legacy) If given, `bode_plot` returns the legacy return values
190194
of magnitude, phase, and frequency. If False, just return the
191195
values with no plot.
196+
plot_magnitude, plot_phase : bool, optional
197+
If set to `False`, don't plot the magnitude or phase, respectively.
192198
rcParams : dict
193199
Override the default parameters used for generating plots.
194200
Default is set by config.default['ctrlplot.rcParams'].
201+
share_frequency, share_magnitude, share_phase : str or bool, optional
202+
Determine whether and how axis limits are shared between the
203+
indicated variables. Can be set set to 'row' to share across all
204+
subplots in a row, 'col' to set across all subplots in a column, or
205+
`False` to allow independent limits.
195206
show_legend : bool, optional
196207
Force legend to be shown if ``True`` or hidden if ``False``. If
197208
``None``, then show legend when there is more than one line on an
198209
axis or ``legend_loc`` or ``legend_map`` has been specified.
199210
title : str, optional
200211
Set the title of the plot. Defaults to plot type and system name(s).
212+
title_frame : str, optional
213+
Set the frame of reference used to center the plot title. If set to
214+
'axes' (default), the horizontal position of the title will
215+
centered relative to the axes. If set to `figure`, it will be
216+
centered with respect to the figure (faster execution).
201217
wrap_phase : bool or float
202218
If wrap_phase is `False` (default), then the phase will be unwrapped
203219
so that it is continuously increasing or decreasing. If wrap_phase is
@@ -1143,7 +1159,7 @@ def plot(self, *args, **kwargs):
11431159

11441160

11451161
def nyquist_response(
1146-
sysdata, omega=None, plot=None, omega_limits=None, omega_num=None,
1162+
sysdata, omega=None, omega_limits=None, omega_num=None,
11471163
return_contour=False, warn_encirclements=True, warn_nyquist=True,
11481164
_check_kwargs=True, **kwargs):
11491165
"""Nyquist response for a system.
@@ -1221,8 +1237,7 @@ def nyquist_response(
12211237
right of stable poles and the left of unstable poles. If a pole is
12221238
exactly on the imaginary axis, the `indent_direction` parameter can be
12231239
used to set the direction of indentation. Setting `indent_direction`
1224-
to `none` will turn off indentation. If `return_contour` is True, the
1225-
exact contour used for evaluation is returned.
1240+
to `none` will turn off indentation.
12261241
12271242
3. For those portions of the Nyquist plot in which the contour is
12281243
indented to avoid poles, resuling in a scaling of the Nyquist plot,
@@ -1623,7 +1638,7 @@ def nyquist_plot(
16231638
determined by config.defaults['nyquist.mirror_style'].
16241639
rcParams : dict
16251640
Override the default parameters used for generating plots.
1626-
Default is set by config.default['freqplot.rcParams'].
1641+
Default is set by config.default['ctrlplot.rcParams'].
16271642
return_contour : bool, optional
16281643
(legacy) If 'True', return the encirclement count and Nyquist
16291644
contour used to generate the Nyquist plot.
@@ -1640,6 +1655,11 @@ def nyquist_plot(
16401655
4 and can be set using config.defaults['nyquist.start_marker_size'].
16411656
title : str, optional
16421657
Set the title of the plot. Defaults to plot type and system name(s).
1658+
title_frame : str, optional
1659+
Set the frame of reference used to center the plot title. If set to
1660+
'axes' (default), the horizontal position of the title will
1661+
centered relative to the axes. If set to `figure`, it will be
1662+
centered with respect to the figure (faster execution).
16431663
warn_nyquist : bool, optional
16441664
If set to 'False', turn off warnings about frequencies above Nyquist.
16451665
warn_encirclements : bool, optional
@@ -2206,6 +2226,7 @@ def gangof4_plot(
22062226
*args, omega=omega, omega_limits=omega_limits,
22072227
omega_num=omega_num, Hz=Hz).plot(**kwargs)
22082228

2229+
22092230
#
22102231
# Singular values plot
22112232
#
@@ -2339,6 +2360,8 @@ def singular_values_plot(
23392360
The matplotlib axes to draw the figure on. If not specified and
23402361
the current figure has a single axes, that axes is used.
23412362
Otherwise, a new figure is created.
2363+
color : matplotlib color spec
2364+
Color to use for singular values (or None for matplotlib default).
23422365
grid : bool
23432366
If True, plot grid lines on gain and phase plots. Default is set by
23442367
`config.defaults['freqplot.grid']`.
@@ -2370,6 +2393,11 @@ def singular_values_plot(
23702393
axis or ``legend_loc`` or ``legend_map`` has been specified.
23712394
title : str, optional
23722395
Set the title of the plot. Defaults to plot type and system name(s).
2396+
title_frame : str, optional
2397+
Set the frame of reference used to center the plot title. If set to
2398+
'axes' (default), the horizontal position of the title will
2399+
centered relative to the axes. If set to `figure`, it will be
2400+
centered with respect to the figure (faster execution).
23732401
23742402
See Also
23752403
--------

0 commit comments

Comments
 (0)