Installation

To isolate STEPS from other python packages, we recommend using a virtual environment. For example:

python -m venv stepsenv
source stepsenv/bin/activate

Once the environment is activated, you can install STEPS from PyPI or from the source code.

Install from PyPI

The easiest way to install STEPS is by installing the STEPS package from PyPI.

Minimum system requirements

1. C++ compiler supporting c++17 (e.g. gcc 7.4, clang 6)
2. pkg-config
3. Python 3.11 or above, along with pip
4. Git SCM utility
5. BLAS/OpenBLAS library
6. MPI library (Open MPI, MPICH, ...)
7. Gmsh (only required for MacOS)

On Ubuntu 24.04, the non-default packages can be installed with:

sudo apt install build-essential pkg-config git libopenblas-dev libopenmpi-dev

On MacOS 15 (Sequoia), the non-default packages can be installed with Homebrew (not installed by default):

brew install pkg-config openblas open-mpi gmsh

Installing with pip

pip install STEPS

This will build and install STEPS using the Python source distribution from PyPI.

Optional system requirements

1. Boost
2. METIS
3. Eigen3
4. Gmsh
5. PETsc

By default, pip install STEPS will download and install these dependencies through pip, if you have all of them installed on your system, you can get STEPS to use them with:

STEPS_NO_BUNDLE=True pip install STEPS

Install using Docker

If you don't want to do the compilation yourself and just want to quickly try STEPS, we provide a prebuilt Docker image for you. Please check https://github.com/CNS-OIST/STEPS_Docker and follow the instructions.

Install from source code

To facilitate new requirements from the parallel TetOpSplit solver, STEPS 3.0 and above uses CMake system to replace the Python distutils system in previous releases. Please follow the instructions below.

Minimum Prerequisites

1. C++ compiler supporting c++17 (e.g. gcc 7.4, clang 6)
2. Python (3.9 or above)
3. CMake (3.16.3 or above)
4. pkg-config (not installed by default on Mac, brew install pkg-config to install it)
5. Cython (0.29 or above)
6. BLAS/OpenBLAS
7. Boost
8. Eigen3
9. METIS
10. build Python package

See install Dependencies sections

Optional Prerequisites

1. To use one of the parallel SSA solvers: MPI libraries (e.g. MPICH)
2. To use the parallel EField solver: PETSc
3. To use the distributed mesh solver with bundled omega_h: Gmsh

Installation From Source code

please avoid using the "Download ZIP" feature, as submodules are currently not packed in the zip file. This includes the master branch as well as all previous releases in https://github.com/CNS-OIST/STEPS/releases.

1. Clone the repository using git clone in terminal, and change to the directory.

git clone --recursive https://github.com/CNS-OIST/STEPS.git
cd STEPS

2. If not already installed, install the build Python modules

pip install --user build

3. Run the following commands to compile the source code and install

git submodule update --init --recursive
mkdir build
cd build
cmake ..
make
[sudo] make install

Note that, by default, STEPS will install its Python dependencies during the call to make install, this can be prevented by giving the -DSTEPS_INSTALL_PYTHON_DEPS=False option to CMake.

After installation, you can check the STEPS installation with the following commands

python3 -c "import steps; steps._greet()"

If STEPS is installed successfully, you should be able to see similar information as below

STochastic Engine for Pathway Simulation
Version:  5.1.0
License:  GPL3.0
Website:  steps.sourceforge.net
CXX Binding: Cython

You can change the installation location by changing the prefix in CMake

cmake -DCMAKE_INSTALL_PREFIX:PATH=/MY_INSTALL_LOCATION ..

MPI and PETSc libraries are automatically detected in the system. If the user wants to manually choose to build STEPS with / without them it can be set

cmake -DUSE_MPI=[True|False] -DUSE_PETSC=[True|False] ..

By default, the distributed mesh solver DistTetOpSplit will be built. If the user wants to manually choose to build STEPS with / without this it can be set

cmake -DSTEPS_USE_DIST_MESH=[True|False] ..

