Metadata-Version: 2.4
Name: spine-neuro
Version: 1.0.0
Summary: A framework for mechanistic neuronal simulation that couples membrane electrophysiology with spatial intracellular calcium signaling and synaptic dynamics and plasticity, from individual neurons to large networks on CPUs, GPUs, and HPC systems
Author: Zachary M. Miksis, Gillian Queisser
Maintainer-email: "Zachary M. Miksis" <miksis@temple.edu>
License-Expression: LGPL-3.0-or-later
Keywords: neuroscience,calcium signaling,cable equation,dendrites,simulation,GPU
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: COPYING
License-File: COPYING.LESSER
Requires-Dist: numpy>=2.2.4
Requires-Dist: scipy>=1.15.2
Requires-Dist: threadpoolctl>=3.1.0
Provides-Extra: examples
Requires-Dist: matplotlib>=3.8.4; extra == "examples"
Provides-Extra: mpi
Requires-Dist: mpi4py>=3.1.0; extra == "mpi"
Provides-Extra: gpu-cuda12
Requires-Dist: cupy-cuda12x>=13.0; extra == "gpu-cuda12"
Provides-Extra: gpu-cuda11
Requires-Dist: cupy-cuda11x>=13.0; extra == "gpu-cuda11"
Provides-Extra: gpu
Requires-Dist: cupy-cuda12x>=13.0; extra == "gpu"
Provides-Extra: multi-gpu-cuda12
Requires-Dist: cupy-cuda12x>=13.0; extra == "multi-gpu-cuda12"
Requires-Dist: pymetis>=2023.1; extra == "multi-gpu-cuda12"
Provides-Extra: multi-gpu-cuda11
Requires-Dist: cupy-cuda11x>=13.0; extra == "multi-gpu-cuda11"
Requires-Dist: pymetis>=2023.1; extra == "multi-gpu-cuda11"
Provides-Extra: hybrid-cuda12
Requires-Dist: cupy-cuda12x>=13.0; extra == "hybrid-cuda12"
Requires-Dist: pymetis>=2023.1; extra == "hybrid-cuda12"
Requires-Dist: mpi4py>=3.1.0; extra == "hybrid-cuda12"
Provides-Extra: hybrid-cuda11
Requires-Dist: cupy-cuda11x>=13.0; extra == "hybrid-cuda11"
Requires-Dist: pymetis>=2023.1; extra == "hybrid-cuda11"
Requires-Dist: mpi4py>=3.1.0; extra == "hybrid-cuda11"
Provides-Extra: metis
Requires-Dist: pymetis>=2023.1; extra == "metis"
Provides-Extra: viz
Requires-Dist: networkx>=3.0; extra == "viz"
Requires-Dist: matplotlib>=3.8.4; extra == "viz"
Requires-Dist: pyvista>=0.43.0; extra == "viz"
Requires-Dist: imageio[ffmpeg]>=2.28.0; extra == "viz"
Dynamic: license-file

# SPINE

**Simulator for Plasticity and Integrated Neuronal Events**

SPINE is a framework for mechanistic neuronal simulation that couples membrane electrophysiology with spatial intracellular calcium signaling and synaptic dynamics and plasticity, from individual neurons to large networks on CPUs, GPUs, and HPC systems.

- **A coupled voltage–calcium model**: PMCA, NCX, VDCC, SERCA, RyR, IP3R, SOC and leaks are built in; Hodgkin–Huxley or your own channels; AMPA, NMDA, GABA and calcium-coupled synapses with plasticity.
- **Extracellular stimulation**: point-source, uniform-field and TMS fields, myelinated axons.
- **One entry point, `solve()`**: one neuron on one CPU process, up to multi-GPU and MPI populations.
- **Output**: checkpoint and restart, streamed and HDF5 recording, 3-D rendering and animation.

The **User Guide** (`documentation/SPINE_user_guide.pdf`) documents the models, every setting and the API.

## Installation

