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]

A class for returning time responses.

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 properties time, 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 the squeeze keyword.

t

Time values of the input/output response(s). This attribute is normally accessed via the time property.

Type

1D array

y

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.

Type

2D or 3D array

x

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.

Type

2D or 3D array, or None

u

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.

Type

2D or 3D array, or None

squeeze

By default, if a system is single-input, single-output (SISO) then the outputs (and inputs) are returned as a 1D array (indexed by time) and if a system is multi-input or multi-output, then the outputs are returned as 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, the output is returned as a 2D or 3D array (indexed by the output [if multi-input], trace [if multi-trace] and time) even if the system is SISO. The default value can be set using config.defaults[‘control.squeeze_time_response’].

Type

bool, optional

transpose

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

Type

bool, optional

issiso

Set to True if the system generating the data is single-input, single-output. If passed as None (default), the input data will be used to set the value.

Type

bool, optional

ninputs, noutputs, nstates

Number of inputs, outputs, and states of the underlying system.

Type

int

input_labels, output_labels, state_labels

Names for the input, output, and state variables.

Type

array of str

success

If False, result may not be valid (see input_output_response()). Defaults to True.

Type

bool, optional

message

Informational message if success is False.

Type

str, optional

sysname

Name of the system that created the data.

Type

str, optional

params

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

Type

dict, optional

plot_inputs

Whether or not to plot the inputs by default (can be overridden in the plot() method)

Type

bool, optional

ntraces

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 surpressed in the data.

Type

int, optional

title

Set the title to use when plotting.

Type

str, optional

trace_labels

Labels to use for traces (set to sysname it ntraces is 0)

Type

array of string, optional

trace_types

Type of trace. Currently only ‘step’ is supported, which controls the way in which the signal is plotted.

Type

array of string, optional

Notes

  1. 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)

    When using this (legacy) interface, the state vector is not affected by the squeeze parameter.

  2. For backward compatibility with earlier version of python-control, this 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.

  3. The default settings for return_x, squeeze and transpose can be changed by calling the class instance and passing new values:

    response(tranpose=True).input

    See TimeResponseData.__call__() for more information.

__init__(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]

Create an input/output time response object.

Parameters

  • time (1D array) – Time values of the output. Ignored if None.

  • outputs (ndarray) – 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).

  • states (array, 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.

  • inputs (array, 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.

  • title (str, optonal) – Title of the data set (used as figure title in plotting).

  • squeeze (bool, 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 using config.defaults[‘control.squeeze_time_response’].

  • input_labels (array of str, optional) – Optional labels for the inputs, outputs, and states, given as a list of strings matching the appropriate signal dimension.

  • output_labels (array of str, optional) – Optional labels for the inputs, outputs, and states, given as a list of strings matching the appropriate signal dimension.

  • state_labels (array of str, optional) – Optional labels for the inputs, outputs, and states, given as a list of strings matching the appropriate signal dimension.

  • sysname (str, optional) – Name of the system that created the data.

  • transpose (bool, optional) – If True, transpose all input and output arrays (for backward compatibility with MATLAB and scipy.signal.lsim()). Default value is False.

  • return_x (bool, optional) – If True, return the state vector when enumerating result by assigning to a tuple (default = False).

  • plot_inputs (bool, optional) – Whether or not to plot the inputs by default (can be overridden in the plot() method)

  • multi_trace (bool, 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.

  • success (bool, optional) – If False, result may not be valid (see input_output_response()).

  • message (str, optional) – Informational message if success is False.

Methods

__init__(time, outputs[, states, inputs, ...])

Create an input/output time response object.

plot(*args, **kwargs)

Plot the time response data objects.

to_pandas()

Convert response data to pandas data frame.

Attributes

inputs

Time response input vector.

outputs

Time response output vector.

states

Time response state vector.

time

Time vector.
property inputs

Time response input vector.

Input(s) to the system, indexed by input (optiona), 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.

See TimeResponseData.squeeze for a description of how the dimensions of the input vector can be modified using the squeeze 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 the squeeze keyword.

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.

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 the squeeze keyword.

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.