# Library conventions¶

The python-control library uses a set of standard conventions for the way that different types of standard information used by the library.

## LTI system representation¶

Linear time invariant (LTI) systems are represented in python-control in state space, transfer function, or frequency response data (FRD) form. Most functions in the toolbox will operate on any of these data types and functions for converting between compatible types is provided.

### State space systems¶

The `StateSpace`

class is used to represent state-space realizations
of linear time-invariant (LTI) systems:

where u is the input, y is the output, and x is the state.

To create a state space system, use the `StateSpace`

constructor:

sys = StateSpace(A, B, C, D)

State space systems can be manipulated using standard arithmetic operations
as well as the `feedback()`

, `parallel()`

, and `series()`

function. A full list of functions can be found in Function reference.

### Transfer functions¶

The `TransferFunction`

class is used to represent input/output
transfer functions

where n is generally greater than or equal to m (for a proper transfer function).

To create a transfer function, use the `TransferFunction`

constructor:

sys = TransferFunction(num, den)

Transfer functions can be manipulated using standard arithmetic operations
as well as the `feedback()`

, `parallel()`

, and `series()`

function. A full list of functions can be found in Function reference.

### FRD (frequency response data) systems¶

The `FrequencyResponseData`

(FRD) class is used to represent systems in
frequency response data form.

The main data members are omega and fresp, where omega is a 1D array with the frequency points of the response, and fresp is a 3D array, with the first dimension corresponding to the output index of the FRD, the second dimension corresponding to the input index, and the 3rd dimension corresponding to the frequency points in omega.

FRD systems have a somewhat more limited set of functions that are available, although all of the standard algebraic manipulations can be performed.

### Discrete time systems¶

A discrete time system is created by specifying a nonzero ‘timebase’, dt. The timebase argument can be given when a system is constructed:

- dt = None: no timebase specified (default)
- dt = 0: continuous time system
- dt > 0: discrete time system with sampling period ‘dt’
- dt = True: discrete time with unspecified sampling period

Only the `StateSpace`

, `TransferFunction`

, and
`InputOutputSystem`

classes allow explicit representation of
discrete time systems.

Systems must have compatible timebases in order to be combined. A system
with timebase None can be combined with a system having a specified
timebase; the result will have the timebase of the latter system.
Similarly, a discrete time system with unspecified sampling time (dt =
True) can be combined with a system having a specified sampling time;
the result will be a discrete time system with the sample time of the latter
system. For continuous time systems, the `sample_system()`

function or
the `StateSpace.sample()`

and `TransferFunction.sample()`

methods
can be used to create a discrete time system from a continuous time system.
See Utility functions and conversions.

## Input/output systems¶

The `iosys`

module contains the
`InputOutputSystem`

class that represents (possibly nonlinear)
input/output systems. The `InputOutputSystem`

class is a
general class that defines any continuous or discrete time dynamical system.
Input/output systems can be simulated and also used to compute equilibrium
points and linearizations.

An input/output system is defined as a dynamical system that has a system
state as well as inputs and outputs (either inputs or states can be empty).
The dynamics of the system can be in continuous or discrete time. To simulate
an input/output system, use the `input_output_response()`

function:

```
t, y = input_output_response(io_sys, T, U, X0, params)
```

An input/output system can be linearized around an equilibrium point to obtain
a `StateSpace`

linear system. Use the
`find_eqpts()`

function to obtain an equilibrium point and the
`linearize()`

function to linearize about that equilibrium point:

```
xeq, ueq = find_eqpt(io_sys, X0, U0)
ss_sys = linearize(io_sys, xeq, ueq)
```

Input/output systems can be created from state space LTI systems by using the
`LinearIOSystem`

