Skip to content

Documentation updates and testing #1038

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
murrayrm merged 15 commits into from
Aug 13, 2024
Merged

Documentation updates and testing #1038

Show file tree
Hide file tree
Changes from 10 commits
Commits
Show all changes
15 commits
Select commit Hold shift + click to select a range
e01c580
small updates to comments + remove obsolete Pending
murrayrm May 11, 2024
f078b3e
docstring updates for nyquist_plot
murrayrm May 19, 2024
4838bbf
add unit test for testing documentation
murrayrm Jul 29, 2024
b767e52
change check_kwargs to _check_kwargs and disable docstring check
murrayrm Jul 29, 2024
3697afa
improve docstrings unit test for deprecation, seq args; skip duplicates
murrayrm Aug 3, 2024
a59184c
add hashes for positional arguments
murrayrm Aug 3, 2024
4d9f57d
update intersphinx URL for SciPy
murrayrm Aug 3, 2024
7f48535
update docstrings to fix missing arguments, incorrect format
murrayrm Aug 3, 2024
8fcf0b7
make deprecration warnings consistent (as FutureWarning)
murrayrm Aug 4, 2024
4ef9dd6
update docstring text for new functions
murrayrm Aug 9, 2024
806e5b3
add test for multiple copies of argument documentation
murrayrm Aug 13, 2024
122c405
update docstring position arg hash to include source + docstring
murrayrm Aug 13, 2024
fb2086c
address @slivingston review comments
murrayrm Aug 13, 2024
a201504
filter known FutureWarning's from unit tests
murrayrm Aug 13, 2024
c3ea6dc
add back missing image examples/vehicle-steering.png
murrayrm Aug 13, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
63 changes: 0 additions & 63 deletions Pending
View file
Open in desktop

This file was deleted.

16 changes: 8 additions & 8 deletions control/bdalg.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -73,7 +73,7 @@ def series(sys1, *sysn, **kwargs):

Parameters
----------
sys1, sys2, ..., sysn: scalar, array, or :class:`InputOutputSystem`
sys1, sys2, ..., sysn : scalar, array, or :class:`InputOutputSystem`
I/O systems to combine.

Returns
Expand Down Expand Up @@ -145,7 +145,7 @@ def parallel(sys1, *sysn, **kwargs):

Parameters
----------
sys1, sys2, ..., sysn: scalar, array, or :class:`InputOutputSystem`
sys1, sys2, ..., sysn : scalar, array, or :class:`InputOutputSystem`
I/O systems to combine.

Returns
Expand Down Expand Up @@ -213,7 +213,7 @@ def negate(sys, **kwargs):

Parameters
----------
sys: scalar, array, or :class:`InputOutputSystem`
sys : scalar, array, or :class:`InputOutputSystem`
I/O systems to negate.

Returns
Expand Down Expand Up @@ -265,9 +265,9 @@ def feedback(sys1, sys2=1, sign=-1, **kwargs):

Parameters
----------
sys1, sys2: scalar, array, or :class:`InputOutputSystem`
sys1, sys2 : scalar, array, or :class:`InputOutputSystem`
I/O systems to combine.
sign: scalar
sign : scalar
The sign of feedback. `sign` = -1 indicates negative feedback, and
`sign` = 1 indicates positive feedback. `sign` is an optional
argument; it assumes a value of -1 if not specified.
Expand Down Expand Up @@ -412,8 +412,8 @@ def connect(sys, Q, inputv, outputv):
"""Index-based interconnection of an LTI system.

.. deprecated:: 0.10.0
`connect` will be removed in a future version of python-control in
favor of `interconnect`, which works with named signals.
`connect` will be removed in a future version of python-control.
Use :func:`interconnect` instead, which works with named signals.

The system `sys` is a system typically constructed with `append`, with
multiple inputs and outputs. The inputs and outputs are connected
Expand Down Expand Up @@ -465,7 +465,7 @@ def connect(sys, Q, inputv, outputv):

"""
# TODO: maintain `connect` for use in MATLAB submodule (?)
warn("`connect` is deprecated; use `interconnect`", DeprecationWarning)
warn("connect() is deprecated; use interconnect()", FutureWarning)

inputv, outputv, Q = \
np.atleast_1d(inputv), np.atleast_1d(outputv), np.atleast_1d(Q)
Expand Down
26 changes: 13 additions & 13 deletions control/canonical.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -204,7 +204,7 @@ def similarity_transform(xsys, T, timescale=1, inverse=False):
The matrix `T` defines the new set of coordinates z = T x.
timescale : float, optional
If present, also rescale the time unit to tau = timescale * t
inverse: boolean, optional
inverse : bool, optional
If True (default), transform so z = T x. If False, transform
so x = T z.

