*kf
by An Uncommon Lab

Create powerful Kalman filters and related algorithms.

Iterate quickly on designs.

Automatically generate test simulations.

Compare results with theoretical results.

Integrate with existing simulations.

Generate robust and fast code.

Intro

screenshot

*kf is a tool for designing, integrating, and testing Kalman filters and other state estimation techniques in MATLAB. It generates custom filters to fit the user's problem, allowing a user to start simple and iterate to a mature design. It also has a bunch of utility functions that make all kinds of filter-related tasks easy and robust. Here's how.

options

First, you describe your problem to *kf. It can then build custom filters quickly, with generic or detailed options, as you like.

NMEE

Second, it can automatically test the filters as soon as they're generated, preventing the need to constantly edit a test program to incorporate each new filter type.

code snip

Third, it gets the implementation right, using efficient run-time-sensitive practices and robust numerical methods.

simulink block

It makes it easy to integrate the generated filters with MATLAB or Simulink, and the generated filters also support C code generation.

info box

Finally, it provides a wealth of information along the way, helping users intelligently build filters for their particular assumptions, approximations, and run-time concerns.

Video

Here's a quick video. You can expand it to full screen.

Engine

The engine works like this: First, we describe our problem, like telling it about our propagation and observations functions. Second, we set up what kind of filter we would like, what options, etc. Third, we generate code for the filter. Then we test.

For example:

1

We provide our problem's...

Propagation function

Observation function

Noise covariance matrices/functions

Initial conditions

... such as...

dynamics.m

measure.m

Q, R

x0, P0

2

... and set some options...

Filter Name

Filter Architecture

Covariance Type

... such as...

'my_filter'

Unscented Filter

Cholesky Factor

3

... and *kf will generate...

Initialization function

Filter function

Example simulation

Monte-Carlo test

... such as...

my_filter_init.m

my_filter_step.m

my_filter_example.m

my_filter_mc.m


Now we can run my_filter_example in MATLAB to see how the filter works in a simple simulation. If it looks good, we can run my_filter_mc to test its statistical properties. We can also use these generated functions as the starting point for more complex simulations.

See the pendulum tutorial for a concrete example.

Use Cases

Here are a few hypothetical use cases where *kf could make a big difference in the development of a filter from early to advanced stages.

Sam needs to build a state estimator that will run on a microprocessor in an industrial robot. She spends the morning writing out the propagation and observation functions in MATLAB and maybe some functions to produce analytical Jacobians at a given state. Now she starts up *kf. First, she tests her analytical Jacobians against the propagation and observation functions to make sure they're right. Then she runs skfengine, selects Extended filters, types in the name of those functions, and clicks Generate Code. This automatically generates an extended Kalman filter for her particular problem as well as a simulation to test it. She runs the sim and finds that things look good. Now she wants to start tweaking options to reduce the filter's runtime, so she selects a few options. She regenerates and tests. She iterates on the design until she's made a filter that's ready for production. She deploys the filter for the testing team. They don't have *kf and can run Sam's filter anyway (because *kf does not create toolbox dependencies). They do some testing in MATLAB with the robot in the loop and approve the filter. It's now ready for C code implementation. *kf can help with this too, but Sam opts for the traditional approach of translating the code by hand. Fortunately, the code is quite readable, which she appreciates.

Tom's needs are a little different. There's no microprocessor or anything, but he has a giant set of data for some nonlinear process that he'll need to filter as soon as possible. He too writes out his propagation and observation functions and sets some constants in the base workspace. Then he starts up *kf, selects Unscented filters, describes his problem, and generates code. That step takes about 2 minutes, and now he has a sigma-point filter (unscented Kalman filter), a simulation, and Monte-Carlo test. Perhaps the simulation looks ok, but the Monte-Carlo test shows that the statistics aren't very good. So, he reviews his code, finds some potential problems, and regenerates right away. Now things look better in the Monte-Carlo test, and he's ready to apply the filter to his giant dataset, but finds that he'd like the filter to run faster. Since Tom has MATLAB Coder installed, which *kf can take advantage of, he goes back to *kf and has it generate a MEX file (compiled code that MATLAB runs). This is about 100X faster, so Tom uses this on his giant dataset and sees much faster results.

Hans needs to develop an algorithm to estimate the state of certain components in a car engine. The problem requires a good deal of numerical precision, so he'll need powerful techniques. His team uses Simulink for simulation and generates C code directly from the models to use on the car's computers. Hans already has his functions and constants set up, so he starts up *kf, sets it up for his problem, choses the most numerically-robust options, like a “square-root” form for the covariance matrix, and makes sure that the numerical safety checks are in place. He tells *kf to generate a Simulink block along with other stuff that gets generated, and clicks Generate Code. He runs the sim and runs the Monte-Carlo test and determines that things look good. He runs the automatically created code generation script to make sure code generation will work correctly later. Now he puts the Simulink block inside the car system model, and his team continues with their Simulink-based design process. When they generate C code for the car's computers later, this all works the first time, because Hans has already tested that the code supports code generation. He saves his *kf session, and when a required change comes up a few weeks later, he can automatically regenerate everything.

Details

Engine

The documentation is the best place to learn about the details of the tool, but here's a sneak peak of a few filters you could quickly piece together with *kf. We'll try to span the space of possible filters.

