{
 "metadata": {
  "name": "",
  "signature": "sha256:dedbd7f55073b104a3b3626e73108b6a60611b932a173ce508666a264357c866"
 },
 "nbformat": 3,
 "nbformat_minor": 0,
 "worksheets": [
  {
   "cells": [
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "[Table of Contents](http://nbviewer.ipython.org/github/rlabbe/Kalman-and-Bayesian-Filters-in-Python/blob/master/table_of_contents.ipynb)"
     ]
    },
    {
     "cell_type": "heading",
     "level": 1,
     "metadata": {},
     "source": [
      "Kalman Filter Math"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "#format the book\n",
      "%matplotlib inline\n",
      "from __future__ import division, print_function\n",
      "import matplotlib.pyplot as plt\n",
      "import sys\n",
      "sys.path.insert(0, '../code') # allow us to format the book\n",
      "import book_format\n",
      "book_format.load_style()"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "html": [
        "<style>\n",
        "@import url('http://fonts.googleapis.com/css?family=Source+Code+Pro');\n",
        "@import url('http://fonts.googleapis.com/css?family=Vollkorn');\n",
        "@import url('http://fonts.googleapis.com/css?family=Arimo');\n",
        "\n",
        "    div.cell{\n",
        "        width: 850px;\n",
        "        margin-left: 0% !important;\n",
        "        margin-right: auto;\n",
        "    }\n",
        "    div.text_cell code {\n",
        "        background: transparent;\n",
        "        color: #000000;\n",
        "        font-weight: 600;\n",
        "        font-size: 11pt;\n",
        "        font-style: bold;\n",
        "        font-family:  'Source Code Pro', Consolas, monocco, monospace;\n",
        "   }\n",
        "    h1 {\n",
        "        font-family: 'Open sans',verdana,arial,sans-serif;\n",
        "\t}\n",
        "\t\n",
        "    div.input_area {\n",
        "        background: #F6F6F9;\n",
        "        border: 1px solid #586e75;\n",
        "    }\n",
        "\n",
        "    .text_cell_render h1 {\n",
        "        font-weight: 200;\n",
        "        font-size: 30pt;\n",
        "        line-height: 100%;\n",
        "        color:#c76c0c;\n",
        "        margin-bottom: 0.5em;\n",
        "        margin-top: 1em;\n",
        "        display: block;\n",
        "        white-space: wrap;\n",
        "    } \n",
        "    h2 {\n",
        "        font-family: 'Open sans',verdana,arial,sans-serif;\n",
        "    }\n",
        "    .text_cell_render h2 {\n",
        "        font-weight: 200;\n",
        "        font-size: 20pt;\n",
        "        font-style: italic;\n",
        "        line-height: 100%;\n",
        "        color:#c76c0c;\n",
        "        margin-bottom: 0.5em;\n",
        "        margin-top: 1.5em;\n",
        "        display: block;\n",
        "        white-space: nowrap;\n",
        "    } \n",
        "    h3 {\n",
        "        font-family: 'Open sans',verdana,arial,sans-serif;\n",
        "    }\n",
        "    .text_cell_render h3 {\n",
        "        font-weight: 300;\n",
        "        font-size: 18pt;\n",
        "        line-height: 100%;\n",
        "        color:#d77c0c;\n",
        "        margin-bottom: 0.5em;\n",
        "        margin-top: 2em;\n",
        "        display: block;\n",
        "        white-space: nowrap;\n",
        "    }\n",
        "    h4 {\n",
        "        font-family: 'Open sans',verdana,arial,sans-serif;\n",
        "    }\n",
        "    .text_cell_render h4 {\n",
        "        font-weight: 300;\n",
        "        font-size: 16pt;\n",
        "        color:#d77c0c;\n",
        "        margin-bottom: 0.5em;\n",
        "        margin-top: 0.5em;\n",
        "        display: block;\n",
        "        white-space: nowrap;\n",
        "    }\n",
        "    h5 {\n",
        "        font-family: 'Open sans',verdana,arial,sans-serif;\n",
        "    }\n",
        "    .text_cell_render h5 {\n",
        "        font-weight: 300;\n",
        "        font-style: normal;\n",
        "        color: #1d3b84;\n",
        "        font-size: 16pt;\n",
        "        margin-bottom: 0em;\n",
        "        margin-top: 1.5em;\n",
        "        display: block;\n",
        "        white-space: nowrap;\n",
        "    }\n",
        "    div.text_cell_render{\n",
        "        font-family: 'Arimo',verdana,arial,sans-serif;\n",
        "        line-height: 135%;\n",
        "        font-size: 125%;\n",
        "        width:750px;\n",
        "        margin-left:auto;\n",
        "        margin-right:auto;\n",
        "        text-align:justify;\n",
        "        text-justify:inter-word;\n",
        "    }\n",
        "    div.output_subarea.output_text.output_pyout {\n",
        "        overflow-x: auto;\n",
        "        overflow-y: scroll;\n",
        "        max-height: 50000px;\n",
        "    }\n",
        "    div.output_subarea.output_stream.output_stdout.output_text {\n",
        "        overflow-x: auto;\n",
        "        overflow-y: scroll;\n",
        "        max-height: 50000px;\n",
        "    }\n",
        "    code{\n",
        "      font-size: 70%;\n",
        "    }\n",
        "    .rendered_html code{\n",
        "    background-color: transparent;\n",
        "    }\n",
        "    ul{\n",
        "        margin: 2em;\n",
        "    }\n",
        "    ul li{\n",
        "        padding-left: 0.5em; \n",
        "        margin-bottom: 0.5em; \n",
        "        margin-top: 0.5em; \n",
        "    }\n",
        "    ul li li{\n",
        "        padding-left: 0.2em; \n",
        "        margin-bottom: 0.2em; \n",
        "        margin-top: 0.2em; \n",
        "    }\n",
        "    ol{\n",
        "        margin: 2em;\n",
        "    }\n",
        "    ol li{\n",
        "        padding-left: 0.5em; \n",
        "        margin-bottom: 0.5em; \n",
        "        margin-top: 0.5em; \n",
        "    }\n",
        "    ul li{\n",
        "        padding-left: 0.5em; \n",
        "        margin-bottom: 0.5em; \n",
        "        margin-top: 0.2em; \n",
        "    }\n",
        "    a:link{\n",
        "       font-weight: bold;\n",
        "       color:#447adb;\n",
        "    }\n",
        "    a:visited{\n",
        "       font-weight: bold;\n",
        "       color: #1d3b84;\n",
        "    }\n",
        "    a:hover{\n",
        "       font-weight: bold;\n",
        "       color: #1d3b84;\n",
        "    }\n",
        "    a:focus{\n",
        "       font-weight: bold;\n",
        "       color:#447adb;\n",
        "    }\n",
        "    a:active{\n",
        "       font-weight: bold;\n",
        "       color:#447adb;\n",
        "    }\n",
        "    .rendered_html :link {\n",
        "       text-decoration: underline; \n",
        "    }\n",
        "    .rendered_html :hover {\n",
        "       text-decoration: none; \n",
        "    }\n",
        "    .rendered_html :visited {\n",
        "      text-decoration: none;\n",
        "    }\n",
        "    .rendered_html :focus {\n",
        "      text-decoration: none;\n",
        "    }\n",
        "    .rendered_html :active {\n",
        "      text-decoration: none;\n",
        "    }\n",
        "    .warning{\n",
        "        color: rgb( 240, 20, 20 )\n",
        "    } \n",
        "    hr {\n",
        "      color: #f3f3f3;\n",
        "      background-color: #f3f3f3;\n",
        "      height: 1px;\n",
        "    }\n",
        "    blockquote{\n",
        "      display:block;\n",
        "      background: #fcfcfc;\n",
        "      border-left: 5px solid #c76c0c;\n",
        "      font-family: 'Open sans',verdana,arial,sans-serif;\n",
        "      width:680px;\n",
        "      padding: 10px 10px 10px 10px;\n",
        "      text-align:justify;\n",
        "      text-justify:inter-word;\n",
        "      }\n",
        "      blockquote p {\n",
        "        margin-bottom: 0;\n",
        "        line-height: 125%;\n",
        "        font-size: 100%;\n",
        "      }\n",
        "</style>\n",
        "<script>\n",
        "    MathJax.Hub.Config({\n",
        "                        TeX: {\n",
        "                           extensions: [\"AMSmath.js\"]\n",
        "                           },\n",
        "                tex2jax: {\n",
        "                    inlineMath: [ ['$','$'], [\"\\\\(\",\"\\\\)\"] ],\n",
        "                    displayMath: [ ['$$','$$'], [\"\\\\[\",\"\\\\]\"] ]\n",
        "                },\n",
        "                displayAlign: 'center', // Change this to 'center' to center equations.\n",
        "                \"HTML-CSS\": {\n",
        "                    styles: {'.MathJax_Display': {\"margin\": 4}}\n",
        "                }\n",
        "        });\n",
        "</script>\n"
       ],
       "metadata": {},
       "output_type": "pyout",
       "prompt_number": 1,
       "text": [
        "<IPython.core.display.HTML at 0x7f9d3d7a04e0>"
       ]
      }
     ],
     "prompt_number": 1
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "** author's note:** *the ordering of material in this chapter is questionable. I delve into solving ODEs before discussing the basic Kalman equations. If you are reading this while it is being worked on (so long as this notice exists), you may find it easier to skip around a bit until I organize it better.*\n",
      "\n",
      "\n",
      "If you've gotten this far I hope that you are thinking that the Kalman filter's fearsome reputation is somewhat undeserved. Sure, I hand waved some equations away, but I hope implementation has been fairly straightforward for you. The underlying concept is quite straightforward - take two measurements, or a measurement and a prediction, and choose the output to be somewhere between the two. If you believe the measurement more your guess will be closer to the measurement, and if you believe the prediction is more accurate your guess will lie closer it it. That's not rocket science (little joke - it is exactly this math that got Apollo to the moon and back!). \n",
      "\n",
      "Well, to be honest I have been choosing my problems carefully. For any arbitrary problem finding some of the matrices that we need to feed into the Kalman filter equations can be quite difficult. I haven't been *too tricky*, though. Equations like Newton's equations of motion can be trivially computed for Kalman filter applications, and they make up the bulk of the kind of problems that we want to solve. If you are a hobbyist, you can safely pass by this chapter for now, and perhaps forever. Some of the later chapters will assume the material in this chapter, but much of the work will still be accessible to you. \n",
      "\n",
      "But, I urge everyone to at least read the first section, and to skim the rest. It is not much harder than what you have done - the difficulty comes in finding closed form expressions for specific problems, not understanding the math in this chapter. "
     ]
    },