[Docs] Code tutorials

.gitignore

@@ -2,6 +2,7 @@
 docs/output/
 docs/source/generated/
 docs/build/
+docs/source/sg_execution_times.rst
 
 ### JetBrains template
 # Covers JetBrains IDEs: IntelliJ, RubyMine, PhpStorm, AppCode, PyCharm, CLion, Android Studio, WebStorm and Rider

docs/requirements.txt

@@ -4,3 +4,5 @@ torch
 pyglet<=1.5.27
 gym
 six
+sphinx-gallery
+memory_profiler

docs/source/conf.py

@@ -29,13 +29,33 @@
     "sphinx.ext.napoleon",
     "sphinx.ext.intersphinx",
     "sphinx.ext.viewcode",
+    "sphinx_gallery.gen_gallery",
     "patch",
 ]
 
 add_module_names = False
 autodoc_member_order = "bysource"
 toc_object_entries = False
 
+sphinx_gallery_conf = {
+    "examples_dirs": [
+        "../../tutorials",
+        "../../tutorials/environment",
+        "../../tutorials/scenario",
+        "../../tutorials/simulator",
+    ],  # path to your example scripts
+    "gallery_dirs": [
+        "generated/tutorials",
+        "generated/tutorials/environment",
+        "generated/tutorials/scenario",
+        "generated/tutorials/simulator",
+    ],  # path to where to save gallery generated output
+    "doc_module": ("vmas",),
+    "filename_pattern": ".*",  # files to parse
+    # "notebook_images": "reference/generated/tutorials/media/",  # images to parse
+    "show_memory": True,
+}
+
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3/", None),
     "sphinx": ("https://www.sphinx-doc.org/en/master/", None),

docs/source/index.rst

@@ -43,9 +43,15 @@ Forthcoming doc sections:
    usage/running
    usage/citing
 
+
 .. toctree::
    :maxdepth: 1
-   :caption: Concepts
+   :caption: Tutorials
+
+   generated/tutorials/index
+   generated/tutorials/environment/index
+   generated/tutorials/scenario/index
+   generated/tutorials/simulator/index
 
 
 .. toctree::

tutorials/README.rst

@@ -0,0 +1,4 @@
+All tutorials
+=============
+
+Below is a gallery of examples

tutorials/environment/README.rst

@@ -0,0 +1,4 @@
+Environment
+-----------
+
+Below is a gallery of examples

tutorials/environment/communication_actions.py

@@ -0,0 +1,52 @@
+#  Copyright (c) 2024.
+#  ProrokLab (https://www.proroklab.org/)
+#  All rights reserved.
+
+"""
+Data download example
+=====================
+
+This example shows one way of dealing with large data files required for your
+examples.
+
+The ``download_data`` function first checks if the data has already been
+downloaded, looking in either the data directory saved the configuration file
+(by default ``~/.sg_template``) or the default data directory. If the data has
+not already been downloaded, it downloads the data from the url and saves the
+data directory to the configuration file. This allows you to use the data
+again in a different example without downloading it again.
+
+Note that examples in the gallery are ordered according to their filenames, thus
+the number after 'plot_' dictates the order the example appears in the gallery.
+"""
+
+
+######################################################################
+# Define Hyperparameters
+# ----------------------
+#
+# We set the hyperparameters for our tutorial.
+# Depending on the resources
+# available, one may choose to execute the policy and the simulator on GPU or on another
+# device.
+# You can tune some of these values to adjust the computational requirements.
+#
+
+import vmas
+
+env = vmas.make_env("dispersion", num_envs=3)
+env.get_random_actions()
+
+######################################################################
+# Define dwdwd
+# ----------------------
+#
+# We set the hyperparameters for our tutorial.
+# Depending on the resources
+# available, one may choose to execute the policy and the simulator on GPU or on another
+# device.
+# You can tune some of these values to adjust the computational requirements.
+#
+
+env = vmas.make_env("dispersion", num_envs=3)
+env.get_random_actions()

