Merge website updates since v1.0.0 release into the dev branch for v1.0.1-pre.1

.github/workflows/documentation.yaml

@@ -12,8 +12,11 @@ jobs:
           python-version: '3.12'
       - name: Install dependencies
         run: |
+          pip install --upgrade pip
+          pip cache purge
           pip install sphinxcontrib-googleanalytics
           pip install "flyvision @ https://github.com/Nely-EPFL/flyvis/archive/refs/heads/main.zip"
+          pip cache purge
           pip install -e ."[dev,examples]"
           pip install toolz
       - name: Sphinx build

.github/workflows/tests_full.yaml

@@ -26,6 +26,7 @@ jobs:
           pip install --upgrade pip
           pip cache purge
           pip install "flyvision @ https://github.com/Nely-EPFL/flyvis/archive/refs/heads/main.zip"
+          pip cache purge
           pip install -e ".[dev,examples]"
       - name: Lint with ruff
         run: |

.github/workflows/tests_macos.yaml

@@ -23,6 +23,7 @@ jobs:
           pip install --upgrade pip
           pip cache purge
           pip install "flyvision @ https://github.com/Nely-EPFL/flyvis/archive/refs/heads/main.zip"
+          pip cache purge
           pip install -e ".[dev,examples]"
       - name: Lint with ruff
         run: |

.github/workflows/tests_ubuntu22.yaml

@@ -26,6 +26,7 @@ jobs:
           pip install --upgrade pip
           pip cache purge
           pip install "flyvision @ https://github.com/Nely-EPFL/flyvis/archive/refs/heads/main.zip"
+          pip cache purge
           pip install -e ".[dev,examples]"
       - name: Lint with ruff
         run: |

.github/workflows/tests_windows.yaml

@@ -22,6 +22,7 @@ jobs:
           pip install --upgrade pip
           pip cache purge
           pip install "flyvision @ https://github.com/nely-epfl/flyvis/archive/refs/heads/main.zip"
+          pip cache purge
           pip install -e .[dev,examples]
       - name: Lint with ruff
         run: |

doc/source/installation.rst

@@ -2,6 +2,9 @@ Installation
 ============
 
 
+FlyGym can be installed as a regular Python package via `PyPI <https://pypi.org/project/flygym/>`_ or as a developer installation from the source code. In addition, we provide a Docker image with FlyGym and its dependencies pre-installed. Below, we provide instructions for each of these methods.
+
+
 Installation via PyPI 
 ---------------------
 The easiest way to install FlyGym is via PyPI. Before you start, you might want to create a Python virtual environment with virtualenv or Conda. For example, with Conda:
@@ -11,32 +14,39 @@ The easiest way to install FlyGym is via PyPI. Before you start, you might want
    conda create -n flygym python=3.12    # flygym is tested on Python 3.9-3.12
    conda activate flygym    # run this every time you use the environment
 
-(Optional) If you would like to interface FlyGym with the `connectome-constrained vision model <https://github.com/TuragaLab/flyvis>`_ from `Lappalainen et al. (2023) <https://www.biorxiv.org/content/10.1101/2023.03.11.532232>`_, you need to install the FlyVision package separately. Since FlyVision is not published on the Python Package Index (PyPI), you must either install it manually following `its installation instructions <https://github.com/TuragaLab/flyvis?tab=readme-ov-file#install-locally->`_, or install it with ``pip`` from our fork on GitHub:
+Then, to install the FlyGym package:
 
 .. code-block:: bash
 
-   pip install "flyvision @ https://github.com/Nely-EPFL/flyvis/archive/refs/heads/main.zip"
+   pip install "flygym"
 
-(Required) Then, to install the FlyGym package:
+.. important::
+
+   **Headless machines**: If you want to run FlyGym on a machine without a display (e.g. a server or a node on a cluster), please check the special instructions at the bottom of this page.
 
-.. code-block:: bash
+.. note::
 
-   # if you only want the basic package:
-   pip install "flygym"
+   **(Optional) Additional dependencies for provided tutorials and examples:** A number of additional dependencies are required to run the provided `tutorials <https://neuromechfly.org/tutorials/index.html>`_ and `examples <https://github.com/NeLy-EPFL/flygym/tree/main/flygym/examples/>`_. To install these dependencies, you can run the following command:
 
