diff --git a/docs/requirements.txt b/docs/requirements.txt index 53fc1f32e..7db1f079a 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,2 +1,4 @@ sphinx==7.1.2 sphinx-rtd-theme==1.3.0rc1 +sphinx_autodoc_typehints +sphinx_copybutton \ No newline at end of file diff --git a/docs/source/index.rst b/docs/source/index.rst index 060efba92..a0a791dfd 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,23 +1,103 @@ -Welcome to Lumache's documentation! -=================================== +JAXsim +====== -**Lumache** (/lu'make/) is a Python library for cooks and food lovers -that creates recipes mixing random ingredients. -It pulls data from the `Open Food Facts database `_ -and offers a *simple* and *intuitive* API. +A scalable physics engine implemented with JAX. With JIT batteries 🔋 -Check out the :doc:`usage` section for further information, including -how to :ref:`installation` the project. +.. warning:: + This project is still experimental, APIs could change without notice. ️⚠ -.. note:: +.. warning:: + This simulator currently focuses on locomotion applications. Only contacts with ground are supported. ️⚠ - This project is under active development. - -Contents +Features -------- -.. toctree:: +- Physics engine in reduced coordinates implemented with `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. +- Integrators: forward Euler, semi-implicit Euler, Runge-Kutta 4. +- High-level classes to compute multi-body dynamics quantities from simulation state. +- High-level classes supporting both object-oriented and functional programming. +- Optional validation of JAX pytrees to prevent JIT re-compilation. + +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`_, preferably in a `virtual environment`_: + +.. code-block:: bash + + pip install jaxsim + +Have a look to `setup.cfg`_ for a complete list of optional dependencies. +You can install all of them by specifying ``jaxsim[all]``. + +**Note:** if you need GPU support, please follow the official `installation instruction`_ of JAX. + +.. _pypa/pip: https://github.com/pypa/pip/ +.. _virtual environment: https://docs.python.org/3.8/tutorial/venv.html +.. _installation instruction: https://github.com/google/jax/#installation + +Credits +------- + +The physics module of JAXsim is based on the theory of the `Rigid Body Dynamics Algorithms`_ book authored by Roy Featherstone. +We structured part of our logic following its accompanying `code`_. +The physics engine is developed entirely in Python using `JAX`_. + +.. _Rigid Body Dynamics Algorithms: https://link.springer.com/book/10.1007/978-1-4899-7560-7 +.. _code: http://royfeatherstone.org/spatial/index.html#spatial-software + +The inspiration of developing JAXsim stems from `google/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`_. +- 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. + +.. _google/brax: https://github.com/google/brax +.. _Pose Frame Semantics: 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. + +Citing +------ + +.. code-block:: bibtex + + @software{ferigo_jaxsim_2022, + author = {Diego Ferigo and Silvio Traversaro and Daniele Pucci}, + title = {{JAXsim}: A Physics Engine in Reduced Coordinates for Control and Robot Learning}, + url = {http://github.com/ami-iit/jaxsin}, + year = {2022}, + } + +Maintainers +----------- + - usage - api +License +------- +`BSD3 `_ \ No newline at end of file diff --git a/docs/source/usage.rst b/docs/source/usage.rst index 924afcf6c..205d2dcb1 100644 --- a/docs/source/usage.rst +++ b/docs/source/usage.rst @@ -6,29 +6,29 @@ Usage Installation ------------ -To use Lumache, first install it using pip: +To use JAXsim, first install it using pip: .. code-block:: console - (.venv) $ pip install lumache + (.venv) $ pip install JAXsim -Creating recipes ----------------- +.. Creating recipes +.. ---------------- -To retrieve a list of random ingredients, -you can use the ``lumache.get_random_ingredients()`` function: +.. To retrieve a list of random ingredients, +.. you can use the ``lumache.get_random_ingredients()`` function: -.. autofunction:: lumache.get_random_ingredients +.. .. autofunction:: lumache.get_random_ingredients -The ``kind`` parameter should be either ``"meat"``, ``"fish"``, -or ``"veggies"``. Otherwise, :py:func:`lumache.get_random_ingredients` -will raise an exception. +.. The ``kind`` parameter should be either ``"meat"``, ``"fish"``, +.. or ``"veggies"``. Otherwise, :py:func:`lumache.get_random_ingredients` +.. will raise an exception. -.. autoexception:: lumache.InvalidKindError +.. .. autoexception:: lumache.InvalidKindError -For example: +.. For example: ->>> import lumache ->>> lumache.get_random_ingredients() -['shells', 'gorgonzola', 'parsley'] +.. >>> import lumache +.. >>> lumache.get_random_ingredients() +.. ['shells', 'gorgonzola', 'parsley']