8000 more docstring fixups · lmartinp/python-control@52a3fd4 · GitHub
[go: up one dir, main page]
Skip to content

Commit 52a3fd4

Browse files
bnavigatorbnavigator
committed
more docstring fixups
1 parent 517b1eb commit 52a3fd4

File tree

3 files changed

+43
-39
lines changed

3 files changed

+43
-39
lines changed

‎control/tests/timeresp_test.py

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -895,8 +895,7 @@ def test_time_vector(self, tsystem, fun, squeeze, matarrayout):
895895
# tout should always match t, which has shape (n, )
896896
np.testing.assert_allclose(tout, tsystem.t)
897897
elif fun == forced_response and sys.dt in [None, True]:
898-
np.testing.assert_allclose(
899-
np.diff(tout), np.full_like(tout[:-1], 1.))
898+
np.testing.assert_allclose(np.diff(tout), 1.)
900899

901900
if squeeze is False or not sys.issiso():
902901
assert yout.shape[0] == sys.noutputs

‎control/timeresp.py

Lines changed: 26 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -210,32 +210,32 @@ def forced_response(sys, T=None, U=0., X0=0., transpose=False,
210210
211211
T : array_like, optional for discrete LTI `sys`
212212
Time steps at which the input is defined; values must be evenly spaced.
213-
If None, `U` must be given and and `len(U)` time steps of sys.dt are
214-
simulated. If sys.dt is None or True (undetermined time step), a dt
215-
of 1.0 is assumed.
213+
If None, `U` must be given and `len(U)` time steps of sys.dt are
214+
simulated. If sys.dt is None or True (undetermined time step), a time
215+
step of 1.0 is assumed.
216216
217217
U : array_like or float, optional
218-
Input array giving input at each time `T`
218+
Input array giving input at each time `T`.
219+
If `U` is None or 0, `T` must be given, even for discrete
220+
time systems. In this case, for continuous time systems, a direct
221+
calculation of the matrix exponential is used, which is faster than the
222+
general interpolating algorithm used otherwise.
219223
220-
If `U` is ``None`` or ``0``, a special algorithm is used. This special
221-
algorithm is faster than the general algorithm, which is used
222-
otherwise.
223-
224-
X0 : array_like or float, optional
224+
X0 : array_like or float, default=0.
225225
Initial condition.
226226
227-
transpose : bool, optional
227+
transpose : bool, default=False
228228
If True, transpose all input and output arrays (for backward
229229
compatibility with MATLAB and :func:`scipy.signal.lsim`).
230230
231-
interpolate : bool, optional
231+
interpolate : bool, default=False
232232
If True and system is a discrete time system, the input will
233233
be interpolated between the given time steps and the output
234234
will be given at system sampling rate. Otherwise, only return
235235
the output at the times given in `T`. No effect on continuous
236236
time simulations.
237237
238-
return_x : bool, optional
238+
return_x : bool, default=None
239239
- If False, return only the time and output vectors.
240240
- If True, also return the the state vector.
241241
- If None, determine the returned variables by
@@ -245,10 +245,10 @@ def forced_response(sys, T=None, U=0., X0=0., transpose=False,
245245
squeeze : bool, optional
246246
By default, if a system is single-input, single-output (SISO) then
247247
the output response is returned as a 1D array (indexed by time). If
248-
squeeze=True, remove single-dimensional entries from the shape of
249-
the output even if the system is not SISO. If squeeze=False, keep
248+
`squeeze` is True, remove single-dimensional entries from the shape of
249+
the output even if the system is not SISO. If `squeeze` is False, keep
250250
the output as a 2D array (indexed by the output number and time)
251-
even if the system is SISO. The default value can be overridden by
251+
even if the system is SISO. The default behavior can be overridden by
252252
config.defaults['control.squeeze_time_response'].
253253
254254
Returns
@@ -263,7 +263,7 @@ def forced_response(sys, T=None, U=0., X0=0., transpose=False,
263263
time).
264264
265265
xout : array
266-
Time evolution of the state vector. Not affected by squeeze. Only
266+
Time evolution of the state vector. Not affected by `squeeze`. Only
267267
returned if `return_x` is True, or `return_x` is None and
268268
config.defaults['forced_response.return_x'] is True.
269269
@@ -284,7 +284,8 @@ def forced_response(sys, T=None, U=0., X0=0., transpose=False,
284284
--------
285285
>>> T, yout, xout = forced_response(sys, T, u, X0)
286286
287-
See :ref:`time-series-convention`.
287+
See :ref:`time-series-convention` and
288+
:ref:`package-configuration-parameters`.
288289
289290
"""
290291
if not isinstance(sys, (StateSpace, TransferFunction)):
@@ -301,6 +302,13 @@ def forced_response(sys, T=None, U=0., X0=0., transpose=False,
301302
"return_x specified for a transfer function system. Internal "
302303
"conversion to state space used; results may meaningless.")
303304

305+
# If we are passed a transfer function and X0 is non-zero, warn the user
306+
if isinstance(sys, TransferFunction) and np.any(X0 != 0):
307+
warnings.warn(
308+
"Non-zero initial condition given for transfer function system. "
309+
"Internal conversion to state space used; may not be consistent "
310+
"with given X0.")
311+
304312
sys = _convert_to_statespace(sys)
305313
A, B, C, D = np.asarray(sys.A), np.asarray(sys.B), np.asarray(sys.C), \
306314
np.asarray(sys.D)
@@ -348,7 +356,7 @@ def forced_response(sys, T=None, U=0., X0=0., transpose=False,
348356

349357
# equally spaced also implies strictly monotonic increase
350358
dt = T[1] - T[0]
351-
if not np.allclose(np.diff(T), np.full_like(T[:-1], dt)):
359+
if not np.allclose(np.diff(T), dt):
352360
raise ValueError("Parameter ``T``: time values must be "
353361
"equally spaced.")
354362
n_steps = T.shape[0] # number of simulation steps
@@ -357,13 +365,6 @@ def forced_response(sys, T=None, U=0., X0=0., transpose=False,
357365
X0 = _check_convert_array(X0, [(n_states,), (n_states, 1)],
358366
'Parameter ``X0``: ', squeeze=True)
359367

360-
# If we are passed a transfer function and X0 is non-zero, warn the user
361-
if isinstance(sys, TransferFunction) and np.any(X0 != 0):
362-
warnings.warn(
363-
"Non-zero initial condition given for transfer function system. "
364-
"Internal conversion to state space used; may not be consistent "
365-
"with given X0.")
366-
367368
xout = np.zeros((n_states, n_steps))
368369
xout[:, 0] = X0
369370
yout = np.zeros((n_outputs, n_steps))

‎doc/conventions.rst

Lines changed: 16 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -83,17 +83,17 @@ The timebase argument can be given when a system is constructed:
8383
* dt = 0: continuous time system (default)
8484
* dt > 0: discrete time system with sampling period 'dt'
8585
* dt = True: discrete time with unspecified sampling period
86-
* dt = None: no timebase specified
86+
* dt = None: no timebase specified
8787

8888
Only the :class:`StateSpace`, :class:`TransferFunction`, and
8989
:class:`InputOutputSystem` classes allow explicit representation of
9090
discrete time systems.
9191

92-
Systems must have compatible timebases in order to be combined. A discrete time
93-
system with unspecified sampling time (`dt = True`) can be combined with a system
92+
Systems must have compatible timebases in order to be combined. A discrete time
93+
system with unspecified sampling time (`dt = True`) can be combined with a system
9494
having a specified sampling time; the result will be a discrete time system with the sample time of the latter
9595
system. Similarly, a system with timebase `None` can be combined with a system having a specified
96-
timebase; the result will have the timebase of the latter system. For continuous
96+
timebase; the result will have the timebase of the latter system. For continuous
9797
time systems, the :func:`sample_system` function or the :meth:`StateSpace.sample` and :meth:`TransferFunction.sample` methods
9898
can be used to create a discrete time system from a continuous time system.
9999
See :ref:`utility-and-conversions`. The default value of 'dt' can be changed by
@@ -179,6 +179,10 @@ can be computed like this::
179179

180180
ft = D * U
181181

182+
183+
.. currentmodule:: control
184+
.. _package-configuration-parameters:
185+
182186
Package configuration parameters
183187
================================
184188

@@ -207,25 +211,25 @@ on standard configurations.
207211
Selected variables that can be configured, along with their default values:
208212
209213
* bode.dB (False): Bode plot magnitude plotted in dB (otherwise powers of 10)
210-
214+
211215
* bode.deg (True): Bode plot phase plotted in degrees (otherwise radians)
212-
216+
213217
* bode.Hz (False): Bode plot frequency plotted in Hertz (otherwise rad/sec)
214-
218+
215219
* bode.grid (True): Include grids for magnitude and phase plots
216-
220+
217221
* freqplot.number_of_samples (None): Number of frequency points in Bode plots
218-
222+
219223
* freqplot.feature_periphery_decade (1.0): How many decades to include in the
220224
frequency range on both sides of features (poles, zeros).
221-
225+
222226
* statesp.use_numpy_matrix (True): set the return type for state space matrices to
223227
`numpy.matrix` (verus numpy.ndarray)
224228
225-
* statesp.default_dt and xferfcn.default_dt (None): set the default value of dt when
229+
* statesp.default_dt and xferfcn.default_dt (None): set the default value of dt when
226230
constructing new LTI systems
227231
228-
* statesp.remove_useless_states (True): remove states that have no effect on the
232+
* statesp.remove_useless_states (True): remove states that have no effect on the
229233
input-output dynamics of the system
230234
231235
Additional parameter variables are documented in individual functions

0 commit comments

Comments
 (0)
0