This repository contains the source for the interactive textbook Learn Multibody Dynamics <https://moorepants.github.io/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
When complete, the website is then viewable in your browser::
_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:
.. code:: rst
=======
Chapter
=======
Section
=======
Subsection
----------
Subsubsection
^^^^^^^^^^^^^
Autoreferencing is enabled so the above sections can be referenced with:
.. code:: rst
:ref:`Chapter`
:ref:`Section`
:ref:`Subsection`
:ref:`Subsubsection`
For equations and figures, they need to be manually labeled for numbered
referencing. Use these patterns:
.. code:: rst
.. 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:
.. code:: rst
([Kane1985_], pg. 23)
Cross-referencing API documentation in various libraries:
.. code:: rst
: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:
.. code:: rst
.. admonition:: Exercise
What is 1 + 1?
.. admonition:: Solution
:class: dropdown
The answer is 2.
Indentation:
- Python: 4 spaces
- RestructuredText: 3 spaces
- LaTeX: 2 spaces
.. code:: rst
.. 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:
.. code:: rst
.. 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:
.. code:: bash
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: https://github.com/executablebooks/sphinx-autobuild
.. code:: bash
sphinx-autobuild -b html . _build/html/
This is also encoded in the Makefile:
.. code:: bash
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:
.. code:: bash
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
+b % # side by side panes
+ # jump between panes
vim-slime
^^^^^^^^^
https://github.com/jpalardy/vim-slime
create a vim slime config file for rst
::
+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,,,g' _build/html/*.html
sed -i 's^^^g' _build/html/*.html
sed -i 's,,,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: https://github.com/pydy/pydy/pull/137