Skip to content

Commit bda7d82

Browse files
murrayrmmurrayrm
committed
DOC: fix inconsistencies in class constructor + class list documentation
1 parent 70a6cf9 commit bda7d82

File tree

13 files changed

+232
-257
lines changed

13 files changed

+232
-257
lines changed

‎control/descfcn.py‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@
2626

2727
# Class for nonlinearities with a built-in describing function
2828
class DescribingFunctionNonlinearity():
29-
"""Base class for nonlinear systems with a describing function
29+
"""Base class for nonlinear systems with a describing function.
3030
3131
This class is intended to be used as a base class for nonlinear functions
3232
that have an analytically defined describing function. Subclasses should
@@ -36,16 +36,16 @@ class DescribingFunctionNonlinearity():
3636
3737
"""
3838
def __init__(self):
39-
"""Initailize a describing function nonlinearity (optional)"""
39+
"""Initailize a describing function nonlinearity (optional)."""
4040
pass
4141

4242
def __call__(self, A):
43-
"""Evaluate the nonlinearity at a (scalar) input value"""
43+
"""Evaluate the nonlinearity at a (scalar) input value."""
4444
raise NotImplementedError(
4545
"__call__() not implemented for this function (internal error)")
4646

4747
def describing_function(self, A):
48-
"""Return the describing function for a nonlinearity
48+
"""Return the describing function for a nonlinearity.
4949
5050
This method is used to allow analytical representations of the
5151
describing function for a nonlinearity. It turns the (complex) value
@@ -56,7 +56,7 @@ def describing_function(self, A):
5656
"describing function not implemented for this function")
5757

5858
def _isstatic(self):
59-
"""Return True if the function has no internal state (memoryless)
59+
"""Return True if the function has no internal state (memoryless).
6060
6161
This internal function is used to optimize numerical computation of
6262
the describing function. It can be set to `True` if the instance
@@ -329,7 +329,7 @@ def _find_intersection(L1a, L1b, L2a, L2b):
329329

330330
# Saturation nonlinearity
331331
class saturation_nonlinearity(DescribingFunctionNonlinearity):
332-
"""Create a saturation nonlinearity for use in describing function analysis
332+
"""Create saturation nonlinearity for use in describing function analysis.
333333
334334
This class creates a nonlinear function representing a saturation with
335335
given upper and lower bounds, including the describing function for the
@@ -381,7 +381,7 @@ def describing_function(self, A):
381381

382382
# Relay with hysteresis (FBS2e, Example 10.12)
383383
class relay_hysteresis_nonlinearity(DescribingFunctionNonlinearity):
384-
"""Relay w/ hysteresis nonlinearity for use in describing function analysis
384+
"""Relay w/ hysteresis nonlinearity for describing function analysis.
385385
386386
This class creates a nonlinear function representing a a relay with
387387
symmetric upper and lower bounds of magnitude `b` and a hysteretic region
@@ -437,7 +437,7 @@ def describing_function(self, A):
437437

438438
# Friction-dominated backlash nonlinearity (#48 in Gelb and Vander Velde, 1968)
439439
class friction_backlash_nonlinearity(DescribingFunctionNonlinearity):
440-
"""Backlash nonlinearity for use in describing function analysis
440+
"""Backlash nonlinearity for describing function analysis.
441441
442442
This class creates a nonlinear function representing a friction-dominated
443443
backlash nonlinearity ,including the describing function for the

‎control/flatsys/bezier.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,7 @@
4343
from .basis import BasisFamily
4444

4545
class BezierFamily(BasisFamily):
46-
r"""Polynomial basis functions.
46+
r"""Bezier curve basis functions.
4747
4848
This class represents the family of polynomials of the form
4949

‎control/flatsys/flatsys.py‎

Lines changed: 57 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -54,8 +54,59 @@ class FlatSystem(NonlinearIOSystem):
5454
"""Base class for representing a differentially flat system.
5555
5656
The FlatSystem class is used as a base class to describe differentially
57-
flat systems for trajectory generation. The class must implement two
58-
functions:
57+
flat systems for trajectory generation. The output of the system does not
58+
need to be the differentially flat output.
59+
60+
Parameters
61+
----------
62+
forward : callable
63+
A function to compute the flat flag given the states and input.
64+
reverse : callable
65+
A function to compute the states and input given the flat flag.
66+
updfcn : callable, optional
67+
Function returning the state update function
68+
69+
`updfcn(t, x, u[, param]) -> array`
70+
71+
where `x` is a 1-D array with shape (nstates,), `u` is a 1-D array
72+
with shape (ninputs,), `t` is a float representing the currrent
73+
time, and `param` is an optional dict containing the values of
74+
parameters used by the function. If not specified, the state
75+
space update will be computed using the flat system coordinates.
76+
outfcn : callable
77+
Function returning the output at the given state
78+
79+
`outfcn(t, x, u[, param]) -> array`
80+
81+
where the arguments are the same as for `upfcn`. If not
82+
specified, the output will be the flat outputs.
83+
inputs : int, list of str, or None
84+
Description of the system inputs. This can be given as an integer
85+
count or as a list of strings that name the individual signals.
86+
If an integer count is specified, the names of the signal will be
87+
of the form `s[i]` (where `s` is one of `u`, `y`, or `x`). If
88+
this parameter is not given or given as `None`, the relevant
89+
quantity will be determined when possible based on other
90+
information provided to functions using the system.
91+
outputs : int, list of str, or None
92+
Description of the system outputs. Same format as `inputs`.
93+
states : int, list of str, or None
94+
Description of the system states. Same format as `inputs`.
95+
dt : None, True or float, optional
96+
System timebase. None (default) indicates continuous
97+
time, True indicates discrete time with undefined sampling
98+
time, positive number is discrete time with specified
99+
sampling time.
100+
params : dict, optional
101+
Parameter values for the systems. Passed to the evaluation
102+
functions for the system as default values, overriding internal
103+
defaults.
104+
name : string, optional
105+
System name (used for specifying signals)
106+
107+
Notes
108+
-----
109+
The class must implement two functions:
59110
60111
zflag = flatsys.foward(x, u)
61112
This function computes the flag (derivatives) of the flat output.
@@ -83,65 +134,13 @@ def __init__(self,
83134
updfcn=None, outfcn=None, # I/O system
84135
inputs=None, outputs=None,
85136
states=None, params={}, dt=None, name=None):
86-
"""Create a differentially flat input/output system.
137+
"""Create a differentially flat I/O system.
87138
88139
The FlatIOSystem constructor is used to create an input/output system
89-
object that also represents a differentially flat system. The output
90-
of the system does not need to be the differentially flat output.
91-
92-
Parameters
93-
----------
94-
forward : callable
95-
A function to compute the flat flag given the states and input.
96-
reverse : callable
97-
A function to compute the states and input given the flat flag.
98-
updfcn : callable, optional
99-
Function returning the state update function
100-
101-
`updfcn(t, x, u[, param]) -> array`
102-
103-
where `x` is a 1-D array with shape (nstates,), `u` is a 1-D array
104-
with shape (ninputs,), `t` is a float representing the currrent
105-
time, and `param` is an optional dict containing the values of
106-
parameters used by the function. If not specified, the state
107-
space update will be computed using the flat system coordinates.
108-
outfcn : callable
109-
Function returning the output at the given state
110-
111-
`outfcn(t, x, u[, param]) -> array`
112-
113-
where the arguments are the same as for `upfcn`. If not
114-
specified, the output will be the flat outputs.
115-
inputs : int, list of str, or None
116-
Description of the system inputs. This can be given as an integer
117-
count or as a list of strings that name the individual signals.
118-
If an integer count is specified, the names of the signal will be
119-
of the form `s[i]` (where `s` is one of `u`, `y`, or `x`). If
120-
this parameter is not given or given as `None`, the relevant
121-
quantity will be determined when possible based on other
122-
information provided to functions using the system.
123-
outputs : int, list of str, or None
124-
Description of the system outputs. Same format as `inputs`.
125-
states : int, list of str, or None
126-
Description of the system states. Same format as `inputs`.
127-
dt : None, True or float, optional
128-
System timebase. None (default) indicates continuous
129-
time, True indicates discrete time with undefined sampling
130-
time, positive number is discrete time with specified
131-
sampling time.
132-
params : dict, optional
133-
Parameter values for the systems. Passed to the evaluation
134-
functions for the system as default values, overriding internal
135-
defaults.
136-
name : string, optional
137-
System name (used for specifying signals)
138-
139-
Returns
140-
-------
141-
InputOutputSystem
142-
Input/output system object
140+
object that also represents a differentially flat system.
143141
144142
"""
143+
145144
# TODO: specify default update and output functions
146145
if updfcn is None: updfcn = self._flat_updfcn
147146
if outfcn is None: outfcn = self._flat_outfcn
@@ -158,6 +157,7 @@ def __init__(self,
158157
# Save the length of the flat flag
159158

160159
def forward(self, x, u, params={}):
160+
161161
"""Compute the flat flag given the states and input.
162162
163163
Given the states and inputs for a system, compute the flat

