README

This repository contains the source for the interactive textbook Learn Multibody Dynamics.

Authors and Contributors

Author: Jason K. Moore

Co-Authors: Wouter Wolfslag

Contributors: Peter Stahlecker, Jan Heinen, @tamoora, Christopher Dembia, Arthur Ryman

License

The contents of this repository are licensed under the CC-BY 4.0 license. See license.rst for more information.

Design

The design of the book has these general goals:

• use computational thinking to teach multibody dynamics
• the book is online and interactive (run/modify code, interact with figures)
• don't just teach the math and expect the students to figure out the computation on their own, the computations should be first class and could even go as far as replacing the math as the teach mechanism
• computational difficulties should not be hidden and should be taught
• after completing the book, you should be able to create a physics engine if you desired
• most lessons should be motivated by a real problem statement, instead of teaching the concepts with little connection to reality or strictly from a mathematical sense
• allow collaborative contributions

Building the Website

Setup the code and environment

Clone the repository:

git clone https://github.com/moorepants/learn-multibody-dynamics.git
cd learn-multibody-dynamics

Install miniconda or a similar tool (e.g. Anaconda) and create a conda environment for the book:

conda env create -f multibody-book-env.yml

Activate the conda environment:

conda activate multibody-book

Build and view the website

To build the website run:

make html

When complete, the website is then viewable in your browser:

<yourbrowser> _build/html/index.html

You can also run sphinx-autobuild (updates while while you edit) with:

make autobuild

Working with a remote git branch

If you want to build one of the branches (for example a pull request), you'll need to fetch and checkout the branch. First fetch down all the branches:

git fetch origin

Then checkout the branch (this command is only need the first time you check it out):

git checkout -b branch-name origin/branch-name

The branch name is listed on the pull request just under the title "...wants to merge X commits into master from branch-name." Or you can find all branches here: https://github.com/moorepants/learn-multibody-dynamics/branches

Now run:

make clean
make html

The make clean makes sure you don't keep any remnants from prior builds around before building the new branch.

After you have a new branch setup you can switch between the master branch and any branch name with just:

git checkout master
git checkout branch-name

If the master branch or any other branch has been updated on github you can pull down the latest changes with:

git checkout branch-name
git pull origin branch-name

Editing Guide

restructuredtext

The text is written in reStructuredText and processed with Sphinx. The Sphinx reStructuredText documentation page is a good starting point to learn the syntax.

reStructuredText doesn't enforce a specific heading order, but this should be followed for this text:

=======
Chapter
=======

Section
=======

Subsection
----------

Subsubsection
^^^^^^^^^^^^^

Autoreferencing is enabled so the above sections can be referenced with:

:ref:`Chapter`
:ref:`Section`
:ref:`Subsection`
:ref:`Subsubsection`

For equations and figures, they need to be manually labeled for numbered referencing. Use these patterns:

.. math::
   :label: eq-my-equation-name
:math:numref:`eq-my-equation-name`

.. _fig-my-figure-name:
:numref:`fig-my-figure-name`

When citing Kane & Levinson 1985 or other books include the page number:

([Kane1985_], pg. 23)

Cross-referencing API documentation in various libraries:

:external:py:meth:`~sympy.physics.vector.frame.ReferenceFrame.ang_acc_in`
:external:py:class:`~sympy.physics.vector.frame.ReferenceFrame`
:external:py:func:`~sympy.physics.vector.functions.cross`

Exercises look like this:

.. admonition:: Exercise

   What is 1 + 1?

.. admonition:: Solution
   :class: dropdown

   The answer is 2.

Indentation:

• Python: 4 spaces
• RestructuredText: 3 spaces
• LaTeX: 2 spaces

.. math::

   \begin{bmatrix}
     a & b
   \end{bmatrix}

.. juputer-execute::

   def f(a):
       return a

jupyer-sphinx

We use jupyter-sphinx to transform each page with code cells into a Jupyter Notebook and Python script. Any page that includes .. jupyter-execute:: directives will be processed in this way. The documentation for jupyter-sphinx is here:

https://jupyter-sphinx.readthedocs.io

Each page that has executable code should include these download links at the top of the page. If the filename is page.rst then include:

.. note::

   You can download this example as a Python script:
   :jupyter-download-script:`page` or Jupyter Notebook:
   :jupyter-download-notebook:`page`.

Xournal++