Expand Down Expand Up @@ -397,21 +397,21 @@ def bdschur(a, condmax=None, sort=None):

Parameters
----------
a : (M, M) array_like
Real matrix to decompose
condmax : None or float, optional
If None (default), use 1/sqrt(eps), which is approximately 1e8
sort : {None, 'continuous', 'discrete'}
Block sorting; see below.
a : (M, M) array_like
Real matrix to decompose
condmax : None or float, optional
If None (default), use 1/sqrt(eps), which is approximately 1e8
sort : {None, 'continuous', 'discrete'}
Block sorting; see below.

Returns
-------
amodal : (M, M) real ndarray
Block-diagonal Schur decomposition of `a`
tmodal : (M, M) real ndarray
Similarity transform relating `a` and `amodal`
blksizes : (N,) int ndarray
Array of Schur block sizes
amodal : (M, M) real ndarray
Block-diagonal Schur decomposition of `a`
tmodal : (M, M) real ndarray
Similarity transform relating `a` and `amodal`
blksizes : (N,) int ndarray
Array of Schur block sizes

Notes
-----
Expand Down
9 changes: 8 additions & 1 deletion control/config.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -83,6 +83,13 @@ def set_defaults(module, **keywords):
The set_defaults() function can be used to modify multiple parameter
values for a module at the same time, using keyword arguments.

Parameters
----------
module : str
Name of the module for which the defaults are being given.
**keywords : keyword arguments
Parameter value assignments.

Examples
--------
>>> ct.defaults['freqplot.number_of_samples']
Expand Down Expand Up @@ -355,7 +362,7 @@ def _process_legacy_keyword(kwargs, oldkey, newkey, newval):
if kwargs.get(oldkey) is not None:
warnings.warn(
f"keyword '{oldkey}' is deprecated; use '{newkey}'",
DeprecationWarning)
FutureWarning)
if newval is not None:
raise ControlArgument(
f"duplicate keywords '{oldkey}' and '{newkey}'")
Expand Down
15 changes: 12 additions & 3 deletions control/ctrlplot.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -207,11 +207,12 @@ def suptitle(
title, fig=None, frame='axes', **kwargs):
"""Add a centered title to a figure.

This function is deprecated. Use :func:`ControlPlot.set_plot_title`.
.. deprecated:: 0.10.1
Use :func:`ControlPlot.set_plot_title`.

"""
warnings.warn(
"suptitle is deprecated; use cplt.set_plot_title", FutureWarning)
"suptitle() is deprecated; use cplt.set_plot_title()", FutureWarning)
_update_plot_title(
title, fig=fig, frame=frame, use_existing=False, **kwargs)

