README.md

metadata

license: agpl-3.0
tags:
  - reservoir-computing
  - echo-state-networks
  - connectomics
  - drone-control
  - robotics
  - pybullet
  - neuroscience
metrics:
  - rmse

Fly Connectome Echo State Network for Drone Control

This repository contains research and simulation code that utilizes biological neural connectivity data (the connectome of the Drosophila melanogaster fruit fly) as the reservoir inside an Echo State Network (ESN) to perform autonomous drone flight control.

Project Overview

• Biological Reservoir: The network reservoir is built from the synaptic connectivity graph of the fly brain. We scale the spectral radius of the graph below 1.0 to guarantee the Echo State Property and stabilize dynamics.
• Drone Control Task: The ESN outputs 4D control signals (target velocities: $v_x$, $v_y$, $v_z$, and yaw rate) from a 12D drone state vector.
• Simulation Environment: Real-time evaluation is conducted using gym-pybullet-drones, a physics engine simulating ground effect, aerodynamic drag, and rotor downwash.

Directory Structure

flydrone-esn/
│
├── LICENSE                       # AGPL 3.0 license file
├── README.md                     # English documentation (with HF YAML front matter)
├── README.txt                    # Detailed Turkish documentation
│
└── src/                          # Code files
    ├── utils.py                  # Core mathematics and ESN reservoir helpers
    ├── database_interaction.ipynb # CAVE API client for retrieving connectome synapses
    ├── drone_realtime_simulation.py # Script to run the trained model in PyBullet and log video
    ├── classes_by_cell_type.csv  # Neuron cell classifications
    ├── W_drone_components.pkl    # Pre-trained ESN drone controller weights
    └── networks_graphs/          # Connectome .graphml data files

Setup and Quick Start

1. Install Dependencies

Make sure you have python 3.10 installed, then run:

pip install -r requirements.txt

2. Run the Real-time Simulation

To run the pre-trained ESN-controlled drone in the PyBullet simulator with a graphical interface, run:

python src/drone_realtime_simulation.py

This runs the simulation and logs third-person and first-person camera flight recordings to drone_third_person.mp4 and drone_first_person.mp4 in your directory.