Skip to content

Commit eedbf2b

Browse files
murrayrmmurrayrm
committed
update class documentation (+ unit tests)
1 parent 056110e commit eedbf2b

71 files changed

Lines changed: 1116 additions & 702 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎control/bdalg.py‎

Lines changed: 24 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -53,7 +53,7 @@ def series(*sys, **kwargs):
5353
'<subsys_name>.<state_name>' for interconnected nonlinear systems.
5454
name : string, optional
5555
System name (used for specifying signals). If unspecified, a generic
56-
name <sys[id]> is generated with a unique integer id.
56+
name 'sys[id]' is generated with a unique integer id.
5757
5858
Raises
5959
------
@@ -124,7 +124,7 @@ def parallel(*sys, **kwargs):
124124
'<subsys_name>.<state_name>' for interconnected nonlinear systems.
125125
name : string, optional
126126
System name (used for specifying signals). If unspecified, a generic
127-
name <sys[id]> is generated with a unique integer id.
127+
name 'sys[id]' is generated with a unique integer id.
128128
129129
Raises
130130
------
@@ -139,7 +139,7 @@ def parallel(*sys, **kwargs):
139139
Notes
140140
-----
141141
This function is a wrapper for the __add__ function in the
142-
StateSpace and TransferFunction classes. The output type is usually
142+
`StateSpace` and `TransferFunction` classes. The output type is usually
143143
the type of `sys1`. If `sys1` is a scalar, then the output type is
144144
the type of `sys2`.
145145
@@ -168,8 +168,7 @@ def parallel(*sys, **kwargs):
168168
return sys
169169

170170
def negate(sys, **kwargs):
171-
"""
172-
Return the negative of a system.
171+
"""Return the negative of a system.
173172
174173
Parameters
175174
----------
@@ -193,16 +192,17 @@ def negate(sys, **kwargs):
193192
'<subsys_name>.<state_name>' for interconnected nonlinear systems.
194193
name : string, optional
195194
System name (used for specifying signals). If unspecified, a generic
196-
name <sys[id]> is generated with a unique integer id.
195+
name 'sys[id]' is generated with a unique integer id.
197196
198197
See Also
199198
--------
200199
append, feedback, interconnect, parallel, series
201200
202201
Notes
203202
-----
204-
This function is a wrapper for the __neg__ function in the StateSpace and
205-
TransferFunction classes. The output type is the same as the input type.
203+
This function is a wrapper for the __neg__ function in the `StateSpace`
204+
and `TransferFunction` classes. The output type is the same as the
205+
input type.
206206
207207
Examples
208208
--------
@@ -248,16 +248,16 @@ def feedback(sys1, sys2=1, sign=-1, **kwargs):
248248
'<subsys_name>.<state_name>' for interconnected nonlinear systems.
249249
name : string, optional
250250
System name (used for specifying signals). If unspecified, a generic
251-
name <sys[id]> is generated with a unique integer id.
251+
name 'sys[id]' is generated with a unique integer id.
252252
253253
Raises
254254
------
255255
ValueError
256-
if `sys1` does not have as many inputs as `sys2` has outputs, or if
257-
`sys2` does not have as many inputs as `sys1` has outputs
256+
If `sys1` does not have as many inputs as `sys2` has outputs, or if
257+
`sys2` does not have as many inputs as `sys1` has outputs.
258258
NotImplementedError
259-
if an attempt is made to perform a feedback on a MIMO TransferFunction
260-
object
259+
If an attempt is made to perform a feedback on a MIMO `TransferFunction`
260+
object.
261261
262262
See Also
263263
--------
@@ -341,7 +341,7 @@ def append(*sys, **kwargs):
341341
'<subsys_name>.<state_name>' for interconnected nonlinear systems.
342342
name : string, optional
343343
System name (used for specifying signals). If unspecified, a generic
344-
name <sys[id]> is generated with a unique integer id.
344+
name 'sys[id]' is generated with a unique integer id.
345345
346346
See Also
347347
--------
@@ -472,16 +472,16 @@ def combine_tf(tf_array, **kwargs):
472472
473473
Parameters
474474
----------
475-
tf_array : list of list of TransferFunction or array_like
475+
tf_array : list of list of `TransferFunction` or array_like
476476
Transfer matrix represented as a two-dimensional array or
477-
list-of-lists containing TransferFunction objects. The
477+
list-of-lists containing `TransferFunction` objects. The
478478
`TransferFunction` objects can have multiple outputs and inputs, as
479479
long as the dimensions are compatible.
480480
481481
Returns
482482
-------
483-
TransferFunction
484-
Transfer matrix represented as a single MIMO TransferFunction object.
483+
`TransferFunction`
484+
Transfer matrix represented as a single MIMO `TransferFunction` object.
485485
486486
Other Parameters
487487
----------------
@@ -491,7 +491,7 @@ def combine_tf(tf_array, **kwargs):
491491
or 'y'). See `InputOutputSystem` for more information.
492492
name : string, optional
493493
System name (used for specifying signals). If unspecified, a generic
494-
name <sys[id]> is generated with a unique integer id.
494+
name 'sys[id]' is generated with a unique integer id.
495495
496496
Raises
497497
------
@@ -603,7 +603,7 @@ def split_tf(transfer_function):
603603
604604
Parameters
605605
----------
606-
transfer_function : TransferFunction
606+
transfer_function : `TransferFunction`
607607
MIMO transfer function to split.
608608
609609
Returns
@@ -658,11 +658,11 @@ def split_tf(transfer_function):
658658
return np.array(tf_split_lst, dtype=object)
659659

