Developer guide / Python

From install to action.

Python 3.9+ and NumPy. No CUDA required. The package is currently installed from source; it has not yet been published to PyPI.

Terminal

git clone https://github.com/freeman-1984-coder/flybrain-sdk.git
cd flybrain-sdk
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"
python examples/quickstart.py
pytest

The six methods

Call	Contract
`FlyBrain.load()`	Load toy/local data offline, or a ready catalog model with explicit download=True.
`stimulate(channel)`	Queue a finite pulse, starting on the next tick. Overlapping currents add.
`step(20)`	Advance 20 ticks; at the default dt, that is 20 ms of simulation.
`action()`	Read motor intensity without advancing time. Values are independent, between 0 and 1.
`save(path)`	Write an atomic, self-contained JSON checkpoint including pending input.
`FlyBrain.restore(path)`	Return a new brain continuing the saved trajectory.

Control a headless game loop

Python

from flybrain import FlyBrain

brain = FlyBrain.load()
brain.stimulate("food", duration_ms=1000)
x = 0.0
for frame in range(50):
    brain.step(20)  # 50 game frames per second
    x += brain.action().walk * 3.0 * 0.020
print(x)

Game speed, physics and rendering are your choices. The toy inputs are pre-encoded stimuli, not image or odor processors. Motor outputs are heuristic readouts, not measured fly behavior.

Open a real circuit

Python · 0.2 alpha

brain = FlyBrain.load("male-cns-escape-v1", download=True)
gf = brain.neurons.select(cell_type="DNp01")
brain.bind_readout({"flash": gf})
brain.stimulate("looming_left", duration_ms=100)
brain.advance(duration_ms=100)
print(brain.action()["flash"])
print(brain.observe(gf, fields=["rates_hz"]).to_dict())

The model is 3.8 MB and uses real anatomical edges with assumed LIF dynamics. Read its model card. Direct currents, reversible silencing, custom output mappings and selected observations are available; checkpoints preserve them.

Inspect and extend

brain.state exposes immutable voltage, final-tick spikes, rates and time. Custom models keep neuron IDs as strings and synapses as signed pre → post edges. CPU is implemented; requesting wasm or cuda raises a clear unavailable-backend error.

Full API reference · Equations and backend contract