<div align="center">
<a href="#"><img width="400px" height="auto" src="https://raw.github.com/duburcqa/jiminy/readme/jiminy_logo.svg"></a>
</div>
____
[](https://opensource.org/licenses/MIT)
[](https://pypi.org/project/jiminy-py)
[](https://www.python.org/downloads/)
[](https://pepy.tech/project/jiminy-py)
[](https://mybinder.org/v2/gh/duburcqa/jiminy.git/demo?labpath=tutorial.ipynb)
[](https://colab.research.google.com/github/duburcqa/jiminy/blob/demo/tutorial.ipynb)
[](https://deepnote.com/workspace/alexis-duburcq-7e87783d-6f49-4586-ae21-9967ef0c7882/project/jiminy-demo-3999591e-5f92-4474-96cc-cddc08b5d295/notebook/tutorial-88bef20df39c460b9974d1ef6366f721)
[](https://github.com/duburcqa/jiminy/actions/workflows/linux.yml)
[](https://github.com/duburcqa/jiminy/actions/workflows/macos.yml)
[](https://github.com/duburcqa/jiminy/actions/workflows/win.yml)
Jiminy is a cross-platform open-source simulator for poly-articulated systems. It was built with two ideas in mind:
- **provide a fast yet physically accurate simulator for robotics research.**
Jiminy is built around [Pinocchio](https://github.com/stack-of-tasks/pinocchio), an open-source fast and efficient kinematics and dynamics library. Jiminy thus uses minimal coordinates and Lagrangian dynamics to simulate an articulated system: this makes Jiminy as close as numerically possible to an analytical solution, without the risk of joint violation.
- **build an efficient and flexible platform for machine learning in robotics.**
Beside a strong focus on performance to answer machine learning's need for running computationally demanding distributed simulations, Jiminy offers convenience tools for learning via a dedicated module [Gym-Jiminy](#gym-jiminy). It is fully compliant with `gym` standard API and provides a highly customizable wrapper to interface any robotics system with state-of-the-art learning frameworks.
## Key features
### General
- Simulation of multi-body systems using **minimal coordinates and Lagrangian dynamics**.
- Comprehensive API for computing dynamic quantities and their derivatives thanks to Pinocchio.
- C++ core with full python bindings, providing user API parity between both languages.
- Designed with machine learning in mind, with seamless wrapping of robots as [OpenAI Gym](https://github.com/openai/gym) environments using one-liners. Jiminy provides both the physical engine and the robot model (including sensors) required for learning.
- **Fully modular learning environment pipeline design**, with plug-and-play robotic observers and controllers, but also composable reward components and termination conditions. See example [here](./python/gym_jiminy/unit_py/data/anymal_pipeline.toml).
- Rich simulation log output, easily customizable for recording, introspection and debugging. The simulation log is made available in RAM directly for fast access, and can be exported in binary or [HDF5](./docs/spec/src/tlmc_format_specification.md) format.
- Dedicated integration in Google Colab, Jupyter Lab, Mybinder and VSCode working out-of-the-box - including interactive 3D viewer based on [Meshcat](https://github.com/rdeits/MeshCat.jl). This facilitates working on remote environments.
- Synchronous and single-threaded offscreen rendering capability, GPU-accelerated without graphical server, based on [Panda3d](https://github.com/panda3d/panda3d).
- Easy to install: `pip` is all that is needed to [get you started](#getting-started) ! Support Linux, Mac and Windows platforms.
### Physics
- Provide both classical phenomenological force-level spring-damper contact model and constraint solver satisfying the maximum energy dissipation principle.
- Support contact and collision with the ground from a fixed set of contact points (primitives and meshes yet to come).
- Simulate multiple articulated systems simultaneously interacting with each other, to support use cases such as multi-agent learning or swarm robotics.
- Modeling of motor transmission backlash and structural deformation via compliant spherical joints with spring-damper dynamics, which are common phenomena, particularly in bipedal robotics.
- Simulate both continuous or discrete-time controller, with possibly different controller and sensor update frequencies.
A more complete list of features is available on the [wiki](https://github.com/duburcqa/jiminy/wiki).
**The documentation is available on [Github.io](https://duburcqa.github.io/jiminy/), or locally in `docs/html/index.html` if built from source.**
## Gym Jiminy
Gym Jiminy is an interface between Jiminy simulator and reinforcement learning frameworks. It is fully compliant with now standard [Open AI Gym](https://github.com/openai/gym) API. Additionally, it offers a generic and easily configurable learning environment for learning locomotion tasks, with minimal intervention from the user, who usually only needs to provide the robot's [URDF](https://wiki.ros.org/urdf) file. Furthermore, Gym Jiminy enables easy modification of many aspects of the simulation to provide richer exploration and ensure robust learning. This ranges from external perturbation forces to sensor noise and bias, including randomization of masses and inertias, ground friction model or even gravity itself. Note that learning can
easily be done on any high-level dynamics features, or restricted to mock sensor data for end-to-end learning.
Gym is cross-platform and compatible with most Reinforcement Learning frameworks implementing standard algorithms. For instance, [Stable Baselines 3](https://github.com/DLR-RM/stable-baselines3), [Tianshou](https://github.com/thu-ml/tianshou), or [Rllib](https://github.com/ray-project/ray). Stable Baselines 3 and Tianshou use its counterpart [Pytorch](https://pytorch.org/), and Rllib supports both. A few learning examples relying on those packages are also provided.
Pre-configured environments for some well-known toys models and reference robotics platforms are provided: [cartpole](https://www.gymlibrary.dev/environments/classic_control/cart_pole/), [acrobot](https://www.gymlibrary.dev/environments/classic_control/acrobot/), [pendulum](https://www.gymlibrary.dev/environments/classic_control/pendulum/), [Ant](https://www.gymlibrary.dev/environments/mujoco/ant/), [ANYmal](https://www.anymal-research.org/#getting-started), and [Cassie](https://www.agilityrobotics.com/robots#cassie), and [Atlas](https://www.bostondynamics.com/atlas).
## Demo
<a href="./python/jiminy_py/examples/tutorial.ipynb">
<p align="middle">
<img src="https://raw.github.com/duburcqa/jiminy/readme/jiminy_plot_log.png" width="49.0%"/>
<img src="https://raw.github.com/duburcqa/jiminy/readme/jiminy_viewer_open.png" width="49.0%"/>
<img src="https://raw.github.com/duburcqa/jiminy/readme/jiminy_tensorboard_cartpole.png" width="98.5%"/>
<img src="https://raw.github.com/duburcqa/jiminy/readme/jiminy_learning_ant.gif" width="32.5%"/>
<img src="https://raw.github.com/duburcqa/jiminy/readme/cassie.png" width="32.5%"/>
<img src="https://raw.github.com/duburcqa/jiminy/readme/atlas.png" width="32.5%"/>
</p>
</a>
## Getting started
Jiminy and Gym Jiminy support Linux, Mac and Windows, and is compatible with Python3.10+. Pre-compiled binaries are distributed on PyPi. They can be installed using `pip>=20.3`:
```bash
# For installing Jiminy
python -m pip install --prefer-binary jiminy_py[meshcat,plot]
# For installing Gym Jiminy
python -m pip install --prefer-binary gym_jiminy[all]
```
Detailed installation instructions, including building from source, are available [here](./INSTALL.md).
Raw data
{
"_id": null,
"home_page": "https://duburcqa.github.io/jiminy/README.html",
"name": "jiminy-py",
"maintainer": "Alexis Duburcq",
"docs_url": null,
"requires_python": "<3.13,>=3.10",
"maintainer_email": null,
"keywords": "robotics physics simulator",
"author": "Alexis Duburcq",
"author_email": "alexis.duburcq@gmail.com",
"download_url": "https://github.com/duburcqa/jiminy/archive/1.8.9.tar.gz",
"platform": null,
"description": "<div align=\"center\">\n <a href=\"#\"><img width=\"400px\" height=\"auto\" src=\"https://raw.github.com/duburcqa/jiminy/readme/jiminy_logo.svg\"></a>\n</div>\n\n____\n\n[](https://opensource.org/licenses/MIT)\n[](https://pypi.org/project/jiminy-py)\n[](https://www.python.org/downloads/)\n[](https://pepy.tech/project/jiminy-py)\n[](https://mybinder.org/v2/gh/duburcqa/jiminy.git/demo?labpath=tutorial.ipynb)\n[](https://colab.research.google.com/github/duburcqa/jiminy/blob/demo/tutorial.ipynb)\n[](https://deepnote.com/workspace/alexis-duburcq-7e87783d-6f49-4586-ae21-9967ef0c7882/project/jiminy-demo-3999591e-5f92-4474-96cc-cddc08b5d295/notebook/tutorial-88bef20df39c460b9974d1ef6366f721)\n[](https://github.com/duburcqa/jiminy/actions/workflows/linux.yml)\n[](https://github.com/duburcqa/jiminy/actions/workflows/macos.yml)\n[](https://github.com/duburcqa/jiminy/actions/workflows/win.yml)\n\nJiminy is a cross-platform open-source simulator for poly-articulated systems. It was built with two ideas in mind:\n\n- **provide a fast yet physically accurate simulator for robotics research.**\n\nJiminy is built around [Pinocchio](https://github.com/stack-of-tasks/pinocchio), an open-source fast and efficient kinematics and dynamics library. Jiminy thus uses minimal coordinates and Lagrangian dynamics to simulate an articulated system: this makes Jiminy as close as numerically possible to an analytical solution, without the risk of joint violation.\n\n- **build an efficient and flexible platform for machine learning in robotics.**\n\nBeside a strong focus on performance to answer machine learning's need for running computationally demanding distributed simulations, Jiminy offers convenience tools for learning via a dedicated module [Gym-Jiminy](#gym-jiminy). It is fully compliant with `gym` standard API and provides a highly customizable wrapper to interface any robotics system with state-of-the-art learning frameworks.\n\n## Key features\n\n### General\n\n- Simulation of multi-body systems using **minimal coordinates and Lagrangian dynamics**.\n- Comprehensive API for computing dynamic quantities and their derivatives thanks to Pinocchio.\n- C++ core with full python bindings, providing user API parity between both languages.\n- Designed with machine learning in mind, with seamless wrapping of robots as [OpenAI Gym](https://github.com/openai/gym) environments using one-liners. Jiminy provides both the physical engine and the robot model (including sensors) required for learning.\n- **Fully modular learning environment pipeline design**, with plug-and-play robotic observers and controllers, but also composable reward components and termination conditions. See example [here](./python/gym_jiminy/unit_py/data/anymal_pipeline.toml).\n- Rich simulation log output, easily customizable for recording, introspection and debugging. The simulation log is made available in RAM directly for fast access, and can be exported in binary or [HDF5](./docs/spec/src/tlmc_format_specification.md) format.\n- Dedicated integration in Google Colab, Jupyter Lab, Mybinder and VSCode working out-of-the-box - including interactive 3D viewer based on [Meshcat](https://github.com/rdeits/MeshCat.jl). This facilitates working on remote environments.\n- Synchronous and single-threaded offscreen rendering capability, GPU-accelerated without graphical server, based on [Panda3d](https://github.com/panda3d/panda3d).\n- Easy to install: `pip` is all that is needed to [get you started](#getting-started) ! Support Linux, Mac and Windows platforms.\n\n### Physics\n\n- Provide both classical phenomenological force-level spring-damper contact model and constraint solver satisfying the maximum energy dissipation principle.\n- Support contact and collision with the ground from a fixed set of contact points (primitives and meshes yet to come).\n- Simulate multiple articulated systems simultaneously interacting with each other, to support use cases such as multi-agent learning or swarm robotics.\n- Modeling of motor transmission backlash and structural deformation via compliant spherical joints with spring-damper dynamics, which are common phenomena, particularly in bipedal robotics.\n- Simulate both continuous or discrete-time controller, with possibly different controller and sensor update frequencies.\n\nA more complete list of features is available on the [wiki](https://github.com/duburcqa/jiminy/wiki).\n\n**The documentation is available on [Github.io](https://duburcqa.github.io/jiminy/), or locally in `docs/html/index.html` if built from source.**\n\n## Gym Jiminy\n\nGym Jiminy is an interface between Jiminy simulator and reinforcement learning frameworks. It is fully compliant with now standard [Open AI Gym](https://github.com/openai/gym) API. Additionally, it offers a generic and easily configurable learning environment for learning locomotion tasks, with minimal intervention from the user, who usually only needs to provide the robot's [URDF](https://wiki.ros.org/urdf) file. Furthermore, Gym Jiminy enables easy modification of many aspects of the simulation to provide richer exploration and ensure robust learning. This ranges from external perturbation forces to sensor noise and bias, including randomization of masses and inertias, ground friction model or even gravity itself. Note that learning can\neasily be done on any high-level dynamics features, or restricted to mock sensor data for end-to-end learning.\n\nGym is cross-platform and compatible with most Reinforcement Learning frameworks implementing standard algorithms. For instance, [Stable Baselines 3](https://github.com/DLR-RM/stable-baselines3), [Tianshou](https://github.com/thu-ml/tianshou), or [Rllib](https://github.com/ray-project/ray). Stable Baselines 3 and Tianshou use its counterpart [Pytorch](https://pytorch.org/), and Rllib supports both. A few learning examples relying on those packages are also provided.\n\nPre-configured environments for some well-known toys models and reference robotics platforms are provided: [cartpole](https://www.gymlibrary.dev/environments/classic_control/cart_pole/), [acrobot](https://www.gymlibrary.dev/environments/classic_control/acrobot/), [pendulum](https://www.gymlibrary.dev/environments/classic_control/pendulum/), [Ant](https://www.gymlibrary.dev/environments/mujoco/ant/), [ANYmal](https://www.anymal-research.org/#getting-started), and [Cassie](https://www.agilityrobotics.com/robots#cassie), and [Atlas](https://www.bostondynamics.com/atlas).\n\n## Demo\n\n<a href=\"./python/jiminy_py/examples/tutorial.ipynb\">\n<p align=\"middle\">\n <img src=\"https://raw.github.com/duburcqa/jiminy/readme/jiminy_plot_log.png\" width=\"49.0%\"/>\n <img src=\"https://raw.github.com/duburcqa/jiminy/readme/jiminy_viewer_open.png\" width=\"49.0%\"/>\n <img src=\"https://raw.github.com/duburcqa/jiminy/readme/jiminy_tensorboard_cartpole.png\" width=\"98.5%\"/>\n <img src=\"https://raw.github.com/duburcqa/jiminy/readme/jiminy_learning_ant.gif\" width=\"32.5%\"/>\n <img src=\"https://raw.github.com/duburcqa/jiminy/readme/cassie.png\" width=\"32.5%\"/>\n <img src=\"https://raw.github.com/duburcqa/jiminy/readme/atlas.png\" width=\"32.5%\"/>\n</p>\n</a>\n\n## Getting started\n\nJiminy and Gym Jiminy support Linux, Mac and Windows, and is compatible with Python3.10+. Pre-compiled binaries are distributed on PyPi. They can be installed using `pip>=20.3`:\n\n```bash\n# For installing Jiminy\npython -m pip install --prefer-binary jiminy_py[meshcat,plot]\n\n# For installing Gym Jiminy\npython -m pip install --prefer-binary gym_jiminy[all]\n```\n\nDetailed installation instructions, including building from source, are available [here](./INSTALL.md).\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Fast and light weight simulator of rigid poly-articulated systems.",
"version": "1.8.9",
"project_urls": {
"Bug Tracker": "https://github.com/duburcqa/jiminy/issues",
"Documentation": "https://duburcqa.github.io/jiminy",
"Download": "https://github.com/duburcqa/jiminy/archive/1.8.9.tar.gz",
"Homepage": "https://duburcqa.github.io/jiminy/README.html",
"Source": "https://github.com/duburcqa/jiminy"
},
"split_keywords": [
"robotics",
"physics",
"simulator"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "019b441f1b603de6636faf4a6f1f90e82d5018bc42e260d2d7ce01aceeafda5e",
"md5": "1ca4e8b64412e91724dca1e886884bb7",
"sha256": "9748ab8565a43673246e271c5f93f63460a6ff0c8c00dbe386d7a880c72d9a09"
},
"downloads": -1,
"filename": "jiminy_py-1.8.9-cp310-cp310-manylinux_2_28_x86_64.whl",
"has_sig": false,
"md5_digest": "1ca4e8b64412e91724dca1e886884bb7",
"packagetype": "bdist_wheel",
"python_version": "cp310",
"requires_python": "<3.13,>=3.10",
"size": 20710533,
"upload_time": "2024-12-02T13:30:38",
"upload_time_iso_8601": "2024-12-02T13:30:38.383311Z",
"url": "https://files.pythonhosted.org/packages/01/9b/441f1b603de6636faf4a6f1f90e82d5018bc42e260d2d7ce01aceeafda5e/jiminy_py-1.8.9-cp310-cp310-manylinux_2_28_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "7f2a36163e5117778f60382ab8af33741fc329e791d08ce47328315e91cf8443",
"md5": "5fe25325fcc4f315faaaa7703d21f656",
"sha256": "98c1b215274711dcf0d0b6960ce67b0c354ccf980b3bd76db8833d181f4450a5"
},
"downloads": -1,
"filename": "jiminy_py-1.8.9-cp311-cp311-manylinux_2_28_x86_64.whl",
"has_sig": false,
"md5_digest": "5fe25325fcc4f315faaaa7703d21f656",
"packagetype": "bdist_wheel",
"python_version": "cp311",
"requires_python": "<3.13,>=3.10",
"size": 20707255,
"upload_time": "2024-12-02T13:30:41",
"upload_time_iso_8601": "2024-12-02T13:30:41.862136Z",
"url": "https://files.pythonhosted.org/packages/7f/2a/36163e5117778f60382ab8af33741fc329e791d08ce47328315e91cf8443/jiminy_py-1.8.9-cp311-cp311-manylinux_2_28_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "44e88d0337dfb248da23f34e2368ff7972d17a3f7e65d15944c37b7ae5a01167",
"md5": "956428bc5eb735f4bd553100a72ce5e5",
"sha256": "6ad48427454dafd03c3908d2a33c94026e1bec36de0529dd1d39581358f55f60"
},
"downloads": -1,
"filename": "jiminy_py-1.8.9-cp312-cp312-manylinux_2_28_x86_64.whl",
"has_sig": false,
"md5_digest": "956428bc5eb735f4bd553100a72ce5e5",
"packagetype": "bdist_wheel",
"python_version": "cp312",
"requires_python": "<3.13,>=3.10",
"size": 20701435,
"upload_time": "2024-12-02T13:30:44",
"upload_time_iso_8601": "2024-12-02T13:30:44.559388Z",
"url": "https://files.pythonhosted.org/packages/44/e8/8d0337dfb248da23f34e2368ff7972d17a3f7e65d15944c37b7ae5a01167/jiminy_py-1.8.9-cp312-cp312-manylinux_2_28_x86_64.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-02 13:30:38",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "duburcqa",
"github_project": "jiminy",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "jiminy-py"
}
JSON
