neuroml-loihi 1.0.0

NeuroML/LEMS to Loihi 2 toolchain

NeuroML2Loihi

An open-source toolchain for converting NeuroML models to run on Intel's Loihi 2 neuromorphic hardware and simulator.

Overview

NeuroML2Loihi takes a model expressed in the community-standard NeuroML/LEMS formats and lowers it onto Loihi 2, closing the gap between platform-independent computational neuroscience models and neuromorphic silicon. The toolchain:

1. Parses NeuroML (.nml) and LEMS (.xml) model files into a unified intermediate representation
2. Assembles runnable networks from parsed models
3. Executes on Loihi 2 backends (simulator or hardware)
4. Records and analyzes neural dynamics (spikes, membrane traces, firing rates)
5. Compares outputs across backends for reproducibility validation

The pipeline is a straight line from model files to analysis: NeuroML and LEMS are parsed into a graph and configuration, a tag → primitive Mapping turns model elements into Lava processes, and the assembled Network is executed on the chosen Backend and recorded for Analysis.

Flagship example: the C. elegans connectome on Loihi 2

The driving use case for this toolchain is deploying the full 302-neuron C. elegans connectome (via the c302 NeuroML models from the OpenWorm project) onto Loihi 2. The heatmap below shows recorded membrane potentials for all 302 neurons over a 300 ms simulation, driven through the touch-sensory PLM neurons — the periodic drive on PLML/PLMR propagates through the connectome to downstream interneurons (AVAL, AVBL, DVA, PVR, …).

Smaller subnetworks (e.g. the PLM touch circuit) are included as examples for fast iteration before scaling up to the full network.

Installation

Prerequisites

Lava must be installed from source. This project requires the Lava neuromorphic computing framework, which is not available via pip and must be installed from source.

To install Lava, follow the instructions at: https://github.com/lava-nc/lava

From Source (Development)

# Clone the repository
git clone https://github.com/DRosen766/NeuroML2Loihi.git
cd NeuroML2Loihi

# Install in development mode
pip install -e .

# Or install with development dependencies
pip install -e ".[dev]"

For Users (when released)

pip install neuroml-loihi

Note: You will still need to install Lava from source separately.

Quick Start

The toolchain follows a parse → assemble → execute → save flow:

from pathlib import Path

from neuroml2loihi.parsers import NMLParser, LEMSParser
from neuroml2loihi.networks import Network
from neuroml2loihi.backends import SimulatorBackend
from neuroml2loihi.experiments import Experiment
from neuroml2loihi.analysis import Plotter

# 1. Parse the NeuroML network and LEMS experiment definition
graph = NMLParser(Path("model.nml")).parse()
config = LEMSParser(Path("experiment.xml")).parse()

# 2. Assemble a runnable network from the parsed model
network = Network(graph=graph, config=config)

# 3. Execute on a backend (SimulatorBackend or HardwareBackend)
experiment = Experiment(network=network, backend=SimulatorBackend(config), config=config)
experiment.execute()

# 4. Save artifacts (.dat spike/voltage files) and visualize
experiment.save_artifacts("runs/run_001")
Plotter(experiment=experiment).plot_raster()

See examples/full_sim_workflow.py and examples/full_hw_workflow.py for complete, runnable end-to-end scripts.

Architecture

The toolchain follows a modular pipeline:

• Parsers - Convert NeuroML/LEMS to intermediate representation (IR)
• IR - Graph-based network structure + configuration
• Mappings - Translate NeuroML tags to Lava primitives (extensible)
• Networks - Orchestrate compilation and execution
• Backends - Loihi 2 simulator and hardware execution
• Experiments - Orchestration and artifact generation (.dat file output)
• Analysis - Visualization and metrics
• Comparison - Cross-backend validation and spike train dissimilarity metrics (Victor-Purpura, Van Rossum)

Extensible mapping

Each NeuroML component tag is mapped to a Lava process. The built-in mappings cover the common cases (iafCell → LIF, expTwoSynapse → Dense), and any custom tag can be wired to a custom process at runtime via register_mapping().

Hardware execution

On the hardware backend, the assembled network is driven by a SpikeBuffer through input-weight Dense connections into a vectorized LIF process (with recurrent Dense connectivity), and both spikes and voltages are recorded via StateProbes and a routing matrix.

See docs/ for detailed architecture documentation.

Development

Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=neuroml2loihi

# Run specific test file
pytest tests/test_imports.py

Project Structure

.
├── src/neuroml2loihi/    # Main package
│   ├── parsers/          # NeuroML & LEMS parsers
│   ├── ir/               # Intermediate representation
│   ├── mappings/         # Tag → Lava primitive mapping
│   ├── networks/         # Network orchestration
│   ├── backends/         # Execution backends
│   ├── analysis/         # Visualization tools
│   └── comparison/       # Cross-run comparison
├── tests/                # Test suite
├── examples/             # Example models and end-to-end scripts
├── docs/                 # Documentation
└── runs/                 # Run artifacts (gitignored)

Contributing

This project follows an incremental development model. See .github/copilot-instructions.md for contribution guidelines and architecture requirements.

Citations

NeuroML

This project builds on the NeuroML model description language. If you use NeuroML2Loihi, please cite:

Gleeson, P., Crook, S., Cannon, R. C., Hines, M. L., Billings, G. O., Farinella, M., Morse, T. M., Davison, A. P., Ray, S., Bhalla, U. S., Barnes, S. R., Dimitrova, Y. D., & Silver, R. A. (2010). NeuroML: A Language for Describing Data Driven Models of Neurons and Networks with a High Degree of Biological Detail. PLoS Computational Biology, 6(6), e1000815. https://doi.org/10.1371/journal.pcbi.1000815

BibTeX

@article{gleesonNeuroML2010,
  title    = {{NeuroML}: A Language for Describing Data Driven Models of Neurons and Networks with a High Degree of Biological Detail},
  author   = {Gleeson, Padraig and Crook, Sharon and Cannon, Robert C. and Hines, Michael L. and Billings, Guy O. and Farinella, Matteo and Morse, Thomas M. and Davison, Andrew P. and Ray, Subhasis and Bhalla, Upinder S. and Barnes, Simon R. and Dimitrova, Yoana D. and Silver, R. Angus},
  editor   = {Friston, Karl J.},
  year     = {2010},
  month    = jun,
  journal  = {PLoS Computational Biology},
  volume   = {6},
  number   = {6},
  pages    = {e1000815},
  issn     = {1553-7358},
  doi      = {10.1371/journal.pcbi.1000815}
}

NeuroML project: https://neuroml.org/

Elephant

This project uses the Elephant library for all neural data analysis (spike train dissimilarity metrics, firing rates, and related measures):

Denker, M., Yegenoglu, A., & Grün, S. (2018). Collaborative HPC-enabled workflows on the HBP Collaboratory using the Elephant framework. In Neuroinformatics 2018, Montreal, Canada.

Elephant: Electrophysiology Analysis Toolkit

• Documentation: https://elephant.readthedocs.io/
• Repository: https://github.com/NeuralEnsemble/elephant
• Citation guide: https://elephant.readthedocs.io/en/latest/citation.html

When using the analysis or comparison features, please cite Elephant according to their guidelines.

License

MIT License - see LICENSE file for details.