First JAXsim version

.github/workflows/style.yml

@@ -0,0 +1,50 @@
+name: Code Style
+
+on:
+  push:
+    branches: [ "**" ]
+    tags-ignore: [ "**" ]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+
+  black:
+
+    name: black
+    runs-on: ubuntu-latest
+
+    steps:
+
+      - name: "🔀 Checkout repository"
+        uses: actions/checkout@v2
+
+      - name: '🐍 Initialize Python'
+        uses: actions/setup-python@v2
+        with:
+          python-version: "3.8"
+
+      - name: "📝 Black Code Formatter"
+        uses: psf/black@stable
+        with:
+          options: --check --diff --color
+
+  isort:
+
+    name: isort
+    runs-on: ubuntu-latest
+
+    steps:
+
+      - name: "🔀 Checkout repository"
+        uses: actions/checkout@v2
+
+      - name: '🐍 Initialize Python'
+        uses: actions/setup-python@v2
+        with:
+          python-version: "3.8"
+
+      - name: "📝 isort"
+        uses: isort/isort-action@master
+        with:
+          configuration: --check --diff --color

.gitignore

@@ -1,3 +1,9 @@
+# IDEs
+.idea*
+
+# Matlab
+*.m~
+
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]

LICENSE

@@ -1,165 +1,29 @@
-                   GNU LESSER GENERAL PUBLIC LICENSE
-                       Version 3, 29 June 2007
-
- Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
- Everyone is permitted to copy and distribute verbatim copies
- of this license document, but changing it is not allowed.
-
-
-  This version of the GNU Lesser General Public License incorporates
-the terms and conditions of version 3 of the GNU General Public
-License, supplemented by the additional permissions listed below.
-
-  0. Additional Definitions.
-
-  As used herein, "this License" refers to version 3 of the GNU Lesser
-General Public License, and the "GNU GPL" refers to version 3 of the GNU
-General Public License.
-
-  "The Library" refers to a covered work governed by this License,
-other than an Application or a Combined Work as defined below.
-
-  An "Application" is any work that makes use of an interface provided
-by the Library, but which is not otherwise based on the Library.
-Defining a subclass of a class defined by the Library is deemed a mode
-of using an interface provided by the Library.
-
-  A "Combined Work" is a work produced by combining or linking an
-Application with the Library.  The particular version of the Library
-with which the Combined Work was made is also called the "Linked
-Version".
-
-  The "Minimal Corresponding Source" for a Combined Work means the
-Corresponding Source for the Combined Work, excluding any source code
-for portions of the Combined Work that, considered in isolation, are
-based on the Application, and not on the Linked Version.
-
-  The "Corresponding Application Code" for a Combined Work means the
-object code and/or source code for the Application, including any data
-and utility programs needed for reproducing the Combined Work from the
-Application, but excluding the System Libraries of the Combined Work.
-
-  1. Exception to Section 3 of the GNU GPL.
-
-  You may convey a covered work under sections 3 and 4 of this License
-without being bound by section 3 of the GNU GPL.
-
-  2. Conveying Modified Versions.
-
-  If you modify a copy of the Library, and, in your modifications, a
-facility refers to a function or data to be supplied by an Application
-that uses the facility (other than as an argument passed when the
-facility is invoked), then you may convey a copy of the modified
-version:
-
-   a) under this License, provided that you make a good faith effort to
-   ensure that, in the event an Application does not supply the
-   function or data, the facility still operates, and performs
-   whatever part of its purpose remains meaningful, or
-
-   b) under the GNU GPL, with none of the additional permissions of
-   this License applicable to that copy.
-
-  3. Object Code Incorporating Material from Library Header Files.
-
-  The object code form of an Application may incorporate material from
-a header file that is part of the Library.  You may convey such object
-code under terms of your choice, provided that, if the incorporated
-material is not limited to numerical parameters, data structure
-layouts and accessors, or small macros, inline functions and templates
-(ten or fewer lines in length), you do both of the following:
-
-   a) Give prominent notice with each copy of the object code that the
-   Library is used in it and that the Library and its use are
-   covered by this License.
-
-   b) Accompany the object code with a copy of the GNU GPL and this license
-   document.
-
-  4. Combined Works.
-
-  You may convey a Combined Work under terms of your choice that,
-taken together, effectively do not restrict modification of the
-portions of the Library contained in the Combined Work and reverse
-engineering for debugging such modifications, if you also do each of
-the following:
-
-   a) Give prominent notice with each copy of the Combined Work that
-   the Library is used in it and that the Library and its use are
-   covered by this License.
-
-   b) Accompany the Combined Work with a copy of the GNU GPL and this license
-   document.
-
-   c) For a Combined Work that displays copyright notices during
-   execution, include the copyright notice for the Library among
-   these notices, as well as a reference directing the user to the
-   copies of the GNU GPL and this license document.
-
-   d) Do one of the following:
-
-       0) Convey the Minimal Corresponding Source under the terms of this
-       License, and the Corresponding Application Code in a form
-       suitable for, and under terms that permit, the user to
-       recombine or relink the Application with a modified version of
-       the Linked Version to produce a modified Combined Work, in the
-       manner specified by section 6 of the GNU GPL for conveying
-       Corresponding Source.
-
-       1) Use a suitable shared library mechanism for linking with the
-       Library.  A suitable mechanism is one that (a) uses at run time
-       a copy of the Library already present on the user's computer
-       system, and (b) will operate properly with a modified version
-       of the Library that is interface-compatible with the Linked
-       Version.
-
-   e) Provide Installation Information, but only if you would otherwise
-   be required to provide such information under section 6 of the
-   GNU GPL, and only to the extent that such information is
-   necessary to install and execute a modified version of the
-   Combined Work produced by recombining or relinking the
-   Application with a modified version of the Linked Version. (If
-   you use option 4d0, the Installation Information must accompany
-   the Minimal Corresponding Source and Corresponding Application
-   Code. If you use option 4d1, you must provide the Installation
-   Information in the manner specified by section 6 of the GNU GPL
-   for conveying Corresponding Source.)
-
-  5. Combined Libraries.
-
-  You may place library facilities that are a work based on the
-Library side by side in a single library together with other library
-facilities that are not Applications and are not covered by this
-License, and convey such a combined library under terms of your
-choice, if you do both of the following:
-
-   a) Accompany the combined library with a copy of the same work based
-   on the Library, uncombined with any other library facilities,
-   conveyed under the terms of this License.
-
-   b) Give prominent notice with the combined library that part of it
-   is a work based on the Library, and explaining where to find the
-   accompanying uncombined form of the same work.
-
-  6. Revised Versions of the GNU Lesser General Public License.
-
-  The Free Software Foundation may publish revised and/or new versions
-of the GNU Lesser General Public License from time to time. Such new
-versions will be similar in spirit to the present version, but may
-differ in detail to address new problems or concerns.
-
-  Each version is given a distinguishing version number. If the
-Library as you received it specifies that a certain numbered version
-of the GNU Lesser General Public License "or any later version"
-applies to it, you have the option of following the terms and
-conditions either of that published version or of any later version
-published by the Free Software Foundation. If the Library as you
-received it does not specify a version number of the GNU Lesser
-General Public License, you may choose any version of the GNU Lesser
-General Public License ever published by the Free Software Foundation.
-
-  If the Library as you received it specifies that a proxy can decide
-whether future versions of the GNU Lesser General Public License shall
-apply, that proxy's public statement of acceptance of any version is
-permanent authorization for you to choose that version for the
-Library.
+BSD 3-Clause License
+
+Copyright (c) 2022, Artificial and Mechanical Intelligence 
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