660660
def _ensure_tf(arraylike_or_tf, dt=None):
661-
"""Convert an array-like to a transfer function.
661+
"""Convert an array_like to a transfer function.
662662
663663
Parameters
664664
----------
665-
arraylike_or_tf : TransferFunction or array_like
665+
arraylike_or_tf : `TransferFunction` or array_like
666666
Array-like or transfer function.
667667
dt : None, True or float, optional
668668
System timebase. 0 (default) indicates continuous
@@ -673,7 +673,7 @@ def _ensure_tf(arraylike_or_tf, dt=None):
673673
674674
Returns
675675
-------
676-
TransferFunction
676+
`TransferFunction`
677677
Transfer function.
678678
679679
Raises
@@ -707,7 +707,7 @@ def _ensure_tf(arraylike_or_tf, dt=None):
707707
)
708708
except TypeError:
709709
raise ValueError(
710-
"`arraylike_or_tf` must only contain array-likes or transfer "
710+
"`arraylike_or_tf` must only contain array_likes or transfer "
711711
"functions."
712712
)
713713
return tfn

‎control/canonical.py‎

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ def canonical_form(xsys, form='reachable'):
2424
2525
Parameters
2626
----------
27-
xsys : StateSpace object
27+
xsys : `StateSpace` object
2828
System to be transformed, with state 'x'.
2929
form : str
3030
Canonical form for transformation. Chosen from:
@@ -34,7 +34,7 @@ def canonical_form(xsys, form='reachable'):
3434
3535
Returns
3636
-------
37-
zsys : StateSpace object
37+
zsys : `StateSpace` object
3838
System in desired canonical form, with state 'z'.
3939
T : (M, M) real ndarray
4040
Coordinate transformation matrix, z = T * x.
@@ -76,12 +76,12 @@ def reachable_form(xsys):
7676
7777
Parameters
7878
----------
79-
xsys : StateSpace object
79+
xsys : `StateSpace` object
8080
System to be transformed, with state `x`.
8181
8282
Returns
8383
-------
84-
zsys : StateSpace object
84+
zsys : `StateSpace` object
8585
System in reachable canonical form, with state `z`.
8686
T : (M, M) real ndarray
8787
Coordinate transformation: z = T * x.
@@ -141,12 +141,12 @@ def observable_form(xsys):
141141
142142
Parameters
143143
----------
144-
xsys : StateSpace object
144+
xsys : `StateSpace` object
145145
System to be transformed, with state `x`.
146146
147147
Returns
148148
-------
149-
zsys : StateSpace object
149+
zsys : `StateSpace` object
150150
System in observable canonical form, with state `z`.
151151
T : (M, M) real ndarray
152152
Coordinate transformation: z = T * x.
@@ -202,7 +202,7 @@ def similarity_transform(xsys, T, timescale=1, inverse=False):
202202
203203
Parameters
204204
----------
205-
xsys : StateSpace object
205+
xsys : `StateSpace` object
206206
System to transform.
207207
T : (M, M) array_like
208208
The matrix `T` defines the new set of coordinates z = T x.
@@ -214,7 +214,7 @@ def similarity_transform(xsys, T, timescale=1, inverse=False):
214214
215215
Returns
216216
-------
217-
zsys : StateSpace object
217+
zsys : `StateSpace` object
218218
System in transformed coordinates, with state 'z'.
219219
220220
See Also
@@ -496,7 +496,7 @@ def modal_form(xsys, condmax=None, sort=False):
496496
497497
Parameters
498498
----------
499-
xsys : StateSpace object
499+
xsys : `StateSpace` object
500500
System to be transformed, with state x.
501501
condmax : None or float, optional
502502
An upper bound on individual transformations. If None, use
@@ -507,9 +507,9 @@ def modal_form(xsys, condmax=None, sort=False):
507507
508508
Returns
509509
-------
510-
zsys : StateSpace object
510+
zsys : `StateSpace` object
511511
System in modal canonical form, with state z.
512-
T : (M, M) ndarray
512+
T : (M, M) array
513513
Coordinate transformation: z = T * x.
514514
515515
Examples

