385 lines
18 KiB
Python
385 lines
18 KiB
Python
# -*- coding: utf-8 -*-
|
|
"""
|
|
The :mod:`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).
|
|
"""
|
|
|
|
"""Copyright (c) 2009 by California Institute of Technology
|
|
All rights reserved.
|
|
|
|
Copyright (c) 2011 by Eike Welk
|
|
|
|
|
|
Redistribution and use in source and binary forms, with or without
|
|
modification, are permitted provided that the following conditions
|
|
are met:
|
|
|
|
1. Redistributions of source code must retain the above copyright
|
|
notice, this list of conditions and the following disclaimer.
|
|
|
|
2. Redistributions in binary form must reproduce the above copyright
|
|
notice, this list of conditions and the following disclaimer in the
|
|
documentation and/or other materials provided with the distribution.
|
|
|
|
3. Neither the name of the California Institute of Technology nor
|
|
the names of its contributors may be used to endorse or promote
|
|
products derived from this software without specific prior
|
|
written permission.
|
|
|
|
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
|
|
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
|
|
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
|
|
FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL CALTECH
|
|
OR THE CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
|
|
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
|
|
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
|
|
USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
|
|
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
|
|
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
|
|
OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
SUCH DAMAGE.
|
|
|
|
Author: Richard M. Murray
|
|
Date: 29 May 09
|
|
Revised: Kevin K. Chen, Dec 10
|
|
|
|
$Id$
|
|
|
|
"""
|
|
|
|
# Import MATLAB-like functions that are defined in other packages
|
|
from scipy.signal import zpk2ss, ss2zpk, tf2zpk, zpk2tf
|
|
from numpy import linspace, logspace
|
|
|
|
# If configuration is not yet set, import and use MATLAB defaults
|
|
import sys
|
|
if not ('.config' in sys.modules):
|
|
from .. import config
|
|
config.use_matlab_defaults()
|
|
|
|
# Control system library
|
|
from ..statesp import *
|
|
from ..xferfcn import *
|
|
from ..lti import *
|
|
from ..frdata import *
|
|
from ..dtime import *
|
|
from ..exception import ControlArgument
|
|
|
|
# Import MATLAB-like functions that can be used as-is
|
|
from ..ctrlutil import *
|
|
from ..freqplot import nyquist, gangof4
|
|
from ..nichols import nichols
|
|
from ..bdalg import *
|
|
from ..pzmap import *
|
|
from ..statefbk import *
|
|
from ..delay import *
|
|
from ..modelsimp import *
|
|
from ..mateqn import *
|
|
from ..margins import margin
|
|
from ..rlocus import rlocus
|
|
from ..dtime import c2d
|
|
from ..sisotool import sisotool
|
|
|
|
# Import functions specific to Matlab compatibility package
|
|
from .timeresp import *
|
|
from .wrappers import *
|
|
|
|
# Set up defaults corresponding to MATLAB conventions
|
|
from ..config import *
|
|
use_matlab_defaults()
|
|
|
|
r"""
|
|
The following tables give an overview of the module ``control.matlab``.
|
|
They also show the implementation progress and the planned features of the
|
|
module.
|
|
|
|
The symbols in the first column show the current state of a feature:
|
|
|
|
* ``*`` : The feature is currently implemented.
|
|
* ``-`` : The feature is not planned for implementation.
|
|
* ``s`` : A similar feature from another library (Scipy) is imported into
|
|
the module, until the feature is implemented here.
|
|
|
|
|
|
Creating linear models
|
|
----------------------------------------------------------------------------
|
|
|
|
== ========================== ============================================
|
|
\* :func:`tf` create transfer function (TF) models
|
|
\ zpk create zero/pole/gain (ZPK) models.
|
|
\* :func:`ss` create state-space (SS) models
|
|
\ dss create descriptor state-space models
|
|
\ delayss create state-space models with delayed terms
|
|
\* :func:`frd` create frequency response data (FRD) models
|
|
\ lti/exp create pure continuous-time delays (TF and
|
|
ZPK only)
|
|
\ filt specify digital filters
|
|
\- lti/set set/modify properties of LTI models
|
|
\- setdelaymodel specify internal delay model (state space
|
|
only)
|
|
\* :func:`rss` create a random continuous state space model
|
|
\* :func:`drss` create a random discrete state space model
|
|
== ========================== ============================================
|
|
|
|
|
|
Data extraction
|
|
----------------------------------------------------------------------------
|
|
|
|
== ========================== ============================================
|
|
\* :func:`tfdata` extract numerators and denominators
|
|
\ lti/zpkdata extract zero/pole/gain data
|
|
\ lti/ssdata extract state-space matrices
|
|
\ lti/dssdata descriptor version of SSDATA
|
|
\ frd/frdata extract frequency response data
|
|
\ lti/get access values of LTI model properties
|
|
\ ss/getDelayModel access internal delay model (state space)
|
|
== ========================== ============================================
|
|
|
|
|
|
Conversions
|
|
----------------------------------------------------------------------------
|
|
|
|
== ============================ ============================================
|
|
\* :func:`tf` conversion to transfer function
|
|
\ zpk conversion to zero/pole/gain
|
|
\* :func:`ss` conversion to state space
|
|
\* :func:`frd` conversion to frequency data
|
|
\* :func:`c2d` continuous to discrete conversion
|
|
\ d2c discrete to continuous conversion
|
|
\ d2d resample discrete-time model
|
|
\ upsample upsample discrete-time LTI systems
|
|
\* :func:`ss2tf` state space to transfer function
|
|
\s :func:`~scipy.signal.ss2zpk` transfer function to zero-pole-gain
|
|
\* :func:`tf2ss` transfer function to state space
|
|
\s :func:`~scipy.signal.tf2zpk` transfer function to zero-pole-gain
|
|
\s :func:`~scipy.signal.zpk2ss` zero-pole-gain to state space
|
|
\s :func:`~scipy.signal.zpk2tf` zero-pole-gain to transfer function
|
|
== ============================ ============================================
|
|
|
|
|
|
System interconnections
|
|
----------------------------------------------------------------------------
|
|
|
|
== ========================== ============================================
|
|
\* :func:`~control.append` group LTI models by appending inputs/outputs
|
|
\* :func:`~control.parallel` connect LTI models in parallel
|
|
(see also overloaded ``+``)
|
|
\* :func:`~control.series` connect LTI models in series
|
|
(see also overloaded ``*``)
|
|
\* :func:`~control.feedback` connect lti models with a feedback loop
|
|
\ lti/lft generalized feedback interconnection
|
|
\* :func:`~control.connect` arbitrary interconnection of lti models
|
|
\ sumblk summing junction (for use with connect)
|
|
\ strseq builds sequence of indexed strings
|
|
(for I/O naming)
|
|
== ========================== ============================================
|
|
|
|
|
|
System gain and dynamics
|
|
----------------------------------------------------------------------------
|
|
|
|
== ========================== ============================================
|
|
\* :func:`dcgain` steady-state (D.C.) gain
|
|
\ lti/bandwidth system bandwidth
|
|
\ lti/norm h2 and Hinfinity norms of LTI models
|
|
\* :func:`pole` system poles
|
|
\* :func:`zero` system (transmission) zeros
|
|
\ lti/order model order (number of states)
|
|
\* :func:`~control.pzmap` pole-zero map (TF only)
|
|
\ lti/iopzmap input/output pole-zero map
|
|
\* :func:`damp` natural frequency, damping of system poles
|
|
\ esort sort continuous poles by real part
|
|
\ dsort sort discrete poles by magnitude
|
|
\ lti/stabsep stable/unstable decomposition
|
|
\ lti/modsep region-based modal decomposition
|
|
== ========================== ============================================
|
|
|
|
|
|
Time-domain analysis
|
|
----------------------------------------------------------------------------
|
|
|
|
== ========================== ============================================
|
|
\* :func:`step` step response
|
|
\ stepinfo step response characteristics
|
|
\* :func:`impulse` impulse response
|
|
\* :func:`initial` free response with initial conditions
|
|
\* :func:`lsim` response to user-defined input signal
|
|
\ lsiminfo linear response characteristics
|
|
\ gensig generate input signal for LSIM
|
|
\ covar covariance of response to white noise
|
|
== ========================== ============================================
|
|
|
|
|
|
Frequency-domain analysis
|
|
----------------------------------------------------------------------------
|
|
|
|
== ========================== ============================================
|
|
\* :func:`bode` Bode plot of the frequency response
|
|
\ lti/bodemag Bode magnitude diagram only
|
|
\ sigma singular value frequency plot
|
|
\* :func:`~control.nyquist` Nyquist plot
|
|
\* :func:`~control.nichols` Nichols plot
|
|
\* :func:`margin` gain and phase margins
|
|
\ lti/allmargin all crossover frequencies and margins
|
|
\* :func:`freqresp` frequency response over a frequency grid
|
|
\* :func:`evalfr` frequency response at single frequency
|
|
== ========================== ============================================
|
|
|
|
|
|
Model simplification
|
|
----------------------------------------------------------------------------
|
|
|
|
== ========================== ============================================
|
|
\* :func:`~control.minreal` minimal realization; pole/zero cancellation
|
|
\ ss/sminreal structurally minimal realization
|
|
\* :func:`~control.hsvd` hankel singular values (state contributions)
|
|
\* :func:`~control.balred` reduced-order approximations of LTI models
|
|
\* :func:`~control.modred` model order reduction
|
|
== ========================== ============================================
|
|
|
|
|
|
Compensator design
|
|
----------------------------------------------------------------------------
|
|
|
|
== ========================== ============================================
|
|
\* :func:`rlocus` evans root locus
|
|
\* :func:`sisotool` SISO controller design
|
|
\* :func:`~control.place` pole placement
|
|
\ estim form estimator given estimator gain
|
|
\ reg form regulator given state-feedback and
|
|
estimator gains
|
|
== ========================== ============================================
|
|
|
|
|
|
LQR/LQG design
|
|
----------------------------------------------------------------------------
|
|
|
|
== ========================== ============================================
|
|
\ ss/lqg single-step LQG design
|
|
\* :func:`~control.lqr` linear quadratic (LQ) state-fbk regulator
|
|
\ dlqr discrete-time LQ state-feedback regulator
|
|
\ lqry LQ regulator with output weighting
|
|
\ lqrd discrete LQ regulator for continuous plant
|
|
\ ss/lqi Linear-Quadratic-Integral (LQI) controller
|
|
\ ss/kalman Kalman state estimator
|
|
\ ss/kalmd discrete Kalman estimator for cts plant
|
|
\ ss/lqgreg build LQG regulator from LQ gain and Kalman
|
|
estimator
|
|
\ ss/lqgtrack build LQG servo-controller
|
|
\ augstate augment output by appending states
|
|
== ========================== ============================================
|
|
|
|
|
|
State-space (SS) models
|
|
----------------------------------------------------------------------------
|
|
|
|
== ========================== ============================================
|
|
\* :func:`rss` random stable cts-time state-space models
|
|
\* :func:`drss` random stable disc-time state-space models
|
|
\ ss2ss state coordinate transformation
|
|
\ canon canonical forms of state-space models
|
|
\* :func:`~control.ctrb` controllability matrix
|
|
\* :func:`~control.obsv` observability matrix
|
|
\* :func:`~control.gram` controllability and observability gramians
|
|
\ ss/prescale optimal scaling of state-space models.
|
|
\ balreal gramian-based input/output balancing
|
|
\ ss/xperm reorder states.
|
|
== ========================== ============================================
|
|
|
|
|
|
Frequency response data (FRD) models
|
|
----------------------------------------------------------------------------
|
|
|
|
== ========================== ============================================
|
|
\ frd/chgunits change frequency vector units
|
|
\ frd/fcat merge frequency responses
|
|
\ frd/fselect select frequency range or subgrid
|
|
\ frd/fnorm peak gain as a function of frequency
|
|
\ frd/abs entrywise magnitude of frequency response
|
|
\ frd/real real part of the frequency response
|
|
\ frd/imag imaginary part of the frequency response
|
|
\ frd/interp interpolate frequency response data
|
|
\* :func:`~control.mag2db` convert magnitude to decibels (dB)
|
|
\* :func:`~control.db2mag` convert decibels (dB) to magnitude
|
|
== ========================== ============================================
|
|
|
|
|
|
Time delays
|
|
----------------------------------------------------------------------------
|
|
|
|
== ========================== ============================================
|
|
\ lti/hasdelay true for models with time delays
|
|
\ lti/totaldelay total delay between each input/output pair
|
|
\ lti/delay2z replace delays by poles at z=0 or FRD phase
|
|
shift
|
|
\* :func:`~control.pade` pade approximation of time delays
|
|
== ========================== ============================================
|
|
|
|
|
|
Model dimensions and characteristics
|
|
----------------------------------------------------------------------------
|
|
|
|
== ========================== ============================================
|
|
\ class model type ('tf', 'zpk', 'ss', or 'frd')
|
|
\ isa test if model is of given type
|
|
\ tf/size model sizes
|
|
\ lti/ndims number of dimensions
|
|
\ lti/isempty true for empty models
|
|
\ lti/isct true for continuous-time models
|
|
\ lti/isdt true for discrete-time models
|
|
\ lti/isproper true for proper models
|
|
\ lti/issiso true for single-input/single-output models
|
|
\ lti/isstable true for models with stable dynamics
|
|
\ lti/reshape reshape array of linear models
|
|
== ========================== ============================================
|
|
|
|
Overloaded arithmetic operations
|
|
----------------------------------------------------------------------------
|
|
|
|
== ========================== ============================================
|
|
\* \+ and - add, subtract systems (parallel connection)
|
|
\* \* multiply systems (series connection)
|
|
\ / right divide -- sys1\*inv(sys2)
|
|
\- \\ left divide -- inv(sys1)\*sys2
|
|
\ ^ powers of a given system
|
|
\ ' pertransposition
|
|
\ .' transposition of input/output map
|
|
\ .\* element-by-element multiplication
|
|
\ [..] concatenate models along inputs or outputs
|
|
\ lti/stack stack models/arrays along some dimension
|
|
\ lti/inv inverse of an LTI system
|
|
\ lti/conj complex conjugation of model coefficients
|
|
== ========================== ============================================
|
|
|
|
Matrix equation solvers and linear algebra
|
|
----------------------------------------------------------------------------
|
|
|
|
== ========================== ============================================
|
|
\* :func:`~control.lyap` solve continuous-time Lyapunov equations
|
|
\* :func:`~control.dlyap` solve discrete-time Lyapunov equations
|
|
\ lyapchol, dlyapchol square-root Lyapunov solvers
|
|
\* :func:`~control.care` solve continuous-time algebraic Riccati
|
|
equations
|
|
\* :func:`~control.dare` solve disc-time algebraic Riccati equations
|
|
\ gcare, gdare generalized Riccati solvers
|
|
\ bdschur block diagonalization of a square matrix
|
|
== ========================== ============================================
|
|
|
|
|
|
Additional functions
|
|
----------------------------------------------------------------------------
|
|
|
|
== ========================== ============================================
|
|
\* :func:`~control.gangof4` generate the Gang of 4 sensitivity plots
|
|
\* :func:`~numpy.linspace` generate a set of numbers that are linearly
|
|
spaced
|
|
\* :func:`~numpy.logspace` generate a set of numbers that are
|
|
logarithmically spaced
|
|
\* :func:`~control.unwrap` unwrap phase angle to give continuous curve
|
|
== ========================== ============================================
|
|
|
|
"""
|