Installation

Installation Step-by-Step

Dependencies

Open-Source Third-Party Dependencies

The pip installation takes care of most of the open-source third-party dependencies, but the FEM solver (FenicsX) and the Message Passing Interface (MPICH) are only installable via conda. We also recommend installing gmsh and ipython from conda.

conda install -c conda-forge::mpi4py fenics-dolfinx==0.9.0 python-gmsh ipykernel

Warning

For Linux users, the default blas library used in FenicsX may not be compatible with the preconditioner used in NRV, which may result in unnecessary CPU overhead during electric field computation. To avoid this, it is advised to force the installation as below.

conda install -c conda-forge mpi4py fenics-dolfinx==0.9.0 libblas=*=*blis python-gmsh ipykernel

Tip

With Mamba, the command is:

mamba install -c conda-forge mpi4py fenics-dolfinx==0.9.0 python-gmsh ipykernel

COMSOL Installation

NRV can perform FEM computations with COMSOL. However, the end user must provide a valid commercial license. COMSOL can be installed before or after NRV. To use COMSOL, information about the installation must be specified in the nrv/_misc code folder by filling in the following fields in the NRV.ini file:

[COMSOL]
COMSOL_STATUS = True
COMSOL_SERVER = PATH_TO_COMSOL_SERVER_BINARIES
COMSOL_CPU = 1
COMSOL_PORT = 2036
TIME_COMSOL_SERVER_LAUNCH = 10

In particular, the correct path to the COMSOL server binaries must be specified, and the port must be adapted if it differs from the default value.

The use of FenicsX for FEM computations has been extensively tested by NRV contributors, and we do not recommend using COMSOL with NRV, as new geometries or electrodes will not be implemented with COMSOL. Also, the use of commercial licenses limits reproducibility and open-science possibilities.

Installing NRV

Using pip

NRV can simply be installed with pip (nrv-py):

pip install nrv-py

If you want the latest development version, please consider:

pip install git+https://github.com/fkolbl/NRV.git

If you already installed a previous version and want to upgrade to the latest development version, please use:

pip install --upgrade --force-reinstall --ignore-installed git+https://github.com/fkolbl/NRV.git

You should now be able to import nrv in your Python shell:

import nrv

Be aware that on the first import of NRV, some files related to ion-channel simulation are automatically compiled by NEURON. You may see the results of the compilation on your prompt, including warnings but no errors.

Using Docker

This method should be preferred, as all dependencies are already set up. Note that in this configuration, COMSOL cannot be used. Assuming that Docker is already installed, the first step is to pull the image:

docker pull nrvframework/nrv

You can then create a new container using:

docker run --rm -it nrvframwork/nrv

where the --rm argument removes the container once finished, and -it provides an interactive console. A second image is available to use NRV in Jupyter notebooks:

docker pull nrvframework/lab

You can then create a container using:

docker run --rm -p 8888:8888 nrvframework/lab

Here, -p 8888:8888 maps the port to the local host. This should give you a link and token to open Jupyter in your browser.

NRV on Windows

NRV is not directly installable on Windows due to some FenicsX dependencies not being available on Windows. However, this problem can easily be overcome by using (WSL2). Assuming a blank WSL2 installation (Ubuntu 22.xx), the following instructions are required to install and use NRV.

Installation of micromamba (a lighter and faster conda equivalent):

"${SHELL}" <(curl -L micro.mamba.pm/install.sh)

Creation of the environment:

micromamba create -n nrv-env -c anaconda python=3.12

Update with sudo and install the required libraries:

sudo apt-get update -y
sudo apt-get install build-essential libglu1-mesa libxi-dev libxmu-dev libglu1-mesa-dev libxrender1 libxcursor1 libxft2 libxinerama1 make libx11-dev git bison flex automake libtool libxext-dev libncurses-dev xfonts-100dpi cython3 libopenmpi-dev zlib1g-dev

Activate the environment and install the required packages:

micromamba activate nrv-env
micromamba install -c conda-forge fenics-dolfinx==0.9.0  sysroot_linux-64=2.17 mpich python-gmsh ipykernel

Finally, NRV can be installed with pip:

pip install nrv-py

The WSL2 terminal must be rebooted before using NRV.

Quick Installation

A simpler installation method has been available since NRV-v1.2.2. The goal is to create a new mamba or micromamba environment from recipes stored in .yaml files in the GitHub repository.

Warning

This method has not been extensively tested yet. If any errors occur, please report them and use the standard method detailed above.

On Linux

On macOS

Tip

In both cases you can test the installation using (note that this command could take longer to execute as nrv is imported for the first time):