
    {
     "cell_type": "heading",
     "level": 2,
     "metadata": {},
     "source": [
      "Bayesian Probabilitity"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "The title of this book is *Kalman and Bayesian Filters in Python* but to date I have not touched on the Bayesian aspect much. There was enough going on in the earlier chapters that adding this form of reasoning about filters could be a distraction rather than a help. I now which to take some time to explain what Bayesian probability is and how a Kalman filter is in fact a Bayesian filter. This is not just a diversion. First of all, a lot of the Kalman filter literature uses this formulation when talking about filters, so you will need to understand what they are talking about. Second, this math plays a strong role in filtering design once we move past the Kalman filter. \n",
      "\n",
      "To do so we will go back to our first tracking problem - tracking a dog in a hallway. Recall the update step - we believed with some degree of precision that the dog was at position 7 (for example), and then receive a measurement that the dog is at position 7.5. We want to incorporate that measurement into our belief. In the *Discrete Bayes* chapter we used histograms to denote our estimates at each halway position, and in the \n",
      "*One Dimensional Kalman Filters* we used Gaussians. Both are method of using *Bayesian* probability.\n",
      "\n",
      "Briefly, *Bayesian* probability is a branch of math that lets us evaluate a hypothesis or new data point given some uncertain information about the past. For example, suppose you are driving down your neighborhood street and see one of your neighbors at their door, using a key to let themselves in. Three doors down you see two people in masks breaking a window of another house. What might you conclude?\n",
      "\n",
      "It is likely that you would reason that in the first case your neighbors were getting home and unlocking their door to get inside. In the second case you at least strongly suspect a robbery is in progress. In the first case you would just proceed on, and in the second case you'd probably call the police.\n",
      "\n",
      "Of course, things are not always what they appear. Perhaps unbeknowst to you your neighbor sold their house that morning, and they were now breaking in to steal the new owner's belongings. In the second case, perhaps the owners of the house were at a costume event at the next house, they had a medical emergency with their child, realized they lost their keys, and were breaking into their own house to get the much needed medication. Those are both *unlikely* events, but possible. Adding a few additional pieces of information would allow you to determine the true state of affairs in all but the most complicated situations.\n",
      "\n",
      "These are instances of *Bayesian* reasoning. We take knowledge from the past and integrate in new information. You know that your neighbor owned their house yesterday, so it is still highly likely that they still own it today. You know that owners of houses normally have keys to the front door, and that the normal mode of entrance into your own house is not breaking windows, so the second case is *likely* to be a breaking and entering. The reasoning is not ironclad as shown by the alternative explanations, but it is likely."
     ]
    },
    {
     "cell_type": "heading",
     "level": 3,
     "metadata": {},
     "source": [
      "Bayes' theorem"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "*Bayes' theorem* mathematically formalizes the above reasoning. It is written as\n",
      "\n",
      "$$P(A|B) = \\frac{P(B | A)\\, P(A)}{P(B)}\\cdot$$\n",
      "\n",
      "\n",
      "Before we do some computations, let's review what the terms mean. P(A) is called the *prior probability* of the event A, and is often just shortened to the *prior*. What is the prior? It is just the probabability of A being true *before* we incorporate new evidence. In our dog tracking problem above, the prior is the probability we assign to our belief that the dog is positioned at 7 before we make the measurement of 7.5. It is important to master this terminology if you expect to read a lot of the literature.\n",
      "\n",
      "$P(A|B)$ is the *conditional probability* that A is true given that B is true. For example, if it is true that your neighbor still owns their house, then it will be very likely that they are not breaking into their house. In Bayesian probability this is called the *posterior*, and it denotes our new belief after incorporating the measurement/knowledge of B. For our dog tracking problem the posterier is the probability given to the estimated position after incorporating the measurement 7.5. For the neighbor problem the posterier would be the probability of a break in after you find out that your neighbor sold their home last week.\n",
      "\n",
      "What math did we use for the dog tracking problem? Recall that we used this equation to compute the new mean and probability distribution\n",
      "\n",
      "$$\n",
      "\\begin{aligned}\n",
      "N(estimate) * N(measurement) &= \\\\\n",
      "N(\\mu_1, \\sigma_1^2)*N(\\mu_2, \\sigma_2^2) &= N(\\frac{\\sigma_1^2 \\mu_2 + \\sigma_2^2 \\mu_1}{\\sigma_1^2 + \\sigma_2^2},\\frac{1}{\\frac{1}{\\sigma_1^2} + \\frac{1}{\\sigma_2^2}}) \\cdot\n",
      "\\end{aligned}\n",
      "$$ \n",
      "\n",
      "\n",
      "Here $N(\\mu_1, \\sigma_1^2)$ is the old estimated position, so $\\sigma_1$ is an indiation of our *prior* probability. $N(\\mu_2, \\sigma_2^2)$ is the mean and variance of our measurement, and so the result can be thought of as the new position and probability distribution after incorporating the new measurement. In other words, our *posterior distribution* is \n",
      "\n",
      "$$\\frac{1}{{\\sigma_{estimate}}^2} + \\frac{1}{{\\sigma_{measurement}}^2}$$"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "This is still a little hard to compare to Bayes' equation because we are dealing with probability distributions rather than probabilities. So let's cast our minds back to the discrete Bayes chapter where we computed the probability that our dog was at any given position in the hallway. It looked like this:\n",
      "\n",
      "    def normalize(p):\n",
      "        s = sum(p)\n",
      "        for i in range (len(p)):\n",
      "            p[i] = p[i] / s\n",
      "\n",
      "    def update(pos, measure, p_hit, p_miss):\n",
      "        q = np.array(pos, dtype=float)\n",
      "        for i in range(len(hallway)):\n",
      "            if hallway[i] == measure:\n",
      "                q[i] = pos[i] * p_hit\n",
      "            else:\n",
      "                q[i] = pos[i] * p_miss\n",
      "        normalize(q)\n",
      "        return q\n",
      "\n",
      "Let's rewrite this using our newly learned terminology.\n",
      "\n",
      "    def update(prior_probability, measure, prob_hit, prob_miss):\n",
      "        posterior_probability = np.array(prior_probability, dtype=float)\n",
      "        for i in range(len(hallway)):\n",
      "            if hallway[i] == measure:\n",
      "                posterior_probability[i] = prior_probability[i] * p_hit\n",
      "            else:\n",
      "                posterior_probability[i] = prior_probability[i] * p_miss\n",
      "\n",
      "        return posterior_probability / sum(posterior_probability)\n",
      "\n",
      "         \n",
      "So what is this doing? It's multiplying the old belief that the dog is at position *i* (prior probability) with the probability that the measurement is correct for that position, and then dividing by the total probability for that new event.\n",
      "\n",
      "Now let's look at Bayes' equation again.\n",
      "\n",
      "$$P(A|B) = \\frac{P(B | A)\\, P(A)}{P(B)}\\cdot$$\n",
      "\n",
      "It's the same thing being calculated by the code. Multipy the prior ($P(A)$) by the probability of the measurement at each position ($P(B|A)$) and divide by the total probability for the event ($P(B)$).\n",
      "\n",
      "In other words the first half of the Discrete Bayes chapter developed Bayes' equation from a thought experiment. I could have just presented Bayes' equation and then given you the Python routine above to implement it, but chances are you would not have understood *why* Bayes' equation works. Presenting the equation first is the normal approach of Kalman filtering texts, and I always found it extremely nonintuitive. \n"
     ]
    },