KALMTOOL
Version 2
for Use with MATLAB
State Estimation for Nonlinear Systems
Technical Report IMM-REP-2000-6 (Revised edition, Dec. 2001)
Department of Mathematical Modelling & Department of Automation
Technical University of Denmark
Magnus Nørgaard
December 17, 2002
RELEASE NOTES
This note contains important information on how the present toolbox is to be installed,
and the conditions under which it may be used. Please read it carefully before use.
Before You Start Using the Toolbox
After installation, all toolbox functions will be located in one directory, and the files
associated with the demonstration programs will be located in a subdirectory under
this. The user should make a path to these directories with the MATLAB function
path:
>> path(path,’/xx/.../xx/Kalmtool’);
>> path(path,’/xx/.../xx/Kalmtool/Demo’);
If the toolbox is going to be used on a regular basis, it is recommended to include this
statement in the file startup.m, which is invoked during the start of MATLAB.
If a C compiler is available, and the MATLAB mex command has been set up, the
MEX functions in the demonstration directory are compiled as follows:
>> cd /xx/xx/.../Kalmtool/Demo
>> demomex
This script invokes the mex command for each of the MEX functions in the demonstra-
tion directory.
Conditions/Disclaimer
By using the toolbox the user agrees to all of the following:
• If one is going to publish any work where this toolbox has been used, please include
a reference to the article: M. Nørgaard, N.K. Poulsen, O. Ravn: New Developments
in State Estimation for Nonlinear Systems, Automatica, (36:11), Nov. 2000, pp.
1627–1638.
• Magnus Nørgaard does not provide any support for this product whatsoever.
i
ii
• The Kalmtool toolbox is shareware. The limited version, which is the one available
from the internet, does not include the C source code for the mex-files. The full
version is the same as the limited version, but it includes the source code. The
conditions for use are the same for the two versions. The full license can currently
be obtained for 85USD/95EUR (single-user license) or 150USD/170EUR (multi-
user license). The price does not include support. Please contact the author by
e-mail for registration details.
The registration requirements are the following:
For education and research at the Technical University of Denmark
(DTU): Limited and full versions are free.
For full-time registered undergraduate and graduate students and for
university researchers: The limited version is free.
Others: Everyone else are free to download and evaluate the toolbox for a 30 day
period but are required to obtain a full license for use beyond 30 days.
Exceptions: None. Requests for free access to the source code will not be an-
swered.
• It is not permitted to utilize any part of the software in commercial products
without prior written consent of Magnus Nørgaard.
• THE TOOLBOX IS PROVIDED ”AS-IS” WITHOUT WARRANTY OF ANY
KIND, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
TO THE IMPLIED WARRANTIES OR CONDITIONS OF MERCHANTABIL-
ITY OR FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL
MAGNUS NØRGAARD BE LIABLE FOR ANY SPECIAL, INCIDENTAL, IN-
DIRECT, OR CONSEQUENTIAL DAMAGES OF ANY KIND, OR DAMAGES
WHATSOEVER RESULTING FROM LOSS OF USE, DATA, OR PROFITS,
WHETHER OR NOT MAGNUS NØRGAARD HAS BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGES, AND/OR ON ANY THEORY OF LIA-
BILITY ARISING OUT OF OR IN CONNECTION WITH THE USE OR PER-
FORMANCE OF THIS SOFTWARE.
Trademarks of companies and/or organizations mentioned in this documentation ap-
pear for identification purposes only and are the property of their respective companies
and/or organizations.
Magnus Nørgaard
toolbox@magnusnorgaard.dk
News in version 2 of
KALMTOOL
Version 2 looks much like version 1 on the surface as there are no new functions. Nev-
ertheless, inside all major functions the changes are substantial.
Linear Terms in the Equations
The DD1 and DD2 filtering functions in the first version of the toolbox were written in
a very general fashion in the sense that there was no possibility to take advantage of
particularly simple terms in the model equations. This has been changed in version 2
so that linear terms can be specified upon call of the functions. This has a particulaly
strong impact on the DD2 filters as the speed increase here will be very significant.
The downside of these extensions is that the toolbox code is no longer quite as short,
clean and simple as it used to be.
In Section 2.6 it will be explained how to call the functions when the equations contain
linear terms.
Mean Values
In version 1 it was possible to specify mean values of the noise processes when calling
the functions. I have decided to remove this feature for various reasons. I believe it was
rarely needed and to most people it was plainly confusing. If needed, mean values can
easily be hard coded or simply passed to the equation functions through the optional
initialization matrix optpar.init.
Mex functions
Starting from Matlab 6, the Windows version now ships with the C compiler lcc (it was
shipped even with some versions of Matlab 5.3). Thus, I have not found it necessary to
provide compilations of the kalmlib library for all major Windows compilers but only
for the lcc compiler. Linux users can still use gcc compiler for their mex-functions.
iii
iv
Chapter 1
Introduction
This manual is a user’s guide for the KALMTOOL toolbox; a MATLAB toolbox con-
taining functions for state estimation for nonlinear systems. The toolbox contains the
well-known Extended Kalman Filter (EKF) and two new filters called the DD1 filter and
the DD2 filter.
The toolbox will run under MATLAB 5.3 and higher, and it is independent of other
MATLAB toolboxes. All functions exist as m-files but for faster execution of the com-
putationally intensive functions these have also been written in C and are provided as
CMEX-functions. The user will have to add some problem specific C code and compile
the functions with the mex command in order to run the CMEX-functions.
Generally, it will require only superficial knowledge about the C programming language
to work with the MEX functions. If you run MATLAB under Linux, you can use the
gcc compiler. Under Windows you can use the lcc compiler, which now ships with
MATLAB. See the External Interfaces manual for MATLAB (formerly known as the
Application Program Interface Guide) on how to set up the mex command for these
compilers.
1.1 Why this Toolbox?
The purpose of this toolbox is to make implementations of the new DD1 and DD2 fil-
ters available for solving nonlinear state estimation problems and to enable a comparison
with a conventional method like the extended Kalman filter.
So what’s the deal with these filters? If you are familiar with the EKF, or one of its
‘relatives’, you will quickly find out about the advantage of the new filters. First of
all, they are easier to use. Secondly, you can expect a similar (DD1) or better (DD2)
performance than with the EKF. On the downside, the new filters tend to require more
computations than the EKF.
1
2
CHAPTER 1.
INTRODUCTION
What exactly is different about the new filters? To make a short story long, we found
that the extended Kalman filter was somewhat inconvenient to use in some of our appli-
cations. A small modification of the application sometimes had serious implications on
the EKF implementation. Moreover, it was often difficult to implement. Our problem
was that the EKF requires a linearization of the system model. Sometimes this is easy
to find but sometimes it can be pretty hard. In any case, it makes things inflexible. If a
small change is made in the model, one has to work out a new set of derivatives. This is
particularly inconvenient in model calibration where certain model parameters are tem-
porarily included in the state vector and estimated simultaneously with the actual states.
So where can I read about these filters? Three publications are available so far.
The short introduction:
M. Nørgaard, N.K. Poulsen, O. Ravn: Easy and Accurate State Estimation for Nonlinear
Systems, 14th IFAC World Conference in Beijing, China, July 5-9, 1999, pp. 343–348.
An expanded version:
M. Nørgaard, N.K. Poulsen, O. Ravn: New Developments in State Estimation for Non-
linear Systems, Automatica, (36:11), Nov. 2000, pp. 1627–1638.
The most thorough description (is shipped with the toolbox):
M. Nørgaard, N.K. Poulsen, O. Ravn: Advances in Derivative-Free State Estimation for
Nonlinear Systems, Technical Report IMM-REP-1998-15, Department of Mathematical
Modelling, DTU, 1998 (revised Apr. 2000).