Neun Python Bindings

Python bindings for the Neun neural simulation library. High-performance computational neuroscience with an intuitive Python interface.

Features

• Multiple neuron models - Hodgkin-Huxley, Hindmarsh-Rose, and more
• High performance - C++ speed with Python convenience
• Synaptic coupling - Electrical and diffusion synapses
• Type safe - Strongly typed bindings prevent errors
• Extensible - Add custom models through JSON configuration
• NumPy integration - Seamless array operations

Quick start

Installation

Download the wheel matching your Python version and platform from the GitHub releases page, then install it:

python -m pip install /path/to/neun_py-<version>-<python>-<abi>-<platform>.whl

Release wheels are built for CPython 3.9-3.13 on x86-64 Linux (manylinux 2.28), Windows, and macOS. A matching wheel contains the compiled extension and needs neither a compiler nor a separate Neun installation. On other platforms, the release source archive can be installed with python -m pip install /path/to/neun_py-<version>.tar.gz; this builds the extension and requires a C++20 compiler and Python development headers, but not a separate Neun install.

From source

git clone https://github.com/GNB-UAM/neun_py.git
cd neun_py
make

The source tree bundles the header-only Neun library under include/neun; the build generates the bindings from models.json and compiles them using those headers. The examples extra installs plotting dependencies:

python -m pip install -e '.[examples]'

First simulation

import neun_py
import matplotlib.pyplot as plt

# Create Hodgkin-Huxley neuron
args = neun_py.HHDoubleConstructorArgs()
neuron = neun_py.HHDoubleRK4(args)

# Set parameters
neuron.set_param(neun_py.HHDoubleParameter.gna, 120 * 7.854e-3)
neuron.set_param(neun_py.HHDoubleParameter.gk, 36 * 7.854e-3)

# Initialize
neuron.set(neun_py.HHDoubleVariable.v, -65)

# Simulate
times, voltages = [], []
for i in range(100000):
    neuron.add_synaptic_input(0.1)
    neuron.step(0.001)
    if i % 100 == 0:
        times.append(i * 0.001)
        voltages.append(neuron.get(neun_py.HHDoubleVariable.v))

plt.plot(times, voltages)
plt.xlabel('Time (ms)')
plt.ylabel('Voltage (mV)')
plt.savefig('spike.pdf')

Documentation

Full Documentation - Complete guides and API reference

Quick Links:

• Installation Guide
• Quick Start Tutorial
• User Guide
• API Reference
• Adding Models

Examples

See the examples/ directory:

• basic.py - Single neuron simulation
• synapsis.py - Coupled neurons with electrical synapse

Run with:

python examples/basic.py --plot output.pdf
python examples/synapsis.py --plot coupled.pdf

Available models

Each model supports:

• Precisions: Float, Double
• Integrators: RK4 (4th order), RK6 (6th order)

Example class names: HHDoubleRK4, HRFloatRK6

Development

Creating a release

After pushing the workflow to GitHub, use Actions > Release > Run workflow to test its source and wheel builds without creating a release. The manual run does not check the tag or publish artifacts to a GitHub release.

1. Update VERSION in setup.py, commit the change, and push it to GitHub.
2. Tag that commit with the same version and push the tag:

git tag v0.4.0
git push origin v0.4.0

Replace 0.4.0 with the new version; tags must match v plus VERSION. 3. The Release workflow builds an sdist and platform wheels, tests the wheels, and creates a GitHub release with those files and generated notes. Check the Actions run and the release page before sharing it. This does not publish to PyPI.

Build system

make              # Build and install in development mode
make clean        # Remove build artifacts
make test         # Run tests
make dist         # Build distributions

Adding models

1. Create C++ header in include/neun/models/
2. Add entry to models.json
3. Rebuild with make clean && make

See Adding Models Guide for details.

Contributing

Contributions welcome! See Contributing Guide.

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests
5. Submit a pull request

License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).

• ✅ Free to use and modify
• ✅ Open source required for derivatives
• ✅ Network use requires source availability

See LICENSE for full text.

Citation

If you use this software in your research, please cite:

@software{lareo2025neun,
  title = {Neun},
  author = {Angel Lareo},
  year = {2025},
  url = {https://github.com/GNB-UAM/Neun}
}

Links

• Documentation: https://gnb-uam.github.io/neun_py/
• Neun library: https://github.com/GNB-UAM/neun
• Source code: https://github.com/GNB-UAM/neun_py
• Issue tracker: https://github.com/GNB-UAM/neun_py/issues

Made with ❤️ by Angel Lareo