‎control/flatsys/linflat.py‎

Lines changed: 0 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -75,11 +75,6 @@ class LinearFlatSystem(FlatSystem, LinearIOSystem):
7575
name : string, optional
7676
System name (used for specifying signals)
7777
78-
Returns
79-
-------
80-
iosys : LinearFlatSystem
81-
Linear system represented as an flat input/output system
82-
8378
"""
8479

8580
def __init__(self, linsys, inputs=None, outputs=None, states=None,

‎control/flatsys/systraj.py‎

Lines changed: 20 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -41,30 +41,29 @@
4141
class SystemTrajectory:
4242
"""Class representing a system trajectory.
4343
44-
The `SystemTrajectory` class is used to represent the trajectory of
45-
a (differentially flat) system. Used by the
46-
:func:`~control.trajsys.point_to_point` function to return a
47-
trajectory.
44+
The `SystemTrajectory` class is used to represent the
45+
trajectory of a (differentially flat) system. Used by the
46+
:func:`~control.trajsys.point_to_point` function to return a trajectory.
4847
49-
"""
50-
def __init__(self, sys, basis, coeffs=[], flaglen=[]):
51-
"""Initilize a system trajectory object.
48+
Parameters
49+
----------
50+
sys : FlatSystem
51+
Flat system object associated with this trajectory.
52+
basis : BasisFamily
53+
Family of basis vectors to use to represent the trajectory.
54+
coeffs : list of 1D arrays, optional
55+
For each flat output, define the coefficients of the basis
56+
functions used to represent the trajectory. Defaults to an empty
57+
list.
58+
flaglen : list of ints, optional
59+
For each flat output, the number of derivatives of the flat
60+
output used to define the trajectory. Defaults to an empty
61+
list.
5262
53-
Parameters
54-
----------
55-
sys : FlatSystem
56-
Flat system object associated with this trajectory.
57-
basis : BasisFamily
58-
Family of basis vectors to use to represent the trajectory.
59-
coeffs : list of 1D arrays, optional
60-
For each flat output, define the coefficients of the basis
61-
functions used to represent the trajectory. Defaults to an empty
62-
list.
63-
flaglen : list of ints, optional
64-
For each flat output, the number of derivatives of the flat output
65-
used to define the trajectory. Defaults to an empty list.
63+
"""
6664

67-
"""
65+
def __init__(self, sys, basis, coeffs=[], flaglen=[]):
66+
"""Initilize a system trajectory object."""
6867
self.nstates = sys.nstates
6968
self.ninputs = sys.ninputs
7069
self.system = sys

