Underactuated Robotics

Algorithms for Walking, Running, Swimming, Flying, and Manipulation

Russ Tedrake

© Russ Tedrake, 2020
How to cite these notes   |   Send me your feedback

Note: These are working notes used for a course being taught at MIT. They will be updated throughout the Spring 2020 semester. Lecture videos are available on YouTube.

Previous Chapter Table of contents Next Chapter

Drake

is the main software toolbox that we use for this text, which in fact originated in a large part due to the MIT underactuated course. The website is the main source for information and documentation. The goal of this chapter is to provide any additional information that can help you get up and running with the examples and exercises provided in these notes.

Pydrake

is primarily a C++ library, with rigorous coding standards and a maturity level intended to support even professional applications in industry. In order to provide a gentler introduction, and to facilitate rapid prototyping, I've written these notes exclusively in python, using Drake's python bindings (pydrake). These bindings are less mature than the C++ backend; your feedback (and even contributions) are very welcome. It is still improving rapidly.

In particular, while the C++ API documentation is excellent, the autogenerated python docs are still a work in progress. I currently recommend using the C++ documentation to find what you need, then checking the Python documentation only if you need to understand how the class or method is spelled in pydrake.

There are also a number of tutorials in that can help you get started.

Online Jupyter Notebooks

I will provide nearly all examples and exercises in the form of a Jupyter Notebook so that we can leverage the fantastic and relatively recent availability of (free) cloud resources. There are a number of examples throughout the text (listed below) which will help you load the notebooks in the cloud, allowing you to do some sophisticated computation without installing anything on your machine! Links to the code will look like this:

examples/double_pendulum/dynamics.ipynb

You'll notice that we often provide links to both Google's Colaboratory and Binder, because they both have some advantages and disadvantages.

Google's Colaboratory is a fantastic resource, with generous computational resources and a very convenient interface that allows you to save/load your work on Google Drive. At present, there are two major downsides to Colab:

  1. It does not support interactive plots (specifically the matplotlib notebook backend). For interactive graphics, we have to record an animation, and convert it to an html compatible format. But the time/memory that these operations require often exceeds the actual simulation time and make the experience significantly less interactive.
  2. We cannot provision the machines ahead of time. We have a slightly ugly install script at the top of every notebook, and the first time you open each notebook it takes about two minutes to provision the machine. At the time of this writing, it seems that the machine will stay provisioned for you for 90 minutes if you close the browser, or 12 hours if you keep it open. Provisioning is per user and appears relatively unlimited.

Binder is another great resource, which we can configure to provision directly from a Docker instance. It appears to provision itself by project -- once one of us starts a Binder instance for an example, it should load more quickly for the rest of us. It does support the matplotlib notebook backend, so can provide a nicer user experience. But Binder has some potentially painful limitations -- it seems that all modifications to your notebook are lost after 10 minutes of inactivity, and there is a limit on the number of simultaneous users.

As a general rule, I would favor Binder for quick explorations and use it for many of the examples in the notes, but recommend Colab (or running on your own machine) if you intend to build on any of the examples or do any of the exercises. Please use Colab if you are taking the course and planning to submit your assignment for credit. For some examples, where I think the code runs only (or simply much better) on some platforms than others, I have removed the less appealing link(s).

Running on your own machine

As you get more advanced, you will want to run (and extend) these examples on your own machine. The website has a number of installation options, including precompiled binaries and Docker instances. Here I provide an example workflow of setting up drake from the precompiled binaries and running the textbook examples.

First, pick your platform (click on your OS):

Ubuntu Linux (Bionic) | Mac Homebrew Ubuntu Linux (Bionic) | Mac Homebrew

Install Drake

The links below indicate the specific distributions that the examples in this text have been tested against.

Download the binaries

curl -o drake.tar.gz 
https://drake-packages.csail.mit.edu/drake/nightly/drake-latest-bionic.tar.gz
curl -o drake.tar.gz 
https://drake-packages.csail.mit.edu/drake/nightly/drake-latest-mac.tar.gz

Unpack and set your PYTHONPATH and Test

sudo tar -xvzf drake.tar.gz -C /opt
sudo /opt/drake/share/drake/setup/install_prereqs
export PYTHONPATH=/opt/drake/lib/python3.6/site-packages:${PYTHONPATH}

python3 -c 'import pydrake; print(pydrake.__file__)
sudo tar -xvzf drake.tar.gz -C /opt
/opt/drake/share/drake/setup/install_prereqs
export PYTHONPATH=/opt/drake/lib/python3.8/site-packages:${PYTHONPATH}
export PATH=/usr/local/opt/python@3.8/bin:${PATH}

python3 -c 'import pydrake; print(pydrake.__file__)

Download the textbook supplement

git clone https://github.com/RussTedrake/underactuated.git

and install the prerequisites using the platform-specific installation script provided:

sudo underactuated/scripts/setup/ubuntu/18.04/install_prereqs
export PYTHONPATH=`pwd`/underactuated:${PYTHONPATH}
underactuated/scripts/setup/mac/install_prereqs
export PYTHONPATH=`pwd`/underactuated:${PYTHONPATH}

Run Jupyter Notebook

cd underactuated
jupyter notebook

You will find the examples in the examples subdirectory, and the notebook exercises in the exercises subdirectory. You might try opening examples/double_pendulum/dynamics.ipynb to get started. Have fun!

Getting help

If you have trouble with , please follow the advice here. If you have trouble with the underactuated repo, you can check for known issues (and potentially file a new one) here.

Previous Chapter Table of contents Next Chapter