BrainGo-bridge

Python bridge connecting BrainGo db to the BAAIWorm 3D body simulation — replacing the NEURON simulator backend with BrainGo db's Rust-based neural simulation engine.

English | 中文

This provides:

• 10-100x faster neural simulation via BrainDB's optimized Rust engine
• Persistent storage via .braindb binary format (mmap-friendly)
• REST API for real-time neuron monitoring and control
• WAL crash recovery for long-running simulations

Architecture

BAAIWorm (Python)                    BrainGo db (Rust)
┌──────────────────┐                ┌──────────────────┐
│  eworm_data/      │                │  braingo/         │
│   cell params     │──load_baaiworm──▶  .braindb file   │
│   connection xlsx │                │  302 neurons      │
│   config.json     │                │  20965 synapses   │
└──────────────────┘                └──────────────────┘
         │                                    │
         ▼                                    ▼
┌──────────────────┐                ┌──────────────────┐
│  braindb_sim/     │                │  braindb-server   │
│   braindb_neuron  │──pyo3/REST────▶  REST API         │
│   _sim.py         │                │  :3000            │
│   braindb_        │                └──────────────────┘
│   circuit.py      │
│   transform.py    │
│   muscle_iface.py │
└──────────────────┘
         │
         ▼
┌──────────────────┐
│  Metaworm/        │
│   FEM body sim    │
│   muscle act.     │
└──────────────────┘

Quick Start

# 1. Build BrainDB with Python bindings
cd braindb && cargo build --release

# 2. Load C. elegans connectome into BrainDB
python -c "
from baaiworm_bridge.braindb_sim.braindb_neuron_sim import BrainDBNeuronSim
sim = BrainDBNeuronSim.from_baaiworm('eworm_data', 'celegans.braindb')
sim.run(1000)  # 100ms
print(sim.get_voltages([0, 1, 2]))
"

# 3. Or use the REST API with connection config
python -c "
from baaiworm_bridge.braindb_sim import BrainDBNeuronSim, BrainDBConnectionConfig

# From config object
cfg = BrainDBConnectionConfig(
    database='celegans.braindb',
    backend='rest', host='localhost', port=3000,
    stdp_enabled=True, wal_enabled=True
)
sim = BrainDBNeuronSim(cfg)

# From DSN string
sim = BrainDBNeuronSim.from_dsn('braindb://localhost:3000/celegans?stdp=true')

# From config file
sim = BrainDBNeuronSim.from_config_file('braindb_config.json')

# From environment variables
# BRAINDB_HOST=localhost BRAINDB_PORT=3000 BRAINDB_DATABASE=celegans
sim = BrainDBNeuronSim.from_env()
"

Connection Configuration

BrainDB uses a database-style connection configuration similar to PostgreSQL's libpq:

Parameter	Default	Description
backend	"pyo3"	"pyo3" / "rest" / "embedded"
database	""	.braindb file path (pyo3) or DB name (rest)
host	"localhost"	Server hostname (rest/embedded)
port	3000	Server port
api_key	""	API key for server auth
auth_token	""	Bearer token (overrides api_key)
connect_timeout	10.0	Connection timeout (seconds)
request_timeout	30.0	Request timeout (seconds)
pool_size	4	Connection pool size
dt	0.1	Simulation timestep (ms)
spike_threshold	30.0	Spike detection threshold (mV)
stdp_enabled	false	STDP plasticity
wal_enabled	false	Write-Ahead Log for crash recovery
wal_checkpoint_interval	10000	Ticks between WAL checkpoints
snapshot_interval	0	Auto-snapshot interval (0=disabled)
parallel_update	false	Parallel neuron update (rayon)

DSN Format

braindb:///path/to/file.braindb?param=value          # local file
braindb://[key@]host:port/database?param=value       # remote server

Environment Variables

BRAINDB_BACKEND=rest
BRAINDB_DATABASE=celegans
BRAINDB_HOST=192.168.1.100
BRAINDB_PORT=3000
BRAINDB_API_KEY=my-secret-key
BRAINDB_DT=0.1
BRAINDB_WAL_ENABLED=true

Directory Layout

baaiworm_bridge/
├── __init__.py
├── README.md
├── requirements.txt
├── braindb_config.example.json  # Example connection config
├── test_bridge.py               # Integration test
├── eworm_data/              # BAAIWorm data (copied, unmodified)
│   ├── components/
│   │   └── param/
│   │       ├── cell/        # 302 neuron JSON params
│   │       └── connection/  # SI5-302.xlsx synapse data
│   └── network/
│       └── config.json      # BAAIWorm network config
└── braindb_sim/             # BrainDB bridge code (new)
    ├── __init__.py
    ├── connection_config.py     # Database connection configuration
    ├── connection_manager.py    # Connection pool & lifecycle
    ├── braindb_neuron_sim.py    # Core simulation wrapper
    ├── braindb_circuit.py       # Circuit abstraction over BrainDB
    ├── braindb_transform.py     # Config → BrainDB transform
    ├── muscle_interface.py      # BrainDB → Metaworm muscle bridge
    └── run_baaiworm_braindb.py  # Main entry point