tutorials/environment/differentiability.py

@@ -0,0 +1,52 @@
+#  Copyright (c) 2024.
+#  ProrokLab (https://www.proroklab.org/)
+#  All rights reserved.
+
+"""
+Data download example
+=====================
+
+This example shows one way of dealing with large data files required for your
+examples.
+
+The ``download_data`` function first checks if the data has already been
+downloaded, looking in either the data directory saved the configuration file
+(by default ``~/.sg_template``) or the default data directory. If the data has
+not already been downloaded, it downloads the data from the url and saves the
+data directory to the configuration file. This allows you to use the data
+again in a different example without downloading it again.
+
+Note that examples in the gallery are ordered according to their filenames, thus
+the number after 'plot_' dictates the order the example appears in the gallery.
+"""
+
+
+######################################################################
+# Define Hyperparameters
+# ----------------------
+#
+# We set the hyperparameters for our tutorial.
+# Depending on the resources
+# available, one may choose to execute the policy and the simulator on GPU or on another
+# device.
+# You can tune some of these values to adjust the computational requirements.
+#
+
+import vmas
+
+env = vmas.make_env("dispersion", num_envs=3)
+env.get_random_actions()
+
+######################################################################
+# Define dwdwd
+# ----------------------
+#
+# We set the hyperparameters for our tutorial.
+# Depending on the resources
+# available, one may choose to execute the policy and the simulator on GPU or on another
+# device.
+# You can tune some of these values to adjust the computational requirements.
+#
+
+env = vmas.make_env("dispersion", num_envs=3)
+env.get_random_actions()

tutorials/environment/interactive_rendering.py

@@ -0,0 +1,52 @@
+#  Copyright (c) 2024.
+#  ProrokLab (https://www.proroklab.org/)
+#  All rights reserved.
+
+"""
+Data download example
+=====================
+
+This example shows one way of dealing with large data files required for your
+examples.
+
+The ``download_data`` function first checks if the data has already been
+downloaded, looking in either the data directory saved the configuration file
+(by default ``~/.sg_template``) or the default data directory. If the data has
+not already been downloaded, it downloads the data from the url and saves the
+data directory to the configuration file. This allows you to use the data
+again in a different example without downloading it again.
+
+Note that examples in the gallery are ordered according to their filenames, thus
+the number after 'plot_' dictates the order the example appears in the gallery.
+"""
+
+
+######################################################################
+# Define Hyperparameters
+# ----------------------
+#
+# We set the hyperparameters for our tutorial.
+# Depending on the resources
+# available, one may choose to execute the policy and the simulator on GPU or on another
+# device.
+# You can tune some of these values to adjust the computational requirements.
+#
+
+import vmas
+
+env = vmas.make_env("dispersion", num_envs=3)
+env.get_random_actions()
+
+######################################################################
+# Define dwdwd
+# ----------------------
+#
+# We set the hyperparameters for our tutorial.
+# Depending on the resources
+# available, one may choose to execute the policy and the simulator on GPU or on another
+# device.
+# You can tune some of these values to adjust the computational requirements.
+#
+
+env = vmas.make_env("dispersion", num_envs=3)
+env.get_random_actions()

tutorials/environment/plot_under_rendering.py

