# Flyvis visual-response baseline

This is an adaptation of the authors' `04_flyvision_moving_edge_responses.ipynb`.
It calls the same official `compute_responses` machinery directly to bypass
response caches. It does not train the model or attach a body or motor decoder.

## Immutable inputs

- Source: https://github.com/TuragaLab/flyvis/tree/0a69fa2fc8e1bfe1d837d722c252ab5f5d6fcbfa
- Model: the notebook's first sorted model, `results/flow/0000/000`.
- Official pretrained ZIP SHA-256:
  `71c78d4070556a536b13b23ee3139cd2788aa2a9d07d430a223b4edead281db1`.
- Stimulus, readouts, reference directions and acceptance criteria: `plan.json`,
  frozen before inference. `status_at_freeze` deliberately remains `prepared-not-run`;
  the actual outcome is in `results-v01/summary.json`.
- Selected upstream source hashes and frozen plan hash: `source-manifest.json`.

## Setup on an isolated Linux machine

Use Python 3.12 and an NVIDIA GPU compatible with PyTorch CUDA 12.4. Run in a new
working directory with the supplied plan, runner, auditor, constraints and source
manifest. Do not install into an existing experiment environment.

```sh
git clone https://github.com/TuragaLab/flyvis.git source
git -C source checkout 0a69fa2fc8e1bfe1d837d722c252ab5f5d6fcbfa
python3.12 -m venv .venv
.venv/bin/python -m pip install torch==2.5.1 torchvision==0.20.1 --index-url https://download.pytorch.org/whl/cu124
SETUPTOOLS_SCM_PRETEND_VERSION_FOR_FLYVIS=0.0+g0a69fa2 .venv/bin/python -m pip install -c constraints.txt -e source
FLYVIS_ROOT_DIR="$PWD/data" .venv/bin/flyvis download-pretrained --skip_large_files
```

The recorded run copied a clean source checkout without its `.git` directory.
The explicit setuptools-scm version labels that source snapshot; it is not an
upstream release number. The official pretrained ZIP was retrieved through the
download endpoint referenced by the authors' downloader and its full SHA-256
was checked before extraction. Credentials are not part of this record.
`requirements-lock.txt` retains the installed dependency versions and replaces
the machine-specific editable-source location with the pinned source identifier.

## Execute and inspect

```sh
mkdir -p logs
OMP_NUM_THREADS=1 OPENBLAS_NUM_THREADS=1 MKL_NUM_THREADS=1 NUMBA_NUM_THREADS=1 MPLBACKEND=Agg CUBLAS_WORKSPACE_CONFIG=:4096:8 nice -n 15 timeout --kill-after=30s 1800 .venv/bin/python -u run.py > logs/run-v01.log 2>&1
.venv/bin/python validate.py
.venv/bin/python -m pip freeze > requirements-lock.txt
.venv/bin/python -m pip check
```

Use a fresh output directory for a reproduction: the runner refuses to overwrite
`results-v01`. Preserve failures and record any repair as a new attempt. GPU
deterministic algorithms are enabled. The repeated movies use the same seed and
are a numerical replay test, not independent seeds, animals or a new learning test.

Recorded attempt history: the first launch stopped at source-hash preflight
because its manifest used `LICENSE` instead of the upstream tracked `license`.
No inference or output directory was created. `source-manifest-v01.json` and the
original error are preserved; only this path spelling was repaired. The second
launch completed inference, with the unchanged frozen plan and `run.py`, writing
`logs/run-v02.log` and `results-v01`. See `execution-history.json`.

The `.npz` files contain every stimulus pixel and every central-column cell-type
trace for moving, repeat and uniform-grey conditions. Response values are model
activity units, not measured Hz, millivolts or motor commands. Metrics use a
prespecified baseline-subtracted peak; they are not the paper's full validation
score. `validate.py` recomputes metrics and criteria from the saved arrays using
NumPy only. It does not rerun inference or validate biological function.

## Integration boundary

`integration-audit.json` records the average-filter template, input/output types
and absence of a FlyWire root-ID correspondence in that template. No connection
to the original Shiu model, DNa02, legs, vehicle or controller is implemented by
this run. Learned resting potentials/time constants/connection strengths belong
to the authors' pretrained model; no additional local training is performed.