Interactive computational book on multibody dynamics
OTHER License
This repository contains the source for the interactive textbook Learn Multibody Dynamics <https://moorepants.github.io/learn-multibody-dynamics/>
_.
Author: Jason K. Moore
Co-Authors: Wouter Wolfslag
Contributors: Peter Stahlecker, Jan Heinen, @tamoora, Christopher Dembia, Arthur Ryman
The contents of this repository are licensed under the CC-BY 4.0 license. See
license.rst
for more information.
The design of the book has these general goals:
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
.. _miniconda: https://docs.conda.io/en/latest/miniconda.html .. _Anaconda: https://www.anaconda.com/products/individual
Activate the conda environment::
conda activate multibody-book
To build the website run::
make html
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
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
The text is written in reStructuredText and processed with Sphinx. The Sphinx reStructuredText documentation page <https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>
_ 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
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::
🏷️ 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:
.. code:: rst
.. math::
\begin{bmatrix}
a & b
\end{bmatrix}
.. juputer-execute::
def f(a):
return a
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`.
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
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.
tmux ^^^^
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
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).
Here are links to various resources that use SymPy for dynamics that could be incorporated into this repository, as is or as inspiration: