Function Reference

The Python Control Systems Library (python-control) provides common functions for analyzing and designing feedback control systems.

The initial goal for the package is to implement all of the functionality required to work through the examples in the textbook Feedback Systems by Astrom and Murray. In addition to standard techniques available for linear control systems, support for nonlinear systems (including trajectory generation, gain scheduling, phase plane diagrams, and describing functions) is included. A MATLAB Compatibility Module is available that provides many of the common functions corresponding to commands available in the MATLAB Control Systems Toolbox.

Documentation is available in two forms: docstrings provided with the code, and the python-control User Guide, available from the python-control homepage.

The docstring examples assume the following import commands:

>>> import numpy as np
>>> import control as ct

Available subpackages

The main control package includes the most common functions used in analysis, design, and simulation of feedback control systems. Several additional subpackages and modules are available that provide more specialized functionality:

• flatsys: Differentially flat systems

• matlab: MATLAB compatibility module

• optimal: Optimization-based control

• phaseplot: 2D phase plane diagrams

These subpackages and modules are described in more detail in the subpackage and module docstrings and in the User Guide.

System Creation

Functions that create input/output systems from a description of the system properties:

ss(A, B, C, D[, dt])	Create a state space system.
tf(num, den[, dt])	Create a transfer function system.
frd(frdata, omega[, dt])	Construct a frequency response data (FRD) model.
nlsys(updfcn[, outfcn])	Create a nonlinear input/output system.
zpk(zeros, poles, gain[, dt])	Create a transfer function from zeros, poles, gain.
pade(T[, n, numdeg])	Create a linear system that approximates a delay.
rss([states, outputs, inputs, strictly_proper])	Create a stable random state space object.
drss([states, outputs, inputs, strictly_proper])	Create a stable, discrete-time, random state space system.

Functions that transform systems from one form to another:

canonical_form(xsys[, form])	Convert a system into canonical form.
modal_form(xsys[, condmax, sort])	Convert a system into modal canonical form.
observable_form(xsys)	Convert a system into observable canonical form.
reachable_form(xsys)	Convert a system into reachable canonical form.
sample_system(sysc, Ts[, method, alpha, ...])	Convert a continuous-time system to discrete time by sampling.
similarity_transform(xsys, T[, timescale, ...])	Similarity transformation, with optional time rescaling.
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.

System Interconnections

series(sys1, sys2[, ..., sysn])	Series connection of I/O systems.
parallel(sys1, sys2[, ..., sysn])	Parallel connection of I/O systems.
negate(sys, **kwargs)	Return the negative of a system.
feedback(sys1[, sys2, sign])	Feedback interconnection between two I/O systems.
interconnect(syslist[, connections, ...])	Interconnect a set of input/output systems.
append(sys1, sys2[, ..., sysn])	Group LTI models by appending their inputs and outputs.
combine_tf(tf_array, **kwargs)	Combine array of transfer functions into MIMO transfer function.
split_tf(transfer_function)	Split MIMO transfer function into SISO transfer functions.
summing_junction([inputs, output, ...])	Create a summing junction as an input/output system.
connection_table(sys[, show_names, column_width])	Print table of connections inside interconnected system.
combine_tf(tf_array, **kwargs)	Combine array of transfer functions into MIMO transfer function.
split_tf(transfer_function)	Split MIMO transfer function into SISO transfer functions.

Time Response

forced_response(sysdata[, timepts, inputs, ...])	Compute the output of a linear system given the input.
impulse_response(sysdata[, timepts, ...])	Compute the impulse response for a linear system.
initial_response(sysdata[, timepts, ...])	Compute the initial condition response for a linear system.
input_output_response(sys[, timepts, ...])	Compute the output response of a system to a given input.
step_response(sysdata[, timepts, ...])	Compute the step response for a linear system.
time_response_plot(data, *fmt[, ax, ...])	Plot the time response of an input/output system.
combine_time_responses(response_list[, ...])	Combine individual time responses into multi-trace response.

Phase plane plots

Generate 2D phase portraits.

This module contains functions for generating 2D phase plots. The base function for creating phase plane portraits is phase_plane_plot, which generates a phase plane portrait for a 2 state I/O system (with no inputs). Utility functions are available to customize the individual elements of a phase plane portrait.

The docstring examples assume the following import commands:

>>> import numpy as np
>>> import control as ct
>>> import control.phaseplot as pp

phase_plane_plot(sys[, pointdata, timedata, ...])	Plot phase plane diagram.
phaseplot.boxgrid(xvals, yvals)	Generate list of points along the edge of box.
phaseplot.circlegrid(centers, radius, num)	Generate list of points around a circle.
phaseplot.equilpoints(sys, pointdata[, ...])	Plot equilibrium points in the phase plane.
phaseplot.meshgrid(xvals, yvals)	Generate list of points forming a mesh.
phaseplot.separatrices(sys, pointdata[, ...])	Plot separatrices in the phase plane.
phaseplot.streamlines(sys, pointdata[, ...])	Plot stream lines in the phase plane.
phaseplot.vectorfield(sys, pointdata[, ...])	Plot a vector field in the phase plane.
phaseplot.streamplot(sys, pointdata[, ...])	Plot streamlines in the phase plane.

