Python¶
Arbor provides access to all of the C++ library’s functionality in Python, which is the only interface for many users. The getting started guides will introduce Arbor via the Python interface.
To test that Arbor is available, try the following in a Python 3 interpreter:
>>> import arbor
>>> print(arbor.__config__)
{'mpi': True, 'mpi4py': True, 'gpu': False, 'version': '0.2.3-dev'}
>>> print(arbor.__version__)
0.2.3-dev
The dictionary arbor.__config__
contains information about the Arbor installation.
This can be used to check that Arbor supports features that you require to run your model,
or even to dynamically decide how to run a model.
Single cell models like do not require parallelism like
that provided by MPI or GPUs, so the 'mpi'
and 'gpu'
fields can be False
.
Performance¶
The Python interface can incur significant memory and runtime overheads relative to C++ during the model building phase, however simulation performance is the same for both interfaces.
Python 2¶
Python 2 reached end of life in January 2020.
Arbor only officially supports Python 3.6 and later, and all examples in the
documentation are in Python 3. While it is possible to install and run Arbor
using Python 2.7 by setting the PYTHON_EXECUTABLE
variable when
configuring CMake, support is only provided for using
Arbor with Python 3.6 and later.
Installing¶
Before starting Arbor needs to be installed with the Python interface enabled. The easiest way to get started with the Python interface is to install Arbor using pip.
Installing with pip requires two steps: (1) Obtain Arbor source code from GitHub; (2) then use pip to compile and install the Arbor package in one shot.
git clone https://github.com/arbor-sim/arbor.git --recursive
# use pip (recommended)
pip3 install ./arbor
# use setuptools and python directly
python3 install ./arbor/setup.py
This will install Arbor as a site-wide package with only multi-threading enabled.
To enable more advanced forms of parallelism, the following flags can optionally be passed to the pip install command:
--mpi
: enable mpi support (requires MPI library).--gpu
: enable nvidia cuda support (requires cudaruntime and nvcc).--vec
: enable vectorization. This might require carefully choosing the--arch
flag.--arch
: cpu micro-architecture to target. By default this is set tonative
.
If calling setup.py
the flags must to come after install
on the command line,
and if being passed to pip they must be passed via --install-option
. The examples
below demonstrate this for both pip and setup.py
, with pip being our recommend method.
Vanilla install with no additional options/features enabled:
pip3 install ./arbor
python3 ./arbor/setup.py install
Enable MPI support. This might require loading an MPI module or setting the CC
and CXX
environment variables.
pip3 install --install-option='--mpi' ./arbor
python3 ./arbor/setup.py install --mpi
Compile with vectorization on a system with SkyLake architecture:
pip3 install --install-option='--vec' --install-option='--arch=skylake' ./arbor
python3 ./arbor/setup.py install --vec --arch=skylake
Compile with support for NVIDIA GPUs. This requires that the CUDA toolkit is installed and the CUDA compiler nvcc is available:
pip3 install --install-option='--gpu' ./arbor
python3 ./arbor/setup.py install --gpu
Note
Installation takes a while because pip has to compile the Arbor C++ library and
wrapper, which takes a few minutes. Pass the --verbose
flag to pip
to see the individual steps being preformed if concerned that progress
is halting.
Note
Detailed instructions on how to install using CMake are in the Python configuration section of the installation guide. CMake is recommended for developers, integration with package managers such as Spack and EasyBuild, and users who require fine grained control over compilation and installation.
Note
If there is an error installing with pip you want to report,
run pip with the --verbose
flag, and attach the output (along with
the pip command itself) to a ticket on the
Arbor GitHub.
For example, pip3 install --install-option='--mpi' --verbose .
.
Dependencies¶
If a downstream dependency of Arbor that requires Arbor be built with
a specific feature enabled, use requirements.txt
to
define the constraints.
For example, a package that depends on arbor would version 0.3 or later
with MPI support would add the following to its requirements.
arbor >= 0.3 --install-option='--gpu' \
--install-option='--mpi'