Build one

First, decide which question you are answering

There are two honest projects here and they are not the same. One is “what does this wiring diagram look like when it runs?” — a visualisation, a toy, a fly that walks across your desktop. The other is “can this circuit do the thing the real circuit does?” — an experiment, with controls and a result that might be no.

Both are worth building. They just need different amounts of work, and the common failure is starting the first and describing it as the second. Pick one now and the rest of the decisions get easier.

Two datasets carry almost everything on this site. They are different animals, not different versions of the same one — pick deliberately and say which you used.

• MaleCNS v1.0 — adult male, brain plus optic lobes plus ventral nerve cord, ~166,000 neurons. The only one with an intact neck connective, so it is the one to use if you want to get from an eye to a leg.
• FlyWire / FAFB — adult female brain, ~139,000 neurons, no nerve cord. Browse it in Codex before you download anything; an hour in the explorer saves a week of guessing at cell types.

The download is a neuron table and an edge table — ids, types, regions, and a weight per connection that counts synaptic contacts. That weight is anatomy, not synaptic strength. Nothing in the file tells you how strongly a connection drives its target, and turning contact counts into conductances is a modelling choice you are making, not a measurement you are reading.

Running the whole graph is a flex, not a requirement, and the projects that pick a circuit usually end up saying more. Both are legitimate:

• Whole graph. 166k neurons and 25M edges is a sparse matrix multiply. It runs at 60 fps on a GPU and is entirely feasible on a laptop CPU at lower rates. Good when you want to watch activity spread and do not yet know where to look.
• A named circuit. Pull the cells you need by type — Kenyon cells, MBONs, DNa02, LC4 — and you get something you can reason about, debug, and make a prediction from. Every L2 project on this site does this.

If you take a subset, say so plainly and say how you chose it. “A 4,386-neuron visuomotor circuit selected by cell type” is a stronger sentence than “the fly brain”, because a reader can check it.

A connectome with no dynamics is a graph: activity in, activity out, nothing carried between frames. That is L0, and plenty of good demos live there.

Adding state is a small step with a large payoff. Leaky integrate-and-fire is the usual choice: each neuron holds a membrane voltage that leaks toward rest, sums weighted input, fires when it crosses a threshold, and goes refractory. Perhaps thirty lines.

The part that matters is where the parameters come from. Numbers you tuned until the demo looked good are a tuning choice; numbers from a published whole-brain model are a modelling decision a reader can check. The parameter set most projects here use comes from the Shiu et al. 2024 whole-brain model. Write down what you used, either way.

This is where every project invents something, and where the honest ones say so. The connectome tells you that photoreceptors connect to the optic lobe. It does not tell you how to turn a game frame into photoreceptor current, and it does not tell you how to turn descending-neuron activity into a button press.

Reasonable anchors exist. Visual input goes to the optic lobe; looming detectors like LC4 and LPLC2 feed the giant-fibre escape pathway through DNp01. Steering runs through DNa02; backward walking through MDN. Sugar and bitter taste have their own receptor classes. Using the real cells for the real job makes the mapping defensible.

But the scaling, the thresholds, the frame-to-current function — those are yours. Putting them in a table in your README costs ten minutes and is the difference between a reader trusting your project and squinting at it.

Here is the trap, stated plainly, because most projects walk into it: training a small readout layer on top of a frozen connectome is not the fly learning. The fly is unchanged; a classifier bolted to its output got better. That is a fine experiment and it stays at L1.

Learning, on this scale, means synapses inside the circuit change. In the fly there is a canonical place for that, and you should use it:

• Kenyon cells → MBONs in the mushroom body. ~2,000 Kenyon cells per hemisphere sparse-code what is happening; MBONs read out approach versus avoid.
• Dopaminergic neurons gate the change. PAM cells carry reward, PPL1 cells carry punishment, and each innervates specific compartments — so the change is compartment-specific, not global.
• An eligibility trace bridges the delay. Reward arrives seconds after the action that earned it. A decaying trace on recent Kenyon-cell activity is how the credit gets back, and the dopaminergic timing window in the real fly is genuinely seconds wide.
• APL keeps the code sparse. One inhibitory neuron per hemisphere. Remove it and the Kenyon-cell code goes dense, patterns overlap and memories interfere — an ablation you can run yourself in an afternoon.

One detail worth knowing before you write it: the classic result is depression only — synapses weaken, never strengthen. That is faithful, and over a long training run it can grind every active synapse to the floor and erase the structure you started with. Some projects here use a bidirectional rule for exactly this reason and document why. Either is defensible; silently doing one while describing the other is not.

This section is short and it is the most important one on the page. A fly that plays a game proves nothing on its own — the wrapper around it might be doing all the work. Four controls, each a few lines:

• Silence the circuit. Same harness, no neural activity. If performance barely drops, the circuit was decorative.
• Shuffle the graph. Same neurons, same degree distribution, rewired at random. If it works just as well, you have shown something about sparse networks, not about flies.
• Untrained baseline. The same circuit before learning. The gap between this and the trained version is your actual result.
• Reward removed. Plasticity running, reward signal replaced by noise. This separates “the weights moved” from “the weights learned something”, and it is the control that most often comes back negative.

A negative control that fails is not a wasted afternoon. Several of the most respected projects in this index report exactly that, and they are rated on the strength of having looked.

Ratings here need evidence, and evidence means a link to a line. Projects that get rated quickly tend to have the same four things in the README:

1. Which dataset and which release. “MaleCNS v1.0”, not “the fly connectome”.
2. The neuron model and its parameters, or a line saying there is no neuron model. Both are fine; the gap is not.
3. What is trained and what is frozen. One sentence. It decides L1 versus L2 on its own.
4. A limitations section — the most-read part of a good README, and the fastest way to be trusted.

Then add it to awesome-fly and it arrives here on the next sync. The route is here.