
    {
     "cell_type": "heading",
     "level": 2,
     "metadata": {},
     "source": [
      "Modeling a Dynamic System that Has Noise"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "We need to start by understanding the underlying equations and assumptions that the Kalman filter uses. We are trying to model real world phenomena, so what do we have to consider?\n",
      "\n",
      "First, each physical system has a process. For example, a car traveling at a certain velocity goes so far in a fixed amount of time, and its velocity varies as a function of its acceleration. We describe that behavior with the well known Newtonian equations we learned in high school.\n",
      "\n",
      "\n",
      "$$\n",
      "\\begin{aligned}\n",
      "v&=at\\\\\n",
      "x &= \\frac{1}{2}at^2 + v_0t + d_0\n",
      "\\end{aligned}\n",
      "$$\n",
      "\n",
      "And once we learned calculus we saw them in this form:\n",
      "\n",
      "$$\n",
      "\\begin{aligned}\n",
      " \\mathbf{v} &= \\frac{d \\mathbf{x}}{d t}\\\\ \n",
      " \\quad \\mathbf{a} &= \\frac{d \\mathbf{v}}{d t}\\\\\n",
      " &= \\frac{d^2 \\mathbf{x}}{d t^2} \\,\\!\n",
      "\\end{aligned}\n",
      " $$\n",
      " \n",
      "A typical problem would have you compute the distance travelled given a constant velocity or acceleration. But, of course we know this is not all that is happening. First, we do not have perfect measures of things like the velocity and acceleration - there is always noise in the measurements, and we have to model that. Second, no car travels on a perfect road. There are bumps that cause the car to slow down, there is wind drag, there are hills that raise and lower the speed. If we do not have explicit knowledge of these factors we lump them all together under the term \"process noise\".\n",
      "\n",
      "Trying to model all of those factors explicitly and exactly is impossible for anything but the most trivial problem. I could try to include equations for things like bumps in the road, the behavior of the car's suspension system, even the effects of hitting bugs with the windshield, but the job would never be done - there would always be more effects to add and limits to our knowledge (how many bugs do we hit in an hour, for example). What is worse, each of those models would in themselves be a simplification - do I assume the wind is constant, that the drag of the car is the same for all angles of the wind, that the suspension act as perfect springs, that the suspension for each wheel acts identically, and so on.\n",
      "\n",
      "So control theory makes a mathematically correct simplification. We acknowledge that there are many factors that influence the system that we either do not know or that we don't want to have to model. At any time $t$ we say that the actual value (say, the position of our car) is the predicted value plus some unknown process noise:\n",
      "\n",
      "$$\n",
      "x(t) = x_{pred}(t) + noise(t)\n",
      "$$\n",
      "\n",
      "This is not meant to imply that $noise(t)$ is a function that we can derive analytically or that it is well behaved. If there is a bump in the road at $t=10$ then the noise factor will just incorporate that effect. Again, this is not implying that we model, compute, or even know the value of *noise(t)*, it is merely a statement of fact - we can *always* describe the actual value as the predicted value from our idealized model plus some other value. \n",
      "\n",
      "Let's express this with linear algebra. Using the same notation from previous chapters, we can say that our model of the system (without noise) is:\n",
      "\n",
      "$$ f(\\mathbf{x}) = \\mathbf{Fx}$$\n",
      "\n",
      "That is, we have a set of linear equations that describe our system. For our car, \n",
      "$\\mathbf{F}$ will be the coefficients for Newton's equations of motion. \n",
      "\n",
      "Now we need to model the noise. We will just call that *w*, and add it to the equation.\n",
      "\n",
      "$$ f(\\mathbf{x}) = \\mathbf{Fx} + \\mathbf{w}$$\n",
      "\n",
      "Finally, we need to consider inputs into the system. We are dealing with linear problems here, so we will assume that there is some input $u$ into the system, and that we have some linear model that defines how that input changes the system. For example, if you press down on the accelerator in your car the car will accelerate. We will need a matrix $\\mathbf{B}$ to convert $u$ into the effect on the system. We just add that into our equation:\n",
      "\n",
      "$$ f(\\mathbf{x}) = \\mathbf{Fx} + \\mathbf{Bu} + \\mathbf{w}$$\n",
      "\n",
      "And that's it. That is one of the equations that Kalman set out to solve, and he found a way to compute an optimal solution if we assume certain properties of $w$.\n",
      "\n",
      "However, we took advantage of something I left mostly unstated in the last chapter. We were able to provide a definition for $\\mathbf{F}$ because we were able to take advantage of the exact solution that Newtonian equations provide us. However, if you have an engineering background you will realize what a small class of problems that covers. If you don't, I will explain it next, and provide you with several ways to compute $\\mathbf{F}$ for arbitrary systems."
     ]
    },
    {
     "cell_type": "heading",
     "level": 2,
     "metadata": {},
     "source": [
      "Modelling Dynamic Systems"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Modelling dynamic systems is properly the topic of at least one undergraduate course in mathmatics. To an extent there is no substitute for a few semesters of ordinary and partial differential equations. If you are a hobbiest, or trying to solve one very specific filtering problem at work you probably do not have the time and/or inclination to devote a year or more to that education.\n",
      "\n",
      "However, I can present enough of the theory to allow us to create the system equations for many different Kalman filters, and give you enough background to at least follow the mathematics in the literature. My goal is to get you to the stage where you can read a Kalman filtering book or paper and understand it well enough to implement the algorithms. The background math is deep, but we end up using a few simple techniques over and over again in practice. \n",
      "\n",
      "Let's lay out the problem and discuss what the solution will be. We  model *dynamic systems* with a set of first order *differential equations*. This should not be a surprise as calculus is the math of of thing that vary. For example, we say that velocity is the derivative of distance with respect to time\n",
      "\n",
      "$$\\mathbf{v}= \\frac{d \\mathbf{x}}{d t} = \\dot{\\mathbf{x}}$$\n",
      "\n",
      "where $\\dot{\\mathbf{x}}$ is the notation for the derivative of $\\mathbf{x}$ with respect to t.\n",
      "\n",
      "\n",
      "We need to use these equations for the predict step of the Kalman filter. Given the state of the system at time $t$ we want to predict its state at time $t + \\Delta t$. The Kalman filter matrices do not accept differential equations, so we need a mathematical technique that will find the solution to those equations at each time step. In general it is extremely difficult to find analytic solutions to systems of differential equations, so we will normally use *numerical* techniques to find accurate approximations for these equations."
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "### Why This is Hard\n",
      "\n",
      "We model dynamic systems with a set of first order differential equations. For example, we already presented the Newtonian equation\n",
      "\n",
      "$$\\mathbf{v}=\\dot{\\mathbf{x}}$$\n",
      "\n",
      "where $\\dot{\\mathbf{x}}$ is the notation for the derivative of $\\mathbf{x}$ with respect to t, or $\\frac{d \\mathbf{x}}{d t}$.\n",
      "\n",
      "In general terms we can then say that a dynamic system consists of equations of the form\n",
      "\n",
      "$$ g(t) = \\dot{x}$$\n",
      "\n",
      "if the behaviour of the system depends on time. However, if the system is *time invariant* the equations are of the form\n",
      "$$ f(x) = \\dot{x}$$\n",
      "\n",
      "What does *time invariant* mean? Consider a home stereo. If you input a signal $x$ into it at time $t$, it will output some signal $f(x)$. If you instead make the input at a later time $t + \\Delta t$ the output signal will still be exactly the same, just shifted in time. This is different from, say, an aircraft. If you make a control input to the aircraft at a later time it's behavior will be different because it will have burned additonal fuel (and thus lost weight), drag may be different due to being at a different altitude, and so on.\n",
      "\n",
      "We can solve these equations by integrating each side. The time variant equation is very straightforward. We essentially solved this problem with the Newtonian equations above, but let's be explicit and write it out. Starting with  $$\\dot{\\mathbf{x}}=\\mathbf{v}$$ we get the expected\n",
      "\n",
      "$$ \\int \\dot{\\mathbf{x}}\\mathrm{d}t = \\int \\mathbf{v} \\mathrm{d}t\\\\\n",
      "x = vt + x_0$$\n",
      "\n",
      "However, integrating the time invariant equation is not so straightforward. \n",
      "\n",
      "$$ \\dot{x} = f(x) \\\\\n",
      "\\frac{dx}{dt} = f(x)\n",
      "$$ \n",
      "\n",
      "Using the *separation of variables* techniques, we divide by $f(x)$ and move the $dx$ term to the right so we can integrate each side:\n",
      "\n",
      "$$\n",
      "\\int^x_{x_0} \\frac{1}{f(x)} dx = \\int^t_{t_0} dt\\\\\n",
      "$$\n",
      "\n",
      "If we let the solution to the left hand side by named $F(x)$, we get\n",
      "\n",
      "$$F(x) - f(x_0) = t-t_0$$\n",
      "\n",
      "We then solve for x with\n",
      "\n",
      "$$F(x) = t - t_0 + F(x_0) \\\\\n",
      "x = F^{-1}[t-t_0 + F(x_0)]$$\n",
      "\n",
      "In other words, we need to find the inverse of $F$. This is not at all trivial, and a significant amount of course work in a STEM education is devoted to finding tricky, analytic solutions to this problem, backed by several centuries of research. \n",
      "\n",
      "In the end, however, they are tricks, and many simple forms of $f(x)$ either have no closed form solution, or pose extreme difficulties. Instead, the practicing engineer turns to numerical methods to find a solution to her problems. I would suggest that students would be better served by learning fewer analytic mathematical tricks and instead focusing on learning numerical methods, but that is the topic for another book."
     ]
    },
    {
     "cell_type": "heading",
     "level": 3,
     "metadata": {},
     "source": [
      "Finding the Fundamental Matrix for Time Invariant Systems"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      " If you already have the mathematical training in solving partial differential equations you may be able to put it to use; I am not assuming that sort of background.  So let me skip over quite a bit of mathematics and present the typical numerical techniques used in Kalman filter design. \n",
      "\n",
      "First, we express the system equations in state-space form (i.e. using linear algebra equations) with\n",
      "\n",
      "$$ \\dot{\\mathbf{x}} = \\mathbf{Fx}$$\n",
      "\n",
      "Now we can assert that we want to find the fundamental matrix $\\Phi$ that propagates the state with the equation\n",
      "\n",
      "$$x(t) = \\Phi(t-t_0)x(t_0)$$\n",
      "\n",
      "In other words, we just want to compute the value of $x$ at time $t$ by multipying its previous value by some matrix $\\Phi$. This is not trivial to do because the original equations do not include time \n",
      "\n",
      "Broadly speaking there are three ways to find $\\Phi$. The technique most often used with Kalman filters is to use a Taylor-series expansion: \n",
      "\n",
      "$$ \\Phi(t) = e^{\\mathbf{F}t} = \\mathbf{I} + \\mathbf{F}t  + \\frac{(\\mathbf{F}t)^2}{2!} + \\frac{(\\mathbf{F}t)^3}{3!} + ... $$\n",
      "\n",
      "This is much easy to compute, and thus is the typical approach used in Kalman filter design when the filter is reasonably small. If you are wondering where $e$ came from, I point you to the wikipedia article on the matrix exponential [1]. Here the important point is to recognize the very simple and regular form this equation takes. We will put this form into use in the next chapter, so I will not belabor its use here. \n",
      "\n",
      "*Linear Time Invarient Theory*, also known as LTI System Theory, gives us a way to find $\\Phi$ using the inverse Laplace transform. You are either nodding your head now, or completely lost. Don't worry, I will not be using the Lapace transform in this book except in this paragraph, as the computation is quite difficult to perform in practice. LTI system theory tells us that \n",
      "\n",
      "$$ \\Phi(t) = \\mathcal{L}^{-1}[(s\\mathbf{I} - \\mathbf{F})^{-1}]$$\n",
      "\n",
      "I have no intention of going into this other than to say that the inverse Lapace transform converts a signal into the frequency (time) domain, but finding a solution to the equation above is non-trivial. If you are interested, the Wikipedia article on LTI system theory provides an introduction [2].\n",
      "\n",
      "Finally, there are numerical techniques to find $\\Phi$. As filters get larger finding analytical solutions becomes very tedious (though packages like Sympy make it easier). C. F. van Loan [3] has developed a technique that finds both $\\Phi$ and $Q$ numerically.\n",
      "\n",
      "I have implemented van Loan's method in `FilterPy`. You may use it as follows:\n",
      "\n",
      "    from filterpy.common import van_loan_discretization\n",
      "  \n",
      "    F = np.array([[0,1],[-1,0]], dtype=float)\n",
      "    G = np.array([[0.],[2.]]) # white noise scaling\n",
      "    phi, Q = van_loan_discretization(F, G, dt=0.1)\n",
      "    \n",
      "See the docstring documentation for van_loan_discretization for more information, which I have embedded below."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "from filterpy.common import van_loan_discretization\n",
      "help(van_loan_discretization)"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "Help on function van_loan_discretization in module filterpy.common.discretization:\n",
        "\n",
        "van_loan_discretization(F, G, dt)\n",
        "    Discretizes a linear differential equation which includes white noise\n",
        "    according to the method of C. F. van Loan [1]. Given the continuous\n",
        "    model\n",
        "    \n",
        "        x' =  Fx + Gu\n",
        "    \n",
        "    where u is the unity white noise, we compute and return the sigma and Q_k\n",
        "    that discretizes that equation.\n",
        "    \n",
        "    \n",
        "    **Example**::\n",
        "    \n",
        "        Given y'' + y = 2u(t), we create the continuous state model of\n",
        "    \n",
        "        x' = | 0 1| * x + |0|*u(t)\n",
        "             |-1 0|       |2|\n",
        "    \n",
        "        and a time step of 0.1:\n",
        "    \n",
        "    \n",
        "        >>> F = np.array([[0,1],[-1,0]], dtype=float)\n",
        "        >>> G = np.array([[0.],[2.]])\n",
        "        >>> phi, Q = van_loan_discretization(F, G, 0.1)\n",
        "    \n",
        "        >>> phi\n",
        "        array([[ 0.99500417,  0.09983342],\n",
        "               [-0.09983342,  0.99500417]])\n",
        "    \n",
        "        >>> Q\n",
        "        array([[ 0.00133067,  0.01993342],\n",
        "               [ 0.01993342,  0.39866933]])\n",
        "    \n",
        "        (example taken from Brown[2])\n",
        "    \n",
        "    \n",
        "    **References**\n",
        "    \n",
        "    [1] C. F. van Loan. \"Computing Integrals Involving the Matrix Exponential.\"\n",
        "        IEEE Trans. Automomatic Control, AC-23 (3): 395-404 (June 1978)\n",
        "    \n",
        "    [2] Robert Grover Brown. \"Introduction to Random Signals and Applied\n",
        "        Kalman Fitlering.\" Forth edition. John Wiley & Sons. p. 126-7. (2012)\n",
        "\n"
       ]
      }
     ],
     "prompt_number": 2
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "### Forming First Order Equations from Higher Order Equations\n",
      "\n",
      "In the sections above I spoke of *first order* differential equations; these are equations with only first derivatives. However, physical systems often require second or higher order equations. Any higher order system of equations can be converted to a first order set of equations by defining extra variables for the first order terms and then solving. Let's do an example. \n",
      "\n",
      "Given the system $\\ddot{x} - 6\\dot{x} + 9x = t$ find the first order equations.\n",
      "\n",
      "\n",
      "The first step is to isolate the highest order term onto one side of the equation .\n",
      "\n",
      "$$\\ddot{x} = 6\\dot{x} - 9x + t$$\n",
      "\n",
      "We define two new variables:\n",
      "\n",
      "$$ x_1(t) = x \\\\\n",
      "x_2(t) = \\dot{x}\n",
      "$$\n",
      "\n",
      "Now we will substitute these into the original equation and solve, giving us a set of first order equations in terms of these new variables.\n",
      "\n",
      "First, we know that $\\dot{x}_1 = x_2$ and that $\\dot{x}_2 = \\ddot{x}$. Therefore\n",
      "\n",
      "$$\\begin{aligned}\n",
      "\\dot{x}_2 &= \\ddot{x} \\\\\n",
      "          &= 6\\dot{x} - 9x + t\\\\\n",
      "          &= 6x_2-9x_1 + t\n",
      "\\end{aligned}$$\n",
      "\n",
      "Therefore our first order system of equations is\n",
      "\n",
      "$$\\begin{aligned}\\dot{x}_1 &= x_2 \\\\\n",
      "\\dot{x}_2 &= 6x_2-9x_1 + t\\end{aligned}$$\n",
      "\n",
      "If you practice this a bit you will become adept at it. Just isolate the highest term, define a new variable and its derivatives, and then substitute."
     ]
    },
    {
     "cell_type": "heading",
     "level": 2,
     "metadata": {},
     "source": [
      "Walking Through the Kalman Filter Equations"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "I promised that you would not have to understand how to derive Kalman filter equations, and that is true. However, I do think it is worth walking through the equations one by one and becoming familiar with the variables. If this is your first time through the material feel free to skip ahead to the next section. However, you will eventually want to work through this material, so why not now? You will need to have passing familiarity with these equations to read material written about the Kalman filter, as they all presuppose that you are familiar with them. I will reiterate them here for easy reference.\n",
      "\n",
      "\n",
      "$$\n",
      "\\begin{aligned}\n",
      "\\text{Predict Step}\\\\\n",
      "\\mathbf{x} &= \\mathbf{F x} + \\mathbf{B u}\\;\\;\\;\\;&(1) \\\\\n",
      "\\mathbf{P} &= \\mathbf{FP{F}}^\\mathsf{T} + \\mathbf{Q}\\;\\;\\;\\;&(2) \\\\\n",
      "\\\\\n",
      "\\text{Update Step}\\\\\n",
      "\\textbf{y} &= \\mathbf{z} - \\mathbf{H}\\mathbf{x}\\;\\;\\;&(3) \\\\\n",
      "\\mathbf{S} &= \\mathbf{HPH}^\\mathsf{T} + \\mathbf{R} \\;\\;\\;&(4) \\\\\n",
      "\\mathbf{K} &= \\mathbf{PH}^\\mathsf{T}\\mathbf{S}^{-1}\\;\\;\\;&(5) \\\\\n",
      "\\mathbf{x} &= \\mathbf{x} +\\mathbf{K}\\mathbf{y} \\;\\;\\;&(6)\\\\\n",
      "\\mathbf{P} &= (\\mathbf{I}-\\mathbf{K}\\mathbf{H})\\mathbf{P}\\;\\;\\;&(7)\n",
      "\\end{aligned}\n",
      "$$\n",
      "\n",
      "I will start with the update step, as that is what we started with in the one dimensional Kalman filter case. The first equation is\n",
      "\n",
      "$$\n",
      "\\mathbf{y} = \\mathbf{z} - \\mathbf{H x}\\tag{3}\n",
      "$$\n",
      "\n",
      "On the right we have $\\mathbf{Hx}$. That should be recognizable as the measurement function. Multiplying $\\mathbf{H}$ with $\\mathbf{x}$ puts $\\mathbf{x}$ into *measurement space*; in other words, the same basis and units as the sensor's measurements. The variable $\\mathbf{z}$ is just the measurement; it is typical, but not universal to use $\\mathbf{z}$ to denote measurements in the literature ($\\mathbf{y}$ is also sometimes used). Do you remember this chart?"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "import mkf_internal\n",
      "mkf_internal.show_residual_chart()"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "metadata": {},
       "output_type": "display_data",
       "png": "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\nQmCC\n",
       "text": [
        "<matplotlib.figure.Figure at 0x7f9d2131da90>"
       ]
      }
     ],
     "prompt_number": 3
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "The blue point labeled \"prediction\" is the output of $\\mathbf{Hx}$, and the dot labeled \"measurement\" is $\\mathbf{z}$. Therefore, $\\mathbf{y} = \\mathbf{z} - \\mathbf{Hx}$ is how we compute the residual, drawn in red, where $\\mathbf{z}$ is the residual.\n",
      "\n",
      "The next two lines are the formidable:\n",
      "\n",
      "$$\n",
      "\\begin{aligned}\n",
      "\\mathbf{S} &= \\textbf{HPH}^\\mathsf{T} + \\textbf{R} \\;\\;\\;&(4) \\\\\n",
      "\\textbf{K} &= \\textbf{PH}^\\mathsf{T}\\mathbf{S}^{-1}\\;\\;\\;&(5) \\\\\n",
      "\\end{aligned}\n",
      "$$\n",
      "Unfortunately it is a fair amount of linear algebra to derive this. The derivation can be quite elegant, and I urge you to look it up if you have the mathematical education to follow it. But $\\mathbf{K}$ is just the *Kalman gain* - the ratio of how much measurement vs prediction we should use to create the new estimate. $\\mathbf{R}$ is the *measurement noise*, and $\\mathbf{P}$ is our *uncertainty covariance matrix* from the prediction step.\n",
      "\n",
      "So let's work through this expression by expression. Start with $\\mathbf{HPH}^\\mathsf{T}$. The linear equation $\\mathbf{ABA}^T$ can be thought of as changing the basis of $\\mathbf{B}$ to $\\mathbf{A}$. So $\\mathbf{HPH}^\\mathsf{T}$ is taking the covariance $\\mathbf{P}$ and putting it in measurement ($\\mathbf{H}$) space. \n",
      "\n",
      "In English, consider the problem of reading a temperature with a thermometer that provices readings in volts. Our state is in terms of temperature, but we are now doing calculations in *measurement space* - volts. So we need to convert $\\mathbf{P}$ from applying to temperatures to volts. The linear algebra form $\\textbf{H}\\textbf{P}\\textbf{H}^\\mathsf{T}$ takes $\\mathbf{P}$ to the basis used by $\\mathbf{H}$, namely volts. \n",
      "\n",
      "Then, once in measurement space, we can add the measurement noise $\\mathbf{R}$ to it. Hence, the expression for the uncertainty once we include the measurement is:\n",
      "\n",
      "$$\\mathbf{S} = \\mathbf{HP}\\mathbf{H}^\\mathsf{T} + \\mathbf{R}$$"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "The next equation is\n",
      "$$\\textbf{K} = \\textbf{P}\\textbf{H}^T\\mathbf{S}^{-1}\\\\\n",
      "$$\n",
      "\n",
      "$\\mathbf{K}$ is the *Kalman gain* - the ratio that chooses how far along the residual to select between the measurement and prediction in the graph above.\n",
      "\n",
      "We can think of the inverse of a matrix as linear algebra's way ofcomputing  $\\frac{1}{x}$. So we can read the equation for $\\textbf{K}$ as\n",
      "\n",
      "$$ \\textbf{K} = \\frac{\\textbf{P}\\textbf{H}^\\mathsf{T}}{\\mathbf{S}} $$\n",
      "\n",
      "\n",
      "$$\n",
      "\\textbf{K} = \\frac{uncertainty_{prediction}}{uncertainty_{measurement}}\\textbf{H}^\\mathsf{T}\n",
      "$$\n",
      "\n",
      "\n",
      "In other words, the *Kalman gain* equation is doing nothing more than computing a ratio based on how much we trust the prediction vs the measurement. If we are confident in our measurements and unconfident in our predictions $\\mathbf{K}$ will favor the measurement, and vice versa. The equation is complicated because we are doing this in multiple dimensions via matrices, but the concept is simple - scale by a ratio.\n",
      "\n",
      "Without going into the derivation of $\\mathbf{K}$, I'll say that this equation is the result of finding a value of $\\mathbf{K}$ that optimizes the *mean-square estimation error*. It does this by finding the minimal values for $\\mathbf{P}$ along its diagonal. Recall that the diagonal of $\\mathbf{P}$ is just the variance for each state variable. So, this equation for $\\mathbf{K}$ ensures that the Kalman filter output is optimal. To put this in concrete terms, for our dog tracking problem this means that the estimates for both position and velocity will be optimal - a value of $\\mathbf{K}$ that made the position extremely accurate but the velocity very inaccurate would be rejected in favor of a $\\mathbf{K}$ that made both position and velocity just somewhat accurate."
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Our next line is:\n",
      " $$\\mathbf{x}=\\mathbf{x}' +\\mathbf{Ky}\\tag{5}$$\n",
      "\n",
      "This just multiplies the residual by the Kalman gain, and adds it to the state variable. In other words, this is the computation of our new estimate.\n",
      "\n",
      "Finally, we have:\n",
      "\n",
      "$$\\mathbf{P}=(\\mathbf{I}-\\mathbf{KH})\\mathbf{P}\\tag{6}$$\n",
      "\n",
      "$I$ is the identity matrix, and is the way we represent $1$ in multiple dimensions. $H$ is our measurement function, and is a constant.  So, simplified, this is simply $P = (1-cK)P$. $K$ is our ratio of how much prediction vs measurement we use. So, if $K$ is large then $(1-cK)$ is small, and P will be made smaller than it was. If $K$ is small, then $(1-cK)$ is large, and P will be made larger than it was. So we adjust the size of our uncertainty by some factor of the *Kalman gain*. I would like to draw your attention back to the g-h filter, which included this Python code:\n",
      "\n",
      "    # update filter \n",
      "    w = w * (1-scale_factor) + z * scale_factor\n",
      "\n",
      "This multidimensional Kalman filter equation is partially implementing this calculation for the variance instead of the state variable."
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Now we have the measurement steps. The first equation is\n",
      "\n",
      "$$\\mathbf{x} = \\mathbf{Fx} + \\mathbf{Bu}\\tag{1}$$\n",
      "\n",
      "This is just our state transition equation which we have already discussed. $\\mathbf{Fx}$  multiplies $\\mathbf{x}$ with the state transition matrix to compute the next state. $B$ and $u$ add in the contribution of the control input $\\mathbf{u}$, if any.\n",
      "\n",
      "The final equation is:\n",
      "$$\\mathbf{P} = \\mathbf{FPF}^\\mathsf{T} + \\mathbf{Q}\\tag{2}$$\n",
      "\n",
      "$\\mathbf{FPF}^\\mathsf{T}$ is the way we put $\\mathbf{P}$ into the process space using linear algebra so that we can add in the process noise $\\mathbf{Q}$ to it."
     ]
    },