README.md

---
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

```text
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:
```bash
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:
```bash
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.