Skip to content

Installation ​

TIP

Ensure that an up-to-date version of uv is available

If you are planning to use supercomputing infrastruture, check out our installation scripts and instructions in the menu.

Quick Install ​

Provides the core functionality to get started, including the predefined systems and datasets, and simulation through the built-in native backend. May be behind the latest development in the main branch.

sh
uv pip install livn

Advanced Setup ​

All backends and whistles! Required if you are interested in generating your own systems (instead of using the pre-defined ones), or scaling up via MPI using NEURON.

The NEURON backend is a source install

There is no livn[neuron] on PyPI as the backend needs a compatible MPI (see Prerequisites):

sh
git clone https://github.com/livn-org/livn.git
cd livn
uv sync --group neuron

Prefer the native backend to get started and move to NEURON when you need MPI across many ranks, full-morphology cells, or other advanced features.

Prerequisites ​

For advanced use cases, an MPI and HDF5 installation is required. It is typically easiest to install using your system's package manager. However, if you prefer building parallel HDF5 yourself follow these instructions.

Linux (Debian) 🐧 / Windows (WSL2) 🪟

sh
apt install -y cmake mpich libmpich-dev libhdf5-mpich-dev hdf5-tools

macOS 🍎

sh
brew install hdf5-mpi

neuroh5 ​

neuroh5 is optional. Only the H5-backed System reads through it, and only for the MPI-collective scatter reads; without it those fall back to pyfive, where every rank reads the whole file. That is correct and fast enough for the culture-scale systems, so install it when you run a large system such as CA1 across many ranks, or when you generate your own:

sh
uv sync --group neuroh5

Generating custom 3D systems with realistic morphology additionally requires the binaries, built as follows:

sh
git clone https://github.com/iraikov/neuroh5.git
cd neuroh5
cmake .
make
export PATH="/path/to/neuroh5/bin:$PATH"

Installation ​

sh
git clone https://github.com/livn-org/livn.git
cd livn
uv sync

# customize as needed, e.g. core + system generation ...
uv sync --package systems 
# or just get the whole smash ...
uv sync --all-packages --all-groups --all-extras

TIP

It is important to ensure that the mpi4py/h5py package links against the correct MPI version. To force a package rebuild using the currently active MPI installation, use:

sh
uv pip install --force-reinstall --no-cache-dir --no-binary=mpi4py mpi4py

To detect possibly missing environment variables, you can use:

uv run https://raw.githubusercontent.com/GazzolaLab/MiV-Simulator/refs/heads/main/configure_mpi.py

Resources ​

Released under the MIT License.