Frequency Response

bode_plot(data[, omega, ax, omega_limits, ...])	Bode plot for a system.
describing_function_plot(data, *args, **kwargs)	Nyquist plot with describing function for a nonlinear system.
describing_function_response(H, F, A[, ...])	Compute the describing function response of a system.
frequency_response(sysdata[, omega, ...])	Frequency response of an LTI system.
nyquist_response(sysdata[, omega, ...])	Nyquist response for a system.
nyquist_plot(data[, omega, plot, ...])	Nyquist plot for a system.
gangof4_response(P, C[, omega, ...])	Compute response of "Gang of 4" transfer functions.
gangof4_plot(response)     gangof4_plot(P, ...)	Plot response of "Gang of 4" transfer functions.
nichols_plot(data[, omega, grid, title, ax, ...])	Nichols plot for a system.
nichols_grid([cl_mags, cl_phases, ...])	Plot Nichols chart grid.

Control System Analysis

Time domain analysis:

damp(sys[, doprint])	Compute system's natural frequencies, damping ratios, and poles.
step_info(sysdata[, timepts, timepts_num, ...])	Step response characteristics (rise time, settling time, etc).

Frequency domain analysis:

bandwidth(sys[, dbdrop])	Find first frequency where gain drops by 3 dB.
dcgain(sys)	Return the zero-frequency (or DC) gain of the given system.
linfnorm(sys[, tol])	L-infinity norm of a linear system.
margin(sys)     margin(mag, phase, omega)	Gain and phase margins and associated crossover frequencies.
stability_margins(sysdata[, returnall, ...])	Stability margins and associated crossover frequencies.
system_norm(system[, p, tol, print_warning, ...])	Computes the input/output norm of system.
phase_crossover_frequencies(sys)	Compute Nyquist plot real-axis crossover frequencies and gains.
singular_values_plot(data[, omega, plot, ...])	Plot the singular values for a system.
singular_values_response(sysdata[, omega, ...])	Singular value response for a system.
sisotool(sys[, initial_gain, xlim_rlocus, ...])	Collection of plots inspired by MATLAB's sisotool.

Pole/zero-based analysis:

poles(sys)	Compute system poles.
zeros(sys)	Compute system zeros.
pole_zero_map(sysdata)	Compute the pole/zero map for an LTI system.
pole_zero_plot(data[, plot, grid, title, ...])	Plot a pole/zero map for a linear system.
pole_zero_subplots(nrows, ncols[, grid, dt, ...])	Create axes for pole/zero plot.
root_locus_map(sysdata[, gains])	Compute the root locus map for an LTI system.
root_locus_plot(sysdata[, gains, grid, plot])	Root locus plot.

Passive systems analysis:

get_input_ff_index(sys)	Input feedforward passivity (IFP) index for a system.
get_output_fb_index(sys)	Return the output feedback passivity (OFP) index for the system.
ispassive(sys[, ofp_index, ifp_index])	Indicate if a linear time invariant (LTI) system is passive.
solve_passivity_LMI(sys[, rho, nu])	Compute passivity indices and/or solves feasibility via a LMI.

Control System Synthesis

State space synthesis:

create_statefbk_iosystem(sys, gain[, ...])	Create an I/O system using a (full) state feedback controller.
dlqr(A, B, Q, R[, N])	Discrete-time linear quadratic regulator design.
lqr(A, B, Q, R[, N])	Linear quadratic regulator design.
place(A, B, p)	Place closed loop eigenvalues.
place_acker(A, B, poles)	Pole placement using Ackermann method.
place_varga(A, B, p[, dtime, alpha])	Place closed loop eigenvalues using Varga method.

Frequency domain synthesis:

h2syn(P, nmeas, ncon)	H2 control synthesis for plant P.
hinfsyn(P, nmeas, ncon)	H-infinity control synthesis for plant P.
mixsyn(g[, w1, w2, w3])	Mixed-sensitivity H-infinity synthesis.
rootlocus_pid_designer(plant[, gain, sign, ...])	Manual PID controller design based on root locus using Sisotool.

System ID and Model Reduction

minimal_realization(sys[, tol, verbose])	Eliminate uncontrollable or unobservable states.
balanced_reduction(sys, orders[, method, alpha])	Balanced reduced order model of system of a given order.
hankel_singular_values(sys)	Calculate the Hankel singular values.
model_reduction(sys[, elim_states, method, ...])	Model reduction by input, output, or state elimination.
eigensys_realization(YY, r)	Calculate ERA model based on impulse-response data.
markov(Y, U, [, m])	Calculate Markov parameters [D CB CAB ...] from data.

Nonlinear System Support

find_operating_point(sys[, initial_state, ...])	Find an operating point for an input/output system.
linearize(sys, xeq[, ueq, t, params])	Linearize an input/output system at a given state and input.

Describing functions

