control.forced_response

control.forced_response(sysdata, timepts=None, inputs=0.0, initial_state=0.0, transpose=False, params=None, interpolate=False, return_states=None, squeeze=None, **kwargs)

Compute the output of a linear system given the input.

As a convenience for parameters U, X0: Numbers (scalars) are converted to constant arrays with the correct shape. The correct shape is inferred from arguments sys and T.

For information on the shape of parameters U, T, X0 and return values T, yout, xout, see Time series data conventions.

Parameters

sysdataI/O system or list of I/O systems

I/O system(s) for which forced response is computed.

timepts (or T)array_like, optional for discrete LTI sys

Time steps at which the input is defined; values must be evenly spaced. If None, inputs must be given and len(inputs) time steps of sys.dt are simulated. If sys.dt is None or True (undetermined time step), a time step of 1.0 is assumed.

inputs (or U)array_like or float, optional

Input array giving input at each time in timepts. If inputs is None or 0, timepts must be given, even for discrete-time systems. In this case, for continuous-time systems, a direct calculation of the matrix exponential is used, which is faster than the general interpolating algorithm used otherwise.

initial_state (or X0)array_like or float, default=0.

Initial condition.

paramsdict, optional

If system is a nonlinear I/O system, set parameter values.

transposebool, default=False

If True, transpose all input and output arrays (for backward compatibility with MATLAB and scipy.signal.lsim).

interpolatebool, default=False

If True and system is a discrete-time system, the input will be interpolated between the given time steps and the output will be given at system sampling rate. Otherwise, only return the output at the times given in T. No effect on continuous time simulations.

return_states (or return_x)bool, default=None

Used if the time response data is assigned to a tuple. If False, return only the time and output vectors. If True, also return the the state vector. If None, determine the returned variables by config.defaults['forced_response.return_x'], which was True before version 0.9 and is False since then.

squeezebool, optional

By default, if a system is single-input, single-output (SISO) then the output response is returned as a 1D array (indexed by time). If squeeze is True, remove single-dimensional entries from the shape of the output even if the system is not SISO. If squeeze is False, keep the output as a 2D array (indexed by the output number and time) even if the system is SISO. The default behavior can be overridden by config.defaults['control.squeeze_time_response'].

Returns

respTimeResponseData or TimeResponseList

Input/output response data object. When accessed as a tuple, returns (time, outputs) (default) or (time, outputs, states) if return_x is True. The plot method can be used to create a plot of the time response(s) (see time_response_plot for more information). If sysdata is a list of systems, a TimeResponseList object is returned, which acts as a list of TimeResponseData objects with a plot method that will plot responses as multiple traces. See time_response_plot for additional information.

resp.timearray

Time values of the output.

resp.outputsarray

Response of the system. If the system is SISO and squeeze is not True, the array is 1D (indexed by time). If the system is not SISO or squeeze is False, the array is 2D (indexed by output and time).

resp.statesarray

Time evolution of the state vector, represented as a 2D array indexed by state and time.

resp.inputsarray

Input(s) to the system, indexed by input and time.

See also

impulse_response, initial_response, input_output_response, step_response, time_response_plot

Notes

For discrete-time systems, the input/output response is computed using the scipy.signal.dlsim function.

For continuous-time systems, the output is computed using the matrix exponential exp(A t) and assuming linear interpolation of the inputs between time points.

If a nonlinear I/O system is passed to forced_response, the input_output_response function is called instead. The main difference between input_output_response and forced_response is that forced_response is specialized (and optimized) for linear systems.

(legacy) The return value of the system can also be accessed by assigning the function to a tuple of length 2 (time, output) or of length 3 (time, output, state) if return_x is True.

Examples

>>> G = ct.rss(4)
>>> timepts = np.linspace(0, 10)
>>> inputs = np.sin(timepts)
>>> tout, yout = ct.forced_response(G, timepts, inputs)

See Time series data conventions and Package Configuration Parameters.