Python Control Readthedocs Io en Latest

Python Control Library Documentation
Release dev
RMM
May 17, 2020

Contents
1 Introduction 3
1.1 Overview of the toolbox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.2 Some differences from MATLAB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.3 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.4 Getting started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2 Library conventions 5
2.1 LTI system representation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.2 Time series data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.3 Package configuration parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
3 Function reference 11
3.1 System creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
3.2 System interconnections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
3.3 Frequency domain plotting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
3.4 Time domain simulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
3.5 Block diagram algebra . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
3.6 Control system analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
3.7 Matrix computations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
3.8 Control system synthesis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
3.9 Model simplification tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
3.10 Nonlinear system support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
3.11 Utility functions and conversions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
4 Control system classes 57

4.1 control.TransferFunction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
4.2 control.StateSpace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
4.3 control.FrequencyResponseData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
4.4 control.iosys.InputOutputSystem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
4.5 Input/output system subclasses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
5 MATLAB compatibility module 81

5.1 Creating linear models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
5.2 Utility functions and conversions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
5.3 System interconnections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
5.4 System gain and dynamics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
5.5 Time-domain analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
i
5.6 Frequency-domain analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
5.7 Compensator design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
5.8 State-space (SS) models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
5.9 Model simplification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
5.10 Time delays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
5.11 Matrix equation solvers and linear algebra . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
5.12 Additional functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
5.13 Functions imported from other modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
6 Differentially flat systems 113

6.1 Overview of differential flatness . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
6.2 Module usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
6.3 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
6.4 Module classes and functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
7 Input/output systems 129

7.1 Module usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
7.2 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
7.3 Module classes and functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
8 Examples 133
8.1 Python scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
8.2 Jupyter notebooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
Python Module Index 211
Index 213
ii
Python Control Library Documentation, Release dev
The Python Control Systems Library (python-control) is a Python package that implements basic operations for anal-
ysis and design of feedback control systems.
Features
• Linear input/output systems in state-space and frequency domain

• Block diagram algebra: serial, parallel, and feedback interconnections
• Time response: initial, step, impulse
• Frequency response: Bode and Nyquist plots
• Control analysis: stability, reachability, observability, stability margins
• Control design: eigenvalue placement, LQR, H2, Hinf
• Model reduction: balanced realizations, Hankel singular values
• Estimator design: linear quadratic estimator (Kalman filter)
Documentation
Contents 1
2 Contents
CHAPTER 1
Introduction
Welcome to the Python Control Systems Toolbox (python-control) User’s Manual. This manual contains informa-
tion on using the python-control package, including documentation for all functions in the package and examples
illustrating their use.
1.1 Overview of the toolbox
The python-control package is a set of python classes and functions that implement common operations for the analysis
and design of feedback control systems. The initial goal is to implement all of the functionality required to work
through the examples in the textbook Feedback Systems by Astrom and Murray. A MATLAB compatibility module is
available that provides many of the common functions corresponding to commands available in the MATLAB Control
Systems Toolbox.
1.2 Some differences from MATLAB
The python-control package makes use of NumPy and SciPy. A list of general differences between NumPy and
MATLAB can be found here.
In terms of the python-control package more specifically, here are some thing to keep in mind:
• You must include commas in vectors. So [1 2 3] must be [1, 2, 3].
• Functions that return multiple arguments use tuples.
• You cannot use braces for collections; use tuples instead.
1.3 Installation
The python-control package can be installed using pip, conda or the standard distutils/setuptools mechanisms. The
package requires numpy and scipy, and the plotting routines require matplotlib. In addition, some routines require the
3
slycot library in order to implement more advanced features (including some MIMO functionality).
To install using pip:
pip install slycot # optional

pip install control
Many parts of python-control will work without slycot, but some functionality is limited or absent, and installation of
slycot is recommended.
Note: the slycot library only works on some platforms, mostly linux-based. Users should check to insure that slycot is
installed correctly by running the command:
python -c "import slycot"
and verifying that no error message appears. It may be necessary to install slycot from source, which requires a
working FORTRAN compiler and either the lapack or openplas library. More information on the slycot package can
be obtained from the slycot project page.
For users with the Anaconda distribution of Python, the following commands can be used:
conda install numpy scipy matplotlib # if not yet installed

conda install -c conda-forge control
This installs slycot and python-control from conda-forge, including the openblas package.
Alternatively, to use setuptools, first download the source and unpack it. To install in your home directory, use:
python setup.py install --user
or to install for all users (on Linux or Mac OS):
python setup.py build

sudo python setup.py install
1.4 Getting started
There are two different ways to use the package. For the default interface described in Function reference, simply
import the control package as follows:
>>> import control
If you want to have a MATLAB-like environment, use the MATLAB compatibility module:
>>> from control.matlab import *
4 Chapter 1. Introduction
CHAPTER 2
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.
2.1 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.
2.1.1 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.
2.1.2 Transfer functions
The TransferFunction class is used to represent input/output transfer functions

num(𝑠) 𝑎0 𝑠𝑚 + 𝑎1 𝑠𝑚−1 + · · · + 𝑎𝑚
𝐺(𝑠) = = ,
den(𝑠) 𝑏0 𝑠𝑛 + 𝑏1 𝑠𝑛−1 + · · · + 𝑏𝑛
5
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.
2.1.3 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.
2.1.4 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.
2.1.5 Conversion between representations
LTI systems can be converted between representations either by calling the constructor for the desired data type using
the original system as the sole argument or using the explicit conversion functions ss2tf() and tf2ss().
2.2 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().
6 Chapter 2. Library conventions

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:
• Arguments can be arrays, matrices, or nested lists.
• Return values are arrays (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
2.2. Time series data 7

2.3 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) val-

ues.
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.
2.3.1 control.reset_defaults
control.reset_defaults()
Reset configuration values to their default (initial) values.
2.3.2 control.use_fbs_defaults
control.use_fbs_defaults()
Use Feedback Systems (FBS) compatible settings.
The following conventions are used:
• Bode plots plot gain in powers of ten, phase in degrees, frequency in rad/sec, no grid

2.3.3 control.use_matlab_defaults
control.use_matlab_defaults()
Use MATLAB compatible configuration settings.
The following conventions are used:
• Bode plots plot gain in dB, phase in degrees, frequency in rad/sec, with grids
• State space class and functions use Numpy matrix objects
2.3.4 control.use_numpy_matrix
control.use_numpy_matrix(flag=True, warn=True)
Turn on/off use of Numpy matrix class for state space operations.
Parameters
• flag (bool) – If flag is True (default), use the Numpy (soon to be deprecated) matrix
class to represent matrices in the ~control.StateSpace class and functions. If flat is False,
then matrices are represented by a 2D ndarray object.
• warn (bool) – If flag is True (default), issue a warning when turning on the use of the
Numpy matrix class. Set warn to false to omit display of the warning message.
2.3. Package configuration parameters 9


CHAPTER 3
Function reference
The Python Control Systems Library control provides common functions for analyzing and designing feedback
control systems.
3.1 System creation
ss(A, B, C, D[, dt]) Create a state space system.

tf(num, den[, dt]) Create a transfer function system.
frd(d, w) Construct a frequency response data model
rss([states, outputs, inputs]) Create a stable continuous random state space object.
drss([states, outputs, inputs]) Create a stable discrete random state space object.
3.1.1 control.ss
control.ss(A, B, C, D[, dt ])
Create a state space system.
The function accepts either 1, 4 or 5 parameters:
ss(sys) Convert a linear system into space system form. Always creates a new system, even if sys is already
a StateSpace object.
ss(A, B, C, D) Create a state space system from the matrices of its state and output equations:
𝑥˙ = 𝐴 · 𝑥 + 𝐵 · 𝑢
𝑦 =𝐶 ·𝑥+𝐷·𝑢
ss(A, B, C, D, dt) Create a discrete-time state space system from the matrices of its state and output
equations:
𝑥[𝑘 + 1] = 𝐴 · 𝑥[𝑘] + 𝐵 · 𝑢[𝑘]
𝑦[𝑘] = 𝐶 · 𝑥[𝑘] + 𝐷 · 𝑢[𝑘𝑖]
11
The matrices can be given as array like data types or strings. Everything that the constructor of numpy.
matrix accepts is permissible here too.
Parameters
• sys (StateSpace or TransferFunction) – A linear system
• A (array_like or string) – System matrix
• B (array_like or string) – Control matrix
• C (array_like or string) – Output matrix
• D (array_like or string) – Feed forward matrix
• dt (If present, specifies the sampling period and a discrete
time) – system is created
Returns out – The new linear system
Return type StateSpace
Raises ValueError – if matrix sizes are not self-consistent
See also:
StateSpace(), tf(), ss2tf(), tf2ss()
Examples
>>> # Create a StateSpace object from four "matrices".

>>> sys1 = ss("1. -2; 3. -4", "5.; 7", "6. 8", "9.")
>>> # Convert a TransferFunction to a StateSpace object.

>>> sys_tf = tf([2.], [1., 3])
>>> sys2 = ss(sys_tf)
3.1.2 control.tf
control.tf(num, den[, dt ])
Create a transfer function system. Can create MIMO systems.
The function accepts either 1, 2, or 3 parameters:
tf(sys) Convert a linear system into transfer function form. Always creates a new system, even if sys is
already a TransferFunction object.
tf(num, den) Create a transfer function system from its numerator and denominator polynomial coeffi-
cients.
If num and den are 1D array_like objects, the function creates a SISO system.
To create a MIMO system, num and den need to be 2D nested lists of array_like objects. (A 3 dimensional
data structure in total.) (For details see note below.)
tf(num, den, dt) Create a discrete time transfer function system; dt can either be a positive number
indicating the sampling time or ‘True’ if no specific timebase is given.
tf('s') or tf('z') Create a transfer function representing the differential operator (‘s’) or delay operator
(‘z’).
12 Chapter 3. Function reference

Parameters
• sys (LTI (StateSpace or TransferFunction)) – A linear system
• num (array_like, or list of list of array_like) – Polynomial coeffi-
cients of the numerator
• den (array_like, or list of list of array_like) – Polynomial coeffi-
cients of the denominator
Return type TransferFunction
Raises
• ValueError – if num and den have invalid or unequal dimensions
• TypeError – if num or den are of incorrect type
See also:
TransferFunction(), ss(), ss2tf(), tf2ss()
Notes
num[i][j] contains the polynomial coefficients of the numerator for the transfer function from the (j+1)st
input to the (i+1)st output. den[i][j] works the same way.
The list [2, 3, 4] denotes the polynomial 2𝑠2 + 3𝑠 + 4.
The special forms tf('s') and tf('z') can be used to create transfer functions for differentiation and unit
delays.
Examples
>>> # Create a MIMO transfer function object

>>> # The transfer function from the 2nd input to the 1st output is
>>> # (3s + 4) / (6s^2 + 5s + 4).
>>> num = [[[1., 2.], [3., 4.]], [[5., 6.], [7., 8.]]]
>>> den = [[[9., 8., 7.], [6., 5., 4.]], [[3., 2., 1.], [-1., -2., -3.]]]
>>> sys1 = tf(num, den)
>>> # Create a variable 's' to allow algebra operations for SISO systems
>>> s = tf('s')
>>> G = (s + 1)/(s**2 + 2*s + 1)
>>> # Convert a StateSpace to a TransferFunction object.

>>> sys_ss = ss("1. -2; 3. -4", "5.; 7", "6. 8", "9.")
>>> sys2 = tf(sys1)
3.1.3 control.frd
control.frd(d, w)
Construct a frequency response data model
frd models store the (measured) frequency response of a system.
3.1. System creation 13

This function can be called in different ways:

frd(response, freqs) Create an frd model with the given response data, in the form of complex re-
sponse vector, at matching frequency freqs [in rad/s]
frd(sys, freqs) Convert an LTI system into an frd model with data at frequencies freqs.
Parameters
• response (array_like, or list) – complex vector with the system response
• freq (array_lik or lis) – vector with frequencies
Returns sys – New frequency response system
Return type FRD
See also:
FRD(), ss(), tf()
3.1.4 control.rss
control.rss(states=1, outputs=1, inputs=1)

Create a stable continuous random state space object.
Parameters
• states (integer) – Number of state variables
• inputs (integer) – Number of system inputs
• outputs (integer) – Number of system outputs
Returns sys – The randomly created linear system
Raises ValueError – if any input is not a positive integer
See also:
drss()
Notes
If the number of states, inputs, or outputs is not specified, then the missing numbers are assumed to be 1. The
poles of the returned system will always have a negative real part.
3.1.5 control.drss
control.drss(states=1, outputs=1, inputs=1)

Create a stable discrete random state space object.
Parameters


See also:
rss()
Notes
poles of the returned system will always have a magnitude less than 1.
3.2 System interconnections
append(sys1, sys2, . . . , sysn) Group models by appending their inputs and outputs
connect(sys, Q, inputv, outputv) Index-based interconnection of an LTI system.
feedback(sys1[, sys2, sign]) Feedback interconnection between two I/O systems.
negate(sys) Return the negative of a system.
parallel(sys1, *sysn) Return the parallel connection sys1 + sys2 (+ . . .
series(sys1, *sysn) Return the series connection (sysn * . . .
3.2.1 control.append
control.append(sys1, sys2, ..., sysn)

Group models by appending their inputs and outputs
Forms an augmented system model, and appends the inputs and outputs together. The system type will be the
type of the first system given; if you mix state-space systems and gain matrices, make sure the gain matrices are
not first.
Parameters sys2, .., sysn (sys1,) – LTI systems to combine
Returns sys – Combined LTI system, with input/output vectors consisting of all input/output vectors
appended
Return type LTI system
Examples
>>> sys1 = ss([[1., -2], [3., -4]], [[5.], [7]]", [[6., 8]], [[9.]])
>>> sys2 = ss([[-1.]], [[1.]], [[1.]], [[0.]])
>>> sys = append(sys1, sys2)
3.2.2 control.connect
control.connect(sys, Q, inputv, outputv)

Index-based interconnection of an LTI system.
3.2. System interconnections 15

The system sys is a system typically constructed with append, with multiple inputs and outputs. The inputs
and outputs are connected according to the interconnection matrix Q, and then the final inputs and outputs are
trimmed according to the inputs and outputs listed in inputv and outputv.
NOTE: Inputs and outputs are indexed starting at 1 and negative values correspond to a negative feedback
interconnection.
Parameters
• sys (StateSpace Transferfunction) – System to be connected
• Q (2D array) – Interconnection matrix. First column gives the input to be connected
second column gives the output to be fed into this input. Negative values for the second
column mean the feedback is negative, 0 means no connection is made. Inputs and outputs
are indexed starting at 1.
• inputv (1D array) – list of final external inputs
• outputv (1D array) – list of final external outputs
Returns sys – Connected and trimmed LTI system
Examples
>>> sys1 = ss([[1., -2], [3., -4]], [[5.], [7]], [[6, 8]], [[9.]])
>>> sys2 = ss([[-1.]], [[1.]], [[1.]], [[0.]])
>>> Q = [[1, 2], [2, -1]] # negative feedback interconnection
>>> sysc = connect(sys, Q, [2], [1, 2])
3.2.3 control.feedback
control.feedback(sys1, sys2=1, sign=-1)

Feedback interconnection between two I/O systems.
Parameters
• sys1 (scalar, StateSpace, TransferFunction, FRD) – The primary pro-
cess.
• sys2 (scalar, StateSpace, TransferFunction, FRD) – The feedback pro-
cess (often a feedback controller).
• sign (scalar) – The sign of feedback. sign = -1 indicates negative feedback, and sign =
1 indicates positive feedback. sign is an optional argument; it assumes a value of -1 if not
specified.
Returns out
Return type StateSpace or TransferFunction
Raises
• ValueError – if sys1 does not have as many inputs as sys2 has outputs, or if sys2 does
not have as many inputs as sys1 has outputs
• NotImplementedError – if an attempt is made to perform a feedback on a MIMO
TransferFunction object

See also:
series(), parallel()
Notes
This function is a wrapper for the feedback function in the StateSpace and TransferFunction classes. It calls
TransferFunction.feedback if sys1 is a TransferFunction object, and StateSpace.feedback if sys1 is a StateSpace
object. If sys1 is a scalar, then it is converted to sys2’s type, and the corresponding feedback function is used. If
sys1 and sys2 are both scalars, then TransferFunction.feedback is used.
3.2.4 control.negate
control.negate(sys)
Return the negative of a system.
Parameters sys (StateSpace, TransferFunction or FRD) –
Returns out
Notes
This function is a wrapper for the __neg__ function in the StateSpace and TransferFunction classes. The output
type is the same as the input type.
Examples
>>> sys2 = negate(sys1) # Same as sys2 = -sys1.
3.2.5 control.parallel
control.parallel(sys1, *sysn)
Return the parallel connection sys1 + sys2 (+ . . . + sysn)
Parameters
• sys1 (scalar, StateSpace, TransferFunction, or FRD) –
• *sysn (other scalars, StateSpaces, TransferFunctions, or FRDs)
–
Returns out
Return type scalar, StateSpace, or TransferFunction
Raises ValueError – if sys1 and sys2 do not have the same numbers of inputs and outputs
See also:
series(), feedback()

Notes
This function is a wrapper for the __add__ function in the StateSpace and TransferFunction classes. The output
type is usually the type of sys1. If sys1 is a scalar, then the output type is the type of sys2.
If both systems have a defined timebase (dt = 0 for continuous time, dt > 0 for discrete time), then the timebase
for both systems must match. If only one of the system has a timebase, the return timebase will be set to match
it.
Examples
>>> sys3 = parallel(sys1, sys2) # Same as sys3 = sys1 + sys2
>>> sys5 = parallel(sys1, sys2, sys3, sys4) # More systems
3.2.6 control.series
control.series(sys1, *sysn)
Return the series connection (sysn * . . . *) sys2 * sys1
Parameters
–
Returns out
Raises ValueError – if sys2.inputs does not equal sys1.outputs if sys1.dt is not compatible with
sys2.dt
See also:
parallel(), feedback()
Notes
This function is a wrapper for the __mul__ function in the StateSpace and TransferFunction classes. The output
it.
Examples
>>> sys3 = series(sys1, sys2) # Same as sys3 = sys2 * sys1
>>> sys5 = series(sys1, sys2, sys3, sys4) # More systems
See also the Input/output systems module, which can be used to create and interconnect nonlinear input/output systems.

3.3 Frequency domain plotting
bode_plot(syslist[, omega, plot, . . . ]) Bode plot for a system

nyquist_plot(syslist[, omega, plot, . . . ]) Nyquist plot for a system
gangof4_plot(P, C[, omega]) Plot the “Gang of 4” transfer functions for a system
nichols_plot(sys_list[, omega, grid]) Nichols plot for a system
3.3.1 control.bode_plot
control.bode_plot(syslist, omega=None, plot=True, omega_limits=None, omega_num=None, mar-

gins=None, *args, **kwargs)
Bode plot for a system
Plots a Bode plot for the system over a (optional) frequency range.
Parameters
• syslist (linsys) – List of linear input/output systems (single system is OK)
• omega (list) – List of frequencies in rad/sec to be used for frequency response
• dB (bool) – If True, plot result in dB. Default is false.
• Hz (bool) – If True, plot frequency in Hz (omega must be provided in rad/sec). Default
value (False) set by config.defaults[‘bode.Hz’]
• deg (bool) – If True, plot phase in degrees (else radians). Default value (True) con-
fig.defaults[‘bode.deg’]
• plot (bool) – If True (default), plot magnitude and phase
• omega_limits (tuple, list, .. of two values) – Limits of the to generate
frequency vector. If Hz=True the limits are in Hz otherwise in rad/s.
• omega_num (int) – Number of samples to plot. Defaults to con-
fig.defaults[‘freqplot.number_of_samples’].
• margins (bool) – If True, plot gain and phase margin.
• *args (matplotlib plot positional properties, optional) – Additional arguments for mat-
plotlib plots (color, linestyle, etc)
• **kwargs (matplotlib plot keyword properties, optional) – Additional keywords (passed
to matplotlib)
Returns
• mag (array (list if len(syslist) > 1)) – magnitude
• phase (array (list if len(syslist) > 1)) – phase in radians
• omega (array (list if len(syslist) > 1)) – frequency in rad/sec
Other Parameters
• grid (bool) – If True, plot grid lines on gain and phase plots. Default is set by con-
fig.defaults[‘bode.grid’].
• The default values for Bode plot configuration parameters can be reset
• using the ‘config.defaults‘ dictionary, with module name ‘bode’.
3.3. Frequency domain plotting 19

Notes
1. Alternatively, you may use the lower-level method (mag, phase, freq) = sys.freqresp(freq) to generate the
frequency response for a system, but it returns a MIMO response.
2. If a discrete time model is given, the frequency response is plotted along the upper branch of the unit circle,
using the mapping z = exp(j omega dt) where omega ranges from 0 to pi/dt and dt is the discrete timebase. If
not timebase is specified (dt = True), dt is set to 1.
Examples
>>> sys = ss("1. -2; 3. -4", "5.; 7", "6. 8", "9.")
>>> mag, phase, omega = bode(sys)
3.3.2 control.nyquist_plot
control.nyquist_plot(syslist, omega=None, plot=True, label_freq=0, arrowhead_length=0.1, arrow-

head_width=0.1, color=None, *args, **kwargs)
Nyquist plot for a system
Plots a Nyquist plot for the system over a (optional) frequency range.
Parameters
• syslist (list of LTI) – List of linear input/output systems (single system is OK)
• omega (freq_range) – Range of frequencies (list or bounds) in rad/sec
• Plot (boolean) – If True, plot magnitude
• color (string) – Used to specify the color of the plot
• label_freq (int) – Label every nth frequency on the plot
• arrowhead_width (arrow head width) –
• arrowhead_length (arrow head length) –
to matplotlib)
Returns
• real (array) – real part of the frequency response array
• imag (array) – imaginary part of the frequency response array
• freq (array) – frequencies
Examples
>>> sys = ss("1. -2; 3. -4", "5.; 7", "6. 8", "9.")
>>> real, imag, freq = nyquist_plot(sys)

3.3.3 control.gangof4_plot
control.gangof4_plot(P, C, omega=None, **kwargs)

Plot the “Gang of 4” transfer functions for a system
Generates a 2x2 plot showing the “Gang of 4” sensitivity functions [T, PS; CS, S]
Parameters
• C (P,) – Linear input/output systems (process and control)
• omega (array) – Range of frequencies (list or bounds) in rad/sec
to matplotlib)
Returns
Return type None
3.3.4 control.nichols_plot
control.nichols_plot(sys_list, omega=None, grid=None)

Nichols plot for a system
Plots a Nichols plot for the system over a (optional) frequency range.
Parameters
• sys_list (list of LTI, or LTI) – List of linear input/output systems (single sys-
tem is OK)
• omega (array_like) – Range of frequencies (list or bounds) in rad/sec
• grid (boolean, optional) – True if the plot should include a Nichols-chart grid.
Default is True.
Returns
Return type None
Note: For plotting commands that create multiple axes on the same plot, the individual axes can be retrieved using the
axes label (retrieved using the get_label method for the matplotliib axes object). The following labels are currently
defined:
• Bode plots: control-bode-magnitude, control-bode-phase
• Gang of 4 plots: control-gangof4-s, control-gangof4-cs, control-gangof4-ps, control-gangof4-t
3.4 Time domain simulation
forced_response(sys[, T, U, X0, transpose, . . . ]) Simulate the output of a linear system.

impulse_response(sys[, T, X0, input, . . . ]) Impulse response of a linear system
initial_response(sys[, T, X0, input, . . . ]) Initial condition response of a linear system
input_output_response(sys, T[, U, X0, . . . ]) Compute the output response of a system to a given in-
put.
step_response(sys[, T, X0, input, output, . . . ]) Step response of a linear system
phase_plot(odefun[, X, Y, scale, X0, T, . . . ]) Phase plot for 2D dynamical systems
3.4. Time domain simulation 21

3.4.1 control.forced_response
control.forced_response(sys, T=None, U=0.0, X0=0.0, transpose=False, interpolate=False,

squeeze=True)
Simulate the output of a linear system.
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.
Parameters
• sys (LTI (StateSpace, or TransferFunction)) – LTI system to simulate
• T (array-like, optional for discrete LTI sys) – Time steps at which the input is defined; values
must be evenly spaced.
• U (array-like or number, optional) – Input array giving input at each time T
(default = 0).
If U is None or 0, a special algorithm is used. This special algorithm is faster than the
general algorithm, which is used otherwise.
• X0 (array-like or number, optional) – Initial condition (default = 0).
• transpose (bool, optional (default=False)) – If True, transpose all input
and output arrays (for backward compatibility with MATLAB and scipy.signal.lsim)
• interpolate (bool, optional (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 (default = False).
• squeeze (bool, optional (default=True)) – If True, remove single-
dimensional entries from the shape of the output. For single output systems, this converts
the output response to a 1D array.
Returns
• T (array) – Time values of the output.
• yout (array) – Response of the system.
• xout (array) – Time evolution of the state vector.
See also:
step_response(), initial_response(), impulse_response()
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.
Examples
>>> T, yout, xout = forced_response(sys, T, u, X0)
See Time series data.

3.4.2 control.impulse_response
control.impulse_response(sys, T=None, X0=0.0, input=0, output=None, transpose=False, re-

turn_x=False, squeeze=True)
Impulse response of a linear system
If the system has multiple inputs or outputs (MIMO), one input has to be selected for the simulation. Optionally,
one output may be selected. The parameters input and output do this. All other inputs are set to 0, all other
outputs are ignored.
For information on the shape of parameters T, X0 and return values T, yout, see Time series data.
Parameters
• sys (StateSpace, TransferFunction) – LTI system to simulate
• T (array-like object, optional) – Time vector (argument is autocomputed if
not given)
• X0 (array-like object or number, optional) – Initial condition (default =
0)
Numbers are converted to constant arrays with the correct shape.
• input (int) – Index of the input that will be used in this simulation.
• output (int) – Index of the output that will be used in this simulation. Set to None to not
trim outputs
• transpose (bool) – If True, transpose all input and output arrays (for backward com-
patibility with MATLAB and scipy.signal.lsim)
• return_x (bool) – If True, return the state vector (default = False).
Returns
• T (array) – Time values of the output
• yout (array) – Response of the system
• xout (array) – Individual response of each x variable
See also:
forced_response(), initial_response(), step_response()
Notes
This function uses the forced_response function to compute the time response. For continuous time systems,
the initial condition is altered to account for the initial impulse.
Examples
>>> T, yout = impulse_response(sys, T, X0)

3.4.3 control.initial_response
control.initial_response(sys, T=None, X0=0.0, input=0, output=None, transpose=False, re-

Initial condition response of a linear system
If the system has multiple outputs (MIMO), optionally, one output may be selected. If no selection is made for
the output, all outputs are given.
Parameters
• sys (StateSpace, or TransferFunction) – LTI system to simulate
not given)
0)
• input (int) – Ignored, has no meaning in initial condition calculation. Parameter ensures
compatibility with step_response and impulse_response
trim outputs
Returns
See also:
forced_response(), impulse_response(), step_response()
Notes
This function uses the forced_response function with the input set to zero.
Examples
>>> T, yout = initial_response(sys, T, X0)

3.4.4 control.input_output_response
control.input_output_response(sys, T, U=0.0, X0=0, params={}, method=’RK45’, re-

Compute the output response of a system to a given input.
Simulate a dynamical system with a given input and return its output and state values.
Parameters
• sys (InputOutputSystem) – Input/output system to simulate.
• T (array-like) – Time steps at which the input is defined; values must be evenly spaced.
(default = 0).
• return_x (bool, optional) – If True, return the values of the state at each time
(default = False).
• squeeze (bool, optional) – If True (default), squeeze unused dimensions out of the
output response. In particular, for a single output system, return a vector of shape (nsteps)
instead of (nsteps, 1).
Returns
• xout (array) – Time evolution of the state vector (if return_x=True)
Raises
• TypeError – If the system is not an input/output system.
• ValueError – If time step does not match sampling time (for discrete time systems)
3.4.5 control.step_response
control.step_response(sys, T=None, X0=0.0, input=None, output=None, transpose=False, re-

Step response of a linear system
one output may be selected. The parameters input and output do this. All other inputs are set to 0, all other
outputs are ignored.
Parameters
not given)
• X0 (array-like or number, optional) – Initial condition (default = 0)

trim outputs
Returns
See also:
forced_response(), initial_response(), impulse_response()
Notes
This function uses the forced_response function with the input set to a unit step.
Examples
>>> T, yout = step_response(sys, T, X0)
3.4.6 control.phase_plot
control.phase_plot(odefun, X=None, Y=None, scale=1, X0=None, T=None, lingrid=None, lin-

time=None, logtime=None, timepts=None, parms=(), verbose=True)
Phase plot for 2D dynamical systems
Produces a vector field or stream line plot for a planar system.
Call signatures: phase_plot(func, X, Y, . . . ) - display vector field on meshgrid phase_plot(func, X, Y, scale,
. . . ) - scale arrows phase_plot(func. X0=(. . . ), T=Tmax, . . . ) - display stream lines phase_plot(func, X,
Y, X0=[. . . ], T=Tmax, . . . ) - plot both phase_plot(func, X0=[. . . ], T=Tmax, lingrid=N, . . . ) - plot both
phase_plot(func, X0=[. . . ], lintime=N, . . . ) - stream lines with arrows
Parameters
• func (callable(x, t, ..)) – Computes the time derivative of y (compatible with
odeint). The function should be the same for as used for scipy.integrate. Namely, it should
be a function of the form dxdt = F(x, t) that accepts a state x of dimension 2 and returns a
derivative dx/dt of dimension 2.
• Y (X,) – Two 3-element sequences specifying x and y coordinates of a grid. These argu-
ments are passed to linspace and meshgrid to generate the points at which the vector field is
plotted. If absent (or None), the vector field is not plotted.
• scale (float, optional) – Scale size of arrows; default = 1

• X0 (ndarray of initial conditions, optional) – List of initial conditions

from which streamlines are plotted. Each initial condition should be a pair of numbers.
• T (array-like or number, optional) – Length of time to run simulations that
generate streamlines. If a single number, the same simulation time is used for all initial
conditions. Otherwise, should be a list of length len(X0) that gives the simulation time for
each initial condition. Default value = 50.
• lingrid (integer or 2-tuple of integers, optional) – Argument is ei-
ther N or (N, M). If X0 is given and X, Y are missing, a grid of arrows is produced using
the limits of the initial conditions, with N grid points in each dimension or N grid points in
x and M grid points in y.
• lintime (integer or tuple (integer, float), optional) – If a single
integer N is given, draw N arrows using equally space time points. If a tuple (N, lambda) is
given, draw N arrows using exponential time constant lambda
• timepts (array-like, optional) – Draw arrows at the given list times [t1, t2, . . . ]
• parms (tuple, optional) – List of parameters to pass to vector field: func(x, t,
*parms)
See also:
box_grid() construct box-shaped grid of initial conditions
Examples
3.5 Block diagram algebra

3.6 Control system analysis
dcgain(sys) Return the zero-frequency (or DC) gain of the given sys-
tem
evalfr(sys, x) Evaluate the transfer function of an LTI system for a
single complex number x.
freqresp(sys, omega) Frequency response of an LTI system at multiple angu-
lar frequencies.
margin(sysdata) Calculate gain and phase margins and associated
crossover frequencies
stability_margins(sysdata[, returnall, epsw]) Calculate stability margins and associated crossover fre-
quencies.
phase_crossover_frequencies(sys) Compute frequencies and gains at intersections with real
axis in Nyquist plot.
pole(sys) Compute system poles.
zero(sys) Compute system zeros.
Continued on next page
3.6. Control system analysis 27

Table 6 – continued from previous page

pzmap(sys[, plot, grid, title]) Plot a pole/zero map for a linear system.
root_locus(sys[, kvect, xlim, ylim, . . . ]) Root locus plot
sisotool(sys[, kvect, xlim_rlocus, . . . ]) Sisotool style collection of plots inspired by MATLAB’s
sisotool.
3.6.1 control.dcgain
control.dcgain(sys)
Return the zero-frequency (or DC) gain of the given system
Returns gain – The zero-frequency gain, or np.nan if the system has a pole at the origin
Return type ndarray
3.6.2 control.evalfr
control.evalfr(sys, x)
Evaluate the transfer function of an LTI system for a single complex number x.
To evaluate at a frequency, enter x = omega*j, where omega is the frequency in radians
Parameters
• sys (StateSpace or TransferFunction) – Linear system
• x (scalar) – Complex number
Returns fresp
Return type ndarray
See also:
freqresp(), bode()
Notes
This function is a wrapper for StateSpace.evalfr and TransferFunction.evalfr.
Examples
>>> sys = ss("1. -2; 3. -4", "5.; 7", "6. 8", "9.")
>>> evalfr(sys, 1j)
array([[ 44.8-21.4j]])
>>> # This is the transfer function matrix evaluated at s = i.
Todo: Add example with MIMO system
3.6.3 control.freqresp
control.freqresp(sys, omega)
Frequency response of an LTI system at multiple angular frequencies.

Parameters
• omega (array_like) – List of frequencies
Returns
• mag (ndarray)
• phase (ndarray)
• omega (list, tuple, or ndarray)
See also:
evalfr(), bode()
Notes
This function is a wrapper for StateSpace.freqresp and TransferFunction.freqresp. The output omega is a sorted
version of the input omega.
Examples
>>> sys = ss("1. -2; 3. -4", "5.; 7", "6. 8", "9.")
>>> mag, phase, omega = freqresp(sys, [0.1, 1., 10.])
>>> mag
array([[[ 58.8576682 , 49.64876635, 13.40825927]]])
>>> phase
array([[[-0.05408304, -0.44563154, -0.66837155]]])

#>>> sys = rss(3, 2, 2) #>>> mag, phase, omega = freqresp(sys, [0.1, 1., 10.]) #>>> mag[0, 1, :] #array([
55.43747231, 42.47766549, 1.97225895]) #>>> phase[1, 0, :] #array([-0.12611087, -1.14294316, 2.5764547
]) #>>> # This is the magnitude of the frequency response from the 2nd #>>> # input to the 1st output, and the
phase (in radians) of the #>>> # frequency response from the 1st input to the 2nd output, for #>>> # s = 0.1i, i,
10i.
3.6.4 control.margin
control.margin(sysdata)
Calculate gain and phase margins and associated crossover frequencies
Parameters sysdata (LTI system or (mag, phase, omega) sequence) –
sys [StateSpace or TransferFunction] Linear SISO system
mag, phase, omega [sequence of array_like] Input magnitude, phase (in deg.), and frequencies
(rad/sec) from bode frequency response data
Returns
• gm (float) – Gain margin
• pm (float) – Phase margin (in degrees)

• wg (float) – Frequency for gain margin (at phase crossover, phase = -180 degrees)
• wp (float) – Frequency for phase margin (at gain crossover, gain = 1)
• Margins are calculated for a SISO open-loop system.
• If there is more than one gain crossover, the one at the smallest
• margin (deviation from gain = 1), in absolute sense, is
• returned. Likewise the smallest phase margin (in absolute sense)
• is returned.
Examples
>>> sys = tf(1, [1, 2, 1, 0])

>>> gm, pm, wg, wp = margin(sys)
3.6.5 control.stability_margins
control.stability_margins(sysdata, returnall=False, epsw=0.0)

Calculate stability margins and associated crossover frequencies.
Parameters
• sysdata (LTI system or (mag, phase, omega) sequence) –
sys [LTI system] Linear SISO system
mag, phase, omega [sequence of array_like] Arrays of magnitudes (absolute values, not
dB), phases (degrees), and corresponding frequencies. Crossover frequencies returned
are in the same units as those in omega (e.g., rad/sec or Hz).
• returnall (bool, optional) – If true, return all margins found. If False (default),
return only the minimum stability margins. For frequency data or FRD systems, only mar-
gins in the given frequency region can be found and returned.
• epsw (float, optional) – Frequencies below this value (default 0.0) are considered
static gain, and not returned as margin.
Returns
• gm (float or array_like) – Gain margin
• pm (float or array_loke) – Phase margin
• sm (float or array_like) – Stability margin, the minimum distance from the Nyquist plot to
-1
• wg (float or array_like) – Frequency for gain margin (at phase crossover, phase = -180
degrees)
• wp (float or array_like) – Frequency for phase margin (at gain crossover, gain = 1)
• ws (float or array_like) – Frequency for stability margin (complex gain closest to -1)

3.6.6 control.phase_crossover_frequencies
control.phase_crossover_frequencies(sys)
Compute frequencies and gains at intersections with real axis in Nyquist plot.
Call as: omega, gain = phase_crossover_frequencies()
Returns
• omega (1d array of (non-negative) frequencies where Nyquist plot)
• intersects the real axis
• gain (1d array of corresponding gains)
Examples
>>> tf = TransferFunction([1], [1, 2, 3, 4])

>>> PhaseCrossoverFrequenies(tf)
(array([ 1.73205081, 0. ]), array([-0.5 , 0.25]))
3.6.7 control.pole
control.pole(sys)
Compute system poles.
Parameters sys (StateSpace or TransferFunction) – Linear system
Returns poles – Array that contains the system’s poles.
Return type ndarray
Raises NotImplementedError – when called on a TransferFunction object
See also:
zero(), TransferFunction.pole(), StateSpace.pole()
3.6.8 control.zero
control.zero(sys)
Compute system zeros.
Returns zeros – Array that contains the system’s zeros.
Return type ndarray
Raises NotImplementedError – when called on a MIMO system
See also:
pole(), StateSpace.zero(), TransferFunction.zero()

3.6.9 control.pzmap
control.pzmap(sys, plot=True, grid=False, title=’Pole Zero Map’, **kwargs)

Plot a pole/zero map for a linear system.
Parameters
• sys (LTI (StateSpace or TransferFunction)) – Linear system for which
poles and zeros are computed.
• plot (bool) – If True a graph is generated with Matplotlib, otherwise the poles and zeros
are only computed and returned.
• grid (boolean (default = False)) – If True plot omega-damping grid.
Returns
• pole (array) – The systems poles
• zeros (array) – The system’s zeros.
3.6.10 control.root_locus
control.root_locus(sys, kvect=None, xlim=None, ylim=None, plotstr=None, plot=True,

print_gain=None, grid=None, **kwargs)
Root locus plot
Calculate the root locus by finding the roots of 1+k*TF(s) where TF is self.num(s)/self.den(s) and each k is an
element of kvect.
Parameters
• sys (LTI object) – Linear input/output systems (SISO only, for now).
• kvect (list or ndarray, optional) – List of gains to use in computing diagram.
• xlim (tuple or list, optional) – Set limits of x axis, normally with tuple (see
matplotlib.axes).
• ylim (tuple or list, optional) – Set limits of y axis, normally with tuple (see
matplotlib.axes).
• plot (boolean, optional) – If True (default), plot root locus diagram.
• print_gain (bool) – If True (default), report mouse clicks when close to the root locus
branches, calculate gain, damping and print.
• grid (bool) – If True plot omega-damping grid. Default is False.
Returns
• rlist (ndarray) – Computed root locations, given as a 2D array
• klist (ndarray or list) – Gains used. Same as klist keyword argument if provided.
3.6.11 control.sisotool
control.sisotool(sys, kvect=None, xlim_rlocus=None, ylim_rlocus=None, plotstr_rlocus=’C0’,

rlocus_grid=False, omega=None, dB=None, Hz=None, deg=None,
omega_limits=None, omega_num=None, margins_bode=True, tvect=None)
Sisotool style collection of plots inspired by MATLAB’s sisotool. The left two plots contain the bode magnitude

and phase diagrams. The top right plot is a clickable root locus plot, clicking on the root locus will change the
gain of the system. The bottom left plot shows a closed loop time response.
Parameters
• sys (LTI object) – Linear input/output systems (SISO only)
• kvect (list or ndarray, optional) – List of gains to use for plotting root locus
• xlim_rlocus (tuple or list, optional) – control of x-axis range, normally
with tuple (see matplotlib.axes)
• ylim_rlocus (tuple or list, optional) – control of y-axis range
• plotstr_rlocus (Additional options to matplotlib) – plotting style for
the root locus plot(color, linestyle, etc)
• rlocus_grid (boolean (default = False)) – If True plot s-plane grid.
• omega (freq_range) – Range of frequencies in rad/sec for the bode plot
• dB (boolean) – If True, plot result in dB for the bode plot
• Hz (boolean) – If True, plot frequency in Hz for the bode plot (omega must be provided
in rad/sec)
• deg (boolean) – If True, plot phase in degrees for the bode plot (else radians)
• omega_num (int) – number of samples
• margins_bode (boolean) – If True, plot gain and phase margin in the bode plot
• tvect (list or ndarray, optional) – List of timesteps to use for closed loop
step response
Examples
>>> sys = tf([1000], [1,25,100,0])

>>> sisotool(sys)
3.7 Matrix computations
care(A, B, Q[, R, S, E, stabilizing]) (X,L,G) = care(A,B,Q,R=None) solves the continuous-

time algebraic Riccati equation
dare(A, B, Q, R[, S, E, stabilizing]) (X,L,G) = dare(A,B,Q,R) solves the discrete-time alge-
braic Riccati equation
lyap(A, Q[, C, E]) X = lyap(A, Q) solves the continuous-time Lyapunov
equation
dlyap(A, Q[, C, E]) dlyap(A,Q) solves the discrete-time Lyapunov equation
ctrb(A, B) Controllabilty matrix
obsv(A, C) Observability matrix
gram(sys, type) Gramian (controllability or observability)
3.7. Matrix computations 33

3.7.1 control.care
control.care(A, B, Q, R=None, S=None, E=None, stabilizing=True)

(X,L,G) = care(A,B,Q,R=None) solves the continuous-time algebraic Riccati equation
𝐴𝑇 𝑋 + 𝑋𝐴 − 𝑋𝐵𝑅−1 𝐵 𝑇 𝑋 + 𝑄 = 0
where A and Q are square matrices of the same dimension. Further, Q and R are a symmetric matrices. If R is
None, it is set to the identity matrix. The function returns the solution X, the gain matrix G = B^T X and the
closed loop eigenvalues L, i.e., the eigenvalues of A - B G.
(X,L,G) = care(A,B,Q,R,S,E) solves the generalized continuous-time algebraic Riccati equation
𝐴𝑇 𝑋𝐸 + 𝐸 𝑇 𝑋𝐴 − (𝐸 𝑇 𝑋𝐵 + 𝑆)𝑅−1 (𝐵 𝑇 𝑋𝐸 + 𝑆 𝑇 ) + 𝑄 = 0
where A, Q and E are square matrices of the same dimension. Further, Q and R are symmetric matrices. If R is
None, it is set to the identity matrix. The function returns the solution X, the gain matrix G = R^-1 (B^T X E +
S^T) and the closed loop eigenvalues L, i.e., the eigenvalues of A - B G , E.
3.7.2 control.dare
control.dare(A, B, Q, R, S=None, E=None, stabilizing=True)

(X,L,G) = dare(A,B,Q,R) solves the discrete-time algebraic Riccati equation
𝐴𝑇 𝑋𝐴 − 𝑋 − 𝐴𝑇 𝑋𝐵(𝐵 𝑇 𝑋𝐵 + 𝑅)−1 𝐵 𝑇 𝑋𝐴 + 𝑄 = 0
where A and Q are square matrices of the same dimension. Further, Q is a symmetric matrix. The function
returns the solution X, the gain matrix G = (B^T X B + R)^-1 B^T X A and the closed loop eigenvalues L, i.e.,
the eigenvalues of A - B G.
(X,L,G) = dare(A,B,Q,R,S,E) solves the generalized discrete-time algebraic Riccati equation
𝐴𝑇 𝑋𝐴 − 𝐸 𝑇 𝑋𝐸 − (𝐴𝑇 𝑋𝐵 + 𝑆)(𝐵 𝑇 𝑋𝐵 + 𝑅)−1 (𝐵 𝑇 𝑋𝐴 + 𝑆 𝑇 ) + 𝑄 = 0
where A, Q and E are square matrices of the same dimension. Further, Q and R are symmetric matrices. The
function returns the solution X, the gain matrix 𝐺 = (𝐵 𝑇 𝑋𝐵 + 𝑅)−1 (𝐵 𝑇 𝑋𝐴 + 𝑆 𝑇 ) and the closed loop
eigenvalues L, i.e., the eigenvalues of A - B G , E.
3.7.3 control.lyap
control.lyap(A, Q, C=None, E=None)

X = lyap(A, Q) solves the continuous-time Lyapunov equation
𝐴𝑋 + 𝑋𝐴𝑇 + 𝑄 = 0
where A and Q are square matrices of the same dimension. Further, Q must be symmetric.
X = lyap(A,Q,C) solves the Sylvester equation
𝐴𝑋 + 𝑋𝑄 + 𝐶 = 0
where A and Q are square matrices.
X = lyap(A,Q,None,E) solves the generalized continuous-time Lyapunov equation
𝐴𝑋𝐸 𝑇 + 𝐸𝑋𝐴𝑇 + 𝑄 = 0
where Q is a symmetric matrix and A, Q and E are square matrices of the same dimension.

3.7.4 control.dlyap
control.dlyap(A, Q, C=None, E=None)

dlyap(A,Q) solves the discrete-time Lyapunov equation
𝐴𝑋𝐴𝑇 − 𝑋 + 𝑄 = 0
where A and Q are square matrices of the same dimension. Further Q must be symmetric.
dlyap(A,Q,C) solves the Sylvester equation
𝐴𝑋𝑄𝑇 − 𝑋 + 𝐶 = 0
dlyap(A,Q,None,E) solves the generalized discrete-time Lyapunov equation
𝐴𝑋𝐴𝑇 − 𝐸𝑋𝐸 𝑇 + 𝑄 = 0
3.7.5 control.ctrb
control.ctrb(A, B)
Controllabilty matrix
Parameters B (A,) – Dynamics and input matrix of the system
Returns C – Controllability matrix
Return type matrix
Examples
>>> C = ctrb(A, B)
3.7.6 control.obsv
control.obsv(A, C)
Observability matrix
Parameters C (A,) – Dynamics and output matrix of the system
Returns O – Observability matrix
Return type matrix
Examples
>>> O = obsv(A, C)
3.7. Matrix computations 35

3.7.7 control.gram
control.gram(sys, type)
Gramian (controllability or observability)
Parameters
• sys (StateSpace) – State-space system to compute Gramian for
• type (String) – Type of desired computation. type is either ‘c’ (controllability) or ‘o’
(observability). To compute the Cholesky factors of gramians use ‘cf’ (controllability) or
‘of’ (observability)
Returns gram – Gramian of system
Return type array
Raises
• ValueError – * if system is not instance of StateSpace class * if type is not ‘c’, ‘o’, ‘cf’
or ‘of’ * if system is unstable (sys.A has eigenvalues not in left half plane)
• ImportError – if slycot routine sb03md cannot be found if slycot routine sb03od cannot
be found
Examples
>>> Wc = gram(sys,'c')
>>> Wo = gram(sys,'o')
>>> Rc = gram(sys,'cf'), where Wc=Rc'*Rc
>>> Ro = gram(sys,'of'), where Wo=Ro'*Ro
3.8 Control system synthesis
acker(A, B, poles) Pole placement using Ackermann method

h2syn(P, nmeas, ncon) H_2 control synthesis for plant P.
hinfsyn(P, nmeas, ncon) H_{inf} control synthesis for plant P.
lqr(A, B, Q, R[, N]) Linear quadratic regulator design
mixsyn(g[, w1, w2, w3]) Mixed-sensitivity H-infinity synthesis.
place(A, B, p) Place closed loop eigenvalues K = place(A, B, p)
3.8.1 control.acker
control.acker(A, B, poles)
Pole placement using Ackermann method
Call: K = acker(A, B, poles)
Parameters
• B (A,) – State and input matrix of the system
• poles (1-d list) – Desired eigenvalue locations
Returns K – Gains such that A - B K has given eigenvalues
Return type matrix

3.8.2 control.h2syn
control.h2syn(P, nmeas, ncon)

H_2 control synthesis for plant P.
Parameters
• P (partitioned lti plant (State-space sys)) –
• nmeas (number of measurements (input to controller)) –
• ncon (number of control inputs (output from controller)) –
Returns K
Return type controller to stabilize P (State-space sys)
Raises ImportError – if slycot routine sb10hd is not loaded
See also:
StateSpace()
Examples
>>> K = h2syn(P,nmeas,ncon)
3.8.3 control.hinfsyn
control.hinfsyn(P, nmeas, ncon)

H_{inf} control synthesis for plant P.
Parameters
• P (partitioned lti plant) –
• nmeas (number of measurements (input to controller)) –
• ncon (number of control inputs (output from controller)) –
Returns
• K (controller to stabilize P (State-space sys))
• CL (closed loop system (State-space sys))
• gam (infinity norm of closed loop system)
• rcond (4-vector, reciprocal condition estimates of:) – 1: control transformation matrix 2:
measurement transformation matrix 3: X-Ricatti equation 4: Y-Ricatti equation
• TODO (document significance of rcond)
Raises ImportError – if slycot routine sb10ad is not loaded
See also:
StateSpace()
3.8. Control system synthesis 37

Examples
>>> K, CL, gam, rcond = hinfsyn(P,nmeas,ncon)
3.8.4 control.lqr
control.lqr(A, B, Q, R[, N ])
Linear quadratic regulator design
The lqr() function computes the optimal state feedback controller that minimizes the quadratic cost
∫︁ ∞
𝐽= (𝑥′ 𝑄𝑥 + 𝑢′ 𝑅𝑢 + 2𝑥′ 𝑁 𝑢)𝑑𝑡
0
The function can be called with either 3, 4, or 5 arguments:

• lqr(sys, Q, R)
• lqr(sys, Q, R, N)
• lqr(A, B, Q, R)
• lqr(A, B, Q, R, N)
where sys is an LTI object, and A, B, Q, R, and N are 2d arrays or matrices of appropriate dimension.
Parameters
• B (A,) – Dynamics and input matrices
• sys (LTI (StateSpace or TransferFunction)) – Linear I/O system
• R (Q,) – State and input weight matrices
• N (2-d array, optional) – Cross weight matrix
Returns
• K (2D array) – State feedback gains
• S (2D array) – Solution to Riccati equation
• E (1D array) – Eigenvalues of the closed loop system
Examples
>>> K, S, E = lqr(sys, Q, R, [N])

>>> K, S, E = lqr(A, B, Q, R, [N])
See also:
lqe()
3.8.5 control.mixsyn
control.mixsyn(g, w1=None, w2=None, w3=None)

Mixed-sensitivity H-infinity synthesis.
mixsyn(g,w1,w2,w3) -> k,cl,info

Parameters
• g (LTI; the plant for which controller must be synthesized) –
• w1 (weighting on s = (1+g*k)**-1; None, or scalar or k1-by-ny
LTI) –
• w2 (weighting on k*s; None, or scalar or k2-by-nu LTI) –
• w3 (weighting on t = g*k*(1+g*k)**-1; None, or scalar or
k3-by-ny LTI) –
• least one of w1, w2, and w3 must not be None. (At) –
Returns
• k (synthesized controller; StateSpace object)
• cl (closed system mapping evaluation inputs to evaluation outputs; if )
• p is the augmented plant, with – [z] = [p11 p12] [w], [y] [p21 g] [u]
• then cl is the system from w->z with u=-k*y. StateSpace object.
• info (tuple with entries, in order,) –
– gamma: scalar; H-infinity norm of cl
– rcond: array; estimates of reciprocal condition numbers computed during synthesis. See
hinfsyn for details
• If a weighting w is scalar, it will be replaced by I*w, where I is
• ny-by-ny for w1 and w3, and nu-by-nu for w2.
See also:
hinfsyn(), augw()
3.8.6 control.place
control.place(A, B, p)
Place closed loop eigenvalues K = place(A, B, p)
Parameters
• A (2-d array) – Dynamics matrix
• B (2-d array) – Input matrix
• p (1-d list) – Desired eigenvalue locations
Returns
• K (2-d array) – Gain such that A - B K has eigenvalues given in p
• Algorithm
• ———
• This is a wrapper function for scipy.signal.place_poles, which
• implements the Tits and Yang algorithm [1]. It will handle SISO,
• MISO, and MIMO systems. If you want more control over the algorithm,
• use scipy.signal.place_poles directly.
3.8. Control system synthesis 39

• [1] A.L. Tits and Y. Yang, “Globally convergent algorithms for robust
• pole assignment by state feedback, IEEE Transactions on Automatic
• Control, Vol. 41, pp. 1432-1452, 1996.
• Limitations
• ———–
• The algorithm will not place poles at the same location more
• than rank(B) times.
Examples
>>> A = [[-1, -1], [0, 1]]

>>> B = [[0], [1]]
>>> K = place(A, B, [-2, -5])
See also:
place_varga(), acker()
3.9 Model simplification tools
minreal(sys[, tol, verbose]) Eliminates uncontrollable or unobservable states in

state-space models or cancelling pole-zero pairs in
transfer functions.
balred(sys, orders[, method, alpha]) Balanced reduced order model of sys of a given order.
hsvd(sys) Calculate the Hankel singular values.
modred(sys, ELIM[, method]) Model reduction of sys by eliminating the states in
ELIM using a given method.
era(YY, m, n, nin, nout, r) Calculate an ERA model of order r based on the
impulse-response data YY.
markov(Y, U, m) Calculate the first M Markov parameters [D CB CAB
. . . ] from input U, output Y.
3.9.1 control.minreal
control.minreal(sys, tol=None, verbose=True)

Eliminates uncontrollable or unobservable states in state-space models or cancelling pole-zero pairs in transfer
functions. The output sysr has minimal order and the same response characteristics as the original model sys.
Parameters
• sys (StateSpace or TransferFunction) – Original system
• tol (real) – Tolerance
• verbose (bool) – Print results if True
Returns rsys – Cleaned model

3.9.2 control.balred
control.balred(sys, orders, method=’truncate’, alpha=None)

Balanced reduced order model of sys of a given order. States are eliminated based on Hankel singular value. If
sys has unstable modes, they are removed, the balanced realization is done on the stable part, then reinserted in
accordance with the reference below.
Reference: Hsu,C.S., and Hou,D., 1991, Reducing unstable linear control systems via real Schur transformation.
Electronics Letters, 27, 984-986.
Parameters
• sys (StateSpace) – Original system to reduce
• orders (integer or array of integer) – Desired order of reduced order model
(if a vector, returns a vector of systems)
• method (string) – Method of removing states, either 'truncate' or 'matchdc'.
• alpha (float) – Redefines the stability boundary for eigenvalues of the system matrix
A. By default for continuous-time systems, alpha <= 0 defines the stability boundary for
the real part of A’s eigenvalues and for discrete-time systems, 0 <= alpha <= 1 defines the
stability boundary for the modulus of A’s eigenvalues. See SLICOT routines AB09MD and
AB09ND for more information.
Returns rsys – A reduced order model or a list of reduced order models if orders is a list
Raises
• ValueError – * if method is not 'truncate' or 'matchdc'
• ImportError – if slycot routine ab09ad, ab09md, or ab09nd is not found
• ValueError – if there are more unstable modes than any value in orders
Examples
>>> rsys = balred(sys, orders, method='truncate')
3.9.3 control.hsvd
control.hsvd(sys)
Calculate the Hankel singular values.
Parameters sys (StateSpace) – A state space system
Returns H – A list of Hankel singular values
Return type array
See also:
gram()
3.9. Model simplification tools 41

Notes
The Hankel singular values are the singular values of the Hankel operator. In practice, we compute the square
root of the eigenvalues of the matrix formed by taking the product of the observability and controllability grami-
ans. There are other (more efficient) methods based on solving the Lyapunov equation in a particular way (more
details soon).
Examples
>>> H = hsvd(sys)
3.9.4 control.modred
control.modred(sys, ELIM, method=’matchdc’)

Model reduction of sys by eliminating the states in ELIM using a given method.
Parameters
• ELIM (array) – Vector of states to eliminate
• method (string) – Method of removing states in ELIM: either 'truncate' or
'matchdc'.
Returns rsys – A reduced order model
Raises ValueError – Raised under the following conditions:
• if method is not either 'matchdc' or 'truncate'
• if eigenvalues of sys.A are not all in left half plane (sys must be stable)
Examples
>>> rsys = modred(sys, ELIM, method='truncate')
3.9.5 control.era
control.era(YY, m, n, nin, nout, r)

Calculate an ERA model of order r based on the impulse-response data YY.
Note: This function is not implemented yet.
Parameters
• YY (array) – nout x nin dimensional impulse-response data
• m (integer) – Number of rows in Hankel matrix
• n (integer) – Number of columns in Hankel matrix

• nin (integer) – Number of input variables

• nout (integer) – Number of output variables
• r (integer) – Order of model
Returns sys – A reduced order model sys=ss(Ar,Br,Cr,Dr)
Examples
>>> rsys = era(YY, m, n, nin, nout, r)
3.9.6 control.markov
control.markov(Y, U, m)
Calculate the first M Markov parameters [D CB CAB . . . ] from input U, output Y.
Parameters
• Y (array_like) – Output data
• U (array_like) – Input data
• m (int) – Number of Markov parameters to output
Returns H – First m Markov parameters
Return type ndarray
Notes
Currently only works for SISO
Examples
>>> H = markov(Y, U, m)
3.10 Nonlinear system support
find_eqpt(sys, x0[, u0, y0, t, params, iu, . . . ]) Find the equilibrium point for an input/output system.
linearize(sys, xeq[, ueq, t, params]) Linearize an input/output system at a given state and in-
put.
put.
ss2io(*args, **kw) Create an I/O system from a state space linear system.
tf2io(*args, **kw) Convert a transfer function into an I/O system
flatsys.point_to_point(sys, x0, u0, xf, uf, Tf) Compute trajectory between an initial and final condi-
tions.
3.10. Nonlinear system support 43

3.10.1 control.iosys.find_eqpt
control.iosys.find_eqpt(sys, x0, u0=[], y0=None, t=0, params={}, iu=None, iy=None, ix=None,

idx=None, dx0=None, return_y=False, return_result=False, **kw)
Find the equilibrium point for an input/output system.
Returns the value of an equlibrium point given the initial state and either input value or desired output value for
the equilibrium point.
Parameters
• x0 (list of initial state values) – Initial guess for the value of the state near
the equilibrium point.
• u0 (list of input values, optional) – If y0 is not specified, sets the equilib-
rium value of the input. If y0 is given, provides an initial guess for the value of the input.
Can be omitted if the system does not have any inputs.
• y0 (list of output values, optional) – If specified, sets the desired values of
the outputs at the equilibrium point.
• t (float, optional) – Evaluation time, for time-varying systems
• params (dict, optional) – Parameter values for the system. Passed to the evaluation
functions for the system as default values, overriding internal defaults.
• iu (list of input indices, optional) – If specified, only the inputs with the
given indices will be fixed at the specified values in solving for an equilibrium point. All
other inputs will be varied. Input indices can be listed in any order.
• iy (list of output indices, optional) – If specified, only the outputs with
the given indices will be fixed at the specified values in solving for an equilibrium point. All
other outputs will be varied. Output indices can be listed in any order.
• ix (list of state indices, optional) – If specified, states with the given in-
dices will be fixed at the specified values in solving for an equilibrium point. All other states
will be varied. State indices can be listed in any order.
• dx0 (list of update values, optional) – If specified, the value of update map
must match the listed value instead of the default value of 0.
• idx (list of state indices, optional) – If specified, state updates with the
given indices will have their update maps fixed at the values given in dx0. All other update
values will be ignored in solving for an equilibrium point. State indices can be listed in any
order. By default, all updates will be fixed at dx0 in searching for an equilibrium point.
• return_y (bool, optional) – If True, return the value of output at the equilibrium
point.
• return_result (bool, optional) – If True, return the result option from the scipy
root function used to compute the equilibrium point.
Returns
• xeq (array of states) – Value of the states at the equilibrium point, or None if no equilibrium
point was found and return_result was False.
• ueq (array of input values) – Value of the inputs at the equilibrium point, or None if no
equilibrium point was found and return_result was False.
• yeq (array of output values, optional) – If return_y is True, returns the value of the outputs
at the equilibrium point, or None if no equilibrium point was found and return_result was
False.

• result (scipy root() result object, optional) – If return_result is True, returns the result from
the scipy root function.
3.10.2 control.iosys.linearize
control.iosys.linearize(sys, xeq, ueq=[], t=0, params={}, **kw)

Linearize an input/output system at a given state and input.
This function computes the linearization of an input/output system at a given state and input value and returns a
control.StateSpace object. The eavaluation point need not be an equilibrium point.
Parameters
• sys (InputOutputSystem) – The system to be linearized
• xeq (array) – The state at which the linearization will be evaluated (does not need to be
an equlibrium state).
• ueq (array) – The input at which the linearization will be evaluated (does not need to
correspond to an equlibrium state).
• t (float, optional) – The time at which the linearization will be computed (for time-
varying systems).
• params (dict, optional) – Parameter values for the systems. Passed to the evalua-
tion functions for the system as default values, overriding internal defaults.
Returns ss_sys – The linearization of the system, as a LinearIOSystem object (which is also a
StateSpace object.
Return type LinearIOSystem
3.10.3 control.iosys.input_output_response
control.iosys.input_output_response(sys, T, U=0.0, X0=0, params={}, method=’RK45’, re-

Compute the output response of a system to a given input.
Simulate a dynamical system with a given input and return its output and state values.
Parameters
• sys (InputOutputSystem) – Input/output system to simulate.
• T (array-like) – Time steps at which the input is defined; values must be evenly spaced.
(default = 0).
• return_x (bool, optional) – If True, return the values of the state at each time
(default = False).
• squeeze (bool, optional) – If True (default), squeeze unused dimensions out of the
output response. In particular, for a single output system, return a vector of shape (nsteps)
instead of (nsteps, 1).
Returns
3.10. Nonlinear system support 45


• xout (array) – Time evolution of the state vector (if return_x=True)
Raises
• TypeError – If the system is not an input/output system.
• ValueError – If time step does not match sampling time (for discrete time systems)
3.10.4 control.iosys.ss2io
control.iosys.ss2io(*args, **kw)
Create an I/O system from a state space linear system.
Converts a StateSpace system into an InputOutputSystem with the same inputs, outputs, and states.
The new system can be a continuous or discrete time system
Parameters
• linsys (StateSpace) – LTI StateSpace system to be converted
• inputs (int, list of str or None, optional) – Description of the system
inputs. This can be given as an integer count or as a list of strings that name the individual
signals. If an integer count is specified, the names of the signal will be of the form s[i]
(where s is one of u, y, or x). If this parameter is not given or given as None, the relevant
quantity will be determined when possible based on other information provided to functions
using the system.
• outputs (int, list of str or None, optional) – Description of the system
outputs. Same format as inputs.
• states (int, list of str, or None, optional) – Description of the system
states. Same format as inputs.
• dt (None, True or float, optional) – System timebase. None (default) indi-
cates continuous time, True indicates discrete time with undefined sampling time, positive
number is discrete time with specified sampling time.
• name (string, optional) – System name (used for specifying signals)
Returns iosys – Linear system represented as an input/output system
3.10.5 control.iosys.tf2io
control.iosys.tf2io(*args, **kw)
Convert a transfer function into an I/O system
3.10.6 control.flatsys.point_to_point
control.flatsys.point_to_point(sys, x0, u0, xf, uf, Tf, T0=0, basis=None, cost=None)

Compute trajectory between an initial and final conditions.
Compute a feasible trajectory for a differentially flat system between an initial condition and a final condition.

Parameters
• flatsys (FlatSystem object) – Description of the differentially flat system. This
object must define a function flatsys.forward() that takes the system state and produceds the
flag of flat outputs and a system flatsys.reverse() that takes the flag of the flat output and
prodes the state and input.
• u0, xf, uf (x0,) – Define the desired initial and final conditions for the system. If any
of the values are given as None, they are replaced by a vector of zeros of the appropriate
dimension.
• Tf (float) – The final time for the trajectory (corresponding to xf)
• T0 (float (optional)) – The initial time for the trajectory (corresponding to x0). If
not specified, its value is taken to be zero.
• basis (BasisFamily object (optional)) – The basis functions to use for gen-
erating the trajectory. If not specified, the PolyFamily basis family will be used, with the
minimal number of elements required to find a feasible trajectory (twice the number of sys-
tem states)
Returns traj – The system trajectory is returned as an object that implements the eval() function,
we can be used to compute the value of the state and input and a given time t.
Return type SystemTrajectory object
3.11 Utility functions and conversions
augw(g[, w1, w2, w3]) Augment plant for mixed sensitivity problem.
canonical_form(xsys[, form]) Convert a system into canonical form
damp(sys[, doprint]) Compute natural frequency, damping ratio, and poles of
a system
db2mag(db) Convert a gain in decibels (dB) to a magnitude
isctime(sys[, strict]) Check to see if a system is a continuous-time system
isdtime(sys[, strict]) Check to see if a system is a discrete time system
issiso(sys[, strict]) Check to see if a system is single input, single output
issys(obj) Return True if an object is a system, otherwise False
mag2db(mag) Convert a magnitude to decibels (dB)
observable_form(xsys) Convert a system into observable canonical form
pade(T[, n, numdeg]) Create a linear system that approximates a delay.
reachable_form(xsys) Convert a system into reachable canonical form
reset_defaults() Reset configuration values to their default (initial) val-
ues.
sample_system(sysc, Ts[, method, alpha]) Convert a continuous time system to discrete time
ss2tf(sys) Transform a state space system to a transfer function.
ssdata(sys) Return state space data objects for a system
tf2ss(sys) Transform a transfer function to a state space system.
tfdata(sys) Return transfer function data objects for a system
timebase(sys[, strict]) Return the timebase for an LTI system
timebaseEqual(sys1, sys2) Check to see if two systems have the same timebase
unwrap(angle[, period]) Unwrap a phase angle to give a continuous curve
use_fbs_defaults() Use Feedback Systems (FBS) compatible settings.
use_matlab_defaults() Use MATLAB compatible configuration settings.
3.11. Utility functions and conversions 47


use_numpy_matrix([flag, warn]) Turn on/off use of Numpy matrix class for state space
operations.
3.11.1 control.augw
control.augw(g, w1=None, w2=None, w3=None)

Augment plant for mixed sensitivity problem.
Parameters
• g (LTI object, ny-by-nu) –
• w1 (weighting on S; None, scalar, or k1-by-ny LTI object) –
• w2 (weighting on KS; None, scalar, or k2-by-nu LTI object) –
• w3 (weighting on T; None, scalar, or k3-by-ny LTI object) –
• p (augmented plant; StateSpace object) –
• a weighting is None, no augmentation is done for it. At
least (If) –
• weighting must not be None. (one) –
• a weighting w is scalar, it will be replaced by I*w, where I
is (If) –
• for w1 and w3, and nu-by-nu for w2. (ny-by-ny) –
Returns p
Return type plant augmented with weightings, suitable for submission to hinfsyn or h2syn.
Raises ValueError – - if all weightings are None
See also:
h2syn(), hinfsyn(), mixsyn()
3.11.2 control.canonical_form
control.canonical_form(xsys, form=’reachable’)
Convert a system into canonical form
Parameters
• xsys (StateSpace object) – System to be transformed, with state ‘x’
• form (String) –
Canonical form for transformation. Chosen from:
– ’reachable’ - reachable canonical form
– ’observable’ - observable canonical form
– ’modal’ - modal canonical form
Returns
• zsys (StateSpace object) – System in desired canonical form, with state ‘z’
• T (matrix) – Coordinate transformation matrix, z = T * x

3.11.3 control.damp
control.damp(sys, doprint=True)
Compute natural frequency, damping ratio, and poles of a system
The function takes 1 or 2 parameters
Parameters
• sys (LTI (StateSpace or TransferFunction)) – A linear system object
• doprint – if true, print table with values
Returns
• wn (array) – Natural frequencies of the poles
• damping (array) – Damping values
• poles (array) – Pole locations
• Algorithm
• ———
• If the system is continuous, – wn = abs(poles) Z = -real(poles)/poles.
• If the system is discrete, the discrete poles are mapped to their
• equivalent location in the s-plane via – s = log10(poles)/dt
• and – wn = abs(s) Z = -real(s)/wn.
See also:
pole()
3.11.4 control.db2mag
control.db2mag(db)
Convert a gain in decibels (dB) to a magnitude
If A is magnitude,
db = 20 * log10(A)
Parameters db (float or ndarray) – input value or array of values, given in decibels

Returns mag – corresponding magnitudes
Return type float or ndarray
3.11.5 control.isctime
control.isctime(sys, strict=False)
Check to see if a system is a continuous-time system
Parameters
• sys (LTI system) – System to be checked
• strict (bool (default = False)) – If strict is True, make sure that timebase is
not None

3.11.6 control.isdtime
control.isdtime(sys, strict=False)
Check to see if a system is a discrete time system
Parameters
• strict (bool (default = False)) – If strict is True, make sure that timebase is
not None
3.11.7 control.issiso
control.issiso(sys, strict=False)
Check to see if a system is single input, single output
Parameters
• strict (bool (default = False)) – If strict is True, do not treat scalars as SISO
3.11.8 control.issys
control.issys(obj)
Return True if an object is a system, otherwise False
3.11.9 control.mag2db
control.mag2db(mag)
Convert a magnitude to decibels (dB)
If A is magnitude,
db = 20 * log10(A)
Parameters mag (float or ndarray) – input magnitude or array of magnitudes

Returns db – corresponding values in decibels
3.11.10 control.observable_form
control.observable_form(xsys)
Convert a system into observable canonical form
Parameters xsys (StateSpace object) – System to be transformed, with state x
Returns
• zsys (StateSpace object) – System in observable canonical form, with state z
• T (matrix) – Coordinate transformation: z = T * x

3.11.11 control.pade
control.pade(T, n=1, numdeg=None)

Create a linear system that approximates a delay.
Return the numerator and denominator coefficients of the Pade approximation.
Parameters
• T (number) – time delay
• n (positive integer) – degree of denominator of approximation
• numdeg (integer, or None (the default)) – If None, numerator degree
equals denominator degree If >= 0, specifies degree of numerator If < 0, numerator degree
is n+numdeg
Returns num, den – Polynomial coefficients of the delay model, in descending powers of s.
Return type array
Notes
Based on:
1. Algorithm 11.3.1 in Golub and van Loan, “Matrix Computation” 3rd. Ed. pp. 572-574
2. M. Vajta, “Some remarks on Padé-approximations”, 3rd TEMPUS-INTCOM Symposium
3.11.12 control.reachable_form
control.reachable_form(xsys)
Convert a system into reachable canonical form
Parameters xsys (StateSpace object) – System to be transformed, with state x
Returns
• zsys (StateSpace object) – System in reachable canonical form, with state z
• T (matrix) – Coordinate transformation: z = T * x
3.11.13 control.sample_system
control.sample_system(sysc, Ts, method=’zoh’, alpha=None)

Convert a continuous time system to discrete time
Creates a discrete time system from a continuous time system by sampling. Multiple methods of conversion are
supported.
Parameters
• sysc (linsys) – Continuous time system to be converted
• Ts (real) – Sampling period
• method (string) – Method to use for conversion: ‘matched’, ‘tustin’, ‘zoh’ (default)
Returns sysd – Discrete time system, with sampling rate Ts
Return type linsys

Notes
See TransferFunction.sample and StateSpace.sample for further details.
Examples
>>> sysc = TransferFunction([1], [1, 2, 1])

>>> sysd = sample_system(sysc, 1, method='matched')
3.11.14 control.ss2tf
control.ss2tf(sys)
Transform a state space system to a transfer function.
The function accepts either 1 or 4 parameters:
ss2tf(sys) Convert a linear system into space system form. Always creates a new system, even if sys is
already a StateSpace object.
ss2tf(A, B, C, D) Create a state space system from the matrices of its state and output equations.
For details see: ss()
Parameters
• sys (StateSpace) – A linear system
• D (array_like or string) – Feedthrough matrix
Returns out – New linear system in transfer function form
Raises
• ValueError – if matrix sizes are not self-consistent, or if an invalid number of arguments
is passed in
• TypeError – if sys is not a StateSpace object
See also:
tf(), ss(), tf2ss()
Examples
>>> A = [[1., -2], [3, -4]]

>>> B = [[5.], [7]]
>>> C = [[6., 8]]
>>> D = [[9.]]
>>> sys1 = ss2tf(A, B, C, D)

>>> sys_ss = ss(A, B, C, D)

>>> sys2 = ss2tf(sys_ss)
3.11.15 control.ssdata
control.ssdata(sys)
Return state space data objects for a system
Parameters sys (LTI (StateSpace, or TransferFunction)) – LTI system whose
data will be returned
Returns (A, B, C, D) – State space data for the system
Return type list of matrices
3.11.16 control.tf2ss
control.tf2ss(sys)
Transform a transfer function to a state space system.
tf2ss(sys) Convert a linear system into transfer function form. Always creates a new system, even if sys is
tf2ss(num, den) Create a transfer function system from its numerator and denominator polynomial coef-
ficients.
For details see: tf()
Parameters
Returns out – New linear system in state space form
Raises
• ValueError – if num and den have invalid or unequal dimensions, or if an invalid number
of arguments is passed in
• TypeError – if num or den are of incorrect type, or if sys is not a TransferFunction object
See also:
ss(), tf(), ss2tf()

Examples
>>> num = [[[1., 2.], [3., 4.]], [[5., 6.], [7., 8.]]]
>>> den = [[[9., 8., 7.], [6., 5., 4.]], [[3., 2., 1.], [-1., -2., -3.]]]
>>> sys1 = tf2ss(num, den)
>>> sys_tf = tf(num, den)

>>> sys2 = tf2ss(sys_tf)
3.11.17 control.tfdata
control.tfdata(sys)
Return transfer function data objects for a system
Returns (num, den) – Transfer function coefficients (SISO only)
Return type numerator and denominator arrays
3.11.18 control.timebase
control.timebase(sys, strict=True)
Return the timebase for an LTI system
dt = timebase(sys)
returns the timebase for a system ‘sys’. If the strict option is set to False, dt = True will be returned as 1.
3.11.19 control.timebaseEqual
control.timebaseEqual(sys1, sys2)
Check to see if two systems have the same timebase
timebaseEqual(sys1, sys2)
returns True if the timebases for the two systems are compatible. By default, systems with timebase ‘None’ are
compatible with either discrete or continuous timebase systems. If two systems have a discrete timebase (dt >
0) then their timebases must be equal.
3.11.20 control.unwrap
control.unwrap(angle, period=6.283185307179586)
Unwrap a phase angle to give a continuous curve
Parameters
• angle (array_like) – Array of angles to be unwrapped
• period (float, optional) – Period (defaults to 2*pi)
Returns angle_out – Output array, with jumps of period/2 eliminated
Return type array_like

Examples
>>> import numpy as np

>>> theta = [5.74, 5.97, 6.19, 0.13, 0.35, 0.57]
>>> unwrap(theta, period=2 * np.pi)
[5.74, 5.97, 6.19, 6.413185307179586, 6.633185307179586, 6.8531853071795865]


CHAPTER 4
Control system classes
The classes listed below are used to represent models of linear time-invariant (LTI) systems. They are usually created
from factory functions such as tf() and ss(), so the user should normally not need to instantiate these directly.
TransferFunction(num, den[, dt]) A class for representing transfer functions

StateSpace(A, B, C, D[, dt]) A class for representing state-space models
FrequencyResponseData(d, w) A class for models defined by frequency response data
(FRD)
InputOutputSystem([inputs, outputs, states, . . . ]) A class for representing input/output systems.
4.1 control.TransferFunction
class control.TransferFunction(num, den[, dt ])

A class for representing transfer functions
The TransferFunction class is used to represent systems in transfer function form.
The main data members are ‘num’ and ‘den’, which are 2-D lists of arrays containing MIMO numerator and
denominator coefficients. For example,
>>> num[2][5] = numpy.array([1., 4., 8.])
means that the numerator of the transfer function from the 6th input to the 3rd output is set to s^2 + 4s + 8.
Discrete-time transfer functions are implemented by using the ‘dt’ instance variable and setting it to something
other than ‘None’. If ‘dt’ has a non-zero value, then it must match whenever two transfer functions are combined.
If ‘dt’ is set to True, the system will be treated as a discrete time system with unspecified sampling time.
The TransferFunction class defines two constants s and z that represent the differentiation and delay operators
in continuous and discrete time. These can be used to create variables that allow algebraic creation of transfer
functions. For example,
57
>>> s = TransferFunction.s
>>> G = (s + 1)/(s**2 + 2*s + 1)
__init__(*args)
TransferFunction(num, den[, dt])
Construct a transfer function.
The default constructor is TransferFunction(num, den), where num and den are lists of lists of arrays con-
taining polynomial coefficients. To create a discrete time transfer funtion, use TransferFunction(num, den,
dt) where ‘dt’ is the sampling time (or True for unspecified sampling time). To call the copy constructor,
call TransferFunction(sys), where sys is a TransferFunction object (continuous or discrete).
Methods
__init__(*args) TransferFunction(num, den[, dt])

damp() Natural frequency, damping ratio of system poles
dcgain() Return the zero-frequency (or DC) gain
evalfr(omega) Evaluate a transfer function at a single angular fre-
quency.
feedback([other, sign]) Feedback interconnection between two LTI objects.
freqresp(omega) Evaluate a transfer function at a list of angular fre-
quencies.
horner(s) Evaluate the systems’s transfer function for a com-
plex variable
isctime([strict]) Check to see if a system is a continuous-time system
isdtime([strict]) Check to see if a system is a discrete-time system
issiso() Check to see if a system is single input, single output
minreal([tol]) Remove cancelling pole/zero pairs from a transfer
function
pole() Compute the poles of a transfer function.
returnScipySignalLTI() Return a list of a list of scipy.signal.lti objects.
sample(Ts[, method, alpha]) Convert a continuous-time system to discrete time
zero() Compute the zeros of a transfer function.
Attributes
s
z
damp()
Natural frequency, damping ratio of system poles
Returns
• wn (array) – Natural frequencies for each system pole
• zeta (array) – Damping ratio for each system pole
• poles (array) – Array of system poles
dcgain()
Return the zero-frequency (or DC) gain
58 Chapter 4. Control system classes

For a continous-time transfer function G(s), the DC gain is G(0) For a discrete-time transfer function G(z),
the DC gain is G(1)
Returns gain – The zero-frequency gain
Return type ndarray
evalfr(omega)
Evaluate a transfer function at a single angular frequency.
self._evalfr(omega) returns the value of the transfer function matrix with input value s = i * omega.
feedback(other=1, sign=-1)
Feedback interconnection between two LTI objects.
freqresp(omega)
Evaluate a transfer function at a list of angular frequencies.
mag, phase, omega = self.freqresp(omega)
reports the value of the magnitude, phase, and angular frequency of the transfer function matrix evaluated
at s = i * omega, where omega is a list of angular frequencies, and is a sorted version of the input omega.
horner(s)
Evaluate the systems’s transfer function for a complex variable
Returns a matrix of values evaluated at complex variable s.
isctime(strict=False)
Parameters
• strict (bool, optional) – If strict is True, make sure that timebase is not None.
Default is False.
isdtime(strict=False)
Check to see if a system is a discrete-time system
Parameters strict (bool, optional) – If strict is True, make sure that timebase is not
None. Default is False.
issiso()
minreal(tol=None)
Remove cancelling pole/zero pairs from a transfer function
pole()
Compute the poles of a transfer function.
returnScipySignalLTI()
Return a list of a list of scipy.signal.lti objects.
For instance,
>>> out = tfobject.returnScipySignalLTI()

>>> out[3][5]
is a signal.scipy.lti object corresponding to the transfer function from the 6th input to the 4th output.
sample(Ts, method=’zoh’, alpha=None)
Convert a continuous-time system to discrete time
4.1. control.TransferFunction 59
Creates a discrete-time system from a continuous-time system by sampling. Multiple methods of conver-
sion are supported.
Parameters
• Ts (float) – Sampling period
• method ({"gbt", "bilinear", "euler", "backward_diff",) – “zoh”,
“matched”} Method to use for sampling:
– gbt: generalized bilinear transformation
– bilinear: Tustin’s approximation (“gbt” with alpha=0.5)
– euler: Euler (or forward difference) method (“gbt” with alpha=0)
– backward_diff: Backwards difference (“gbt” with alpha=1.0)
– zoh: zero-order hold (default)
• alpha (float within [0, 1]) – The generalized bilinear transformation weight-
ing parameter, which should only be specified with method=”gbt”, and is ignored other-
wise.
Return type StateSpace system
Notes
1. Available only for SISO systems

2. Uses the command cont2discrete from scipy.signal
Examples
>>> sys = TransferFunction(1, [1,1])

>>> sysd = sys.sample(0.5, method='bilinear')
zero()
Compute the zeros of a transfer function.
4.2 control.StateSpace
class control.StateSpace(A, B, C, D[, dt ])

A class for representing state-space models
The StateSpace class is used to represent state-space realizations of linear time-invariant (LTI) systems:
dx/dt = A x + B u y = C x + D u
where u is the input, y is the output, and x is the state.
The main data members are the A, B, C, and D matrices. The class also keeps track of the number of
states (i.e., the size of A). The data format used to store state space matrices is set using the value of con-
fig.defaults[‘use_numpy_matrix’]. If True (default), the state space elements are stored as numpy.matrix ob-
jects; otherwise they are numpy.ndarray objects. The use_numpy_matrix() function can be used to set the
storage type.

Discrete-time state space system are implemented by using the ‘dt’ instance variable and setting it to the sam-
pling period. If ‘dt’ is not None, then it must match whenever two state space systems are combined. Setting dt
= 0 specifies a continuous system, while leaving dt = None means the system timebase is not specified. If ‘dt’ is
set to True, the system will be treated as a discrete time system with unspecified sampling time.
__init__(*args, **kw)
StateSpace(A, B, C, D[, dt])
Construct a state space object.
The default constructor is StateSpace(A, B, C, D), where A, B, C, D are matrices or equivalent objects. To
create a discrete time system, use StateSpace(A, B, C, D, dt) where ‘dt’ is the sampling time (or True for
unspecified sampling time). To call the copy constructor, call StateSpace(sys), where sys is a StateSpace
object.
Methods
__init__(*args, **kw) StateSpace(A, B, C, D[, dt])

append(other) Append a second model to the present model.
dcgain() Return the zero-frequency gain
evalfr(omega) Evaluate a SS system’s transfer function at a single
frequency.
feedback([other, sign]) Feedback interconnection between two LTI systems.
freqresp(omega) Evaluate the system’s transfer func.
plex variable
lft(other[, nu, ny]) Return the Linear Fractional Transformation.
minreal([tol]) Calculate a minimal realization, removes unobserv-
able and uncontrollable states
pole() Compute the poles of a state space system.
sample(Ts[, method, alpha]) Convert a continuous time system to discrete time
zero() Compute the zeros of a state space system.
append(other)
Append a second model to the present model. The second model is converted to state-space if necessary,
inputs and outputs are appended and their order is preserved
damp()
Returns
dcgain()
Return the zero-frequency gain
The zero-frequency gain of a continuous-time state-space system is given by:
4.2. control.StateSpace 61
and of a discrete-time state-space system by:

Returns gain – An array of shape (outputs,inputs); the array will either be the zero-frequency
(or DC) gain, or, if the frequency response is singular, the array will be filled with np.nan.
Return type ndarray
evalfr(omega)
Evaluate a SS system’s transfer function at a single frequency.
Feedback interconnection between two LTI systems.
freqresp(omega)
Evaluate the system’s transfer func. at a list of freqs, omega.
Reports the frequency response of the system,
G(j*omega) = mag*exp(j*phase)
for continuous time. For discrete time systems, the response is evaluated around the unit circle such that
G(exp(j*omega*dt)) = mag*exp(j*phase).
Parameters omega (array) – A list of frequencies in radians/sec at which the system should
be evaluated. The list can be either a python list or a numpy array and will be sorted before
evaluation.
Returns
• mag (float) – The magnitude (absolute value, not dB or log10) of the system frequency
response.
• phase (float) – The wrapped phase in radians of the system frequency response.
• omega (array) – The list of sorted frequencies at which the response was evaluated.
horner(s)
Parameters
Default is False.
issiso()

lft(other, nu=-1, ny=-1)

Return the Linear Fractional Transformation.
A definition of the LFT operator can be found in Appendix A.7, page 512 in the 2nd Edition, Multivariable
Feedback Control by Sigurd Skogestad.
An alternative definition can be found here: https://www.mathworks.com/help/control/ref/lft.html
Parameters
• other (LTI) – The lower LTI system
• ny (int, optional) – Dimension of (plant) measurement output.
• nu (int, optional) – Dimension of (plant) control input.
minreal(tol=0.0)
Calculate a minimal realization, removes unobservable and uncontrollable states
pole()
Compute the poles of a state space system.
For instance,
>>> out = ssobject.returnScipySignalLTI()

>>> out[3][5]
sion are supported.
Parameters
• method ({"gbt", "bilinear", "euler", "backward_diff", "zoh"})
– Which method to use:
– euler: Euler (or forward differencing) method (“gbt” with alpha=0)
– backward_diff: Backwards differencing (“gbt” with alpha=1.0)
wise
4.2. control.StateSpace 63
Notes
Uses the command ‘cont2discrete’ from scipy.signal
Examples
>>> sys = StateSpace(0, 1, 1, 0)

zero()
Compute the zeros of a state space system.
4.3 control.FrequencyResponseData
class control.FrequencyResponseData(d, w)
A class for models defined by frequency response data (FRD)
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. For example,
>>> frdata[2,5,:] = numpy.array([1., 0.8-0.2j, 0.2-0.8j])
means that the frequency response from the 6th input to the 3rd output at the frequencies defined in omega is set
to the array above, i.e. the rows represent the outputs and the columns represent the inputs.
__init__(*args, **kwargs)
Construct an FRD object.
The default constructor is FRD(d, w), where w is an iterable of frequency points, and d is the matching
frequency data.
If d is a single list, 1d array, or tuple, a SISO system description is assumed. d can also be
To call the copy constructor, call FRD(sys), where sys is a FRD object.
To construct frequency response data for an existing LTI object, other than an FRD, call FRD(sys, omega)
Methods
__init__(*args, **kwargs) Construct an FRD object.

eval(omega) Evaluate a transfer function at a single angular fre-
quency.
evalfr(omega) Evaluate a transfer function at a single angular fre-
quency.
feedback([other, sign]) Feedback interconnection between two FRD objects.
freqresp(omega) Evaluate a transfer function at a list of angular fre-
quencies.


Attributes
epsw
damp()
Returns
dcgain()
eval(omega)
self.evalfr(omega) returns the value of the frequency response at frequency omega.
Note that a “normal” FRD only returns values for which there is an entry in the omega vector. An interpo-
lating FRD can return intermediate values.
evalfr(omega)
self._evalfr(omega) returns the value of the frequency response at frequency omega.
Note that a “normal” FRD only returns values for which there is an entry in the omega vector. An interpo-
lating FRD can return intermediate values.
Feedback interconnection between two FRD objects.
freqresp(omega)
Evaluate a transfer function at a list of angular frequencies.
reports the value of the magnitude, phase, and angular frequency of the transfer function matrix evaluated
at s = i * omega, where omega is a list of angular frequencies, and is a sorted version of the input omega.
Parameters
Default is False.
4.3. control.FrequencyResponseData 65
issiso()
4.4 control.iosys.InputOutputSystem
class control.iosys.InputOutputSystem(inputs=None, outputs=None, states=None,
params={}, dt=None, name=None)
A class for representing input/output systems.
The InputOutputSystem class allows (possibly nonlinear) input/output systems to be represented in Python. It
is intended as a parent class for a set of subclasses that are used to implement specific structures and operations
for different types of input/output dynamical systems.
Parameters
• inputs (int, list of str, or None) – Description of the system inputs. This
can be given as an integer count or as a list of strings that name the individual signals. If
an integer count is specified, the names of the signal will be of the form s[i] (where s is
one of u, y, or x). If this parameter is not given or given as None, the relevant quantity will
be determined when possible based on other information provided to functions using the
system.
• outputs (int, list of str, or None) – Description of the system outputs.
Same format as inputs.
• states (int, list of str, or None) – Description of the system states. Same
format as inputs.
ninputs, noutputs, nstates
Number of input, output and state variables
Type int
input_index, output_index, state_index
Dictionary of signal names for the inputs, outputs and states and the index of the corresponding array
Type dict
dt
System timebase. None (default) indicates continuous time, True indicates discrete time with undefined
sampling time, positive number is discrete time with specified sampling time.
Type None, True or float
params
Parameter values for the systems. Passed to the evaluation functions for the system as default values,
overriding internal defaults.
Type dict, optional

name
System name (used for specifying signals)
Type string, optional
Notes
The InputOuputSystem class (and its subclasses) makes use of two special methods for implementing much of
the work of the class:
• _rhs(t, x, u): compute the right hand side of the differential or difference equation for the system. This
must be specified by the subclass for the system.
• _out(t, x, u): compute the output for the current state of the system. The default is to return the entire
system state.
__init__(inputs=None, outputs=None, states=None, params={}, dt=None, name=None)
Create an input/output system.
The InputOutputSystem contructor is used to create an input/output object with the core information re-
quired for all input/output systems. Instances of this class are normally created by one of the input/output
subclasses: LinearIOSystem, NonlinearIOSystem, InterconnectedSystem.
Parameters
system.
format as inputs.
• params (dict, optional) – Parameter values for the systems. Passed to the evalu-
ation functions for the system as default values, overriding internal defaults.
Returns Input/output system object
Return type InputOutputSystem
Methods
__init__([inputs, outputs, states, params, . . . ]) Create an input/output system.

copy() Make a copy of an input/output system.
feedback([other, sign, params]) Feedback interconnection between two input/output
systems
4.4. control.iosys.InputOutputSystem 67

find_input(name) Find the index for an input given its name (None if
not found)
find_output(name) Find the index for an output given its name (None if
not found)
find_state(name) Find the index for a state given its name (None if not
found)
linearize(x0, u0[, t, params, eps]) Linearize an input/output system at a given state and
input.
set_inputs(inputs[, prefix]) Set the number/names of the system inputs.
set_outputs(outputs[, prefix]) Set the number/names of the system outputs.
set_states(states[, prefix]) Set the number/names of the system states.
copy()
Make a copy of an input/output system.
feedback(other=1, sign=-1, params={})
Feedback interconnection between two input/output systems
Parameters
• sys1 (InputOutputSystem) – The primary process.
• sys2 (InputOutputSystem) – The feedback process (often a feedback controller).
• sign (scalar, optional) – The sign of feedback. sign = -1 indicates negative feed-
back, and sign = 1 indicates positive feedback. sign is an optional argument; it assumes a
value of -1 if not specified.
Returns out
Raises ValueError – if the inputs, outputs, or timebases of the systems are incompatible.
find_input(name)
Find the index for an input given its name (None if not found)
find_output(name)
Find the index for an output given its name (None if not found)
find_state(name)
Find the index for a state given its name (None if not found)
linearize(x0, u0, t=0, params={}, eps=1e-06)
Return the linearization of an input/output system at a given state and input value as a StateSpace system.
See linearize() for complete documentation.
set_inputs(inputs, prefix=’u’)
Set the number/names of the system inputs.
Parameters
an integer count is specified, the names of the signal will be of the form u[i] (where the
prefix u can be changed using the optional prefix parameter).
• prefix (string, optional) – If inputs is an integer, create the names of the states
using the given prefix (default = ‘u’). The names of the input will be of the form prefix[i].

set_outputs(outputs, prefix=’y’)
Set the number/names of the system outputs.
Parameters
This can be given as an integer count or as a list of strings that name the individual signals.
If an integer count is specified, the names of the signal will be of the form u[i] (where the
• prefix (string, optional) – If outputs is an integer, create the names of the states
using the given prefix (default = ‘y’). The names of the input will be of the form prefix[i].
set_states(states, prefix=’x’)
Set the number/names of the system states.
Parameters
• states (int, list of str, or None) – Description of the system states. This
• prefix (string, optional) – If states is an integer, create the names of the states
using the given prefix (default = ‘x’). The names of the input will be of the form prefix[i].
4.5 Input/output system subclasses
Input/output systems are accessed primarily via a set of subclasses that allow for linear, nonlinear, and interconnected
elements:
LinearIOSystem(linsys[, inputs, outputs, . . . ]) Input/output representation of a linear (state space) sys-

tem.
NonlinearIOSystem(updfcn[, outfcn, inputs, . . . ]) Nonlinear I/O system.
InterconnectedSystem(syslist[, connections, Interconnection of a set of input/output systems.
. . . ])
4.5.1 control.iosys.LinearIOSystem
class control.iosys.LinearIOSystem(linsys, inputs=None, outputs=None, states=None,

name=None)
Input/output representation of a linear (state space) system.
This class is used to implementat a system that is a linear state space system (defined by the StateSpace system
object).
__init__(linsys, inputs=None, outputs=None, states=None, name=None)
Create an I/O system from a state space linear system.
Converts a StateSpace system into an InputOutputSystem with the same inputs, outputs, and
states. The new system can be a continuous or discrete time system
Parameters
4.5. Input/output system subclasses 69

• inputs (int, list of str or None, optional) – Description of the sys-

tem inputs. This can be given as an integer count or as a list of strings that name the
individual signals. If an integer count is specified, the names of the signal will be of the
form s[i] (where s is one of u, y, or x). If this parameter is not given or given as None, the
relevant quantity will be determined when possible based on other information provided
to functions using the system.
• outputs (int, list of str or None, optional) – Description of the sys-
tem outputs. Same format as inputs.
• states (int, list of str, or None, optional) – Description of the sys-
tem states. Same format as inputs.
Returns iosys – Linear system represented as an input/output system
Methods
__init__(linsys[, inputs, outputs, states, name]) Create an I/O system from a state space linear sys-
tem.
frequency.
systems
not found)
not found)
found)
plex variable
input.


append(other)
copy()
damp()
Returns
dcgain()
Return type ndarray
evalfr(omega)
Parameters
Returns out

find_input(name)
find_output(name)
find_state(name)
freqresp(omega)
evaluation.
Returns
response.
horner(s)
Parameters
Default is False.
issiso()


Parameters
minreal(tol=0.0)
pole()
For instance,

>>> out[3][5]
sion are supported.
Parameters
wise

Notes
Examples

Parameters
Parameters
Parameters
zero()
4.5.2 control.iosys.NonlinearIOSystem
class control.iosys.NonlinearIOSystem(updfcn, outfcn=None, inputs=None, outputs=None,

states=None, params={}, dt=None, name=None)
Nonlinear I/O system.
This class is used to implement a system that is a nonlinear state space system (defined by and update function
and an output function).

__init__(updfcn, outfcn=None, inputs=None, outputs=None, states=None, params={}, dt=None,

name=None)
Create a nonlinear I/O system given update and output functions.
Creates an InputOutputSystem for a nonlinear system by specifying a state update function and an output
function. The new system can be a continuous or discrete time system (Note: discrete-time systems not
yet supported by most function.)
Parameters
• updfcn (callable) – Function returning the state update function
updfcn(t, x, u[, param]) -> array
where x is a 1-D array with shape (nstates,), u is a 1-D array with shape (ninputs,), t is a
float representing the currrent time, and param is an optional dict containing the values of
parameters used by the function.
• outfcn (callable) – Function returning the output at the given state
outfcn(t, x, u[, param]) -> array
where the arguments are the same as for upfcn.
• dt (timebase, optional) – The timebase for the system, used to specify whether
the system is operating in continuous or discrete time. It can have the following values:
– dt = None No timebase specified
– dt = 0 Continuous time system
– dt > 0 Discrete time system with sampling time dt
– dt = True Discrete time with unspecified sampling time
• name (string, optional) – System name (used for specifying signals).
Returns iosys – Nonlinear system represented as an input/output system.
Return type NonlinearIOSystem
Methods
__init__(updfcn[, outfcn, inputs, outputs, . . . ]) Create a nonlinear I/O system given update and out-
put functions.


systems
not found)
not found)
found)
input.
copy()
Parameters
Returns out
find_input(name)
find_output(name)
find_state(name)
Parameters

Parameters
Parameters
4.5.3 control.iosys.InterconnectedSystem
class control.iosys.InterconnectedSystem(syslist, connections=[], inplist=[], outlist=[],

inputs=None, outputs=None, states=None,
Interconnection of a set of input/output systems.
This class is used to implement a system that is an interconnection of input/output systems. The sys consists of
a collection of subsystems whose inputs and outputs are connected via a connection map. The overall system
inputs and outputs are subsets of the subsystem inputs and outputs.
__init__(syslist, connections=[], inplist=[], outlist=[], inputs=None, outputs=None, states=None,
Create an I/O system from a list of systems + connection info.
The InterconnectedSystem class is used to represent an input/output system that consists of an intercon-
nection between a set of subystems. The outputs of each subsystem can be summed together to to provide
inputs to other subsystems. The overall system inputs and outputs can be any subset of subsystem inputs
and outputs.
Parameters
• syslist (array_like of InputOutputSystems) – The list of input/output
systems to be connected
• connections (tuple of connection specifications, optional) –
Description of the internal connections between the subsystems. Each element of the
tuple describes an input to one of the subsystems. The entries are are of the form:
(input-spec, output-spec1, output-spec2, . . . )

The input-spec should be a tuple of the form (subsys_i, inp_j) where subsys_i is the index
into syslist and inp_j is the index into the input vector for the subsystem. If subsys_i has a
single input, then the subsystem index subsys_i can be listed as the input-spec. If systems
and signals are given names, then the form ‘sys.sig’ or (‘sys’, ‘sig’) are also recognized.
Each output-spec should be a tuple of the form (subsys_i, out_j, gain). The input will be
constructed by summing the listed outputs after multiplying by the gain term. If the gain
term is omitted, it is assumed to be 1. If the system has a single output, then the subsystem
index subsys_i can be listed as the input-spec. If systems and signals are given names, then
the form ‘sys.sig’, (‘sys’, ‘sig’) or (‘sys’, ‘sig’, gain) are also recognized, and the special
form ‘-sys.sig’ can be used to specify a signal with gain -1.
If omitted, the connection map (matrix) can be specified using the
set_connect_map() method.
• inplist (tuple of input specifications, optional) – List of specifi-
cations for how the inputs for the overall system are mapped to the subsystem inputs. The
input specification is the same as the form defined in the connection specification. Each
system input is added to the input for the listed subsystem.
If omitted, the input map can be specified using the set_input_map method.
• outlist (tuple of output specifications, optional) – List of specifi-
cations for how the outputs for the subsystems are mapped to overall system outputs. The
output specification is the same as the form defined in the connection specification (includ-
ing the optional gain term). Numbered outputs must be chosen from the list of subsystem
outputs, but named outputs can also be contained in the list of subsystem inputs.
If omitted, the output map can be specified using the set_output_map method.
• dt (timebase, optional) – The timebase for the system, used to specify whether
the system is operating in continuous or discrete time. It can have the following values:
– dt = None No timebase specified
– dt = 0 Continuous time system
– dt > 0 Discrete time system with sampling time dt
– dt = True Discrete time with unspecified sampling time
• name (string, optional) – System name (used for specifying signals).
Methods
__init__(syslist[, connections, inplist, . . . ]) Create an I/O system from a list of systems + con-
nection info.
systems
not found)
not found)


found)
input.
set_connect_map(connect_map) Set the connection map for an interconnected I/O
system.
set_input_map(input_map) Set the input map for an interconnected I/O system.
set_output_map(output_map) Set the output map for an interconnected I/O system.
copy()
Parameters
Returns out
find_input(name)
find_output(name)
find_state(name)
set_connect_map(connect_map)
Set the connection map for an interconnected I/O system.
Parameters connect_map (2D array) – Specify the matrix that will be used to multiply
the vector of subsystem outputs to obtain the vector of subsystem inputs.
set_input_map(input_map)
Set the input map for an interconnected I/O system.
Parameters input_map (2D array) – Specify the matrix that will be used to multiply the
vector of system inputs to obtain the vector of subsystem inputs. These values are added to
the inputs specified in the connection map.

Parameters
set_output_map(output_map)
Set the output map for an interconnected I/O system.
Parameters output_map (2D array) – Specify the matrix that will be used to multiply the
vector of subsystem outputs to obtain the vector of system outputs.
Parameters
Parameters

CHAPTER 5
MATLAB compatibility module
The control.matlab module contains a number of functions that emulate some of the functionality of MATLAB.
The intent of these functions is to provide a simple interface to the python control systems library (python-control) for
people who are familiar with the MATLAB Control Systems Toolbox (tm).
5.1 Creating linear models
tf(num, den[, dt]) Create a transfer function system.

ss(A, B, C, D[, dt]) Create a state space system.
frd(d, w) Construct a frequency response data model
5.1.1 control.matlab.tf
control.matlab.tf(num, den[, dt ])
Create a transfer function system. Can create MIMO systems.
The function accepts either 1, 2, or 3 parameters:
tf(sys) Convert a linear system into transfer function form. Always creates a new system, even if sys is
tf(num, den) Create a transfer function system from its numerator and denominator polynomial coeffi-
cients.
If num and den are 1D array_like objects, the function creates a SISO system.
To create a MIMO system, num and den need to be 2D nested lists of array_like objects. (A 3 dimensional
data structure in total.) (For details see note below.)
tf(num, den, dt) Create a discrete time transfer function system; dt can either be a positive number
indicating the sampling time or ‘True’ if no specific timebase is given.
81
tf('s') or tf('z') Create a transfer function representing the differential operator (‘s’) or delay operator
(‘z’).
Parameters
Raises
• ValueError – if num and den have invalid or unequal dimensions
• TypeError – if num or den are of incorrect type
See also:
TransferFunction(), ss(), ss2tf(), tf2ss()
Notes
num[i][j] contains the polynomial coefficients of the numerator for the transfer function from the (j+1)st
input to the (i+1)st output. den[i][j] works the same way.
The list [2, 3, 4] denotes the polynomial 2𝑠2 + 3𝑠 + 4.
The special forms tf('s') and tf('z') can be used to create transfer functions for differentiation and unit
delays.
Examples
>>> # Create a MIMO transfer function object

>>> # The transfer function from the 2nd input to the 1st output is
>>> # (3s + 4) / (6s^2 + 5s + 4).
>>> num = [[[1., 2.], [3., 4.]], [[5., 6.], [7., 8.]]]
>>> den = [[[9., 8., 7.], [6., 5., 4.]], [[3., 2., 1.], [-1., -2., -3.]]]
>>> sys1 = tf(num, den)
>>> # Create a variable 's' to allow algebra operations for SISO systems
>>> s = tf('s')
>>> G = (s + 1)/(s**2 + 2*s + 1)
>>> # Convert a StateSpace to a TransferFunction object.

>>> sys_ss = ss("1. -2; 3. -4", "5.; 7", "6. 8", "9.")
>>> sys2 = tf(sys1)
82 Chapter 5. MATLAB compatibility module

5.1.2 control.matlab.ss
control.matlab.ss(A, B, C, D[, dt ])
Create a state space system.
The function accepts either 1, 4 or 5 parameters:
ss(sys) Convert a linear system into space system form. Always creates a new system, even if sys is already
a StateSpace object.
ss(A, B, C, D) Create a state space system from the matrices of its state and output equations:
𝑥˙ = 𝐴 · 𝑥 + 𝐵 · 𝑢
𝑦 =𝐶 ·𝑥+𝐷·𝑢
ss(A, B, C, D, dt) Create a discrete-time state space system from the matrices of its state and output
equations:
𝑥[𝑘 + 1] = 𝐴 · 𝑥[𝑘] + 𝐵 · 𝑢[𝑘]

𝑦[𝑘] = 𝐶 · 𝑥[𝑘] + 𝐷 · 𝑢[𝑘𝑖]
The matrices can be given as array like data types or strings. Everything that the constructor of numpy.
matrix accepts is permissible here too.
Parameters
• sys (StateSpace or TransferFunction) – A linear system
• D (array_like or string) – Feed forward matrix
• dt (If present, specifies the sampling period and a discrete
time) – system is created
Raises ValueError – if matrix sizes are not self-consistent
See also:
StateSpace(), tf(), ss2tf(), tf2ss()
Examples
>>> # Create a StateSpace object from four "matrices".

>>> sys1 = ss("1. -2; 3. -4", "5.; 7", "6. 8", "9.")
>>> # Convert a TransferFunction to a StateSpace object.

>>> sys_tf = tf([2.], [1., 3])
>>> sys2 = ss(sys_tf)
5.1. Creating linear models 83

5.1.3 control.matlab.frd
control.matlab.frd(d, w)
Construct a frequency response data model
frd models store the (measured) frequency response of a system.
This function can be called in different ways:
frd(response, freqs) Create an frd model with the given response data, in the form of complex re-
sponse vector, at matching frequency freqs [in rad/s]
frd(sys, freqs) Convert an LTI system into an frd model with data at frequencies freqs.
Parameters
• response (array_like, or list) – complex vector with the system response
• freq (array_lik or lis) – vector with frequencies
Returns sys – New frequency response system
Return type FRD
See also:
FRD(), ss(), tf()
5.1.4 control.matlab.rss
control.matlab.rss(states=1, outputs=1, inputs=1)

Create a stable continuous random state space object.
Parameters
See also:
drss()
Notes
poles of the returned system will always have a negative real part.

5.1.5 control.matlab.drss
control.matlab.drss(states=1, outputs=1, inputs=1)

Create a stable discrete random state space object.
Parameters
See also:
rss()
Notes
poles of the returned system will always have a magnitude less than 1.
5.2 Utility functions and conversions
mag2db(mag) Convert a magnitude to decibels (dB)

db2mag(db) Convert a gain in decibels (dB) to a magnitude
c2d(sysc, Ts[, method]) Return a discrete-time system
ss2tf(sys) Transform a state space system to a transfer function.
tf2ss(sys) Transform a transfer function to a state space system.
tfdata(sys) Return transfer function data objects for a system
5.2.1 control.matlab.mag2db
control.matlab.mag2db(mag)
Convert a magnitude to decibels (dB)
If A is magnitude,
db = 20 * log10(A)
Parameters mag (float or ndarray) – input magnitude or array of magnitudes

Returns db – corresponding values in decibels
5.2.2 control.matlab.db2mag
control.matlab.db2mag(db)
Convert a gain in decibels (dB) to a magnitude

If A is magnitude,
db = 20 * log10(A)
Parameters db (float or ndarray) – input value or array of values, given in decibels

Returns mag – corresponding magnitudes
5.2.3 control.matlab.c2d
control.matlab.c2d(sysc, Ts, method=’zoh’)

Return a discrete-time system
Parameters
• sysc (LTI (StateSpace or TransferFunction), continuous) – System
to be converted
• Ts (number) – Sample time for the conversion
• method (string, optional) – Method to be applied, ‘zoh’ Zero-order hold on the in-
puts (default) ‘foh’ First-order hold, currently not implemented ‘impulse’ Impulse-invariant
discretization, currently not implemented ‘tustin’ Bilinear (Tustin) approximation, only
SISO ‘matched’ Matched pole-zero method, only SISO
5.2.4 control.matlab.ss2tf
control.matlab.ss2tf(sys)
Transform a state space system to a transfer function.
ss2tf(sys) Convert a linear system into space system form. Always creates a new system, even if sys is
already a StateSpace object.
ss2tf(A, B, C, D) Create a state space system from the matrices of its state and output equations.
For details see: ss()
Parameters
• sys (StateSpace) – A linear system
• D (array_like or string) – Feedthrough matrix
Returns out – New linear system in transfer function form
Raises
• ValueError – if matrix sizes are not self-consistent, or if an invalid number of arguments
is passed in
• TypeError – if sys is not a StateSpace object

See also:
tf(), ss(), tf2ss()
Examples
>>> A = [[1., -2], [3, -4]]

>>> B = [[5.], [7]]
>>> C = [[6., 8]]
>>> D = [[9.]]
>>> sys1 = ss2tf(A, B, C, D)
>>> sys_ss = ss(A, B, C, D)

>>> sys2 = ss2tf(sys_ss)
5.2.5 control.matlab.tf2ss
control.matlab.tf2ss(sys)
Transform a transfer function to a state space system.
tf2ss(sys) Convert a linear system into transfer function form. Always creates a new system, even if sys is
tf2ss(num, den) Create a transfer function system from its numerator and denominator polynomial coef-
ficients.
For details see: tf()
Parameters
Returns out – New linear system in state space form
Raises
• ValueError – if num and den have invalid or unequal dimensions, or if an invalid number
of arguments is passed in
• TypeError – if num or den are of incorrect type, or if sys is not a TransferFunction object
See also:
ss(), tf(), ss2tf()

Examples
>>> num = [[[1., 2.], [3., 4.]], [[5., 6.], [7., 8.]]]
>>> den = [[[9., 8., 7.], [6., 5., 4.]], [[3., 2., 1.], [-1., -2., -3.]]]
>>> sys1 = tf2ss(num, den)
>>> sys_tf = tf(num, den)

>>> sys2 = tf2ss(sys_tf)
5.2.6 control.matlab.tfdata
control.matlab.tfdata(sys)
Return transfer function data objects for a system
Returns (num, den) – Transfer function coefficients (SISO only)
Return type numerator and denominator arrays
5.3 System interconnections

connect(sys, Q, inputv, outputv) Index-based interconnection of an LTI system.
append(sys1, sys2, . . . , sysn) Group models by appending their inputs and outputs
5.3.1 control.matlab.series
control.matlab.series(sys1, *sysn)
Return the series connection (sysn * . . . *) sys2 * sys1
Parameters
–
Returns out
Raises ValueError – if sys2.inputs does not equal sys1.outputs if sys1.dt is not compatible with
sys2.dt
See also:
parallel(), feedback()

Notes
This function is a wrapper for the __mul__ function in the StateSpace and TransferFunction classes. The output
it.
Examples
>>> sys3 = series(sys1, sys2) # Same as sys3 = sys2 * sys1
>>> sys5 = series(sys1, sys2, sys3, sys4) # More systems
5.3.2 control.matlab.parallel
control.matlab.parallel(sys1, *sysn)
Return the parallel connection sys1 + sys2 (+ . . . + sysn)
Parameters
–
Returns out
Raises ValueError – if sys1 and sys2 do not have the same numbers of inputs and outputs
See also:
series(), feedback()
Notes
This function is a wrapper for the __add__ function in the StateSpace and TransferFunction classes. The output
it.
Examples
>>> sys3 = parallel(sys1, sys2) # Same as sys3 = sys1 + sys2
>>> sys5 = parallel(sys1, sys2, sys3, sys4) # More systems

5.3.3 control.matlab.feedback
control.matlab.feedback(sys1, sys2=1, sign=-1)

Feedback interconnection between two I/O systems.
Parameters
• sys1 (scalar, StateSpace, TransferFunction, FRD) – The primary pro-
cess.
• sys2 (scalar, StateSpace, TransferFunction, FRD) – The feedback pro-
cess (often a feedback controller).
• sign (scalar) – The sign of feedback. sign = -1 indicates negative feedback, and sign =
1 indicates positive feedback. sign is an optional argument; it assumes a value of -1 if not
specified.
Returns out
Raises
• ValueError – if sys1 does not have as many inputs as sys2 has outputs, or if sys2 does
not have as many inputs as sys1 has outputs
• NotImplementedError – if an attempt is made to perform a feedback on a MIMO
TransferFunction object
See also:
series(), parallel()
Notes
This function is a wrapper for the feedback function in the StateSpace and TransferFunction classes. It calls
TransferFunction.feedback if sys1 is a TransferFunction object, and StateSpace.feedback if sys1 is a StateSpace
object. If sys1 is a scalar, then it is converted to sys2’s type, and the corresponding feedback function is used. If
sys1 and sys2 are both scalars, then TransferFunction.feedback is used.
5.3.4 control.matlab.negate
control.matlab.negate(sys)
Return the negative of a system.
Parameters sys (StateSpace, TransferFunction or FRD) –
Returns out
Notes
This function is a wrapper for the __neg__ function in the StateSpace and TransferFunction classes. The output
type is the same as the input type.

Examples
>>> sys2 = negate(sys1) # Same as sys2 = -sys1.
5.3.5 control.matlab.connect
control.matlab.connect(sys, Q, inputv, outputv)

Index-based interconnection of an LTI system.
The system sys is a system typically constructed with append, with multiple inputs and outputs. The inputs
and outputs are connected according to the interconnection matrix Q, and then the final inputs and outputs are
trimmed according to the inputs and outputs listed in inputv and outputv.
NOTE: Inputs and outputs are indexed starting at 1 and negative values correspond to a negative feedback
interconnection.
Parameters
• sys (StateSpace Transferfunction) – System to be connected
• Q (2D array) – Interconnection matrix. First column gives the input to be connected
second column gives the output to be fed into this input. Negative values for the second
column mean the feedback is negative, 0 means no connection is made. Inputs and outputs
are indexed starting at 1.
• inputv (1D array) – list of final external inputs
• outputv (1D array) – list of final external outputs
Returns sys – Connected and trimmed LTI system
Examples
>>> sys1 = ss([[1., -2], [3., -4]], [[5.], [7]], [[6, 8]], [[9.]])
>>> sys2 = ss([[-1.]], [[1.]], [[1.]], [[0.]])
>>> Q = [[1, 2], [2, -1]] # negative feedback interconnection
>>> sysc = connect(sys, Q, [2], [1, 2])
5.3.6 control.matlab.append
control.matlab.append(sys1, sys2, ..., sysn)

Group models by appending their inputs and outputs
Forms an augmented system model, and appends the inputs and outputs together. The system type will be the
type of the first system given; if you mix state-space systems and gain matrices, make sure the gain matrices are
not first.
Parameters sys2, .., sysn (sys1,) – LTI systems to combine
Returns sys – Combined LTI system, with input/output vectors consisting of all input/output vectors
appended

Examples
>>> sys1 = ss([[1., -2], [3., -4]], [[5.], [7]]", [[6., 8]], [[9.]])
>>> sys2 = ss([[-1.]], [[1.]], [[1.]], [[0.]])
5.4 System gain and dynamics
dcgain(*args) Compute the gain of the system in steady state.

pole(sys) Compute system poles.
zero(sys) Compute system zeros.
damp(sys[, doprint]) Compute natural frequency, damping ratio, and poles of
a system
pzmap(sys[, plot, grid, title]) Plot a pole/zero map for a linear system.
5.4.1 control.matlab.dcgain
control.matlab.dcgain(*args)
Compute the gain of the system in steady state.
The function takes either 1, 2, 3, or 4 parameters:
Parameters
• B, C, D (A,) – A linear system in state space form.
• P, k (Z,) – A linear system in zero, pole, gain form.
• den (num,) – A linear system in transfer function form.
• sys (LTI (StateSpace or TransferFunction)) – A linear system object.
Returns gain – The gain of each output versus each input: 𝑦 = 𝑔𝑎𝑖𝑛 · 𝑢
Return type ndarray
Notes
This function is only useful for systems with invertible system matrix A.
All systems are first converted to state space form. The function then computes:
𝑔𝑎𝑖𝑛 = −𝐶 · 𝐴−1 · 𝐵 + 𝐷
5.4.2 control.matlab.pole
control.matlab.pole(sys)
Compute system poles.
Returns poles – Array that contains the system’s poles.
Return type ndarray

Raises NotImplementedError – when called on a TransferFunction object

See also:
zero(), TransferFunction.pole(), StateSpace.pole()
5.4.3 control.matlab.zero
control.matlab.zero(sys)
Compute system zeros.
Returns zeros – Array that contains the system’s zeros.
Return type ndarray
Raises NotImplementedError – when called on a MIMO system
See also:
pole(), StateSpace.zero(), TransferFunction.zero()
5.4.4 control.matlab.damp
control.matlab.damp(sys, doprint=True)
Compute natural frequency, damping ratio, and poles of a system
The function takes 1 or 2 parameters
Parameters
• sys (LTI (StateSpace or TransferFunction)) – A linear system object
• doprint – if true, print table with values
Returns
• wn (array) – Natural frequencies of the poles
• damping (array) – Damping values
• poles (array) – Pole locations
• Algorithm
• ———
• If the system is continuous, – wn = abs(poles) Z = -real(poles)/poles.
• If the system is discrete, the discrete poles are mapped to their
• equivalent location in the s-plane via – s = log10(poles)/dt
• and – wn = abs(s) Z = -real(s)/wn.
See also:
pole()
5.4. System gain and dynamics 93

5.4.5 control.matlab.pzmap
control.matlab.pzmap(sys, plot=True, grid=False, title=’Pole Zero Map’, **kwargs)

Plot a pole/zero map for a linear system.
Parameters
• sys (LTI (StateSpace or TransferFunction)) – Linear system for which
poles and zeros are computed.
• plot (bool) – If True a graph is generated with Matplotlib, otherwise the poles and zeros
are only computed and returned.
• grid (boolean (default = False)) – If True plot omega-damping grid.
Returns
• pole (array) – The systems poles
• zeros (array) – The system’s zeros.
5.5 Time-domain analysis
step(sys[, T, X0, input, output, return_x]) Step response of a linear system

impulse(sys[, T, X0, input, output, return_x]) Impulse response of a linear system
initial(sys[, T, X0, input, output, return_x]) Initial condition response of a linear system
lsim(sys[, U, T, X0]) Simulate the output of a linear system.
5.5.1 control.matlab.step
control.matlab.step(sys, T=None, X0=0.0, input=0, output=None, return_x=False)

Step response of a linear system
one output may be selected. If no selection is made for the output, all outputs are given. The parameters input
and output do this. All other inputs are set to 0, all other outputs are ignored.
Parameters
not given)
• output (int) – If given, index of the output that is returned by this simulation.
Returns
• xout (array (if selected)) – Individual response of each x variable

See also:
lsim(), initial(), impulse()
Examples
>>> yout, T = step(sys, T, X0)
5.5.2 control.matlab.impulse
control.matlab.impulse(sys, T=None, X0=0.0, input=0, output=None, return_x=False)

Impulse response of a linear system
one output may be selected. If no selection is made for the output, all outputs are given. The parameters input
and output do this. All other inputs are set to 0, all other outputs are ignored.
Parameters
• sys (StateSpace, TransferFunction) – LTI system to simulate
not given)
• output (int) – Index of the output that will be used in this simulation.
Returns
See also:
lsim(), step(), initial()
Examples
>>> yout, T = impulse(sys, T)
5.5.3 control.matlab.initial
control.matlab.initial(sys, T=None, X0=0.0, input=None, output=None, return_x=False)

Initial condition response of a linear system
If the system has multiple outputs (?IMO), optionally, one output may be selected. If no selection is made for
the output, all outputs are given.
Parameters
5.5. Time-domain analysis 95


not given)
0)
• input (int) – This input is ignored, but present for compatibility with step and impulse.
• output (int) – If given, index of the output that is returned by this simulation.
Returns
See also:
lsim(), step(), impulse()
Examples
>>> yout, T = initial(sys, T, X0)
5.5.4 control.matlab.lsim
control.matlab.lsim(sys, U=0.0, T=None, X0=0.0)

Simulate the output of a linear system.
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.
Parameters
• sys (LTI (StateSpace, or TransferFunction)) – LTI system to simulate
(default = 0).
If U is None or 0, a special algorithm is used. This special algorithm is faster than the
general algorithm, which is used otherwise.
• T (array-like) – Time steps at which the input is defined, numbers must be (strictly
monotonic) increasing.
Returns
• xout (array) – Time evolution of the state vector.
See also:
step(), initial(), impulse()

Examples
>>> yout, T, xout = lsim(sys, U, T, X0)
5.6 Frequency-domain analysis
bode(syslist[, omega, dB, Hz, deg, . . . ]) Bode plot of the frequency response
nyquist(syslist[, omega, plot, label_freq, . . . ]) Nyquist plot for a system
nichols(sys_list[, omega, grid]) Nichols plot for a system
margin(sysdata) Calculate gain and phase margins and associated
crossover frequencies
freqresp(sys, omega) Frequency response of an LTI system at multiple angu-
lar frequencies.
evalfr(sys, x) Evaluate the transfer function of an LTI system for a
single complex number x.
5.6.1 control.matlab.bode
control.matlab.bode(syslist[, omega, dB, Hz, deg, ... ])

Bode plot of the frequency response
Plots a bode gain and phase diagram
Parameters
• sys (LTI, or list of LTI) – System for which the Bode response is plotted and
give. Optionally a list of systems can be entered, or several systems can be specified (i.e.
several parameters). The sys arguments may also be interspersed with format strings. A fre-
quency argument (array_like) may also be added, some examples: * >>> bode(sys, w) # one
system, freq vector * >>> bode(sys1, sys2, . . . , sysN) # several systems * >>> bode(sys1,
sys2, . . . , sysN, w) * >>> bode(sys1, ‘plotstyle1’, . . . , sysN, ‘plotstyleN’) # + plot formats
• omega (freq_range) – Range of frequencies in rad/s
• dB (boolean) – If True, plot result in dB
• Hz (boolean) – If True, plot frequency in Hz (omega must be provided in rad/sec)
• deg (boolean) – If True, return phase in degrees (else radians)
• Plot (boolean) – If True, plot magnitude and phase
Examples
>>> sys = ss("1. -2; 3. -4", "5.; 7", "6. 8", "9.")
>>> mag, phase, omega = bode(sys)
Todo: Document these use cases
• >>> bode(sys, w)
5.6. Frequency-domain analysis 97

• >>> bode(sys1, sys2, ..., sysN)
• >>> bode(sys1, sys2, ..., sysN, w)
• >>> bode(sys1, 'plotstyle1', ..., sysN, 'plotstyleN')
5.6.2 control.matlab.nyquist
control.matlab.nyquist(syslist, omega=None, plot=True, label_freq=0, arrowhead_length=0.1, ar-

rowhead_width=0.1, color=None, *args, **kwargs)
Nyquist plot for a system
Plots a Nyquist plot for the system over a (optional) frequency range.
Parameters
• syslist (list of LTI) – List of linear input/output systems (single system is OK)
• omega (freq_range) – Range of frequencies (list or bounds) in rad/sec
• Plot (boolean) – If True, plot magnitude
• color (string) – Used to specify the color of the plot
• label_freq (int) – Label every nth frequency on the plot
• arrowhead_width (arrow head width) –
• arrowhead_length (arrow head length) –
to matplotlib)
Returns
• real (array) – real part of the frequency response array
• imag (array) – imaginary part of the frequency response array
• freq (array) – frequencies
Examples
>>> sys = ss("1. -2; 3. -4", "5.; 7", "6. 8", "9.")
>>> real, imag, freq = nyquist_plot(sys)
5.6.3 control.matlab.nichols
control.matlab.nichols(sys_list, omega=None, grid=None)

Nichols plot for a system
Plots a Nichols plot for the system over a (optional) frequency range.
Parameters

• sys_list (list of LTI, or LTI) – List of linear input/output systems (single sys-
tem is OK)
• omega (array_like) – Range of frequencies (list or bounds) in rad/sec
• grid (boolean, optional) – True if the plot should include a Nichols-chart grid.
Default is True.
Returns
Return type None
5.6.4 control.matlab.margin
control.matlab.margin(sysdata)
Calculate gain and phase margins and associated crossover frequencies
Parameters sysdata (LTI system or (mag, phase, omega) sequence) –
sys [StateSpace or TransferFunction] Linear SISO system
mag, phase, omega [sequence of array_like] Input magnitude, phase (in deg.), and frequencies
(rad/sec) from bode frequency response data
Returns
• gm (float) – Gain margin
• pm (float) – Phase margin (in degrees)
• wg (float) – Frequency for gain margin (at phase crossover, phase = -180 degrees)
• wp (float) – Frequency for phase margin (at gain crossover, gain = 1)
• Margins are calculated for a SISO open-loop system.
• If there is more than one gain crossover, the one at the smallest
• margin (deviation from gain = 1), in absolute sense, is
• returned. Likewise the smallest phase margin (in absolute sense)
• is returned.
Examples
>>> sys = tf(1, [1, 2, 1, 0])

>>> gm, pm, wg, wp = margin(sys)
5.6.5 control.matlab.freqresp
control.matlab.freqresp(sys, omega)
Frequency response of an LTI system at multiple angular frequencies.
Parameters
• omega (array_like) – List of frequencies
Returns
5.6. Frequency-domain analysis 99

• mag (ndarray)
• phase (ndarray)
• omega (list, tuple, or ndarray)
See also:
evalfr(), bode()
Notes
This function is a wrapper for StateSpace.freqresp and TransferFunction.freqresp. The output omega is a sorted
version of the input omega.
Examples
>>> sys = ss("1. -2; 3. -4", "5.; 7", "6. 8", "9.")
>>> mag, phase, omega = freqresp(sys, [0.1, 1., 10.])
>>> mag
array([[[ 58.8576682 , 49.64876635, 13.40825927]]])
>>> phase
array([[[-0.05408304, -0.44563154, -0.66837155]]])

#>>> sys = rss(3, 2, 2) #>>> mag, phase, omega = freqresp(sys, [0.1, 1., 10.]) #>>> mag[0, 1, :] #array([
55.43747231, 42.47766549, 1.97225895]) #>>> phase[1, 0, :] #array([-0.12611087, -1.14294316, 2.5764547
]) #>>> # This is the magnitude of the frequency response from the 2nd #>>> # input to the 1st output, and the
phase (in radians) of the #>>> # frequency response from the 1st input to the 2nd output, for #>>> # s = 0.1i, i,
10i.
5.6.6 control.matlab.evalfr
control.matlab.evalfr(sys, x)
Evaluate the transfer function of an LTI system for a single complex number x.
To evaluate at a frequency, enter x = omega*j, where omega is the frequency in radians
Parameters
• x (scalar) – Complex number
Returns fresp
Return type ndarray
See also:
freqresp(), bode()
Notes
This function is a wrapper for StateSpace.evalfr and TransferFunction.evalfr.

Examples
>>> sys = ss("1. -2; 3. -4", "5.; 7", "6. 8", "9.")
>>> evalfr(sys, 1j)
array([[ 44.8-21.4j]])
>>> # This is the transfer function matrix evaluated at s = i.
5.7 Compensator design
rlocus(sys[, kvect, xlim, ylim, plotstr, . . . ]) Root locus plot

sisotool(sys[, kvect, xlim_rlocus, . . . ]) Sisotool style collection of plots inspired by MATLAB’s
sisotool.
place(A, B, p) Place closed loop eigenvalues K = place(A, B, p)
lqr(A, B, Q, R[, N]) Linear quadratic regulator design
5.7.1 control.matlab.rlocus
control.matlab.rlocus(sys, kvect=None, xlim=None, ylim=None, plotstr=None, plot=True,

print_gain=None, grid=None, **kwargs)
Root locus plot
Calculate the root locus by finding the roots of 1+k*TF(s) where TF is self.num(s)/self.den(s) and each k is an
element of kvect.
Parameters
• sys (LTI object) – Linear input/output systems (SISO only, for now).
• kvect (list or ndarray, optional) – List of gains to use in computing diagram.
• xlim (tuple or list, optional) – Set limits of x axis, normally with tuple (see
matplotlib.axes).
• ylim (tuple or list, optional) – Set limits of y axis, normally with tuple (see
matplotlib.axes).
• plot (boolean, optional) – If True (default), plot root locus diagram.
• print_gain (bool) – If True (default), report mouse clicks when close to the root locus
branches, calculate gain, damping and print.
• grid (bool) – If True plot omega-damping grid. Default is False.
Returns
• rlist (ndarray) – Computed root locations, given as a 2D array
• klist (ndarray or list) – Gains used. Same as klist keyword argument if provided.
5.7. Compensator design 101

5.7.2 control.matlab.sisotool
control.matlab.sisotool(sys, kvect=None, xlim_rlocus=None, ylim_rlocus=None, plot-

str_rlocus=’C0’, rlocus_grid=False, omega=None, dB=None, Hz=None,
deg=None, omega_limits=None, omega_num=None, margins_bode=True,
tvect=None)
Sisotool style collection of plots inspired by MATLAB’s sisotool. The left two plots contain the bode magnitude
and phase diagrams. The top right plot is a clickable root locus plot, clicking on the root locus will change the
gain of the system. The bottom left plot shows a closed loop time response.
Parameters
• sys (LTI object) – Linear input/output systems (SISO only)
• kvect (list or ndarray, optional) – List of gains to use for plotting root locus
• xlim_rlocus (tuple or list, optional) – control of x-axis range, normally
with tuple (see matplotlib.axes)
• ylim_rlocus (tuple or list, optional) – control of y-axis range
• plotstr_rlocus (Additional options to matplotlib) – plotting style for
the root locus plot(color, linestyle, etc)
• rlocus_grid (boolean (default = False)) – If True plot s-plane grid.
• omega (freq_range) – Range of frequencies in rad/sec for the bode plot
• dB (boolean) – If True, plot result in dB for the bode plot
• Hz (boolean) – If True, plot frequency in Hz for the bode plot (omega must be provided
in rad/sec)
• deg (boolean) – If True, plot phase in degrees for the bode plot (else radians)
• omega_num (int) – number of samples
• margins_bode (boolean) – If True, plot gain and phase margin in the bode plot
• tvect (list or ndarray, optional) – List of timesteps to use for closed loop
step response
Examples
>>> sys = tf([1000], [1,25,100,0])

>>> sisotool(sys)
5.7.3 control.matlab.place
control.matlab.place(A, B, p)
Place closed loop eigenvalues K = place(A, B, p)
Parameters
• A (2-d array) – Dynamics matrix
• B (2-d array) – Input matrix

• p (1-d list) – Desired eigenvalue locations

Returns
• K (2-d array) – Gain such that A - B K has eigenvalues given in p
• Algorithm
• ———
• This is a wrapper function for scipy.signal.place_poles, which
• implements the Tits and Yang algorithm [1]. It will handle SISO,
• MISO, and MIMO systems. If you want more control over the algorithm,
• use scipy.signal.place_poles directly.
• [1] A.L. Tits and Y. Yang, “Globally convergent algorithms for robust
• pole assignment by state feedback, IEEE Transactions on Automatic
• Control, Vol. 41, pp. 1432-1452, 1996.
• Limitations
• ———–
• The algorithm will not place poles at the same location more
• than rank(B) times.
Examples
>>> A = [[-1, -1], [0, 1]]

>>> B = [[0], [1]]
>>> K = place(A, B, [-2, -5])
See also:
place_varga(), acker()
5.7.4 control.matlab.lqr
control.matlab.lqr(A, B, Q, R[, N ])
Linear quadratic regulator design
The lqr() function computes the optimal state feedback controller that minimizes the quadratic cost
∫︁ ∞
𝐽= (𝑥′ 𝑄𝑥 + 𝑢′ 𝑅𝑢 + 2𝑥′ 𝑁 𝑢)𝑑𝑡
0
The function can be called with either 3, 4, or 5 arguments:

• lqr(sys, Q, R)
• lqr(sys, Q, R, N)
• lqr(A, B, Q, R)
• lqr(A, B, Q, R, N)
where sys is an LTI object, and A, B, Q, R, and N are 2d arrays or matrices of appropriate dimension.
5.7. Compensator design 103

Parameters
• B (A,) – Dynamics and input matrices
• sys (LTI (StateSpace or TransferFunction)) – Linear I/O system
• R (Q,) – State and input weight matrices
• N (2-d array, optional) – Cross weight matrix
Returns
• K (2D array) – State feedback gains
• S (2D array) – Solution to Riccati equation
• E (1D array) – Eigenvalues of the closed loop system
Examples
>>> K, S, E = lqr(sys, Q, R, [N])

>>> K, S, E = lqr(A, B, Q, R, [N])
See also:
lqe()
5.8 State-space (SS) models
ctrb(A, B) Controllabilty matrix
obsv(A, C) Observability matrix
gram(sys, type) Gramian (controllability or observability)
5.8.1 control.matlab.ctrb
control.matlab.ctrb(A, B)
Controllabilty matrix
Parameters B (A,) – Dynamics and input matrix of the system
Returns C – Controllability matrix
Return type matrix
Examples
>>> C = ctrb(A, B)
5.8.2 control.matlab.obsv
control.matlab.obsv(A, C)
Observability matrix

Parameters C (A,) – Dynamics and output matrix of the system

Returns O – Observability matrix
Return type matrix
Examples
>>> O = obsv(A, C)
5.8.3 control.matlab.gram
control.matlab.gram(sys, type)
Gramian (controllability or observability)
Parameters
• sys (StateSpace) – State-space system to compute Gramian for
• type (String) – Type of desired computation. type is either ‘c’ (controllability) or ‘o’
(observability). To compute the Cholesky factors of gramians use ‘cf’ (controllability) or
‘of’ (observability)
Returns gram – Gramian of system
Return type array
Raises
• ValueError – * if system is not instance of StateSpace class * if type is not ‘c’, ‘o’, ‘cf’
or ‘of’ * if system is unstable (sys.A has eigenvalues not in left half plane)
• ImportError – if slycot routine sb03md cannot be found if slycot routine sb03od cannot
be found
Examples
>>> Wc = gram(sys,'c')
>>> Wo = gram(sys,'o')
>>> Rc = gram(sys,'cf'), where Wc=Rc'*Rc
>>> Ro = gram(sys,'of'), where Wo=Ro'*Ro
5.9 Model simplification
minreal(sys[, tol, verbose]) Eliminates uncontrollable or unobservable states in

state-space models or cancelling pole-zero pairs in
transfer functions.
hsvd(sys) Calculate the Hankel singular values.
balred(sys, orders[, method, alpha]) Balanced reduced order model of sys of a given order.
modred(sys, ELIM[, method]) Model reduction of sys by eliminating the states in
ELIM using a given method.
5.9. Model simplification 105


era(YY, m, n, nin, nout, r) Calculate an ERA model of order r based on the
impulse-response data YY.
markov(Y, U, m) Calculate the first M Markov parameters [D CB CAB
. . . ] from input U, output Y.
5.9.1 control.matlab.minreal
control.matlab.minreal(sys, tol=None, verbose=True)

Eliminates uncontrollable or unobservable states in state-space models or cancelling pole-zero pairs in transfer
functions. The output sysr has minimal order and the same response characteristics as the original model sys.
Parameters
• sys (StateSpace or TransferFunction) – Original system
• tol (real) – Tolerance
• verbose (bool) – Print results if True
Returns rsys – Cleaned model
5.9.2 control.matlab.hsvd
control.matlab.hsvd(sys)
Calculate the Hankel singular values.
Parameters sys (StateSpace) – A state space system
Returns H – A list of Hankel singular values
Return type array
See also:
gram()
Notes
The Hankel singular values are the singular values of the Hankel operator. In practice, we compute the square
root of the eigenvalues of the matrix formed by taking the product of the observability and controllability grami-
ans. There are other (more efficient) methods based on solving the Lyapunov equation in a particular way (more
details soon).
Examples
>>> H = hsvd(sys)
5.9.3 control.matlab.balred
control.matlab.balred(sys, orders, method=’truncate’, alpha=None)

Balanced reduced order model of sys of a given order. States are eliminated based on Hankel singular value. If

sys has unstable modes, they are removed, the balanced realization is done on the stable part, then reinserted in
accordance with the reference below.
Reference: Hsu,C.S., and Hou,D., 1991, Reducing unstable linear control systems via real Schur transformation.
Electronics Letters, 27, 984-986.
Parameters
• orders (integer or array of integer) – Desired order of reduced order model
(if a vector, returns a vector of systems)
• method (string) – Method of removing states, either 'truncate' or 'matchdc'.
• alpha (float) – Redefines the stability boundary for eigenvalues of the system matrix
A. By default for continuous-time systems, alpha <= 0 defines the stability boundary for
the real part of A’s eigenvalues and for discrete-time systems, 0 <= alpha <= 1 defines the
stability boundary for the modulus of A’s eigenvalues. See SLICOT routines AB09MD and
AB09ND for more information.
Returns rsys – A reduced order model or a list of reduced order models if orders is a list
Raises
• ValueError – * if method is not 'truncate' or 'matchdc'
• ImportError – if slycot routine ab09ad, ab09md, or ab09nd is not found
• ValueError – if there are more unstable modes than any value in orders
Examples
>>> rsys = balred(sys, orders, method='truncate')
5.9.4 control.matlab.modred
control.matlab.modred(sys, ELIM, method=’matchdc’)

Model reduction of sys by eliminating the states in ELIM using a given method.
Parameters
• ELIM (array) – Vector of states to eliminate
• method (string) – Method of removing states in ELIM: either 'truncate' or
'matchdc'.
Returns rsys – A reduced order model
Raises ValueError – Raised under the following conditions:
• if method is not either 'matchdc' or 'truncate'
• if eigenvalues of sys.A are not all in left half plane (sys must be stable)
5.9. Model simplification 107

Examples
>>> rsys = modred(sys, ELIM, method='truncate')
5.9.5 control.matlab.era
control.matlab.era(YY, m, n, nin, nout, r)

Calculate an ERA model of order r based on the impulse-response data YY.
Note: This function is not implemented yet.
Parameters
• YY (array) – nout x nin dimensional impulse-response data
• m (integer) – Number of rows in Hankel matrix
• n (integer) – Number of columns in Hankel matrix
• nin (integer) – Number of input variables
• nout (integer) – Number of output variables
• r (integer) – Order of model
Returns sys – A reduced order model sys=ss(Ar,Br,Cr,Dr)
Examples
>>> rsys = era(YY, m, n, nin, nout, r)
5.9.6 control.matlab.markov
control.matlab.markov(Y, U, m)
Calculate the first M Markov parameters [D CB CAB . . . ] from input U, output Y.
Parameters
• Y (array_like) – Output data
• U (array_like) – Input data
• m (int) – Number of Markov parameters to output
Returns H – First m Markov parameters
Return type ndarray
Notes
Currently only works for SISO

Examples
>>> H = markov(Y, U, m)
5.10 Time delays
pade(T[, n, numdeg]) Create a linear system that approximates a delay.
5.10.1 control.matlab.pade
control.matlab.pade(T, n=1, numdeg=None)

Create a linear system that approximates a delay.
Return the numerator and denominator coefficients of the Pade approximation.
Parameters
• T (number) – time delay
• n (positive integer) – degree of denominator of approximation
• numdeg (integer, or None (the default)) – If None, numerator degree
equals denominator degree If >= 0, specifies degree of numerator If < 0, numerator degree
is n+numdeg
Returns num, den – Polynomial coefficients of the delay model, in descending powers of s.
Return type array
Notes
Based on:
1. Algorithm 11.3.1 in Golub and van Loan, “Matrix Computation” 3rd. Ed. pp. 572-574
2. M. Vajta, “Some remarks on Padé-approximations”, 3rd TEMPUS-INTCOM Symposium
5.11 Matrix equation solvers and linear algebra
lyap(A, Q[, C, E]) X = lyap(A, Q) solves the continuous-time Lyapunov

equation
dlyap(A, Q[, C, E]) dlyap(A,Q) solves the discrete-time Lyapunov equation
care(A, B, Q[, R, S, E, stabilizing]) (X,L,G) = care(A,B,Q,R=None) solves the continuous-
time algebraic Riccati equation
dare(A, B, Q, R[, S, E, stabilizing]) (X,L,G) = dare(A,B,Q,R) solves the discrete-time alge-
braic Riccati equation
5.11.1 control.matlab.lyap
control.matlab.lyap(A, Q, C=None, E=None)

X = lyap(A, Q) solves the continuous-time Lyapunov equation
5.11. Matrix equation solvers and linear algebra 109

𝐴𝑋 + 𝑋𝐴𝑇 + 𝑄 = 0
where A and Q are square matrices of the same dimension. Further, Q must be symmetric.
X = lyap(A,Q,C) solves the Sylvester equation
𝐴𝑋 + 𝑋𝑄 + 𝐶 = 0
X = lyap(A,Q,None,E) solves the generalized continuous-time Lyapunov equation
𝐴𝑋𝐸 𝑇 + 𝐸𝑋𝐴𝑇 + 𝑄 = 0
5.11.2 control.matlab.dlyap
control.matlab.dlyap(A, Q, C=None, E=None)

dlyap(A,Q) solves the discrete-time Lyapunov equation
𝐴𝑋𝐴𝑇 − 𝑋 + 𝑄 = 0
where A and Q are square matrices of the same dimension. Further Q must be symmetric.
dlyap(A,Q,C) solves the Sylvester equation
𝐴𝑋𝑄𝑇 − 𝑋 + 𝐶 = 0
dlyap(A,Q,None,E) solves the generalized discrete-time Lyapunov equation
𝐴𝑋𝐴𝑇 − 𝐸𝑋𝐸 𝑇 + 𝑄 = 0
5.11.3 control.matlab.care
control.matlab.care(A, B, Q, R=None, S=None, E=None, stabilizing=True)

(X,L,G) = care(A,B,Q,R=None) solves the continuous-time algebraic Riccati equation
𝐴𝑇 𝑋 + 𝑋𝐴 − 𝑋𝐵𝑅−1 𝐵 𝑇 𝑋 + 𝑄 = 0
where A and Q are square matrices of the same dimension. Further, Q and R are a symmetric matrices. If R is
None, it is set to the identity matrix. The function returns the solution X, the gain matrix G = B^T X and the
closed loop eigenvalues L, i.e., the eigenvalues of A - B G.
(X,L,G) = care(A,B,Q,R,S,E) solves the generalized continuous-time algebraic Riccati equation
𝐴𝑇 𝑋𝐸 + 𝐸 𝑇 𝑋𝐴 − (𝐸 𝑇 𝑋𝐵 + 𝑆)𝑅−1 (𝐵 𝑇 𝑋𝐸 + 𝑆 𝑇 ) + 𝑄 = 0
where A, Q and E are square matrices of the same dimension. Further, Q and R are symmetric matrices. If R is
None, it is set to the identity matrix. The function returns the solution X, the gain matrix G = R^-1 (B^T X E +
S^T) and the closed loop eigenvalues L, i.e., the eigenvalues of A - B G , E.
5.11.4 control.matlab.dare
control.matlab.dare(A, B, Q, R, S=None, E=None, stabilizing=True)

(X,L,G) = dare(A,B,Q,R) solves the discrete-time algebraic Riccati equation
𝐴𝑇 𝑋𝐴 − 𝑋 − 𝐴𝑇 𝑋𝐵(𝐵 𝑇 𝑋𝐵 + 𝑅)−1 𝐵 𝑇 𝑋𝐴 + 𝑄 = 0

where A and Q are square matrices of the same dimension. Further, Q is a symmetric matrix. The function
returns the solution X, the gain matrix G = (B^T X B + R)^-1 B^T X A and the closed loop eigenvalues L, i.e.,
the eigenvalues of A - B G.
(X,L,G) = dare(A,B,Q,R,S,E) solves the generalized discrete-time algebraic Riccati equation
𝐴𝑇 𝑋𝐴 − 𝐸 𝑇 𝑋𝐸 − (𝐴𝑇 𝑋𝐵 + 𝑆)(𝐵 𝑇 𝑋𝐵 + 𝑅)−1 (𝐵 𝑇 𝑋𝐴 + 𝑆 𝑇 ) + 𝑄 = 0
where A, Q and E are square matrices of the same dimension. Further, Q and R are symmetric matrices. The
function returns the solution X, the gain matrix 𝐺 = (𝐵 𝑇 𝑋𝐵 + 𝑅)−1 (𝐵 𝑇 𝑋𝐴 + 𝑆 𝑇 ) and the closed loop
eigenvalues L, i.e., the eigenvalues of A - B G , E.
5.12 Additional functions
gangof4(P, C[, omega]) Plot the “Gang of 4” transfer functions for a system
unwrap(angle[, period]) Unwrap a phase angle to give a continuous curve
5.12.1 control.matlab.gangof4
control.matlab.gangof4(P, C, omega=None, **kwargs)

Plot the “Gang of 4” transfer functions for a system
Generates a 2x2 plot showing the “Gang of 4” sensitivity functions [T, PS; CS, S]
Parameters
• C (P,) – Linear input/output systems (process and control)
• omega (array) – Range of frequencies (list or bounds) in rad/sec
to matplotlib)
Returns
Return type None
5.12.2 control.matlab.unwrap
control.matlab.unwrap(angle, period=6.283185307179586)
Unwrap a phase angle to give a continuous curve
Parameters
• angle (array_like) – Array of angles to be unwrapped
• period (float, optional) – Period (defaults to 2*pi)
Returns angle_out – Output array, with jumps of period/2 eliminated
Return type array_like
Examples
5.12. Additional functions 111

>>> import numpy as np

>>> theta = [5.74, 5.97, 6.19, 0.13, 0.35, 0.57]
>>> unwrap(theta, period=2 * np.pi)
[5.74, 5.97, 6.19, 6.413185307179586, 6.633185307179586, 6.8531853071795865]
5.13 Functions imported from other modules
linspace(start, stop[, num, endpoint, . . . ]) Return evenly spaced numbers over a specified interval.
logspace(start, stop[, num, endpoint, base, . . . ]) Return numbers spaced evenly on a log scale.
ss2zpk(A, B, C, D[, input]) State-space representation to zero-pole-gain representa-
tion.
tf2zpk(b, a) Return zero, pole, gain (z, p, k) representation from a
numerator, denominator representation of a linear filter.
zpk2ss(z, p, k) Zero-pole-gain representation to state-space representa-
tion
zpk2tf(z, p, k) Return polynomial transfer function representation from
zeros and poles

CHAPTER 6
Differentially flat systems
The control.flatsys package contains a set of classes and functions that can be used to compute trajectories for
differentially flat systems.
A differentially flat system is defined by creating an object using the FlatSystem class, which has member functions
for mapping the system state and input into and out of flat coordinates. The point_to_point() function can be
used to create a trajectory between two endpoints, written in terms of a set of basis functions defined using the
BasisFamily class. The resulting trajectory is return as a SystemTrajectory object and can be evaluated
using the eval() member function.
6.1 Overview of differential flatness
A nonlinear differential equation of the form
𝑥˙ = 𝑓 (𝑥, 𝑢), 𝑥 ∈ 𝑅𝑛 , 𝑢 ∈ 𝑅𝑚
is differentially flat if there exists a function 𝛼 such that
𝑧 = 𝛼(𝑥, 𝑢, 𝑢˙ . . . , 𝑢(𝑝) )
and we can write the solutions of the nonlinear system as functions of 𝑧 and a finite number of derivatives
˙ . . . , 𝑧 (𝑞) )
𝑥 = 𝛽(𝑧, 𝑧,
˙ . . . , 𝑧 (𝑞) ).
𝑢 = 𝛾(𝑧, 𝑧,
For a differentially flat system, all of the feasible trajectories for the system can be written as functions of a flat output
𝑧(·) and its derivatives. The number of flat outputs is always equal to the number of system inputs.
Differentially flat systems are useful in situations where explicit trajectory generation is required. Since the behavior
of a flat system is determined by the flat outputs, we can plan trajectories in output space, and then map these to
appropriate inputs. Suppose we wish to generate a feasible trajectory for the the nonlinear system
𝑥˙ = 𝑓 (𝑥, 𝑢), 𝑥(0) = 𝑥0 , 𝑥(𝑇 ) = 𝑥𝑓 .
113
If the system is differentially flat then
. . . , 𝑧 (𝑞) (0) = 𝑥0 ,
(︀ )︀
𝑥(0) = 𝛽 𝑧(0), 𝑧(0),
˙
˙ ), . . . , 𝑧 (𝑞) (𝑇 ) = 𝑥𝑓 ,
(︀ )︀
𝑥(𝑇 ) = 𝛾 𝑧(𝑇 ), 𝑧(𝑇
and we see that the initial and final condition in the full state space depends on just the output 𝑧 and its derivatives at
the initial and final times. Thus any trajectory for 𝑧 that satisfies these boundary conditions will be a feasible trajectory
for the system, using equation~eqref{eq:trajgen:flat2state} to determine the full state space and input trajectories.
In particular, given initial and final conditions on 𝑧 and its derivatives that satisfy the initial and final conditions any
curve 𝑧(·) satisfying those conditions will correspond to a feasible trajectory of the system. We can parameterize the
flat output trajectory using a set of smooth basis functions 𝜓𝑖 (𝑡):
𝑁
∑︁
𝑧(𝑡) = 𝛼𝑖 𝜓𝑖 (𝑡), 𝛼𝑖 ∈ 𝑅
𝑖=1
We seek a set of coefficients 𝛼𝑖 , 𝑖 = 1, . . . , 𝑁 such that 𝑧(𝑡) satisfies the boundary conditions for 𝑥(0) and 𝑥(𝑇 ). The
derivatives of the flat output can be computed in terms of the derivatives of the basis functions:
𝑁
∑︁
𝑧(𝑡)
˙ = 𝛼𝑖 𝜓˙ 𝑖 (𝑡)
𝑖=1
..
.
𝑁
(𝑞)
∑︁
𝑧˙ (𝑞) (𝑡) = 𝛼𝑖 𝜓𝑖 (𝑡).
𝑖=1
We can thus write the conditions on the flat outputs and their derivatives as
⎡ ⎤
𝜓1 (0) 𝜓2 (0) . . . 𝜓𝑁 (0)
⎡ ⎤
𝑧(0)
⎢ 𝜓˙ 1 (0) ˙ ˙
𝜓2 (0) . . . 𝜓𝑁 (0) ⎥ ⎢ 𝑧(0)
⎢ ˙
⎥ ⎥
⎢
. . .
⎥
⎢
.. .. ..
⎥
⎥⎡ ⎤ ⎢ . ⎥
⎢ .
.
⎢ ⎥
⎥ 𝛼1
⎢ ⎥
⎢ (𝑞) (𝑞) (𝑞)
⎢
(𝑞)
⎥
⎢ 𝜓1 (0) 𝜓2 (0) . . . 𝜓𝑁 (0) ⎥ ⎢ . ⎥ ⎢ 𝑧 (0) ⎥
⎥⎣ . ⎦ = ⎢
⎢ ⎥
⎥ .
⎢ ⎥
⎢ 𝜓 (𝑇 ) 𝜓 (𝑇 ) . . . 𝜓 (𝑇 ) 𝑧(𝑇 )
⎢ 1 2 𝑁 ⎢ ⎥
⎥ 𝛼𝑁
⎥
⎢ ˙ ˙ ˙
⎢
𝑧(𝑇
˙ )
⎥
⎢ 𝜓1 (𝑇 ) 𝜓2 (𝑇 ) . . . 𝜓𝑁 (𝑇 ) ⎥ ⎢ ⎥
.
⎢ ⎥
⎢ .
. .
. .
.
⎥ ⎢ . ⎥
⎢
⎣ . . .
⎥
⎦ ⎣ . ⎦
(𝑞) (𝑞)
𝜓 (𝑇 ) 𝜓 (𝑇 ) . . . 𝜓 (𝑇 )
(𝑞) 𝑧 (𝑞) (𝑇 )
1 2 𝑁
This equation is a linear equation of the form

[︂
]︂
𝑧¯(0)
𝑀𝛼 =
𝑧¯(𝑇 )
where 𝑧¯ is called the flat flag for the system. Assuming that 𝑀 has a sufficient number of columns and that it is full
column rank, we can solve for a (possibly non-unique) 𝛼 that solves the trajectory generation problem.
6.2 Module usage
To create a trajectory for a differentially flat system, a FlatSystem object must be created. This is done by spec-
ifying the forward and reverse mappings between the system state/input and the differentially flat outputs and their
derivatives (“flat flag”).
The forward() method computes the flat flag given a state and input:
114 Chapter 6. Differentially flat systems

zflag = sys.forward(x, u)
The reverse() method computes the state and input given the flat flag:
x, u = sys.reverse(zflag)
The flag 𝑧¯ is implemented as a list of flat outputs 𝑧𝑖 and their derivatives up to order 𝑞𝑖 :
(𝑗)
zflag[i][j] = 𝑧𝑖
The number of flat outputs must match the number of system inputs.
For a linear system, a flat system representation can be generated using the LinearFlatSystem class:
flatsys = control.flatsys.LinearFlatSystem(linsys)
For more general systems, the FlatSystem object must be created manually
flatsys = control.flatsys.FlatSystem(nstate, ninputs, forward, reverse)
In addition to the flat system descriptionn, a set of basis functions 𝜑𝑖 (𝑡) must be chosen. The FlatBasis class is used
to represent the basis functions. A polynomial basis function of the form 1, 𝑡, 𝑡2 :, ...𝑐𝑎𝑛𝑏𝑒𝑐𝑜𝑚𝑝𝑢𝑡𝑒𝑑𝑢𝑠𝑖𝑛𝑔𝑡ℎ𝑒 class,
which is initialized by passing the desired order of the polynomial basis set:
polybasis = control.flatsys.PolyBasis(N)
Once the system and basis function have been defined, the point_to_point() function can be used to compute a
trajectory between initial and final states and inputs:
traj = control.flatsys.point_to_point(x0, u0, xf, uf, Tf, basis=polybasis)
The returned object has class SystemTrajectory and can be used to compute the state and input trajectory be-
tween the initial and final condition:
xd, ud = traj.eval(T)
where T is a list of times on which the trajectory should be evaluated (e.g., T = numpy.linspace(0, Tf, M).
6.3 Example
To illustrate how we can use a two degree-of-freedom design to improve the performance of the system, consider the
problem of steering a car to change lanes on a road. We use the non-normalized form of the dynamics, which are
derived Feedback Systems by Astrom and Murray, Example 3.11.
import control.flatsys as fs
# Function to take states, inputs and return the flat flag

def vehicle_flat_forward(x, u, params={}):
# Get the parameter values
b = params.get('wheelbase', 3.)
# Create a list of arrays to store the flat output and its derivatives
zflag = [np.zeros(3), np.zeros(3)]
# Flat output is the x, y position of the rear wheels

zflag[0][0] = x[0]
zflag[1][0] = x[1]
# First derivatives of the flat output

zflag[0][1] = u[0] * np.cos(x[2]) # dx/dt
zflag[1][1] = u[0] * np.sin(x[2]) # dy/dt
(continues on next page)
6.3. Example 115

(continued from previous page)
# First derivative of the angle

thdot = (u[0]/b) * np.tan(u[1])
# Second derivatives of the flat output (setting vdot = 0)

zflag[0][2] = -u[0] * thdot * np.sin(x[2])
zflag[1][2] = u[0] * thdot * np.cos(x[2])
return zflag
# Function to take the flat flag and return states, inputs

def vehicle_flat_reverse(zflag, params={}):
# Create a vector to store the state and inputs

x = np.zeros(3)
u = np.zeros(2)
# Given the flat variables, solve for the state

x[0] = zflag[0][0] # x position
x[1] = zflag[1][0] # y position
x[2] = np.arctan2(zflag[1][1], zflag[0][1]) # tan(theta) = ydot/xdot
# And next solve for the inputs

u[0] = zflag[0][1] * np.cos(x[2]) + zflag[1][1] * np.sin(x[2])
u[1] = np.arctan2(
(zflag[1][2] * np.cos(x[2]) - zflag[0][2] * np.sin(x[2])), u[0]/b)
return x, u
vehicle_flat = fs.FlatSystem(
3, 2, forward=vehicle_flat_forward, reverse=vehicle_flat_reverse)
To find a trajectory from an initial state 𝑥0 to a final state 𝑥f in time 𝑇f we solve a point-to-point trajectory generation
problem. We also set the initial and final inputs, whi ch sets the vehicle velocity 𝑣 and steering wheel angle 𝛿 at the
endpoints.
# Define the endpoints of the trajectory

x0 = [0., -2., 0.]; u0 = [10., 0.]
xf = [100., 2., 0.]; uf = [10., 0.]
Tf = 10
# Define a set of basis functions to use for the trajectories

poly = fs.PolyFamily(6)
# Find a trajectory between the initial condition and the final condition
traj = fs.point_to_point(vehicle_flat, x0, u0, xf, uf, Tf, basis=poly)
# Create the trajectory

t = np.linspace(0, Tf, 100)
x, u = traj.eval(t)

6.4 Module classes and functions
6.4.1 Flat systems classes
BasisFamily(N) Base class for implementing basis functions for flat sys-
tems.
FlatSystem(forward, reverse[, updfcn, . . . ]) Base class for representing a differentially flat system.
LinearFlatSystem(linsys[, inputs, outputs, . . . ])
PolyFamily(N) Polynomial basis functions.
SystemTrajectory(sys, basis[, coeffs, flaglen]) Class representing a system trajectory.
control.flatsys.BasisFamily
class control.flatsys.BasisFamily(N)
Base class for implementing basis functions for flat systems.
A BasisFamily object is used to construct trajectories for a flat system. The class must implement a single
function that computes the jth derivative of the ith basis function at a time t:
(𝑞)
𝑧𝑖 (𝑡) = basis.eval_deriv(self, i, j, t)
__init__(N)
Create a basis family of order N.
Methods
__init__(N) Create a basis family of order N.
control.flatsys.FlatSystem
class control.flatsys.FlatSystem(forward, reverse, updfcn=None, outfcn=None, inputs=None,

outputs=None, states=None, params={}, dt=None,
name=None)
Base class for representing a differentially flat system.
The FlatSystem class is used as a base class to describe differentially flat systems for trajectory generation. The
class must implement two functions:
zflag = flatsys.foward(x, u) This function computes the flag (derivatives) of the flat output. The inputs to this
function are the state ‘x’ and inputs ‘u’ (both 1D arrays). The output should be a 2D array with the
first dimension equal to the number of system inputs and the second dimension of the length required to
represent the full system dynamics (typically the number of states)
x, u = flatsys.reverse(zflag) This function system state and inputs give the the flag (derivatives) of the flat
output. The input to this function is an 2D array whose first dimension is equal to the number of system
inputs and whose second dimension is of length required to represent the full system dynamics (typically
the number of states). The output is the state x and inputs u (both 1D arrays).
A flat system is also an input/output system supporting simulation, composition, and linearization. If the update
and output methods are given, they are used in place of the flat coordinates.
__init__(forward, reverse, updfcn=None, outfcn=None, inputs=None, outputs=None, states=None,
Create a differentially flat input/output system.
6.4. Module classes and functions 117

The FlatIOSystem constructor is used to create an input/output system object that also represents a differ-
entially flat system. The output of the system does not need to be the differentially flat output.
Parameters
• forward (callable) – A function to compute the flat flag given the states and input.
• reverse (callable) – A function to compute the states and input given the flat flag.
• updfcn (callable, optional) – Function returning the state update function
updfcn(t, x, u[, param]) -> array
where x is a 1-D array with shape (nstates,), u is a 1-D array with shape (ninputs,), t is a
float representing the currrent time, and param is an optional dict containing the values of
parameters used by the function. If not specified, the state space update will be computed
using the flat system coordinates.
• outfcn (callable) – Function returning the output at the given state
outfcn(t, x, u[, param]) -> array
where the arguments are the same as for upfcn. If not specified, the output will be the flat
outputs.
system.
format as inputs.
Returns Input/output system object
Methods
__init__(forward, reverse[, updfcn, outfcn, . . . ]) Create a differentially flat input/output system.

systems
not found)


not found)
found)
forward(x, u[, params]) Compute the flat flag given the states and input.
input.
reverse(zflag[, params]) Compute the states and input given the flat flag.
copy()
Parameters
Returns out
find_input(name)
find_output(name)
find_state(name)
forward(x, u, params={})
Compute the flat flag given the states and input.
Given the states and inputs for a system, compute the flat outputs and their derivatives (the flat “flag”) for
the system.
Parameters
• x (list or array) – The state of the system.
• u (list or array) – The input to the system.
• params (dict, optional) – Parameter values for the system. Passed to the evalua-
Returns zflag – For each flat output 𝑧𝑖 , zflag[i] should be an ndarray of length 𝑞𝑖 that contains
the flat output and its first 𝑞𝑖 derivatives.
Return type list of 1D arrays


reverse(zflag, params={})
Compute the states and input given the flat flag.
Parameters
• zflag (list of arrays) – For each flat output 𝑧𝑖 , zflag[i] should be an ndarray of
length 𝑞𝑖 that contains the flat output and its first 𝑞𝑖 derivatives.
• params (dict, optional) – Parameter values for the system. Passed to the evalua-
Returns
• x (1D array) – The state of the system corresponding to the flat flag.
• u (1D array) – The input to the system corresponding to the flat flag.
Parameters
Parameters
Parameters

control.flatsys.LinearFlatSystem
class control.flatsys.LinearFlatSystem(linsys, inputs=None, outputs=None, states=None,

name=None)
__init__(linsys, inputs=None, outputs=None, states=None, name=None)

Define a flat system from a SISO LTI system.
Given a reachable, single-input/single-output, linear time-invariant system, create a differentially flat sys-
tem representation.
Parameters
Returns iosys – Linear system represented as an flat input/output system
Return type LinearFlatSystem
Methods
__init__(linsys[, inputs, outputs, states, name]) Define a flat system from a SISO LTI system.
frequency.
systems
not found)
not found)


found)
forward(x, u) Compute the flat flag given the states and input.
plex variable
input.
reverse(zflag) Compute the states and input given the flat flag.
append(other)
copy()
damp()
Returns
dcgain()
Return type ndarray
evalfr(omega)


Parameters
Returns out
find_input(name)
find_output(name)
find_state(name)
forward(x, u)
Compute the flat flag given the states and input.
See control.flatsys.FlatSystem.forward() for more info.
freqresp(omega)
evaluation.
Returns
response.
horner(s)

Parameters
Default is False.
issiso()
Parameters
minreal(tol=0.0)
pole()
For instance,

>>> out[3][5]
reverse(zflag)
Compute the states and input given the flat flag.
See control.flatsys.FlatSystem.reverse() for more info.
sion are supported.
Parameters


wise
Notes
Examples

Parameters
Parameters

Parameters
zero()
control.flatsys.PolyFamily
class control.flatsys.PolyFamily(N)
Polynomial basis functions.
This class represents the family of polynomials of the form
𝜑𝑖 (𝑡) = 𝑡𝑖
__init__(N)
Create a polynomial basis of order N.
Methods
__init__(N) Create a polynomial basis of order N.

eval_deriv(i, k, t) Evaluate the kth derivative of the ith basis function
at time t.
eval_deriv(i, k, t)
Evaluate the kth derivative of the ith basis function at time t.
control.flatsys.SystemTrajectory
class control.flatsys.SystemTrajectory(sys, basis, coeffs=[], flaglen=[])

Class representing a system trajectory.
The SystemTrajectory class is used to represent the trajectory of a (differentially flat) system. Used by the
point_to_point() function to return a trajectory.
__init__(sys, basis, coeffs=[], flaglen=[])
Initilize a system trajectory object.
Parameters
• sys (FlatSystem) – Flat system object associated with this trajectory.
• basis (BasisFamily) – Family of basis vectors to use to represent the trajectory.
• coeffs (list of 1D arrays, optional) – For each flat output, define the co-
efficients of the basis functions used to represent the trajectory. Defaults to an empty list.

• flaglen (list of ints, optional) – For each flat output, the number of deriva-
tives of the flat output used to define the trajectory. Defaults to an empty list.
Methods
__init__(sys, basis[, coeffs, flaglen]) Initilize a system trajectory object.

eval(tlist) Return the state and input for a trajectory at a list of
times.
eval(tlist)
Return the state and input for a trajectory at a list of times.
Evaluate the trajectory at a list of time points, returning the state and input vectors for the trajectory:
x, u = traj.eval(tlist)
Parameters tlist (1D array) – List of times to evaluate the trajectory.

Returns
• x (2D array) – For each state, the values of the state at the given times.
• u (2D array) – For each input, the values of the input at the given times.
6.4.2 Flat systems functions
point_to_point(sys, x0, u0, xf, uf, Tf[, . . . ]) Compute trajectory between an initial and final condi-
tions.


CHAPTER 7
Input/output systems
The iosys module contains the InputOutputSystem class that represents (possibly nonlinear) input/output sys-
tems. 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.
7.1 Module usage
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_eqpt() 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 defini-
tion 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:
129
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).
7.2 Example
To illustrate the use of the input/output systems module, we create a model for a predator/prey system, following the
notation and parameter values in FBS2e.
We begin by defining the dynamics of the system
import control
import numpy as np
import matplotlib.pyplot as plt
def predprey_rhs(t, x, u, params):

# Parameter setup
a = params.get('a', 3.2)
b = params.get('b', 0.6)
c = params.get('c', 50.)
d = params.get('d', 0.56)
k = params.get('k', 125)
r = params.get('r', 1.6)
# Map the states into local variable names

H = x[0]
L = x[1]
# Compute the control action (only allow addition of food)

u_0 = u if u > 0 else 0
# Compute the discrete updates

dH = (r + u_0) * H * (1 - H/k) - (a * H * L)/(c + H)
dL = b * (a * H * L)/(c + H) - d * L
return [dH, dL]
We now create an input/output system using these dynamics:
io_predprey = control.NonlinearIOSystem(
predprey_rhs, None, inputs=('u'), outputs=('H', 'L'),
states=('H', 'L'), name='predprey')
Note that since we have not specified an output function, the entire state will be used as the output of the system.
The io_predprey system can now be simulated to obtain the open loop dynamics of the system:
X0 = [25, 20] # Initial H, L

T = np.linspace(0, 70, 500) # Simulation 70 years of time
130 Chapter 7. Input/output systems

# Simulate the system

t, y = control.input_output_response(io_predprey, T, 0, X0)
# Plot the response

plt.figure(1)
plt.plot(t, y[0])
plt.plot(t, y[1])
plt.legend(['Hare', 'Lynx'])
plt.show(block=False)
We can also create a feedback controller to stabilize a desired population of the system. We begin by finding the
(unstable) equilibrium point for the system and computing the linearization about that point.
eqpt = control.find_eqpt(io_predprey, X0, 0)

xeq = eqpt[0] # choose the nonzero equilibrium point
lin_predprey = control.linearize(io_predprey, xeq, 0)
We next compute a controller that stabilizes the equilibrium point using eigenvalue placement and computing the
feedforward gain using the number of lynxes as the desired output (following FBS2e, Example 7.5):
K = control.place(lin_predprey.A, lin_predprey.B, [-0.1, -0.2])

A, B = lin_predprey.A, lin_predprey.B
C = np.array([[0, 1]]) # regulated output = number of lynxes
kf = -1/(C @ np.linalg.inv(A - B @ K) @ B)
To construct the control law, we build a simple input/output system that applies a corrective input based on deviations
from the equilibrium point. This system has no dynamics, since it is a static (affine) map, and can constructed using
the ~control.ios.NonlinearIOSystem class:
io_controller = control.NonlinearIOSystem(
None,
lambda t, x, u, params: -K @ (u[1:] - xeq) + kf * (u[0] - xeq[1]),
inputs=('Ld', 'u1', 'u2'), outputs=1, name='control')
The input to the controller is u, consisting of the vector of hare and lynx populations followed by the desired lynx
population.
To connect the controller to the predatory-prey model, we create an InterconnectedSystem:
io_closed = control.InterconnectedSystem(
(io_predprey, io_controller), # systems
connections=(
('predprey.u', 'control.y[0]'),
('control.u1', 'predprey.H'),
('control.u2', 'predprey.L')
),
inplist=('control.Ld'),
outlist=('predprey.H', 'predprey.L', 'control.y[0]')
)
Finally, we simulate the closed loop system:

t, y = control.input_output_response(io_closed, T, 30, [15, 20])
7.2. Example 131


# Plot the response
plt.figure(2)
plt.subplot(2, 1, 1)
plt.plot(t, y[0])
plt.plot(t, y[1])
plt.legend(['Hare', 'Lynx'])
plt.plot(t, y[2])
plt.legend(['input'])
plt.show(block=False)
7.3 Module classes and functions
7.3.1 Input/output system classes
InputOutputSystem([inputs, outputs, states, . . . ]) A class for representing input/output systems.

InterconnectedSystem(syslist[, connections, Interconnection of a set of input/output systems.
. . . ])
LinearIOSystem(linsys[, inputs, outputs, . . . ]) Input/output representation of a linear (state space) sys-
tem.
NonlinearIOSystem(updfcn[, outfcn, inputs, . . . ]) Nonlinear I/O system.
7.3.2 Input/output system functions
find_eqpt(sys, x0[, u0, y0, t, params, iu, . . . ]) Find the equilibrium point for an input/output system.
linearize(sys, xeq[, ueq, t, params]) Linearize an input/output system at a given state and in-
put.
put.
ss2io(*args, **kw) Create an I/O system from a state space linear system.
tf2io(*args, **kw) Convert a transfer function into an I/O system
132 Chapter 7. Input/output systems

CHAPTER 8
Examples
The source code for the examples below are available in the examples/ subdirecory of the source code distribu-
tion. The can also be accessed online via the [python-control GitHub repository](https://github.com/python-control/
python-control/tree/master/examples).
8.1 Python scripts
The following Python scripts document the use of a variety of methods in the Python Control Toolbox on examples
drawn from standard control textbooks and other sources.
8.1.1 Secord order system (MATLAB module example)
This example computes time and frequency responses for a second-order system using the MATLAB compatibility
module.
Code
1 # secord.py - demonstrate some standard MATLAB commands

2 # RMM, 25 May 09
3
4 import os
5 import matplotlib.pyplot as plt # MATLAB plotting functions
6 from control.matlab import * # MATLAB-like functions
7
8 # Parameters defining the system

9 m = 250.0 # system mass
10 k = 40.0 # spring constant
11 b = 60.0 # damping constant
12
13 # System matrices
133

14 A = [[0, 1.], [-k/m, -b/m]]
15 B = [[0], [1/m]]
16 C = [[1., 0]]
17 sys = ss(A, B, C, 0)
18
19 # Step response for the system

20 plt.figure(1)
21 yout, T = step(sys)
22 plt.plot(T.T, yout.T)
23 plt.show(block=False)
24
25 # Bode plot for the system

26 plt.figure(2)
27 mag, phase, om = bode(sys, logspace(-2, 2), Plot=True)
29
30 # Nyquist plot for the system

31 plt.figure(3)
32 nyquist(sys, logspace(-2, 2))
34
35 # Root lcous plot for the system

36 rlocus(sys)
37
38 if 'PYCONTROL_TEST_EXAMPLES' not in os.environ:

39 plt.show()
Notes
1. The environment variable PYCONTROL_TEST_EXAMPLES is used for testing to turn off plotting of the outputs.
8.1.2 Inner/outer control design for vertical takeoff and landing aircraft
This script demonstrates the use of the python-control package for analysis and design of a controller for a vectored
thrust aircraft model that is used as a running example through the text Feedback Systems by Astrom and Murray.
This example makes use of MATLAB compatible commands.
Code
1 # pvtol-nested.py - inner/outer design for vectored thrust aircraft

2 # RMM, 5 Sep 09
3 #
4 # This file works through a fairly complicated control design and
5 # analysis, corresponding to the planar vertical takeoff and landing
6 # (PVTOL) aircraft in Astrom and Murray, Chapter 11. It is intended
7 # to demonstrate the basic functionality of the python-control
8 # package.
9 #
10
11 from __future__ import print_function

12
13 import os
134 Chapter 8. Examples


16 import numpy as np
17
18 # System parameters
19 m = 4 # mass of aircraft
20 J = 0.0475 # inertia around pitch axis
21 r = 0.25 # distance to center of force
22 g = 9.8 # gravitational constant
23 c = 0.05 # damping factor (estimated)
24
25 # Transfer functions for dynamics

26 Pi = tf([r], [J, 0, 0]) # inner loop (roll)
27 Po = tf([1], [m, c, 0]) # outer loop (position)
28
29 #
30 # Inner loop control design
31 #
32 # This is the controller for the pitch dynamics. Goal is to have
33 # fast response for the pitch dynamics so that we can use this as a
34 # control for the lateral dynamics
35 #
36
37 # Design a simple lead controller for the system

38 k, a, b = 200, 2, 50
39 Ci = k*tf([1, a], [1, b]) # lead compensator
40 Li = Pi*Ci
41
42 # Bode plot for the open loop process

43 plt.figure(1)
44 bode(Pi)
45
46 # Bode plot for the loop transfer function, with margins

47 plt.figure(2)
48 bode(Li)
49
50 # Compute out the gain and phase margins

51 #! Not implemented
52 # gm, pm, wcg, wcp = margin(Li)
53
54 # Compute the sensitivity and complementary sensitivity functions

55 Si = feedback(1, Li)
56 Ti = Li*Si
57
58 # Check to make sure that the specification is met

59 plt.figure(3)
60 gangof4(Pi, Ci)
61
62 # Compute out the actual transfer function from u1 to v1 (see L8.2 notes)
63 # Hi = Ci*(1-m*g*Pi)/(1+Ci*Pi)
64 Hi = parallel(feedback(Ci, Pi), -m*g*feedback(Ci*Pi, 1))
65
66 plt.figure(4)
67 plt.clf()
68 plt.subplot(221)
69 bode(Hi)
70
8.1. Python scripts 135


71 # Now design the lateral control system
72 a, b, K = 0.02, 5, 2
73 Co = -K*tf([1, 0.3], [1, 10]) # another lead compensator
74 Lo = -m*g*Po*Co
75
76 plt.figure(5)
77 bode(Lo) # margin(Lo)
78
79 # Finally compute the real outer-loop loop gain + responses

80 L = Co*Hi*Po
81 S = feedback(1, L)
82 T = feedback(L, 1)
83
84 # Compute stability margins

85 gm, pm, wgc, wpc = margin(L)
86 print("Gain margin: %g at %g" % (gm, wgc))
87 print("Phase margin: %g at %g" % (pm, wpc))
88
89 plt.figure(6)
90 plt.clf()
91 bode(L, np.logspace(-4, 3))
92
93 # Add crossover line to the magnitude plot

94 #
95 # Note: in matplotlib before v2.1, the following code worked:
96 #
97 # plt.subplot(211); hold(True);
98 # loglog([1e-4, 1e3], [1, 1], 'k-')
99 #
100 # In later versions of matplotlib the call to plt.subplot will clear the
101 # axes and so we have to extract the axes that we want to use by hand.
102 # In addition, hold() is deprecated so we no longer require it.
103 #
104 for ax in plt.gcf().axes:
105 if ax.get_label() == 'control-bode-magnitude':
106 break
107 ax.semilogx([1e-4, 1e3], 20*np.log10([1, 1]), 'k-')
108
109 #
110 # Replot phase starting at -90 degrees
111 #
112 # Get the phase plot axes
113 for ax in plt.gcf().axes:
114 if ax.get_label() == 'control-bode-phase':
115 break
116
117 # Recreate the frequency response and shift the phase

118 mag, phase, w = freqresp(L, np.logspace(-4, 3))
119 phase = phase - 360
120
121 # Replot the phase by hand

122 ax.semilogx([1e-4, 1e3], [-180, -180], 'k-')
123 ax.semilogx(w, np.squeeze(phase), 'b-')
124 ax.axis([1e-4, 1e3, -360, 0])
125 plt.xlabel('Frequency [deg]')
126 plt.ylabel('Phase [deg]')
127 # plt.set(gca, 'YTick', [-360, -270, -180, -90, 0])


128 # plt.set(gca, 'XTick', [10^-4, 10^-2, 1, 100])
129
130 #
131 # Nyquist plot for complete design
132 #
133 plt.figure(7)
134 plt.clf()
135 nyquist(L, (0.0001, 1000))
136 plt.axis([-700, 5300, -3000, 3000])
137
138 # Add a box in the region we are going to expand

139 plt.plot([-400, -400, 200, 200, -400], [-100, 100, 100, -100, -100], 'r-')
140
141 # Expanded region

142 plt.figure(8)
143 plt.clf()
144 plt.subplot(231)
145 nyquist(L)
146 plt.axis([-10, 5, -20, 20])
147
148 # set up the color

149 color = 'b'
150
151 # Add arrows to the plot

152 # H1 = L.evalfr(0.4); H2 = L.evalfr(0.41);
153 # arrow([real(H1), imag(H1)], [real(H2), imag(H2)], AM_normal_arrowsize, \
154 # 'EdgeColor', color, 'FaceColor', color);
155
156 # H1 = freqresp(L, 0.35); H2 = freqresp(L, 0.36);

157 # arrow([real(H2), -imag(H2)], [real(H1), -imag(H1)], AM_normal_arrowsize, \
158 # 'EdgeColor', color, 'FaceColor', color);
159
160 plt.figure(9)
161 Yvec, Tvec = step(T, np.linspace(0, 20))
162 plt.plot(Tvec.T, Yvec.T)
163
164 Yvec, Tvec = step(Co*S, np.linspace(0, 20))

165 plt.plot(Tvec.T, Yvec.T)
166
167 plt.figure(10)
168 plt.clf()
169 P, Z = pzmap(T, plot=True, grid=True)
170 print("Closed loop poles and zeros: ", P, Z)
171
172 # Gang of Four

173 plt.figure(11)
174 plt.clf()
175 gangof4(Hi*Po, Co)
176

178 plt.show()
Notes
1. Importing print_function from __future__ in line 11 is only required if using Python 2.7.

8.1.3 LQR control design for vertical takeoff and landing aircraft
This script demonstrates the use of the python-control package for analysis and design of a controller for a vectored
thrust aircraft model that is used as a running example through the text Feedback Systems by Astrom and Murray.
This example makes use of MATLAB compatible commands.
Code
1 # pvtol_lqr.m - LQR design for vectored thrust aircraft

2 # RMM, 14 Jan 03
3 #
4 # This file works through an LQR based design problem, using the
5 # planar vertical takeoff and landing (PVTOL) aircraft example from
6 # Astrom and Murray, Chapter 5. It is intended to demonstrate the
7 # basic functionality of the python-control package.
8 #
9
10 import os
14
15 #
16 # System dynamics
17 #
18 # These are the dynamics for the PVTOL system, written in state space
19 # form.
20 #
21
22 # System parameters
23 m = 4 # mass of aircraft
24 J = 0.0475 # inertia around pitch axis
25 r = 0.25 # distance to center of force
26 g = 9.8 # gravitational constant
27 c = 0.05 # damping factor (estimated)
28
29 # State space dynamics

30 xe = [0, 0, 0, 0, 0, 0] # equilibrium point of interest
31 ue = [0, m*g] # (note these are lists, not matrices)
32
33 # TODO: The following objects need converting from np.matrix to np.array

34 # This will involve re-working the subsequent equations as the shapes
35 # See below.
36
37 # Dynamics matrix (use matrix type so that * works for multiplication)

38 A = np.matrix(
39 [[0, 0, 0, 1, 0, 0],
40 [0, 0, 0, 0, 1, 0],
41 [0, 0, 0, 0, 0, 1],
42 [0, 0, (-ue[0]*np.sin(xe[2]) - ue[1]*np.cos(xe[2]))/m, -c/m, 0, 0],
43 [0, 0, (ue[0]*np.cos(xe[2]) - ue[1]*np.sin(xe[2]))/m, 0, -c/m, 0],
44 [0, 0, 0, 0, 0, 0]]
45 )


46
47 # Input matrix
48 B = np.matrix(
49 [[0, 0], [0, 0], [0, 0],
50 [np.cos(xe[2])/m, -np.sin(xe[2])/m],
51 [np.sin(xe[2])/m, np.cos(xe[2])/m],
52 [r/J, 0]]
53 )
54
55 # Output matrix
56 C = np.matrix([[1, 0, 0, 0, 0, 0], [0, 1, 0, 0, 0, 0]])
57 D = np.matrix([[0, 0], [0, 0]])
58
59 #
60 # Construct inputs and outputs corresponding to steps in xy position
61 #
62 # The vectors xd and yd correspond to the states that are the desired
63 # equilibrium states for the system. The matrices Cx and Cy are the
64 # corresponding outputs.
65 #
66 # The way these vectors are used is to compute the closed loop system
67 # dynamics as
68 #
69 # xdot = Ax + B u => xdot = (A-BK)x + K xd
70 # u = -K(x - xd) y = Cx
71 #
72 # The closed loop dynamics can be simulated using the "step" command,
73 # with K*xd as the input vector (assumes that the "input" is unit size,
74 # so that xd corresponds to the desired steady state.
75 #
76
77 xd = np.matrix([[1], [0], [0], [0], [0], [0]])

78 yd = np.matrix([[0], [1], [0], [0], [0], [0]])
79
80 #
81 # Extract the relevant dynamics for use with SISO library
82 #
83 # The current python-control library only supports SISO transfer
84 # functions, so we have to modify some parts of the original MATLAB
85 # code to extract out SISO systems. To do this, we define the 'lat' and
86 # 'alt' index vectors to consist of the states that are are relevant
87 # to the lateral (x) and vertical (y) dynamics.
88 #
89
90 # Indices for the parts of the state that we want

91 lat = (0, 2, 3, 5)
92 alt = (1, 4)
93
94 # Decoupled dynamics
95 Ax = (A[lat, :])[:, lat] # ! not sure why I have to do it this way
96 Bx = B[lat, 0]
97 Cx = C[0, lat]
98 Dx = D[0, 0]
99
100 Ay = (A[alt, :])[:, alt] # ! not sure why I have to do it this way
101 By = B[alt, 1]
102 Cy = C[1, alt]


103 Dy = D[1, 1]
104
105 # Label the plot

106 plt.clf()
107 plt.suptitle("LQR controllers for vectored thrust aircraft (pvtol-lqr)")
108
109 #
110 # LQR design
111 #
112
113 # Start with a diagonal weighting

114 Qx1 = np.diag([1, 1, 1, 1, 1, 1])
115 Qu1a = np.diag([1, 1])
116 K, X, E = lqr(A, B, Qx1, Qu1a)
117 K1a = np.matrix(K)
118
119 # Close the loop: xdot = Ax - B K (x-xd)

120 # Note: python-control requires we do this 1 input at a time
121 # H1a = ss(A-B*K1a, B*K1a*concatenate((xd, yd), axis=1), C, D);
122 # (T, Y) = step(H1a, T=np.linspace(0,10,100));
123
124 # TODO: The following equations will need modifying when converting from np.matrix to
˓→np.array
125 # because the results and even intermediate calculations will be different with numpy
˓→arrays
126 # For example:

127 # Bx = B[lat, 0]
128 # Will need to be changed to:
129 # Bx = B[lat, 0].reshape(-1, 1)
130 # (if we want it to have the same shape as before)
131
132 # For reference, here is a list of the correct shapes of these objects:
133 # A: (6, 6)
134 # B: (6, 2)
135 # C: (2, 6)
136 # D: (2, 2)
137 # xd: (6, 1)
138 # yd: (6, 1)
139 # Ax: (4, 4)
140 # Bx: (4, 1)
141 # Cx: (1, 4)
142 # Dx: ()
143 # Ay: (2, 2)
144 # By: (2, 1)
145 # Cy: (1, 2)
146
147 # Step response for the first input

148 H1ax = ss(Ax - Bx*K1a[0, lat], Bx*K1a[0, lat]*xd[lat, :], Cx, Dx)
149 Yx, Tx = step(H1ax, T=np.linspace(0, 10, 100))
150
151 # Step response for the second input

152 H1ay = ss(Ay - By*K1a[1, alt], By*K1a[1, alt]*yd[alt, :], Cy, Dy)
153 Yy, Ty = step(H1ay, T=np.linspace(0, 10, 100))
154
156 plt.title("Identity weights")
157 # plt.plot(T, Y[:,1, 1], '-', T, Y[:,2, 2], '--')


158 plt.plot(Tx.T, Yx.T, '-', Ty.T, Yy.T, '--')
159 plt.plot([0, 10], [1, 1], 'k-')
160
161 plt.axis([0, 10, -0.1, 1.4])

162 plt.ylabel('position')
163 plt.legend(('x', 'y'), loc='lower right')
164
165 # Look at different input weightings

166 Qu1a = np.diag([1, 1])
167 K1a, X, E = lqr(A, B, Qx1, Qu1a)
168 H1ax = ss(Ax - Bx*K1a[0, lat], Bx*K1a[0, lat]*xd[lat, :], Cx, Dx)
169
170 Qu1b = (40 ** 2)*np.diag([1, 1])

171 K1b, X, E = lqr(A, B, Qx1, Qu1b)
172 H1bx = ss(Ax - Bx*K1b[0, lat], Bx*K1b[0, lat]*xd[lat, :], Cx, Dx)
173
174 Qu1c = (200 ** 2)*np.diag([1, 1])

175 K1c, X, E = lqr(A, B, Qx1, Qu1c)
176 H1cx = ss(Ax - Bx*K1c[0, lat], Bx*K1c[0, lat]*xd[lat, :], Cx, Dx)
177
178 [Y1, T1] = step(H1ax, T=np.linspace(0, 10, 100))

179 [Y2, T2] = step(H1bx, T=np.linspace(0, 10, 100))
180 [Y3, T3] = step(H1cx, T=np.linspace(0, 10, 100))
181
183 plt.title("Effect of input weights")
184 plt.plot(T1.T, Y1.T, 'b-')
187 plt.plot([0, 10], [1, 1], 'k-')
188
189 plt.axis([0, 10, -0.1, 1.4])

190
191 # arcarrow([1.3, 0.8], [5, 0.45], -6)

192 plt.text(5.3, 0.4, 'rho')
193
194 # Output weighting - change Qx to use outputs

195 Qx2 = C.T*C
196 Qu2 = 0.1*np.diag([1, 1])
197 K, X, E = lqr(A, B, Qx2, Qu2)
198 K2 = np.matrix(K)
199
200 H2x = ss(Ax - Bx*K2[0, lat], Bx*K2[0, lat]*xd[lat, :], Cx, Dx)
201 H2y = ss(Ay - By*K2[1, alt], By*K2[1, alt]*yd[alt, :], Cy, Dy)
202
204 plt.title("Output weighting")
205 [Y2x, T2x] = step(H2x, T=np.linspace(0, 10, 100))
206 [Y2y, T2y] = step(H2y, T=np.linspace(0, 10, 100))
207 plt.plot(T2x.T, Y2x.T, T2y.T, Y2y.T)
209 plt.xlabel('time')
212
213 #
214 # Physically motivated weighting


215 #
216 # Shoot for 1 cm error in x, 10 cm error in y. Try to keep the angle
217 # less than 5 degrees in making the adjustments. Penalize side forces
218 # due to loss in efficiency.
219 #
220
221 Qx3 = np.diag([100, 10, 2*np.pi/5, 0, 0, 0])

222 Qu3 = 0.1*np.diag([1, 10])
223 (K, X, E) = lqr(A, B, Qx3, Qu3)
224 K3 = np.matrix(K)
225
226 H3x = ss(Ax - Bx*K3[0, lat], Bx*K3[0, lat]*xd[lat, :], Cx, Dx)
227 H3y = ss(Ay - By*K3[1, alt], By*K3[1, alt]*yd[alt, :], Cy, Dy)
229 # step(H3x, H3y, 10)
230 [Y3x, T3x] = step(H3x, T=np.linspace(0, 10, 100))
231 [Y3y, T3y] = step(H3y, T=np.linspace(0, 10, 100))
232 plt.plot(T3x.T, Y3x.T, T3y.T, Y3y.T)
233 plt.title("Physically motivated weights")
236

238 plt.show()
Notes
8.1.4 Balanced model reduction examples
Code
1 #!/usr/bin/env python
2
3 import os
4
6 import control.modelsimp as msimp
7 import control.matlab as mt
8 from control.statesp import StateSpace
9 import matplotlib.pyplot as plt
10
11 plt.close('all')
12
13 # controllable canonical realization computed in MATLAB for the

14 # transfer function: num = [1 11 45 32], den = [1 15 60 200 60]
15 A = np.array([
16 [-15., -7.5, -6.25, -1.875],
17 [8., 0., 0., 0.],
18 [0., 4., 0., 0.],
19 [0., 0., 1., 0.]
20 ])


21 B = np.array([
22 [2.],
23 [0.],
24 [0.],
25 [0.]
26 ])
27 C = np.array([[0.5, 0.6875, 0.7031, 0.5]])
28 D = np.array([[0.]])
29
30 # The full system

31 fsys = StateSpace(A, B, C, D)
32
33 # The reduced system, truncating the order by 1

34 n = 3
35 rsys = msimp.balred(fsys, n, method='truncate')
36
37 # Comparison of the step responses of the full and reduced systems

38 plt.figure(1)
39 y, t = mt.step(fsys)
40 yr, tr = mt.step(rsys)
41 plt.plot(t.T, y.T)
42 plt.plot(tr.T, yr.T)
43
44 # Repeat balanced reduction, now with 100-dimensional random state space

45 sysrand = mt.rss(100, 1, 1)
46 rsysrand = msimp.balred(sysrand, 10, method='truncate')
47
48 # Comparison of the impulse responses of the full and reduced random systems
49 plt.figure(2)
50 yrand, trand = mt.impulse(sysrand)
51 yrandr, trandr = mt.impulse(rsysrand)
52 plt.plot(trand.T, yrand.T, trandr.T, yrandr.T)
53

55 plt.show()
Notes
8.1.5 Phase plot examples
Code
1 # phaseplots.py - examples of phase portraits

2 # RMM, 24 July 2011
3 #
4 # This file contains examples of phase portraits pulled from "Feedback
5 # Systems" by Astrom and Murray (Princeton University Press, 2008).
6
7 import os
8


11 from control.phaseplot import phase_plot
12 from numpy import pi
13
14 # Clear out any figures that are present

15 plt.close('all')
16
17 #
18 # Inverted pendulum
19 #
20
21 # Define the ODEs for a damped (inverted) pendulum

22 def invpend_ode(x, t, m=1., l=1., b=0.2, g=1):
23 return x[1], -b/m*x[1] + (g*l/m)*np.sin(x[0])
24
25
26 # Set up the figure the way we want it to look

27 plt.figure()
28 plt.clf()
29 plt.axis([-2*pi, 2*pi, -2.1, 2.1])
30 plt.title('Inverted pendulum')
31
32 # Outer trajectories
33 phase_plot(
34 invpend_ode,
35 X0=[[-2*pi, 1.6], [-2*pi, 0.5], [-1.8, 2.1],
36 [-1, 2.1], [4.2, 2.1], [5, 2.1],
37 [2*pi, -1.6], [2*pi, -0.5], [1.8, -2.1],
38 [1, -2.1], [-4.2, -2.1], [-5, -2.1]],
39 T=np.linspace(0, 40, 200),
40 logtime=(3, 0.7)
41 )
42
43 # Separatrices
44 phase_plot(invpend_ode, X0=[[-2.3056, 2.1], [2.3056, -2.1]], T=6, lingrid=0)
45
46 #
47 # Systems of ODEs: damped oscillator example (simulation + phase portrait)
48 #
49
50 def oscillator_ode(x, t, m=1., b=1, k=1):

51 return x[1], -k/m*x[0] - b/m*x[1]
52
53
54 # Generate a vector plot for the damped oscillator

55 plt.figure()
56 plt.clf()
57 phase_plot(oscillator_ode, [-1, 1, 10], [-1, 1, 10], 0.15)
58 #plt.plot([0], [0], '.')
59 # a=gca; set(a,'FontSize',20); set(a,'DataAspectRatio',[1,1,1])
60 plt.xlabel('$x_1$')
61 plt.ylabel('$x_2$')
62 plt.title('Damped oscillator, vector field')
63
64 # Generate a phase plot for the damped oscillator

65 plt.figure()
66 plt.clf()


67 plt.axis([-1, 1, -1, 1]) # set(gca, 'DataAspectRatio', [1, 1, 1]);
68 phase_plot(
69 oscillator_ode,
70 X0=[
71 [-1, 1], [-0.3, 1], [0, 1], [0.25, 1], [0.5, 1], [0.75, 1], [1, 1],
72 [1, -1], [0.3, -1], [0, -1], [-0.25, -1], [-0.5, -1], [-0.75, -1], [-1, -1]
73 ],
74 T=np.linspace(0, 8, 80),
75 timepts=[0.25, 0.8, 2, 3]
76 )
77 plt.plot([0], [0], 'k.') # 'MarkerSize', AM_data_markersize*3)
78 # set(gca, 'DataAspectRatio', [1,1,1])
81 plt.title('Damped oscillator, vector field and stream lines')
82
83 #
84 # Stability definitions
85 #
86 # This set of plots illustrates the various types of equilibrium points.
87 #
88
89
90 def saddle_ode(x, t):

91 """Saddle point vector field"""
92 return x[0] - 3*x[1], -3*x[0] + x[1]
93
94
95 # Asy stable
96 m = 1
97 b = 1
98 k = 1 # default values
99 plt.figure()
100 plt.clf()
101 plt.axis([-1, 1, -1, 1]) # set(gca, 'DataAspectRatio', [1 1 1]);
102 phase_plot(
103 oscillator_ode,
104 X0=[
105 [-1, 1], [-0.3, 1], [0, 1], [0.25, 1], [0.5, 1], [0.7, 1], [1, 1], [1.3, 1],
106 [1, -1], [0.3, -1], [0, -1], [-0.25, -1], [-0.5, -1], [-0.7, -1], [-1, -1],
107 [-1.3, -1]
108 ],
109 T=np.linspace(0, 10, 100),
110 timepts=[0.3, 1, 2, 3],
111 parms=(m, b, k)
112 )
114 # plt.set(gca,'FontSize', 16)
117 plt.title('Asymptotically stable point')
118
119 # Saddle
120 plt.figure()
121 plt.clf()
122 plt.axis([-1, 1, -1, 1]) # set(gca, 'DataAspectRatio', [1 1 1])
123 phase_plot(


124 saddle_ode,
125 scale=2,
126 timepts=[0.2, 0.5, 0.8],
127 X0=[
128 [-1, -1], [1, 1],
129 [-1, -0.95], [-1, -0.9], [-1, -0.8], [-1, -0.6], [-1, -0.4], [-1, -0.2],
130 [-0.95, -1], [-0.9, -1], [-0.8, -1], [-0.6, -1], [-0.4, -1], [-0.2, -1],
131 [1, 0.95], [1, 0.9], [1, 0.8], [1, 0.6], [1, 0.4], [1, 0.2],
132 [0.95, 1], [0.9, 1], [0.8, 1], [0.6, 1], [0.4, 1], [0.2, 1],
133 [-0.5, -0.45], [-0.45, -0.5], [0.5, 0.45], [0.45, 0.5],
134 [-0.04, 0.04], [0.04, -0.04]
135 ],
136 T=np.linspace(0, 2, 20)
137 )
139 # set(gca,'FontSize', 16)
142 plt.title('Saddle point')
143
144 # Stable isL

145 m = 1
146 b = 0
147 k = 1 # zero damping
148 plt.figure()
149 plt.clf()
150 plt.axis([-1, 1, -1, 1]) # set(gca, 'DataAspectRatio', [1 1 1]);
151 phase_plot(
152 oscillator_ode,
153 timepts=[pi/6, pi/3, pi/2, 2*pi/3, 5*pi/6, pi, 7*pi/6,
154 4*pi/3, 9*pi/6, 5*pi/3, 11*pi/6, 2*pi],
155 X0=[[0.2, 0], [0.4, 0], [0.6, 0], [0.8, 0], [1, 0], [1.2, 0], [1.4, 0]],
156 T=np.linspace(0, 20, 200),
157 parms=(m, b, k)
158 )
160 # plt.set(gca,'FontSize', 16)
163 plt.title('Undamped system\nLyapunov stable, not asympt. stable')
164

166 plt.show()
Notes
8.1.6 SISO robust control example (SP96, Example 2.1)
Code

1 """robust_siso.py
2
3 Demonstrate mixed-sensitivity H-infinity design for a SISO plant.

4
5 Based on Example 2.11 from Multivariable Feedback Control, Skogestad

6 and Postlethwaite, 1st Edition.
7 """
8
9 import os
10
13
14 from control import tf, mixsyn, feedback, step_response

15
16 s = tf([1, 0], 1)
17 # the plant
18 g = 200/(10*s + 1) / (0.05*s + 1)**2
19 # disturbance plant
20 gd = 100/(10*s + 1)
21
22 # first design
23 # sensitivity weighting
24 M = 1.5
25 wb = 10
26 A = 1e-4
27 ws1 = (s/M + wb) / (s + wb*A)
28 # KS weighting
29 wu = tf(1, 1)
30
31 k1, cl1, info1 = mixsyn(g, ws1, wu)

32
33 # sensitivity (S) and complementary sensitivity (T) functions for

34 # design 1
35 s1 = feedback(1, g*k1)
36 t1 = feedback(g*k1, 1)
37
38 # second design
39 # this weighting differs from the text, where A**0.5 is used; if you use that,
40 # the frequency response doesn't match the figure. The time responses
41 # are similar, though.
42 ws2 = (s/M ** 0.5 + wb)**2 / (s + wb*A)**2
43 # the KS weighting is the same as for the first design
44
45 k2, cl2, info2 = mixsyn(g, ws2, wu)

46
47 # S and T for design 2

48 s2 = feedback(1, g*k2)
49 t2 = feedback(g*k2, 1)
50
51 # frequency response
52 omega = np.logspace(-2, 2, 101)
53 ws1mag, _, _ = ws1.freqresp(omega)
54 s1mag, _, _ = s1.freqresp(omega)
55 ws2mag, _, _ = ws2.freqresp(omega)
56 s2mag, _, _ = s2.freqresp(omega)
57


58 plt.figure(1)
59 # text uses log-scaled absolute, but dB are probably more familiar to most control
˓→engineers
60 plt.semilogx(omega, 20*np.log10(s1mag.flat), label='$S_1$')

61 plt.semilogx(omega, 20*np.log10(s2mag.flat), label='$S_2$')
62 # -1 in logspace is inverse
63 plt.semilogx(omega, -20*np.log10(ws1mag.flat), label='$1/w_{P1}$')
64 plt.semilogx(omega, -20*np.log10(ws2mag.flat), label='$1/w_{P2}$')
65
66 plt.ylim([-80, 10])
67 plt.xlim([1e-2, 1e2])
68 plt.xlabel('freq [rad/s]')
69 plt.ylabel('mag [dB]')
70 plt.legend()
71 plt.title('Sensitivity and sensitivity weighting frequency responses')
72
73 # time response
74 time = np.linspace(0, 3, 201)
75 _, y1 = step_response(t1, time)
76 _, y2 = step_response(t2, time)
77
78 # gd injects into the output (that is, g and gd are summed), and the
79 # closed loop mapping from output disturbance->output is S.
80 _, y1d = step_response(s1*gd, time)
81 _, y2d = step_response(s2*gd, time)
82
83 plt.figure(2)
84 plt.subplot(1, 2, 1)
85 plt.plot(time, y1, label='$y_1(t)$')
86 plt.plot(time, y2, label='$y_2(t)$')
87
88 plt.ylim([-0.1, 1.5])
89 plt.xlim([0, 3])
90 plt.xlabel('time [s]')
91 plt.ylabel('signal [1]')
92 plt.legend()
93 plt.title('Tracking response')
94
96 plt.plot(time, y1d, label='$y_1(t)$')
97 plt.plot(time, y2d, label='$y_2(t)$')
98
99 plt.ylim([-0.1, 1.5])
100 plt.xlim([0, 3])
102 plt.ylabel('signal [1]')
103 plt.legend()
104 plt.title('Disturbance response')
105

107 plt.show()
Notes

8.1.7 MIMO robust control example (SP96, Example 3.8)
Code
1 """robust_mimo.py
2
3 Demonstrate mixed-sensitivity H-infinity design for a MIMO plant.

4
5 Based on Example 3.8 from Multivariable Feedback Control, Skogestad and Postlethwaite,
˓→ 1st Edition.
6 """
7
8 import os
9
12
13 from control import tf, ss, mixsyn, step_response

14
15
16 def weighting(wb, m, a):

17 """weighting(wb,m,a) -> wf
18 wb - design frequency (where |wf| is approximately 1)
19 m - high frequency gain of 1/wf; should be > 1
20 a - low frequency gain of 1/wf; should be < 1
21 wf - SISO LTI object
22 """
23 s = tf([1, 0], [1])
24 return (s/m + wb) / (s + wb*a)
25
26
27 def plant():
28 """plant() -> g
29 g - LTI object; 2x2 plant with a RHP zero, at s=0.5.
30 """
31 den = [0.2, 1.2, 1]
32 gtf = tf([[[1], [1]],
33 [[2, 1], [2]]],
34 [[den, den],
35 [den, den]])
36 return ss(gtf)
37
38
39 # as of this writing (2017-07-01), python-control doesn't have an

40 # equivalent to Matlab's sigma function, so use a trivial stand-in.
41 def triv_sigma(g, w):
42 """triv_sigma(g,w) -> s
43 g - LTI object, order n
44 w - frequencies, length m
45 s - (m,n) array of singular values of g(1j*w)"""
46 m, p, _ = g.freqresp(w)
47 sjw = (m*np.exp(1j*p*np.pi/180)).transpose(2, 0, 1)
48 sv = np.linalg.svd(sjw, compute_uv=False)
49 return sv
50
51
52 def analysis():


53 """Plot open-loop responses for various inputs"""
54 g = plant()
55
56 t = np.linspace(0, 10, 101)

57 _, yu1 = step_response(g, t, input=0)
59
60 yu1 = yu1
61 yu2 = yu2
62
63 # linear system, so scale and sum previous results to get the

64 # [1,-1] response
65 yuz = yu1 - yu2
66
67 plt.figure(1)
69 plt.plot(t, yu1[0], label='$y_1$')
72 plt.ylabel('output')
73 plt.ylim([-1.1, 2.1])
74 plt.legend()
75 plt.title('o/l response\nto input [1,0]')
76
82 plt.ylim([-1.1, 2.1])
83 plt.legend()
84 plt.title('o/l response\nto input [0,1]')
85
87 plt.plot(t, yuz[0], label='$y_1$')
88 plt.plot(t, yuz[1], label='$y_2$')
91 plt.ylim([-1.1, 2.1])
92 plt.legend()
93 plt.title('o/l response\nto input [1,-1]')
94
95
96 def synth(wb1, wb2):

97 """synth(wb1,wb2) -> k,gamma
98 wb1: S weighting frequency
99 wb2: KS weighting frequency
100 k: controller
101 gamma: H-infinity norm of 'design', that is, of evaluation system
102 with loop closed through design
103 """
104 g = plant()
105 wu = ss([], [], [], np.eye(2))
106 wp1 = ss(weighting(wb=wb1, m=1.5, a=1e-4))
107 wp2 = ss(weighting(wb=wb2, m=1.5, a=1e-4))
108 wp = wp1.append(wp2)
109 k, _, info = mixsyn(g, wp, wu)


110 return k, info[0]
111
112
113 def step_opposite(g, t):

114 """reponse to step of [-1,1]"""
117 return yu1 - yu2
118
119
120 def design():

121 """Show results of designs"""
122 # equal weighting on each output
123 k1, gam1 = synth(0.25, 0.25)
124 # increase "bandwidth" of output 2 by moving crossover weighting frequency 100
˓→times higher
125 k2, gam2 = synth(0.25, 25)

126 # now weight output 1 more heavily
127 # won't plot this one, just want gamma
128 _, gam3 = synth(25, 0.25)
129
130 print('design 1 gamma {:.3g} (Skogestad: 2.80)'.format(gam1))

133
134 # do the designs

135 g = plant()
136 w = np.logspace(-2, 2, 101)
137 I = ss([], [], [], np.eye(2))
138 s1 = I.feedback(g*k1)
139 s2 = I.feedback(g*k2)
140
141 # frequency response

142 sv1 = triv_sigma(s1, w)
143 sv2 = triv_sigma(s2, w)
144
145 plt.figure(2)
146
148 plt.semilogx(w, 20*np.log10(sv1[:, 0]), label=r'$\sigma_1(S_1)$')
152 plt.ylim([-60, 10])
153 plt.ylabel('magnitude [dB]')
154 plt.xlim([1e-2, 1e2])
155 plt.xlabel('freq [rad/s]')
156 plt.legend()
157 plt.title('Singular values of S')
158
159 # time response

160
161 # in design 1, both outputs have an inverse initial response; in

162 # design 2, output 2 does not, and is very fast, while output 1
163 # has a larger initial inverse response than in design 1
164 time = np.linspace(0, 10, 301)
165 t1 = (g*k1).feedback(I)


166 t2 = (g*k2).feedback(I)
167
168 y1 = step_opposite(t1, time)

169 y2 = step_opposite(t2, time)
170
172 plt.plot(time, y1[0], label='des. 1 $y_1(t))$')
177 plt.ylabel('response [1]')
178 plt.legend()
179 plt.title('c/l response to reference [1,-1]')
180
181
182 if __name__ == "__main__":

183 analysis()
184 design()
186 plt.show()
Notes
8.1.8 Cruise control design example (as a nonlinear I/O system)
Code
1 # cruise-control.py - Cruise control example from FBS

2 # RMM, 16 May 2019
3 #
4 # The cruise control system of a car is a common feedback system encountered
5 # in everyday life. The system attempts to maintain a constant velocity in the
6 # presence of disturbances primarily caused by changes in the slope of a
7 # road. The controller compensates for these unknowns by measuring the speed
8 # of the car and adjusting the throttle appropriately.
9 #
10 # This file explore the dynamics and control of the cruise control system,
11 # following the material presenting in Feedback Systems by Astrom and Murray.
12 # A full nonlinear model of the vehicle dynamics is used, with both PI and
13 # state space control laws. Different methods of constructing control systems
14 # are show, all using the InputOutputSystem class (and subclasses).
15
18 from math import pi
19 import control as ct
20
21 #
22 # Section 4.1: Cruise control modeling and control
23 #


24
25 # Vehicle model: vehicle()

26 #
27 # To develop a mathematical model we start with a force balance for
28 # the car body. Let v be the speed of the car, m the total mass
29 # (including passengers), F the force generated by the contact of the
30 # wheels with the road, and Fd the disturbance force due to gravity,
31 # friction, and aerodynamic drag.
32
33 def vehicle_update(t, x, u, params={}):

34 """Vehicle dynamics for cruise control system.
35
36 Parameters
37 ----------
38 x : array
39 System state: car velocity in m/s
40 u : array
41 System input: [throttle, gear, road_slope], where throttle is
42 a float between 0 and 1, gear is an integer between 1 and 5,
43 and road_slope is in rad.
44
45 Returns
46 -------
47 float
48 Vehicle acceleration
49
50 """
51 from math import copysign, sin
52 sign = lambda x: copysign(1, x) # define the sign() function
53
54 # Set up the system parameters

55 m = params.get('m', 1600.)
56 g = params.get('g', 9.8)
57 Cr = params.get('Cr', 0.01)
58 Cd = params.get('Cd', 0.32)
59 rho = params.get('rho', 1.3)
60 A = params.get('A', 2.4)
61 alpha = params.get(
62 'alpha', [40, 25, 16, 12, 10]) # gear ratio / wheel radius
63
64 # Define variables for vehicle state and inputs

65 v = x[0] # vehicle velocity
66 throttle = np.clip(u[0], 0, 1) # vehicle throttle
67 gear = u[1] # vehicle gear
68 theta = u[2] # road slope
69
70 # Force generated by the engine

71
72 omega = alpha[int(gear)-1] * v # engine angular speed

73 F = alpha[int(gear)-1] * motor_torque(omega, params) * throttle
74
75 # Disturbance forces
76 #
77 # The disturbance force Fd has three major components: Fg, the forces due
78 # to gravity; Fr, the forces due to rolling friction; and Fa, the
79 # aerodynamic drag.
80


81 # Letting the slope of the road be \theta (theta), gravity gives the
82 # force Fg = m g sin \theta.
83
84 Fg = m * g * sin(theta)
85
86 # A simple model of rolling friction is Fr = m g Cr sgn(v), where Cr is

87 # the coefficient of rolling friction and sgn(v) is the sign of v (+/- 1) or
88 # zero if v = 0.
89
90 Fr = m * g * Cr * sign(v)
91
92 # The aerodynamic drag is proportional to the square of the speed: Fa =

93 # 1/\rho Cd A |v| v, where \rho is the density of air, Cd is the
94 # shape-dependent aerodynamic drag coefficient, and A is the frontal area
95 # of the car.
96
97 Fa = 1/2 * rho * Cd * A * abs(v) * v

98
99 # Final acceleration on the car

100 Fd = Fg + Fr + Fa
101 dv = (F - Fd) / m
102
103 return dv
104
105 # Engine model: motor_torque

106 #
107 # The force F is generated by the engine, whose torque is proportional to
108 # the rate of fuel injection, which is itself proportional to a control
109 # signal 0 <= u <= 1 that controls the throttle position. The torque also
110 # depends on engine speed omega.
111
112 def motor_torque(omega, params={}):

113 # Set up the system parameters
114 Tm = params.get('Tm', 190.) # engine torque constant
115 omega_m = params.get('omega_m', 420.) # peak engine angular speed
116 beta = params.get('beta', 0.4) # peak engine rolloff
117
118 return np.clip(Tm * (1 - beta * (omega/omega_m - 1)**2), 0, None)

119
120 # Define the input/output system for the vehicle

121 vehicle = ct.NonlinearIOSystem(
122 vehicle_update, None, name='vehicle',
123 inputs = ('u', 'gear', 'theta'), outputs = ('v'), states=('v'))
124
125 # Figure 1.11: A feedback system for controlling the speed of a vehicle. In
126 # this example, the speed of the vehicle is measured and compared to the
127 # desired speed. The controller is a PI controller represented as a transfer
128 # function. In the textbook, the simulations are done for LTI systems, but
129 # here we simulate the full nonlinear system.
130
131 # Construct a PI controller with rolloff, as a transfer function

132 Kp = 0.5 # proportional gain
133 Ki = 0.1 # integral gain
134 control_tf = ct.tf2io(
135 ct.TransferFunction([Kp, Ki], [1, 0.01*Ki/Kp]),
136 name='control', inputs='u', outputs='y')
137


138 # Construct the closed loop control system
139 # Inputs: vref, gear, theta
140 # Outputs: v (vehicle velocity)
141 cruise_tf = ct.InterconnectedSystem(
142 (control_tf, vehicle), name='cruise',
143 connections = (
144 ('control.u', '-vehicle.v'),
145 ('vehicle.u', 'control.y')),
146 inplist = ('control.u', 'vehicle.gear', 'vehicle.theta'),
147 inputs = ('vref', 'gear', 'theta'),
148 outlist = ('vehicle.v', 'vehicle.u'),
149 outputs = ('v', 'u'))
150
151 # Define the time and input vectors

152 T = np.linspace(0, 25, 101)
153 vref = 20 * np.ones(T.shape)
154 gear = 4 * np.ones(T.shape)
155 theta0 = np.zeros(T.shape)
156
157 # Now simulate the effect of a hill at t = 5 seconds

158 plt.figure()
159 plt.suptitle('Response to change in road slope')
160 vel_axes = plt.subplot(2, 1, 1)
161 inp_axes = plt.subplot(2, 1, 2)
162 theta_hill = np.array([
163 0 if t <= 5 else
164 4./180. * pi * (t-5) if t <= 6 else
165 4./180. * pi for t in T])
166
167 for m in (1200, 1600, 2000):

168 # Compute the equilibrium state for the system
169 X0, U0 = ct.find_eqpt(
170 cruise_tf, [0, vref[0]], [vref[0], gear[0], theta0[0]],
171 iu=[1, 2], y0=[vref[0], 0], iy=[0], params={'m':m})
172
173 t, y = ct.input_output_response(
174 cruise_tf, T, [vref, gear, theta_hill], X0, params={'m':m})
175
176 # Plot the velocity

177 plt.sca(vel_axes)
178 plt.plot(t, y[0])
179
180 # Plot the input

181 plt.sca(inp_axes)
182 plt.plot(t, y[1])
183
184 # Add labels to the plots

185 plt.sca(vel_axes)
186 plt.ylabel('Speed [m/s]')
187 plt.legend(['m = 1000 kg', 'm = 2000 kg', 'm = 3000 kg'], frameon=False)
188
189 plt.sca(inp_axes)
190 plt.ylabel('Throttle')
191 plt.xlabel('Time [s]')
192
193 # Figure 4.2: Torque curves for a typical car engine. The graph on the
194 # left shows the torque generated by the engine as a function of the


195 # angular velocity of the engine, while the curve on the right shows
196 # torque as a function of car speed for different gears.
197
198 plt.figure()
199 plt.suptitle('Torque curves for typical car engine')
200
201 # Figure 4.2a - single torque curve as function of omega

202 omega_range = np.linspace(0, 700, 701)
204 plt.plot(omega_range, [motor_torque(w) for w in omega_range])
205 plt.xlabel('Angular velocity $\omega$ [rad/s]')
206 plt.ylabel('Torque $T$ [Nm]')
207 plt.grid(True, linestyle='dotted')
208
209 # Figure 4.2b - torque curves in different gears, as function of velocity

211 v_range = np.linspace(0, 70, 71)
212 alpha = [40, 25, 16, 12, 10]
213 for gear in range(5):
214 omega_range = alpha[gear] * v_range
215 plt.plot(v_range, [motor_torque(w) for w in omega_range],
216 color='blue', linestyle='solid')
217
218 # Set up the axes and style

219 plt.axis([0, 70, 100, 200])
220 plt.grid(True, linestyle='dotted')
221
222 # Add labels

223 plt.text(11.5, 120, '$n$=1')
224 plt.text(24, 120, '$n$=2')
225 plt.text(42.5, 120, '$n$=3')
226 plt.text(58.5, 120, '$n$=4')
227 plt.text(58.5, 185, '$n$=5')
228 plt.xlabel('Velocity $v$ [m/s]')
229 plt.ylabel('Torque $T$ [Nm]')
230
232
233 # Figure 4.3: Car with cruise control encountering a sloping road
234
235 # PI controller model: control_pi()

236 #
237 # We add to this model a feedback controller that attempts to regulate the
238 # speed of the car in the presence of disturbances. We shall use a
239 # proportional-integral controller
240
241 def pi_update(t, x, u, params={}):

242 # Get the controller parameters that we need
243 ki = params.get('ki', 0.1)
244 kaw = params.get('kaw', 2) # anti-windup gain
245
246 # Assign variables for inputs and states (for readability)

247 v = u[0] # current velocity
248 vref = u[1] # reference velocity
249 z = x[0] # integrated error
250
251 # Compute the nominal controller output (needed for anti-windup)



252 u_a = pi_output(t, x, u, params)
253
254 # Compute anti-windup compensation (scale by ki to account for structure)

255 u_aw = kaw/ki * (np.clip(u_a, 0, 1) - u_a) if ki != 0 else 0
256
257 # State is the integrated error, minus anti-windup compensation

258 return (vref - v) + u_aw
259
260 def pi_output(t, x, u, params={}):

262 kp = params.get('kp', 0.5)
263 ki = params.get('ki', 0.1)
264
265 # Assign variables for inputs and states (for readability)

266 v = u[0] # current velocity
267 vref = u[1] # reference velocity
268 z = x[0] # integrated error
269
270 # PI controller
271 return kp * (vref - v) + ki * z
272
273 control_pi = ct.NonlinearIOSystem(

274 pi_update, pi_output, name='control',
275 inputs = ['v', 'vref'], outputs = ['u'], states = ['z'],
276 params = {'kp':0.5, 'ki':0.1})
277
278 # Create the closed loop system

279 cruise_pi = ct.InterconnectedSystem(
280 (vehicle, control_pi), name='cruise',
281 connections=(
282 ('vehicle.u', 'control.u'),
283 ('control.v', 'vehicle.v')),
284 inplist=('control.vref', 'vehicle.gear', 'vehicle.theta'),
285 outlist=('control.u', 'vehicle.v'), outputs=['u', 'v'])
286
287 # Figure 4.3b shows the response of the closed loop system. The figure shows
288 # that even if the hill is so steep that the throttle changes from 0.17 to
289 # almost full throttle, the largest speed error is less than 1 m/s, and the
290 # desired velocity is recovered after 20 s.
291
292 # Define a function for creating a "standard" cruise control plot

293 def cruise_plot(sys, t, y, t_hill=5, vref=20, antiwindup=False,
294 linetype='b-', subplots=[None, None]):
295 # Figure out the plot bounds and indices
296 v_min = vref-1.2; v_max = vref+0.5; v_ind = sys.find_output('v')
297 u_min = 0; u_max = 2 if antiwindup else 1; u_ind = sys.find_output('u')
298
299 # Make sure the upper and lower bounds on v are OK

300 while max(y[v_ind]) > v_max: v_max += 1
301 while min(y[v_ind]) < v_min: v_min -= 1
302
303 # Create arrays for return values

304 subplot_axes = list(subplots)
305
306 # Velocity profile

307 if subplot_axes[0] is None:
308 subplot_axes[0] = plt.subplot(2, 1, 1)


309 else:
310 plt.sca(subplots[0])
311 plt.plot(t, y[v_ind], linetype)
312 plt.plot(t, vref*np.ones(t.shape), 'k-')
313 plt.plot([t_hill, t_hill], [v_min, v_max], 'k--')
314 plt.axis([0, t[-1], v_min, v_max])
315 plt.xlabel('Time $t$ [s]')
316 plt.ylabel('Velocity $v$ [m/s]')
317
318 # Commanded input profile

319 if subplot_axes[1] is None:
320 subplot_axes[1] = plt.subplot(2, 1, 2)
321 else:
322 plt.sca(subplots[1])
323 plt.plot(t, y[u_ind], 'r--' if antiwindup else linetype)
324 plt.plot([t_hill, t_hill], [u_min, u_max], 'k--')
325 plt.axis([0, t[-1], u_min, u_max])
326 plt.xlabel('Time $t$ [s]')
327 plt.ylabel('Throttle $u$')
328
329 # Applied input profile

330 if antiwindup:
331 # TODO: plot the actual signal from the process?
332 plt.plot(t, np.clip(y[u_ind], 0, 1), linetype)
333 plt.legend(['Commanded', 'Applied'], frameon=False)
334
335 return subplot_axes

336
337 # Define the time and input vectors

338 T = np.linspace(0, 30, 101)
340 gear = 4 * np.ones(T.shape)
341 theta0 = np.zeros(T.shape)
342
343 # Compute the equilibrium throttle setting for the desired speed (solve for x
344 # and u given the gear, slope, and desired output velocity)
345 X0, U0, Y0 = ct.find_eqpt(
346 cruise_pi, [vref[0], 0], [vref[0], gear[0], theta0[0]],
347 y0=[0, vref[0]], iu=[1, 2], iy=[1], return_y=True)
348
349 # Now simulate the effect of a hill at t = 5 seconds

350 plt.figure()
351 plt.suptitle('Car with cruise control encountering sloping road')
352 theta_hill = [
353 0 if t <= 5 else
354 4./180. * pi * (t-5) if t <= 6 else
355 4./180. * pi for t in T]
356 t, y = ct.input_output_response(cruise_pi, T, [vref, gear, theta_hill], X0)
357 cruise_plot(cruise_pi, t, y)
358
359 #
360 # Example 7.8: State space feedback with integral action
361 #
362
363 # State space controller model: control_sf_ia()

364 #
365 # Construct a state space controller with integral action, linearized around


366 # an equilibrium point. The controller is constructed around the equilibrium
367 # point (x_d, u_d) and includes both feedforward and feedback compensation.
368 #
369 # Controller inputs: (x, y, r) system states, system output, reference
370 # Controller state: z integrated error (y - r)
371 # Controller output: u state feedback control
372 #
373 # Note: to make the structure of the controller more clear, we implement this
374 # as a "nonlinear" input/output module, even though the actual input/output
375 # system is linear. This also allows the use of parameters to set the
376 # operating point and gains for the controller.
377
378 def sf_update(t, z, u, params={}):

379 y, r = u[1], u[2]
380 return y - r
381
382 def sf_output(t, z, u, params={}):

384 K = params.get('K', 0)
385 ki = params.get('ki', 0)
386 kf = params.get('kf', 0)
387 xd = params.get('xd', 0)
388 yd = params.get('yd', 0)
389 ud = params.get('ud', 0)
390
391 # Get the system state and reference input

392 x, y, r = u[0], u[1], u[2]
393
394 return ud - K * (x - xd) - ki * z + kf * (r - yd)

395
396 # Create the input/output system for the controller

397 control_sf = ct.NonlinearIOSystem(
398 sf_update, sf_output, name='control',
399 inputs=('x', 'y', 'r'),
400 outputs=('u'),
401 states=('z'))
402
403 # Create the closed loop system for the state space controller
404 cruise_sf = ct.InterconnectedSystem(
405 (vehicle, control_sf), name='cruise',
406 connections=(
407 ('vehicle.u', 'control.u'),
408 ('control.x', 'vehicle.v'),
409 ('control.y', 'vehicle.v')),
410 inplist=('control.r', 'vehicle.gear', 'vehicle.theta'),
411 outlist=('control.u', 'vehicle.v'), outputs=['u', 'v'])
412
413 # Compute the linearization of the dynamics around the equilibrium point
414
415 # Y0 represents the steady state with PI control => we can use it to
416 # identify the steady state velocity and required throttle setting.
417 xd = Y0[1]
418 ud = Y0[0]
419 yd = Y0[1]
420
421 # Compute the linearized system at the eq pt

422 cruise_linearized = ct.linearize(vehicle, xd, [ud, gear[0], 0])


423
424 # Construct the gain matrices for the system

425 A, B, C = cruise_linearized.A, cruise_linearized.B[0, 0], cruise_linearized.C
426 K = 0.5
427 kf = -1 / (C * np.linalg.inv(A - B * K) * B)
428
429 # Response of the system with no integral feedback term

430 plt.figure()
431 plt.suptitle('Cruise control with proportional and PI control')
432 theta_hill = [
433 0 if t <= 8 else
434 4./180. * pi * (t-8) if t <= 9 else
435 4./180. * pi for t in T]
437 cruise_sf, T, [vref, gear, theta_hill], [X0[0], 0],
438 params={'K':K, 'kf':kf, 'ki':0.0, 'kf':kf, 'xd':xd, 'ud':ud, 'yd':yd})
439 subplots = cruise_plot(cruise_sf, t, y, t_hill=8, linetype='b--')
440
441 # Response of the system with state feedback + integral action

443 cruise_sf, T, [vref, gear, theta_hill], [X0[0], 0],
444 params={'K':K, 'kf':kf, 'ki':0.1, 'kf':kf, 'xd':xd, 'ud':ud, 'yd':yd})
445 cruise_plot(cruise_sf, t, y, t_hill=8, linetype='b-', subplots=subplots)
446
447 # Add a legend

448 plt.legend(['Proportional', 'PI control'], frameon=False)
449
450 # Example 11.5: simulate the effect of a (steeper) hill at t = 5 seconds

451 #
452 # The windup effect occurs when a car encounters a hill that is so steep (6
453 # deg) that the throttle saturates when the cruise controller attempts to
454 # maintain speed.
455
456 plt.figure()
457 plt.suptitle('Cruise control with integrator windup')
458 T = np.linspace(0, 70, 101)
460 theta_hill = [
461 0 if t <= 5 else
462 6./180. * pi * (t-5) if t <= 6 else
463 6./180. * pi for t in T]
465 cruise_pi, T, [vref, gear, theta_hill], X0,
466 params={'kaw':0})
467 cruise_plot(cruise_pi, t, y, antiwindup=True)
468
469 # Example 11.6: add anti-windup compensation

470 #
471 # Anti-windup can be applied to the system to improve the response. Because of
472 # the feedback from the actuator model, the output of the integrator is
473 # quickly reset to a value such that the controller output is at the
474 # saturation limit.
475
476 plt.figure()
477 plt.suptitle('Cruise control with integrator anti-windup protection')
479 cruise_pi, T, [vref, gear, theta_hill], X0,


480 params={'kaw':2.})
481 cruise_plot(cruise_pi, t, y, antiwindup=True)
482
483 # If running as a standalone program, show plots and wait before closing
484 import os
485 if __name__ == '__main__' and 'PYCONTROL_TEST_EXAMPLES' not in os.environ:
486 plt.show()
487 else:
Notes
8.1.9 Gain scheduled control for vehicle steeering (I/O system)
Code
1 # steering-gainsched.py - gain scheduled control for vehicle steering

2 # RMM, 8 May 2019
3 #
4 # This file works through Example 1.1 in the "Optimization-Based Control"
5 # course notes by Richard Murray (avaliable at http://fbsbook.org, in the
6 # optimization-based control supplement). It is intended to demonstrate the
7 # functionality for nonlinear input/output systems in the python-control
8 # package.
9
12 from cmath import sqrt
13 import matplotlib.pyplot as mpl
14
15 #
16 # Vehicle steering dynamics
17 #
18 # The vehicle dynamics are given by a simple bicycle model. We take the state
19 # of the system as (x, y, theta) where (x, y) is the position of the vehicle
20 # in the plane and theta is the angle of the vehicle with respect to
21 # horizontal. The vehicle input is given by (v, phi) where v is the forward
22 # velocity of the vehicle and phi is the angle of the steering wheel. The
23 # model includes saturation of the vehicle steering angle.
24 #
25 # System state: x, y, theta
26 # System input: v, phi
27 # System output: x, y
28 # System parameters: wheelbase, maxsteer
29 #
30 def vehicle_update(t, x, u, params):
31 # Get the parameters for the model
32 l = params.get('wheelbase', 3.) # vehicle wheelbase
33 phimax = params.get('maxsteer', 0.5) # max steering angle (rad)
34
35 # Saturate the steering input



36 phi = np.clip(u[1], -phimax, phimax)
37
38 # Return the derivative of the state

39 return np.array([
40 np.cos(x[2]) * u[0], # xdot = cos(theta) v
41 np.sin(x[2]) * u[0], # ydot = sin(theta) v
42 (u[0] / l) * np.tan(phi) # thdot = v/l tan(phi)
43 ])
44
45 def vehicle_output(t, x, u, params):

46 return x # return x, y, theta (full state)
47
48 # Define the vehicle steering dynamics as an input/output system

49 vehicle = ct.NonlinearIOSystem(
50 vehicle_update, vehicle_output, states=3, name='vehicle',
51 inputs=('v', 'phi'),
52 outputs=('x', 'y', 'theta'))
53
54 #
55 # Gain scheduled controller
56 #
57 # For this system we use a simple schedule on the forward vehicle velocity and
58 # place the poles of the system at fixed values. The controller takes the
59 # current vehicle position and orientation plus the velocity velocity as
60 # inputs, and returns the velocity and steering commands.
61 #
62 # System state: none
63 # System input: ex, ey, etheta, vd, phid
64 # System output: v, phi
65 # System parameters: longpole, latpole1, latpole2
66 #
67 def control_output(t, x, u, params):
68 # Get the controller parameters
69 longpole = params.get('longpole', -2.)
70 latpole1 = params.get('latpole1', -1/2 + sqrt(-7)/2)
71 latpole2 = params.get('latpole2', -1/2 - sqrt(-7)/2)
72 l = params.get('wheelbase', 3)
73
74 # Extract the system inputs

75 ex, ey, etheta, vd, phid = u
76
77 # Determine the controller gains

78 alpha1 = -np.real(latpole1 + latpole2)
79 alpha2 = np.real(latpole1 * latpole2)
80
81 # Compute and return the control law

82 v = -longpole * ex # Note: no feedfwd (to make plot interesting)
83 if vd != 0:
84 phi = phid + (alpha1 * l) / vd * ey + (alpha2 * l) / vd * etheta
85 else:
86 # We aren't moving, so don't turn the steering wheel
87 phi = phid
88
89 return np.array([v, phi])

90
91 # Define the controller as an input/output system

92 controller = ct.NonlinearIOSystem(


93 None, control_output, name='controller', # static system
94 inputs=('ex', 'ey', 'etheta', 'vd', 'phid'), # system inputs
95 outputs=('v', 'phi') # system outputs
96 )
97
98 #
99 # Reference trajectory subsystem
100 #
101 # The reference trajectory block generates a simple trajectory for the system
102 # given the desired speed (vref) and lateral position (yref). The trajectory
103 # consists of a straight line of the form (vref * t, yref, 0) with nominal
104 # input (vref, 0).
105 #
106 # System state: none
107 # System input: vref, yref
108 # System output: xd, yd, thetad, vd, phid
109 # System parameters: none
110 #
111 def trajgen_output(t, x, u, params):
112 vref, yref = u
113 return np.array([vref * t, yref, 0, vref, 0])
114
115 # Define the trajectory generator as an input/output system

116 trajgen = ct.NonlinearIOSystem(
117 None, trajgen_output, name='trajgen',
118 inputs=('vref', 'yref'),
119 outputs=('xd', 'yd', 'thetad', 'vd', 'phid'))
120
121 #
122 # System construction
123 #
124 # The input to the full closed loop system is the desired lateral position and
125 # the desired forward velocity. The output for the system is taken as the
126 # full vehicle state plus the velocity of the vehicle. The following diagram
127 # summarizes the interconnections:
128 #
129 # +---------+ +---------------> v
130 # | | |
131 # [ yref ] | v |
132 # [ ] ---> trajgen -+-+-> controller -+-> vehicle -+-> [x, y, theta]
133 # [ vref ] ^ |
134 # | |
135 # +----------- [-1] -----------+
136 #
137 # We construct the system using the InterconnectedSystem constructor and using
138 # signal labels to keep track of everything.
139
140 steering = ct.InterconnectedSystem(

141 # List of subsystems
142 (trajgen, controller, vehicle), name='steering',
143
144 # Interconnections between subsystems

145 connections=(
146 ('controller.ex', 'trajgen.xd', '-vehicle.x'),
147 ('controller.ey', 'trajgen.yd', '-vehicle.y'),
148 ('controller.etheta', 'trajgen.thetad', '-vehicle.theta'),
149 ('controller.vd', 'trajgen.vd'),


150 ('controller.phid', 'trajgen.phid'),
151 ('vehicle.v', 'controller.v'),
152 ('vehicle.phi', 'controller.phi')
153 ),
154
155 # System inputs

156 inplist=['trajgen.vref', 'trajgen.yref'],
157 inputs=['yref', 'vref'],
158
159 # System outputs

160 outlist=['vehicle.x', 'vehicle.y', 'vehicle.theta', 'controller.v',
161 'controller.phi'],
162 outputs=['x', 'y', 'theta', 'v', 'phi']
163 )
164
165 # Set up the simulation conditions

166 yref = 1
167 T = np.linspace(0, 5, 100)
168
169 # Set up a figure for plotting the results

170 mpl.figure();
171
172 # Plot the reference trajectory for the y position

173 mpl.plot([0, 5], [yref, yref], 'k--')
174
175 # Find the signals we want to plot

176 y_index = steering.find_output('y')
177 v_index = steering.find_output('v')
178
179 # Do an iteration through different speeds

180 for vref in [8, 10, 12]:
181 # Simulate the closed loop controller response
182 tout, yout = ct.input_output_response(
183 steering, T, [vref * np.ones(len(T)), yref * np.ones(len(T))])
184
185 # Plot the reference speed

186 mpl.plot([0, 5], [vref, vref], 'k--')
187
188 # Plot the system output

189 y_line, = mpl.plot(tout, yout[y_index, :], 'r') # lateral position
190 v_line, = mpl.plot(tout, yout[v_index, :], 'b') # vehicle velocity
191
192 # Add axis labels

193 mpl.xlabel('Time (s)')
194 mpl.ylabel('x vel (m/s), y pos (m)')
195 mpl.legend((v_line, y_line), ('v', 'y'), loc='center right', frameon=False)
Notes
8.1.10 Differentially flat system - kinematic car
This example demonstrates the use of the flatsys module for generating trajectories for differentially flat systems. The
example is drawn from Chapter 8 of FBS2e.

Code
1 # kincar-flatsys.py - differentially flat systems example

2 # RMM, 3 Jul 2019
3 #
4 # This example demonstrates the use of the `flatsys` module for generating
5 # trajectories for differnetially flat systems by computing a trajectory for a
6 # kinematic (bicycle) model of a car changing lanes.
7
8 import os
12 import control.flatsys as fs
13
14
15 # Function to take states, inputs and return the flat flag

16 def vehicle_flat_forward(x, u, params={}):
17 # Get the parameter values
18 b = params.get('wheelbase', 3.)
19
20 # Create a list of arrays to store the flat output and its derivatives
21 zflag = [np.zeros(3), np.zeros(3)]
22
23 # Flat output is the x, y position of the rear wheels

24 zflag[0][0] = x[0]
25 zflag[1][0] = x[1]
26
27 # First derivatives of the flat output

28 zflag[0][1] = u[0] * np.cos(x[2]) # dx/dt
29 zflag[1][1] = u[0] * np.sin(x[2]) # dy/dt
30
31 # First derivative of the angle

32 thdot = (u[0]/b) * np.tan(u[1])
33
34 # Second derivatives of the flat output (setting vdot = 0)

35 zflag[0][2] = -u[0] * thdot * np.sin(x[2])
36 zflag[1][2] = u[0] * thdot * np.cos(x[2])
37
38 return zflag
39
40
41 # Function to take the flat flag and return states, inputs

42 def vehicle_flat_reverse(zflag, params={}):
43 # Get the parameter values
44 b = params.get('wheelbase', 3.)
45
46 # Create a vector to store the state and inputs

47 x = np.zeros(3)
48 u = np.zeros(2)
49
50 # Given the flat variables, solve for the state

51 x[0] = zflag[0][0] # x position
52 x[1] = zflag[1][0] # y position
53 x[2] = np.arctan2(zflag[1][1], zflag[0][1]) # tan(theta) = ydot/xdot
54
55 # And next solve for the inputs



56 u[0] = zflag[0][1] * np.cos(x[2]) + zflag[1][1] * np.sin(x[2])
57 thdot_v = zflag[1][2] * np.cos(x[2]) - zflag[0][2] * np.sin(x[2])
58 u[1] = np.arctan2(thdot_v, u[0]**2 / b)
59
60 return x, u
61
62
63 # Function to compute the RHS of the system dynamics

64 def vehicle_update(t, x, u, params):
65 b = params.get('wheelbase', 3.) # get parameter values
66 dx = np.array([
67 np.cos(x[2]) * u[0],
68 np.sin(x[2]) * u[0],
69 (u[0]/b) * np.tan(u[1])
70 ])
71 return dx
72
73
74 # Create differentially flat input/output system

75 vehicle_flat = fs.FlatSystem(
76 vehicle_flat_forward, vehicle_flat_reverse, vehicle_update,
77 inputs=('v', 'delta'), outputs=('x', 'y', 'theta'),
78 states=('x', 'y', 'theta'))
79
80 # Define the endpoints of the trajectory

81 x0 = [0., -2., 0.]; u0 = [10., 0.]
82 xf = [40., 2., 0.]; uf = [10., 0.]
83 Tf = 4
84
85 # Define a set of basis functions to use for the trajectories

86 poly = fs.PolyFamily(6)
87
88 # Find a trajectory between the initial condition and the final condition
89 traj = fs.point_to_point(vehicle_flat, x0, u0, xf, uf, Tf, basis=poly)
90
91 # Create the desired trajectory between the initial and final condition
92 T = np.linspace(0, Tf, 500)
93 xd, ud = traj.eval(T)
94
95 # Simulation the open system dynamics with the full input

96 t, y, x = ct.input_output_response(
97 vehicle_flat, T, ud, x0, return_x=True)
98
99 # Plot the open loop system dynamics

100 plt.figure()
101 plt.suptitle("Open loop trajectory for kinematic car lane change")
102
103 # Plot the trajectory in xy coordinates

105 plt.plot(x[0], x[1])
106 plt.xlabel('x [m]')
107 plt.ylabel('y [m]')
108 plt.axis([x0[0], xf[0], x0[1]-1, xf[1]+1])
109
110 # Time traces of the state and input

112 plt.plot(t, x[1])


113 plt.ylabel('y [m]')
114
116 plt.plot(t, x[2])
117 plt.ylabel('theta [rad]')
118
120 plt.plot(t, ud[0])
121 plt.xlabel('Time t [sec]')
122 plt.ylabel('v [m/s]')
123 plt.axis([0, Tf, u0[0] - 1, uf[0] + 1])
124
126 plt.plot(t, ud[1])
127 plt.xlabel('Ttime t [sec]')
128 plt.ylabel('$\delta$ [rad]')
129 plt.tight_layout()
130
131 # Show the results unless we are running in batch mode

133 plt.show()
Notes
8.2 Jupyter notebooks
The examples below use python-control in a Jupyter notebook environment. These notebooks demonstrate the use of
modeling, anaylsis, and design tools using running examples in FBS2e.
8.2.1 Cruise control
Richard M. Murray and Karl J. Åström

17 Jun 2019
The cruise control system of a car is a common feedback system encountered in everyday life. The system attempts to
maintain a constant velocity in the presence of disturbances primarily caused by changes in the slope of a road. The
controller compensates for these unknowns by measuring the speed of the car and adjusting the throttle appropriately.
This notebook explores the dynamics and control of the cruise control system, following the material presenting in
Feedback Systems by Astrom and Murray. A nonlinear model of the vehicle dynamics is used, with both state space
and frequency domain control laws. The process model is presented in Section 1, and a controller based on state
feedback is discussed in Section 2, where we also add integral action to the controller. In Section 3 we explore
the behavior with PI control including the effect of actuator saturation and how it is avoided by windup protection.
Different methods of constructing control systems are shown, all using the InputOutputSystem class (and subclasses).
[1]: import numpy as np

8.2. Jupyter notebooks 167


from math import pi
import control as ct
Process Model
Vehicle Dynamics
To develop a mathematical model we start with a force balance for the car body. Let 𝑣 be the speed of the car, 𝑚
the total mass (including passengers), 𝐹 the force generated by the contact of the wheels with the road, and 𝐹𝑑 the
disturbance force due to gravity, friction, and aerodynamic drag.
[2]: def vehicle_update(t, x, u, params={}):

"""Vehicle dynamics for cruise control system.
Parameters
----------
x : array
System state: car velocity in m/s
u : array
System input: [throttle, gear, road_slope], where throttle is
a float between 0 and 1, gear is an integer between 1 and 5,
and road_slope is in rad.
Returns
-------
float
Vehicle acceleration
"""
from math import copysign, sin
sign = lambda x: copysign(1, x) # define the sign() function
# Set up the system parameters

m = params.get('m', 1600.) # vehicle mass, kg
g = params.get('g', 9.8) # gravitational constant, m/s^2
Cr = params.get('Cr', 0.01) # coefficient of rolling friction
Cd = params.get('Cd', 0.32) # drag coefficient
rho = params.get('rho', 1.3) # density of air, kg/m^3
A = params.get('A', 2.4) # car area, m^2
alpha = params.get(
'alpha', [40, 25, 16, 12, 10]) # gear ratio / wheel radius
# Define variables for vehicle state and inputs

v = x[0] # vehicle velocity
throttle = np.clip(u[0], 0, 1) # vehicle throttle
gear = u[1] # vehicle gear
theta = u[2] # road slope
# Force generated by the engine
omega = alpha[int(gear)-1] * v # engine angular speed

F = alpha[int(gear)-1] * motor_torque(omega, params) * throttle
# Disturbance forces


#
# The disturbance force Fd has three major components: Fg, the forces due
# to gravity; Fr, the forces due to rolling friction; and Fa, the
# aerodynamic drag.
# Letting the slope of the road be \theta (theta), gravity gives the
# force Fg = m g sin \theta.
Fg = m * g * sin(theta)
# A simple model of rolling friction is Fr = m g Cr sgn(v), where Cr is

# the coefficient of rolling friction and sgn(v) is the sign of v (±1) or
# zero if v = 0.
Fr = m * g * Cr * sign(v)
# The aerodynamic drag is proportional to the square of the speed: Fa =

# 1/2 \rho Cd A |v| v, where \rho is the density of air, Cd is the
# shape-dependent aerodynamic drag coefficient, and A is the frontal area
# of the car.
Fa = 1/2 * rho * Cd * A * abs(v) * v
# Final acceleration on the car

Fd = Fg + Fr + Fa
dv = (F - Fd) / m
return dv
Engine model
The force F is generated by the engine, whose torque is proportional to the rate of fuel injection, which is itself
proportional to a control signal 0 <= u <= 1 that controls the throttle position. The torque also depends on engine
speed omega.
[3]: def motor_torque(omega, params={}):

# Set up the system parameters
Tm = params.get('Tm', 190.) # engine torque constant
omega_m = params.get('omega_m', 420.) # peak engine angular speed
beta = params.get('beta', 0.4) # peak engine rolloff
return np.clip(Tm * (1 - beta * (omega/omega_m - 1)**2), 0, None)
Torque curves for a typical car engine. The graph on the left shows the torque generated by the engine as a function
of the angular velocity of the engine, while the curve on the right shows torque as a function of car speed for different
gears.
[4]: # Figure 4.2a - single torque curve as function of omega

omega_range = np.linspace(0, 700, 701)
plt.plot(omega_range, [motor_torque(w) for w in omega_range])
plt.xlabel('Angular velocity $\omega$ [rad/s]')
plt.ylabel('Torque $T$ [Nm]')
plt.grid(True, linestyle='dotted')

# Figure 4.2b - torque curves in different gears, as function of velocity

v_range = np.linspace(0, 70, 71)
alpha = [40, 25, 16, 12, 10]
for gear in range(5):
omega_range = alpha[gear] * v_range
plt.plot(v_range, [motor_torque(w) for w in omega_range],
color='blue', linestyle='solid')
# Set up the axes and style

plt.axis([0, 70, 100, 200])
plt.grid(True, linestyle='dotted')
# Add labels
plt.text(11.5, 120, '$n$=1')
plt.text(24, 120, '$n$=2')
plt.text(42.5, 120, '$n$=3')
plt.text(58.5, 120, '$n$=4')
plt.text(58.5, 185, '$n$=5')
plt.xlabel('Velocity $v$ [m/s]')
plt.ylabel('Torque $T$ [Nm]')
plt.tight_layout()
plt.suptitle('Torque curves for typical car engine');
Input/ouput model for the vehicle system
We now create an input/output model for the vehicle system that takes the throttle input 𝑢, the gear and the angle of
the road 𝜃 as input. The output of this model is the current vehicle velocity 𝑣.
[5]: vehicle = ct.NonlinearIOSystem(
vehicle_update, None, name='vehicle',
inputs = ('u', 'gear', 'theta'), outputs = ('v'), states=('v'))
# Define a generator for creating a "standard" cruise control plot

def cruise_plot(sys, t, y, t_hill=5, vref=20, antiwindup=False, linetype='b-',
subplots=[None, None]):
# Figure out the plot bounds and indices
v_min = vref-1.2; v_max = vref+0.5; v_ind = sys.find_output('v')
u_min = 0; u_max = 2 if antiwindup else 1; u_ind = sys.find_output('u')
# Make sure the upper and lower bounds on v are OK



while max(y[v_ind]) > v_max: v_max += 1
while min(y[v_ind]) < v_min: v_min -= 1
# Create arrays for return values

subplot_axes = subplots.copy()
# Velocity profile
if subplot_axes[0] is None:
subplot_axes[0] = plt.subplot(2, 1, 1)
else:
plt.sca(subplots[0])
plt.plot(t, y[v_ind], linetype)
plt.plot(t, vref*np.ones(t.shape), 'k-')
plt.plot([t_hill, t_hill], [v_min, v_max], 'k--')
plt.axis([0, t[-1], v_min, v_max])
plt.xlabel('Time $t$ [s]')
plt.ylabel('Velocity $v$ [m/s]')
# Commanded input profile

if subplot_axes[1] is None:
subplot_axes[1] = plt.subplot(2, 1, 2)
else:
plt.plot(t, y[u_ind], 'r--' if antiwindup else linetype)
plt.plot([t_hill, t_hill], [u_min, u_max], 'k--')
plt.axis([0, t[-1], u_min, u_max])
plt.ylabel('Throttle $u$')
# Applied input profile

if antiwindup:
plt.plot(t, np.clip(y[u_ind], 0, 1), linetype)
plt.legend(['Commanded', 'Applied'], frameon=False)
return subplot_axes
State space controller
Construct a state space controller with integral action, linearized around an equilibrium point. The controller is con-
structed around the equilibrium point (𝑥𝑑 , 𝑢𝑑 ) and includes both feedforward and feedback compensation.
• Controller inputs - (𝑥, 𝑦, 𝑟): system states, system output, reference
• Controller state - 𝑧: integrated error (𝑦 − 𝑟)
• Controller output - 𝑢: state feedback control
Note: to make the structure of the controller more clear, we implement this as a “nonlinear” input/output module, even
though the actual input/output system is linear. This also allows the use of parameters to set the operating point and
gains for the controller.
[6]: def sf_update(t, z, u, params={}):

y, r = u[1], u[2]
return y - r
def sf_output(t, z, u, params={}):



# Get the controller parameters that we need
K = params.get('K', 0)
ki = params.get('ki', 0)
kf = params.get('kf', 0)
xd = params.get('xd', 0)
yd = params.get('yd', 0)
ud = params.get('ud', 0)
# Get the system state and reference input

x, y, r = u[0], u[1], u[2]
return ud - K * (x - xd) - ki * z + kf * (r - yd)
# Create the input/output system for the controller

control_sf = ct.NonlinearIOSystem(
sf_update, sf_output, name='control',
inputs=('x', 'y', 'r'),
outputs=('u'),
states=('z'))
# Create the closed loop system for the state space controller
cruise_sf = ct.InterconnectedSystem(
(vehicle, control_sf), name='cruise',
connections=(
('vehicle.u', 'control.u'),
('control.x', 'vehicle.v'),
('control.y', 'vehicle.v')),
inplist=('control.r', 'vehicle.gear', 'vehicle.theta'),
outlist=('control.u', 'vehicle.v'), outputs=['u', 'v'])
# Define the time and input vectors

T = np.linspace(0, 25, 501)
vref = 20 * np.ones(T.shape)
gear = 4 * np.ones(T.shape)
theta0 = np.zeros(T.shape)
# Find the equilibrium point for the system

Xeq, Ueq = ct.find_eqpt(
vehicle, [vref[0]], [0, gear[0], theta0[0]], y0=[vref[0]], iu=[1, 2])
print("Xeq = ", Xeq)
print("Ueq = ", Ueq)
# Compute the linearized system at the eq pt

cruise_linearized = ct.linearize(vehicle, Xeq, [Ueq[0], gear[0], 0])
Xeq = [20.]
Ueq = [0.16874874 4. 0. ]
[7]: # Construct the gain matrices for the system

A, B, C = cruise_linearized.A, cruise_linearized.B[0, 0], cruise_linearized.C
K = 0.5
kf = -1 / (C * np.linalg.inv(A - B * K) * B)
# Compute the steady state velocity and throttle setting

xd = Xeq[0]
ud = Ueq[0]
yd = vref[-1]

# Response of the system with no integral feedback term

plt.figure()
theta_hill = [
0 if t <= 5 else
4./180. * pi * (t-5) if t <= 6 else
4./180. * pi for t in T]
t, y_sfb = ct.input_output_response(
cruise_sf, T, [vref, gear, theta_hill], [Xeq[0], 0],
params={'K':K, 'ki':0.0, 'kf':kf, 'xd':xd, 'ud':ud, 'yd':yd})
subplots = cruise_plot(cruise_sf, t, y_sfb, t_hill=5, linetype='b--')
# Response of the system with state feedback + integral action

t, y_sfb_int = ct.input_output_response(
cruise_sf, T, [vref, gear, theta_hill], [Xeq[0], 0],
params={'K':K, 'ki':0.1, 'kf':kf, 'xd':xd, 'ud':ud, 'yd':yd})
cruise_plot(cruise_sf, t, y_sfb_int, t_hill=5, linetype='b-', subplots=subplots)
# Add title and legend

plt.suptitle('Cruise control with state feedback, integral action')
import matplotlib.lines as mlines
p_line = mlines.Line2D([], [], color='blue', linestyle='--', label='State feedback')
pi_line = mlines.Line2D([], [], color='blue', linestyle='-', label='w/ integral action
˓→')
plt.legend(handles=[p_line, pi_line], frameon=False, loc='lower right');
Pole/zero cancellation
The transfer function for the linearized dynamics of the cruise control system is given by 𝑃 (𝑠) = 𝑏/(𝑠 + 𝑎). A simple
(but not necessarily good) way to design a PI controller is to choose the parameters of the PI controller as 𝑘i = 𝑎𝑘p .
The controller transfer function is then 𝐶(𝑠) = 𝑘p + 𝑘i /𝑠 = 𝑘i (𝑠 + 𝑎)/𝑠. It has a zero at 𝑠 = −𝑘i /𝑘p = −𝑎 that
cancels the process pole at 𝑠 = −𝑎. We have 𝑃 (𝑠)𝐶(𝑠) = 𝑘i /𝑠 giving the transfer function from reference to vehicle
velocity as 𝐺𝑦𝑟 (𝑠) = 𝑏𝑘p /(𝑠 + 𝑏𝑘p ), and control design is then simply a matter of choosing the gain 𝑘p . The closed
loop system dynamics are of first order with the time constant 1/(𝑏𝑘p ).

[8]: # Get the transfer function from throttle input + hill to vehicle speed
P = ct.ss2tf(cruise_linearized[0, 0])
# Construction a controller that cancels the pole

kp = 0.5
a = -P.pole()[0]
b = np.real(P(0)) * a
ki = a * kp
C = ct.tf2ss(ct.TransferFunction([kp, ki], [1, 0]))
control_pz = ct.LinearIOSystem(C, name='control', inputs='u', outputs='y')
print("system: a = ", a, ", b = ", b)
print("pzcancel: kp =", kp, ", ki =", ki, ", 1/(kp b) = ", 1/(kp * b))
print("sfb_int: K = ", K, ", ki = 0.1")
# Construct the closed loop system and plot the response

# Create the closed loop system for the state space controller
cruise_pz = ct.InterconnectedSystem(
(vehicle, control_pz), name='cruise_pz',
connections = (
('control.u', '-vehicle.v'),
('vehicle.u', 'control.y')),
inplist = ('control.u', 'vehicle.gear', 'vehicle.theta'),
inputs = ('vref', 'gear', 'theta'),
outlist = ('vehicle.v', 'vehicle.u'),
outputs = ('v', 'u'))
# Find the equilibrium point

X0, U0 = ct.find_eqpt(
cruise_pz, [vref[0], 0], [vref[0], gear[0], theta0[0]],
iu=[1, 2], y0=[vref[0], 0], iy=[0])
# Response of the system with PI controller canceling process pole

t, y_pzcancel = ct.input_output_response(
cruise_pz, T, [vref, gear, theta_hill], X0)
subplots = cruise_plot(cruise_pz, t, y_pzcancel, t_hill=5, linetype='b-')
cruise_plot(cruise_sf, t, y_sfb_int, t_hill=5, linetype='b--', subplots=subplots);
system: a = 0.010124405669387215 , b = 1.3203061238159202
pzcancel: kp = 0.5 , ki = 0.005062202834693608 , 1/(kp b) = 1.5148002148317266
sfb_int: K = 0.5 , ki = 0.1

PI Controller
In this example, the speed of the vehicle is measured and compared to the desired speed. The controller is a PI
controller represented as a transfer function. In the textbook, the simulations are done for LTI systems, but here we
simulate the full nonlinear system.
Parameter design through pole placement
To illustrate the design of a PI controller, we choose the gains 𝑘p and 𝑘i so that the characteristic polynomial has the
form
𝑠2 + 2𝜁𝜔0 𝑠 + 𝜔02
[9]: # Values of the first order transfer function P(s) = b/(s + a) are set above
# Define the input that we want to track

theta_hill = np.array([
0 if t <= 5 else
4./180. * pi * (t-5) if t <= 6 else
4./180. * pi for t in T])
# Fix \omega_0 and vary \zeta

w0 = 0.5
subplots = [None, None]
for zeta in [0.5, 1, 2]:
# Create the controller transfer function (as an I/O system)
kp = (2*zeta*w0 - a)/b
ki = w0**2 / b
control_tf = ct.tf2io(
ct.TransferFunction([kp, ki], [1, 0.01*ki/kp]),


name='control', inputs='u', outputs='y')
# Construct the closed loop system by interconnecting process and controller

cruise_tf = ct.InterconnectedSystem(
(vehicle, control_tf), name='cruise',
connections = [('control.u', '-vehicle.v'), ('vehicle.u', 'control.y')],
outlist = ('vehicle.v', 'vehicle.u'), outputs = ('v', 'u'))
# Plot the velocity response

cruise_tf, [vref[0], 0], [vref[0], gear[0], theta_hill[0]],
iu=[1, 2], y0=[vref[0], 0], iy=[0])
t, y = ct.input_output_response(cruise_tf, T, [vref, gear, theta_hill], X0)

subplots = cruise_plot(cruise_tf, t, y, t_hill=5, subplots=subplots)
[10]: # Fix \zeta and vary \omega_0

zeta = 1
for w0 in [0.2, 0.5, 1]:
# Create the controller transfer function (as an I/O system)
kp = (2*zeta*w0 - a)/b
ki = w0**2 / b
ct.TransferFunction([kp, ki], [1, 0.01*ki/kp]),
# Construct the closed loop system by interconnecting process and controller



# Plot the velocity response
cruise_tf, [vref[0], 0], [vref[0], gear[0], theta_hill[0]],
iu=[1, 2], y0=[vref[0], 0], iy=[0])
t, y = ct.input_output_response(cruise_tf, T, [vref, gear, theta_hill], X0)

subplots = cruise_plot(cruise_tf, t, y, t_hill=5, subplots=subplots)
Robustness to change in mass
[11]: # Nominal controller design for remaining analyses

# Construct a PI controller with rolloff, as a transfer function
Kp = 0.5 # proportional gain
Ki = 0.1 # integral gain
ct.TransferFunction([Kp, Ki], [1, 0.01*Ki/Kp]),
inplist = ('control.u', 'vehicle.gear', 'vehicle.theta'), inputs = ('vref', 'gear
˓→', 'theta'),
[12]: # Define the time and input vectors

theta0 = np.zeros(T.shape)
# Now simulate the effect of a hill at t = 5 seconds

plt.figure()
plt.suptitle('Response to change in road slope')
theta_hill = np.array([


0 if t <= 5 else
4./180. * pi * (t-5) if t <= 6 else
4./180. * pi for t in T])

linecolor = ['red', 'blue', 'green']
handles = []
for i, m in enumerate([1200, 1600, 2000]):
# Compute the equilibrium state for the system
cruise_tf, [vref[0], 0], [vref[0], gear[0], theta0[0]],
iu=[1, 2], y0=[vref[0], 0], iy=[0], params={'m':m})
t, y = ct.input_output_response(
cruise_tf, T, [vref, gear, theta_hill], X0, params={'m':m})
subplots = cruise_plot(cruise_tf, t, y, t_hill=5, subplots=subplots,

linetype=linecolor[i][0] + '-')
handles.append(mlines.Line2D([], [], color=linecolor[i], linestyle='-',
label="m = %d" % m))
# Add labels to the plots

plt.ylabel('Speed [m/s]')
plt.legend(handles=handles, frameon=False, loc='lower right');
plt.ylabel('Throttle')
plt.xlabel('Time [s]');
PI controller with antiwindup protection
We now create a more complicated feedback controller that includes anti-windup protection.

[13]: def pi_update(t, x, u, params={}):

ki = params.get('ki', 0.1)
kaw = params.get('kaw', 2) # anti-windup gain
# Assign variables for inputs and states (for readability)

v = u[0] # current velocity
vref = u[1] # reference velocity
z = x[0] # integrated error
# Compute the nominal controller output (needed for anti-windup)

u_a = pi_output(t, x, u, params)
# Compute anti-windup compensation (scale by ki to account for structure)

u_aw = kaw/ki * (np.clip(u_a, 0, 1) - u_a) if ki != 0 else 0
# State is the integrated error, minus anti-windup compensation

return (vref - v) + u_aw
def pi_output(t, x, u, params={}):

kp = params.get('kp', 0.5)
ki = params.get('ki', 0.1)
# Assign variables for inputs and states (for readability)

v = u[0] # current velocity
vref = u[1] # reference velocity
z = x[0] # integrated error
# PI controller
return kp * (vref - v) + ki * z
control_pi = ct.NonlinearIOSystem(
pi_update, pi_output, name='control',
inputs = ['v', 'vref'], outputs = ['u'], states = ['z'],
params = {'kp':0.5, 'ki':0.1})
# Create the closed loop system

cruise_pi = ct.InterconnectedSystem(
(vehicle, control_pi), name='cruise',
connections=(
('vehicle.u', 'control.u'),
('control.v', 'vehicle.v')),
inplist=('control.vref', 'vehicle.gear', 'vehicle.theta'),
outlist=('control.u', 'vehicle.v'), outputs=['u', 'v'])
Response to a small hill
Figure 4.3b shows the response of the closed loop system. The figure shows that even if the hill is so steep that the
throttle changes from 0.17 to almost full throttle, the largest speed error is less than 1 m/s, and the desired velocity is
recovered after 20 s.
[14]: # Compute the equilibrium throttle setting for the desired speed
X0, U0, Y0 = ct.find_eqpt(
cruise_pi, [vref[0], 0], [vref[0], gear[0], theta0[0]],


y0=[0, vref[0]], iu=[1, 2], iy=[1], return_y=True)
# Now simulate the effect of a hill at t = 5 seconds

plt.figure()
plt.suptitle('Car with cruise control encountering sloping road')
theta_hill = [
0 if t <= 5 else
4./180. * pi * (t-5) if t <= 6 else
4./180. * pi for t in T]
cruise_pi, T, [vref, gear, theta_hill], X0)
cruise_plot(cruise_pi, t, y);
Effect of Windup
The windup effect occurs when a car encounters a hill that is so steep (6∘ ) that the throttle saturates when the cruise
controller attempts to maintain speed.
[15]: plt.figure()
plt.suptitle('Cruise control with integrator windup')
theta_hill = [
0 if t <= 5 else
6./180. * pi * (t-5) if t <= 6 else
6./180. * pi for t in T]
cruise_pi, T, [vref, gear, theta_hill], X0,
params={'kaw':0})
cruise_plot(cruise_pi, t, y, antiwindup=True);

PI controller with anti-windup compensation
Anti-windup can be applied to the system to improve the response. Because of the feedback from the actuator model,
the output of the integrator is quickly reset to a value such that the controller output is at the saturation limit.
[16]: plt.figure()
plt.suptitle('Cruise control with integrator anti-windup protection')
cruise_pi, T, [vref, gear, theta_hill], X0,
params={'kaw':2.})
cruise_plot(cruise_pi, t, y, antiwindup=True);
[ ]:

8.2.2 Vehicle steering
Karl J. Astrom and Richard M. Murray

23 Jul 2019
This notebook contains the computations for the vehicle steering running example in Feedback Systems.
RMM comments to Karl, 27 Jun 2019 * I’m using this notebook to walk through all of the vehicle steering examples
and make sure that all of the parameters, conditions, and maximum steering angles are consitent and reasonable.
* Please feel free to send me comments on the contents as well as the bulletted notes, in whatever form is most
convenient. * Once we have sorted out all of the settings we want to use, I’ll copy over the changes into the MATLAB
files that we use for creating the figures in the book. * These notes will be removed from the notebook once we have
finalized everything.
[1]: import numpy as np
import control as ct
ct.use_fbs_defaults()
ct.use_numpy_matrix(False)
Vehicle steering dynamics (Example 3.11)
The vehicle dynamics are given by a simple bicycle model. We take the state of the system as (𝑥, 𝑦, 𝜃) where (𝑥, 𝑦) is
the position of the reference point of the vehicle in the plane and 𝜃 is the angle of the vehicle with respect to horizontal.
The vehicle input is given by (𝑣, 𝛿) where 𝑣 is the forward velocity of the vehicle and 𝛿 is the angle of the steering
wheel. We take as parameters the wheelbase 𝑏 and the offset 𝑎 between the rear wheels and the reference point. The
model includes saturation of the vehicle steering angle (maxsteer).
• System state: x, y, theta
• System input: v, delta
• System output: x, y
• System parameters: wheelbase, refoffset, maxsteer
Assuming no slipping of the wheels, the motion of the vehicle is given by a rotation around a point O that depends
on the steering angle 𝛿. To compute the angle 𝛼 of the velocity of the reference point with respect to the axis of the
vehicle, we let the distance from the center of rotation O to the contact point of the rear wheel be 𝑟r and it the follows
from Figure 3.17 in FBS that 𝑏 = 𝑟r tan 𝛿 and 𝑎 = 𝑟r tan 𝛼, which implies that tan 𝛼 = (𝑎/𝑏) tan 𝛿.
Reasonable limits for the steering angle depend on the speed. The physical limit is given in our model as 0.5 radians
(about 30 degrees). However, this limit is rarely possible when the car is driving since it would cause the tires to
slide on the pavement. We us a limit of 0.1 radians (about 6 degrees) at 10 m/s (≈ 35 kph) and 0.05 radians (about
3 degrees) at 30 m/s (≈ 110 kph). Note that a steering angle of 0.05 rad gives a cross acceleration of (𝑣 2 /𝑏) tan 𝛿 ≈
(100/3)0.05 = 1.7 m/s2 at 10 m/s and 15 m/s2 at 30 m/s (≈ 1.5 times the force of gravity).
[2]: def vehicle_update(t, x, u, params):
# Get the parameters for the model
a = params.get('refoffset', 1.5) # offset to vehicle reference point
b = params.get('wheelbase', 3.) # vehicle wheelbase
maxsteer = params.get('maxsteer', 0.5) # max steering angle (rad)
# Saturate the steering input

delta = np.clip(u[1], -maxsteer, maxsteer)
alpha = np.arctan2(a * np.tan(delta), b)

# Return the derivative of the state

return np.array([
u[0] * np.cos(x[2] + alpha), # xdot = cos(theta + alpha) v
u[0] * np.sin(x[2] + alpha), # ydot = sin(theta + alpha) v
(u[0] / b) * np.tan(delta) # thdot = v/l tan(phi)
])
def vehicle_output(t, x, u, params):

return x[0:2]
# Default vehicle parameters (including nominal velocity)

vehicle_params={'refoffset': 1.5, 'wheelbase': 3, 'velocity': 15,
'maxsteer': 0.5}
# Define the vehicle steering dynamics as an input/output system

vehicle = ct.NonlinearIOSystem(
vehicle_update, vehicle_output, states=3, name='vehicle',
inputs=('v', 'delta'), outputs=('x', 'y'), params=vehicle_params)
Vehicle driving on a curvy road (Figure 8.6a)
To illustrate the dynamics of the system, we create an input that correspond to driving down a curvy road. This
trajectory will be used in future simulations as a reference trajectory for estimation and control.
RMM notes, 27 Jun 2019: * The figure below appears in Chapter 8 (output feedback) as Example 8.3, but I’ve put
it here in the notebook since it is a good way to demonstrate the dynamics of the vehicle. * In the book, this figure
is created for the linear model and in a manner that I can’t quite understand, since the linear model that is used
is only for the lateral dynamics. The original file is OutputFeedback/figures/steering_obs.m. * To
create the figure here, I set the initial vehicle angle to be 𝜃(0) = 0.75 rad and then used an input that gives a figure
approximating Example 8.3 To create the lateral offset, I think subtracted the trajectory from the averaged straight line
trajectory, shown as a dashed line in the 𝑥𝑦 figure below. * I find the approach that we used in the MATLAB version
to be confusing, but I also think the method of creating the lateral error here is a hart to follow. We might instead
consider choosing a trajectory that goes mainly vertically, with the 2D dynamics being the 𝑥, 𝜃 dynamics instead of
the 𝑦, 𝜃 dynamics.
KJA comments, 1 Jul 2019:
0. I think we should point out that the reference point is typically the projection of the center of mass of the whole
vehicle.
1. The heading angle 𝜃 must be marked in Figure 3.17b.
2. I think it is useful to start with a curvy road that you have done here but then to specialized to a trajectory that is
essentially horizontal, where 𝑦 is the deviation from the nominal horizontal 𝑥 axis. Assuming that 𝛼 and 𝜃 are
small we get the natural linearization of (3.26) 𝑥˙ = 𝑣 and 𝑦˙ = 𝑣(𝛼 + 𝜃)
RMM response, 16 Jul 2019: * I’ve changed the trajectory to be about the horizontal axis, but I am ploting things
vertically for better figure layout. This corresponds to what is done in Example 9.10 in the text, which I think looks
OK.
KJA response, 20 Jul 2019: Fig 8.6a is fine
[3]: # System parameters

wheelbase = vehicle_params['wheelbase']
v0 = vehicle_params['velocity']

# Control inputs
T_curvy = np.linspace(0, 7, 500)
v_curvy = v0*np.ones(T_curvy.shape)
delta_curvy = 0.1*np.sin(T_curvy)*np.cos(4*T_curvy) + 0.0025*np.sin(T_curvy*np.pi/7)
u_curvy = [v_curvy, delta_curvy]
X0_curvy = [0, 0.8, 0]
# Simulate the system + estimator

t_curvy, y_curvy, x_curvy = ct.input_output_response(
vehicle, T_curvy, u_curvy, X0_curvy, params=vehicle_params, return_x=True)
# Configure matplotlib plots to be a bit bigger and optimize layout

plt.figure(figsize=[9, 4.5])
# Plot the resulting trajectory (and some road boundaries)

plt.plot(y_curvy[1], y_curvy[0])
plt.plot(y_curvy[1] - 9/np.cos(x_curvy[2]), y_curvy[0], 'k-', linewidth=1)
plt.plot(y_curvy[1] - 3/np.cos(x_curvy[2]), y_curvy[0], 'k--', linewidth=1)
plt.plot(y_curvy[1] + 3/np.cos(x_curvy[2]), y_curvy[0], 'k-', linewidth=1)
plt.xlabel('y [m]')
plt.ylabel('x [m]');
plt.axis('Equal')
# Plot the lateral position

plt.plot(t_curvy, y_curvy[1])
plt.ylabel('Lateral position $y$ [m]')
# Plot the steering angle

plt.plot(t_curvy, delta_curvy)
plt.ylabel('Steering angle $\\delta$ [rad]')
plt.xlabel('Time t [sec]')
plt.tight_layout()

Linearization of lateral steering dynamics (Example 6.13)
We are interested in the motion of the vehicle about a straight-line path (𝜃 = 𝜃0 ) with constant velocity 𝑣0 ̸= 0. To
find the relevant equilibrium point, we first set 𝜃˙ = 0 and we see that we must have 𝛿 = 0, corresponding to the
steering wheel being straight. The motion in the xy plane is by definition not at equilibrium and so we focus on lateral
deviation of the vehicle from a straight line. For simplicity, we let 𝜃e = 0, which corresponds to driving along the 𝑥
axis. We can then focus on the equations of motion in the 𝑦 and 𝜃 directions with input 𝑢 = 𝛿.
[4]: # Define the lateral dynamics as a subset of the full vehicle steering dynamics
lateral = ct.NonlinearIOSystem(
lambda t, x, u, params: vehicle_update(
t, [0., x[0], x[1]], [params.get('velocity', 1), u[0]], params)[1:],
lambda t, x, u, params: vehicle_output(
t, [0., x[0], x[1]], [params.get('velocity', 1), u[0]], params)[1:],
states=2, name='lateral', inputs=('phi'), outputs=('y')
)
# Compute the linearization at velocity v0 = 15 m/sec

lateral_linearized = ct.linearize(lateral, [0, 0], [0], params=vehicle_params)
# Normalize dynamics using state [x1/b, x2] and timescale v0 t / b

b = vehicle_params['wheelbase']
v0 = vehicle_params['velocity']
lateral_transformed = ct.similarity_transform(
lateral_linearized, [[1/b, 0], [0, 1]], timescale=v0/b)
# Set the output to be the normalized state x1/b

lateral_normalized = lateral_transformed * (1/b)
print("Linearized system dynamics:\n")
print(lateral_normalized)
# Save the system matrices for later use

A = lateral_normalized.A


B = lateral_normalized.B
C = lateral_normalized.C
Linearized system dynamics:
A = [[0. 1.]
[0. 0.]]
B = [[0.5]
[1. ]]
C = [[1. 0.]]
D = [[0.]]
Eigenvalue placement controller design (Example 7.4)
We want to design a controller that stabilizes the dynamics of the vehicle and tracks a given reference value 𝑟 of
the lateral position of the vehicle. We use feedback to design the dynamics of the system to have the characteristic
polynomial 𝑝(𝑠) = 𝑠2 + 2𝜁c 𝜔c + 𝜔c2 .
To find reasonable values of 𝜔c we observe that the initial response of the steering angle to a unit step change in the
steering command is 𝜔c2 𝑟, where 𝑟 is the commanded lateral transition. Recall that the model is normalized so that the
length unit is the wheelbase 𝑏 and the time unit is the time 𝑏/𝑣0 to travel one wheelbase. A typical car has a wheelbase
of about 3 m and, assuming a speed of 30 m/s, a normalized time unit corresponds to 0.1 s. To determine a reasonable
steering angle when making a gentle lane change, we assume that the turning radius is 𝑅 = 600 m. For a wheelbase
of 3 m this corresponds to a steering angle 𝛿 ≈ 3/600 = 0.005 rad and a lateral acceleration of 𝑣√2 /𝑅 = 302/600 = 1.5
m/s2 . Assuming that a lane change corresponds to a translation of one wheelbase we find 𝜔c = 0.005 = 0.07 rad/s.
The unit step responses for the closed loop system for different values of the design parameters are shown below. The
effect of 𝜔𝑐 is shown on the left, which shows that the response speed increases with increasing 𝜔c . All responses have
overshoot less than 5% (15 cm), as indicated by the dashed lines. The settling times range from 30 to 60 normalized
time units, which corresponds to about 3–6 s, and are limited by the acceptable lateral acceleration of the vehicle. The
effect of 𝜁c is shown on the right. The response speed and the overshoot increase with decreasing damping. Using
these plots, we conclude that a reasonable design choice is 𝜔c = 0.07 and 𝜁c = 0.7.
RMM note, 27 Jun 2019: * The design guidelines are for 𝑣0 = 30 m/s (highway speeds) but most of the examples
below are done at lower speed (typically 10 m/s). Also, the eigenvalue locations above are not the same ones that we
use in the output feedback example below. We should probably make things more consistent.
KJA comment, 1 Jul 2019: * I am all for maikng it consist and choosing e.g. v0 = 30 m/s
RMM comment, 17 Jul 2019: * I’ve updated the examples below to use v0 = 30 m/s for everything except the
forward/reverse example. This corresponds to ~105 kph (freeway speeds) and a reasonable bound for the steering
angle to avoid slipping is 0.05 rad.
[5]: # Utility function to place poles for the normalized vehicle steering system
def normalized_place(wc, zc):
# Get the dynamics and input matrices, for later use
A, B = lateral_normalized.A, lateral_normalized.B
# Compute the eigenvalues from the characteristic polynomial

eigs = np.roots([1, 2*zc*wc, wc**2])
# Compute the feedback gain using eigenvalue placement



K = ct.place_varga(A, B, eigs)
# Create a new system representing the closed loop response

clsys = ct.StateSpace(A - B @ K, B, lateral_normalized.C, 0)
# Compute the feedforward gain based on the zero frequency gain of the closed loop
kf = np.real(1/clsys.evalfr(0))
# Scale the input by the feedforward gain

clsys *= kf
# Return gains and closed loop system dynamics

return K, kf, clsys
# Utility function to plot simulation results for normalized vehicle steering system
def normalized_plot(t, y, u, inpfig, outfig):
plt.sca(outfig)
plt.plot(t, y)
plt.sca(inpfig)
plt.plot(t, u[0])
# Utility function to label plots of normalized vehicle steering system

def normalized_label(inpfig, outfig):
plt.sca(inpfig)
plt.xlabel('Normalized time $v_0 t / b$')
plt.ylabel('Steering angle $\delta$ [rad]')
plt.sca(outfig)
plt.ylabel('Lateral position $y/b$')
plt.plot([0, 20], [0.95, 0.95], 'k--')
plt.plot([0, 20], [1.05, 1.05], 'k--')

# Explore range of values for omega_c, with zeta_c = 0.7

outfig = plt.subplot(2, 2, 1)
inpfig = plt.subplot(2, 2, 3)
zc = 0.7
for wc in [0.5, 0.7, 1]:
# Place the poles of the system
K, kf, clsys = normalized_place(wc, zc)
# Compute the step response

t, y, x = ct.step_response(clsys, np.linspace(0, 20, 100), return_x=True)
# Compute the input used to generate the control response

u = -K @ x + kf * 1
# Plot the results

normalized_plot(t, y, u, inpfig, outfig)
# Add labels to the figure

normalized_label(inpfig, outfig)
plt.legend(('$\omega_c = 0.5$', '$\omega_c = 0.7$', '$\omega_c = 0.1$'))
# Explore range of values for zeta_c, with omega_c = 0.07



outfig = plt.subplot(2, 2, 2)
inpfig = plt.subplot(2, 2, 4)
wc = 0.7
for zc in [0.5, 0.7, 1]:
# Place the poles of the system
K, kf, clsys = normalized_place(wc, zc)
# Compute the step response

t, y, x = ct.step_response(clsys, np.linspace(0, 20, 100), return_x=True)
# Compute the input used to generate the control response

u = -K @ x + kf * 1
# Plot the results

normalized_plot(t, y, u, inpfig, outfig)
# Add labels to the figure

normalized_label(inpfig, outfig)
plt.legend(('$\zeta_c = 0.5$', '$\zeta_c = 0.7$', '$\zeta_c = 1$'))
plt.tight_layout()
RMM notes, 17 Jul 2019 * These step responses are very slow. Note that the steering wheel angles are about 10X
less than a resonable bound (0.05 rad at 30 m/s). A consequence of these low gains is that the tracking controller in
Example 8.4 has to use a different set of gains. We could update, but the gains listed here have a rationale that we
would have to update as well. * Based on the discussion below, I think we should make 𝜔c range from 0.5 to 1 (10X
faster).
KJA response, 20 Jul 2019: Makes a lot of sense to make 𝜔c range from 0.5 to 1 (10X faster). The plots were still in
the range 0.05 to 0.1 in the note you sent me.
RMM response: 23 Jul 2019: Updated 𝜔c to 10X faster. Note that this makes size of the inputs for the step response
quite large, but that is in part because a unit step in the desired position produces an (instantaneous) error of 𝑏 = 3 m
=⇒ quite a large error. A lateral error of 10 cm with 𝜔𝑐 = 0.7 would produce an (initial) input of 0.015 rad.

Eigenvalue placement observer design (Example 8.3)
We construct an estimator for the (normalized) lateral dynamics by assigning the eigenvalues of the estimator dynamics
to desired value, specifified in terms of the second order characteristic equation for the estimator dynamics.
[6]: # Find the eigenvalue from the characteristic polynomial

wo = 1 # bandwidth for the observer
zo = 0.7 # damping ratio for the observer
eigs = np.roots([1, 2*zo*wo, wo**2])
# Compute the estimator gain using eigenvalue placement

L = np.transpose(
ct.place(np.transpose(A), np.transpose(C), eigs))
print("L = ", L)
# Create a linear model of the lateral dynamics driving the estimator

est = ct.StateSpace(A - L @ C, np.block([[B, L]]), np.eye(2), np.zeros((2,2)))
L = [[1.4]
[1. ]]
Linear observer applied to nonlinear system output
A simulation of the observer for a vehicle driving on a curvy road is shown below. The first figure shows the trajectory
of the vehicle on the road, as viewed from above. The response of the observer is shown on the right, where time is
normalized to the vehicle length. We see that the observer error settles in about 4 vehicle lengths.
RMM note, 27 Jun 2019: * As an alternative, we can attempt to estimate the state of the full nonlinear system using a
linear estimator. This system does not necessarily converge to zero since there will be errors in the nominal dynamics
of the system for the linear estimator. * The limits on the 𝑥 axis for the time plots are different to show the error over
the entire trajectory. * We should decide whether we want to keep the figure above or the one below for the text.
KJA comment, 1 Jul 2019: * I very much like your observation about the nonlinear system. I think it is a very good
idea to use your new simulation
RMM comment, 17 Jul 2019: plan to use this version in the text.
KJA comment, 20 Jul 2019: I think this is a big improvement we show that an observer based on a linearized model
works on a nonlinear simulation, If possible we could add a line telling why the linear model works and that this is
standard procedure in control engineering.
[7]: # Convert the curvy trajectory into normalized coordinates

x_ref = x_curvy[0] / wheelbase
y_ref = x_curvy[1] / wheelbase
theta_ref = x_curvy[2]
tau = v0 * T_curvy / b
# Simulate the estimator, with a small initial error in y position

t, y_est, x_est = ct.forced_response(est, tau, [delta_curvy, y_ref], [0.5, 0])

# Plot the actual and estimated states

ax = plt.subplot(2, 2, 1)
plt.plot(t, y_ref)
plt.plot(t, x_est[0])


ax.set(xlim=[0, 10])
plt.legend(['actual', 'estimated'])
plt.plot(t, x_est[0] - y_ref)
plt.ylabel('Lateral error')
plt.plot(t, theta_ref)
plt.plot(t, x_est[1])
plt.ylabel('Vehicle angle $\\theta$')
plt.plot(t, x_est[1] - theta_ref)
plt.ylabel('Angle error')
plt.tight_layout()
Output Feedback Controller (Example 8.4)
RMM note, 27 Jun 2019 * The feedback gains for the controller below are different that those computed in the
eigenvalue placement example (from Ch 7), where an argument was given for the choice of the closed loop eigenvalues.
Should we choose a single, consistent set of gains in both places? * This plot does not quite match Example 8.4 because
a different reference is being used for the laterial position. * The transient in 𝛿 is quiet large. This appears to be due to
the error in 𝜃(0), which is initialized to zero intead of to theta_curvy.
KJA comment, 1 Jul 2019: 1. The large initial errors dominate the plots.
2. There is somehing funny happening at the end of the simulation, may be due to the small curvature at the end of

the path?
RMM comment, 17 Jul 2019: * Updated to use the new trajectory * We will have the issue that the gains here are
different than the gains that we used in Chapter 7. I think that what we need to do is update the gains in Ch 7 (they are
too sluggish, as noted above). * Note that unlike the original example in the book, the errors do not converge to zero.
This is because we are using pure state feedback (no feedforward) => the controller doesn’t apply any input until there
is an error.
KJA comment, 20 Jul 2019: We may add that state feedback is a proportional controller which does not guarantee
that the error goes to zero for example by changing the line “The tracking error . . . ” to “The tracking error can be
improved by adding integral action (Section7.4), later in this chapter “Disturbance Modeling” or feedforward (Section
8,5). Should we do an exercises?
[8]: # Compute the feedback gains

# K, kf, clsys = normalized_place(1, 0.707) # Gains from MATLAB
# K, kf, clsys = normalized_place(0.07, 0.707) # Original gains
K, kf, clsys = normalized_place(0.7, 0.707) # Final gains
# Print out the gains

print("K = ", K)
print("kf = ", kf)
# Construct an output-based controller for the system

clsys = ct.StateSpace(
np.block([[A, -B@K], [L@C, A - B@K - L@C]]),
np.block([[B], [B]]) * kf,
np.block([[C, np.zeros(C.shape)], [np.zeros(C.shape), C]]),
np.zeros((2,1)))

t, y, x = ct.forced_response(clsys, tau, y_ref, [0.4, 0, 0.0, 0])
# Calcaluate the input used to generate the control response

u_sfb = kf * y_ref - K @ x[0:2]
u_ofb = kf * y_ref - K @ x[2:4]

# Plot the actual and estimated states

plt.plot(t, x[0])
plt.plot(t, x[2])
plt.plot(t, y_ref, 'k-.')
plt.legend(['state feedback', 'output feedback', 'reference'])
plt.plot(t, x[1])
plt.plot(t, x[3])
plt.plot(t, theta_ref, 'k-.')
plt.ylabel('Vehicle angle $\\theta$')
plt.plot(t, u_sfb[0])


plt.plot(t, u_ofb[0])
plt.plot(t, delta_curvy, 'k-.')
plt.ylabel('Steering angle $\\delta$')
plt.tight_layout()
K = [[0.49 0.7448]]
kf = [[0.49]]
Trajectory Generation (Example 8.8)
To illustrate how we can use a two degree-of-freedom design to improve the performance of the system, consider the
problem of steering a car to change lanes on a road. We use the non-normalized form of the dynamics, which were
derived in Example 3.11.
KJA comment, 1 Jul 2019: 1. I think the reference trajectory is too much curved in the end compare with Example
3.11
In summary I think it is OK to change the reference trajectories but we should make sure that the curvature is less than
𝜌 = 600𝑚 not to have too high acceleratarion.
RMM response, 16 Jul 2019: * Not sure if the comment about the trajectory being too curved is referring to this
example. The steering angles (and hence radius of curvature/acceleration) are quite low. ??
KJA response, 20 Jul 2019: You are right the curvature is not too small. We could add the sentence “The small
deviations can be eliminated by adding feedback.”
RMM response, 23 Jul 2019: I think the small deviation you are referring to is in the velocity trace. This occurs
because I gave a fixed endpoint in time and so the velocity had to be adjusted to hit that exact point at that time. This
doesn’t show up in the book, so it won’t be a problem ( =⇒ no additional explanation required).
[9]: import control.flatsys as fs
# Function to take states, inputs and return the flat flag



def vehicle_flat_forward(x, u, params={}):
# Create a list of arrays to store the flat output and its derivatives
zflag = [np.zeros(3), np.zeros(3)]
# Flat output is the x, y position of the rear wheels

zflag[0][0] = x[0]
zflag[1][0] = x[1]
# First derivatives of the flat output

zflag[0][1] = u[0] * np.cos(x[2]) # dx/dt
zflag[1][1] = u[0] * np.sin(x[2]) # dy/dt
# First derivative of the angle

thdot = (u[0]/b) * np.tan(u[1])
# Second derivatives of the flat output (setting vdot = 0)

zflag[0][2] = -u[0] * thdot * np.sin(x[2])
zflag[1][2] = u[0] * thdot * np.cos(x[2])
return zflag
# Function to take the flat flag and return states, inputs

def vehicle_flat_reverse(zflag, params={}):
# Create a vector to store the state and inputs

x = np.zeros(3)
u = np.zeros(2)
# Given the flat variables, solve for the state

x[0] = zflag[0][0] # x position
x[1] = zflag[1][0] # y position
x[2] = np.arctan2(zflag[1][1], zflag[0][1]) # tan(theta) = ydot/xdot
# And next solve for the inputs

u[0] = zflag[0][1] * np.cos(x[2]) + zflag[1][1] * np.sin(x[2])
thdot_v = zflag[1][2] * np.cos(x[2]) - zflag[0][2] * np.sin(x[2])
u[1] = np.arctan2(thdot_v, u[0]**2 / b)
return x, u
vehicle_flat = fs.FlatSystem(vehicle_flat_forward, vehicle_flat_reverse, inputs=2,

˓→states=3)
To find a trajectory from an initial state 𝑥0 to a final state 𝑥f in time 𝑇f we solve a point-to-point trajectory generation
problem. We also set the initial and final inputs, which sets the vehicle velocity 𝑣 and steering wheel angle 𝛿 at the
endpoints.
[10]: # Define the endpoints of the trajectory

x0 = [0., 2., 0.]; u0 = [15, 0.]
xf = [75, -2., 0.]; uf = [15, 0.]
Tf = xf[0] / uf[0]

# Define a set of basis functions to use for the trajectories

poly = fs.PolyFamily(6)
# Find a trajectory between the initial condition and the final condition
traj = fs.point_to_point(vehicle_flat, x0, u0, xf, uf, Tf, basis=poly)
# Create the trajectory

t = np.linspace(0, Tf, 100)
x, u = traj.eval(t)

# Plot the trajectory in xy coordinate

plt.plot(x[1], x[0])
plt.xlabel('y [m]')
plt.ylabel('x [m]')
# Add lane lines and scale the axis

plt.plot([-4, -4], [0, x[0, -1]], 'k-', linewidth=1)
plt.plot([0, 0], [0, x[0, -1]], 'k--', linewidth=1)
plt.plot([4, 4], [0, x[0, -1]], 'k-', linewidth=1)
plt.axis([-10, 10, -5, x[0, -1] + 5])
# Time traces of the state and input

plt.plot(t, x[1])
plt.ylabel('y [m]')
plt.plot(t, x[2])
plt.ylabel('theta [rad]')
plt.plot(t, u[0])
plt.ylabel('v [m/s]')
plt.axis([0, Tf, u0[0] - 1, uf[0] +1])
plt.plot(t, u[1]);
plt.ylabel('$\delta$ [rad]')
plt.tight_layout()

Vehicle transfer functions for forward and reverse driving (Example 10.11)
The vehicle steering model has different properties depending on whether we are driving forward or in reverse. The
figures below show step responses from steering angle to lateral translation for a the linearized model when driving
forward (dashed) and reverse (solid). In this simulation we have added an extra pole with the time constant 𝑇 = 0.1
to approximately account for the dynamics in the steering system.
With rear-wheel steering the center of mass first moves in the wrong direction and the overall response with rear-
wheel steering is significantly delayed compared with that for front-wheel steering. (b) Frequency response for driving
forward (dashed) and reverse (solid). Notice that the gain curves are identical, but the phase curve for driving in reverse
has non-minimum phase.
RMM note, 27 Jun 2019: * I cannot recreate the figures in Example 10.11. Since we are looking at the lateral velocity,
there is a differentiator in the output and this takes the step function and creates an offset at 𝑡 = 0 (intead of a smooth
curve). * The transfer functions are also different, and I don’t quite understand why. Need to spend a bit more time on
this one.
KJA comment, 1 Jul 2019: The reason why you cannot recreate figures i Example 10.11 is because the caption in
figure is wrong, sorry my fault, the y-axis should be lateral position not lateral velocity. The approximate expression
for the transfer functions
𝑎𝑣0 𝑠 + 𝑣02 1.5𝑠 + 1 0.5𝑠 + 0.33
𝐺𝑦𝛿 = = 2
=
𝑏𝑠 3𝑠 𝑠
are quite close to the values that you get numerically
In this case I think it is useful to have v=1 m/s because we do not drive to fast backwards.
RMM response, 17 Jul 2019 * Updated figures below use the same parameters as the running example (the current text
uses different parameters) * Following the material in the text, a pole is added at s = -1 to approximate the dynamics
of the steering system. This is not strictly needed, so we could decide to take it out (and update the text)
KJA comment, 20 Jul 2019: I have been oscillating a bit about this example. Of course it does not make sense to drive
in reverse in 30 m/s but it seems a bit silly to change parameters just in this case (if we do we have to motivate it). On
the other hand what we are doing is essentially based on transfer functions and a RHP zero. My current view which

has changed a few times is to keep the standard parameters. In any case we should eliminate the extra time constant.
A small detail, I could not see the time response in the file you sent, do not resend it!, I will look at the final version.
RMM comment, 23 Jul 2019: I think it is OK to have the speed be different and just talk about this in the text. I have
removed the extra time constant in the current version.
[11]: # Magnitude of the steering input (half maximum)

Msteer = vehicle_params['maxsteer'] / 2
# Create a linearized model of the system going forward at 2 m/s

forward_lateral = ct.linearize(lateral, [0, 0], [0], params={'velocity': 2})
forward_tf = ct.ss2tf(forward_lateral)[0, 0]
print("Forward TF = ", forward_tf)
# Create a linearized model of the system going in reverise at 1 m/s

reverse_lateral = ct.linearize(lateral, [0, 0], [0], params={'velocity': -2})
reverse_tf = ct.ss2tf(reverse_lateral)[0, 0]
print("Reverse TF = ", reverse_tf)
Forward TF =
s + 1.333
-----------------------------
s^2 + 7.828e-16 s - 1.848e-16
Reverse TF =
-s + 1.333
-----------------------------
s^2 - 7.828e-16 s - 1.848e-16
[12]: # Configure matplotlib plots to be a bit bigger and optimize layout

plt.figure()
# Forward motion
t, y = ct.step_response(forward_tf * Msteer, np.linspace(0, 4, 500))
plt.plot(t, y, 'b--')
# Reverse motion
t, y = ct.step_response(reverse_tf * Msteer, np.linspace(0, 4, 500))
plt.plot(t, y, 'b-')
# Add labels and reference lines

plt.axis([0, 4, -0.5, 2.5])
plt.legend(['forward', 'reverse'], loc='upper left')
plt.ylabel('Lateral position [m]')
plt.plot([0, 4], [0, 0], 'k-', linewidth=1)
# Plot the Bode plots

plt.figure()
ct.bode_plot(forward_tf[0, 0], np.logspace(-1, 1, 100), color='b', linestyle='--')
ct.bode_plot(reverse_tf[0, 0], np.logspace(-1, 1, 100), color='b', linestyle='-')
plt.legend(('forward', 'reverse'));

Feedforward Compensation (Example 12.6)
For a lane transfer system we would like to have a nice response without overshoot, and we therefore consider the
use of feedforward compensation to provide a reference trajectory for the closed loop system. We choose the desired
response as 𝐹m (𝑠) = 𝑎2 2/(𝑠 + 𝑎)2 , where the response speed or aggressiveness of the steering is governed by the
parameter 𝑎.
RMM note, 27 Jun 2019: * 𝑎 was used in the original description of the dynamics as the reference offset. Perhaps
choose a different symbol here? * In current version of Ch 12, the 𝑦 axis is labeled in absolute units, but it should
actually be in normalized units, I think. * The steering angle input for this example is quite high. Compare to Example
8.8, above. Also, we should probably make the size of the “lane change” from this example match whatever we use in
Example 8.8
KJA comments, 1 Jul 2019: Chosen parameters look good to me
RMM response, 17 Jul 2019 * I changed the time constant for the feedforward model to give something that is more
reasonable in terms of turning angle at the speed of 𝑣0 = 30 m/s. Note that this takes about 30 body lengths to change
lanes (= 9 seconds at 105 kph). * The time to change lanes is about 2X what it is using the differentially flat trajectory

above. This is mainly because the feedback controller applies a large pulse at the beginning of the trajectory (based
on the input error), whereas the differentially flat trajectory spreads the turn over a longer interval. Since are living the
steering angle, we have to limit the size of the pulse => slow down the time constant for the reference model.
KJA response, 20 Jul 2019: I think the time for lane change is too long, which may depend on the small steering angles
used. The largest steering angle is about 0.03 rad, but we have admitted larger values in previous examples. I suggest
that we change the design so that the largest sterring angel is closer to 0.05, see the remark from Bjorn O a lane change
could take about 5 s at 30m/s.
RMM response, 23 Jul 2019: I reset the time constant to 0.2, which gives something closer to what we had for
trajectory generation. It is still slower, but this is to be expected since it is a linear controller. We now finish the
trajectory in 20 body lengths, which is about 6 seconds.
[13]: # Define the desired response of the system

a = 0.2
P = ct.ss2tf(lateral_normalized)
Fm = ct.TransferFunction([a**2], [1, 2*a, a**2])
Fr = Fm / P
# Compute the step response of the feedforward components

t, y_ffwd = ct.step_response(Fm, np.linspace(0, 25, 100))
t, delta_ffwd = ct.step_response(Fr, np.linspace(0, 25, 100))
# Scale and shift to correspond to lane change (-2 to +2)

y_ffwd = 0.5 - 1 * y_ffwd
delta_ffwd *= 1
# Overhead view
plt.plot(y_ffwd, t)
plt.plot(-1*np.ones(t.shape), t, 'k-', linewidth=1)
plt.plot(0*np.ones(t.shape), t, 'k--', linewidth=1)
plt.plot(1*np.ones(t.shape), t, 'k-', linewidth=1)
plt.axis([-5, 5, -2, 27])
# Plot the response

plt.plot(t, y_ffwd)
# plt.axis([0, 10, -5, 5])
plt.ylabel('Normalized position y/b')
plt.plot(t, delta_ffwd)
# plt.axis([0, 10, -1, 1])
plt.ylabel('$\\delta$ [rad]')
plt.xlabel('Normalized time $v_0 t / b$');
plt.tight_layout()

Fundamental Limits (Example 14.13)
Consider a controller based on state feedback combined with an observer where we want a faster closed loop system
and choose 𝜔c = 10, 𝜁c = 0.707, 𝜔o = 20, and 𝜁o = 0.707.
KJA comment, 20 Jul 2019: This is a really troublesome case. If we keep it as a vehicle steering problem we must
have an order of magnitude lower valuer for 𝜔𝑐 and 𝜔𝑜 and then the zero will not be slow. My recommendation is to
keep it as a general system with the transfer function. 𝑃 (𝑠) = (𝑠 + 1)/𝑠2 . The text then has to be reworded.
RMM response, 23 Jul 2019: I think the way we have it is OK. Our current value for the controller and observer is
𝜔c = 0.7 and 𝜔o = 1. Here we way we want something faster and so we got to 𝜔c = 7 (10X) and 𝜔o = 10 (10X).
[14]: # Compute the feedback gain using eigenvalue placement

wc = 10
zc = 0.707
K = ct.place(A, B, eigs)
kr = np.real(1/clsys.evalfr(0))
print("K = ", np.squeeze(K))
# Compute the estimator gain using eigenvalue placement

wo = 20
zo = 0.707
eigs = np.roots([1, 2*zo*wo, wo**2])
L = np.transpose(
ct.place(np.transpose(A), np.transpose(C), eigs))
print("L = ", np.squeeze(L))

C1 = ct.ss2tf(ct.StateSpace(A - B@K - L@C, L, K, 0))
print("C(s) = ", C1)
# Compute the loop transfer function and plot Nyquist, Bode

L1 = P * C1
plt.figure(); ct.nyquist_plot(L1, np.logspace(0.5, 3, 500))
plt.figure(); ct.bode_plot(L1, np.logspace(-1, 3, 500));

K = [100. -35.86]
L = [ 28.28 400. ]
C(s) =
-1.152e+04 s + 4e+04
--------------------
s^2 + 42.42 s + 6658
[15]: # Modified control law

wc = 10
zc = 2.6
K = ct.place(A, B, eigs)
kr = np.real(1/clsys.evalfr(0))
print("K = ", np.squeeze(K))

C2 = ct.ss2tf(ct.StateSpace(A - B@K - L@C, L, K, 0))
print("C(s) = ", C2)

K = [100. 2.]
C(s) =
3628 s + 4e+04
---------------------
s^2 + 80.28 s + 156.6
[16]: # Plot the gang of four for the two designs

ct.gangof4(P, C1, np.logspace(-1, 3, 100))
ct.gangof4(P, C2, np.logspace(-1, 3, 100))
[ ]:
8.2.3 Vertical takeoff and landing aircraft
This notebook demonstrates the use of the python-control package for analysis and design of a controller for a vectored
thrust aircraft model that is used as a running example through the text Feedback Systems by Astrom and Murray. This
example makes use of MATLAB compatible commands.
Additional information on this system is available at
http://www.cds.caltech.edu/~murray/wiki/index.php/Python-control/Example:_Vertical_takeoff_and_landing_
aircraft
System Description
This example uses a simplified model for a (planar) vertical takeoff and landing aircraft (PVTOL), as shown below:

The position and orientation of the center of mass of the aircraft is denoted by (𝑥, 𝑦, 𝜃), 𝑚 is the mass of the vehicle,
𝐽 the moment of inertia, 𝑔 the gravitational constant and 𝑐 the damping coefficient. The forces generated by the main
downward thruster and the maneuvering thrusters are modeled as a pair of forces 𝐹1 and 𝐹2 acting at a distance 𝑟
below the aircraft (determined by the geometry of the thrusters).
Letting 𝑧 = (𝑥, 𝑦, 𝜃, 𝑥,
˙ 𝑦, ˙ the equations can be written in state space form as:
˙ 𝜃),
⎡ ⎤ ⎡ ⎤
𝑧4 0
⎢
⎢ 𝑧5 ⎥ ⎢
⎥ ⎢ 0 ⎥
⎥
𝑑𝑧 ⎢ 𝑧6
⎥ ⎢ 0 ⎥
=⎢ ⎢ 𝑐
⎥ +⎢1
⎢ 1
⎥
𝑑𝑡 ⎢ − 𝑧
𝑚 4 ⎥
⎥
𝑚 cos 𝜃𝐹1 + 𝑚 sin 𝜃𝐹2⎥
⎥
⎣−𝑔 − 𝑐 𝑧5 ⎦ ⎣ 1 sin 𝜃𝐹1 + 1 cos 𝜃𝐹2 ⎦
⎢
𝑚 𝑚 𝑚
𝑟
0 𝐽 𝐹1
LQR state feedback controller
This section demonstrates the design of an LQR state feedback controller for the vectored thrust aircraft example.
This example is pulled from Chapter 6 (Linear Systems, Example 6.4) and Chapter 7 (State Feedback, Example 7.9)
of Astrom and Murray. The python code listed here are contained the the file pvtol-lqr.py.
To execute this example, we first import the libraries for SciPy, MATLAB plotting and the python-control package:
[1]: from numpy import * # Grab all of the NumPy functions

from matplotlib.pyplot import * # Grab MATLAB plotting functions
from control.matlab import * # MATLAB-like functions
%matplotlib inline
The parameters for the system are given by
[2]: m = 4 # mass of aircraft

J = 0.0475 # inertia around pitch axis
r = 0.25 # distance to center of force
g = 9.8 # gravitational constant
c = 0.05 # damping factor (estimated)
𝑑𝑧
Choosing equilibrium inputs to be 𝑢𝑒 = (0, 𝑚𝑔), the dynamics of the system 𝑑𝑡 , and their linearization 𝐴 about

equilibrium point 𝑧𝑒 = (0, 0, 0, 0, 0, 0) are given by

⎡ ⎤ ⎡ ⎤
𝑧4 0 0 0 1 0 0
⎢
⎢ 𝑧5 ⎥
⎥
⎢0 0
⎢ 0 0 1 0⎥
⎥
𝑑𝑧 ⎢ 𝑧 6
⎥ ⎢0 0 0 0 0 1⎥
=⎢ ⎢ 𝑐
⎥ 𝐴=⎢ ⎥
𝑑𝑡 ⎢ −𝑔 sin 𝑧3 − 𝑧
𝑚 4 ⎥
⎥ ⎢0 0 −𝑔 −𝑐/𝑚 0 0⎥
⎣𝑔(cos 𝑧3 − 1) − 𝑐 𝑧5 ⎦
⎢ ⎥
𝑚
⎣0 0 0 0 −𝑐/𝑚 0⎦
0 0 0 0 0 0 0
[3]: # State space dynamics

xe = [0, 0, 0, 0, 0, 0] # equilibrium point of interest
ue = [0, m*g] # (note these are lists, not matrices)
[4]: # Dynamics matrix (use matrix type so that * works for multiplication)
# Note that we write A and B here in full generality in case we want
# to test different xe and ue.
A = matrix(
[[ 0, 0, 0, 1, 0, 0],
[ 0, 0, 0, 0, 1, 0],
[ 0, 0, 0, 0, 0, 1],
[ 0, 0, (-ue[0]*sin(xe[2]) - ue[1]*cos(xe[2]))/m, -c/m, 0, 0],
[ 0, 0, (ue[0]*cos(xe[2]) - ue[1]*sin(xe[2]))/m, 0, -c/m, 0],
[ 0, 0, 0, 0, 0, 0 ]])
# Input matrix
B = matrix(
[[0, 0], [0, 0], [0, 0],
[cos(xe[2])/m, -sin(xe[2])/m],
[sin(xe[2])/m, cos(xe[2])/m],
[r/J, 0]])
# Output matrix
C = matrix([[1, 0, 0, 0, 0, 0], [0, 1, 0, 0, 0, 0]])
D = matrix([[0, 0], [0, 0]])
To compute a linear quadratic regulator for the system, we write the cost function as
∫︁ ∞
𝐽= (𝜉 𝑇 𝑄𝜉 𝜉 + 𝑣 𝑇 𝑄𝑣 𝑣)𝑑𝑡,
0
where 𝜉 = 𝑧 − 𝑧𝑒 and 𝑣 = 𝑢 − 𝑢𝑒 represent the local coordinates around the desired equilibrium point (𝑧𝑒 , 𝑢𝑒 ). We
begin with diagonal matrices for the state and input costs:
[5]: Qx1 = diag([1, 1, 1, 1, 1, 1])

Qu1a = diag([1, 1])
(K, X, E) = lqr(A, B, Qx1, Qu1a); K1a = matrix(K)
This gives a control law of the form 𝑣 = −𝐾𝜉, which can then be used to derive the control law in terms of the original
variables:
𝑢 = 𝑣 + 𝑢𝑒 = −𝐾(𝑧 − 𝑧𝑑 ) + 𝑢𝑑 .
𝑤ℎ𝑒𝑟𝑒 : 𝑚𝑎𝑡ℎ : ‘𝑢𝑒 = (0, 𝑚𝑔)‘𝑎𝑛𝑑 : 𝑚𝑎𝑡ℎ : ‘𝑧𝑑 = (𝑥𝑑 , 𝑦𝑑 , 0, 0, 0, 0)‘
The way we setup the dynamics above, 𝐴 is already hardcoding 𝑢𝑑 , so we don’t need to include it as an external input.
So we just need to cascade the −𝐾(𝑧 − 𝑧𝑑 ) controller with the PVTOL aircraft’s dynamics to control it. For didactic
purposes, we will cheat in two small ways:

• First, we will only interface our controller with the linearized dynamics. Using the nonlinear dynamics would
require the NonlinearIOSystem functionalities, which we leave to another notebook to introduce.
2. Second, as written, our controller requires full state feedback (𝐾 multiplies full state vectors 𝑧), which we do
not have access to because our system, as written above, only returns 𝑥 and 𝑦 (because of 𝐶 matrix). Hence, we
would need a state observer, such as a Kalman Filter, to track the state variables. Instead, we assume that we
have access to the full state.
The following code implements the closed loop system:
[6]: # Our input to the system will only be (x_d, y_d), so we need to
# multiply it by this matrix to turn it into z_d.
Xd = matrix([[1,0,0,0,0,0],
[0,1,0,0,0,0]]).T
# Closed loop dynamics

H = ss(A-B*K,B*K*Xd,C,D)
# Step response for the first input

x,t = step(H,input=0,output=0,T=linspace(0,10,100))
# Step response for the second input
y,t = step(H,input=1,output=1,T=linspace(0,10,100))
[7]: plot(t,x,'-',t,y,'--')
plot([0, 10], [1, 1], 'k-')
ylabel('Position')
xlabel('Time (s)')
title('Step Response for Inputs')
legend(('Yx', 'Yy'), loc='lower right')
show()
The plot above shows the 𝑥 and 𝑦 positions of the aircraft when it is commanded to move 1 m in each direction. The
following shows the 𝑥 motion for control weights 𝜌 = 1, 102 , 104 . A higher weight of the input term in the cost
function causes a more sluggish response. It is created using the code:
[8]: # Look at different input weightings

Qu1a = diag([1, 1])
K1a, X, E = lqr(A, B, Qx1, Qu1a)


H1ax = H = ss(A-B*K1a,B*K1a*Xd,C,D)
Qu1b = (40**2)*diag([1, 1])

K1b, X, E = lqr(A, B, Qx1, Qu1b)
H1bx = H = ss(A-B*K1b,B*K1b*Xd,C,D)
Qu1c = (200**2)*diag([1, 1])

K1c, X, E = lqr(A, B, Qx1, Qu1c)
H1cx = ss(A-B*K1c,B*K1c*Xd,C,D)
[Y1, T1] = step(H1ax, T=linspace(0,10,100), input=0,output=0)

[Y2, T2] = step(H1bx, T=linspace(0,10,100), input=0,output=0)
[Y3, T3] = step(H1cx, T=linspace(0,10,100), input=0,output=0)
[9]: plot(T1, Y1.T, 'b-', T2, Y2.T, 'r-', T3, Y3.T, 'g-')
plot([0 ,10], [1, 1], 'k-')
title('Step Response for Inputs')
ylabel('Position')
xlabel('Time (s)')
legend(('Y1','Y2','Y3'),loc='lower right')
axis([0, 10, -0.1, 1.4])
show()
Lateral control using inner/outer loop design
This section demonstrates the design of loop shaping controller for the vectored thrust aircraft example. This example
is pulled from Chapter 11 (Frequency Domain Design) of Astrom and Murray.
To design a controller for the lateral dynamics of the vectored thrust aircraft, we make use of a “inner/outer” loop
design methodology. We begin by representing the dynamics using the block diagram

where
The controller is constructed by splitting the process dynamics and controller into two components: an inner loop
consisting of the roll dynamics 𝑃𝑖 and control 𝐶𝑖 and an outer loop consisting of the lateral position dynamics 𝑃𝑜 and
controller 𝐶𝑜 .
The closed
inner loop dynamics 𝐻𝑖 control the roll angle of the aircraft using the vectored thrust while the outer loop controller
𝐶𝑜 commands the roll angle to regulate the lateral position.
The following code imports the libraries that are required and defines the dynamics:
[10]: from matplotlib.pyplot import * # Grab MATLAB plotting functions

from control.matlab import * # MATLAB-like functions
[12]: # System parameters

m = 4 # mass of aircraft
J = 0.0475 # inertia around pitch axis
r = 0.25 # distance to center of force
g = 9.8 # gravitational constant
c = 0.05 # damping factor (estimated)
[13]: # Transfer functions for dynamics

Pi = tf([r], [J, 0, 0]) # inner loop (roll)
Po = tf([1], [m, c, 0]) # outer loop (position)
For the inner loop, use a lead compensator
[14]: k = 200
a = 2
b = 50
Ci = k*tf([1, a], [1, b]) # lead compensator
Li = Pi*Ci
The closed loop dynamics of the inner loop, 𝐻𝑖 , are given by

[15]: Hi = parallel(feedback(Ci, Pi), -m*g*feedback(Ci*Pi, 1))
Finally, we design the lateral compensator using another lead compenstor
[16]: # Now design the lateral control system

a = 0.02
b = 5
K = 2
Co = -K*tf([1, 0.3], [1, 10]) # another lead compensator
Lo = -m*g*Po*Co
The performance of the system can be characterized using the sensitivity function and the complementary sensitivity
function:
[17]: L = Co*Hi*Po
S = feedback(1, L)
T = feedback(L, 1)
[18]: t, y = step(T, T=linspace(0,10,100))

plot(y, t)
title("Step Response")
grid()
xlabel("time (s)")
ylabel("y(t)")
show()
The frequency response and Nyquist plot for the loop transfer function are computed using the commands
[19]: bode(L)
show()

[20]: nyquist(L, (0.0001, 1000))

show()
[21]: gangof4(Hi*Po, Co)

• genindex
Development
You can check out the latest version of the source code with the command:
git clone https://github.com/python-control/python-control.git
You can run a set of unit tests to make sure that everything is working correctly. After installation, run:
python setup.py test
Your contributions are welcome! Simply fork the GitHub repository and send a pull request.
Links
• Issue tracker: https://github.com/python-control/python-control/issues

• Mailing list: http://sourceforge.net/p/python-control/mailman/


Python Module Index
c
control, 11
control.flatsys, 113
control.iosys, 129
control.matlab, 81
211
212 Python Module Index

Index
Symbols canonical_form() (in module control), 48

__init__() (control.FrequencyResponseData care() (in module control), 34
method), 64 care() (in module control.matlab), 110
__init__() (control.StateSpace method), 61 connect() (in module control), 15
__init__() (control.TransferFunction method), 58 connect() (in module control.matlab), 91
__init__() (control.flatsys.BasisFamily method), 117 control (module), 11
__init__() (control.flatsys.FlatSystem method), 117 control.flatsys (module), 113
__init__() (control.flatsys.LinearFlatSystem control.iosys (module), 129
method), 121 control.matlab (module), 81
__init__() (control.flatsys.PolyFamily method), 126 copy() (control.flatsys.FlatSystem method), 119
__init__() (control.flatsys.SystemTrajectory copy() (control.flatsys.LinearFlatSystem method), 122
method), 126 copy() (control.iosys.InputOutputSystem method), 68
__init__() (control.iosys.InputOutputSystem copy() (control.iosys.InterconnectedSystem method),
method), 67 79
__init__() (control.iosys.InterconnectedSystem copy() (control.iosys.LinearIOSystem method), 71
method), 77 copy() (control.iosys.NonlinearIOSystem method), 76
__init__() (control.iosys.LinearIOSystem method), ctrb() (in module control), 35
69 ctrb() (in module control.matlab), 104
__init__() (control.iosys.NonlinearIOSystem
method), 74
D
damp() (control.flatsys.LinearFlatSystem method), 122
A damp() (control.FrequencyResponseData method), 65
acker() (in module control), 36 damp() (control.iosys.LinearIOSystem method), 71
append() (control.flatsys.LinearFlatSystem method), damp() (control.StateSpace method), 61
122 damp() (control.TransferFunction method), 58
append() (control.iosys.LinearIOSystem method), 71 damp() (in module control), 49
append() (control.StateSpace method), 61 damp() (in module control.matlab), 93
append() (in module control), 15 dare() (in module control), 34
append() (in module control.matlab), 91 dare() (in module control.matlab), 110
augw() (in module control), 48 db2mag() (in module control), 49
db2mag() (in module control.matlab), 85
B dcgain() (control.flatsys.LinearFlatSystem method),
balred() (in module control), 41 122
balred() (in module control.matlab), 106 dcgain() (control.FrequencyResponseData method),
BasisFamily (class in control.flatsys), 117 65
bode() (in module control.matlab), 97 dcgain() (control.iosys.LinearIOSystem method), 71
bode_plot() (in module control), 19 dcgain() (control.StateSpace method), 61
dcgain() (control.TransferFunction method), 58
C dcgain() (in module control), 28
c2d() (in module control.matlab), 86 dcgain() (in module control.matlab), 92
213
dlyap() (in module control), 35 find_output() (control.flatsys.FlatSystem method),

dlyap() (in module control.matlab), 110 119
drss() (in module control), 14 find_output() (control.flatsys.LinearFlatSystem
drss() (in module control.matlab), 85 method), 123
dt (control.iosys.InputOutputSystem attribute), 66 find_output() (control.iosys.InputOutputSystem
method), 68
E find_output() (control.iosys.InterconnectedSystem
era() (in module control), 42 method), 79
era() (in module control.matlab), 108 find_output() (control.iosys.LinearIOSystem
eval() (control.flatsys.SystemTrajectory method), 127 method), 72
eval() (control.FrequencyResponseData method), 65 find_output() (control.iosys.NonlinearIOSystem
eval_deriv() (control.flatsys.PolyFamily method), method), 76
126 find_state() (control.flatsys.FlatSystem method),
evalfr() (control.flatsys.LinearFlatSystem method), 119
122 find_state() (control.flatsys.LinearFlatSystem
evalfr() (control.FrequencyResponseData method), method), 123
65 find_state() (control.iosys.InputOutputSystem
evalfr() (control.iosys.LinearIOSystem method), 71 method), 68
evalfr() (control.StateSpace method), 62 find_state() (control.iosys.InterconnectedSystem
evalfr() (control.TransferFunction method), 59 method), 79
evalfr() (in module control), 28 find_state() (control.iosys.LinearIOSystem
evalfr() (in module control.matlab), 100 method), 72
find_state() (control.iosys.NonlinearIOSystem
F method), 76
feedback() (control.flatsys.FlatSystem method), 119 FlatSystem (class in control.flatsys), 117
feedback() (control.flatsys.LinearFlatSystem forced_response() (in module control), 22
method), 122 forward() (control.flatsys.FlatSystem method), 119
feedback() (control.FrequencyResponseData forward() (control.flatsys.LinearFlatSystem method),
method), 65 123
feedback() (control.iosys.InputOutputSystem frd() (in module control), 13
method), 68 frd() (in module control.matlab), 84
feedback() (control.iosys.InterconnectedSystem freqresp() (control.flatsys.LinearFlatSystem
method), 79 method), 123
feedback() (control.iosys.LinearIOSystem method), freqresp() (control.FrequencyResponseData
71 method), 65
feedback() (control.iosys.NonlinearIOSystem freqresp() (control.iosys.LinearIOSystem method),
method), 76 72
feedback() (control.StateSpace method), 62 freqresp() (control.StateSpace method), 62
feedback() (control.TransferFunction method), 59 freqresp() (control.TransferFunction method), 59
feedback() (in module control), 16 freqresp() (in module control), 28
feedback() (in module control.matlab), 90 freqresp() (in module control.matlab), 99
find_eqpt() (in module control.iosys), 44 FrequencyResponseData (class in control), 64
find_input() (control.flatsys.FlatSystem method),
119 G
find_input() (control.flatsys.LinearFlatSystem gangof4() (in module control.matlab), 111
method), 123 gangof4_plot() (in module control), 21
find_input() (control.iosys.InputOutputSystem gram() (in module control), 36
method), 68 gram() (in module control.matlab), 105
find_input() (control.iosys.InterconnectedSystem
method), 79 H
find_input() (control.iosys.LinearIOSystem h2syn() (in module control), 37
method), 71 hinfsyn() (in module control), 37
find_input() (control.iosys.NonlinearIOSystem horner() (control.flatsys.LinearFlatSystem method),
method), 76 123
214 Index
horner() (control.iosys.LinearIOSystem method), 72 linearize() (control.iosys.InterconnectedSystem

horner() (control.StateSpace method), 62 method), 79
horner() (control.TransferFunction method), 59 linearize() (control.iosys.LinearIOSystem method),
hsvd() (in module control), 41 73
hsvd() (in module control.matlab), 106 linearize() (control.iosys.NonlinearIOSystem
method), 76
I linearize() (in module control.iosys), 45
impulse() (in module control.matlab), 95 lqr() (in module control), 38
impulse_response() (in module control), 23 lqr() (in module control.matlab), 103
initial() (in module control.matlab), 95 lsim() (in module control.matlab), 96
initial_response() (in module control), 24 lyap() (in module control), 34
input_output_response() (in module control), lyap() (in module control.matlab), 109
25
input_output_response() (in module con- M
trol.iosys), 45 mag2db() (in module control), 50
InputOutputSystem (class in control.iosys), 66 mag2db() (in module control.matlab), 85
InterconnectedSystem (class in control.iosys), 77 margin() (in module control), 29
isctime() (control.flatsys.LinearFlatSystem method), margin() (in module control.matlab), 99
123 markov() (in module control), 43
isctime() (control.FrequencyResponseData method), markov() (in module control.matlab), 108
65 minreal() (control.flatsys.LinearFlatSystem method),
isctime() (control.iosys.LinearIOSystem method), 72 124
isctime() (control.StateSpace method), 62 minreal() (control.iosys.LinearIOSystem method), 73
isctime() (control.TransferFunction method), 59 minreal() (control.StateSpace method), 63
isctime() (in module control), 49 minreal() (control.TransferFunction method), 59
isdtime() (control.flatsys.LinearFlatSystem method), minreal() (in module control), 40
124 minreal() (in module control.matlab), 106
isdtime() (control.FrequencyResponseData method), mixsyn() (in module control), 38
65 modred() (in module control), 42
isdtime() (control.iosys.LinearIOSystem method), 72 modred() (in module control.matlab), 107
isdtime() (control.StateSpace method), 62
isdtime() (control.TransferFunction method), 59 N
isdtime() (in module control), 50 name (control.iosys.InputOutputSystem attribute), 66
issiso() (control.flatsys.LinearFlatSystem method), negate() (in module control), 17
124 negate() (in module control.matlab), 90
issiso() (control.FrequencyResponseData method), nichols() (in module control.matlab), 98
66 nichols_plot() (in module control), 21
issiso() (control.iosys.LinearIOSystem method), 72 NonlinearIOSystem (class in control.iosys), 74
issiso() (control.StateSpace method), 62 nyquist() (in module control.matlab), 98
issiso() (control.TransferFunction method), 59 nyquist_plot() (in module control), 20
issiso() (in module control), 50
issys() (in module control), 50 O
observable_form() (in module control), 50
L obsv() (in module control), 35
lft() (control.flatsys.LinearFlatSystem method), 124 obsv() (in module control.matlab), 104
lft() (control.iosys.LinearIOSystem method), 72
lft() (control.StateSpace method), 62 P
LinearFlatSystem (class in control.flatsys), 121 pade() (in module control), 51
LinearIOSystem (class in control.iosys), 69 pade() (in module control.matlab), 109
linearize() (control.flatsys.FlatSystem method), 119 parallel() (in module control), 17
linearize() (control.flatsys.LinearFlatSystem parallel() (in module control.matlab), 89
method), 124 params (control.iosys.InputOutputSystem attribute), 66
linearize() (control.iosys.InputOutputSystem phase_crossover_frequencies() (in module
method), 68 control), 31
Index 215
phase_plot() (in module control), 26 set_inputs() (control.iosys.InterconnectedSystem

place() (in module control), 39 method), 79
place() (in module control.matlab), 102 set_inputs() (control.iosys.LinearIOSystem
point_to_point() (in module control.flatsys), 46 method), 74
pole() (control.flatsys.LinearFlatSystem method), 124 set_inputs() (control.iosys.NonlinearIOSystem
pole() (control.iosys.LinearIOSystem method), 73 method), 76
pole() (control.StateSpace method), 63 set_output_map() (con-
pole() (control.TransferFunction method), 59 trol.iosys.InterconnectedSystem method),
pole() (in module control), 31 80
pole() (in module control.matlab), 92 set_outputs() (control.flatsys.FlatSystem method),
PolyFamily (class in control.flatsys), 126 120
pzmap() (in module control), 32 set_outputs() (control.flatsys.LinearFlatSystem
pzmap() (in module control.matlab), 94 method), 125
set_outputs() (control.iosys.InputOutputSystem
R method), 68
reachable_form() (in module control), 51 set_outputs() (control.iosys.InterconnectedSystem
reset_defaults() (in module control), 8 method), 80
returnScipySignalLTI() (con- set_outputs() (control.iosys.LinearIOSystem
trol.flatsys.LinearFlatSystem method), 124 method), 74
returnScipySignalLTI() (con- set_outputs() (control.iosys.NonlinearIOSystem
trol.iosys.LinearIOSystem method), 73 method), 77
returnScipySignalLTI() (control.StateSpace set_states() (control.flatsys.FlatSystem method),
method), 63 120
returnScipySignalLTI() (con- set_states() (control.flatsys.LinearFlatSystem
trol.TransferFunction method), 59 method), 125
reverse() (control.flatsys.FlatSystem method), 120 set_states() (control.iosys.InputOutputSystem
reverse() (control.flatsys.LinearFlatSystem method), method), 69
124 set_states() (control.iosys.InterconnectedSystem
rlocus() (in module control.matlab), 101 method), 80
root_locus() (in module control), 32 set_states() (control.iosys.LinearIOSystem
rss() (in module control), 14 method), 74
rss() (in module control.matlab), 84 set_states() (control.iosys.NonlinearIOSystem
method), 77
S sisotool() (in module control), 32
sample() (control.flatsys.LinearFlatSystem method), sisotool() (in module control.matlab), 102
124 ss() (in module control), 11
sample() (control.iosys.LinearIOSystem method), 73 ss() (in module control.matlab), 83
sample() (control.StateSpace method), 63 ss2io() (in module control.iosys), 46
sample() (control.TransferFunction method), 59 ss2tf() (in module control), 52
sample_system() (in module control), 51 ss2tf() (in module control.matlab), 86
series() (in module control), 18 ssdata() (in module control), 53
series() (in module control.matlab), 88 stability_margins() (in module control), 30
set_connect_map() (con- StateSpace (class in control), 60
trol.iosys.InterconnectedSystem method), step() (in module control.matlab), 94
79 step_response() (in module control), 25
set_input_map() (con- SystemTrajectory (class in control.flatsys), 126
trol.iosys.InterconnectedSystem method),
79 T
set_inputs() (control.flatsys.FlatSystem method), tf() (in module control), 12
120 tf() (in module control.matlab), 81
set_inputs() (control.flatsys.LinearFlatSystem tf2io() (in module control.iosys), 46
method), 125 tf2ss() (in module control), 53
set_inputs() (control.iosys.InputOutputSystem tf2ss() (in module control.matlab), 87
method), 68 tfdata() (in module control), 54
216 Index
tfdata() (in module control.matlab), 88

timebase() (in module control), 54
timebaseEqual() (in module control), 54
TransferFunction (class in control), 57
U
unwrap() (in module control), 54
unwrap() (in module control.matlab), 111
use_fbs_defaults() (in module control), 8
use_matlab_defaults() (in module control), 9
use_numpy_matrix() (in module control), 9
Z
zero() (control.flatsys.LinearFlatSystem method), 126
zero() (control.iosys.LinearIOSystem method), 74
zero() (control.StateSpace method), 64
zero() (control.TransferFunction method), 60
zero() (in module control), 31
zero() (in module control.matlab), 93
Index 217

Python Control Readthedocs Io en Latest

Uploaded by

Python Control Readthedocs Io en Latest

Uploaded by

Python Control Library Documentation

May 17, 2020

4 Control system classes 57

5 MATLAB compatibility module 81

6 Differentially flat systems 113

7 Input/output systems 129

Python Module Index 211

• Linear input/output systems in state-space and frequency domain

1.1 Overview of the toolbox

1.2 Some differences from MATLAB

pip install slycot # optional

python -c "import slycot"

conda install numpy scipy matplotlib # if not yet installed

python setup.py install --user

or to install for all users (on Linux or Mac OS):

python setup.py build

1.4 Getting started

>>> import control

>>> from control.matlab import *

2.1 LTI system representation

2.1.1 State space systems

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

2.1.3 FRD (frequency response data) systems

2.1.4 Discrete time systems

2.1.5 Conversion between representations

2.2 Time series data

6 Chapter 2. Library conventions

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

U = [[u1(t1), u1(t2), u1(t3), ..., u1(tn)]

As all simulation functions return arrays, plotting is convenient:

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

2.2. Time series data 7

2.3 Package configuration parameters

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

reset_defaults() Reset configuration values to their default (initial) val-

8 Chapter 2. Library conventions

2.3. Package configuration parameters 9

10 Chapter 2. Library conventions

3.1 System creation

ss(A, B, C, D[, dt]) Create a state space system.

>>> # Create a StateSpace object from four "matrices".

>>> # Convert a TransferFunction to a StateSpace object.

12 Chapter 3. Function reference

>>> # Create a MIMO transfer function object

>>> # Convert a StateSpace to a TransferFunction object.

3.1. System creation 13

This function can be called in different ways:

control.rss(states=1, outputs=1, inputs=1)

control.drss(states=1, outputs=1, inputs=1)

14 Chapter 3. Function reference

• outputs (integer) – Number of system outputs

3.2 System interconnections

control.append(sys1, sys2, ..., sysn)

control.connect(sys, Q, inputv, outputv)

3.2. System interconnections 15

control.feedback(sys1, sys2=1, sign=-1)

16 Chapter 3. Function reference

>>> sys2 = negate(sys1) # Same as sys2 = -sys1.

3.2. System interconnections 17

>>> sys3 = parallel(sys1, sys2) # Same as sys3 = sys1 + sys2

>>> sys5 = parallel(sys1, sys2, sys3, sys4) # More systems

>>> sys3 = series(sys1, sys2) # Same as sys3 = sys2 * sys1

>>> sys5 = series(sys1, sys2, sys3, sys4) # More systems

18 Chapter 3. Function reference

3.3 Frequency domain plotting

bode_plot(syslist[, omega, plot, . . . ]) Bode plot for a system

control.bode_plot(syslist, omega=None, plot=True, omega_limits=None, omega_num=None, mar-

3.3. Frequency domain plotting 19

control.nyquist_plot(syslist, omega=None, plot=True, label_freq=0, arrowhead_length=0.1, arrow-

20 Chapter 3. Function reference

control.gangof4_plot(P, C, omega=None, **kwargs)

control.nichols_plot(sys_list, omega=None, grid=None)

3.4 Time domain simulation

forced_response(sys[, T, U, X0, transpose, . . . ]) Simulate the output of a linear system.

series(sys1, sysn) Return the series connection (sysn . . .