https://github.com/ami-iit/jaxsim

A differentiable physics engine and multibody dynamics library for control and robot learning.

Keywords

aba ad automatic-differentiation crba dynamics featherstone jacobian jax jit kinematics ode physics physics-engine rigid-body-dynamics rnea robotics robotics-control robotics-simulation simulation simulation-modeling

Keywords from Contributors

robot distributed simulator parallel evolutionary-algorithms archival genetic-algorithm transformers control urdf

Last synced: 5 months ago · JSON representation

Repository

A differentiable physics engine and multibody dynamics library for control and robot learning.

Basic Info

Host: GitHub
Owner: ami-iit
License: bsd-3-clause
Language: Python
Default Branch: main
Homepage: https://jaxsim.readthedocs.io/
Size: 4.65 MB

Statistics

Stars: 148
Watchers: 18
Forks: 17
Open Issues: 23
Releases: 10

Topics

aba ad automatic-differentiation crba dynamics featherstone jacobian jax jit kinematics ode physics physics-engine rigid-body-dynamics rnea robotics robotics-control robotics-simulation simulation simulation-modeling

Created about 4 years ago · Last pushed 6 months ago

Metadata Files

Readme Contributing License Codeowners

README.md

JaxSim

JaxSim is a differentiable physics engine built with JAX, tailored for co-design and robotic learning applications.

Features

Physically consistent differentiability w.r.t. hardware parameters.
Closed chain dynamics support.
Reduced-coordinate physics engine for fixed-base and floating-base robots.
Fully Python-based, leveraging JAX following a functional programming paradigm.
Seamless execution on CPUs, GPUs, and TPUs.
Supports JIT compilation and automatic vectorization for high performance.
Compatible with SDF models and URDF (via sdformat conversion).

[!WARNING] This project is still experimental. APIs may change between releases without notice.

[!NOTE] JaxSim currently focuses on locomotion applications. Only contacts between bodies and smooth ground surfaces are supported.

How to use it

```python import pathlib

import icub_models import jax.numpy as jnp

import jaxsim.api as js

Load the iCub model

modelpath = icubmodels.getmodelfile("iCubGazeboV2_5")

joints = ('torsopitch', 'torsoroll', 'torsoyaw', 'lshoulderpitch', 'lshoulderroll', 'lshoulderyaw', 'lelbow', 'rshoulderpitch', 'rshoulderroll', 'rshoulderyaw', 'relbow', 'lhippitch', 'lhiproll', 'lhipyaw', 'lknee', 'lanklepitch', 'lankleroll', 'rhippitch', 'rhiproll', 'rhipyaw', 'rknee', 'ranklepitch', 'rankle_roll')

Build and reduce the model

modeldescription = pathlib.Path(modelpath)

fullmodel = js.model.JaxSimModel.buildfrommodeldescription( modeldescription=modeldescription, timestep=0.0001, isurdf=True )

model = js.model.reduce(model=fullmodel, consideredjoints=joints)

Get the number of degrees of freedom

ndof = model.dofs()

Initialize data and simulation

Note that the default data representation is mixed velocity representation

data = js.data.JaxSimModelData.build( model=model, base_position=jnp.array([0.0, 0.0, 1.0]) )

T = jnp.arange(start=0, stop=1.0, step=model.time_step)

tau = jnp.zeros(ndof)

Simulate

for _ in T: data = js.model.step( model=model, data=data, linkforces=None, jointforce_references=tau ) ```

Check the example folder for additional use cases!

[!NOTE]

Installation

With conda

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*"`.

With pixi

> ### Note > The minimum version of `pixi` required is `0.39.0`. Since the `pixi.lock` file is stored using Git LFS, make sure you have [Git LFS](https://github.com/git-lfs/git-lfs/blob/main/INSTALLING.md) installed and properly configured on your system before installation. After cloning the repository, run: ```bash git lfs install && git lfs pull ``` This ensures all LFS-tracked files are properly downloaded before you proceed with the installation. You can add the jaxsim dependency in [`pixi`][pixi] project as follows: ```bash pixi add jaxsim ``` If you are on Linux and you want to use a `cuda`-powered version of `jax`, remember to add the appropriate line in the [`system-requirements`](https://pixi.sh/latest/reference/pixi_manifest/#the-system-requirements-table) table, i.e. adding ~~~toml [system-requirements] cuda = "12" ~~~ if you are using a `pixi.toml` file or ~~~toml [tool.pixi.system-requirements] cuda = "12" ~~~ if you are using a `pyproject.toml` file.

With pip

You can install the project using [`pypa/pip`][pip], preferably in a [virtual environment][venv], as follows: ```bash pip install jaxsim ``` Check [`pyproject.toml`](pyproject.toml) 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.

