1. 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.
1.1. Docker Image
1.2. Install from source code
1.2.1. Minimum Prerequisites
1.2.2. Optional Prerequisites
1.2.3. Other Recommended
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 STEPS uses both NumPy and Scipy. As explained below, if these packages are not installed STEPS will install them by default during its installation. 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. For further information on these packages you can visit the following online resources:
1.2.4. Obtaining STEPS Source code
STEPS 3.0.0 and above are available at https://github.com/CNS-OIST/STEPS
Old releases (STEPS 2.2.0 and below) can be downloaded at https://sourceforge.net/projects/steps/files/.
1.2.5. Install From Github Repository
This section describes how to compile and install STEPS on a generic Unix-like system, including Linux and MacOSX. Official support of Windows platform is discontinued.
1.2.5.1. New installation or upgrade from a STEPS version above 3.0.0
To install STEPS from source code, first clone the repository using the folowing command in terminal:
git clone https://github.com/CNS-OIST/STEPS.git
If not already installed, install the build python package
pip install --user build
then run the following commands to compile the source code and install:
cd STEPS
git submodule update --init --recursive
mkdir build
cd build
cmake ..
make
make install
Note that, by default, STEPS will install its python dependencies during the call to make install, this can be prevented by setting the following cmake option:
cmake -DSTEPS_INSTALL_PYTHON_DEPS=False ..
The python packages that would be installed are listed here.
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 they can 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 they can set:
cmake -DSTEPS_USE_DIST_MESH=[True|False] ..
Please refer to CMAKE documentation for customizing your installation. Advanced installation customization and frequently encountered problems during installations are discussed in the Customizing STEPS installation page.
1.2.6. 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: 5.0.2
License: GPL3.0
Website: steps.sourceforge.net
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.sim 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:
[1]:
import steps.interface
from steps.model import *
mdl = Model()
Installation was successful if you can create this object.
1.3. Running STEPS
1.3.1. Serial 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:
python my_serial_simulation.py
1.3.2. Parallel Mode
Parallel simulations need to be executed in terminal with the mpirun command, or similar command in your MPI distribution:
mpirun -n <n_procs> python my_parallel_simulation.py
<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.
1.3.3. Validation and Examples
Short validation tests (runnning in a few minutes) can be found in the release repository, under
test/validationand can be run from thebuilddirectory withctest -R .*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