diff --git a/docs/_static/notebooks/extensions.png b/docs/_static/notebooks/extensions.png new file mode 100644 index 00000000..8441802d Binary files /dev/null and b/docs/_static/notebooks/extensions.png differ diff --git a/docs/_static/notebooks/install_extensions.png b/docs/_static/notebooks/install_extensions.png new file mode 100644 index 00000000..db026ce3 Binary files /dev/null and b/docs/_static/notebooks/install_extensions.png differ diff --git a/docs/index.rst b/docs/index.rst index cf17b1c5..4cc81b13 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -105,6 +105,7 @@ Head over to the :ref:`getting-started` page to install and setup PrimAITE! source/getting_started source/primaite_session + source/example_notebooks source/simulation source/game_layer source/config diff --git a/docs/source/example_notebooks.rst b/docs/source/example_notebooks.rst new file mode 100644 index 00000000..9fb5cc9e --- /dev/null +++ b/docs/source/example_notebooks.rst @@ -0,0 +1,79 @@ +.. only:: comment + + © Crown-owned copyright 2023, Defence Science and Technology Laboratory UK + +Example Jupyter Notebooks +========================= + +There are a few example notebooks included which helps with the understanding of PrimAITE's capabilities. + +The Jupyter Notebooks can be run via the 2 examples below. These assume that the instructions to install PrimAITE from the :ref:`Getting Started ` page is completed as a prerequisite. + +Running Jupyter Notebooks +------------------------- + +1. Navigate to the PrimAITE directory + +.. code-block:: bash + :caption: Unix + + cd ~/primaite/PRIMAITE_VERSION_TOKEN + +.. code-block:: powershell + :caption: Windows (Powershell) + + cd ~\primaite\PRIMAITE_VERSION_TOKEN + +2. Run jupyter notebook + +.. code-block:: bash + :caption: Unix + + jupyter notebook + +.. code-block:: powershell + :caption: Windows (Powershell) + + jupyter notebook + +3. Opening the jupyter webpage (optional) + +The default web browser may automatically open the webpage. However, if that is not the case, open a web browser and navigate to |jupyter_index|. + +.. |jupyter_index| raw:: html + + http://localhost:8888/tree + +4. Navigate to the list of notebooks + +The example notebooks are located in notebooks/example_notebooks or by navigating to |jupyter_index_notebooks| + +.. |jupyter_index_notebooks| raw:: html + + http://localhost:8888/tree/notebooks/example_notebooks + +Running Jupyter Notebooks via VSCode +------------------------------------ + +It is also possible to view the Jupyter notebooks within VSCode. + +Installing extensions +""""""""""""""""""""" + +VSCode may need some extensions to be installed if not already done. +To do this, press the "Select Kernel" button on the top right. + +This should open a dialog which has the option to install python and jupyter extensions. + +.. image:: ../../_static/notebooks/install_extensions.png + :width: 700 + :align: center + :alt: :: The top dialog option that appears will automatically install the extensions + +The following extensions should now be installed + +.. image:: ../../_static/notebooks/extensions.png + :width: 300 + :align: center + +VSCode will then ask for a Python environment version to use. PrimAITE is compatible with Python versions 3.8 - 3.10 diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst index a800ee56..c1559168 100644 --- a/docs/source/getting_started.rst +++ b/docs/source/getting_started.rst @@ -38,12 +38,12 @@ Install PrimAITE .. code-block:: bash :caption: Unix - mkdir ~/primaite/3.0.0 + mkdir -p ~/primaite/3.0.0b6 .. code-block:: powershell :caption: Windows (Powershell) - mkdir ~\primaite\3.0.0 + mkdir ~\primaite\3.0.0b6 2. Navigate to the primaite directory and create a new python virtual environment (venv) @@ -51,7 +51,7 @@ Install PrimAITE .. code-block:: bash :caption: Unix - cd ~/primaite/3.0.0 + cd ~/primaite/3.0.0b6 python3 -m venv .venv .. code-block:: powershell diff --git a/docs/source/primaite_session.rst b/docs/source/primaite_session.rst index 87a3f03d..b02e015e 100644 --- a/docs/source/primaite_session.rst +++ b/docs/source/primaite_session.rst @@ -35,7 +35,7 @@ Outputs ------- Running a session creates a session output directory in your user data folder. The filepath looks like this: -``~/primaite/3.0.0/sessions/YYYY-MM-DD/HH-MM-SS/``. This folder contains the simulation sys logs generated by each node, +``~/primaite/3.0.0b6/sessions/YYYY-MM-DD/HH-MM-SS/``. This folder contains the simulation sys logs generated by each node, the saved agent checkpoints, and final model. The folder also contains a .json file for each episode step that contains the action, reward, and simulation state. These can be found in -``~/primaite/3.0.0/sessions/YYYY-MM-DD/HH-MM-SS/simulation_output/episode_/step_metadata/step_.json`` +``~/primaite/3.0.0b6/sessions/YYYY-MM-DD/HH-MM-SS/simulation_output/episode_/step_metadata/step_.json``