Fast and light weight simulator of rigid poly-articulated systems.


Keywords
robotics, physics, simulator, c-plus-plus, machine-learning, openai-gym, python
License
MIT
Install
pip install jiminy-py==1.2.34

Documentation


License Version Python Downloads Try it in Binder Try it in Colab Try in in Deepnote Linux CI MacOS CI Windows CI

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, 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. 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 environments using one-liners. Jiminy provides both the physical engine and the robot model (including sensors) required for learning.
  • 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 raw binary or HDF5 format.
  • Dedicated integration in Google Colab, Jupyter Lab, Mybinder and VSCode working out-of-the-box - including interactive 3D viewer based on Meshcat. This facilitates working on remote environments.
  • Synchronous and single-threaded offscreen rendering capability, GPU-accelerated without graphical server, based on Panda3d.
  • Easy to install: pip is all that is needed to get you 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.
  • Compliant spherical joints with spring-damper dynamics to model mechanical deformation, a common phenomenon particularly in legged 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.

The documentation is available on Github.io, 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 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 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, Tianshou, or Rllib. Stable Baselines 3 and Tianshou use its counterpart Pytorch, 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, acrobot, pendulum, Ant, ANYmal, and Cassie, and Atlas.

Demo

Getting started

Jiminy and Gym Jiminy support Linux, Mac and Windows, and is compatible with Python3.8+. Pre-compiled binaries are distributed on PyPi. They can be installed using pip>=20.3:

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