diff --git a/docs/sphinx/breathe/core.rst b/docs/sphinx/breathe/core.rst index 8d5d29964..78933da2a 100644 --- a/docs/sphinx/breathe/core.rst +++ b/docs/sphinx/breathe/core.rst @@ -17,5 +17,7 @@ Core .. doxygenenum:: scenario::core::JointControlMode +.. doxygenenum:: scenario::core::JointType + .. doxygenfile:: core/utils/utils.h - :project: scenario \ No newline at end of file + :project: scenario diff --git a/docs/sphinx/breathe/gazebo.rst b/docs/sphinx/breathe/gazebo.rst index 2739dfffb..2be4996f2 100644 --- a/docs/sphinx/breathe/gazebo.rst +++ b/docs/sphinx/breathe/gazebo.rst @@ -29,9 +29,6 @@ Gazebo .. doxygenclass:: scenario::controllers::UseScenarioModel :members: -.. doxygenclass:: scenario::controllers::UseScenarioModel - :members: - .. doxygenclass:: scenario::controllers::SetJointReferences :members: diff --git a/docs/sphinx/getting_started/gym-ignition.rst b/docs/sphinx/getting_started/gym-ignition.rst index c98b714ce..f6fff0b29 100644 --- a/docs/sphinx/getting_started/gym-ignition.rst +++ b/docs/sphinx/getting_started/gym-ignition.rst @@ -27,6 +27,12 @@ Beyond the abstractions provided by ScenarIO, gym-ignition introduces the follow Refer to :py:class:`~gym_ignition.rbd.idyntree.inverse_kinematics_nlp.InverseKinematicsNLP` and :py:class:`~gym_ignition.rbd.idyntree.kindyncomputations.KinDynComputations` for more details. +.. tip:: + + If you want to learn more about ``iDynTree``, the two classes we mainly use are ``iDynTree::KinDynComputations`` (`docs `__) and ``iDynTree::InverseKinematics`` (`docs `__). + + The theory and notation is summarized in `Multibody dynamics notation `_. + You can find demo environments created with ``gym-ignition`` in the `gym_ignition_environments `_ folder. These examples show how to structure a new standalone Python package containing the environment with your robots. diff --git a/docs/sphinx/getting_started/scenario.rst b/docs/sphinx/getting_started/scenario.rst index 3fc69d888..b4bb48c3f 100644 --- a/docs/sphinx/getting_started/scenario.rst +++ b/docs/sphinx/getting_started/scenario.rst @@ -1,7 +1,7 @@ .. _getting_started_scenario: -ScenarI/O -========= +ScenarIO +======== In this getting started section we show how to use the Gazebo ScenarIO library to simulate a pendulum system. We will use the models of the ground plane and the pendulum stored in the repository diff --git a/docs/sphinx/index.rst b/docs/sphinx/index.rst index de12a98d0..b7f955cc0 100644 --- a/docs/sphinx/index.rst +++ b/docs/sphinx/index.rst @@ -1,40 +1,27 @@ -.. _what_is_gym_ignition: +.. _scenario_and_gym_ignition: -What is gym-ignition? -===================== +ScenarIO and gym-ignition +========================= -**gym-ignition is a framework to create reproducible robotics environments for reinforcement learning research.** +This project targets both *control* and *robot learning* research domains: -The aims of the project are the following: - -- Provide unified APIs for interfacing with both simulated and real robots. -- Implement the simulation backend interfacing with the Ignition Gazebo simulator. -- Enable a seamless switch of all the physics engines supported by Ignition Gazebo. -- Guarantee the reproducibility and the scalability of the simulations by using the simulator as a library, without - relying on any network transport. -- Simplify the development of OpenAI Gym environments for robot learning research. - -**gym-ignition** targets both *control* and *robot learning* research domains: - -- Researchers in robotics and control can simulate their robots with familiar tools like Gazebo and URDF, +- Researchers in robotics and control can simulate their robots with familiar tools like Gazebo and URDF/SDF, without the need to rely on any middleware. - Researchers in robot learning can quickly develop new robotic environments that can scale to hundreds of parallel instances. -To know more about why we started developing gym-ignition, why we selected Ignition Gazebo for our simulations, -and what are our long-term goals, visit the :ref:`Motivations ` page. +We provide two related subprojects to each of these categories: -We are building an entire ecosystem around gym-ignition, if you're interested have a look to the other projects: +1. **ScenarIO** provides APIs to interface with the robots. +2. **gym-ignition** helps structuring environments compatible with OpenAI Gym, + while minimizing boilerplate code and providing common rigid-body dynamics utilities. -.. list-table:: - :header-rows: 1 - :align: center +Check the sections :ref:`What is ScenarIO ` and +:ref:`What is gym-ignition ` for more details, +and visit :ref:`Motivations ` for an extended overview. + +For a quick practical introduction, visit the :ref:`Getting Started ` page. - * - ScenarI/O and ``gym_ignition`` - - Robot Models - - Ignition Plugins - * - `robotology/gym-ignition `_ - - `robotology/gym-ignition-models `_ - - `dic-iit/gazebo-scenario-plugins `_ +If you use this project for your research, please check the FAQ about :ref:`how to give credit `. .. list-table:: @@ -49,14 +36,22 @@ We are building an entire ecosystem around gym-ignition, if you're interested ha .. toctree:: :hidden: :maxdepth: 1 - :caption: Motivations + :caption: What + + what/what_is_scenario + what/what_is_gym_ignition + +.. toctree:: + :hidden: + :maxdepth: 1 + :caption: Why - motivations/why_gym_ignition + motivations/motivations .. toctree:: :hidden: :maxdepth: 1 - :caption: Installation + :caption: Installation (How) installation/support_policy installation/stable diff --git a/docs/sphinx/info/faq.rst b/docs/sphinx/info/faq.rst index 9db8a47ba..3ee90db29 100644 --- a/docs/sphinx/info/faq.rst +++ b/docs/sphinx/info/faq.rst @@ -1,6 +1,26 @@ FAQ === +.. _faq_citation: + +How to give credit? +------------------- + +If you use **ScenarIO** or **gym-ignition** for your research, +please cite the following reference: + +.. code-block:: bibtex + :caption: BibTeX entry + + @INPROCEEDINGS{ferigo2020gymignition, + title={Gym-Ignition: Reproducible Robotic Simulations for Reinforcement Learning}, + author={D. {Ferigo} and S. {Traversaro} and G. {Metta} and D. {Pucci}}, + booktitle={2020 IEEE/SICE International Symposium on System Integration (SII)}, + year={2020}, + pages={885-890}, + doi={10.1109/SII46433.2020.9025951} + } + Interaction with Tensorflow --------------------------- diff --git a/docs/sphinx/installation/developer.rst b/docs/sphinx/installation/developer.rst index bf7524863..66a987e29 100644 --- a/docs/sphinx/installation/developer.rst +++ b/docs/sphinx/installation/developer.rst @@ -33,20 +33,23 @@ the CMake project as follows: .. code-block:: bash - mkdir build - cd build - cmake .. - cmake --build . - cmake --build . --target install + cd scenario/ + cmake -S . -B build + cmake --build build/ + cmake --build build/ --target install .. note:: + The default install prefix of the CMake project is ``/usr/local``. If you want to use a different folder, pass ``-DCMAKE_INSTALL_PREFIX=/new/install/prefix`` to the first ``cmake`` command. .. attention:: - The SWIG bindings are installed in the `site-packages `_ folder of the active Python interpreter. + + The SWIG bindings are installed in the `site-packages `_ + folder of the active Python interpreter. If you have an active virtual environment, it will be automatically detected. - Visit `FindPython3 `_ for more details. + We rely on CMake's logic for detecting Python, + visit `FindPython3 `_ for more details. .. include:: virtual_environment.rst @@ -58,10 +61,18 @@ From the root of the repository: .. code-block:: bash + pip install -e scenario/ pip install -e . The editable installation only symlinks the resources of the repository into the active Python installation. It allows to develop directly operating on the files of the repository and use the updated package without requiring to install it again. +.. note:: + + The ``scenario`` editable installation is just a placeholder. + It is necessary to prevent the editable installation of ``gym-ignition`` to override the resources installed by + the manual CMake execution. + Otherwise, the ``scenar-io`` package from PyPI would be pulled, resulting with a wrong version. + .. include:: system_configuration.rst diff --git a/docs/sphinx/installation/nightly.rst b/docs/sphinx/installation/nightly.rst index 8991bbcda..e23e1245b 100644 --- a/docs/sphinx/installation/nightly.rst +++ b/docs/sphinx/installation/nightly.rst @@ -13,10 +13,23 @@ We publish updated nightly packages after any pull request merged in the ``devel PyPI Package ************ -Install the pre-release `gym-ignition `_ package from PyPI: +We provide two different packages for ScenarIO and gym-ignition. + +If you are interested in the ScenarIO package, +install the `scenar-io `_ package from PyPI: + +.. code-block:: bash + + pip install --pre scenar-io + +Instead, if you are interested in gym-ignition, +install the `gym-ignition `_ package from PyPI: .. code-block:: bash - pip install --pre gym-ignition + pip install --pre scenar-io gym-ignition + +Note that in this case, specifying also the ``scenar-io`` dependency is necessary, +otherwise ``pip`` will pull the stable package from PyPI. .. include:: system_configuration.rst diff --git a/docs/sphinx/installation/optional_dependencies.rst b/docs/sphinx/installation/optional_dependencies.rst deleted file mode 100644 index b9343c9af..000000000 --- a/docs/sphinx/installation/optional_dependencies.rst +++ /dev/null @@ -1,21 +0,0 @@ -.. _installation_optional_dependencies: - -Optional Dependencies -===================== - -.. _installation_optional_dependencies_idyntree: - -iDynTree -******** - -**gym-ignition** provides helper classes to manipulate the kinematics and the dynamics of rigid-bodies. -Among the many existing solutions, we selected `iDynTree `_. - -Follow the `official installation instructions `__ and make sure that you also enable and install the `Python bindings `__. - -You can verify that the installation succeeded and your system is properly configured if you can ``import iDynTree`` in a Python interpreter. - -.. tip:: - If you want to learn more about ``iDynTree``, the two classes we mainly use are ``iDynTree::KinDynComputations`` (`docs `__) and ``iDynTree::InverseKinematics`` (`docs `__). - - The theory and notation behind the library is summarized in `Multibody dynamics notation `_. \ No newline at end of file diff --git a/docs/sphinx/installation/stable.rst b/docs/sphinx/installation/stable.rst index 08f4ed6a0..06e6a002e 100644 --- a/docs/sphinx/installation/stable.rst +++ b/docs/sphinx/installation/stable.rst @@ -13,8 +13,20 @@ We publish updated stable packages after any tagged release of the ``master`` br PyPI Package ************ -Install the `gym-ignition `_ package from PyPI: +We provide two different packages for ScenarIO and gym-ignition. + +If you are interested in the ScenarIO package, +install the `scenar-io `_ package from PyPI: + +.. code-block:: bash + + pip install scenar-io + +Instead, if you are interested in gym-ignition, +install the `gym-ignition `_ package from PyPI: .. code-block:: bash pip install gym-ignition + +It will download and install also ``scenar-io`` since it depends on it. diff --git a/docs/sphinx/installation/support_policy.rst b/docs/sphinx/installation/support_policy.rst index b2270f13b..b3b2b8555 100644 --- a/docs/sphinx/installation/support_policy.rst +++ b/docs/sphinx/installation/support_policy.rst @@ -8,7 +8,7 @@ dependencies, depending on the installation type you select. The project mostly supports all the major operating systems. However, we are currently using and testing only GNU/Linux systems. -We do not yet provide direct support to other operating systems. +We do not yet provide official support to other operating systems. The table below recaps the project requirements of the :ref:`Stable ` and :ref:`Nightly ` channels: @@ -31,12 +31,12 @@ The table below recaps the project requirements of the :ref:`Stable `_ are no longer accurate. -This section provides a constantly updated description aligned with the most recent development news. +:ref:`reference publication ` are becoming outdated. +While that publication remains the reference in case you use the project for your research, +this section provides a constantly updated description aligned with the most recent development news. .. _why_scenario: @@ -36,16 +37,18 @@ it will interact either with the simulated or the real robot depending on the Sc .. note:: The ScenarIO interface is flexible and generic. - Let's say you already have built your functionality with the backends we provide, and you are not happy from the performance of the simulator we used. + Let's say you already have built your functionality with the backends we provide, + and you are not happy from the performance of the simulator we used. You can implement your own simulation backend and run it alongside those we provide. The same applies to the real-time backend, in case your robot uses a custom middleware or SDK. -.. tip: +.. tip:: So far, we always referred to the C++ abstraction layer provided by ScenarIO. The interface / implementation pattern is implemented with classic inheritance and polymorphism. Having such unified interface simplifies the process to expose it to other languages. - Thanks to SWIG, we officially provide Python bindings of ScenarIO, so that you can prototype your applications even faster! + Thanks to SWIG, we officially provide Python bindings of ScenarIO, + so that you can prototype your applications even faster! .. _why_ignition_gazebo: @@ -67,7 +70,7 @@ The price to pay, instead, is that Ignition Gazebo has not yet reached feature p the gap is getting filled quickly. .. [*] Yes, you read correctly: *library*. Ignition Gazebo is a library. - A `ignition::gazebo::Server` object can be instantiated and it can be stepped programmatically from your code. + A ``ignition::gazebo::Server`` object can be instantiated and it can be stepped programmatically from your code. This type of architecture became quite popular recently because it gives you full control of the simulation. Ignition Gazebo, therefore, became a solution similar to the well known alternatives like ``pybullet`` and ``mujoco-py``. diff --git a/docs/sphinx/what/what_is_gym_ignition.rst b/docs/sphinx/what/what_is_gym_ignition.rst new file mode 100644 index 000000000..a487cbbd3 --- /dev/null +++ b/docs/sphinx/what/what_is_gym_ignition.rst @@ -0,0 +1,22 @@ +.. _what_is_gym_ignition: + +What is gym-ignition? +===================== + +**gym-ignition** is a framework to create **reproducible robotics environments** for reinforcement learning research. + +It is based on the :ref:`ScenarIO ` project which provides the low-level APIs to interface with the Ignition Gazebo simulator. +By default, RL environments share a lot of boilerplate code, e.g. for initializing the simulator or structuring the classes +to expose the ``gym.Env`` interface. +Gym-ignition provides the :py:class:`~gym_ignition.base.task.Task` and :py:class:`~gym_ignition.base.runtime.Runtime` +abstractions that help you focusing on the development of the decision-making logic rather than engineering. +It includes :py:mod:`~gym_ignition.randomizers` to simplify the implementation of domain randomization +of models, physics, and tasks. +Gym-ignition also provides powerful dynamics algorithms compatible with both fixed-base and floating-based robots by +exploiting `iDynTree `_ and exposing +high-level functionalities (:py:mod:`~gym_ignition.rbd.idyntree`). + +Gym-ignition does not provide out-of-the-box environments ready to be used. +Rather, its aim is simplifying and streamlining their development. +Nonetheless, for illustrative purpose, it includes canonical examples in the +:py:mod:`gym_ignition_environments` package. diff --git a/docs/sphinx/what/what_is_scenario.rst b/docs/sphinx/what/what_is_scenario.rst new file mode 100644 index 000000000..060a581d5 --- /dev/null +++ b/docs/sphinx/what/what_is_scenario.rst @@ -0,0 +1,31 @@ +.. _what_is_scenario: + +What is ScenarIO +================ + +**ScenarIO** is a C++ abstraction layer to interact with simulated and real robots. + +It mainly provides the following +`C++ interfaces `_: + +- :cpp:class:`scenario::core::World` +- :cpp:class:`scenario::core::Model` +- :cpp:class:`scenario::core::Link` +- :cpp:class:`scenario::core::Joint` + +These interfaces can be implemented to operate on different scenarios, +including robots operating on either simulated worlds or in real-time. + +ScenarIO currently fully implements **Gazebo ScenarIO** (APIs), +a simulated back-end that interacts with `Ignition Gazebo `_. +The result allows stepping the simulator programmatically, ensuring a fully reproducible behaviour. +It relates closely to other projects like +`pybullet `_ and `mujoco-py `_. + +A real-time backend that interacts with the `YARP `_ middleware is under development. + +ScenarIO can be used either from C++ (:ref:`Core APIs `, :ref:`Gazebo APIs `) +or from Python (:py:mod:`~scenario.bindings.core`, :py:mod:`~scenario.bindings.gazebo`). + +If you're interested to know the reasons why we started developing ScenarIO and why we selected Ignition Gazebo +for our simulations, visit the :ref:`Motivations ` section.