Metadata-Version: 2.4
Name: neuroml-loihi
Version: 1.0.0
Summary: NeuroML/LEMS to Loihi 2 toolchain
Author-email: Danny Rosen <daniel20@vt.edu>
License: MIT
Project-URL: Homepage, https://github.com/DRosen766/NeuroML2Loihi
Project-URL: Documentation, https://github.com/DRosen766/NeuroML2Loihi/tree/main/docs
Project-URL: Repository, https://github.com/DRosen766/NeuroML2Loihi
Project-URL: Bug Tracker, https://github.com/DRosen766/NeuroML2Loihi/issues
Keywords: neuroml,lems,loihi,neuromorphic,spiking-neural-networks
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: networkx>=3.0
Requires-Dist: numpy>=1.23
Requires-Dist: elephant>=1.0.0
Requires-Dist: neo>=0.13.0
Requires-Dist: quantities>=0.15.0
Requires-Dist: matplotlib>=3.5
Requires-Dist: torch>=2.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: jupyter>=1.0.0; extra == "dev"
Provides-Extra: analysis
Requires-Dist: matplotlib>=3.5; extra == "analysis"
Requires-Dist: numpy>=1.20; extra == "analysis"
Provides-Extra: docs
Requires-Dist: sphinx==9.1.0; extra == "docs"
Requires-Dist: myst-parser==5.1.0; extra == "docs"
Requires-Dist: furo==2025.12.19; extra == "docs"
Requires-Dist: linkify-it-py>=2.0; extra == "docs"
Dynamic: license-file

# NeuroML2Loihi

An open-source toolchain for converting [NeuroML](https://neuroml.org/) models to run on Intel's [Loihi 2](https://www.intel.com/content/www/us/en/research/neuromorphic-computing.html)
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

![NeuroML2Loihi framework architecture](docs/images/architecture.png)

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](https://github.com/openworm/c302)
NeuroML models from the [OpenWorm](https://openworm.org/) 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`, …).

![Membrane potentials of the 302-neuron c302 connectome](docs/images/c302_full_voltage_heatmap.png)

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)

```bash
# 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)

```bash
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:

```python
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`](examples/full_sim_workflow.py) and
[`examples/full_hw_workflow.py`](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()`.

![Tag-to-process mapping](docs/images/mapping.png)

### 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
`StateProbe`s and a routing matrix.

![Hardware recording pipeline](docs/images/hardware_pipeline.png)

See [`docs/`](docs/) for detailed architecture documentation.

## Development

### Running Tests

```bash
# 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`](.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

<details>
<summary>BibTeX</summary>

```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}
}
```
</details>

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](LICENSE) file for details.
