byu-magicc / lie_groups

Implementation-focused introduction to Lie groups for roboticists

Lie Groups

This repo houses an implementation-focused introduction to Lie Groups for roboticists. All material is written in Python and presented in Jupyter Notebook format.

For the best experience, start reading online with nbviewer or interacting with the code using binder by clicking the appropriate badge above. Alternatively, follow the Getting Started instructions below to run the notebook on your local machine.

Overview

The purpose of this repo is to present theory, tools, and examples of Lie groups and algebras for the practitioner working with the control, estimation, and optimization of rigid bodies.

To facilitate this, each chapter will present a section on using the group element to illustrate kinematics, solving differential equations, control, and estimation. We take the approach of starting with the unit circle (S^1) and working through more complicated spaces: SE(2), SO(3), SE(3), and SL(3).

Motivation

Many interesting problems in control and estimation exist which can be solved by using "hacks" like wrapping Euler angles, normalizing quaternions at every step, etc. Alternatively, Lie theory can be applied to implement algorithms that do their work on the manifold (i.e., the surface of all 3D rotation matrices, SO(3)).

In particular, vision-based control and estimation is an active research area that employs the use of Lie groups and Lie algebras to leverage computationally efficient representations of rigid body transformations. Many state of the art algorithms in visual-inertial odometry, SLAM, and robust control use these concepts.

Getting Started

To get started improving and learning with these notebooks, make sure you have Jupyter installed:

$ pip install jupyter --user

After cloning this repo and navigating into its directory on your machine, kick off the Jupyter notebook server with:

$ jupyter notebook

The server will start and a new browser tab will open.

For more information on Python/pip, see here.

You will also need ffmpeg installed to render matplotlib animations as inline videos. On Ubuntu, this is accomplished with

sudo apt install ffmpeg

For other operating systems, refer to the documentation here or here.

Handling Merge Conflicts: nbdime

Because Jupyter notebook are difficult to parse as raw text, the nbdime tool was created to help graphically manage merge conflicts. Install using pip with

$ pip install -U nbdime

and make sure to integrate with git using nbdime config-git --enable --global. This will allow git diff to use nbdime's command-line diff interface for any *.ipynb files. Alternatively, you can use nbdiff-web to compare Jupyter notebooks graphically.

See the nbdime docs to read more about git integration and using nbdime as the merge tool.

lie_groups's Issues

Reusable notebook code

Some notebooks are currently broken (e.g., 1.6-Estimation) because it needs the manifold PID controller code from 1.4-PID-Control. Chapter 1.5-Optimal-Control originally got around this issue by puling out the relevant code into a .py and then using the %load magic. This causes code duplication and noise.

The best solution I have found so far is to use the following magic:

%%capture
%run 1.4-PID-Control.ipynb

The %%capture magic must be at the top of the cell, and it squelches any output for the entire cell that it is in. The %run magic will run the specified notebook and put everything into the global namespace.

Now, the only problem with this approach is the time delay. This is because 1.4-PID-Control creates a number of embedded HTML5 videos. Obviously, those tasks don't need to be preformed when we are just trying to load classes/functions into another notebook.

To solve this, I'm thinking that some of the plotting be abstracted out into a .py file. Then, at the top of that file it can check if a variable, say, NO_OUTPUT is True. If it is, it doesn't run the simulation or create an HTML5 video.

Then, in notebooks that want to use 1.4-PID-Control, you would find this Python cell at the top:

%%capture
NO_OUTPUT=True
%run 1.4-PID-Control.ipynb

Need `environment.yml` or `requirements.txt` and `apt.txt`

There are some dependencies missing when you try to run the code in binder.

see http://mybinder.readthedocs.io/en/latest/using.html#preparing-a-repository-for-binder

If we add these dependencies, binder will go ahead and install them for us.

Short list of things we need (off the top of my head)

• numpy
• cvxpy
• ffmpeg

add more as you guys see fit.

@plusk01 @superjax

Split up Chapter 2

Right now, chapter 2 is becoming a bit of beast. I propose separating chapter 2 into several chapters:

1. SO(2) Notation and Kinetmatics
2. Gradient Descent on SO(2)
3. Differential Equation Solvers for SO(2)
4. PID Control on SO(2)
5. Optimal Control on SO(2)
6. State Estimation on SO(2)

@plusk01, @jerelbn, @randybeard, @dpkoch, What do you think?

Fix Preface

The 00-Preface.ipynb file looks like it is still just the copy from the Kalman and Bayesian Filters in Python repo.

1.5 Optimal Control - cvxpy error

@superjax I installed cvxpy (Python 3) and tried to run your notebook. I get the following error from cvxpy in the LMPC_Manifold class:

IndexError: Too many indices for expression.

Any ideas?