Expand All @@ -220,6 +221,10 @@ def suptitle(
def get_plot_axes(line_array):
"""Get a list of axes from an array of lines.

.. deprecated:: 0.10.1
This function will be removed in a future version of python-control.
Use `cplt.axes` to obtain axes for a control plot `cplt`.

@slivingston slivingston Aug 12, 2024

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Use `cplt.axes` to obtain axes for a control plot `cplt`.
Use `cplt.axes` to obtain axes for an instance of :class:`ControlPlot`.

Even though get_plot_axes() is defined in the same module (ctrlplot) as ControlPlot, it is available at the top of the package as control.get_plot_axes(), so a user may not realize that cplt abbreviates the new class ControlPlot. E.g., observe how get_plot_axes() is shown at https://python-control.readthedocs.io/en/0.10.0/generated/control.get_plot_axes.html.

Therefore, I recommend to be explicit here when referring to the class ControlPlot.


This function can be used to return the set of axes corresponding
to the line array that is returned by `time_response_plot`. This
is useful for generating an axes array that can be passed to
Expand All @@ -242,7 +247,8 @@ def get_plot_axes(line_array):
Only the first element of each array entry is used to determine the axes.

"""
warnings.warn("get_plot_axes is deprecated; use cplt.axes", FutureWarning)
warnings.warn(
"get_plot_axes() is deprecated; use cplt.axes()", FutureWarning)
_get_axes = np.vectorize(lambda lines: lines[0].axes)
if isinstance(line_array, ControlPlot):
return _get_axes(line_array.lines)
Expand All @@ -268,6 +274,9 @@ def pole_zero_subplots(
Scaling to apply to the subplots.
fig : :class:`matplotlib.figure.Figure`
Figure to use for creating subplots.
rcParams : dict
Override the default parameters used for generating plots.
Default is set up config.default['freqplot.rcParams'].

@slivingston slivingston Aug 12, 2024

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Default is set up config.default['freqplot.rcParams'].
Default is set up config.default['ctrlplot.rcParams'].


Returns
-------
Expand Down
3 changes: 2 additions & 1 deletion control/ctrlutil.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -88,7 +88,8 @@ def unwrap(angle, period=2*math.pi):
def issys(obj):
"""Deprecated function to check if an object is an LTI system.

Use isinstance(obj, ct.LTI)
.. deprecated:: 0.10.0
Use isinstance(obj, ct.LTI)

"""
warnings.warn("issys() is deprecated; use isinstance(obj, ct.LTI)",
Expand Down
8 changes: 4 additions & 4 deletions control/delay.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,10 +57,10 @@ def pade(T, n=1, numdeg=None):
time delay
n : positive integer
degree of denominator of approximation
numdeg: integer, or None (the default)
If None, numerator degree equals denominator degree
If >= 0, specifies degree of numerator
If < 0, numerator degree is n+numdeg
numdeg : integer, or None (the default)
If numdeg is `None`, numerator degree equals denominator degree.
If numdeg >= 0, specifies degree of numerator.
If numdeg < 0, numerator degree is n+numdeg.

Returns
-------
Expand Down
18 changes: 16 additions & 2 deletions control/descfcn.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -102,6 +102,10 @@ def describing_function(
A : array_like
The amplitude(s) at which the describing function should be calculated.

num_points : int, optional
Number of points to use in computing describing function (default =
100).

zero_check : bool, optional
If `True` (default) then `A` is zero, the function will be evaluated
and checked to make sure it is zero. If not, a `TypeError` exception
Expand Down Expand Up @@ -271,7 +275,7 @@ def __len__(self):
# Compute the describing function response + intersections
def describing_function_response(
H, F, A, omega=None, refine=True, warn_nyquist=None,
plot=False, check_kwargs=True, **kwargs):
_check_kwargs=True, **kwargs):
"""Compute the describing function response of a system.

This function uses describing function analysis to analyze a closed
Expand All @@ -294,6 +298,10 @@ def describing_function_response(
Set to True to turn on warnings generated by `nyquist_plot` or False
to turn off warnings. If not set (or set to None), warnings are
turned off if omega is specified, otherwise they are turned on.
refine : bool, optional
If `True`, :func:`scipy.optimize.minimize` to refine the estimate
of the intersection of the frequency response and the describing
function.

Returns
-------
Expand Down Expand Up @@ -328,7 +336,7 @@ def describing_function_response(
# Start by drawing a Nyquist curve
response = nyquist_response(
H, omega, warn_encirclements=warn_nyquist, warn_nyquist=warn_nyquist,
check_kwargs=check_kwargs, **kwargs)
_check_kwargs=_check_kwargs, **kwargs)
H_omega, H_vals = response.contour.imag, H(response.contour)

# Compute the describing function
Expand Down Expand Up @@ -420,6 +428,8 @@ def describing_function_plot(
If True (default), refine the location of the intersection of the
Nyquist curve for the linear system and the describing function to
determine the intersection point
label : str or array_like of str, optional
If present, replace automatically generated label with the given label.
point_label : str, optional
Formatting string used to label intersection points on the Nyquist
plot. Defaults to "%5.2g @ %-5.2g". Set to `None` to omit labels.
Expand All @@ -429,6 +439,10 @@ def describing_function_plot(
Otherwise, a new figure is created.
title : str, optional
Set the title of the plot. Defaults to plot type and system name(s).
warn_nyquist : bool, optional
Set to True to turn on warnings generated by `nyquist_plot` or False
to turn off warnings. If not set (or set to None), warnings are
turned off if omega is specified, otherwise they are turned on.
**kwargs : :func:`matplotlib.pyplot.plot` keyword properties, optional
Additional keywords passed to `matplotlib` to specify line properties
for Nyquist curve.
Expand Down
3 changes: 2 additions & 1 deletion control/frdata.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -597,12 +597,13 @@ def freqresp(self, omega):
Method has been given the more pythonic name
:meth:`FrequencyResponseData.frequency_response`. Or use
:func:`freqresp` in the MATLAB compatibility module.

"""
warn("FrequencyResponseData.freqresp(omega) will be removed in a "
"future release of python-control; use "
"FrequencyResponseData.frequency_response(omega), or "
"freqresp(sys, omega) in the MATLAB compatibility module "
"instead", DeprecationWarning)
"instead", FutureWarning)
return self.frequency_response(omega)

def feedback(self, other=1, sign=-1):
Expand Down
Loading