jaxsim 0.1.dev401__tar.gz → 0.2.0__tar.gz

jaxsim-0.2.0/.devcontainer/Dockerfile

@@ -0,0 +1,26 @@
+FROM mcr.microsoft.com/devcontainers/base:ubuntu
+COPY environment.yml /opt/environment.yml
+
+# Enable by default the conda environment for all users.
+# The prefix is the one used by the micromamba feature.
+ENV CONDA_PREFIX_JAXSIM=/opt/conda/envs/jaxsim
+RUN echo 'function activate_conda() {' >> /etc/bash.bashrc &&\
+    echo '  eval "$(micromamba shell hook -s bash)"' >> /etc/bash.bashrc &&\
+    echo '  micromamba activate ${CONDA_PREFIX_JAXSIM-$CONDA_PREFIX}' >> /etc/bash.bashrc &&\
+    echo '}' >> /etc/bash.bashrc &&\
+    echo '[[ -x $(which micromamba) && -d ${CONDA_PREFIX_JAXSIM-$CONDA_PREFIX} ]] && activate_conda' >> /etc/bash.bashrc &&\
+    echo '[[ -x $(which micromamba) && ! -x $(which mamba) ]] && alias mamba="$(which micromamba)"' >> /etc/bash.bashrc &&\
+    echo '[[ -x $(which micromamba) && ! -x $(which conda) ]] && alias conda="$(which micromamba)"' >> /etc/bash.bashrc
+
+# Provide libGL.so.1 from the host OS
+RUN sudo apt-get update &&\
+    sudo apt-get install -y --no-install-recommends libgl1 &&\
+    rm -rf /var/lib/apt/lists/*
+
+# The Python extension in VSCode is not able to detect the interpreter installed with micromamba.
+# As documented as follows, we provide a suggestion through an environment variable.
+# https://code.visualstudio.com/docs/python/environments#_where-the-extension-looks-for-environments
+ENV WORKON_HOME=$CONDA_PREFIX_JAXSIM
+
+# Specify the workdir of the container
+WORKDIR /workspace/jaxsim

jaxsim-0.2.0/.devcontainer/devcontainer.json

@@ -0,0 +1,34 @@
+// For format details, see https://aka.ms/devcontainer.json. For config options, see the
+// README at: https://github.com/devcontainers/templates/tree/main/src/ubuntu
+{
+	"name": "Ubuntu",
+	// Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile
+	"build": {
+		"context": "..",
+		"dockerfile": "Dockerfile",
+	},
+
+	// Features to add to the dev container. More info: https://containers.dev/features.
+	"features": {
+		"ghcr.io/mamba-org/devcontainer-features/micromamba:1": {
+			"envFile": "/opt/environment.yml",
+		},
+	},
+
+	// Use 'forwardPorts' to make a list of ports inside the container available locally.
+	// "forwardPorts": [],
+
+	// Use 'postCreateCommand' to run commands after the container is created.
+	// "postCreateCommand": "uname -a",
+
+	// Configure tool-specific properties.
+	// "customizations": {},
+
+	// Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root.
+	// "remoteUser": "root"
+
+	// VSCode extensions
+	"extensions": [
+		"ms-python.python",
+	],
+}

jaxsim-0.2.0/.github/CODEOWNERS

@@ -0,0 +1,2 @@
+*       @diegoferigo @flferretti
+*.ipynb  @flferretti

{jaxsim-0.1.dev401 → jaxsim-0.2.0}/.github/workflows/ci_cd.yml

@@ -1,11 +1,17 @@
 name: Python CI/CD
 
 on:
+  workflow_dispatch:
   push:
   pull_request:
   release:
     types:
       - published
+  schedule:
+  # * is a special character in YAML so you have to quote this string
+  # Execute a "nightly" build at 2 AM UTC
+  - cron:  '0 2 * * *'
+
 
 jobs:
 
@@ -83,6 +89,10 @@ jobs:
         shell: bash
         run: pip install "$(find dist/ -type f -name '*.whl')"
 
+      - name: Document installed pip packages
+        shell: bash
+        run: pip list --verbose
+
       - name: Import the package
         run: python -c "import jaxsim"
 
@@ -90,14 +100,42 @@ jobs:
         with:
           fetch-depth: 0
 
-      - name: Install Gazebo Classic
-        if: contains(matrix.os, 'ubuntu')
+      - uses: dorny/paths-filter@v3
+        id: changes
+        with:
+          filters: |
+            conf: &conf
+              - 'pyproject.toml'
+              - 'setup.cfg'
+              - 'setup.py'
+            src: &src
+              - 'src/**'
+            tests: &tests
+              - 'tests/**'
+            all:
+              - *conf
+              - *src
+              - *tests
+
+      # https://gazebosim.org/docs/harmonic/install_ubuntu
+      - name: Install Gazebo Sim
+        if: |
+          contains(matrix.os, 'ubuntu') &&
+          (github.event_name != 'pull_request' ||
+           steps.changes.outputs.all == 'true')
         run: |
           sudo apt-get update
-          sudo apt-get install gazebo
+          sudo apt-get install lsb-release wget gnupg
+          sudo wget https://packages.osrfoundation.org/gazebo.gpg -O /usr/share/keyrings/pkgs-osrf-archive-keyring.gpg
+          echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/pkgs-osrf-archive-keyring.gpg] http://packages.osrfoundation.org/gazebo/ubuntu-stable $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/gazebo-stable.list > /dev/null
+          sudo apt-get update
+          sudo apt-get install gz-harmonic
 
       - name: Run the Python tests
-        if: contains(matrix.os, 'ubuntu')
+        if: |
+          contains(matrix.os, 'ubuntu') &&
+          (github.event_name != 'pull_request' ||
+           steps.changes.outputs.all == 'true')
         run: pytest
         env:
           JAX_PLATFORM_NAME: cpu

jaxsim-0.2.0/.github/workflows/read_the_docs.yml

@@ -0,0 +1,18 @@
+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"
+          project-language: ""

{jaxsim-0.1.dev401 → jaxsim-0.2.0}/.github/workflows/style.yml

@@ -10,39 +10,40 @@ on:
 jobs:
 
   black:
-
     name: black
     runs-on: ubuntu-latest
 
     steps:
 
       - name: "🔀 Checkout repository"
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
 
       - name: '🐍 Initialize Python'
-        uses: actions/setup-python@v2
+        uses: actions/setup-python@v5
         with:
-          python-version: "3.8"
+          python-version: "3.*"
 
+      # Note: the black version needs to be in sync with what
+      # specified in setup.cfg.
       - name: "📝 Black Code Formatter"
         uses: psf/black@stable
         with:
-          options: --check --diff --color
+          options: "--check --diff --color"
+          version: "~= 24.0"
 
   isort:
-
     name: isort
     runs-on: ubuntu-latest
 
     steps:
 
       - name: "🔀 Checkout repository"
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
 
       - name: '🐍 Initialize Python'
-        uses: actions/setup-python@v2
+        uses: actions/setup-python@v5
         with:
-          python-version: "3.8"
+          python-version: "3.*"
 
       # Workaround for https://github.com/isort/isort-action/issues/70
       - run: pip install colorama
@@ -50,4 +51,16 @@ jobs:
       - name: "📝 isort"
         uses: isort/isort-action@master
         with:
-          configuration: --check --diff --color
+          configuration: "--check --diff --color"
+
+  ruff:
+    name: ruff
+    runs-on: ubuntu-latest
+
+    steps:
+
+      - name: "🔀 Checkout repository"
+        uses: actions/checkout@v4
+
+      - name: "📝 Ruff"
+        uses: chartboost/ruff-action@v1

{jaxsim-0.1.dev401 → jaxsim-0.2.0}/.gitignore

@@ -136,3 +136,6 @@ dmypy.json
 
 # setuptools_scm dynamic version
 src/jaxsim/_version.py
+
+# ruff
+.ruff_cache/

jaxsim-0.2.0/.pre-commit-config.yaml

@@ -0,0 +1,26 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.5.0
+    hooks:
+    - id: check-ast
+    - id: check-merge-conflict
+    - id: check-yaml
+    - id: end-of-file-fixer
+    - id: trailing-whitespace
+
+  - repo: https://github.com/psf/black-pre-commit-mirror
+    rev: 24.2.0
+    hooks:
+      - id: black
+        language_version: python3.11
+
+  - repo: https://github.com/pycqa/isort
+    rev: 5.13.2
+    hooks:
+      - id: isort
+        name: isort (python)
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.3.2
+    hooks:
+      - id: ruff

{jaxsim-0.1.dev401 → jaxsim-0.2.0}/.readthedocs.yaml

@@ -4,16 +4,16 @@ build:
   os: ubuntu-22.04
   tools:
     python: "mambaforge-22.9"
-    
+
 conda:
-  environment: docs/jaxsim_conda_env.yml
+  environment: environment.yml
 
 python:
   install:
     - method: pip
       path: .
-      
+
 sphinx:
   configuration: docs/conf.py
 
-formats: all
+formats: all

jaxsim-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,74 @@
+# Contributing to JAXsim :rocket:
+
+Hello Contributor,
+
+We're thrilled that you're considering contributing to JAXsim!
+Here's a brief guide to help you seamlessly become a part of our project.
+
+## Development Environment :hammer_and_wrench:
+
+Make sure your development environment is set up.
+Follow the installation instructions in the [README](./README.md) to get JAXsim and its dependencies up and running.
+
+To ensure consistency and maintain code quality, we recommend using the pre-commit hook with the following configuration.
+This will help catch issues before they become a part of the project.
+
+### Setting Up Pre-commit Hook :fishing_pole_and_fish:
+
+`pre-commit` is a tool that manages pre-commit hooks for your project.
+It will run checks on your code before you commit it, ensuring that it meets the project's standards.
+You should have it already installed if you followed the installation instructions in the [README](./README.md).
+
+Run the following command to install the hooks:
+
+```bash
+pre-commit install
+```
+
+### Using Pre-commit Hook :vertical_traffic_light:
+
+Before making any commits, the pre-commit hook will automatically run.
+If it finds any issues, it will prevent the commit and provide instructions on how to fix them.
+
+To get your commit through without fixing the issues, use the `--no-verify` flag:
+
+```bash
+git commit -m "Your commit message" --no-verify
+```
+
+To manually run the pre-commit hook at any time, use:
+
+```bash
+pre-commit run --all-files
+```
+
+## Making Changes :construction:
+
+Before submitting a pull request, create an issue to discuss your changes if major changes are involved.
+This helps us understand your needs and provide feedback.
+Clearly describe your pull request, referencing any related issues.
+Follow the [PEP 8](https://peps.python.org/pep-0008/) style guide and include relevant tests.
+
+## Testing :test_tube:
+
+Your code will be tested with the CI/CD pipeline before merging.
+Feel free to add new ones or update the existing tests in the [workflows](./github/workflows) folder to cover your changes.
+
+## Documentation :book:
+
+Update the documentation in the [docs](./docs) folder and the [README](./README.md) to reflect your changes, if necessary.
+There is no need to build the documentation locally; it will be automatically built and deployed with your pull request, where a preview link will be provided.
+
+## Code Review :eyes:
+
+Expect feedback during the code review process.
+Address comments and make necessary changes.
+This collaboration ensures quality.
+Please keep the commit history clean, or squash commits if necessary.
+
+## License :scroll:
+
+JAXsim is under the [BSD 3-Clause License](./LICENSE).
+By contributing, you agree to the same license.
+
+Thank you for contributing to JAXsim! Your efforts are appreciated.

{jaxsim-0.1.dev401 → jaxsim-0.2.0}/LICENSE

@@ -1,6 +1,6 @@
 BSD 3-Clause License
 
-Copyright (c) 2022, Artificial and Mechanical Intelligence 
+Copyright (c) 2022, Artificial and Mechanical Intelligence
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without

jaxsim-0.2.0/PKG-INFO

@@ -0,0 +1,237 @@
+Metadata-Version: 2.1
+Name: jaxsim
+Version: 0.2.0
+Summary: A differentiable physics engine and multibody dynamics library for control and robot learning.
+Home-page: https://github.com/ami-iit/jaxsim
+Author: Diego Ferigo
+Author-email: diego.ferigo@iit.it
+License: BSD
+Project-URL: Changelog, https://github.com/ami-iit/jaxsim/releases
+Project-URL: Documentation, https://jaxsim.readthedocs.io
+Project-URL: Source, https://github.com/ami-iit/jaxsim
+Project-URL: Tracker, https://github.com/ami-iit/jaxsim/issues
+Keywords: physics,physics engine,jax,rigid body dynamics,featherstone,reinforcement learning,robot,robotics,sdf,urdf
+Platform: any
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: Robot Framework
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Topic :: Games/Entertainment :: Simulation
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Topic :: Software Development
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: coloredlogs
+Requires-Dist: jax>=0.4.13
+Requires-Dist: jaxlib>=0.4.13
+Requires-Dist: jaxlie>=1.3.0
+Requires-Dist: jax_dataclasses>=1.4.0
+Requires-Dist: pptree
+Requires-Dist: rod>=0.2.0
+Requires-Dist: typing_extensions; python_version < "3.12"
+Provides-Extra: style
+Requires-Dist: black[jupyter]~=24.0; extra == "style"
+Requires-Dist: isort; extra == "style"
+Requires-Dist: pre-commit; extra == "style"
+Provides-Extra: testing
+Requires-Dist: idyntree; extra == "testing"
+Requires-Dist: pytest>=6.0; extra == "testing"
+Requires-Dist: pytest-icdiff; extra == "testing"
+Requires-Dist: robot-descriptions; extra == "testing"
+Provides-Extra: viz
+Requires-Dist: lxml; extra == "viz"
+Requires-Dist: mediapy; extra == "viz"
+Requires-Dist: mujoco>=3.0.0; extra == "viz"
+Provides-Extra: all
+Requires-Dist: black[jupyter]~=24.0; extra == "all"
+Requires-Dist: isort; extra == "all"
+Requires-Dist: pre-commit; extra == "all"
+Requires-Dist: idyntree; extra == "all"
+Requires-Dist: pytest>=6.0; extra == "all"
+Requires-Dist: pytest-icdiff; extra == "all"
+Requires-Dist: robot-descriptions; extra == "all"
+Requires-Dist: lxml; extra == "all"
+Requires-Dist: mediapy; extra == "all"
+Requires-Dist: mujoco>=3.0.0; extra == "all"
+
+# JaxSim
+
+JaxSim is a **differentiable physics engine** and **multibody dynamics library** designed for applications in control and robot learning, implemented with JAX.
+
+Its design facilitates research and accelerates prototyping in the intersection of robotics and artificial intelligence. 
+
+## Features
+
+- Physics engine in reduced coordinates supporting fixed-base and floating-base robots.
+- Multibody dynamics library providing all the necessary components for developing model-based control algorithms.
+- Completely developed in Python with [`google/jax`][jax] following a functional programming paradigm.
+- Transparent support for running on CPUs, GPUs, and TPUs.
+- Full support for JIT compilation for increased performance.
+- Full support for automatic vectorization for massive parallelization of open-loop and closed-loop architectures.
+- Support for SDF models and, upon conversion with [sdformat][sdformat], URDF models.
+- Visualization based on the [passive viewer][passive_viewer_mujoco] of Mujoco.
+
+### JaxSim as a simulator
+
+- Wide range of fixed-step explicit Runge-Kutta integrators.
+- Support for variable-step integrators implemented as embedded Runge-Kutta schemes.
+- Improved stability by optionally integrating the base orientation on the $\text{SO}(3)$ manifold.
+- Soft contacts model supporting full friction cone and sticking-slipping transition.
+- Collision detection between points rigidly attached to bodies and uneven ground surfaces.
+
+### JaxSim as a multibody dynamics library
+
+- Provides rigid body dynamics algorithms (RBDAs) like RNEA, ABA, CRBA, and Jacobians. 
+- Provides all the quantities included in the Euler-Poincarè formulation of the equations of motion.
+- Supports body-fixed, inertial-fixed, and mixed [velocity representations][notation].
+- Exposes all the necessary quantities to develop controllers in centroidal coordinates.
+
+### JaxSim for robot learning
+
+- Being developed with JAX, all the RBDAs support automatic differentiation both in forward and reverse modes.
+- Support for automatically differentiating against kinematics and dynamics parameters.
+- All fixed-step integrators are forward and reverse differentiable.
+- All variable-step integrators are forward differentiable.
+- Ideal for sampling synthetic data for reinforcement learning (RL).
+- Ideal for designing physics-informed neural networks (PINNs) with loss functions requiring model-based quantities.
+- Ideal for combining model-based control with learning-based components.
+
+[jax]: https://github.com/google/jax/
+[sdformat]: https://github.com/gazebosim/sdformat
+[notation]: https://research.tue.nl/en/publications/multibody-dynamics-notation-version-2
+[passive_viewer_mujoco]: https://mujoco.readthedocs.io/en/stable/python.html#passive-viewer
+
+> [!WARNING]
+> This project is still experimental, APIs could change between releases without notice.
+
+> [!NOTE]
+> JaxSim currently focuses on locomotion applications.
+> Only contacts between bodies and smooth ground surfaces are supported.
+
+## Documentation
+
+The JaxSim API documentation is available at [jaxsim.readthedocs.io][readthedocs].
+
+[readthedocs]: https://jaxsim.readthedocs.io/
+
+## Installation
+
+<details>
+<summary>With conda</summary>
+
+You can install the project using [`conda`][conda] as follows:
+
+```bash
+conda install jaxsim -c conda-forge
+```
+
+You can enforce GPU support, if needed, by also specifying `"jaxlib = * = *cuda*"`.
+
+</details>
+
+<details>
+<summary>With pip</summary>
+
+You can install the project using [`pypa/pip`][pip], preferably in a [virtual environment][venv], as follows:
+
+```bash
+pip install jaxsim
+```
+
+Check [`setup.cfg`](setup.cfg) for the complete list of optional dependencies.
+You can obtain a full installation using `jaxsim[all]`.
+
+If you need GPU support, follow the official [installation instructions][jax_gpu] of JAX.
+
+</details>
+
+<details>
+<summary>Contributors installation</summary>
+
+If you want to contribute to the project, we recommend creating the following `jaxsim` conda environment first:
+
+```bash
+conda env create -f environment.yml
+```
+
+Then, activate the environment and install the project in editable mode:
+
+```bash
+conda activate jaxsim
+pip install --no-deps -e .
+```
+
+</details>
+
+[conda]: https://anaconda.org/
+[pip]: https://github.com/pypa/pip/
+[venv]: https://docs.python.org/3/tutorial/venv.html
+[jax_gpu]: https://github.com/google/jax/#installation
+
+## Credits
+
+The RBDAs are based on the theory of the [Rigid Body Dynamics Algorithms][RBDA]
+book by Roy Featherstone.
+The algorithms and some simulation features were inspired by its accompanying [code][spatial_v2].
+
+[RBDA]: https://link.springer.com/book/10.1007/978-1-4899-7560-7
+[spatial_v2]: http://royfeatherstone.org/spatial/index.html#spatial-software
+
+The development of JaxSim started in late 2021, inspired by early versions of [`google/brax`][brax].
+At that time, Brax was implemented in maximal coordinates, and we wanted a physics engine in reduced coordinates.
+We are grateful to the Brax team for their work and showing the potential of [JAX][jax] in this field.
+
+Brax v2 was later implemented reduced coordinates, following an approach comparable to JaxSim.
+The development then shifted to [MJX][mjx], which today provides a JAX-based implementation of the Mujoco APIs.
+
+The main differences between MJX/Brax and JaxSim are as follows:
+
+- JaxSim supports out-of-the-box all SDF models with [Pose Frame Semantics][PFS].
+- JaxSim only supports collisions between points rigidly attached to bodies and a compliant ground surface.
+  Our contact model requires careful tuning of its spring-damper parameters, but being an instantaneous  
+  function of the state $(\mathbf{q}, \boldsymbol{\nu})$, it doesn't require running any optimization algorithm
+  when stepping the simulation forward.
+- JaxSim mitigates the stiffness of the contact-aware system dynamics by providing variable-step integrators. 
+
+[brax]: https://github.com/google/brax
+[mjx]: https://mujoco.readthedocs.io/en/3.0.0/mjx.html
+[PFS]: http://sdformat.org/tutorials?tut=pose_frame_semantics
+
+## Contributing
+
+We welcome contributions from the community.
+Please read the [contributing guide](./CONTRIBUTING.md) to get started.
+
+## Citing
+
+```bibtex
+@software{ferigo_jaxsim_2022,
+  author = {Diego Ferigo and Filippo Luca Ferretti and Silvio Traversaro and Daniele Pucci},
+  title = {{JaxSim}: A Differentiable Physics Engine and Multibody Dynamics Library for Control and Robot Learning},
+  url = {http://github.com/ami-iit/jaxsim},
+  year = {2022},
+}
+```
+
+## People
+
+| Author | Maintainers |
+|:------:|:-----------:|
+| [<img src="https://avatars.githubusercontent.com/u/469199?v=4" width="40">][df] | [<img src="https://avatars.githubusercontent.com/u/102977828?v=4" width="40">][ff] [<img src="https://avatars.githubusercontent.com/u/469199?v=4" width="40">][df] |
+
+[df]: https://github.com/diegoferigo
+[ff]: https://github.com/flferretti
+
+## License
+
+[BSD3](https://choosealicense.com/licenses/bsd-3-clause/)