This repository contains the source for the website Learn Multibody Dynamics.
The contents of this repository are licensed under the CC-BY 4.0 license. See
license.rst
for more information.
Clone the repository:
git clone https://github.com/moorepants/learn-multibody-dynamics.git cd learn-multibody-dynamics
Install miniconda or 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
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
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 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:
: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`
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
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
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
https://medium.com/hackernoon/a-gentle-introduction-to-tmux-8d784c404340
tmux new <Ctrl>+b % # side by side panes <Ctrl>+<arrow key> # jump between panes
https://github.com/jpalardy/vim-slime
create a vim slime config file for rst
<Ctrl>+cc # execute line(s) in ipython pane
Here are links to various resources of open dynamics with SymP materials:
- my mae223 notebooks: https://moorepants.github.io/mae223/schedule.html
- pydy tutorial: https://github.com/pydy/pydy-tutorial-human-standing
- pydy docs examples: https://pydy.readthedocs.io/en/latest/index.html#examples
- pydy examples: https://github.com/pydy/pydy/tree/master/examples
- sympy mechanics docs: 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
- homework notebooks from Arend's class
- Oliver's solutions to the TUD advanced dynamics course examples: pydy/pydy#137
- Maybe some problems from EME171: https://moorepants.github.io/eme171/resources.html
- Problems from EME 134: https://moorepants.github.io/eme134/labs.html