By default, the distributed mesh solver will be built with bundled omega_h. An external omega_h build may be used by setting

cmake -DUSE_BUNDLE_OMEGA_H=False ..

Please refer to CMAKE documentation for customizing your installation

(optional): To checkout a previous release, for example release with tag 4.1.0 (Release tags can be found here, type in

git checkout tags/4.1.0 -b steps_4.1.0
git submodule update --recursive

Simulation with serial solvers

STEPS 3.0 and above contain all serial solvers in previous releases, to run STEPS in serial interactive mode, open Python and import the steps module

import steps

Scripts of serial STEPS simulations can be executed in terminal

python3 sim_script.py

Script migration in 3.6

A new Python API is available but scripts that worked with STEPS 3.5 should still work without any modification in STEPS 3.6.

Detailed guides for the new API can be found in the documentation.

More details in RELEASES document.

Simulation with parallel solvers

At the moment STEPS does not provide the interactive interface for parallel solvers TetVesicle, TetOpSplit, DistTetOpSplit, thus parallel simulations need to be executed via scripts in terminal e.g. with mpirun command

mpirun -n N_PROCS python3 parallel_sim_script.py

N_PROCS is the number of MPI processes to be created for the parallel simulation. For the TetVesicle solver N_PROCS must be a minimum of 2. For the DistTetOpSplit solver N_PROCS must be a power of 2.

High performance computing clusters often provide optimized parallel job scheduler and associated commands. For example, the above mpirun command may be replaced by

srun --mpi=pmix python3 parallel_sim_script.py

with Slurm scheduler and PMIx interface. Please refer to the documentation of your MPI solution for further customization.

Dependencies and build instructions

Python dependencies

Since STEPS 5.0, the Python dependencies (except build) are automatically installed during STEPS installation. This does not apply to non-python dependencies like MPI or PETSC, which still need to be installed by the users.

Unless the user explicitly prevents it with -DSTEPS_INSTALL_PYTHON_DEPS=False, the following python packages will be installed automatically:

1. NumPy
2. SciPy
3. matplotlib
4. h5py
5. mpi4py (if MPI is installed)

On some systems, the python3-venv package might be needed. If so, an error message during installation will point to the exact command needed to install it on your system.

Linux Debian based:

You can follow the installation procedure performed by the Docker image recipe

OSX:

Use Anaconda or Miniconda: conda install scipy numpy matplotlib cmake cython openblas openmpi llvm-openmp

Full example to build STEPS on Apple M1 Silicon with Python 3.8 through Miniconda

Prerequisites:

• Install latest XCode
• Install Miniconda3 macOS Apple M1 64-bit

CONDA_DIR=/path/to/miniconda
export PATH=$CONDA_DIR/bin:$PATH
conda install -c conda-forge \
  boost-cpp    \
  cmake        \
  cython       \
  eigen        \
  gfortran     \
  gmsh         \
  gsl          \
  llvm-openmp  \
  matplotlib   \
  metis        \
  mpi4py       \
  mpich        \
  numpy        \
  openblas     \
  pkg-config   \
  python-build \
  scipy
export MPICH_FC=$CONDA_DIR/bin/gfortran
export MPICH_CC=/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/cc
export MPICH_CXX=/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/c++

# Fetch and build PETSc
cd /path/to/src
git clone -b release https://gitlab.com/petsc/petsc.git petsc
pushd petsc
./configure --prefix=/path/to/petsc/installation --with-64-bit-indices=1 --with-debugging=0 \
            --with-scalar-type=real --with-x=0 --CC=mpicc --CXX=mpicxx --F77=mpif77 --FC=mpif90 \
            "MAKEFLAGS=$MAKEFLAGS"
make
make install
export PKG_CONFIG_PATH="/path/to/petsc/installation/lib/pkgconfig:$PKG_CONFIG_PATH"
popd

cd /path/to/src
git clone -b 5.0.0_beta --recursive https://github.com/CNS-OIST/STEPS.git
cd STEPS
mkdir _