Contributors installation (with conda)

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 . ```

Contributors installation (with pixi)

> ### Note > The minimum version of `pixi` required is `0.39.0`. Since the `pixi.lock` file is stored using Git LFS, make sure you have [Git LFS](https://github.com/git-lfs/git-lfs/blob/main/INSTALLING.md) installed and properly configured on your system before installation. After cloning the repository, run: ```bash git lfs install && git lfs pull ``` This ensures all LFS-tracked files are properly downloaded before you proceed with the installation. You can install the default dependencies of the project using [`pixi`][pixi] as follows: ```bash pixi install ``` See `pixi task list` for a list of available tasks.

Documentation

The JaxSim API documentation is available at jaxsim.readthedocs.io.

Additional features

Jaxsim can also be used as a multi-body dynamics library! With full support for automatic differentiation of RBDAs (forwards and reverse mode) and automatic differentiation against both kinematic and dynamic parameters.

Using JaxSim as a multibody dynamics library

```python import pathlib

import icub_models import jax.numpy as jnp

import jaxsim.api as js

Load the iCub model

modelpath = icubmodels.getmodelfile("iCubGazeboV2_5")

joints = ('torsopitch', 'torsoroll', 'torsoyaw', 'lshoulderpitch', 'lshoulderroll', 'lshoulderyaw', 'lelbow', 'rshoulderpitch', 'rshoulderroll', 'rshoulderyaw', 'relbow', 'lhippitch', 'lhiproll', 'lhipyaw', 'lknee', 'lanklepitch', 'lankleroll', 'rhippitch', 'rhiproll', 'rhipyaw', 'rknee', 'ranklepitch', 'rankle_roll')

Build and reduce the model

modeldescription = pathlib.Path(modelpath)

fullmodel = js.model.JaxSimModel.buildfrommodeldescription( modeldescription=modeldescription, timestep=0.0001, isurdf=True )

model = js.model.reduce(model=fullmodel, consideredjoints=joints)

Initialize model data

data = js.data.JaxSimModelData.build( model=model, base_position=jnp.array([0.0, 0.0, 1.0]), )

Frame and dynamics computations

frameindex = js.frame.nametoidx(model=model, framename="l_foot")

Frame transformation

WHF = js.frame.transform( model=model, data=data, frameindex=frameindex )

Frame Jacobian

WJF = js.frame.jacobian( model=model, data=data, frameindex=frameindex )

Dynamics properties

M = js.model.freefloatingmassmatrix(model=model, data=data) # Mass matrix h = js.model.freefloatingbiasforces(model=model, data=data) # Bias forces g = js.model.freefloatinggravityforces(model=model, data=data) # Gravity forces C = js.model.freefloatingcoriolismatrix(model=model, data=data) # Coriolis matrix

Print dynamics results