README.md

@@ -1 +1,85 @@
-# jaxsim
+# JAXsim
+
+**A scalable physics engine implemented with JAX. With JIT batteries 🔋**
+
+⚠ This project is still experimental, APIs could change without notice. ️⚠
+
+⚠ This simulator currently focuses on locomotion applications. Only contacts with ground are supported. ️⚠
+
+## Features
+
+- Physics engine in reduced coordinates implemented with [JAX][jax] in Python.
+- Supported JIT compilation of Python code for increased performance.
+- Transparent support to execute the simulation on CPUs, GPUs, and TPUs.
+- Possibility to run parallel multi-body simulations on hardware accelerators for significantly increased throughput.
+- Support of SDF models (and, upon conversion, URDF models).
+- Collision detection between bodies and uneven ground surface.
+- Continuous soft contacts model with no friction cone approximations.
+- Full support of inertial properties of bodies.
+- Revolute, prismatic, and fixed joints support.
+- Forward Euler and RK4 integrators.
+- High-level classes to compute multi-body dynamics quantities from simulation state.
+
+Planned features:
+
+- Reinforcement Learning module developed in JAX.
+- Finalization of differentiable physics through the simulation.
+
+[jax]: https://github.com/google/jax/
+
+## Installation
+
+You can install the project with [`pypa/pip`][pip], preferably in a [virtual environment][venv]:
+
+```bash
+pip install "jaxsim @ git+https://github.com/ami-iit/jaxsim"
+```
+
+Have a look to [`setup.cfg`](setup.cfg) for a complete list of optional dependencies.
+You can install all of them specifying `jaxsim[all]`.
+
+**Note:** if you need GPU support, please follow the official [installation instruction][jax_gpu] of JAX.
+
+[pip]: https://github.com/pypa/pip/
+[venv]: https://docs.python.org/3.8/tutorial/venv.html
+[jax_gpu]: https://github.com/google/jax/#installation
+
+## Credits
+
+The physics module of JAXsim is based on the theory of the [Rigid Body Dynamics Algorithms][RBDA]
+book authored by Roy Featherstone.
+We structured part of our logic following its accompanying [code][spatial_v2].
+The physics engine is developed entirely in Python using [JAX][jax].
+
+[RBDA]: https://link.springer.com/book/10.1007/978-1-4899-7560-7
+[spatial_v2]: http://royfeatherstone.org/spatial/index.html#spatial-software
+
+The inspiration of developing JAXsim stems from [`google/brax`][brax].
+Here below we summarize the differences between the projects:
+
+- JAXsim simulates multibody dynamics in reduced coordinates, while `brax` uses maximal coordinates.
+- 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, under the assumption that 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.
+- While supported thanks to the usage of JAX, differentiating through the simulator has not yet been studied.
+
+[brax]: https://github.com/google/brax
+[PFS]: http://sdformat.org/tutorials?tut=pose_frame_semantics
+
+## Contributing
+
+Pull requests are welcome. 
+For major changes, please open an issue first to discuss what you would like to change.
+
+## Maintainers
+
+| [<img src="https://github.com/diegoferigo.png" width="40">][df] | [@diegoferigo][df] |
+|:---------------------------------------------------------------:|:------------------:|
+
+[df]: https://github.com/diegoferigo
+
+## License
+
+[BSD3](https://choosealicense.com/licenses/bsd-3-clause/)

pyproject.toml

@@ -0,0 +1,17 @@
+[build-system]
+build-backend = "setuptools.build_meta"
+requires = [
+    "wheel",
+    "setuptools>=45",
+    "setuptools_scm[toml]>=6.0",
+]
+
+[tool.setuptools_scm]
+local_scheme = "dirty-tag"
+
+[tool.black]
+line-length = 88
+
+[tool.isort]
+profile = "black"
+multi_line_output = 3