{
"cells": [
{
"cell_type": "markdown",
"metadata": {},
"source": [
"# Getting Started\n",
"\n",
"The aim of this document is to get you started quickly with STEPS\n",
"by working through a number of examples that highlight the various\n",
"capabilities of this software package. However, before you can do\n",
"that, you need to have a working copy of STEPS installed on your\n",
"computer. So we will first explain the requirements of STEPS in terms\n",
"of third party software and prior knowledge and then how to compile\n",
"and install on your system.\n",
"\n",
"## Docker Image\n",
"For user who want to quickly try STEPS without compilation from the source code,\n",
"we provide a prebuilt Docker image of the latest release, which can be accessed via \n",
"[https://github.com/CNS-OIST/STEPS_Docker](https://github.com/CNS-OIST/STEPS_Docker)\n",
"\n",
"## Install from source code\n",
"\n",
"### Minimum Prerequisites\n",
"1. C++ compiler supporting c++17 (e.g. gcc 7.4, clang 6)\n",
"2. Python3 (3.8.x or above, 3.9.x or above if using stepsblender python package)\n",
"3. [CMake](https://cmake.org/)\n",
"4. [pkg-config](https://www.freedesktop.org/wiki/Software/pkg-config/) (not installed by default on Mac, `brew install pkg-config` to install it)\n",
"5. [Cython](http://www.cython.org/)\n",
"6. BLAS/[OpenBLAS](http://www.openblas.net/)\n",
"7. [Boost](https://www.boost.org/)\n",
"8. [Eigen3](https://eigen.tuxfamily.org/)\n",
"9. [METIS](https://github.com/KarypisLab/METIS)\n",
"10. `build` Python package\n",
"\n",
"### Optional Prerequisites\n",
"1. To use the parallel SSA solver TetOpSplit: MPI libraries (e.g. [MPICH](https://www.mpich.org/) )\n",
"2. To use the parallel EField solver: [PETSc](https://www.mcs.anl.gov/petsc/)\n",
"3. To use the distributed mesh solver: [Omega_h](https://github.com/sandialabs/omega_h) (bundled with STEPS by default)\n",
"\n",
"### Other Recommended\n",
"\n",
"**Scientific Python**\n",
"\n",
"Through the use of a number of packages, namely NumPy, SciPy and Matplotlib,\n",
"Python can be made to resemble the Matlab environment for scientific computing\n",
"rather closely. The NumPy package brings powerful array objects to Python.\n",
"These array objects will typically rely on an optimized linear algebra package\n",
"to make the operations on them very fast. SciPy builds on top of NumPy and adds\n",
"even more functionality for signal processing, numerical integration, etc.\n",
"Finally, Matplotlib adds a collection of powerful 2D plotting tools to your\n",
"Python environment, that once again resemble the plotting commands familiar from Matlab.\n",
"\n",
"These add-on packages are in common use among the scientific computing community and\n",
"STEPS uses both NumPy and Scipy. As explained below, if these packages are not installed\n",
"STEPS will install them by default during its installation.\n",
"We highly recommend you do take the time to get acquainted with them as they will make it\n",
"easier to run simulations, collect output and perform extra processing on this data.\n",
"For further information on these packages you can visit the following online resources:\n",
"\n",
"* Documentation for [NumPy](https://numpy.org/doc/stable/index.html) and [SciPy](https://docs.scipy.org/doc/scipy/)\n",
"* [NumPy for Matlab users](https://numpy.org/doc/stable/user/numpy-for-matlab-users.html)\n",
"\n",
"### Obtaining STEPS Source code\n",
"\n",
"STEPS 3.0.0 and above are available at [https://github.com/CNS-OIST/STEPS](https://github.com/CNS-OIST/STEPS)\n",
"\n",
"Old releases (STEPS 2.2.0 and below) can be downloaded at [https://sourceforge.net/projects/steps/files/](https://sourceforge.net/projects/steps/files/).\n",
"\n",
"### Install From Github Repository\n",
"\n",
"This section describes how to compile and install STEPS on a generic Unix-like system, including Linux and MacOSX.\n",
"Official support of Windows platform is discontinued.\n",
"\n",
"#### New installation or upgrade from a STEPS version above 3.0.0\n",
"\n",
"To **install STEPS from source code**, first clone the repository using the folowing command in terminal:\n",
"\n",
"```bash\n",
"git clone https://github.com/CNS-OIST/STEPS.git\n",
"```\n",
"\n",
"If not already installed, install the `build` python package\n",
"```bash\n",
"pip install --user build\n",
"```\n",
"\n",
"then run the following commands to compile the source code and install:\n",
"\n",
"```bash\n",
"cd STEPS\n",
"git submodule update --init --recursive\n",
"mkdir build\n",
"cd build\n",
"cmake ..\n",
"make\n",
"make install\n",
"```\n",
"\n",
"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:\n",
"```bash\n",
"cmake -DSTEPS_INSTALL_PYTHON_DEPS=False ..\n",
"```\n",
"The python packages that would be installed are listed [here](https://github.com/CNS-OIST/STEPS?tab=readme-ov-file#python-dependencies).\n",
"\n",
"You can change the installation location by changing the prefix in CMake:\n",
"\n",
"```bash\n",
"cmake -DCMAKE_INSTALL_PREFIX:PATH=/MY_INSTALL_LOCATION ..\n",
"```\n",
"\n",
"MPI and PETSc libraries are automatically detected in the system. If the user\n",
"wants to manually choose to build STEPS with / without them they can set:\n",
"\n",
"```bash\n",
"cmake -DUSE_MPI=[True|False] -DUSE_PETSC=[True|False] ..\n",
"```\n",
"\n",
"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:\n",
"```bash\n",
"cmake -DSTEPS_USE_DIST_MESH=[True|False] ..\n",
"```\n",
"\n",
"Please refer to [CMAKE documentation](https://cmake.org/documentation/) for customizing your installation. Advanced installation customization and frequently encountered problems during installations are discussed in the [Customizing STEPS installation](customizing_install.rst) page.\n",
"\n",
"### Test the Installation\n",
"\n",
"After installation, you can check the STEPS installation with the following commands:\n",
"\n",
"```bash\n",
"python -c \"import steps; steps._greet()\"\n",
"```\n",
"\n",
"If STEPS is installed successfully, you should be able to see similar information as below:\n",
"\n",
" STochastic Engine for Pathway Simulation\n",
" Version: 5.0.2\n",
" License: GPL3.0\n",
" Website: steps.sourceforge.net\n",
" CXX Binding: Cython\n",
"\n",
"Just about every task related to building a model, describing the geometry and\n",
"running a simulation in STEPS involves creating **objects** in Python and utilising\n",
"the object methods (so it is highly recommend that you are familiar with Python objects\n",
"and comfortable using them, though you will gain more experience by working through the\n",
"examples in this document). The class definitions for these objects reside in Python modules\n",
"in the steps directory ([steps.model](API_2/API_model.rst), [steps.geom](API_2/API_geom.rst), [steps.sim](API_2/API_sim.rst) etc).\n",
"So to test installation,\n",
"try to create your first STEPS object. What this object is and how it is used will become clear\n",
"in the next chapter. So, from the Python prompt:\n"
]
},