-   # to install additional dependencies required to run the provided examples:
-   pip install "flygym[examples]"
+   .. code-block:: bash
 
-   # to install dev tools such as pytest (automated testing) and sphinx (docs building):
-   pip install "flygym[dev]"
-
-   # to install everything:
-   pip install "flygym[examples,dev]"
+      pip install "flygym[examples]"
 
+   The tutorial and example on interfacing FlyGym with the `connectome-constrained vision model <https://github.com/TuragaLab/flyvis>`_ from `Lappalainen et al. (2023) <https://www.biorxiv.org/content/10.1101/2023.03.11.532232>`_ further requires the FlyVision package, which is not published on the Python Package Index (PyPI). As a result, the command above does not install FlyVision. Instead, you must either install it manually following `its installation instructions <https://github.com/TuragaLab/flyvis?tab=readme-ov-file#install-locally->`_, or install it with ``pip`` from our fork on GitHub:
+
+   .. code-block:: bash
+
+      pip install "flyvision @ https://github.com/Nely-EPFL/flyvis/archive/refs/heads/main.zip"
+
+.. Note::
+
+   **(Optional) Additional tools for developers:** Developers of FlyGym use a number of other tools for automated documentation generation, testing, and code linting. These tools are not required to use FlyGym as it is, but can be useful if you wish to modify the code or contribute to the project. To install these tools, you can run:
+
+   .. code-block:: bash
 
-Please note that the ``pip`` installation does not easily allow the user to modify the source code. If you want to modify the source code, please follow the instructions below for developer installation.
+      pip install "flygym[dev]"
 
-If you want to run FlyGym on a machine without a display (e.g. a server or a node on a cluster), please check the special instructions at the bottom of this page.
+   Note, however, that ``pip`` installation does not easily allow the user to modify the source code. If you want to modify the source code, please follow the instructions below for developer installation.
 
 
 Developer installation
@@ -142,7 +152,7 @@ Docker image
 
 `"Containerization" <https://en.wikipedia.org/wiki/Containerization_(computing)>`_ is a way of virtualization that aims to bundle an application and its dependencies into a single portable, executable unit called a *container*. `Docker <https://docs.docker.com/guides/docker-overview/>`_ is a popular platform for developing, shipping, and running containers, making it easier to manage and deploy applications in a consistent manner.
 
-Instead of installing FlyGym on your machine directly, you can also install Docker on your machine and run FlyGym through Docker. This might be particularly helpful if you are using container-as-a-service (CaaS) systems such as Kubernetes to train or deploy models at scale. We provide a Docker image with FlyGym and its dependencies pre-installed and publish it to `Docker Hub <https://hub.docker.com/r/nelyepfl/flygym>`_. This image is defined by the `Dockerfile <https://github.com/NeLy-EPFL/flygym/blob/main/flygym/Dockerfile>`_ at the root level of the directory.
+Instead of installing FlyGym on your machine directly, you can also install Docker on your machine and run FlyGym through Docker. This might be particularly helpful if you are using container-as-a-service (CaaS) systems such as Kubernetes to train or deploy models at scale. We provide a Docker image with FlyGym and its dependencies pre-installed and publish it to `Docker Hub <https://hub.docker.com/r/nelyepfl/flygym>`_. This image is defined by the `Dockerfile <https://github.com/NeLy-EPFL/flygym/blob/main/Dockerfile>`_ at the root level of the directory.
 
 For more information about how to interact with Docker, please refer to the `official Docker guides <https://docs.docker.com/guides/>`_. Note that you need to `install NVIDIA Container Toolkit <https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html>`_ if you would like to use an NVIDIA GPU from the container.
 

doc/source/tutorials/advanced_olfaction.rst

@@ -1,16 +1,18 @@
 Advanced olfaction: Navigating a complex odor plume
 ===================================================
 
-**Author:** Victor Alfred Stimpfling
+.. note::
 
