control.TimeResponseData
- class control.TimeResponseData(time, outputs, states=None, inputs=None, issiso=None, output_labels=None, state_labels=None, input_labels=None, title=None, transpose=False, return_x=False, squeeze=None, multi_trace=False, trace_labels=None, trace_types=None, plot_inputs=True, sysname=None, params=None, success=True, message=None)[source]
Bases:
object
Input/output system time response data.
This class maintains and manipulates the data corresponding to the temporal response of an input/output system. It is used as the return type for time domain simulations (
step_response
,input_output_response
, etc).A time response consists of a time vector, an output vector, and optionally an input vector and/or state vector. Inputs and outputs can be 1D (scalar input/output) or 2D (vector input/output).
A time response can be stored for multiple input signals (called traces), with the output and state indexed by the trace number. This allows for input/output response matrices, which is mainly useful for impulse and step responses for linear systems. For multi-trace responses, the same time vector must be used for all traces.
Time responses are accessed through either the raw data, stored as
t
,y
,x
,u
, or using a set of propertiestime
,outputs
,states
,inputs
. When accessing time responses via their properties, squeeze processing is applied so that (by default) single-input, single-output systems will have the output and input indices suppressed. This behavior is set using thesqueeze
parameter.- Parameters
- time1D array
Time values of the output. Ignored if None.
- outputsndarray
Output response of the system. This can either be a 1D array indexed by time (for SISO systems or MISO systems with a specified input), a 2D array indexed by output and time (for MIMO systems with no input indexing, such as initial_response or forced response) or trace and time (for SISO systems with multiple traces), or a 3D array indexed by output, trace, and time (for multi-trace input/output responses).
- statesarray, optional
Individual response of each state variable. This should be a 2D array indexed by the state index and time (for single trace systems) or a 3D array indexed by state, trace, and time.
- inputsarray, optional
Inputs used to generate the output. This can either be a 1D array indexed by time (for SISO systems or MISO/MIMO systems with a specified input), a 2D array indexed either by input and time (for a multi-input system) or trace and time (for a single-input, multi-trace response), or a 3D array indexed by input, trace, and time.
- titlestr, optional
Title of the data set (used as figure title in plotting).
- squeezebool, optional
By default, if a system is single-input, single-output (SISO) then the inputs and outputs are returned as a 1D array (indexed by time) and if a system is multi-input or multi-output, then the inputs are returned as a 2D array (indexed by input and time) and the outputs are returned as either a 2D array (indexed by output and time) or a 3D array (indexed by output, trace, and time). If
squeeze
= True, access to the output response will remove single-dimensional entries from the shape of the inputs and outputs even if the system is not SISO. If squeeze=False, keep the input as a 2D or 3D array (indexed by the input (if multi-input), trace (if single input) and time) and the output as a 3D array (indexed by the output, trace, and time) even if the system is SISO. The default value can be set usingconfig.defaults['control.squeeze_time_response']
.
- Other Parameters
- input_labels, output_labels, state_labelsarray of str, optional
Optional labels for the inputs, outputs, and states, given as a list of strings matching the appropriate signal dimension.
- sysnamestr, optional
Name of the system that created the data.
- transposebool, optional
If True, transpose all input and output arrays (for backward compatibility with MATLAB and
scipy.signal.lsim
). Default value is False.- return_xbool, optional
If True, return the state vector when enumerating result by assigning to a tuple (default = False).
- plot_inputsbool, optional
Whether or not to plot the inputs by default (can be overridden in the
plot
method).- multi_tracebool, optional
If True, then 2D input array represents multiple traces. For a MIMO system, the
input
attribute should then be set to indicate which trace is being specified. Default is False.- successbool, optional
If False, result may not be valid (see
input_output_response
).- messagestr, optional
Informational message if
success
is False.
See also
Notes
The responses for individual elements of the time response can be accessed using integers, slices, or lists of signal offsets or the names of the appropriate signals:
sys = ct.rss(4, 2, 1) resp = ct.initial_response(sys, initial_state=[1, 1, 1, 1]) plt.plot(resp.time, resp.outputs['y[0]'])
In the case of multi-trace data, the responses should be indexed using the output signal name (or offset) and the input signal name (or offset):
sys = ct.rss(4, 2, 2, strictly_proper=True) resp = ct.step_response(sys) plt.plot(resp.time, resp.outputs[['y[0]', 'y[1]'], 'u[0]'].T)
For backward compatibility with earlier versions of python-control, this class has an
__iter__
method that allows it to be assigned to a tuple with a variable number of elements. This allows the following patterns to work:t, y = step_response(sys) t, y, x = step_response(sys, return_x=True)
Similarly, the class has
__getitem__
and__len__
methods that allow the return value to be indexed:response[0]: returns the time vector
response[1]: returns the output vector
response[2]: returns the state vector
When using this (legacy) interface, the state vector is not affected by the
squeeze
parameter.The default settings for
return_x
,squeeze
andtranspose
can be changed by calling the class instance and passing new values:response(transpose=True).input
See
TimeResponseData.__call__
for more information.- Attributes
- t1D array
Time values of the input/output response(s). This attribute is normally accessed via the
time
property.- y2D or 3D array
Output response data, indexed either by output index and time (for single trace responses) or output, trace, and time (for multi-trace responses). These data are normally accessed via the
outputs
property, which performs squeeze processing.- x2D or 3D array, or None
State space data, indexed either by output number and time (for single trace responses) or output, trace, and time (for multi-trace responses). If no state data are present, value is None. These data are normally accessed via the
states
property, which performs squeeze processing.- u2D or 3D array, or None
Input signal data, indexed either by input index and time (for single trace responses) or input, trace, and time (for multi-trace responses). If no input data are present, value is None. These data are normally accessed via the
inputs
property, which performs squeeze processing.- issisobool, optional
Set to True if the system generating the data is single-input, single-output. If passed as None (default), the input and output data will be used to set the value.
- ninputs, noutputs, nstatesint
Number of inputs, outputs, and states of the underlying system.
- paramsdict, optional
If system is a nonlinear I/O system, set parameter values.
- ntracesint, optional
Number of independent traces represented in the input/output response. If
ntraces
is 0 (default) then the data represents a single trace with the trace index suppressed in the data.- trace_labelsarray of string, optional
Labels to use for traces (set to sysname it
ntraces
is 0).- trace_typesarray of string, optional
Type of trace. Currently only ‘step’ is supported, which controls the way in which the signal is plotted.
Attributes
Time response input vector.
Time response output vector.
Squeeze processing parameter.
Time response state vector.
Time vector.
Methods
Change value of processing keywords.
Plot the time response data objects.
Convert response data to pandas data frame.
- __call__(**kwargs)[source]
Change value of processing keywords.
Calling the time response object will create a copy of the object and change the values of the keywords used to control the
outputs
,states
, andinputs
properties.- Parameters
- squeezebool, optional
If
squeeze
= True, access to the output response will remove single-dimensional entries from the shape of the inputs, outputs, and states even if the system is not SISO. Ifsqueeze
= False, keep the input as a 2D or 3D array (indexed by the input (if multi-input), trace (if single input) and time) and the output and states as a 3D array (indexed by the output/state, trace, and time) even if the system is SISO.- transposebool, optional
If True, transpose all input and output arrays (for backward compatibility with MATLAB and
scipy.signal.lsim
). Default value is False.- return_xbool, optional
If True, return the state vector when enumerating result by assigning to a tuple (default = False).
- input_labels, output_labels, state_labels: array of str
Labels for the inputs, outputs, and states, given as a list of strings matching the appropriate signal dimension.
- property inputs
Time response input vector.
Input(s) to the system, indexed by input (optional), trace (optional), and time. If a 1D vector is passed, the input corresponds to a scalar-valued input. If a 2D vector is passed, then it can either represent multiple single-input traces or a single multi-input trace. The optional
multi_trace
keyword should be used to disambiguate the two. If a 3D vector is passed, then it represents a multi-trace, multi-input signal, indexed by input, trace, and time.Input and output signal names can be used to index the data in place of integer offsets, with the input signal names being used to access multi-input data.
See
TimeResponseData.squeeze
for a description of how the dimensions of the input vector can be modified using thesqueeze
keyword.- Type
1D or 2D array
- property outputs
Time response output vector.
Output response of the system, indexed by either the output and time (if only a single input is given) or the output, trace, and time (for multiple traces). See
TimeResponseData.squeeze
for a description of how this can be modified using thesqueeze
keyword.Input and output signal names can be used to index the data in place of integer offsets, with the input signal names being used to access multi-input data.
- Type
1D, 2D, or 3D array
- plot(*args, **kwargs)[source]
Plot the time response data objects.
This method calls
time_response_plot
, passing all arguments and keywords. Seetime_response_plot
for details.
- squeeze
Squeeze processing parameter.
By default, if a system is single-input, single-output (SISO) then the inputs and outputs are returned as a 1D array (indexed by time) and if a system is multi-input or multi-output, then the inputs are returned as a 2D array (indexed by input and time) and the outputs are returned as either a 2D array (indexed by output and time) or a 3D array (indexed by output, trace, and time). If squeeze=True, access to the output response will remove single-dimensional entries from the shape of the inputs and outputs even if the system is not SISO. If squeeze=False, keep the input as a 2D or 3D array (indexed by the input (if multi-input), trace (if single input) and time) and the output as a 3D array (indexed by the output, trace, and time) even if the system is SISO. The default value can be set using config.defaults[‘control.squeeze_time_response’].
- property states
Time response state vector.
Time evolution of the state vector, indexed indexed by either the state and time (if only a single trace is given) or the state, trace, and time (for multiple traces). See
TimeResponseData.squeeze
for a description of how this can be modified using thesqueeze
keyword.Input and output signal names can be used to index the data in place of integer offsets, with the input signal names being used to access multi-input data.
- Type
2D or 3D array
- property time
Time vector.
Time values of the input/output response(s).
- Type
1D array
- to_pandas()[source]
Convert response data to pandas data frame.
Creates a pandas data frame using the input, output, and state labels for the time response. The column labels are given by the input and output (and state, when present) labels, with time labeled by ‘time’ and traces (for multi-trace responses) labeled by ‘trace’.