I draw the figures, one per page, in Xournal++. The I export as -> svg -> choose None for background and "current page" to get a single exported svg.

The SVG figures should be cropped to the bounding box of the drawn elements. One can do so using Inkscape with these button presses: File -> Document Properties -> Resize Page to Content. With Inkscape > 1.0 this command will crop the figure:

inkscape --export-type=svg --export-area-drawing ./my-figure.svg

Live rebuilding with sphinx-autobuild

Sphinx autobuild is a pretty good way to get almost instaneous rendered HTML versions of the reStructuredText file. You can open a window with your text editor and a window with your broswer side-by-side for almost instant feedback on the formatting and Jupyter code execution.

sphinx-autobuild -b html . _build/html/

This is also encoded in the Makefile:

make autobuild

If errors occur in jupyter-sphinx cells while editing this will always cause the entire book to be rebuilt, i.e. it wipes the sphinx cache. If you set an environment variable CHAPTER to the name of chapter's filename (without the .rst extension) only the chapter you are working on will be built. For example:

CHAPTER=configuration make autobuild

will only build the configuration.rst chapter.

Execute code cells in IPython while writing

tmux

https://tmuxcheatsheet.com/

https://medium.com/hackernoon/a-gentle-introduction-to-tmux-8d784c404340

tmux new
<Ctrl>+b %  # side by side panes
<Ctrl>+<arrow key>  # jump between panes

vim-slime

https://github.com/jpalardy/vim-slime

create a vim slime config file for rst

<Ctrl>+cc  # execute line(s) in ipython pane

Prepare Offline Version

Created a directory for MathJax v2:

mkdir -p _static/js/
cd _static/js/
wget https://github.com/mathjax/MathJax/archive/refs/tags/2.7.9.zip
unzip 2.7.9.zip
mv MathJax-2.7.9/ MathJax/
rm 2.7.9.zip

Download this JavaScript file also:

wget https://cdn.jsdelivr.net/npm/@jupyter-widgets/html-manager@^1.0.1/dist/embed-amd.js
cd ../..

In conf.py change these two lines:

todo_include_todos = False

mathjax_path = "js/MathJax/MathJax.js?config=TeX-AMS-MML_HTMLorMML"

Now, build the HTML version:

make clean
make html

Make sure embed-amd.js loads from the local source with:

sed -i "s,https://cdn.jsdelivr.net/npm/@jupyter-widgets/html-manager@^1.0.1/dist,_static/js,g" _build/html/*.html

Remove links to external resources (slows loading on offline computers):

sed -i 's,<link href="https://fonts.gstatic.com/" rel="preconnect" crossorigin>,,g' _build/html/*.html
sed -i 's^<link href="https://fonts.googleapis.com/css?family=Roboto+Mono:400,500,700|Roboto:300,400,400i,700&display=fallback" rel="stylesheet">^^g' _build/html/*.html
sed -i 's,<script src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.4/require.min.js"></script>,,g' _build/html/*.html

Now build the PDF version:

make latexpdf

Create a folder to zip up the book:

mkdir -p misc/book/

Copy over the files:

cp -r _build/html/* misc/book/
cp _build/latex/learnmultibodydynamics.pdf misc/

Zip the book:

cd misc/
zip -r me41056-book-20XX.zip book/ learnmultibodydynamics.pdf

This version should work offline (except for externally loaded videos and images).

Content Resources

Here are links to various resources that use SymPy for dynamics that could be incorporated into this repository, as is or as inspiration:

• UC Davis MAE223 notebooks: https://moorepants.github.io/mae223/schedule.html
• PyDy tutorial: https://github.com/pydy/pydy-tutorial-human-standing
• PyDy documentation examples: https://pydy.readthedocs.io/en/latest/index.html#examples
• PyDy source examples: https://github.com/pydy/pydy/tree/master/examples
• SymPy Mechanics documentation: https://docs.sympy.org/dev/modules/physics/mechanics/index.html
• Resonance notebooks: https://moorepants.github.io/resonance/
• Yeadon example: https://nbviewer.jupyter.org/github/chrisdembia/yeadon/blob/v1.2.1/examples/bicyclerider/bicycle_example.ipynb
• Problems from EME 134: https://moorepants.github.io/eme134/labs.html
• TU Delft MAE41055 2021 homework notebooks
• Oliver's solutions to the TUD advanced dynamics course examples: pydy/pydy#137