-**Note:** The code presented in this notebook has been simplified and
-restructured for display in a notebook format. A more complete and
-better structured implementation can be found in the `examples folder of
-the FlyGym repository on
-GitHub <https://github.com/NeLy-EPFL/flygym/tree/main/flygym/examples/>`__.
+    **Author:** Victor Alfred Stimpfling
 
-**Notebook Format:** This tutorial is available in `.ipynb` format in the
-`notebooks folder of the FlyGym repository <https://github.com/NeLy-EPFL/flygym/tree/main/notebooks>`_.
+    The code presented in this notebook has been simplified and
+    restructured for display in a notebook format. A more complete and
+    better structured implementation can be found in the `examples folder of
+    the FlyGym repository on
+    GitHub <https://github.com/NeLy-EPFL/flygym/tree/main/flygym/examples/>`__.
+
+    This tutorial is available in ``.ipynb`` format in the
+    `notebooks folder of the FlyGym repository <https://github.com/NeLy-EPFL/flygym/tree/main/notebooks>`_.
 
 **Summary**: In this tutorial, we simulate a complex odor plume, replay
 the plume in MuJoCo, and build a simple controller to navigate it.

doc/source/tutorials/advanced_vision.rst

@@ -1,16 +1,18 @@
 Connectome-constrained visual system model
 ==========================================
 
-**Authors:** Thomas Ka Chung Lam, Sibo Wang-Chen
+.. note::
 
-**Note:** The code presented in this notebook has been simplified and
-restructured for display in a notebook format. A more complete and
-better structured implementation can be found in the `examples folder of
-the FlyGym repository on
-GitHub <https://github.com/NeLy-EPFL/flygym/tree/main/flygym/examples/>`__.
+    **Authors:** Thomas Ka Chung Lam, Sibo Wang-Chen
 
-**Notebook Format:** This tutorial is available in `.ipynb` format in the
-`notebooks folder of the FlyGym repository <https://github.com/NeLy-EPFL/flygym/tree/main/notebooks>`_.
+    The code presented in this notebook has been simplified and
+    restructured for display in a notebook format. A more complete and
+    better structured implementation can be found in the `examples folder of
+    the FlyGym repository on
+    GitHub <https://github.com/NeLy-EPFL/flygym/tree/main/flygym/examples/>`__.
+
+    This tutorial is available in ``.ipynb`` format in the
+    `notebooks folder of the FlyGym repository <https://github.com/NeLy-EPFL/flygym/tree/main/notebooks>`_.
 
 **Summary**: In this tutorial, we will (1) simulate two flies in the
 same arena, and (2) integrate a connectome-constrained visual system
@@ -40,10 +42,10 @@ To overcome this limitation, we can implement the core logic of the
 hybrid turning controller at the level of the Fly instead (see `API
 reference <https://neuromechfly.org/api_ref/examples/locomotion.html#hybrid-turning-fly>`__).
 Because we can have multiple Fly objects in the same Simulation, this
-approach allows us to separately control multiple “``HybridTurningFly``”
-instance. Let’s spawn two flies, a target fly and an observer fly that
-looks at the target fly perpendicular to the target fly’s heading
-direction:
+approach allows us to separately control multiple ``HybridTurningFly``
+instances. Let’s spawn two flies: a target fly that walks forward and an
+observer fly that observes the target fly perpendicular to the target fly's
+direction of movement.
 
 .. code:: ipython3
 

doc/source/tutorials/cpg_controller.rst

@@ -1,16 +1,18 @@
 Controlling locomotion with CPGs
 ================================
 
-**Authors:** Sibo Wang-Chen, Femke Hurtak
+.. note::
 
-**Note:** The code presented in this notebook has been simplified and
-restructured for display in a notebook format. A more complete and
-better structured implementation can be found in the `examples folder of
-the FlyGym repository on
-GitHub <https://github.com/NeLy-EPFL/flygym/tree/main/flygym/examples/>`__.
+    **Authors:** Sibo Wang-Chen, Femke Hurtak
 