Get the repository, or the release archive on Zenodo ([10.5281/zenodo.24226059](https://doi.org/10.5281/zenodo.24226059)), which holds the source, the User Guide and the examples. From its top folder:

```bash
pip install -e .
```

This needs Python ≥ 3.10; NumPy, SciPy and threadpoolctl are installed with it. The distribution is named `spine-neuro` (`pip show spine-neuro`); the package is imported as `spine`.

Optional extras are installed from the repository directory and combine freely, e.g. `pip install -e ".[viz,mpi]"`: `examples` (matplotlib), `viz` (3-D rendering and animation), `mpi`, `gpu-cuda12` / `gpu-cuda11`, `multi-gpu-cuda12` / `multi-gpu-cuda11`, `hybrid-cuda12` / `hybrid-cuda11`, and `metis`. HDF5 output needs `h5py`, which no extra installs: `pip install h5py`. See *Dependencies* in the User Guide.

## Quick start

```python
from spine.utils import NeuronModel
from spine.solver import solve
from spine.graph import gen_beam
from spine.synapse import SynapseFactory

neuron = NeuronModel()
neuron.settings.top_folder = './'
neuron.settings.data_folder = 'calcium_wave/'
neuron.settings.output_folder = 'calcium_wave-output/'

for key in ('CYT_buffer', 'PMCA', 'NCX', 'SERCA', 'PM_leak', 'ER_leak', 'RyR', 'IP3', 'synapse'):
    neuron.model[key] = True                # the calcium mechanisms

neuron.geom_builder['const_rad'] = True
neuron.settings.rad = 0.2                   # µm
gen_beam(neuron, 64, 1000)                  # a 64 µm beam of 1000 nodes
neuron.settings.T = 70.e-3                  # 70 ms
neuron.settings.set_time_step(5.e-6)

neuron.synapse_instances = [                # calcium and IP3 influx at node 500
    SynapseFactory.create_calcium_linear(nodes=[500], amplitude=2.5e-12, duration=1.e-3),
    SynapseFactory.create_ip3_linear(nodes=[500], amplitude=5.0e-12, duration=200.e-3),
]

neuron.recorder['full'] = True              # cytosolic Ca²⁺ → results/calcium_wave-output/cyt.txt
neuron.recorder['full_er'] = True           # ER Ca²⁺       → results/calcium_wave-output/er.txt
solve(neuron)
```

`examples/basics/calcium_wave.py` is a runnable version with plots. Internal units are µm, s, V and µmol/µm³; output is in mV and µM (*Units and conventions* in the User Guide).

## Examples

`examples/` has one directory per topic (`basics/`, `synapses/`, `morphology/`, `stimulation/`, `visualization/`, `gpu/`, `scaling/`, `cells/`); every script writes to `results/` below the current directory. The *Index of examples* in the User Guide describes each one. `cells/` holds published cell models: the Jarsky CA1 cell under TMS (`jarsky/`), the Aberra layer-5 cell under field stimulation (`aberra/`), and a cerebellar Purkinje cell based on Masoli et al. (2015) with its SCA1[82Q] variant (`purkinje/`). The Jarsky and Purkinje directories have a README of their own.

```bash
python examples/basics/calcium_wave.py                                   # start here
python examples/gpu/calcium_wave_gpu.py                                  # needs a GPU extra
mpirun -n 8 python examples/scaling/parallel_scaling_test.py             # needs the mpi extra
```

## Parallel and GPU runs

`solve(neuron)` runs one neuron on one CPU process. `mpirun -n N python script.py` is detected and needs no code change; `solve(..., backend='gpu', batched=True)` and `solve(..., backend='gpu', devices=[...])` run populations on one or several GPUs, and MPI ranks can each hold GPUs. These are tested across the ranks and devices of one node, not across several nodes. See *Parallel and GPU Backends* in the User Guide.

## Testing and contributing

```bash
pytest tests/                   # about three minutes on a workstation, CPU only
pytest tests/ -k synapse        # a subset by keyword
```

The suite runs the listings of the User Guide, compares the batched, multi-device and MPI solvers with the serial solver, and checks checkpointing and recording. Tests that need CuPy, `mpirun` or `pymetis` are skipped where those are missing; run `python tests/gpu_population_check.py` on a GPU machine. To add your own channels, receptors or flux mechanisms, see *Extending SPINE*; the package layout is in *Architecture and Design*; *Contributing and Testing* describes the workflow (fork, branch, add a test, open a pull request).

## Citation

```bibtex
@software{spine2026,
  author  = {Miksis, Zachary M. and Queisser, Gillian},
  title   = {{SPINE}: Simulator for Plasticity and Integrated Neuronal Events},
  version = {1.0.0},
  year    = {2026},
  doi     = {10.5281/zenodo.24226059}
}
```

`CITATION.cff` holds the same entry; GitHub's *Cite this repository* reads it.

## License

Copyright (C) 2026 Zachary M. Miksis and Gillian Queisser.

SPINE is free software: you can redistribute it and modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version (SPDX: `LGPL-3.0-or-later`). SPINE is distributed in the hope that it will be useful, but without any warranty, without even the implied warranty of merchantability or fitness for a particular purpose. The license is in `COPYING.LESSER`; it adds permissions to the GNU General Public License in `COPYING`. If you did not receive them, see <https://www.gnu.org/licenses/>.

## Acknowledgments

Works SPINE is based on:

- *Standard model* (calcium parameters and coupled electro-calcium formulation): P. R. Borole, J. M. Rosado, M. Neal and G. Queisser, "Neuronal Resilience and Calcium Signaling Pathways in the Context of Synapse Loss and Calcium Leaks: A Computational Modeling Study and Implications for Alzheimer's Disease," *SIAM J. Appl. Math.*, 2023. [doi:10.1137/23M1557842](https://doi.org/10.1137/23M1557842)
- *FJ model* (Extended-Flux Fick-Jacobs, under development): Z. M. Miksis and G. Queisser, "A New Fick-Jacobs Derivation with Applications to Computational Branched Diffusion Networks," 2025. [arXiv:2501.08247](https://arxiv.org/abs/2501.08247)

## Support

Email: miksis@temple.edu
