Skip to content

Commit acaa417

Browse files
murrayrmmurrayrm
committed
regularize Returns docstring for bundle objects
1 parent d498ad5 commit acaa417

26 files changed

Lines changed: 423 additions & 436 deletions

‎control/bdalg.py‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,7 @@ def series(*sys, **kwargs):
3838
3939
Returns
4040
-------
41-
out : scalar, array, or `InputOutputSystem`
41+
out : `InputOutputSystem`
4242
Series interconnection of the systems.
4343
4444
Other Parameters
@@ -109,7 +109,7 @@ def parallel(*sys, **kwargs):
109109
110110
Returns
111111
-------
112-
out : scalar, array, or `InputOutputSystem`
112+
out : `InputOutputSystem`
113113
Parallel interconnection of the systems.
114114
115115
Other Parameters
@@ -177,7 +177,7 @@ def negate(sys, **kwargs):
177177
178178
Returns
179179
-------
180-
out : scalar, array, or `InputOutputSystem`
180+
out : `InputOutputSystem`
181181
Negated system.
182182
183183
Other Parameters
@@ -233,7 +233,7 @@ def feedback(sys1, sys2=1, sign=-1, **kwargs):
233233
234234
Returns
235235
-------
236-
out : scalar, array, or `InputOutputSystem`
236+
out : `InputOutputSystem`
237237
Feedback interconnection of the systems.
238238
239239
Other Parameters
@@ -608,7 +608,7 @@ def split_tf(transfer_function):
608608
609609
Returns
610610
-------
611-
np.ndarray
611+
ndarray
612612
NumPy array of SISO transfer functions.
613613
614614
Examples

‎control/canonical.py‎

Lines changed: 12 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -275,7 +275,10 @@ def _bdschur_defective(blksizes, eigvals):
275275
-------
276276
True iff Schur blocks are defective.
277277
278-
blksizes, eigvals are the 3rd and 4th results returned by mb03rd.
278+
Notes
279+
-----
280+
`blksizes`, `eigvals` are the 3rd and 4th results returned by mb03rd.
281+
279282
"""
280283
if any(blksizes > 2):
281284
return True
@@ -327,9 +330,10 @@ def _bdschur_condmax_search(aschur, tschur, condmax):
327330
328331
Notes
329332
-----
330-
Outputs as for slycot.mb03rd
333+
Outputs as for slycot.mb03rd.
334+
335+
`aschur`, `tschur` are as returned by scipy.linalg.schur.
331336
332-
aschur, tschur are as returned by scipy.linalg.schur.
333337
"""
334338
try:
335339
from slycot import mb03rd
@@ -428,12 +432,11 @@ def bdschur(a, condmax=None, sort=None):
428432
429433
If `sort` is 'continuous', the blocks are sorted according to
430434
associated eigenvalues. The ordering is first by real part of
431-
eigenvalue, in descending order, then by absolute value of
432-
imaginary part of eigenvalue, also in decreasing order.
435+
eigenvalue, in descending order, then by absolute value of imaginary
436+
part of eigenvalue, also in decreasing order.
433437
434-
If `sort` is 'discrete', the blocks are sorted as for
435-
'continuous', but applied to log of eigenvalues
436-
(i.e., continuous-equivalent eigenvalues).
438+
If `sort` is 'discrete', the blocks are sorted as for 'continuous', but
439+
applied to log of eigenvalues (i.e., continuous-equivalent eigenvalues).
437440
438441
Examples
439442
--------
@@ -509,7 +512,7 @@ def modal_form(xsys, condmax=None, sort=False):
509512
-------
510513
zsys : `StateSpace` object
511514
System in modal canonical form, with state z.
512-
T : (M, M) array
515+
T : (M, M) ndarray
513516
Coordinate transformation: z = T * x.
514517
515518
Examples

