# flysim mushroom-body fix

Minimal repro and fix for a transposed dopaminergic read in
[flycoinrh](https://github.com/fruitflydev/flycoinrh) (`5aab4e78`), the
leaky integrate-and-fire simulation of the FlyEM male *Drosophila* CNS
connectome.

[![python](https://img.shields.io/badge/python-3.13%2B-3776AB?logo=python&logoColor=white)](#tests)
[![tests](https://img.shields.io/badge/tests-63%20passed%20%C2%B7%209%20skipped%20%C2%B7%202%20xfailed-brightgreen)](#tests)
[![no connectome required](https://img.shields.io/badge/connectome-not%20required-blue)](#tests)
[![licence](https://img.shields.io/badge/licence-MIT-0a7bbc)](LICENSE)
[![data licence](https://img.shields.io/badge/connectome%20data-CC--BY%204.0-0a7bbc)](NOTICE.md)

The bug is one transposed index. It is worth a repository of its own because it
silently inverts which mushroom-body compartment gets reinforced, which means
any downstream approach/avoidance readout built on it is reading the wrong sign
without any error being raised.

## The bug

`upstream/mushroom.py` classifies PAM / PPL1 compartments with

```python
pam_in = abs(W[pam][:, mbon].sum(axis=0))
```

`upstream/build_graph.py` fixes `W[i, j]` as **post-by-pre** (row = postsynaptic,
column = presynaptic). Under that convention `W[pam][:, mbon]` is
**MBON→DAN feedback**, not the dopaminergic input the docstring claims to
read.

A second fact makes the documented read unusable on the shipped graph:
`SIGN["dopamine"] = 0.0` and `keep = v != 0.0` delete every dopaminergic
edge, so transposing the indices alone yields zeros and switches learning
off. That is why the transposed read shipped: it is the only one that
returns a split.

## The fix

Upstream is vendored **unmodified**. Two changes, both in `flysim_mb/`:

1. `flysim_mb/graph.py` builds an unsigned modulatory matrix
   `graph_mod.npz`, `D[post, pre]`, `MIN_SYN_MOD = 1`.
2. `flysim_mb/mushroom.py` reads `D[mbon][:, dan].sum(axis=1)` — the
   synapses each MBON actually receives.

On MaleCNS v1.0 the corrected split is 24,005 / 20,037 PAM / PPL1-side
KC→MBON synapses (upstream's own code on the same graph reproduces its
README's 27,939 / 14,349, which is the transposed read). MBON01–10 land
PAM-side and MBON11–15 PPL1-side, matching the hemibrain compartment map.

The two strict xfails in `tests/upstream_audit/test_mushroom_orientation.py`
still xfail: they pin the upstream defect and **must not** be weakened.
`xfail_strict = true` is on, so "fixing" them turns the suite red — which is
the point.

## Tests

Synthetic graphs in `tests/upstream_audit/synthetic.py` and
`tests/core/synthetic.py` run **without the connectome**: their direction is
known by construction, which is the only way to prove an orientation.
`tests/core/test_real_graph.py` self-skips when `data/malecns-v1.0/` is
absent. Download URLs and sha256 are in `data/MANIFEST.md` (CC-BY 4.0,
~1.15 GB, not redistributed here).

```sh
python3.13 -m venv .venv
.venv/bin/pip install -e '.[dev]'
.venv/bin/python -m pytest tests/
```

```
63 passed, 9 skipped, 2 xfailed
```

The 9 skips are `test_real_graph.py` (connectome absent). The 2 xfails
are the strict pins of the upstream defect.

## Layout

```
upstream/     flycoinrh at 5aab4e78: build_graph.py, mushroom.py, flysim.py, flyeye.py
flysim_mb/    the two-part fix (graph, mushroom, populations)
tests/        upstream_audit (pins the bug) + core (proves the fix)
docs/         UPSTREAM_NOTES.md §1–2 and the Phase 0.5 addendum
data/         MANIFEST.md only: the connectome is not in this repository
```

## Where this comes from

This is a standalone extract from [FLYFAM](https://github.com/maumcrez-svg/flyfam)
([flyfam.xyz](https://flyfam.xyz)), where the corrected mushroom body drives a
pre-registered associative-conditioning experiment and, downstream of that, a
paper-trading loop. Nothing in *this* repository is about markets: there is no
instrument, no price, no decoder and no trading code. It is the neuroscience
defect and its fix, with the tests that pin both.

## Attribution and licences

- **`upstream/`** — [fruitflydev/flycoinrh](https://github.com/fruitflydev/flycoinrh)
  at `5aab4e7895a1f5930319bf3bde8010b350a163a2`, **MIT**, © 2026 fruitflydev.
  Vendored verbatim with its own `LICENSE` and `NOTICE`. No upstream file is
  modified anywhere in this tree; the fix lives only in `flysim_mb/`.
- **Connectome** — FlyEM male *Drosophila* CNS v1.0, © HHMI Janelia FlyEM, the
  Cambridge Connectomics Group and Google Research, **CC-BY 4.0**. The data
  files are **not** in this repository; `data/MANIFEST.md` records source URLs,
  byte sizes and sha256 so the download is reproducible. The attribution
  obligation travels with every derived artifact, a built graph included.
- **`flysim_mb/`, `tests/`, `docs/`** — **MIT**, same as the upstream they fix.
- Simulation approach after Shiu et al. 2024 and Lappalainen et al. 2024.

See [`LICENSE`](LICENSE) and [`NOTICE.md`](NOTICE.md). Not affiliated with HHMI
Janelia, the Cambridge Connectomics Group, Google Research or fruitflydev.