‎control/config.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@
2929

3030

3131
class DefaultDict(collections.UserDict):
32-
"""Map names for settings from older version to their renamed ones.
32+
"""Default parameters dictionary, with legacy warnings.
3333
3434
If a user wants to write to an old setting, issue a warning and write to
3535
the renamed setting instead. Accessing the old setting returns the value

‎control/ctrlplot.py‎

Lines changed: 8 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -122,7 +122,7 @@
122122
#
123123

124124
class ControlPlot():
125-
"""A class for representing control figures.
125+
"""Return class for control platting functions.
126126
127127
This class is used as the return type for control plotting functions.
128128
It contains the information required to access portions of the plot
@@ -136,17 +136,17 @@ class ControlPlot():
136136
137137
Parameters
138138
----------
139-
lines : array of list of `matplotlib:Line2D`
139+
lines : array of list of `matplotlib.lines.Line2D`
140140
Array of Line2D objects for each line in the plot. Generally, the
141141
shape of the array matches the subplots shape and the value of the
142142
array is a list of Line2D objects in that subplot. Some plotting
143143
functions will return variants of this structure, as described in
144144
the individual documentation for the functions.
145-
axes : 2D array of `matplotlib:Axes`
145+
axes : 2D array of `matplotlib.axes.Axes`
146146
Array of Axes objects for each subplot in the plot.
147-
figure : `matplotlib:Figure`
147+
figure : `matplotlib.figure.Figure`
148148
Figure on which the Axes are drawn.
149-
legend : `matplotlib:.legend.Legend` (instance or ndarray)
149+
legend : `matplotlib.legend.Legend` (instance or ndarray)
150150
Legend object(s) for the plot. If more than one legend is
151151
included, this will be an array with each entry being either None
152152
(for no legend) or a legend object.
@@ -176,6 +176,7 @@ def __setitem__(self, item, val):
176176
self.lines[item] = val
177177
shape = property(lambda self: self.lines.shape, None)
178178
def reshape(self, *args):
179+
"""Reshape lines array (legacy)."""
179180
return self.lines.reshape(*args)
180181

181182
def set_plot_title(self, title, frame='axes'):
@@ -310,11 +311,11 @@ def pole_zero_subplots(
310311
case 'empty', _: # empty grid
311312
ax_array[row, col] = fig.add_subplot(nrows, ncols, index+1)
312313

313-
case True, True: # continuous time grid
314+
case True, True: # continuous-time grid
314315
ax_array[row, col], _ = sgrid(
315316
(nrows, ncols, index+1), scaling=scaling)
316317

317-
case True, False: # discrete time grid
318+
case True, False: # discrete-time grid
318319
ax_array[row, col] = fig.add_subplot(nrows, ncols, index+1)
319320
zgrid(ax=ax_array[row, col], scaling=scaling)
320321

0 commit comments

Comments
 (0)