SingularityEdge/FlyDrone-ESN

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 neural dynamics.
• Drone Control Task: The network is trained using Ridge Regression to output 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/
│
├── README.md                     # English documentation (with HF YAML front matter)
├── README.txt                    # Detailed Turkish documentation
├── requirements.txt              # Project dependencies
│
└── src/                          # Code files
    ├── utils.py                  # Core mathematics and ESN reservoir helpers
    ├── database_interaction.ipynb # CAVE API client for retrieving connectome synapses
    ├── drone_data_collection.py  # Script to collect training trajectories in PyBullet
    ├── drone_esn_training.py     # Script to train Wout using Ridge Regression
    ├── drone_realtime_simulation.py # Script to run the trained model in PyBullet and log video
    ├── classes_by_cell_type.csv  # Neuron cell classifications
    └── 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. Collect Training Data

To collect drone state-action flight datasets (circular trajectories with sinusoidal height variation) in a headless PyBullet simulator, run:

python src/drone_data_collection.py

This generates the src/drone_dataset.npz data file.

3. Train the Model

To scale the connectome matrix and train output weights using Ridge Regression ($\beta = 10^{-6}$), run:

python src/drone_esn_training.py

This saves the trained ESN components inside src/W_drone_components.pkl.

4. Run the Real-time Simulation

To run the 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.