Merge release v1.0.0

.github/workflows/black.yaml

@@ -6,7 +6,7 @@ jobs:
   lint:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - uses: psf/black@stable
         with:
           version: "23.3.0"

.github/workflows/documentation.yaml

@@ -6,13 +6,14 @@ jobs:
   docs:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
-      - uses: actions/setup-python@v3
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
         with:
           python-version: '3.12'
       - name: Install dependencies
         run: |
           pip install sphinxcontrib-googleanalytics
+          pip install "flyvision @ https://github.com/Nely-EPFL/flyvis/archive/refs/heads/main.zip"
           pip install -e ."[dev,examples]"
           pip install toolz
       - name: Sphinx build

.github/workflows/tests_docker.yaml

@@ -0,0 +1,27 @@
+name: Build and test Docker image
+
+on: [push]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Cache Docker layers
+        uses: actions/cache@v4
+        with:
+          path: /tmp/.buildx-cache
+          key: ${{ runner.os }}-buildx-${{ github.sha }}
+          restore-keys: |
+            ${{ runner.os }}-buildx-
+
+      - name: Build Docker image
+        run: docker build --tag flygym:temp .
+
+      - name: Run tests inside Docker container
+        run: docker run --rm flygym:temp -c "pytest"

.github/workflows/tests.yaml → .github/workflows/tests_full.yaml

@@ -1,37 +1,32 @@
-name: MuJoCo Tests
+name: Unit tests (full)
 
 on: [push]
 
-# env:
-#   LD_PRELOAD: /usr/lib/x86_64-linux-gnu/libGLEW.so
-
 jobs:
   build:
-
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     strategy:
       matrix:
         python-version: ["3.9", "3.10", "3.11", "3.12"]
-
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
       - name: Set up renderer
         run: |
           sudo apt-get update
-          sudo apt-get install -y libgl1-mesa-dev libgl1-mesa-glx libosmesa6-dev
+          sudo apt-get install -y libegl1-mesa-dev
           echo "MUJOCO_GL=egl" >> $GITHUB_ENV
           echo "PYOPENGL_PLATFORM=egl" >> $GITHUB_ENV
       - name: Install dependencies
         run: |
           sudo apt-get install ffmpeg
           pip install --upgrade pip
           pip cache purge
-          pip install -e ."[dev,examples]"
-          pip install toolz
+          pip install "flyvision @ https://github.com/Nely-EPFL/flyvis/archive/refs/heads/main.zip"
+          pip install -e ".[dev,examples]"
       - name: Lint with ruff
         run: |
           # stop the build if there are Python syntax errors or undefined names

.github/workflows/tests_macos.yaml