‎control/ctrlplot.py‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -239,13 +239,13 @@ def get_plot_axes(line_array):
239239
240240
Parameters
241241
----------
242-
line_array : array of list of Line2D
242+
line_array : array of list of `matplotlib.lines.Line2D`
243243
A 2D array with elements corresponding to a list of lines appearing
244244
in an axes, matching the return type of a time response data plot.
245245
246246
Returns
247247
-------
248-
axes_array : array of list of Axes
248+
axes_array : array of list of `matplotlib.axes.Axes`
249249
A 2D array with elements corresponding to the Axes associated with
250250
the lines in `line_array`.
251251
@@ -287,7 +287,7 @@ def pole_zero_subplots(
287287
288288
Returns
289289
-------
290-
ax_array : array
290+
ax_array : ndarray
291291
2D array of axes.
292292
293293
"""
@@ -612,8 +612,10 @@ def _add_arrows_to_line2D(
612612
613613
Returns
614614
-------
615-
arrows: list of arrows
615+
arrows : list of arrows
616616
617+
Notes
618+
-----
617619
Based on https://stackoverflow.com/questions/26911898/
618620
619621
"""

‎control/ctrlutil.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ def unwrap(angle, period=2*math.pi):
2828
2929
Returns
3030
-------
31-
angle_out : array_like
31+
angle_out : ndarray
3232
Output array, with jumps of period/2 eliminated.
3333
3434
Examples

‎control/descfcn.py‎

Lines changed: 26 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -124,7 +124,7 @@ def describing_function(
124124
125125
Returns
126126
-------
127-
df : array of complex
127+
df : ndarray of complex
128128
The (complex) value of the describing function at the given amplitudes.
129129
130130
Raises
@@ -312,15 +312,21 @@ def describing_function_response(
312312
-------
313313
response : `DescribingFunctionResponse` object
314314
Response object that contains the result of the describing function
315-
analysis. The following information can be retrieved from this
316-
object:
317-
response.intersections : 1D array of 2-tuples or None
315+
analysis. The results can plotted using the
316+
`~DescribingFunctionResponse.plot` method.
317+
response.intersections : 1D ndarray of 2-tuples or None
318318
A list of all amplitudes and frequencies in which
319319
:math:`H(j\\omega) N(a) = -1`, where :math:`N(a)` is the describing
320320
function associated with `F`, or None if there are no such
321321
points. Each pair represents a potential limit cycle for the
322322
closed loop system with amplitude given by the first value of the
323323
tuple and frequency given by the second value.
324+
response.Nvals : complex ndarray
325+
Complex value of the describing function, indexed by amplitude.
326+
327+
See Also
328+
--------
329+
DescribingFunctionResponse, describing_function_plot
324330
325331
Examples
326332
--------
@@ -456,20 +462,22 @@ def describing_function_plot(
456462
Returns
457463
-------
458464
cplt : `ControlPlot` object
459-
Object containing the data that were plotted:
460-
461-
* cplt.lines: Array of `matplotlib.lines.Line2D` objects for
462-
each line in the plot. The first element of the array is
463-
a list of lines (typically only one) for the Nyquist plot
464-
of the linear I/O system. The second element of the array
465-
is a list of lines (typically only one) for the describing
466-
function curve.
467-
468-
* cplt.axes: 2D array of `matplotlib.axes.Axes` for the plot.
469-
470-
* cplt.figure: `matplotlib.figure.Figure` containing the plot.
471-
472-
See `ControlPlot` for more detailed information.
465+
Object containing the data that were plotted. See `ControlPlot`
466+
for more detailed information.
467+
cplt.lines : array of `matplotlib.lines.Line2D`
468+
Array containing information on each line in the plot. The first
469+
element of the array is a list of lines (typically only one) for
470+
the Nyquist plot of the linear I/O system. The second element of
471+
the array is a list of lines (typically only one) for the
472+
describing function curve.
473+
cplt.axes : 2D array of `matplotlib.axes.Axes`
474+
Axes for each subplot.
475+
cplt.figure : `matplotlib.figure.Figure`
476+
Figure containing the plot.
477+
478+
See Also
479+
--------
480+
DescribingFunctionResponse, describing_function_response
473481
474482
Examples
475483
--------

‎control/dtime.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@ def sample_system(sysc, Ts, method='zoh', alpha=None, prewarp_frequency=None,
3434
Returns
3535
-------
3636
sysd : LTI of the same class (`StateSpace` or `TransferFunction`)
37-
Discrete time system, with sampling rate Ts.
37+
Discrete time system, with sampling rate `Ts`.
3838
3939
Other Parameters
4040
----------------

‎control/flatsys/flatsys.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -133,7 +133,7 @@ def forward(self, x, u, params=None):
133133
Returns
134134
-------
135135
zflag : list of 1D arrays
136-
For each flat output :math:`z_i`, zflag[i] should be an
136+
For each flat output :math:`z_i`, `zflag[i]` should be an
137137
ndarray of length :math:`q_i` that contains the flat
138138
output and its first :math:`q_i` derivatives.
139139

‎control/flatsys/systraj.py‎

Lines changed: 21 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -131,28 +131,27 @@ def response(self, timepts, transpose=False, return_x=False, squeeze=None):
131131
132132
Returns
133133
-------
134-
response : `control.TimeResponseData`
135-
Time response represented as a `TimeResponseData` object
136-
containing the following properties:
137-
138-
* time (array): Time values of the output.
139-
140-
* outputs (array): Response of the system. If the system is
141-
SISO and squeeze is not True, the array is 1D (indexed by
142-
time). If the system is not SISO or `squeeze` is False,
143-
the array is 3D (indexed by the output, trace, and time).
144-
145-
* states (array): Time evolution of the state vector,
146-
represented as either a 2D array indexed by state and time
147-
(if SISO) or a 3D array indexed by state, trace, and time.
148-
Not affected by `squeeze`.
149-
150-
* inputs (array): Input(s) to the system, indexed in the same
151-
manner as `outputs`.
152-
153-
The return value of the system can also be accessed by assigning
154-
the function to a tuple of length 2 (time, output) or of length 3
155-
(time, output, state) if `return_x` is True.
134+
response : `TimeResponseData`
135+
Time response data object representing the input/output response.
136+
When accessed as a tuple, returns ``(time, outputs)`` or ``(time,
137+
outputs, states`` if `return_x` is True. If the input/output
138+
system signals are named, these names will be used as labels for
139+
the time response. If `sys` is a list of systems, returns a
140+
`TimeResponseList` object. Results can be plotted using the
141+
`~TimeResponseData.plot` method. See `TimeResponseData` for more
142+
detailed information.
143+
response.time : array
144+
Time values of the output.
145+
response.outputs : array
146+
Response of the system. If the system is SISO and `squeeze` is
147+
not True, the array is 1D (indexed by time). If the system is not
148+
SISO or `squeeze` is False, the array is 2D (indexed by output and
149+
time).
150+
response.states : array
151+
Time evolution of the state vector, represented as a 2D array
152+
indexed by state and time.
153+
response.inputs : array
154+
Input(s) to the system, indexed by input and time.
156155
157156
"""
158157
# Compute the state and input response using the eval function

0 commit comments

Comments
 (0)