The best place to start learning about generating these filters is the pendulum tutorial.

Frameworks

Not all problems justify generating a custom filter. Sometimes it's easier to just write a script and have it call a function for the filtering. For Kalman filters, there's a Kalman filter framework, which can function as a large number of different filters, such as a fully linear Kalman filter, an extended Kalman filter, an iterated filter, and a Schmidt-Kalman filter. Using it looks something like this:

options = kffoptions('f', @my_propagation_function, ...); % Configure the filter.
 
for k = 1:n
    ...
    [x_k, P_k] = kff(t, x_km1, P_km1, z(:,k), options); % Run one step of the filter.
    ...
end

See the framework tutorial for more.

Basic Filters & Utilities

We might also use one of the built-in “generic” filters for quick prototyping work with simple function handles. For instance:

% Update state, x, and information matrix, Y, for new measurement, z.
[x, Y] = eif(t, x, Y, u, z, @propagate, @measure, invF, H, G, invQ, invR, dt);

There are several utility functions as well. For instance to draw n random vectors with a covariance of C, we can use mnddraw:

% If C is m-by-m, then draws will be m-by-n.
draws = mnddraw(C, n);

Or for the sake of simulation, we might need a random, valid 5-by-5 covariance matrix:

C = randcov(5);

There are naturally many more such little utilities. For a list, see the doc.

Requirements

*kf requires MATLAB R2012a or later. It has been tested on OS X, Windows, and Linux.

Some of the integration options naturally require some dependencies. We've kept them as light as possible. Here's a breakdown:

MATLAB is the only strong requirement. With just MATLAB, you can generate filters as MATLAB code.

With Simulink, you can automatically wrap the generated filter in a Simulink block.

If you have MATLAB Coder, you can further:

Purchasing & Installation

*kf is US$1000. To purchase and set up an account, see our purchasing page.

After that, installation is easy.

  1. In MATLAB R2013b and later, enter the following at the command line:
    eval(urlread('http://install.anuncommonlab.com/starkf/install_starkf_web.m'))
  2. That will guide you through logging in and choosing a directory for *kf to live it.
  3. Alternately, log in to download the manual installation package (for machines that aren't connected to the internet or are using an older version of MATLAB).

That should do it. You'll be emailed when there are significant updates.

FAQ

I have a trusty ekf file I wrote a long time ago. How would *kf help me?

*kf would help if you needed it to run faster, or to add “consider covariance”, or to use more robust numerical techniques, or to update different sensors at different rates, or to try an unscented filter, or to say, “I have infinite covariance when the filter starts”, or to run some statistics on the results, or to test the old EKF, or to build an iterated filter for better accuracy. You get the idea. But we know that some folks just need the most basic EKF for light duty, and we'll always recommend using the right tool for the job.

Are there ready-made filters for industry-specific problems?

No. We've focused on making *kf a general tool, not tied to any particular industry, but useful for state estimation in its many forms. Is there a particular industry or problem you were hoping for? Let us know.

Which type of filter should I use?

That's a great question. Here are some notes.

How do I know these filters work?

We've tested the filter generation engine with tens of thousands of permutations of options, generating tens of thousands of different filters. We have compared their results to known results and verified that the filter algorithms are correct. However, there are too many permutations to realistically test them all, and since the generated filters call the user's custom functions, performance is naturally dependent on the user. The right answer is that the user must test her generated filters comprehensively, and *kf has tools to help with this as well.

How does this tie into model-based design?

The filters that *kf generates support code generation by MATLAB Coder and Simulink Coder. Therefore, the very same filter code that's generated initially and tested by automatic simulation and testing functions can be used in larger simulations, can generate C code, and can be tested directly in the target. That is, *kf ties perfectly into model-based design.

Can I use *kf without having to understand anything?

No. However, *kf will help you learn about all kinds of different filtering concepts very quickly by making it easy to try different ideas and by providing detailed documentation, which is freely available to all. Also, this article is good place to start learning. It takes a lifetime to master all this stuff, but it doesn't take very long at all to learn what you need in order to create one or two great filters.

I do research in state estimation. Will *kf help me build fundamentally new filters?

No, not really. It might help by making it easy to generate tons of different well-known filters for comparison. It's meant to combine good state estimation concepts and make them easy to wield, but it's not meant to build fundamentally new forms.

How is licensing handled?

*kf is licensed to one person at a time. It may be installed on 5 machines simultaneously. Each machine requires registration, which is handled automatically if the machine is connected to the internet, but this can be done manually too.

Resources

Buy it. >>

Log in to download. >>

Read the engine tutorial. >>

Read the framework tutorial. >>

Blast through the doc. >>

Read about Kalman filters and related algorithms. >>

Contact us. >>

Legal

*kf is a trademark of An Uncommon Lab. MATLAB, Simulink, and MATLAB Coder are trademarks of The MathWorks, Inc. No part of these materials should be construed as implying endorsement on the part of The MathWorks, Inc., for An Uncommon Lab or *kf. OS X is a registered trademark of Apple. Windows is a registered trademark of Microsoft. Linux is a registered trademark of Linus Torvalds.

 

<< Back to An Uncommon Lab