
    {
     "cell_type": "heading",
     "level": 2,
     "metadata": {},
     "source": [
      "Design of the Process Noise Matrix"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "In general the design of the $\\mathbf{Q}$ matrix is among the most difficult aspects of Kalman filter design. This is due to several factors. First, the math itself is somewhat difficult and requires a good foundation in signal theory. Second, we are trying to model the noise in something for which we have little information. For example, consider trying to model the process noise for a baseball. We can model it as a sphere moving through the air, but that leave many unknown factors - the wind, ball rotation and spin decay, the coefficient of friction of a scuffed ball with stitches, the effects of wind and air density, and so on. I will develop the equations for an exact mathematical solution for a given process model, but since the process model is incomplete the result for $\\mathbf{Q}$ will also be incomplete. This has a lot of ramifications for the behavior of the Kalman filter. If $\\mathbf{Q}$ is too small than the filter will be overconfident in it's prediction model and will diverge from the actual solution. If $\\mathbf{Q}$ is too large than the filter will be unduly influenced by the noise in the measurements and perform suboptimally. In practice we spend a lot of time running simulations and evaluating collected data to try to select an appropriate value for $\\mathbf{Q}$. But let's start by looking at the math.\n",
      "\n",
      "\n",
      "Let's assume a kinematic system - some system that can be modelled using Newton's equations of motion. We can make a few different assumptions about this process. \n",
      "\n",
      "We have been using a process model of\n",
      "\n",
      "$$ f(\\mathbf{x}) = \\mathbf{Fx} + \\mathbf{w}$$\n",
      "\n",
      "where $\\mathbf{w}$ is the process noise. Kinematic systems are *continuous* - their inputs and outputs can vary at any arbitrary point in time. However, our Kalman filters are *discrete*. We sample the system at regular intervals. Therefore we must find the discrete representation for the noise term in the equation above. However, this depends on what assumptions we make about the behavior of the noise. We will consider two different models for the noise."
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "### Continuous White Noise Model\n",
      "\n",
      "We model kinematic systems using Newton's equations. So far in this book we have either used position and velocity, or position,velocity, and acceleration as the models for our systems. There is nothing stopping us from going further - we can model jerk, jounce, snap, and so on. We don't do that normally because adding terms beyond the dynamics of the real system actually degrades the solution. \n",
      "\n",
      "Let's say that we need to model the position, velocity, and acceleration. We can then assume that acceleration is constant. Of course, there is process noise in the system and so the acceleration is not actually constant. In this section we will assume that the acceleration changes by a continouus time zero-mean white noise $w(t)$. In other words, we are assuming that velocity is acceleration changing by small amounts that over time average to 0 (zero-mean). \n",
      "\n",
      "\n",
      "Since the noise is changing continuously we will need to integrate to get the discrete noise for the discretization interval that we have chosen. We will not prove it here, but the equation for discretizing the noise is\n",
      "\n",
      "$$\\mathbf{Q} = \\int_0^{\\Delta t} \\Phi(t)\\mathbf{Q_c}\\Phi^\\mathsf{T}(t) dt$$\n",
      "\n",
      "where $\\mathbf{Q_c}$ is the continuous noise. This gives us\n",
      "\n",
      "$$\\Phi = \\begin{bmatrix}1 & \\Delta t & {\\Delta t}^2/2 \\\\ 0 & 1 & \\Delta t\\\\ 0& 0& 1\\end{bmatrix}$$\n",
      "\n",
      "for the fundamental matrix, and\n",
      "\n",
      "$$\\mathbf{Q_c} = \\begin{bmatrix}0&0&0\\\\0&0&0\\\\0&0&1\\end{bmatrix} \\Phi_s$$\n",
      "\n",
      "for the continuous process noise matrix, where $\\Phi_s$ is the spectral density of the white noise.\n",
      "\n",
      "We could carry out these computations ourselves, but I prefer using SymPy to solve the equation."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "import sympy\n",
      "from sympy import  init_printing, Matrix,MatMul, integrate, symbols\n",
      "\n",
      "init_printing(use_latex='mathjax')\n",
      "dt, phi = symbols('\\Delta{t} \\Phi_s')\n",
      "F_k = Matrix([[1, dt, dt**2/2],\n",
      "              [0,  1,      dt],\n",
      "              [0,  0,       1]])\n",
      "Q_c = Matrix([[0,0,0],\n",
      "              [0,0,0],\n",
      "              [0,0,1]])*phi\n",
      "\n",
      "Q=sympy.integrate(F_k*Q_c*F_k.T,(dt, 0, dt))\n",
      "\n",
      "# factor phi out of the matrix to make it more readable\n",
      "Q = Q/phi\n",
      "sympy.MatMul(Q, phi)"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "latex": [
        "$$\\left[\\begin{matrix}\\frac{\\Delta{t}^{5}}{20} & \\frac{\\Delta{t}^{4}}{8} & \\frac{\\Delta{t}^{3}}{6}\\\\\\frac{\\Delta{t}^{4}}{8} & \\frac{\\Delta{t}^{3}}{3} & \\frac{\\Delta{t}^{2}}{2}\\\\\\frac{\\Delta{t}^{3}}{6} & \\frac{\\Delta{t}^{2}}{2} & \\Delta{t}\\end{matrix}\\right] \\Phi_{s}$$"
       ],
       "metadata": {},
       "output_type": "pyout",
       "prompt_number": 4,
       "text": [
        "\u23a1         5           4           3\u23a4       \n",
        "\u23a2\\Delta{t}   \\Delta{t}   \\Delta{t} \u23a5       \n",
        "\u23a2\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u23a5\u22c5\\Phi_s\n",
        "\u23a2    20          8           6     \u23a5       \n",
        "\u23a2                                  \u23a5       \n",
        "\u23a2         4           3           2\u23a5       \n",
        "\u23a2\\Delta{t}   \\Delta{t}   \\Delta{t} \u23a5       \n",
        "\u23a2\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u23a5       \n",
        "\u23a2    8           3           2     \u23a5       \n",
        "\u23a2                                  \u23a5       \n",
        "\u23a2         3           2            \u23a5       \n",
        "\u23a2\\Delta{t}   \\Delta{t}             \u23a5       \n",
        "\u23a2\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500  \\Delta{t} \u23a5       \n",
        "\u23a3    6           2                 \u23a6       "
       ]
      }
     ],
     "prompt_number": 4
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "For completeness, let us compute the equations for the 0th order and 1st order equations.\n"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "F_k = sympy.Matrix([[1]])\n",
      "Q_c = sympy.Matrix([[phi]])\n",
      "\n",
      "print('0th order discrete process noise')\n",
      "sympy.integrate(F_k*Q_c*F_k.T,(dt, 0, dt))"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "0th order discrete process noise\n"
       ]
      },
      {
       "latex": [
        "$$\\left[\\begin{matrix}\\Delta{t} \\Phi_{s}\\end{matrix}\\right]$$"
       ],
       "metadata": {},
       "output_type": "pyout",
       "prompt_number": 5,
       "text": [
        "[\\Delta{t}\u22c5\\Phi_s]"
       ]
      }
     ],
     "prompt_number": 5
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "F_k = sympy.Matrix([[1, dt],\n",
      "                    [0, 1]])\n",
      "Q_c = sympy.Matrix([[0,0],\n",
      "                    [0,1]])*phi\n",
      "\n",
      "Q = sympy.integrate(F_k*Q_c*F_k.T,(dt, 0, dt))\n",
      "\n",
      "print('1st order discrete process noise')\n",
      "# factor phi out of the matrix to make it more readable\n",
      "Q = Q/phi\n",
      "sympy.MatMul(Q, phi)"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "1st order discrete process noise\n"
       ]
      },
      {
       "latex": [
        "$$\\left[\\begin{matrix}\\frac{\\Delta{t}^{3}}{3} & \\frac{\\Delta{t}^{2}}{2}\\\\\\frac{\\Delta{t}^{2}}{2} & \\Delta{t}\\end{matrix}\\right] \\Phi_{s}$$"
       ],
       "metadata": {},
       "output_type": "pyout",
       "prompt_number": 6,
       "text": [
        "\u23a1         3           2\u23a4       \n",
        "\u23a2\\Delta{t}   \\Delta{t} \u23a5       \n",
        "\u23a2\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u23a5\u22c5\\Phi_s\n",
        "\u23a2    3           2     \u23a5       \n",
        "\u23a2                      \u23a5       \n",
        "\u23a2         2            \u23a5       \n",
        "\u23a2\\Delta{t}             \u23a5       \n",
        "\u23a2\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500  \\Delta{t} \u23a5       \n",
        "\u23a3    2                 \u23a6       "
       ]
      }
     ],
     "prompt_number": 6
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "### Piecewise White Noise Model\n",
      "\n",
      "Another model for the noise assumes that the that highest order term (say, acceleration) is constant for each time period, but differs for each time period, and each of these is uncorrelated between time periods. This is subtly different than the model above, where we assumed that the last term had a continuously varying noisy signal applied to it.  \n",
      "\n",
      "We will model this as\n",
      "\n",
      "$$f(x)=Fx+\\Gamma w$$\n",
      "\n",
      "where $\\Gamma$ is the *noise gain* of the system, and $w$ is the constant piecewise accleration (or velocity, or jerk, etc). \n",
      "\n",
      "\n",
      "Lets start with by looking a first order system. In this case we have the state transition function\n",
      "\n",
      "$$\\mathbf{F} = \\begin{bmatrix}1&\\Delta t \\\\ 0& 1\\end{bmatrix}$$\n",
      "\n",
      "In one time period, the change in velocity will be $w(t)\\Delta t$, and the change in position will be $w(t)\\Delta t^2/2$, giving us\n",
      "\n",
      "$$\\Gamma = \\begin{bmatrix}\\frac{1}{2}\\Delta t^2 \\\\ \\Delta t\\end{bmatrix}$$\n",
      "\n",
      "The covariance of the process noise is then\n",
      "\n",
      "$$Q = E[\\Gamma w(t) w(t) \\Gamma^\\mathsf{T}] = \\Gamma\\sigma^2_v\\Gamma^\\mathsf{T}$$.\n",
      "\n",
      "We can compute that with SymPy as follows"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "var=symbols('sigma^2_v')\n",
      "v = Matrix([[dt**2/2], [dt]])\n",
      "\n",
      "Q = v * var * v.T\n",
      "\n",
      "# factor variance out of the matrix to make it more readable\n",
      "Q = Q / var\n",
      "sympy.MatMul(Q, var)"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "latex": [
        "$$\\left[\\begin{matrix}\\frac{\\Delta{t}^{4}}{4} & \\frac{\\Delta{t}^{3}}{2}\\\\\\frac{\\Delta{t}^{3}}{2} & \\Delta{t}^{2}\\end{matrix}\\right] \\sigma^{2}_{v}$$"
       ],
       "metadata": {},
       "output_type": "pyout",
       "prompt_number": 7,
       "text": [
        "\u23a1         4           3\u23a4    \n",
        "\u23a2\\Delta{t}   \\Delta{t} \u23a5    \n",
        "\u23a2\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u23a5\u22c5\u03c3\u00b2\u1d65\n",
        "\u23a2    4           2     \u23a5    \n",
        "\u23a2                      \u23a5    \n",
        "\u23a2         3            \u23a5    \n",
        "\u23a2\\Delta{t}            2\u23a5    \n",
        "\u23a2\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500  \\Delta{t} \u23a5    \n",
        "\u23a3    2                 \u23a6    "
       ]
      }
     ],
     "prompt_number": 7
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "The second order system proceeds with the same math.\n",
      "\n",
      "\n",
      "$$\\mathbf{F} = \\begin{bmatrix}1 & \\Delta t & {\\Delta t}^2/2 \\\\ 0 & 1 & \\Delta t\\\\ 0& 0& 1\\end{bmatrix}$$\n",
      "\n",
      "Here we will assume that the white noise is a discrete time Wiener process. This gives us\n",
      "\n",
      "$$\\Gamma = \\begin{bmatrix}\\frac{1}{2}\\Delta t^2 \\\\ \\Delta t\\\\ 1\\end{bmatrix}$$\n",
      "\n",
      "There is no 'truth' to this model, it is just convienent and provides good results. For example, we could assume that the noise is applied to the jerk at the cost of a more complicated equation. \n",
      "\n",
      "The covariance of the process noise is then\n",
      "\n",
      "$$Q = E[\\Gamma w(t) w(t) \\Gamma^\\mathsf{T}] = \\Gamma\\sigma^2_v\\Gamma^\\mathsf{T}$$.\n",
      "\n",
      "We can compute that with SymPy as follows"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "var=symbols('sigma^2_v')\n",
      "v = Matrix([[dt**2/2], [dt], [1]])\n",
      "\n",
      "Q = v * var * v.T\n",
      "\n",
      "# factor variance out of the matrix to make it more readable\n",
      "Q = Q / var\n",
      "sympy.MatMul(Q, var)"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "latex": [
        "$$\\left[\\begin{matrix}\\frac{\\Delta{t}^{4}}{4} & \\frac{\\Delta{t}^{3}}{2} & \\frac{\\Delta{t}^{2}}{2}\\\\\\frac{\\Delta{t}^{3}}{2} & \\Delta{t}^{2} & \\Delta{t}\\\\\\frac{\\Delta{t}^{2}}{2} & \\Delta{t} & 1\\end{matrix}\\right] \\sigma^{2}_{v}$$"
       ],
       "metadata": {},
       "output_type": "pyout",
       "prompt_number": 8,
       "text": [
        "\u23a1         4           3           2\u23a4    \n",
        "\u23a2\\Delta{t}   \\Delta{t}   \\Delta{t} \u23a5    \n",
        "\u23a2\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u23a5\u22c5\u03c3\u00b2\u1d65\n",
        "\u23a2    4           2           2     \u23a5    \n",
        "\u23a2                                  \u23a5    \n",
        "\u23a2         3                        \u23a5    \n",
        "\u23a2\\Delta{t}            2            \u23a5    \n",
        "\u23a2\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500  \\Delta{t}   \\Delta{t} \u23a5    \n",
        "\u23a2    2                             \u23a5    \n",
        "\u23a2                                  \u23a5    \n",
        "\u23a2         2                        \u23a5    \n",
        "\u23a2\\Delta{t}                         \u23a5    \n",
        "\u23a2\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500  \\Delta{t}       1     \u23a5    \n",
        "\u23a3    2                             \u23a6    "
       ]
      }
     ],
     "prompt_number": 8
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "We cannot say that this model is more or less correct than the continuous model - both are approximations to what is happening to the actual object. Only experience and experiments can guide you to the appropriate model. In practice you will usually find that either model provides reasonable results, but typically one will perform better than the other.\n",
      "\n",
      "The advantage of the second model is that we can model the noise in terms of $\\sigma^2$ which we can describe in terms of the motion and the amount of error we expect. The first model requires us to specify the spectral density, which is not very intuitive, but it handles varying time samples much more easily since the noise is integrated across the time period. However, these are not fixed rules - use whichever model (or a model of your own devising) based on testing how the filter performs and/or your knowledge of the behavior of the physical model."
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "### Using FilterPy to Compute Q\n",
      "\n",
      "FilterPy offers several routines to compute the $\\mathbf{Q}$ matrix. The function `Q_continuous_white_noise()` computes $\\mathbf{Q}$ for a given value for $\\Delta t$ and the spectral density."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "import filterpy.common as common\n",
      "\n",
      "common.Q_continuous_white_noise(dim=2, dt=1, spectral_density=1)"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "metadata": {},
       "output_type": "pyout",
       "prompt_number": 9,
       "text": [
        "array([[ 0.33333333,  0.5       ],\n",
        "       [ 0.5       ,  1.        ]])"
       ]
      }
     ],
     "prompt_number": 9
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "common.Q_continuous_white_noise(dim=3, dt=1, spectral_density=1)"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "metadata": {},
       "output_type": "pyout",
       "prompt_number": 10,
       "text": [
        "array([[ 0.05      ,  0.125     ,  0.16666667],\n",
        "       [ 0.125     ,  0.33333333,  0.5       ],\n",
        "       [ 0.16666667,  0.5       ,  1.        ]])"
       ]
      }
     ],
     "prompt_number": 10
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "The function `Q_discrete_white_noise()` computes $\\mathbf{Q}$ assuming a piecewise model for the noise."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "common.Q_discrete_white_noise(2, var=1.)"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "metadata": {},
       "output_type": "pyout",
       "prompt_number": 11,
       "text": [
        "array([[ 0.25,  0.5 ],\n",
        "       [ 0.5 ,  1.  ]])"
       ]
      }
     ],
     "prompt_number": 11
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "common.Q_discrete_white_noise(3, var=1.)"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "metadata": {},
       "output_type": "pyout",
       "prompt_number": 12,
       "text": [
        "array([[ 0.25,  0.5 ,  0.5 ],\n",
        "       [ 0.5 ,  1.  ,  1.  ],\n",
        "       [ 0.5 ,  1.  ,  1.  ]])"
       ]
      }
     ],
     "prompt_number": 12
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "### Simplification of Q\n",
      "\n",
      "Through the early parts of this book I used a much simpler form for $\\mathbf{Q}$, often only putting a noise term in the lower rightmost element. Is this justified? Well, consider the value of $\\mathbf{Q}$ for a small $\\Delta t$"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "common.Q_continuous_white_noise(dim=3, dt=0.05, spectral_density=1)"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "metadata": {},
       "output_type": "pyout",
       "prompt_number": 13,
       "text": [
        "array([[  1.56250000e-08,   7.81250000e-07,   2.08333333e-05],\n",
        "       [  7.81250000e-07,   4.16666667e-05,   1.25000000e-03],\n",
        "       [  2.08333333e-05,   1.25000000e-03,   5.00000000e-02]])"
       ]
      }
     ],
     "prompt_number": 13
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "We can see that most of the terms are very small. Recall that the only Kalman filter using this matrix is\n",
      "\n",
      "$$ \\mathbf{P}=\\mathbf{FPF}^\\mathsf{T} + \\mathbf{Q}$$\n",
      "\n",
      "If the values for $\\mathbf{Q}$ are small relative to $\\mathbf{P}$\n",
      "than it will be contributing almost nothing to the computation of $\\mathbf{P}$. Setting $\\mathbf{Q}$ to \n",
      "\n",
      "$$Q=\\begin{bmatrix}0&0&0\\\\0&0&0\\\\0&0&\\sigma^2\\end{bmatrix}$$\n",
      "\n",
      "while not correct, is often a useful approximation. If you do this you will have to perform quite a few studies to guarantee that your filter works in a variety of situations. Given the availability of functions to compute the correct values of $\\mathbf{Q}$ for you I would strongly recommend not using approximations. Perhaps it is justified for quick-and-dirty filters, or on embedded devices where you need to wring out every last bit of performance, and seek to minimize the number of matrix operations required. "
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "\n",
      "** author's note: the following aside probably belongs elsewhere in the book**\n",
      "\n",
      "> As an aside, most textbooks are more exact with the notation, in Gelb[1] for example, *Pk(+)* is used to denote the uncertainty covariance for the prediction step, and *Pk(-)* for the uncertainty covariance for the update step. Other texts use subscripts with 'k|k-1', superscipt $^-$, and many other variations. As a programmer I find all of that fairly unreadable; I am used to thinking about variables changing state as a program runs, and do not use a different variable name for each new computation. There is no agreed upon format, so each author makes different choices. I find it challenging to switch quickly between books an papers, and so have adopted this admittedly less precise notation. Mathematicians will write scathing emails to me, but I hope the programmers and students will rejoice.\n",
      "\n",
      "> If you are a programmer trying to understand a paper's math equations, I strongly recommend just removing all of the superscripts, subscripts, and diacriticals, replacing them with a single letter. If you work with equations like this every day this is superflous advice, but when I read I am usually trying to understand the flow of computation. To me it is far more understandable to remember that $P$ in this step represents the updated value of $P$ computed in the last step, as opposed to trying to remember what $P_{k-1}(+)$ denotes, and what its relation to $P_k(-)$ is, if any.\n",
      "\n",
      "> For example, for the equation of $\\mathbf{S}$ above, Wikipedia uses\n",
      "\n",
      "> $$\\textbf{S}_k = \\textbf{H}_k \\textbf{P}_{k\\mid k-1} \\textbf{H}_k^\\mathsf{T} + \\textbf{R}_k\n",
      "$$\n",
      "\n",
      "> Is that more exact? Absolutely. Is it easier or harder to read? You'll need to answer that for yourself.\n",
      "\n",
      "> For reference, the Appendix **Symbols and Notations** lists the symbology used by the major authors in the field."
     ]
    },
    {
     "cell_type": "heading",
     "level": 2,
     "metadata": {},
     "source": [
      "References"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      " * [1] *Matrix Exponential* http://en.wikipedia.org/wiki/Matrix_exponential \n",
      "\n",
      " * [2] *LTI System Theory* http://en.wikipedia.org/wiki/LTI_system_theory\n",
      " \n",
      " * [3] C.F. van Loan, \"Computing Integrals Involving the Matrix Exponential,\" IEEE Transactions Automatic Control, June 1978."
     ]
    }
   ],
   "metadata": {}
  }
 ]
}