Skip to content

Commit

Permalink
docs: update docs (#62)
Browse files Browse the repository at this point in the history
Co-authored-by: Jiaming Ji <[email protected]>
  • Loading branch information
muchvo and zmsn-2077 authored Aug 20, 2023
1 parent c916674 commit 95d9a59
Show file tree
Hide file tree
Showing 116 changed files with 4,600 additions and 91 deletions.
1 change: 1 addition & 0 deletions .pre-commit-config.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@ repos:
- id: check-added-large-files
exclude: |
(?x)(
^docs/_static/images/
^safety_gymnasium/tasks/safe_issac_gym/assets/|
^safety_gymnasium/assets/meshes/|
^safety_gymnasium/assets/textures/|
Expand Down
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -134,8 +134,8 @@ Here are some screenshots of the Safe Navigation tasks.
<td>
<figure class="align-default">
<a class="reference external image-reference" href="agents/doggo.html"><img
alt="https://github.com/zmsn-2077/safety-gymnasium-zmsn/raw/HEAD/images/doggo_front.jpeg"
src="https://github.com/zmsn-2077/safety-gymnasium-zmsn/raw/HEAD/images/doggo_front.jpeg"
alt="https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/images/doggo_front.jpeg"
src="https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/images/doggo_front.jpeg"
style="width: 130px;"></a>
</figure>
<p class="centered">
Expand Down
Binary file added docs/_static/images/ant_multi_goal0.jpeg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/_static/images/ant_multi_goal1.jpeg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/_static/images/ant_multi_goal2.jpeg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/_static/images/ant_vel.jpeg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/_static/images/ant_vel_safe.gif
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/_static/images/ant_vel_unsafe.gif
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/_static/images/building_button0.jpeg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/_static/images/building_button1.jpeg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/_static/images/building_button2.jpeg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/_static/images/building_goal0.jpeg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/_static/images/building_goal1.jpeg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/_static/images/building_goal2.jpeg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/_static/images/building_push0.jpeg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/_static/images/building_push1.jpeg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/_static/images/building_push2.jpeg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/_static/images/doggo_back.jpeg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/_static/images/doggo_front.jpeg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/_static/images/doggo_left.jpeg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/_static/images/doggo_right.jpeg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/_static/images/fading_easy0.gif
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/_static/images/fading_easy1.gif
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/_static/images/fading_easy2.gif
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/_static/images/fading_hard0.gif
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/_static/images/fading_hard1.gif
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/_static/images/fading_hard2.gif
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/_static/images/fixedwalls.jpeg
Binary file added docs/_static/images/formula_one0.jpeg
Binary file added docs/_static/images/formula_one1.jpeg
Binary file added docs/_static/images/formula_one2.jpeg
Binary file added docs/_static/images/freight_franka_back.jpeg
Binary file added docs/_static/images/freight_franka_front.jpeg
Binary file added docs/_static/images/freight_franka_left.jpeg
Binary file added docs/_static/images/freight_franka_right.jpeg
Binary file added docs/_static/images/half_cheetah_vel.jpeg
Binary file added docs/_static/images/half_cheetah_vel_safe.gif
Binary file added docs/_static/images/half_cheetah_vel_unsafe.gif
Binary file added docs/_static/images/hopper_vel.jpeg
Binary file added docs/_static/images/hopper_vel_safe.gif
Binary file added docs/_static/images/hopper_vel_unsafe.gif
Binary file added docs/_static/images/humanoid_vel.jpeg
Binary file added docs/_static/images/humanoid_vel_safe.gif
Binary file added docs/_static/images/humanoid_vel_unsafe.gif
Binary file added docs/_static/images/multi_ant.jpeg
Binary file added docs/_static/images/multi_point.jpeg
Binary file added docs/_static/images/point_multi_goal0.jpeg
Binary file added docs/_static/images/point_multi_goal1.jpeg
Binary file added docs/_static/images/point_multi_goal2.jpeg
Binary file added docs/_static/images/race0.jpeg
Binary file added docs/_static/images/race1.jpeg
Binary file added docs/_static/images/race2.jpeg
Binary file added docs/_static/images/shadow_hand_back.jpeg
Binary file added docs/_static/images/shadow_hand_dof.jpg
Binary file added docs/_static/images/shadow_hand_front.jpeg
Binary file added docs/_static/images/shadow_hand_left.jpeg
Binary file added docs/_static/images/shadow_hand_right.jpeg
Binary file added docs/_static/images/shadow_hand_safe_finger.jpg
Binary file added docs/_static/images/shadow_hand_safe_joint.jpg
Binary file added docs/_static/images/swimmer_vel.jpeg
Binary file added docs/_static/images/swimmer_vel_safe.gif
Binary file added docs/_static/images/swimmer_vel_unsafe.gif
Binary file added docs/_static/images/walker2d_vel.jpeg
Binary file added docs/_static/images/walker2d_vel_safe.gif
Binary file added docs/_static/images/walker2d_vel_unsafe.gif
108 changes: 103 additions & 5 deletions docs/components_of_environments/agents.rst
Original file line number Diff line number Diff line change
@@ -1,6 +1,11 @@
Agents
======

A set of unified agents for tasks has been designed, which are an important part of the environment. Their features are described in detail in this section.

Safe Navigation & Vision
------------------------

.. list-table::

* - .. figure:: ../_static/images/point_front.jpeg
Expand All @@ -11,28 +16,121 @@ Agents
:width: 230px
:target: agents/car.html
.. centered:: :doc:`agents/car`
- .. figure:: ../_static/images/racecar_front.jpeg
- .. figure:: ../_static/images/doggo_front.jpeg
:width: 230px
:target: agents/doggo.html
.. centered:: :doc:`agents/doggo`
* - .. figure:: ../_static/images/racecar_front.jpeg
:width: 230px
:target: agents/racecar.html
.. centered:: :doc:`agents/racecar`
* - .. figure:: ../_static/images/ant_front.jpeg
- .. figure:: ../_static/images/ant_front.jpeg
:width: 230px
:target: agents/ant.html
.. centered:: :doc:`agents/ant`
- .. figure:: ../_static/images/coming_soon.png
:width: 230px
.. centered:: Coming soon...
- .. figure:: ../_static/images/coming_soon.png

Safe Velocity
-------------

.. list-table::

* - .. figure:: ../_static/images/ant_vel.jpeg
:width: 230px
.. centered:: Coming soon...
:target: https://gymnasium.farama.org/environments/mujoco/ant/
.. centered:: `Ant <https://gymnasium.farama.org/environments/mujoco/ant/>`_
- .. figure:: ../_static/images/half_cheetah_vel.jpeg
:width: 230px
:target: https://gymnasium.farama.org/environments/mujoco/half-cheetah/
.. centered:: `HalfCheetah <https://gymnasium.farama.org/environments/mujoco/half-cheetah/>`_
- .. figure:: ../_static/images/hopper_vel.jpeg
:width: 230px
:target: https://gymnasium.farama.org/environments/mujoco/hopper/
.. centered:: `Hopper <https://gymnasium.farama.org/environments/mujoco/hopper/>`_
* - .. figure:: ../_static/images/humanoid_vel.jpeg
:width: 230px
:target: https://gymnasium.farama.org/environments/mujoco/humanoid/
.. centered:: `Humanoid <https://gymnasium.farama.org/environments/mujoco/humanoid/>`_
- .. figure:: ../_static/images/swimmer_vel.jpeg
:width: 230px
:target: https://gymnasium.farama.org/environments/mujoco/swimmer/
.. centered:: `Swimmer <https://gymnasium.farama.org/environments/mujoco/swimmer/>`_
- .. figure:: ../_static/images/walker2d_vel.jpeg
:width: 230px
:target: https://gymnasium.farama.org/environments/mujoco/walker2d/
.. centered:: `Walker2d <https://gymnasium.farama.org/environments/mujoco/walker2d/>`_

Safe Multi-Agent
----------------

.. list-table::

* - .. figure:: ../_static/images/multi_point.jpeg
:width: 230px
:target: agents/point.html
.. centered:: :ref:`Multi-Point <Point>`
- .. figure:: ../_static/images/multi_ant.jpeg
:width: 230px
:target: agents/ant.html
.. centered:: :ref:`Multi-Ant <Ant>`
* - .. figure:: ../_static/images/freight_franka_front.jpeg
:width: 230px
:target: agents/freight_franka.html
.. centered:: :doc:`agents/freight_franka`
- .. figure:: ../_static/images/shadow_hand_front.jpeg
:width: 230px
:target: agents/shadowhands.html
.. centered:: :doc:`agents/shadowhands`
* - .. figure:: ../_static/images/ant_vel.jpeg
:width: 230px
:target: https://robotics.farama.org/envs/MaMuJoCo/ma_ant/
.. centered:: `MA-Ant <https://robotics.farama.org/envs/MaMuJoCo/ma_ant/>`_
- .. figure:: ../_static/images/half_cheetah_vel.jpeg
:width: 230px
:target: https://robotics.farama.org/envs/MaMuJoCo/ma_half_cheetah/
.. centered:: `MA-HalfCheetah <https://robotics.farama.org/envs/MaMuJoCo/ma_half_cheetah/>`_
* - .. figure:: ../_static/images/hopper_vel.jpeg
:width: 230px
:target: https://robotics.farama.org/envs/MaMuJoCo/ma_hopper/
.. centered:: `MA-Hopper <https://robotics.farama.org/envs/MaMuJoCo/ma_hopper/>`_
- .. figure:: ../_static/images/humanoid_vel.jpeg
:width: 230px
:target: https://robotics.farama.org/envs/MaMuJoCo/ma_humanoid/
.. centered:: `MA-Humanoid <https://robotics.farama.org/envs/MaMuJoCo/ma_humanoid/>`_
* - .. figure:: ../_static/images/swimmer_vel.jpeg
:width: 230px
:target: https://robotics.farama.org/envs/MaMuJoCo/ma_swimmer/
.. centered:: `MA-Swimmer <https://robotics.farama.org/envs/MaMuJoCo/ma_swimmer/>`_
- .. figure:: ../_static/images/walker2d_vel.jpeg
:width: 230px
:target: https://robotics.farama.org/envs/MaMuJoCo/ma_walker2d/
.. centered:: `MA-Walker2d <https://robotics.farama.org/envs/MaMuJoCo/ma_walker2d/>`_


Safe Isaac Gym
--------------

We have designed a set of unified agents for tasks, which are an important part of the environment. Its features are described in detail in this section.
.. list-table::

* - .. figure:: ../_static/images/freight_franka_front.jpeg
:width: 230px
:target: agents/freight_franka.html
.. centered:: :doc:`agents/freight_franka`
- .. figure:: ../_static/images/shadow_hand_front.jpeg
:width: 230px
:target: agents/shadowhands.html
.. centered:: :doc:`agents/shadowhands`


.. toctree::
:hidden:

agents/point.rst
agents/car.rst
agents/doggo.rst
agents/racecar.rst
agents/ant.rst
agents/freight_franka.rst
agents/shadowhands.rst
20 changes: 11 additions & 9 deletions docs/components_of_environments/agents/ant.rst
Original file line number Diff line number Diff line change
@@ -1,6 +1,8 @@
Ant
===

.. _Ant:

.. list-table::

* - .. figure:: ../../_static/images/ant_front.jpeg
Expand All @@ -19,15 +21,15 @@ Ant

A quadrupedal robot, based on the model proposed in `High-Dimensional Continuous Control Using Generalized Advantage Estimation <https://arxiv.org/abs/1506.02438>`__. Moving in three dimensions, it consists of a torso and four legs connected together, each leg consisting of two hinged connecting limbs, which are at the same time connected to the torso by hinges. It is necessary to coordinate the movement of the four legs in the target direction by applying moments to the drivers of the eight hinges.

+-----------------------------+--------------------------------+
| Specific Action Space | Box(-1.0, 1.0, (8,), float64) |
+=============================+================================+
| Specific Observation Shape | (40,) |
+-----------------------------+--------------------------------+
| Observation High | inf |
+-----------------------------+--------------------------------+
| Observation Low | -inf |
+-----------------------------+--------------------------------+
+---------------------------------+--------------------------------+
| **Specific Action Space** | Box(-1.0, 1.0, (8,), float64) |
+---------------------------------+--------------------------------+
| **Specific Observation Shape** | (40,) |
+---------------------------------+--------------------------------+
| **Specific Observation High** | inf |
+---------------------------------+--------------------------------+
| **Specific Observation Low** | -inf |
+---------------------------------+--------------------------------+


Specific Action Space
Expand Down
18 changes: 9 additions & 9 deletions docs/components_of_environments/agents/car.rst
Original file line number Diff line number Diff line change
Expand Up @@ -18,15 +18,15 @@ Car

A slightly more complex robot, moving in three dimensions, has two independently driven parallel wheels and one free-rolling rear wheel. For this robot, both steering and forward/backward movement require coordination of the two drives. It is similar in design to a simple robot used for educational purposes.

+-----------------------------+--------------------------------+
| Specific Action Space | Box(-1.0, 1.0, (2,), float64) |
+=============================+================================+
| Specific Observation Shape | (24,) |
+-----------------------------+--------------------------------+
| Observation High | inf |
+-----------------------------+--------------------------------+
| Observation Low | -inf |
+-----------------------------+--------------------------------+
+---------------------------------+--------------------------------+
| **Specific Action Space** | Box(-1.0, 1.0, (2,), float64) |
+---------------------------------+--------------------------------+
| **Specific Observation Shape** | (24,) |
+---------------------------------+--------------------------------+
| **Specific Observation High** | inf |
+---------------------------------+--------------------------------+
| **Specific Observation Low** | -inf |
+---------------------------------+--------------------------------+


Specific Action Space
Expand Down
88 changes: 88 additions & 0 deletions docs/components_of_environments/agents/doggo.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,88 @@
Doggo
=====

.. list-table::

* - .. figure:: ../../_static/images/doggo_front.jpeg
:width: 200px
.. centered:: front
- .. figure:: ../../_static/images/doggo_back.jpeg
:width: 200px
.. centered:: back
- .. figure:: ../../_static/images/doggo_left.jpeg
:width: 200px
.. centered:: left
- .. figure:: ../../_static/images/doggo_right.jpeg
:width: 200px
.. centered:: right

Doggo is a quadrupedal robot with bilateral symmetry. Each of the four legs has two controls at the hip, for azimuth and elevation relative to the torso, and one in the knee, controlling angle. It is designed such that a uniform random policy should keep the robot from falling over and generate some travel.

+---------------------------------+--------------------------------+
| **Specific Action Space** | Box(-1.0, 1.0, (12,), float64) |
+---------------------------------+--------------------------------+
| **Specific Observation Shape** | (12,) |
+---------------------------------+--------------------------------+
| **Specific Observation High** | inf |
+---------------------------------+--------------------------------+
| **Specific Observation Low** | -inf |
+---------------------------------+--------------------------------+


Specific Action Space
---------------------

+-----+---------------------------------------------------------------------------------+-------------+-------------+----------------------------------+------------+--------------+
| Num | Action | Control Min | Control Max | Name (in corresponding XML file) | Joint/Site | Unit |
+=====+=================================================================================+=============+=============+==================================+============+==============+
| 0 | torque applied on the rotor between the torso and front left hip around z-axis | -1 | 1 | hip_1_z | hinge | torque (N m) |
+-----+---------------------------------------------------------------------------------+-------------+-------------+----------------------------------+------------+--------------+
| 1 | torque applied on the rotor between the torso and back left hip around z-axis | -1 | 1 | hip_2_z | hinge | torque (N m) |
+-----+---------------------------------------------------------------------------------+-------------+-------------+----------------------------------+------------+--------------+
| 2 | torque applied on the rotor between the torso and back right hip around z-axis | -1 | 1 | hip_3_z | hinge | torque (N m) |
+-----+---------------------------------------------------------------------------------+-------------+-------------+----------------------------------+------------+--------------+
| 3 | torque applied on the rotor between the torso and front right hip around z-axis | -1 | 1 | hip_4_z | hinge | torque (N m) |
+-----+---------------------------------------------------------------------------------+-------------+-------------+----------------------------------+------------+--------------+
| 4 | torque applied on the rotor between the torso and front left hip around y-axis | -1 | 1 | hip_1_y | hinge | torque (N m) |
+-----+---------------------------------------------------------------------------------+-------------+-------------+----------------------------------+------------+--------------+
| 5 | torque applied on the rotor between the torso and back left hip around y-axis | -1 | 1 | hip_2_y | hinge | torque (N m) |
+-----+---------------------------------------------------------------------------------+-------------+-------------+----------------------------------+------------+--------------+
| 6 | torque applied on the rotor between the torso and back right hip around y-axis | -1 | 1 | hip_3_y | hinge | torque (N m) |
+-----+---------------------------------------------------------------------------------+-------------+-------------+----------------------------------+------------+--------------+
| 7 | torque applied on the rotor between the torso and front right hip around y-axis | -1 | 1 | hip_4_y | hinge | torque (N m) |
+-----+---------------------------------------------------------------------------------+-------------+-------------+----------------------------------+------------+--------------+
| 8 | torque applied on the rotor between the front left two links | -1 | 1 | ankle_1 | hinge | torque (N m) |
+-----+---------------------------------------------------------------------------------+-------------+-------------+----------------------------------+------------+--------------+
| 9 | torque applied on the rotor between the back left two links | -1 | 1 | ankle_2 | hinge | torque (N m) |
+-----+---------------------------------------------------------------------------------+-------------+-------------+----------------------------------+------------+--------------+
| 10 | torque applied on the rotor between the back right two links | -1 | 1 | ankle_3 | hinge | torque (N m) |
+-----+---------------------------------------------------------------------------------+-------------+-------------+----------------------------------+------------+--------------+
| 11 | torque applied on the rotor between the front right two links | -1 | 1 | ankle_4 | hinge | torque (N m) |
+-----+---------------------------------------------------------------------------------+-------------+-------------+----------------------------------+------------+--------------+


Specific Observation Space
--------------------------

+-------+----------------+------+------+-----------------------------------+-------------+----------------------------+
| Size | Observation | Min | Max | Name (in corresponding XML file) | Joint/Site | Unit |
+=======+================+======+======+===================================+=============+============================+
| 3 | accelerometer | -inf | inf | accelerometer | site | acceleration (m/s^2) |
+-------+----------------+------+------+-----------------------------------+-------------+----------------------------+
| 3 | velocimeter | -inf | inf | velocimeter | site | velocity (m/s) |
+-------+----------------+------+------+-----------------------------------+-------------+----------------------------+
| 3 | gyro | -inf | inf | gyro | site | anglular velocity (rad/s) |
+-------+----------------+------+------+-----------------------------------+-------------+----------------------------+
| 3 | magnetometer | -inf | inf | magnetometer | site | magnetic flux (Wb) |
+-------+----------------+------+------+-----------------------------------+-------------+----------------------------+


Specific Starting Randomness
----------------------------

Nothing.

Specific Episode End
--------------------

Nothing.
Loading

0 comments on commit 95d9a59

Please sign in to comment.