
{
"cell_type": "code",
"execution_count": 1,
"metadata": {},
"outputs": [],
"source": [
"import steps.interface\n",
"from steps.model import *\n",
"\n",
"mdl = Model()"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Installation was successful if you can create this object.\n",
"\n",
"## Running STEPS\n",
"\n",
"### Serial Mode\n",
"\n",
"It is often more convenient to run STEPS simulation with pre-written Python scripts, which is the main focus of this manual.\n",
"You can execute a simulation script in serial mode like this:\n",
"\n",
"```bash\n",
"python my_serial_simulation.py\n",
"```\n",
"\n",
"### Parallel Mode\n",
"\n",
"Parallel simulations need to be executed in terminal with the `mpirun` command, or similar command in your MPI distribution:\n",
"\n",
"```bash\n",
"mpirun -n <n_procs> python my_parallel_simulation.py\n",
"```\n",
"\n",
"`<n_proc>` is the number of MPI processes to be created for the parallel simulation.\n",
"Please refer to the documentation of your MPI solution for further customization.\n",
"\n",
"### Validation and Examples\n",
"- Short validation tests (runnning in a few minutes) can be found in the release repository, under `test/validation` and can be run from the `build` directory with `ctest -R .*validation.*`\n",
"- Longer validation tests (using serial and parallel solvers) can be found in the [STEPS_Validation](https://github.com/CNS-OIST/STEPS_Validation) repository\n",
"- Examples of STEPS simulations, as well as user manual can be found in the [STEPS_Example](https://github.com/CNS-OIST/STEPS_Example) repository\n"
]
}
],
"metadata": {
"kernelspec": {
"display_name": "Python 3 (ipykernel)",
"language": "python",
"name": "python3"
},
"language_info": {
"codemirror_mode": {
"name": "ipython",
"version": 3
},
"file_extension": ".py",
"mimetype": "text/x-python",
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.10.12"
}
},
"nbformat": 4,
"nbformat_minor": 4
}