Merge pull request #61 from flferretti/feature/docs

Add `readthedocs` based documentation for the JAXsim API

.readthedocs.yaml

@@ -0,0 +1,14 @@
+version: "2"
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "mambaforge-22.9"
+
+conda:
+  environment: docs/jaxsim_conda_env.yml
+
+sphinx:
+  configuration: docs/conf.py
+
+formats: all

README.md

@@ -21,14 +21,18 @@
 - Revolute, prismatic, and fixed joints support.
 - Integrators: forward Euler, semi-implicit Euler, Runge-Kutta 4.
 - High-level classes for object-oriented programming.
-- High-level classes to compute multi-body dynamics quantities from simulation state.
+- High-level classes to compute multi-body dynamics quantities from the simulation state.
 - High-level classes wrapping the low-level functional RBDAs with support of [multiple velocities representations][notation].
 - Default validation of JAX pytrees to prevent JIT re-compilations.
 - Preliminary support for automatic differentiation of RBDAs.
 
 [jax]: https://github.com/google/jax/
 [notation]: https://research.tue.nl/en/publications/multibody-dynamics-notation-version-2
 
+## Documentation
+
+The JAXsim API documentation is available at [kaxsim.readthedocs.io](https://jaxsim.readthedocs.io/).
+
 ## Installation
 
 You can install the project with [`pypa/pip`][pip], preferably in a [virtual environment][venv]:
@@ -66,7 +70,7 @@ Here below we summarize the differences between the projects:
 - JAXsim supports SDF (and, indirectly, URDF) models, assuming the model is described with the
   recent [Pose Frame Semantics][PFS].
 - Contrarily to brax, JAXsim only supports collision detection between bodies and a compliant ground surface.
-- The RBDAs of JAXsim support automatic differentiation, but this functionality has not being thoroughly tested.
+- The RBDAs of JAXsim support automatic differentiation, but this functionality has not been thoroughly tested.
 
 [brax]: https://github.com/google/brax
 [mjx]: https://mujoco.readthedocs.io/en/3.0.0/mjx.html

docs/Makefile

@@ -0,0 +1,16 @@
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+SPHINXPROJ    = JAXsim
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/conf.py

@@ -0,0 +1,63 @@
+# Configuration file for the Sphinx documentation builder.
+import os
+import pathlib
+import sys
+
+# -- Version information
+
+sys.path.insert(0, os.path.abspath("."))
+sys.path.insert(0, os.path.abspath("../"))
+sys.path.insert(0, os.path.abspath("../../"))
+
+module_path = os.path.abspath("../src/")
+sys.path.insert(0, module_path)
+version_file = os.path.abspath("../src/jaxsim/version.txt")
+
+with open(version_file) as file_handler:
+    __version__ = file_handler.read().strip()
+
+# -- Project information
+
+project = "JAXsim"
+copyright = "2022, Artificial and Mechanical Intelligence"
+author = "Artificial and Mechanical Intelligence"
+
+release = f"{__version__}"
+version = f"main ({__version__})"
+
+# -- General configuration
+
+extensions = [
+    "sphinx.ext.duration",
+    "sphinx.ext.doctest",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.mathjax",
+    "sphinx.ext.ifconfig",
+    "sphinx.ext.viewcode",
+    "sphinx_rtd_theme",
+    "sphinx.ext.napoleon",
+    "sphinx_autodoc_typehints",
+    "sphinx_multiversion",
+]
+
+# -- Options for intersphinx extension
+
+language = "en"
+
+templates_path = ["_templates"]
+
+master_doc = "index"
+
+exclude_patterns = ["_build"]
+
+autodoc_typehints = "signature"
+
+# -- Options for HTML output
+
+html_theme = "sphinx_rtd_theme"
+
+# -- Options for EPUB output
+
+epub_show_urls = "footnote"

docs/guide/install.rst

@@ -0,0 +1,29 @@
+Installation
+============
+
+.. _installation:
+
+Prerequisites
+-------------
+
+JAXsim requires Python 3.10 or later. 
+
+Basic Installation
+------------------
+
+You can install the project with `pypa/pip`, preferably in a `virtual environment`_:
+
+.. code-block:: bash
+
+   pip install jaxsim
+
+Have a look to `setup.cfg` for a complete list of optional dependencies.
+You can install all of them by specifying ``jaxsim[all]``.
+
+.. note::
+
+    If you need GPU support, please follow the official `installation instruction`_ of JAX.
+
+.. _pypa/pip: https://github.com/pypa/pip/
+.. _virtual environment: https://docs.python.org/3.8/tutorial/venv.html
+.. _installation instruction: https://github.com/google/jax/#installation

docs/index.rst

@@ -0,0 +1,108 @@
+JAXsim
+#######
+
+A scalable physics engine and multibody dynamics library implemented with JAX. With JIT batteries 🔋
+
+.. warning::
+    This project is still experimental, APIs could change without notice.
+
+.. note::
+    This simulator currently focuses on locomotion applications. Only contacts with ground are supported.
+
+Features
+--------
+
+- Physics engine in reduced coordinates implemented with `JAX <https://github.com/google/jax/>`_ in Python.
+- JIT compilation of Python code for increased performance.
+- Transparent support to execute logic on CPUs, GPUs, and TPUs.
+- Parallel multi-body simulations on hardware accelerators for significantly increased throughput.
+- Support for SDF models (and, upon conversion, URDF models).
+- Collision detection between bodies and uneven ground surface.
+- Soft contacts model supporting full friction cone and sticking / slipping transition.
+- Complete support for inertial properties of rigid bodies.
+- Revolute, prismatic, and fixed joints support.
+- Integrators: forward Euler, semi-implicit Euler, Runge-Kutta 4.
+- High-level classes for object-oriented programming.
+- High-level classes to compute multi-body dynamics quantities from simulation state.
+- High-level classes wrapping the low-level functional RBDAs with support of `multiple velocities representations <https://research.tue.nl/en/publications/multibody-dynamics-notation-version-2>`_.
+- Default validation of JAX pytrees to prevent JIT re-compilations.
+- Preliminary support for automatic differentiation of RBDAs.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: User Guide
+
+   guide/install
+
+.. toctree::
+   :maxdepth: 2
+   :caption: JAXsim API
+
+   modules/typing
+   modules/high_level
+   modules/math
+   modules/physics
+   modules/parsers
+   modules/simulation
+   modules/utils
+
+
+Examples
+--------
+
+Explore and learn how to use the library through practical demonstrations available in the `examples <https://github.com/ami-iit/jaxsim/tree/main/examples>`__ folder.
+
+Credits
+-------
+
+The physics module of JAXsim is based on the theory of the `Rigid Body Dynamics Algorithms <https://link.springer.com/book/10.1007/978-1-4899-7560-7>`_ book by Roy Featherstone.
+We structured part of our logic following its accompanying `code <http://royfeatherstone.org/spatial/index.html#spatial-software>`_.
+The physics engine is developed entirely in Python using `JAX <https://github.com/google/jax/>`_.
+
+The inspiration for developing JAXsim originally stemmed from early versions of `google/brax <https://github.com/google/brax>`_.
+Here below we summarize the differences between the projects:
+
+- JAXsim simulates multibody dynamics in reduced coordinates, while brax v1 uses maximal coordinates.
+- The new v2 APIs of brax (and the new `MJX <https://mujoco.readthedocs.io/en/3.0.0/mjx.html>`_) were then implemented in reduced coordinates, following an approach comparable to JAXsim, with major differences in contact handling.
+- The rigid-body algorithms used in JAXsim allow to efficiently compute quantities based on the Euler-Poincarè
+  formulation of the equations of motion, necessary for model-based robotics research.
+- JAXsim supports SDF (and, indirectly, URDF) models, assuming the model is described with the
+  recent `Pose Frame Semantics <http://sdformat.org/tutorials?tut=pose_frame_semantics>`_.
+- Contrarily to brax, JAXsim only supports collision detection between bodies and a compliant ground surface.
+- The RBDAs of JAXsim support automatic differentiation, but this functionality has not been thoroughly tested.
+
+Contributing
+------------
+
+Pull requests are welcome. 
+For major changes, please open an issue first to discuss what you would like to change.
+
+Citing
+------
+
+.. code-block:: bibtex
+
+    @software{ferigo_jaxsim_2022,
+      author = {Diego Ferigo and Silvio Traversaro and Daniele Pucci},
+      title = {{JAXsim}: A Physics Engine in Reduced Coordinates and Multibody Dynamics Library for Control and Robot Learning},
+      url = {http://github.com/ami-iit/jaxsim},
+      year = {2022},
+    }
+
+People
+------
+
+Author and Maintainer
+'''''''''''''''''''''
+
+`Diego Ferigo <https://github.com/diegoferigo>`_
+
+Maintainer
+''''''''''
+
+`Filippo Luca Ferretti <https://github.com/flferretti>`_
+
+License
+-------
+
+`BSD3 <https://choosealicense.com/licenses/bsd-3-clause/>`_

docs/jaxsim_conda_env.yml

@@ -0,0 +1,21 @@
+name: jaxsim
+channels:
+  - conda-forge
+dependencies:
+  - coloredlogs
+  - python=3.11
+  - jax
+  - jax-dataclasses
+  - jaxlib
+  - jaxlie
+  - jinja2
+  - rod
+  - coloredlogs
+  - sphinx
+  - sphinx-autodoc-typehints
+  - sphinx-copybutton
+  - sphinx_fontawesome
+  - sphinx-multiversion
+  - sphinx_rtd_theme
+  - pip
+  - pptree

docs/make.bat

@@ -0,0 +1,36 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+set SPHINXPROJ=JaxSim
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/modules/high_level.rst

@@ -0,0 +1,17 @@
+.. _high_level:
+
+
+High Level 
+==========
+
+.. autoclass:: jaxsim.high_level.model.Model
+    :members:
+    :inherited-members:
+
+.. autoclass:: jaxsim.high_level.joint.Joint
+    :members:
+    :inherited-members:
+
+.. autoclass:: jaxsim.high_level.link.Link
+    :members:
+    :inherited-members:

docs/modules/math.rst

@@ -0,0 +1,41 @@
+.. _math:
+
+
+Math 
+====
+
+.. automodule:: jaxsim.math.adjoint
+    :members:
+    :inherited-members:
+
+.. automodule:: jaxsim.math.conv
+    :members:
+    :inherited-members:
+
+.. automodule:: jaxsim.math.cross
+    :members:
+    :inherited-members:
+
+.. automodule:: jaxsim.math.inertia
+    :members:
+    :inherited-members:
+
+.. automodule:: jaxsim.math.joint
+    :members:
+    :inherited-members:
+
+.. automodule:: jaxsim.math.plucker
+    :members:
+    :inherited-members:
+
+.. automodule:: jaxsim.math.quaternion
+    :members:
+    :inherited-members:
+
+.. automodule:: jaxsim.math.rotation
+    :members:
+    :inherited-members:
+
+.. automodule:: jaxsim.math.skew
+    :members:
+    :inherited-members: