flycns 0.6.0__tar.gz

flycns-0.6.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Felipe Santibanez-Leal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

flycns-0.6.0/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: flycns
+Version: 0.6.0
+Summary: Compile fly connectome releases (MaleCNS v1.0) into simulation-ready graphs with two-eye column maps, and simulate the whole central nervous system (graded optic lobe plus spiking LIF) with parity between Python and the browser.
+Author-email: Felipe Santibanez-Leal <fsantibanez@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/fsantibanezleal/CAOS_FlyCNS
+Project-URL: Source, https://github.com/fsantibanezleal/CAOS_FlyCNS
+Project-URL: Issues, https://github.com/fsantibanezleal/CAOS_FlyCNS/issues
+Project-URL: Changelog, https://github.com/fsantibanezleal/CAOS_FlyCNS/blob/main/CHANGELOG.md
+Keywords: connectome,drosophila,malecns,neuroscience,simulation,spiking,leaky-integrate-and-fire,compound-eye
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.26
+Provides-Extra: release
+Requires-Dist: pyarrow>=15; extra == "release"
+Requires-Dist: pandas>=2.1; extra == "release"
+Provides-Extra: gpu
+Requires-Dist: torch>=2.3; extra == "gpu"
+Provides-Extra: parity
+Requires-Dist: brian2>=2.7; extra == "parity"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: mmh3>=4.0; extra == "dev"
+Dynamic: license-file
+
+# flycns
+
+[![ci](https://github.com/fsantibanezleal/CAOS_FlyCNS/actions/workflows/ci.yaml/badge.svg?branch=main)](https://github.com/fsantibanezleal/CAOS_FlyCNS/actions/workflows/ci.yaml)
+[![license: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+Compile a fly connectome release into a graph a simulator can run, model the two compound eyes over the release's
+own optic-lobe columns, and simulate the whole central nervous system with the published neuron models, in Python
+and in the browser, with the two implementations held to each other by parity tests.
+
+- **Release:** MaleCNS v1.0, the complete male *Drosophila* CNS (166,700 neurons, brain and ventral nerve cord;
+  Berg et al., *Cell* 189:5504-5526, 2026, doi:10.1016/j.cell.2026.08.015; data CC BY 4.0). Both optic lobes are
+  mapped column by column in the release (879 columns left, 892 right), which is what lets two eyes feed it.
+- **Neuron models:** the published leaky integrate-and-fire model of the fly brain (Shiu et al., *Nature*
+  634:210-219, 2024, doi:10.1038/s41586-024-07763-9), and a graded optic lobe in the form of the connectome-constrained
+  visual model (Lappalainen et al., *Nature* 2024, doi:10.1038/s41586-024-07939-3).
+- **Two implementations, one set of equations:** a Python reference (NumPy, and PyTorch on a GPU) and a browser
+  engine (`@fasl-work/flycns`, WebGPU with a worker fallback).
+
+## What it is not
+
+A general neural simulator, a learned model of the fly, or a claim about behaviour. Synapse counts and signs are
+data and never change; the package integrates published equations over them and says where those equations are
+known to fall short.
+
+## Status
+
+Version 0.06.000: the MaleCNS v1.0 compiler and compiled format; the two compound eyes over the release's own
+columns, their vertical set by the dorsal rim; the published spiking model, identical to a literal Brian2
+transcription, on a NumPy reference and a GPU engine; the graded visual neurons as flyvis computes them, held to
+flyvis itself, with its 50 trained networks shipped as data; and flyvis's numbers transferred onto the neuron-level
+wiring of both MaleCNS optic lobes, where T4 cells, measured through the modelled eyes, prefer their known
+directions; and the whole CNS coupled, in four engines (the published model everywhere, which does not see; the
+graded optic lobes with the spiking CNS, which carries a flash to the motor neurons; flyvis's own networks mapped
+onto MaleCNS; and the stabilised version, which leaves the published model one state). Next: the browser engine.
+This README lists capabilities only as they land.
+
+## Compile MaleCNS v1.0
+
+Download the four tables listed in [`docs/releases/01_malecns-v1.md`](docs/releases/01_malecns-v1.md) into one
+folder, then:
+
+```python
+from pathlib import Path
+from flycns.release import compile_malecns_v1
+from flycns.compiled import read_compiled
+
+compile_malecns_v1(Path("malecns-tables"), Path("compiled/malecns-v1.0"), progress=print)
+graph = read_compiled(Path("compiled/malecns-v1.0"))      # every array verified against its SHA-256
+print(graph.n_neurons, graph.n_edges, graph.counts["columns"])
+```
+
+A table whose SHA-256 differs from the locked value is refused. Compilation streams the 13 GB synapse table in record
+batches and takes a few minutes on a desktop.
+
+## Simulate
+
+```python
+from pathlib import Path
+
+from flycns.compiled import read_compiled
+from flycns.dynamics import Drive, LIFReference, synaptic_weights
+
+graph = read_compiled(Path("compiled/malecns-v1.0"))
+weights = synaptic_weights(graph["csr_indptr"], graph["csr_indices"], graph["csr_count"], graph["neuron_sign"], 0.275)
+engine = LIFReference(graph["csr_indptr"], graph["csr_indices"], weights)      # or LIFTorch on a GPU
+run = engine.run(10_000, Drive(activate={1234: 150.0}), seed=0)                   # one second of model time
+print(run.spike_counts().sum(), "spikes")
+```
+
+The graded visual neurons run through `flycns.dynamics.GradedReference` (or `GradedTorch`), with the trained flyvis
+parameters from `flycns.flyvis.load_ensemble()`; see [`docs/models/03_graded.md`](docs/models/03_graded.md).
+
+## Install (development)
+
+```bash
+python -m venv .venv
+.venv/Scripts/python -m pip install -e ".[dev,release,parity]"     # add ,gpu for PyTorch; .venv/bin/python elsewhere
+.venv/Scripts/python -m pytest -rs
+npm ci && npm test
+```
+
+## Documentation
+
+The wiki starts at [`docs/README.md`](docs/README.md).
+
+## License
+
+Code: MIT. Connectome data are not redistributed here; they are fetched from the release with their hashes checked,
+and remain under their own licence (MaleCNS: CC BY 4.0). The trained parameters of flyvis's pretrained networks
+ship inside the package under flyvis's MIT licence, whose notice travels with them
+(`src/flycns/data/flyvis-1.2.0-ensemble/LICENSE-flyvis.txt`).

flycns-0.6.0/README.md

@@ -0,0 +1,91 @@
+# flycns
+
+[![ci](https://github.com/fsantibanezleal/CAOS_FlyCNS/actions/workflows/ci.yaml/badge.svg?branch=main)](https://github.com/fsantibanezleal/CAOS_FlyCNS/actions/workflows/ci.yaml)
+[![license: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+Compile a fly connectome release into a graph a simulator can run, model the two compound eyes over the release's
+own optic-lobe columns, and simulate the whole central nervous system with the published neuron models, in Python
+and in the browser, with the two implementations held to each other by parity tests.
+
+- **Release:** MaleCNS v1.0, the complete male *Drosophila* CNS (166,700 neurons, brain and ventral nerve cord;
+  Berg et al., *Cell* 189:5504-5526, 2026, doi:10.1016/j.cell.2026.08.015; data CC BY 4.0). Both optic lobes are
+  mapped column by column in the release (879 columns left, 892 right), which is what lets two eyes feed it.
+- **Neuron models:** the published leaky integrate-and-fire model of the fly brain (Shiu et al., *Nature*
+  634:210-219, 2024, doi:10.1038/s41586-024-07763-9), and a graded optic lobe in the form of the connectome-constrained
+  visual model (Lappalainen et al., *Nature* 2024, doi:10.1038/s41586-024-07939-3).
+- **Two implementations, one set of equations:** a Python reference (NumPy, and PyTorch on a GPU) and a browser
+  engine (`@fasl-work/flycns`, WebGPU with a worker fallback).
+
+## What it is not
+
+A general neural simulator, a learned model of the fly, or a claim about behaviour. Synapse counts and signs are
+data and never change; the package integrates published equations over them and says where those equations are
+known to fall short.
+
+## Status
+
+Version 0.06.000: the MaleCNS v1.0 compiler and compiled format; the two compound eyes over the release's own
+columns, their vertical set by the dorsal rim; the published spiking model, identical to a literal Brian2
+transcription, on a NumPy reference and a GPU engine; the graded visual neurons as flyvis computes them, held to
+flyvis itself, with its 50 trained networks shipped as data; and flyvis's numbers transferred onto the neuron-level
+wiring of both MaleCNS optic lobes, where T4 cells, measured through the modelled eyes, prefer their known
+directions; and the whole CNS coupled, in four engines (the published model everywhere, which does not see; the
+graded optic lobes with the spiking CNS, which carries a flash to the motor neurons; flyvis's own networks mapped
+onto MaleCNS; and the stabilised version, which leaves the published model one state). Next: the browser engine.
+This README lists capabilities only as they land.
+
+## Compile MaleCNS v1.0
+
+Download the four tables listed in [`docs/releases/01_malecns-v1.md`](docs/releases/01_malecns-v1.md) into one
+folder, then:
+
+```python
+from pathlib import Path
+from flycns.release import compile_malecns_v1
+from flycns.compiled import read_compiled
+
+compile_malecns_v1(Path("malecns-tables"), Path("compiled/malecns-v1.0"), progress=print)
+graph = read_compiled(Path("compiled/malecns-v1.0"))      # every array verified against its SHA-256
+print(graph.n_neurons, graph.n_edges, graph.counts["columns"])
+```
+
+A table whose SHA-256 differs from the locked value is refused. Compilation streams the 13 GB synapse table in record
+batches and takes a few minutes on a desktop.
+
+## Simulate
+
+```python
+from pathlib import Path
+
+from flycns.compiled import read_compiled
+from flycns.dynamics import Drive, LIFReference, synaptic_weights
+
+graph = read_compiled(Path("compiled/malecns-v1.0"))
+weights = synaptic_weights(graph["csr_indptr"], graph["csr_indices"], graph["csr_count"], graph["neuron_sign"], 0.275)
+engine = LIFReference(graph["csr_indptr"], graph["csr_indices"], weights)      # or LIFTorch on a GPU
+run = engine.run(10_000, Drive(activate={1234: 150.0}), seed=0)                   # one second of model time
+print(run.spike_counts().sum(), "spikes")
+```
+
+The graded visual neurons run through `flycns.dynamics.GradedReference` (or `GradedTorch`), with the trained flyvis
+parameters from `flycns.flyvis.load_ensemble()`; see [`docs/models/03_graded.md`](docs/models/03_graded.md).
+
+## Install (development)
+
+```bash
+python -m venv .venv
+.venv/Scripts/python -m pip install -e ".[dev,release,parity]"     # add ,gpu for PyTorch; .venv/bin/python elsewhere
+.venv/Scripts/python -m pytest -rs
+npm ci && npm test
+```
+
+## Documentation
+
+The wiki starts at [`docs/README.md`](docs/README.md).
+
+## License
+
+Code: MIT. Connectome data are not redistributed here; they are fetched from the release with their hashes checked,
+and remain under their own licence (MaleCNS: CC BY 4.0). The trained parameters of flyvis's pretrained networks
+ship inside the package under flyvis's MIT licence, whose notice travels with them
+(`src/flycns/data/flyvis-1.2.0-ensemble/LICENSE-flyvis.txt`).

flycns-0.6.0/pyproject.toml

@@ -0,0 +1,64 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "flycns"
+version = "0.6.0"
+description = "Compile fly connectome releases (MaleCNS v1.0) into simulation-ready graphs with two-eye column maps, and simulate the whole central nervous system (graded optic lobe plus spiking LIF) with parity between Python and the browser."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "Felipe Santibanez-Leal", email = "fsantibanez@gmail.com" }]
+keywords = ["connectome", "drosophila", "malecns", "neuroscience", "simulation", "spiking", "leaky-integrate-and-fire", "compound-eye"]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Bio-Informatics",
+    "Typing :: Typed",
+]
+dependencies = ["numpy>=1.26"]
+
+[project.optional-dependencies]
+# reading release files (feather tables)
+release = ["pyarrow>=15", "pandas>=2.1"]
+# the GPU path of the dynamics
+gpu = ["torch>=2.3"]
+# the literal Brian2 transcription used by the parity tests
+parity = ["brian2>=2.7"]
+# mmh3 is the independent MurmurHash3 oracle for the counter-based generator
+dev = ["pytest>=8.0", "ruff>=0.6", "mmh3>=4.0"]
+
+[project.urls]
+Homepage = "https://github.com/fsantibanezleal/CAOS_FlyCNS"
+Source = "https://github.com/fsantibanezleal/CAOS_FlyCNS"
+Issues = "https://github.com/fsantibanezleal/CAOS_FlyCNS/issues"
+Changelog = "https://github.com/fsantibanezleal/CAOS_FlyCNS/blob/main/CHANGELOG.md"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+flycns = ["py.typed", "data/**/*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+markers = [
+    "data: needs the release files on disk (skipped when absent, and reported with -rs)",
+    "gpu: needs a CUDA device",
+    "parity: needs brian2",
+]
+
+[tool.ruff]
+line-length = 110
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+ignore = ["E501"]

flycns-0.6.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

flycns-0.6.0/src/flycns/__init__.py

@@ -0,0 +1,7 @@
+"""flycns: fly connectome releases compiled for simulation, two compound eyes, and the whole CNS in motion.
+
+The display version (``X.XX.XXX``) lives in the ``VERSION`` file at the repository root; ``__version__`` is its
+semantic form, the one the package index and ``pyproject.toml`` carry.
+"""
+
+__version__ = "0.6.0"

flycns-0.6.0/src/flycns/compiled.py

@@ -0,0 +1,150 @@
+"""The compiled directory: the one thing both simulators read.
+
+A compiled connectome is a directory holding ``manifest.json`` and one little-endian binary file per array. The
+manifest lists every array with its dtype, shape and SHA-256, plus the release it came from, the hashes of the source
+tables, the string tables the index arrays point into, and the counts the compiler measured. The reader refuses a
+directory whose arrays do not match their recorded hashes: a simulation must never run on a graph that is not the one
+that was compiled.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+
+SCHEMA = "flycns.compiled/1"
+
+#: dtypes the format allows, by name; each is written little-endian.
+DTYPES = {
+    "int8": np.int8,
+    "uint8": np.uint8,
+    "int16": np.int16,
+    "uint16": np.uint16,
+    "int32": np.int32,
+    "uint32": np.uint32,
+    "int64": np.int64,
+    "float32": np.float32,
+}
+
+
+class CompiledError(ValueError):
+    """A compiled directory that cannot be trusted: a missing file, a wrong shape, or a hash that differs."""
+
+
+def sha256_bytes(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+def sha256_file(path: Path, chunk: int = 1 << 24) -> str:
+    digest = hashlib.sha256()
+    with open(path, "rb") as handle:
+        while block := handle.read(chunk):
+            digest.update(block)
+    return digest.hexdigest()
+
+
+def _dtype_name(array: np.ndarray) -> str:
+    for name, dtype in DTYPES.items():
+        if array.dtype == np.dtype(dtype):
+            return name
+    raise CompiledError(f"dtype {array.dtype} is not allowed in a compiled directory")
+
+
+def write_compiled(directory: Path, arrays: dict[str, np.ndarray], meta: dict[str, Any],
+                   schema: str = SCHEMA) -> dict[str, Any]:
+    """Write ``arrays`` and a manifest into ``directory``; return the manifest.
+
+    ``meta`` carries the release, sources, counts and string tables; it is stored as given under the manifest's
+    ``release``, ``sources``, ``counts`` and ``strings`` keys. Array files are written in name order so two
+    compilations of the same inputs produce the same bytes.
+    """
+    directory = Path(directory)
+    directory.mkdir(parents=True, exist_ok=True)
+    entries = []
+    for name in sorted(arrays):
+        array = np.ascontiguousarray(arrays[name])
+        dtype = _dtype_name(array)
+        data = array.astype(array.dtype.newbyteorder("<"), copy=False).tobytes(order="C")
+        file_name = f"{name}.bin"
+        (directory / file_name).write_bytes(data)
+        entries.append(
+            {"name": name, "dtype": dtype, "shape": list(array.shape), "file": file_name, "bytes": len(data),
+             "sha256": sha256_bytes(data)}
+        )
+    manifest = {
+        "schema": schema,
+        "release": meta.get("release", {}),
+        "sources": meta.get("sources", []),
+        "counts": meta.get("counts", {}),
+        "strings": meta.get("strings", {}),
+        "arrays": entries,
+    }
+    # LF on every system, so the same inputs give the same bytes on Windows and Linux
+    (directory / "manifest.json").write_text(json.dumps(manifest, indent=2, sort_keys=True) + "\n", encoding="utf-8",
+                                             newline="\n")
+    return manifest
+
+
+@dataclass
+class Compiled:
+    """A verified compiled connectome: its manifest, arrays and string tables."""
+
+    directory: Path
+    manifest: dict[str, Any]
+    arrays: dict[str, np.ndarray] = field(repr=False)
+
+    @property
+    def strings(self) -> dict[str, list[str]]:
+        return self.manifest["strings"]
+
+    @property
+    def counts(self) -> dict[str, Any]:
+        return self.manifest["counts"]
+
+    @property
+    def n_neurons(self) -> int:
+        return int(self.arrays["neuron_body_id"].shape[0])
+
+    @property
+    def n_edges(self) -> int:
+        return int(self.arrays["csr_indices"].shape[0])
+
+    def __getitem__(self, name: str) -> np.ndarray:
+        return self.arrays[name]
+
+
+def read_compiled(directory: Path, verify: bool = True, schema: str = SCHEMA) -> Compiled:
+    """Read a compiled directory, checking every array against the manifest.
+
+    With ``verify`` (the default) each file's SHA-256 is recomputed; any difference, a missing file or a size that
+    does not match the declared shape raises :class:`CompiledError`.
+    """
+    directory = Path(directory)
+    manifest_path = directory / "manifest.json"
+    if not manifest_path.is_file():
+        raise CompiledError(f"{directory} holds no manifest.json")
+    manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+    if manifest.get("schema") != schema:
+        raise CompiledError(f"schema {manifest.get('schema')!r} is not {schema!r}")
+    arrays: dict[str, np.ndarray] = {}
+    for entry in manifest["arrays"]:
+        path = directory / entry["file"]
+        if not path.is_file():
+            raise CompiledError(f"array {entry['name']} is missing its file {entry['file']}")
+        data = path.read_bytes()
+        if verify and sha256_bytes(data) != entry["sha256"]:
+            raise CompiledError(
+                f"array {entry['name']}: SHA-256 {sha256_bytes(data)} differs from the manifest's {entry['sha256']}"
+            )
+        dtype = np.dtype(DTYPES[entry["dtype"]]).newbyteorder("<")
+        shape = tuple(entry["shape"])
+        expected = int(np.prod(shape, dtype=np.int64)) * dtype.itemsize
+        if len(data) != expected:
+            raise CompiledError(f"array {entry['name']}: {len(data)} bytes where shape {shape} needs {expected}")
+        arrays[entry["name"]] = np.frombuffer(data, dtype=dtype).reshape(shape).astype(dtype.newbyteorder("="))
+    return Compiled(directory=directory, manifest=manifest, arrays=arrays)

flycns-0.6.0/src/flycns/data/flyvis-1.2.0-ensemble/LICENSE-flyvis.txt

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2023 Janne K. Lappalainen, Fabian D. Tschopp, Mason McGill, Jakob H. Macke, Srinivas C. Turaga
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.