describing_function(F, A[, num_points, ...])	Numerically compute describing function of a nonlinear function.
friction_backlash_nonlinearity(b)	Backlash nonlinearity for describing function analysis.
relay_hysteresis_nonlinearity(b, c)	Relay w/ hysteresis for describing function analysis.
saturation_nonlinearity([ub, lb])	Saturation nonlinearity for describing function analysis.

Differentially flat systems

Flat systems subpackage.

This subpackage contains a set of classes and functions 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 SystemTrajectory.eval member function. Alternatively, the solve_flat_optimal function can be used to solve an optimal control problem with trajectory and final costs or constraints.

The docstring examples assume that the following import commands:

>>> import numpy as np
>>> import control as ct
>>> import control.flatsys as fs

flatsys.flatsys(forward, reverse[, updfcn, ...)	Create a differentially flat I/O system.
flatsys.point_to_point(sys, timepts[, ...])	Compute trajectory between an initial and final conditions.
flatsys.solve_flat_optimal(sys, timepts[, ...])	Compute trajectory between an initial and final conditions.

Optimal control

Optimization-based control module.

This module provides support for optimization-based controllers for nonlinear systems with state and input constraints. An optimal control problem can be solved using the solve_optimal_trajectory function or set up using the OptimalControlProblem class and then solved using the compute_trajectory method. Utility functions are available to define common cost functions and input/state constraints. Optimal estimation problems can be solved using the solve_optimal_estimate function or by using the OptimalEstimationProblem class and the compute_estimate method..

The docstring examples assume the following import commands:

>>> import numpy as np
>>> import control as ct
>>> import control.optimal as opt

optimal.create_mpc_iosystem(sys, timepts[, ...])	Create a model predictive I/O control system.
optimal.disturbance_range_constraint(sys, lb, ub)	Create constraint for bounded disturbances.
optimal.gaussian_likelihood_cost(sys, Rv[, Rw])	Create cost function for Gaussian likelihoods.
optimal.input_poly_constraint(sys, A, b)	Create input constraint from polytope.
optimal.input_range_constraint(sys, lb, ub)	Create input constraint from polytope.
optimal.output_poly_constraint(sys, A, b)	Create output constraint from polytope.
optimal.output_range_constraint(sys, lb, ub)	Create output constraint from range.
optimal.quadratic_cost(sys, Q, R[, x0, u0])	Create quadratic cost function.
optimal.solve_optimal_trajectory(sys, timepts)	Compute the solution to an optimal control problem.
optimal.solve_optimal_estimate(sys, timepts)	Compute the solution to a finite horizon estimation problem.
optimal.state_poly_constraint(sys, A, b)	Create state constraint from polytope.
optimal.state_range_constraint(sys, lb, ub)	Create state constraint from range.

Stochastic System Support

correlation(T, X[, Y, squeeze])	Compute the correlation of time signals.
create_estimator_iosystem(sys, QN, RN[, P0, ...])	Create an I/O system implementing a linear quadratic estimator.
dlqe(A, G, C, QN, RN, [, N])	Discrete-time linear quadratic estimator (Kalman filter).
lqe(A, G, C, QN, RN, [, NN])	Continuous-time linear quadratic estimator (Kalman filter).
white_noise(T, Q[, dt])	Generate a white noise signal with specified intensity.

Matrix Computations

care(A, B, Q[, R, S, E, stabilizing, ...])	Solves the continuous-time algebraic Riccati equation.
ctrb(A, B[, t])	Controllability matrix.
dare(A, B, Q, R[, S, E, stabilizing, ...])	Solves the discrete-time algebraic Riccati equation.
dlyap(A, Q[, C, E, method])	Solves the discrete-time Lyapunov equation.
lyap(A, Q[, C, E, method])	Solves the continuous-time Lyapunov equation.
obsv(A, C[, t])	Observability matrix.
gram(sys, type)	Gramian (controllability or observability).

Utility Functions

augw(g[, w1, w2, w3])	Augment plant for mixed sensitivity problem.
bdschur(a[, condmax, sort])	Block-diagonal Schur decomposition.
db2mag(db)	Convert a gain in decibels (dB) to a magnitude.
isctime([sys, dt, strict])	Check to see if a system is a continuous-time system.
isdtime([sys, strict, dt])	Check to see if a system is a discrete-time system.
iosys_repr(sys[, format])	Return representation of an I/O system.
issiso(sys[, strict])	Check to see if a system is single input, single output.
mag2db(mag)	Convert a magnitude to decibels (dB).
reset_defaults()	Reset configuration values to their default (initial) values.
reset_rcParams()	Reset rcParams to default values for control plots.
set_defaults(module, **keywords)	Set default values of parameters for a module.
ssdata(sys)	Return state space data objects for a system.
timebase(sys[, strict])	Return the timebase for a system.
unwrap(angle[, period])	Unwrap a phase angle to give a continuous curve.
use_fbs_defaults()	Use Feedback Systems (FBS) compatible settings.
use_legacy_defaults(version)	Sets the defaults to whatever they were in a given release.
use_matlab_defaults()	Use MATLAB compatible configuration settings.