‎control/frdata.py‎

Lines changed: 11 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -57,9 +57,9 @@
5757

5858

5959
class FrequencyResponseData(LTI):
60-
"""FrequencyResponseData(d, w)
60+
"""FrequencyResponseData(d, w[, smooth])
6161
62-
A class for models defined by frequency response data (FRD)
62+
A class for models defined by frequency response data (FRD).
6363
6464
The FrequencyResponseData (FRD) class is used to represent systems in
6565
frequency response data form.
@@ -84,13 +84,18 @@ class FrequencyResponseData(LTI):
8484
----------
8585
ninputs, noutputs : int
8686
Number of input and output variables.
87+
omega : 1D array
88+
Frequency points of the response.
89+
fresp : 3D array
90+
Frequency response, indexed by output index, input index, and
91+
frequency point.
8792
8893
Notes
8994
-----
90-
The main data members are 'omega' and 'fresp', where `omega` is a 1D array
91-
with the frequency points of the response, and `fresp` is a 3D array, with
92-
the first dimension corresponding to the output index of the FRD, the
93-
second dimension corresponding to the input index, and the 3rd dimension
95+
The main data members are 'omega' and 'fresp', where 'omega' is a the 1D
96+
arran yf frequency points and and 'fresp' is a 3D array, with the first
97+
dimension corresponding to the output index of the FRD, the second
98+
dimension corresponding to the input index, and the 3rd dimension
9499
corresponding to the frequency points in omega. For example,
95100
96101
>>> frdata[2,5,:] = numpy.array([1., 0.8-0.2j, 0.2-0.8j])

0 commit comments

Comments
 (0)