@@ -0,0 +1,33 @@
+name: Unit tests (macOS)
+
+on: [push]
+
+env:
+  SKIP_RENDERING: "true"
+
+jobs:
+  build:
+    strategy:
+      matrix:
+        os: ["macos-13", "macos-latest"]
+        python-version: ["3.12"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: |
+          pip install --upgrade pip
+          pip cache purge
+          pip install "flyvision @ https://github.com/Nely-EPFL/flyvis/archive/refs/heads/main.zip"
+          pip install -e ".[dev,examples]"
+      - name: Lint with ruff
+        run: |
+          # stop the build if there are Python syntax errors or undefined names
+          ruff --output-format=github --select=E9,F63,F7,F82 --target-version=py38 .
+      - name: Test with pytest
+        run: |
+          python -m pytest

.github/workflows/tests_ubuntu22.yaml

@@ -0,0 +1,36 @@
+name: Unit tests (Ubuntu 22.04)
+
+on: [push]
+
+jobs:
+  build:
+    runs-on: ubuntu-22.04
+    strategy:
+      matrix:
+        python-version: ["3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Set up renderer
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y libegl1-mesa-dev
+          echo "MUJOCO_GL=egl" >> $GITHUB_ENV
+          echo "PYOPENGL_PLATFORM=egl" >> $GITHUB_ENV
+      - name: Install dependencies
+        run: |
+          sudo apt-get install ffmpeg
+          pip install --upgrade pip
+          pip cache purge
+          pip install "flyvision @ https://github.com/Nely-EPFL/flyvis/archive/refs/heads/main.zip"
+          pip install -e ".[dev,examples]"
+      - name: Lint with ruff
+        run: |
+          # stop the build if there are Python syntax errors or undefined names
+          ruff --output-format=github --select=E9,F63,F7,F82 --target-version=py38 .
+      - name: Test with pytest
+        run: |
+          python -m pytest

.github/workflows/tests_windows.yaml

@@ -0,0 +1,32 @@
+name: Unit tests (Windows)
+
+on: [push]
+
+env:
+  SKIP_RENDERING: "true"
+
+jobs:
+  build:
+    runs-on: windows-latest
+    strategy:
+      matrix:
+        python-version: ["3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: |
+          pip install --upgrade pip
+          pip cache purge
+          pip install "flyvision @ https://github.com/nely-epfl/flyvis/archive/refs/heads/main.zip"
+          pip install -e .[dev,examples]
+      - name: Lint with ruff
+        run: |
+          # stop the build if there are Python syntax errors or undefined names
+          ruff --output-format=github --select=E9,F63,F7,F82 --target-version=py38 .
+      - name: Test with pytest
+        run: |
+          python -m pytest

Dockerfile

@@ -0,0 +1,26 @@
+FROM python:3.12-bookworm
+
+# Set shell to bash (instead of sh)
+SHELL ["/bin/bash", "-c"]
+
+# Change working directory
+ENV HOME /root
+WORKDIR $HOME/flygym
+
+# Install system dependencies
+RUN apt update && \
+    apt-get install -y libegl1-mesa-dev ffmpeg
+
+# Set renderer
+ENV MUJOCO_GL=egl
+ENV PYOPENGL_PLATFORM=egl
+
+# Copy flygym package to the container and install the package
+ADD . $HOME/flygym/
+
+# Set up virtual environment and install dependencies
+RUN pip install "flyvision @ https://github.com/Nely-EPFL/flyvis/archive/refs/heads/main.zip" && \
+    pip install -e ".[examples,dev]"
+
+# Set entrypoint
+ENTRYPOINT ["/bin/bash"]

README.md

@@ -9,6 +9,11 @@
 [![PyPI version](https://badge.fury.io/py/flygym.svg)](https://badge.fury.io/py/flygym)
 ![Repo Size](https://img.shields.io/github/repo-size/NeLy-EPFL/flygym)
 
+[![Docker](https://img.shields.io/badge/docker-%230db7ed.svg?style=for-the-badge&logo=docker&logoColor=white)](https://hub.docker.com/r/nelyepfl/flygym)
+![Docker image size](https://img.shields.io/docker/image-size/nelyepfl/flygym/latest)
+
+
+
 ![overview_video](https://github.com/NeLy-EPFL/_media/blob/main/flygym/overview_video.gif?raw=true)
 
 This repository contains the source code for FlyGym, the Python library for NeuroMechFly v2, a digital twin of the adult fruit fly *Drosophila* melanogaster that can see, smell, walk over challenging terrain, and interact with the environment (see our [NeuroMechFly v2 paper](https://www.biorxiv.org/content/10.1101/2023.09.18.556649)).
@@ -29,9 +34,10 @@ This package is developed at the [Neuroengineering Laboratory](https://www.epfl.
 In brief:
 ```bash
 pip install "flygym"
+# or pip install "flygym[examples]" to install additional dependencies needed for examples
 ```
 
-See [our website](https://neuromechfly.org/installation.html) for details, especially if you plan to install FlyGym in the developer mode (i.e. if you plan to make changes to the code). Dependencies are specified in [`setup.py`](https://github.com/NeLy-EPFL/flygym/blob/main/setup.py) and will be installed automatically upon installation using pip. Installation should take no more than a few minutes. NeuroMechFly has been tested on Linux (Ubuntu 22.04.3) and macOS (13.5.2). All commits are tested automatically using the latest Ubuntu version on Python versions 3.9 through 3.12 (see [CI workflow](https://github.com/NeLy-EPFL/flygym/blob/main/.github/workflows/tests.yaml) for exact test specification). The PyPI version of the current release of FlyGym is indicated on the shield at the top of this page. No special or paid software is required to use FlyGym.
+Alternatively, we provide a [Docker image](https://hub.docker.com/r/nelyepfl/flygym). See [our website](https://neuromechfly.org/installation.html) for details, especially if you plan to install FlyGym in the developer mode (i.e. if you plan to make changes to the code). Dependencies are specified in [`setup.py`](https://github.com/NeLy-EPFL/flygym/blob/main/setup.py) and will be installed automatically upon installation using pip. Installation should take no more than a few minutes. The PyPI version of the current release of FlyGym is indicated on the shield at the top of this page. No special, paid software is required to use FlyGym.
 
 ## Demos
 See [our website](https://neuromechfly.org/tutorials/index.html) for tutorials, including expected outputs. For code blocks that take more than a few seconds to run, the running time (on a 2020 MacBook Pro with M1 processor running macOS 13.5.2) is indicated, typically in the form of a progress bar.

doc/source/api_ref/examples/locomotion.rst

@@ -38,10 +38,21 @@ Hybrid turning controller
     :inherited-members:
 
 Hybrid turning fly
--------------------------
+------------------
 
 .. autoclass:: flygym.examples.locomotion.HybridTurningFly
     :members:
     :undoc-members:
     :show-inheritance:
     :inherited-members:
+
+Utility class for coloring body segments of the fly
+---------------------------------------------------
+
+The following utility class is a wrapper around the ``Fly`` class that facilitates the recoloring of specific segments. This is useful for, as an example, recoloring parts of the leg depending on the activation of specific correction rules.
+
+.. autoclass:: flygym.examples.locomotion.ColorableFly
+    :members:
+    :undoc-members:
+    :show-inheritance:
+    :inherited-members:

doc/source/gallery/index.rst

@@ -88,7 +88,7 @@ NeuroMechFly can be used to emulate a wide range of behaviours and scenarios. He
         <div class="gallery-item">
             <a href="video_13_plume_navigation.html">
                 <img src="https://github.com/NeLy-EPFL/_media/blob/main/flygym/videos/video_13_plume_navigation_v2_SWC_thumbnail.jpeg/?raw=true" alt="Plume navigation">
-                <p>Navigating dynamic olfactive environements</p>
+                <p>Navigating dynamic olfactive environments</p>
             </a>
         </div>
         <div class="gallery-item">

doc/source/index.rst

@@ -29,15 +29,15 @@ Simulating embodied sensorimotor control with NeuroMechFly v2
 
 .. note:: 
 
-   FlyGym is in beta. API changes may occur in future releases. See the `changelog <changelog.html>`_ for details.
+   API changes may occur in future releases. See the `changelog <changelog.html>`_ for details.
 
 
 FlyGym is the Python library for NeuroMechFly v2, a digital twin of the adult fruit fly *Drosophila melanogaster* that can see, smell, walk over challenging terrain, and interact with the environment (see our `NeuroMechFly v2 paper <https://www.biorxiv.org/content/10.1101/2023.09.18.556649>`_).
 
 FlyGym consists of the following components:
 
 - **Biomechanical model:** The biomechanical model is based on a micro-CT scan of a real adult female fly (see our `original NeuroMechFly <https://doi.org/10.1038/s41592-022-01466-7>`_ publication). In NeuroMechFly v2 we have updated several body segments (in particular in the antennae) to better reflect the biological reality.
-- **Vision:** The fly has compound eyes consisting of individual units called ommatidia. These are arranged on a hexagonal lattice. We have simulated visual inputs on the fly's retinae.
+- **Vision:** The fly has compound eyes consisting of individual units called ommatidia. These are arranged on a hexagonal lattice. We have simulated visual inputs on the fly's retinas.
 - **Olfaction:** The fly has odor receptors in the antennae and maxillary palps. We have simulated olfactory signals experienced by the fly by computing odor/chemical intensities at the locations of the antennae and maxillary palps.
 - **Hierarchical control:** The fly's central nervous system (CNS) consists of the brain and the ventral nerve cord (VNC). This hierarchy is analogous to the brain-spinal cord organization of vertebrates. The user can build a two-part model --- one handling brain-level sensory integration and decision making as well as one handling VNC-level motor control --- with a interface between the two consisting of descending (brain-to-VNC) and ascending (VNC-to-brain) neuronal pathways.
 - **Leg adhesion:** Insects have evolved specialized adhesive structures at the tips of their legs. These enable locomotion on inclined and overhanging surfaces. We have simulated adhesion in our model. The mechanism by which the fly lifts the legs during locomotion despite adhesive forces is currently not well understood. Therefore, to abstract this, adhesion can be turned on or off during stance or swing of the legs, respectively.