-**Notebook Format:** This tutorial is available in `.ipynb` format in the
-`notebooks folder of the FlyGym repository <https://github.com/NeLy-EPFL/flygym/tree/main/notebooks>`_.
+    The code presented in this notebook has been simplified and
+    restructured for display in a notebook format. A more complete and
+    better structured implementation can be found in the `examples folder of
+    the FlyGym repository on
+    GitHub <https://github.com/NeLy-EPFL/flygym/tree/main/flygym/examples/>`__.
+
+    This tutorial is available in ``.ipynb`` format in the
+    `notebooks folder of the FlyGym repository <https://github.com/NeLy-EPFL/flygym/tree/main/notebooks>`_.
 
 **Summary:** In this tutorial, we will introduce the concept of Central
 Pattern Generators (CPGs) and build a CPG-based model to control walking

doc/source/tutorials/gym_basics_and_kinematic_replay.rst

@@ -1,16 +1,12 @@
 Interacting with NeuroMechFly
 =============================
 
-**Author:** Sibo Wang-Chen
+.. note::
 
-**Note:** The code presented in this notebook has been simplified and
-restructured for display in a notebook format. A more complete and
-better structured implementation can be found in the `examples folder of
-the FlyGym repository on
-GitHub <https://github.com/NeLy-EPFL/flygym/tree/main/flygym/examples/>`__.
+    **Author:** Sibo Wang-Chen
 
-**Notebook Format:** This tutorial is available in `.ipynb` format in the
-`notebooks folder of the FlyGym repository <https://github.com/NeLy-EPFL/flygym/tree/main/notebooks>`_.
+    This tutorial is available in ``.ipynb`` format in the
+    `notebooks folder of the FlyGym repository <https://github.com/NeLy-EPFL/flygym/tree/main/notebooks>`_.
 
 **Summary:** In this tutorial, we will introduce the basic concepts of
 interacting with the simulated fly in a Markov Decision Process using

doc/source/tutorials/head_stabilization.rst

@@ -1,13 +1,18 @@
 Head stabilization
 ==================
 
-**Author:** Sibo Wang-Chen
+.. note::
 
-**Note:** The code presented in this notebook has been simplified and
-restructured for display in a notebook format. A more complete and
-better structured implementation can be found in the `examples folder of
-the FlyGym repository on
-GitHub <https://github.com/NeLy-EPFL/flygym/tree/main/flygym/examples/>`__.
+    **Author:** Sibo Wang-Chen
+
+    The code presented in this notebook has been simplified and
+    restructured for display in a notebook format. A more complete and
+    better structured implementation can be found in the `examples folder of
+    the FlyGym repository on
+    GitHub <https://github.com/NeLy-EPFL/flygym/tree/main/flygym/examples/>`__.
+
+    This tutorial is available in ``.ipynb`` format in the
+    `notebooks folder of the FlyGym repository <https://github.com/NeLy-EPFL/flygym/tree/main/notebooks>`_.
 
 **Summary:** In this tutorial, we will use mechanosensory information to
 correct for self motion in closed loop. We will train an internal model

doc/source/tutorials/hybrid_controller.rst

@@ -1,16 +1,18 @@
 Overcome complex terrain with a hybrid controller
 =================================================
 
-**Authors:** Victor Alfred Stimpfling, Sibo Wang-Chen
+.. note::
 
-**Note:** The code presented in this notebook has been simplified and
-restructured for display in a notebook format. A more complete and
-better structured implementation can be found in the `examples folder of
-the FlyGym repository on
-GitHub <https://github.com/NeLy-EPFL/flygym/tree/main/flygym/examples/>`__.
+    **Authors:** Victor Alfred Stimpfling, Sibo Wang-Chen
 
-**Notebook Format:** This tutorial is available in `.ipynb` format in the
-`notebooks folder of the FlyGym repository <https://github.com/NeLy-EPFL/flygym/tree/main/notebooks>`_.
+    The code presented in this notebook has been simplified and
+    restructured for display in a notebook format. A more complete and
+    better structured implementation can be found in the `examples folder of
+    the FlyGym repository on
+    GitHub <https://github.com/NeLy-EPFL/flygym/tree/main/flygym/examples/>`__.
+
+    This tutorial is available in ``.ipynb`` format in the
+    `notebooks folder of the FlyGym repository <https://github.com/NeLy-EPFL/flygym/tree/main/notebooks>`_.
 
 **Summary**: In this tutorial, we will illustrate how CPG- and
 rule-based controllers fail to produce robust locomotion over complex

