Skip to content

Commit e4fd04f

Browse files
murrayrmmurrayrm
committed
update linear.rst and associated doc files and function docstrings
1 parent 6d6cf25 commit e4fd04f

17 files changed

Lines changed: 284 additions & 120 deletions

‎control/lti.py‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -133,9 +133,8 @@ def frequency_response(self, omega=None, squeeze=None):
133133
outputs=self.output_labels, plot_type='bode')
134134

135135
def dcgain(self):
136-
"""Return the zero-frequency gain"""
137-
raise NotImplementedError("dcgain not implemented for %s objects" %
138-
str(self.__class__))
136+
"""Return the zero-frequency (DC) gain."""
137+
return NotImplemented
139138

140139
def _dcgain(self, warn_infinite):
141140
zeroresp = self(0 if self.isctime() else 1,

‎control/margins.py‎

Lines changed: 8 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -271,13 +271,14 @@ def stability_margins(sysdata, returnall=False, epsw=0.0, method='best'):
271271
and not returned as margin.
272272
method : string, optional
273273
Method to use (default is 'best'):
274-
'poly': use polynomial method if passed a :class:`LTI` system.
275-
'frd': calculate crossover frequencies using numerical interpolation
276-
of a :class:`FrequencyResponseData` representation of the system if
277-
passed a :class:`LTI` system.
278-
'best': use the 'poly' method if possible, reverting to 'frd' if it is
279-
detected that numerical inaccuracy is likey to arise in the 'poly'
280-
method for for discrete-time systems.
274+
275+
* 'poly': use polynomial method if passed a :class:`LTI` system.
276+
* 'frd': calculate crossover frequencies using numerical
277+
interpolation of a :class:`FrequencyResponseData` representation
278+
of the system if passed a :class:`LTI` system.
279+
* 'best': use the 'poly' method if possible, reverting to 'frd' if
280+
it is detected that numerical inaccuracy is likey to arise in the
281+
'poly' method for for discrete-time systems.
281282
282283
Returns
283284
-------

‎control/robust.py‎

Lines changed: 4 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -2,42 +2,10 @@
22
#
33
# Author: Steve Brunton, Kevin Chen, Lauren Padilla
44
# Date: 24 Dec 2010
5-
#
6-
# This file contains routines for obtaining reduced order models
7-
#
8-
# Copyright (c) 2010 by California Institute of Technology
9-
# All rights reserved.
10-
#
11-
# Redistribution and use in source and binary forms, with or without
12-
# modification, are permitted provided that the following conditions
13-
# are met:
14-
#
15-
# 1. Redistributions of source code must retain the above copyright
16-
# notice, this list of conditions and the following disclaimer.
17-
#
18-
# 2. Redistributions in binary form must reproduce the above copyright
19-
# notice, this list of conditions and the following disclaimer in the
20-
# documentation and/or other materials provided with the distribution.
21-
#
22-
# 3. Neither the name of the California Institute of Technology nor
23-
# the names of its contributors may be used to endorse or promote
24-
# products derived from this software without specific prior
25-
# written permission.
26-
#
27-
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
28-
# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
29-
# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
30-
# FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL CALTECH
31-
# OR THE CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
32-
# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
33-
# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
34-
# USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
35-
# ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
36-
# OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
37-
# OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
38-
# SUCH DAMAGE.
39-
#
40-
# $Id$
5+
6+
"""
7+
This file contains routines for obtaining reduced order models.
8+
"""
419

4210
import warnings
4311

‎control/statesp.py‎

Lines changed: 1 addition & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1350,7 +1350,7 @@ def sample(self, Ts, method='zoh', alpha=None, prewarp_frequency=None,
13501350
return StateSpace(sysd, **kwargs)
13511351

13521352
def dcgain(self, warn_infinite=False):
1353-
"""Return the zero-frequency gain.
1353+
"""Return the zero-frequency ("DC") gain.
13541354
13551355
The zero-frequency gain of a continuous-time state-space
13561356
system is given by:
@@ -1931,9 +1931,6 @@ def ssdata(sys):
19311931
def linfnorm(sys, tol=1e-10):
19321932
"""L-infinity norm of a linear system.
19331933
1934-
.. deprecated:: 0.10.2
1935-
This functionality is now available in :func:`sysnorm`.
1936-
19371934
Parameters
19381935
----------
19391936
sys : LTI (StateSpace or TransferFunction)
@@ -1957,8 +1954,6 @@ def linfnorm(sys, tol=1e-10):
19571954
--------
19581955
slycot.ab13dd : the Slycot routine linfnorm that does the calculation
19591956
"""
1960-
warn("linfnorm() is deprecated; use sysnorm(sys, p='inf')", FutureWarning)
1961-
19621957
if ab13dd is None:
19631958
raise ControlSlycot("Can't find slycot module 'ab13dd'")
19641959

‎control/sysnorm.py‎

Lines changed: 14 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@
1818

1919
import control as ct
2020

21-
__all__ = ['norm']
21+
__all__ = ['system_norm', 'norm']
2222

2323
#------------------------------------------------------------------------------
2424

@@ -83,24 +83,26 @@ def _h2norm_slycot(sys, print_warning=True):
8383

8484
#------------------------------------------------------------------------------
8585

86-
def norm(system, p=2, tol=1e-6, print_warning=True, method=None):
87-
"""Computes norm of system.
86+
def system_norm(system, p=2, tol=1e-6, print_warning=True, method=None):
87+
"""Computes the input/output norm of system.
8888
8989
Parameters
9090
----------
9191
system : LTI (:class:`StateSpace` or :class:`TransferFunction`)
92-
System in continuous or discrete time for which the norm should be computed.
92+
System in continuous or discrete time for which the norm should
93+
be computed.
9394
p : int or str
94-
Type of norm to be computed. ``p=2`` gives the H2 norm, and ``p='inf'`` gives the L-infinity norm.
95+
Type of norm to be computed. `p=2` gives the H2 norm, and
96+
`p='inf'` gives the L-infinity norm.
9597
tol : float
9698
Relative tolerance for accuracy of L-infinity norm computation. Ignored
97-
unless ``p='inf'``.
99+
unless `p='inf'`.
98100
print_warning : bool
99101
Print warning message in case norm value may be uncertain.
100102
method : str, optional
101103
Set the method used for computing the result. Current methods are
102-
``'slycot'`` and ``'scipy'``. If set to ``None`` (default), try ``'slycot'`` first
103-
and then ``'scipy'``.
104+
'slycot' and 'scipy'. If set to `None` (default), try 'slycot' first
105+
and then 'scipy'.
104106
105107
Returns
106108
-------
@@ -121,7 +123,8 @@ def norm(system, p=2, tol=1e-6, print_warning=True, method=None):
121123
"""
122124

123125
if not isinstance(system, (ct.StateSpace, ct.TransferFunction)):
124-
raise TypeError('Parameter ``system``: must be a ``StateSpace`` or ``TransferFunction``')
126+
raise TypeError(
127+
"Parameter `system`: must be a `StateSpace` or `TransferFunction`")
125128

126129
G = ct.ss(system)
127130
A = G.A
@@ -292,3 +295,5 @@ def _Hamilton_matrix(gamma):
292295
else:
293296
raise ct.ControlArgument(f"Norm computation for p={p} currently not supported.")
294297

298+
299+
norm = system_norm

‎control/xferfcn.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1243,7 +1243,7 @@ def sample(self, Ts, method='zoh', alpha=None, prewarp_frequency=None,
12431243
return TransferFunction(sysd, name=name, **kwargs)
12441244

12451245
def dcgain(self, warn_infinite=False):
1246-
"""Return the zero-frequency (or DC) gain.
1246+
"""Return the zero-frequency ("DC") gain.
12471247
12481248
For a continous-time transfer function G(s), the DC gain is G(0)
12491249
For a discrete-time transfer function G(z), the DC gain is G(1)

‎doc/conf.py‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -121,6 +121,9 @@
121121
# Set the default role to render items in backticks as code
122122
default_role = 'py:obj'
123123

124+
# Align inline math with text
125+
imgmath_use_preview = True
126+
124127
# Theme options are theme-specific and customize the look and feel of a theme
125128
# further. For a list of options available for each theme, see the
126129
# documentation.

‎doc/functions.rst‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -114,11 +114,12 @@ Control system analysis
114114
get_input_ff_index
115115
get_output_fb_index
116116
ispassive
117+
linfnorm
117118
margin
118-
norm
119119
solve_passivity_LMI
120120
stability_margins
121121
step_info
122+
system_norm
122123
phase_crossover_frequencies
123124
poles
124125
zeros

‎doc/intro.rst‎

Lines changed: 36 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ Guide. This guide contains information on using the python-control
77
package, including documentation for all functions in the package and
88
examples illustrating their use.
99

10+
1011
Package overview
1112
================
1213

@@ -16,6 +17,7 @@ Package overview
1617
:no-inherited-members:
1718
:no-special-members:
1819

20+
1921
Installation
2022
============
2123

@@ -82,6 +84,35 @@ control package::
8284
Note that Google colab does not currently support Slycot, so some
8385
functionality may not be available.
8486

87+
88+
Package conventions
89+
===================
90+
91+
The python-control package makes use of a few naming and calling conventions:
92+
93+
* Function names are written in lower case with underscores between
94+
words ('frequency_response').
95+
96+
* Class names use camel case ('StateSpace', 'ControlPlot', etc) and
97+
instances of the class are created with "factory functions" ('ss')
98+
or as the output of an operation ('bode_plot').
99+
100+
* Functions that return multiple values use either objects (with
101+
elements for each return value) or tuples. For those functions that
102+
return tuples, the underscore variable can be used if only some of
103+
the return values are needed::
104+
105+
K, _, _ = lqr(sys)
106+
107+
* Python-control supports both single-input, single-output (SISO)
108+
systems and mullti-input, multi-output (MIMO) systems, including
109+
time and frequency responses. By default, SISO systems will
110+
typically generate objects that have the input and output dimensions
111+
supressed (using the NumPy :func:`~numpy.squeeze` function). The
112+
`squeeze` keyword can be set to `False` to force functions to return
113+
objects that include the input and output dimensions.
114+
115+
85116
Some differences from MATLAB
86117
============================
87118

@@ -102,11 +133,11 @@ some things to keep in mind:
102133
vectors implemented as nested list . So [1 2 3] must be written as
103134
[1, 2, 3] and matrices are written using 2D nested lists, e.g., [[1,
104135
2], [3, 4]].
105-
* Functions that return multiple values use either objects (with
106-
elements for each return value) or tuples. The number of elements
107-
in a tuple is fixed and so functions that return variable numbers of
108-
return values will have a parameter of the form `return_<val>`
109-
that is used to return additional data.
136+
* Functions that in MATLAB would return variable numbers of values
137+
will have a parameter of the form `return_<val>` that is used to
138+
return additional data. (These functions usually return an object of
139+
a class that has attributpes that can be used to access the
140+
information and this is the preferred usage pattern.)
110141
* You cannot use braces for collections; use tuples instead.
111142
* Time series data have time as the final index (see
112143
:ref:`time-series-convention`).

0 commit comments

Comments
 (0)