# flycns

[![ci](https://github.com/fsantibanezleal/CAOS_FlyCNS/actions/workflows/ci.yaml/badge.svg?branch=main)](https://github.com/fsantibanezleal/CAOS_FlyCNS/actions/workflows/ci.yaml)
[![license: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

Compile a fly connectome release into a graph a simulator can run, model the two compound eyes over the release's
own optic-lobe columns, and simulate the whole central nervous system with the published neuron models, in Python
and in the browser, with the two implementations held to each other by parity tests.

- **Release:** MaleCNS v1.0, the complete male *Drosophila* CNS (166,700 neurons, brain and ventral nerve cord;
  Berg et al., *Cell* 189:5504-5526, 2026, doi:10.1016/j.cell.2026.08.015; data CC BY 4.0). Both optic lobes are
  mapped column by column in the release (879 columns left, 892 right), which is what lets two eyes feed it.
- **Neuron models:** the published leaky integrate-and-fire model of the fly brain (Shiu et al., *Nature*
  634:210-219, 2024, doi:10.1038/s41586-024-07763-9), and a graded optic lobe in the form of the connectome-constrained
  visual model (Lappalainen et al., *Nature* 2024, doi:10.1038/s41586-024-07939-3).
- **Two implementations, one set of equations:** a Python reference (NumPy, and PyTorch on a GPU) and a browser
  engine (`@fasl-work/flycns`, WebGPU with a worker fallback).

## What it is not

A general neural simulator, a learned model of the fly, or a claim about behaviour. Synapse counts and signs are
data and never change; the package integrates published equations over them and says where those equations are
known to fall short.

## Status

Version 0.07.000: the MaleCNS v1.0 compiler and compiled format; the two compound eyes over the release's own
columns, their vertical set by the dorsal rim; the published spiking model, identical to a literal Brian2
transcription, on a NumPy reference and a GPU engine; the graded visual neurons as flyvis computes them, held to
flyvis itself, with its 50 trained networks shipped as data; and flyvis's numbers transferred onto the neuron-level
wiring of both MaleCNS optic lobes, where T4 cells, measured through the modelled eyes, prefer their known
directions; and the whole CNS coupled, in four engines (the published model everywhere, which does not see; the
graded optic lobes with the spiking CNS, which carries a flash to the motor neurons; flyvis's own networks mapped
onto MaleCNS; and the stabilised version, which leaves the published model one state); and the browser engine
(`@fasl-work/flycns`): a CPU engine that reproduces the Python reference spike for spike, the whole CNS included,
and WebGPU kernels held to it by the design's tolerances. Next: Destello's scenes, cases and web product.
This README lists capabilities only as they land.

## Compile MaleCNS v1.0

Download the four tables listed in [`docs/releases/01_malecns-v1.md`](docs/releases/01_malecns-v1.md) into one
folder, then:

```python
from pathlib import Path
from flycns.release import compile_malecns_v1
from flycns.compiled import read_compiled

compile_malecns_v1(Path("malecns-tables"), Path("compiled/malecns-v1.0"), progress=print)
graph = read_compiled(Path("compiled/malecns-v1.0"))      # every array verified against its SHA-256
print(graph.n_neurons, graph.n_edges, graph.counts["columns"])
```

A table whose SHA-256 differs from the locked value is refused. Compilation streams the 13 GB synapse table in record
batches and takes a few minutes on a desktop.

## Simulate

```python
from pathlib import Path

from flycns.compiled import read_compiled
from flycns.dynamics import Drive, LIFReference, synaptic_weights

graph = read_compiled(Path("compiled/malecns-v1.0"))
weights = synaptic_weights(graph["csr_indptr"], graph["csr_indices"], graph["csr_count"], graph["neuron_sign"], 0.275)
engine = LIFReference(graph["csr_indptr"], graph["csr_indices"], weights)      # or LIFTorch on a GPU
run = engine.run(10_000, Drive(activate={1234: 150.0}), seed=0)                   # one second of model time
print(run.spike_counts().sum(), "spikes")
```

The graded visual neurons run through `flycns.dynamics.GradedReference` (or `GradedTorch`), with the trained flyvis
parameters from `flycns.flyvis.load_ensemble()`; see [`docs/models/03_graded.md`](docs/models/03_graded.md).

## Install

```bash
pip install flycns              # Python 3.11+; flycns[gpu] adds PyTorch, flycns[release] reads release files
npm install @fasl-work/flycns   # the browser engine: loaders, the CPU engines, WebGPU, the worker
```

Both are published from this repository's releases: [`flycns`](https://pypi.org/project/flycns/) on PyPI through
trusted publishing, and [`@fasl-work/flycns`](https://www.npmjs.com/package/@fasl-work/flycns) on npm. The browser
engine and its measurements are in [`docs/models/06_browser.md`](docs/models/06_browser.md).

## Install (development)

```bash
python -m venv .venv
.venv/Scripts/python -m pip install -e ".[dev,release,parity]"     # add ,gpu for PyTorch; .venv/bin/python elsewhere
.venv/Scripts/python -m pytest -rs
npm ci && npm test
```

## Documentation

The wiki starts at [`docs/README.md`](docs/README.md).

## License

Code: MIT. Connectome data are not redistributed here; they are fetched from the release with their hashes checked,
and remain under their own licence (MaleCNS: CC BY 4.0). The trained parameters of flyvis's pretrained networks
ship inside the package under flyvis's MIT licence, whose notice travels with them
(`src/flycns/data/flyvis-1.2.0-ensemble/LICENSE-flyvis.txt`).