connectome

A whole nervous system's wiring diagram as one asset: every neuron with its soma position, cell type, class and neurotransmitter, and every neuron-to-neuron connection with its synapse count, packed into the binary form a GPU spiking simulation binds directly. The brain module of the fruitFly package runs any instance of this type; the type itself carries no animal.

maleCNS.connectome/
  manifest.json   counts, provenance, byte layouts, vocabularies
  neurons.bin     32 bytes per neuron
  offsets.bin     u32[neurons + 1], CSR row starts into edges.bin
  edges.bin       u32 per connection: target index | synapse count << 18
  README.md       the animal, the dataset, the release, the license
  .metadata       description + tags

The manifest

{
  "dataset": "MaleCNS v1.0 ...",
  "license": "CC-BY 4.0",
  "citation": "...",
  "neurons": 164587,
  "edges": 25563197,
  "edge_format": "...",
  "neuron_record": "...",
  "flags": "...",
  "sign_rule": "...",
  "soma_centre_um": [x, y, z],
  "vocab": {
    "types": [...], "superclasses": [...], "classes": [...],
    "neurotransmitters": [...], "sides": [...], "dimorphism": [...], "fruDsx": [...]
  }
}

The neuron record (32 bytes, little-endian)

offset	type	field
0	f32	soma x, micrometres, centred on soma_centre_um
4	f32	soma y
8	f32	soma z
12	u32	index into vocab.types
16	u32	flags (below)
20	u32	source body id, low 32 bits
24	u32	source body id, high 32 bits
28	u32	out-degree (number of edges in this neuron's row)

Flags: bits 0-5 superclass, 6-13 class, 14-17 neurotransmitter, 18-19 side, bit 20 has a soma position, 21-23 dimorphism, 24-26 fruDsx, bit 27 set when the neuron excites its targets (clear when it inhibits). Every bit field indexes the vocabulary of the same name, 0 being unknown.

Parts

A payload larger than one blob may carry is stored as numbered parts, edges.0.bin, edges.1.bin, ..., and the manifest's parts says how many ("parts": { "edges": 2 }). ref:parts("edges") lists them with the byte offset each starts at, so a GPU upload writes each part in place; ref:bytes("edges") concatenates them when a caller wants the whole table. A payload without an entry in parts is the single file <name>.bin.

The edge (4 bytes)

Bits 0-17 hold the postsynaptic neuron's index, bits 18-31 the synapse count clamped at 16383. Row i of the table is edges[offsets[i] .. offsets[i+1]), so a neuron's outgoing connections are one contiguous run, which is what an event-driven spike propagation reads.

Reading one from Luau

local ref = asset.resolve("maleCNS", "connectome")
local m = ref:manifest()              -- the decoded manifest
local neurons = ref:bytes("neurons")  -- a Luau `buffer` of neurons.bin
local edges = ref:bytes("edges")      -- the whole edge table, for a GPU upload
ref:counts()                          -- { neurons = ..., edges = ... }

ref:bytes(name) reads the whole file into a Luau buffer, so a call for edges on a large connectome holds a hundred megabytes until the caller drops it; hand it to a GPU buffer's writeBytes and let it go.

Making one

A connectome is written by a packer outside the engine (the fruitFly package's README names the script for MaleCNS). It reads the dataset's own export, assigns dense indices, sorts edges by presynaptic neuron, and writes the four files above. asset.create("connectome", "<name>") scaffolds the folder with an empty manifest for a packer to fill.