flydnet

Use the real Drosophila connectome (FlyWire v783) as neural-network layers, and ask whether the wiring actually matters. Pick any set of neurons by annotation (mushroom body, visual system, whole brain), wire a layer exactly as the fly's synapse map, and train it with backprop or dopamine-like associative learning. fd.compare trains the same model on the real connectome and on nested null models over paired seeds, runs exact sign-flip tests, warns about pitfalls, and reads the nested controls to say which structure matters. Own autograd engine on NumPy (CPU) / CuPy (GPU); PyTorch optional. Docs in Korean.

Alpha (0.2). API가 바뀔 수 있다. 연구용 도구이며, 정확도 향상을 기대할 도구는 아니다 (아래 "결과 요약").

초파리 커넥톰의 실제 배선을 신경망 층으로 쓰고, **"이 배선이 정말 중요한가"**를 통계로 묻는 라이브러리.

설치

pip install flydnet                  # CPU (NumPy·SciPy). torch 없음
pip install "flydnet[gpu-cuda12]"    # + GPU (CuPy, CUDA 12.x 드라이버). CUDA 13.x면 [gpu-cuda13]
pip install "flydnet[torch]"         # + torch 연동 (flydnet.torch)

python -m flydnet download           # FlyWire v783 연결·주석 + DoOR 냄새 데이터 (약 130 MB, 버전 고정·SHA-256 확인)
python -m flydnet                    # 데이터 상태

CUDA 버전은 nvidia-smi 오른쪽 위에 나온다. 데이터 위치는 ~/.flydnet/data (fd.set_data_dir(...)로 바꿈). FLYDNET_DEVICE=cpu로 CPU를 강제할 수 있다.

빠른 시작

import numpy as np, flydnet as fd

mb = fd.Circuit.from_flywire()                       # 오른쪽 버섯체: PN 344, KC 2597, APL 1, MBON 48
model = fd.Pathway(
    fd.Projection(784, 344),                         # 축삭 투사: 픽셀 → PN (모두 연결)
    fd.Neuropil(mb, "PN", "KC"),                     # 실제 PN→KC 배선 (연결 13,485개만, 부호 유지 학습)
    fd.LateralInhibition(frac=0.05),                 # APL 억제: KC 5%만
    fd.Projection(2597, 10),
)
rule = fd.AdaptivePlasticity(model.synapses(), rate=1e-3)
loss = fd.surprise(model(x), y)                      # 놀람 = 교차 엔트로피
rule.clear(); loss.retrograde(); rule.step()         # 역행성 신호(자동 미분) → 가소성

MNIST 2에폭 96.2% (GPU 약 6초, examples/ganglion_mnist.py).

대조 실험: fd.compare

같은 학습 절차를 실제 배선과 대조군 배선에 seed마다 짝지어 돌리고 비교한다.

def run(circuit, seed):                    # 회로 하나로 모델을 만들고 학습해서 점수 하나 (seed를 학습 난수에)
    ...
    return accuracy

report = fd.compare(run, mb, controls=["shuffled", "randomized", "shuffled_weights"], seeds=6, chance=1/30)
print(report)

조건                               평균              95% CI      실제 - 대조      d       p    실제 우세
real (실제 배선)                 0.7806     [0.759, 0.8021]
shuffled                     0.7833    [0.7685, 0.7982]    -0.002778  -0.16   0.750      1/6
randomized                   0.6517     [0.6353, 0.668]      +0.1289   5.35   0.031      6/6
shuffled_weights             0.7736     [0.755, 0.7922]    +0.006944   0.73   0.188      4/6

해석 (대조군 포함 관계):
  → 실제 배선이 randomized는 이기고 shuffled와는 차이가 없음 → 중요한 구조: 뉴런별 연결 수 분포 (차수·허브)

(스파이킹 버섯체, 합성 냄새 30클래스, examples/compare_odor.py --model lif, 약 20초)

• 같은 seed끼리 짝지어 학습 잡음을 상쇄하고, 부호 뒤집기 순열 검정(분포 가정 없음, seed ≤ 14면 정확한 p)을 쓴다.
• 대조군 포함 관계(randomized ⊂ shuffled ⊂ local ⊂ 실제)로 어떤 구조가 중요한지 해석한다.
• 함정을 경고한다: seed가 적어 p가 0.05 아래로 내려갈 수 없음, 상한 근처라 차이가 가려짐, 찍기 수준, 같은 seed인데 결과가 다름, 큰 구조 때문에만 이김, 효과는 큰데 비유의.

구성 요소

전체 뇌(13.9만 뉴런, 연결 1,509만)도 일반 GPU에서 학습된다 (ConnectomeLayer 학습 1스텝, RTX 5070: 배치 8에 0.58초, 배치 32에 1.3초).

자체 엔진 이름 (torch 대응)

이름은 같은 일을 하는 생물 구조에서 땄다 (역행성 신호, 시냅스, 조직, 신경 경로, 가소성…). 엔진 검증: 연산마다 수치 미분, torch와 출력·기울기·옵티마이저 비교, CPU↔GPU 비교 (tests/).

torch 연동

0.1 코드는 fd.이름을 fd.torch.이름으로 바꾸면 그대로 돈다 (fd.torch.ConnectomeLayer, fd.torch.AssocReadout, fd.torch.extract 등).

결과 요약

12개 실험 (자세한 방법·수치·한계는 소스 저장소의 REPORT.md):

개발

python -m venv .venv
.venv\Scripts\pip install --no-cache-dir -e ".[examples,dev,gpu-cuda13]"
.venv\Scripts\python -m pytest -q                       # 테스트
.venv\Scripts\python scripts\release.py bump patch      # 버전 올리기 + CHANGELOG 틀
.venv\Scripts\python scripts\release.py check --upload  # 커밋·CHANGELOG·PyPI 중복·테스트·빌드·설치 확인 후 업로드

데이터 출처: FlyWire v783 연결(Shiu et al. 2024, MIT), 세포 주석(Schlegel et al. 2024), DoOR 2.0(CC BY-SA 4.0). MIT 라이선스.