print(f"{M.shape=} \n{h.shape=} \n{g.shape=} \n{C.shape=}") ```

Credits

The RBDAs are based on the theory of the Rigid Body Dynamics Algorithms book by Roy Featherstone. The algorithms and some simulation features were inspired by its accompanying code.

The development of JaxSim started in late 2021, inspired by early versions of google/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 for showing the potential of JAX in this field.

Brax v2 was later implemented with reduced coordinates, following an approach comparable to JaxSim. The development then shifted to MJX, which 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.
JaxSim only supports collisions between points rigidly attached to bodies and a compliant ground surface.

Contributing

We welcome contributions from the community. Please read the contributing guide 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}, }

Theoretical aspects of JaxSim are based on Chapters 7 and 8 of the following Ph.D. thesis:

bibtex @phdthesis{ferigo_phd_thesis_2022, title = {Simulation Architectures for Reinforcement Learning applied to Robotics}, author = {Diego Ferigo}, school = {University of Manchester}, type = {PhD Thesis}, month = {July}, year = {2022}, }

People

| Authors | Maintainers | |:------:|:-----------:| | | |

License

BSD3

Owner

Name: Artificial and Mechanical Intelligence
Login: ami-iit
Kind: organization
Location: Italy

Website: https://ami.iit.it/
Repositories: 111
Profile: https://github.com/ami-iit

GitHub Events

Total

Create event: 161
Commit comment event: 26
Release event: 4
Delete event: 147
Member event: 1
Pull request event: 284
Fork event: 7
Issues event: 31
Watch event: 71
Issue comment event: 296
Push event: 852
Pull request review event: 735
Pull request review comment event: 386
Gollum event: 2

Last Year

Create event: 161
Commit comment event: 26
Release event: 4
Delete event: 147
Member event: 1
Pull request event: 284
Fork event: 7
Issues event: 31
Watch event: 71
Issue comment event: 296
Push event: 852
Pull request review event: 735
Pull request review comment event: 386
Gollum event: 2

Committers

Last synced: 8 months ago

All Time

Total Commits: 1,777
Total Committers: 13
Avg Commits per committer: 136.692
Development Distribution Score (DDS): 0.559

Past Year

Commits: 869
Committers: 10
Avg Commits per committer: 86.9
Development Distribution Score (DDS): 0.417

Top Committers

Name	Email	Commits
Filippo Luca Ferretti	f**i@o**m	783
diegoferigo	d**o@i**t	774
Alessandro Croci	a**i@i**t	109
Carlotta	c**e@i**t	51
Omar G. Younis	o**8@g**m	30
Silvio Traversaro	s**o@t**t	16
dependabot[bot]	4****]	5
pre-commit-ci[bot]	6****]	3
Giovanni Fregonese	g**t@g**m	2
ConnorTingley	5****y	1
Daniele Pucci	d**5@g**m	1
Lucas Libshutz	l**4@c**u	1
icub	i**b@i**t	1

Committer Domains (Top 20 + Academic)

iit.it: 3 icub.iit: 1 cornell.edu: 1 traversaro.it: 1

Issues and Pull Requests

Last synced: 6 months ago

All Time

Total issues: 56
Total pull requests: 410
Average time to close issues: 4 months
Average time to close pull requests: 8 days
Total issue authors: 12
Total pull request authors: 15
Average comments per issue: 2.63
Average comments per pull request: 1.99
Merged pull requests: 331
Bot issues: 1
Bot pull requests: 30

Past Year

Issues: 11
Pull requests: 193
Average time to close issues: 14 days
Average time to close pull requests: 7 days
Issue authors: 9
Pull request authors: 10
Average comments per issue: 2.27
Average comments per pull request: 1.33
Merged pull requests: 143
Bot issues: 1
Bot pull requests: 27

View more stats

Top Authors

Issue Authors

diegoferigo (27)
flferretti (12)
xela-95 (8)
traversaro (4)
lorycontixd (4)
CarlottaSartore (3)
fl-ferr (3)
lucaslibshutz (1)
berkguler (1)
paLeziart (1)
markusheimerl (1)
younik (1)
dependabot[bot] (1)

Pull Request Authors

flferretti (266)
diegoferigo (161)
xela-95 (43)
github-actions[bot] (25)
traversaro (13)
CarlottaSartore (12)
dependabot[bot] (8)
younik (8)
pre-commit-ci[bot] (7)
lorycontixd (3)
lucaslibshutz (2)
giotherobot (2)
fl-ferr (1)
ConnorTingley (1)
DanielePucci (1)

Top Labels

Issue Labels

help wanted (2) bug (2) dependencies (1)

Pull Request Labels

pixi (25) dependencies (8) github_actions (8) enhancement (4) bug (3)

Packages

Total packages: 1
Total downloads:
- pypi 911 last-month

Total dependent packages: 0
Total dependent repositories: 0
Total versions: 304
Total maintainers: 3

pypi.org: jaxsim

A differentiable physics engine and multibody dynamics library for control and robot learning.

Documentation: https://jaxsim.readthedocs.io
License: 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.
Latest release: 0.7.0
published 10 months ago

Versions: 304
Dependent Packages: 0
Dependent Repositories: 0
Downloads: 911 Last month

Rankings

Dependent packages count: 6.6%

Stargazers count: 16.1%

Average: 20.5%

Forks count: 23.2%

Downloads: 25.8%

Dependent repos count: 30.6%

Maintainers (3)

dgferigo traversaro flferretti

Last synced: 6 months ago

https://github.com/ami-iit/jaxsim

Science Score: 59.0%

Keywords

Keywords from Contributors

Repository

Basic Info

Statistics

Topics

Metadata Files

README.md

JaxSim

Features

How to use it

Load the iCub model

Build and reduce the model

Get the number of degrees of freedom

Initialize data and simulation

Note that the default data representation is mixed velocity representation

Simulate

Installation

Documentation

Additional features

Using JaxSim as a multibody dynamics library

Load the iCub model

Build and reduce the model

Initialize model data

Frame and dynamics computations

Frame transformation

Frame Jacobian

Dynamics properties

Print dynamics results

Credits

Contributing

Citing

People

License

Owner

GitHub Events

Total

Last Year

Committers

All Time

Past Year

Top Committers

Committer Domains (Top 20 + Academic)

Issues and Pull Requests

All Time

Past Year

Top Authors

Issue Authors

Pull Request Authors

Top Labels

Issue Labels

Pull Request Labels

Packages

pypi.org: jaxsim

Rankings

Maintainers (3)

Dependencies