class`:

```
io_sys = LinearIOSystem(ss_sys)
```

Nonlinear input/output systems can be created using the
`NonlinearIoSystem`

class, which requires the definition of an
update function (for the right hand side of the differential or different
equation) and and output function (computes the outputs from the state):

```
io_sys = NonlinearIOSystem(updfcn, outfcn, inputs=M, outputs=P, states=N)
```

More complex input/output systems can be constructed by using the
`InterconnectedSystem`

class, which allows a collection of
input/output subsystems to be combined with internal connections between the
subsystems and a set of overall system inputs and outputs that link to the
subsystems:

```
steering = ct.InterconnectedSystem(
(plant, controller), name='system',
connections=(('controller.e', '-plant.y')),
inplist=('controller.e'), inputs='r',
outlist=('plant.y'), outputs='y')
```

Interconnected systems can also be created using block diagram manipulations
such as the `series()`

, `parallel()`

, and
`feedback()`

functions. The `InputOutputSystem`

class also supports various algebraic operations such as * (series
interconnection) and + (parallel interconnection).

## Time series data¶

A variety of functions in the library return time series data: sequences of
values that change over time. A common set of conventions is used for
returning such data: columns represent different points in time, rows are
different components (e.g., inputs, outputs or states). For return
arguments, an array of times is given as the first returned argument,
followed by one or more arrays of variable values. This convention is used
throughout the library, for example in the functions
`forced_response()`

, `step_response()`

, `impulse_response()`

,
and `initial_response()`

.

Note

The convention used by python-control is different from the convention used in the scipy.signal library. In Scipy’s convention the meaning of rows and columns is interchanged. Thus, all 2D values must be transposed when they are used with functions from scipy.signal.

Types:

Argumentscan bearrays,matrices, ornested lists.Return valuesarearrays(not matrices).

The time vector is either 1D, or 2D with shape (1, n):

```
T = [[t1, t2, t3, ..., tn ]]
```

Input, state, and output all follow the same convention. Columns are different points in time, rows are different components. When there is only one row, a 1D object is accepted or returned, which adds convenience for SISO systems:

```
U = [[u1(t1), u1(t2), u1(t3), ..., u1(tn)]
[u2(t1), u2(t2), u2(t3), ..., u2(tn)]
...
...
[ui(t1), ui(t2), ui(t3), ..., ui(tn)]]
Same for X, Y
```

So, U[:,2] is the system’s input at the third point in time; and U[1] or U[1,:] is the sequence of values for the system’s second input.

The initial conditions are either 1D, or 2D with shape (j, 1):

```
X0 = [[x1]
[x2]
...
...
[xj]]
```

As all simulation functions return *arrays*, plotting is convenient:

```
t, y = step_response(sys)
plot(t, y)
```

The output of a MIMO system can be plotted like this:

```
t, y, x = forced_response(sys, u, t)
plot(t, y[0], label='y_0')
plot(t, y[1], label='y_1')
```

The convention also works well with the state space form of linear systems. If
`D`

is the feedthrough *matrix* of a linear system, and `U`

is its input
(*matrix* or *array*), then the feedthrough part of the system’s response,
can be computed like this:

```
ft = D * U
```

## Package configuration parameters¶

The python-control library can be customized to allow for different default values for selected parameters. This includes the ability to set the style for various types of plots and establishing the underlying representation for state space matrices.

To set the default value of a configuration variable, set the appropriate element of the control.config.defaults dictionary:

```
control.config.defaults['module.parameter'] = value
```

The ~control.config.set_defaults function can also be used to set multiple configuration parameters at the same time:

```
control.config.set_defaults('module', param1=val1, param2=val2, ...]
```

Finally, there are also functions available set collections of variables based on standard configurations.

Selected variables that can be configured, along with their default values:

- bode.dB (False): Bode plot magnitude plotted in dB (otherwise powers of 10)
- bode.deg (True): Bode plot phase plotted in degrees (otherwise radians)
- bode.Hz (False): Bode plot frequency plotted in Hertz (otherwise rad/sec)
- bode.grid (True): Include grids for magnitude and phase plots
- freqplot.number_of_samples (None): Number of frequency points in Bode plots
- freqplot.feature_periphery_decade (1.0): How many decades to include in the frequency range on both sides of features (poles, zeros).
- statesp.use_numpy_matrix: set the return type for state space matrices to numpy.matrix (verus numpy.ndarray)

Additional parameter variables are documented in individual functions

Functions that can be used to set standard configurations:

`reset_defaults` () |
Reset configuration values to their default (initial) values. |

`use_fbs_defaults` () |
Use Feedback Systems (FBS) compatible settings. |

`use_matlab_defaults` () |
Use MATLAB compatible configuration settings. |

`use_numpy_matrix` ([flag, warn]) |
Turn on/off use of Numpy matrix class for state space operations. |