Getting Started

The aim of this document is to get you started quickly with STEPS by working through a number of examples that highlight the various capabilities of this software package. However, before you can do that, you need to have a working copy of STEPS installed on your computer. So we will first explain the requirements of STEPS in terms of third party software and prior knowledge and then how to compile and install on your system.

Docker Image

For user who want to quickly try STEPS without compilation from the source code, we provide a prebuilt Docker image of the latest release, which can be accessed via

Install from source code

Minimum Prerequisites

  1. C++ compiler supporting c++11 (e.g. gcc 4.8, clang 3.3)
  2. Either Python 2.7 or Python 3.4 (or more recent)
  3. NumPy
  4. CMake
  5. Cython
  6. BLAS/OpenBLAS

Optional Prerequisites

  1. To use the parallel SSA solver TetOpSplit: MPI libraries (e.g. MPICH )
  2. To use the parallel EField solver: PETSc

For STEPS Advanced Modules

SBML importer

The steps.utilities.sbml module is a package for importing and running SBML files. This module requires the SBML library libSBML.

It is important when building libSBML to configure the Python API, for example with the following command:

$ ./configure --with-python

Please refer to libSBML documentation for further information.

For more details about the SBML module, see SBML support.

Visualization toolkit

Installation of PyQtGraph and PyOpenGL is required for the visualization toolkit, see Visualization Toolkit.

Scientific Python

Through the use of a number of packages, namely NumPy, SciPy and Matplotlib, Python can be made to resemble the Matlab environment for scientific computing rather closely. The NumPy package brings powerful array objects to Python. These array objects will typically rely on an optimized linear algebra package to make the operations on them very fast. SciPy builds on top of NumPy and adds even more functionality for signal processing, numerical integration, etc. Finally, Matplotlib adds a collection of powerful 2D plotting tools to your Python environment, that once again resemble the plotting commands familiar from Matlab.

These add-on packages are in common use among the scientific computing community and it is highly recommended that two of these packages (NumPy and SciPy) are installed on your system. Although one could use STEPS without taking advantage of these packages, we highly recommend you do take the time to get acquainted with them as they will make it easier to run simulations, collect output and perform extra processing on this data. Starting from the very first example we will show how NumPy arrays can be used for these tasks rather than the basic built-in types in Python (lists, tuples etc), although one could replace a NumPy array with a list in the code, for example, if more comfortable with the built-in types. For further information on these packages you can visit the following online resources:

Obtaining STEPS Source code

STEPS 3.0.0 and above are avalalble at

Old releases (STEPS 2.2.0 and below) can be downloaded at

Install From Github Repository

This section describes how to compile and install STEPS on a generic Unix-alike system, including Linux and MacOSX. Official support of Windows platform is discontinued.

Note: Started from Version 3.0.0, STEPS has adapted CMake for building and installation. To avoid version conflict, we recommend user to remove any previous installation that is below 3.0.0.

You can find the installation location of STEPS in a terminal using:

python -c "import steps; print steps.__file__"

For example:

$ python -c "import steps; print steps.__file__"

You can now manaully delete the STEPS installation above:

[sudo] rm -rf /usr/local/lib/python2.7/site-packages/steps

To install STEPS from source code, first clone the repository using the folowing command in terminal:

git clone

then run the following commands to compile the source code and install:

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

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


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 set:

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

Please refer to CMAKE documentation for customizing your installation

Test the Installation

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

python -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:  3.1.0
License:  GPL2.0
CXX Binding: Cython

Just about every task related to building a model, describing the geometry and running a simulation in STEPS involves creating objects in Python and utilising the object methods (so it is highly recommend that you are familiar with Python objects and comfortable using them, though you will gain more experience by working through the examples in this document). The class definitions for these objects reside in Python modules in the steps directory (steps.model, steps.geom, steps.solver etc). So to test installation, try to create your first STEPS object. What this object is and how it is used will become clear in the next chapter. So, from the Python prompt:

In [1]:
import steps.model
modobject = steps.model.Model()

Installation was successful if you can create this object.

Running STEPS

Serial Interactive Mode

To run STEPS in serial interactive mode, start python and import the steps module:

In [2]:
import steps

Serial Non-Interactive Mode

It is often more convenient to run STEPS simulation with pre-written Python scripts, which is the main focus of this manual. You can execute a simulation script in serial mode like this:


Parallel Non-Interactive Mode

At the moment STEPS does not provide the interactive interface for parallel TetOpSplit solver, thus parallel simulations need to be executed via scripts in terminal with mpirun command, or similar command in your MPI distribution:

mpirun -n <n_procs> python

<n_proc> is the number of MPI processes to be created for the parallel simulation. Please refer to the documentation of your MPI solution for further customization.

Validation and Examples

  • Short validation tests (runnning in a few minutes, using serial solvers only) can be found in the release repository, under test/validation
  • Longer validation tests (using serial and parallel solvers) can be found in the STEPS_Validation repository
  • Examples of STEPS simulations, as well as user manual can be found in the STEPS_Example repository