doc/source/tutorials/olfaction_basics.rst

@@ -1,16 +1,18 @@
 Olfaction basics
 ================
 
-**Author:** Sibo Wang-Chen
+.. note::
 
-**Note:** The code presented in this notebook has been simplified and
-restructured for display in a notebook format. A more complete and
-better structured implementation can be found in the `examples folder of
-the FlyGym repository on
-GitHub <https://github.com/NeLy-EPFL/flygym/tree/main/flygym/examples/>`__.
+    **Author:** Sibo Wang-Chen
 
-**Notebook Format:** This tutorial is available in `.ipynb` format in the
-`notebooks folder of the FlyGym repository <https://github.com/NeLy-EPFL/flygym/tree/main/notebooks>`_.
+    The code presented in this notebook has been simplified and
+    restructured for display in a notebook format. A more complete and
+    better structured implementation can be found in the `examples folder of
+    the FlyGym repository on
+    GitHub <https://github.com/NeLy-EPFL/flygym/tree/main/flygym/examples/>`__.
+
+    This tutorial is available in ``.ipynb`` format in the
+    `notebooks folder of the FlyGym repository <https://github.com/NeLy-EPFL/flygym/tree/main/notebooks>`_.
 
 **Summary:** In this tutorial, we will implement a simple controller for
 odor-guided taxis.

doc/source/tutorials/path_integration.rst

@@ -1,16 +1,18 @@
 Path integration
 ================
 
-**Author:** Sibo Wang-Chen
+.. note::
 
-**Note:** The code presented in this notebook has been simplified and
-restructured for display in a notebook format. A more complete and better
-structured implementation can be found in the
-`examples folder of the FlyGym repository on
-GitHub <https://github.com/NeLy-EPFL/flygym/tree/main/flygym/examples/>`__.
+    **Author:** Sibo Wang-Chen
 
-**Notebook Format:** This tutorial is available in `.ipynb` format in the
-`notebooks folder of the FlyGym repository <https://github.com/NeLy-EPFL/flygym/tree/main/notebooks>`_.
+    The code presented in this notebook has been simplified and
+    restructured for display in a notebook format. A more complete and better
+    structured implementation can be found in the
+    `examples folder of the FlyGym repository on
+    GitHub <https://github.com/NeLy-EPFL/flygym/tree/main/flygym/examples/>`__.
+
+    This tutorial is available in ``.ipynb`` format in the
+    `notebooks folder of the FlyGym repository <https://github.com/NeLy-EPFL/flygym/tree/main/notebooks>`_.
 
 **Summary:** In this tutorial, we will show how the position and heading
 of the animal can be estimated by integrating mechanosensory signals, a

doc/source/tutorials/rule_based_controller.rst

@@ -1,16 +1,18 @@
 Rule-based controller
 =====================
 
-**Authors:** Victor Alfred Stimpfling, Sibo Wang-Chen
+.. note::
 
-**Note:** The code presented in this notebook has been simplified and
-restructured for display in a notebook format. A more complete and
-better structured implementation can be found in the `examples folder of
-the FlyGym repository on
-GitHub <https://github.com/NeLy-EPFL/flygym/tree/main/flygym/examples/>`__.
+    **Authors:** Victor Alfred Stimpfling, Sibo Wang-Chen
 
-**Notebook Format:** This tutorial is available in `.ipynb` format in the
-`notebooks folder of the FlyGym repository <https://github.com/NeLy-EPFL/flygym/tree/main/notebooks>`_.
+    The code presented in this notebook has been simplified and
+    restructured for display in a notebook format. A more complete and
+    better structured implementation can be found in the `examples folder of
+    the FlyGym repository on
+    GitHub <https://github.com/NeLy-EPFL/flygym/tree/main/flygym/examples/>`__.
+
+    This tutorial is available in ``.ipynb`` format in the
+    `notebooks folder of the FlyGym repository <https://github.com/NeLy-EPFL/flygym/tree/main/notebooks>`_.
 
 **Summary:** In this tutorial, we will show how locomotion can be
 achieved using local coordination rules in the absence of centralized