@@ -0,0 +1,52 @@
+#  Copyright (c) 2024.
+#  ProrokLab (https://www.proroklab.org/)
+#  All rights reserved.
+
+"""
+Data download example
+=====================
+
+This example shows one way of dealing with large data files required for your
+examples.
+
+The ``download_data`` function first checks if the data has already been
+downloaded, looking in either the data directory saved the configuration file
+(by default ``~/.sg_template``) or the default data directory. If the data has
+not already been downloaded, it downloads the data from the url and saves the
+data directory to the configuration file. This allows you to use the data
+again in a different example without downloading it again.
+
+Note that examples in the gallery are ordered according to their filenames, thus
+the number after 'plot_' dictates the order the example appears in the gallery.
+"""
+
+
+######################################################################
+# Define Hyperparameters
+# ----------------------
+#
+# We set the hyperparameters for our tutorial.
+# Depending on the resources
+# available, one may choose to execute the policy and the simulator on GPU or on another
+# device.
+# You can tune some of these values to adjust the computational requirements.
+#
+
+import vmas
+
+env = vmas.make_env("dispersion", num_envs=3)
+env.get_random_actions()
+
+######################################################################
+# Define dwdwd
+# ----------------------
+#
+# We set the hyperparameters for our tutorial.
+# Depending on the resources
+# available, one may choose to execute the policy and the simulator on GPU or on another
+# device.
+# You can tune some of these values to adjust the computational requirements.
+#
+
+env = vmas.make_env("dispersion", num_envs=3)
+env.get_random_actions()

tutorials/environment/rendering.py

@@ -0,0 +1,52 @@
+#  Copyright (c) 2024.
+#  ProrokLab (https://www.proroklab.org/)
+#  All rights reserved.
+
+"""
+Data download example
+=====================
+
+This example shows one way of dealing with large data files required for your
+examples.
+
+The ``download_data`` function first checks if the data has already been
+downloaded, looking in either the data directory saved the configuration file
+(by default ``~/.sg_template``) or the default data directory. If the data has
+not already been downloaded, it downloads the data from the url and saves the
+data directory to the configuration file. This allows you to use the data
+again in a different example without downloading it again.
+
+Note that examples in the gallery are ordered according to their filenames, thus
+the number after 'plot_' dictates the order the example appears in the gallery.
+"""
+
+
+######################################################################
+# Define Hyperparameters
+# ----------------------
+#
+# We set the hyperparameters for our tutorial.
+# Depending on the resources
+# available, one may choose to execute the policy and the simulator on GPU or on another
+# device.
+# You can tune some of these values to adjust the computational requirements.
+#
+
+import vmas
+
+env = vmas.make_env("dispersion", num_envs=3)
+env.get_random_actions()
+
+######################################################################
+# Define dwdwd
+# ----------------------
+#
+# We set the hyperparameters for our tutorial.
+# Depending on the resources
+# available, one may choose to execute the policy and the simulator on GPU or on another
+# device.
+# You can tune some of these values to adjust the computational requirements.
+#
+
+env = vmas.make_env("dispersion", num_envs=3)
+env.get_random_actions()

tutorials/environment/spaces.py

@@ -0,0 +1,52 @@
+#  Copyright (c) 2024.
+#  ProrokLab (https://www.proroklab.org/)
+#  All rights reserved.
+
+"""
+Data download example
+=====================
+
+This example shows one way of dealing with large data files required for your
+examples.
+
+The ``download_data`` function first checks if the data has already been
+downloaded, looking in either the data directory saved the configuration file
+(by default ``~/.sg_template``) or the default data directory. If the data has
+not already been downloaded, it downloads the data from the url and saves the
+data directory to the configuration file. This allows you to use the data
+again in a different example without downloading it again.
+
+Note that examples in the gallery are ordered according to their filenames, thus
+the number after 'plot_' dictates the order the example appears in the gallery.
+"""
+
+
+######################################################################
+# Define Hyperparameters
+# ----------------------
+#
+# We set the hyperparameters for our tutorial.
+# Depending on the resources
+# available, one may choose to execute the policy and the simulator on GPU or on another
+# device.
+# You can tune some of these values to adjust the computational requirements.
+#
+
+import vmas
+
+env = vmas.make_env("dispersion", num_envs=3)
+env.get_random_actions()
+
+######################################################################
+# Define dwdwd
+# ----------------------
+#
+# We set the hyperparameters for our tutorial.
+# Depending on the resources
+# available, one may choose to execute the policy and the simulator on GPU or on another
+# device.
+# You can tune some of these values to adjust the computational requirements.
+#
+
+env = vmas.make_env("dispersion", num_envs=3)
+env.get_random_actions()