Merge branch 'ami-iit:main' into feature/coriolis

.github/workflows/ci_cd.yml

@@ -22,7 +22,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v4
         with:
-          python-version: "3.10"
+          python-version: "3.11"
 
       - name: Install Python tools
         run: pip install build twine
@@ -55,11 +55,10 @@ jobs:
         os:
           - ubuntu-22.04
           - macos-latest
-          # https://github.com/google/jax/issues/5795
-          # - windows-latest
+          - windows-latest
         python:
-          - "3.10"
           - "3.11"
+          - "3.12"
 
     steps:
 
@@ -74,19 +73,13 @@ jobs:
           path: dist
           name: dist
 
-      # Workaround: install iDynTree for Python 3.11
-      - name: iDynTree on Python 3.11
-        if: contains(matrix.os, 'ubuntu') && matrix.python == '3.11'
-        shell: bash
-        run: pip install --pre idyntree
-
       - name: Install wheel (ubuntu)
         if: contains(matrix.os, 'ubuntu')
         shell: bash
         run: pip install "$(find dist/ -type f -name '*.whl')[all]"
 
-      - name: Install wheel (macos)
-        if: contains(matrix.os, 'macos')
+      - name: Install wheel (macos|windows)
+        if: contains(matrix.os, 'macos') || contains(matrix.os, 'windows')
         shell: bash
         run: pip install "$(find dist/ -type f -name '*.whl')"
 
@@ -98,13 +91,13 @@ jobs:
           fetch-depth: 0
 
       - name: Install Gazebo Classic
-        if: contains(matrix.os, 'ubuntu') && (matrix.python == '3.10' || matrix.python == '3.11')
+        if: contains(matrix.os, 'ubuntu')
         run: |
           sudo apt-get update
           sudo apt-get install gazebo
 
       - name: Run the Python tests
-        if: contains(matrix.os, 'ubuntu') && (matrix.python == '3.10' || matrix.python == '3.11')
+        if: contains(matrix.os, 'ubuntu')
         run: pytest
         env:
           JAX_PLATFORM_NAME: cpu

.github/workflows/read_the_docs.yml

@@ -0,0 +1,17 @@
+name: Read the Docs PR
+on:
+  pull_request_target:
+    types:
+      - opened
+
+permissions:
+  pull-requests: write
+
+jobs:
+
+  documentation-links:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: readthedocs/actions/preview@v1
+        with:
+          project-slug: "jaxsim"

.gitignore

@@ -133,3 +133,6 @@ dmypy.json
 
 # Pyre type checker
 .pyre/
+
+# setuptools_scm dynamic version
+src/jaxsim/_version.py

.readthedocs.yaml

@@ -0,0 +1,19 @@
+version: "2"
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "mambaforge-22.9"
+
+conda:
+  environment: docs/jaxsim_conda_env.yml
+
+python:
+  install:
+    - method: pip
+      path: .
+
+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 [jaxsim.readthedocs.io](https://jaxsim.readthedocs.io/).
+
 ## Installation
 
 You can install the project with [`pypa/pip`][pip], preferably in a [virtual environment][venv]:
@@ -46,6 +50,10 @@ Install all of them with `jaxsim[all]`.
 [venv]: https://docs.python.org/3/tutorial/venv.html
 [jax_gpu]: https://github.com/google/jax/#installation
 
+## Quickstart
+
+Explore and learn how to use the library through practical demonstrations available in the [examples](./examples) folder.
+
 ## Credits
 
 The physics module of JAXsim is based on the theory of the [Rigid Body Dynamics Algorithms][RBDA]
@@ -66,7 +74,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
+
+from pkg_resources import get_distribution
+
+# -- 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__ = get_distribution("jaxsim").version
+
+# -- 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