.. _in_python: Python Installation =================== Arbor's Python API will be the most convenient interface for most users. .. note:: Arbor requires Python version 3.7 and later. It is advised that you update ``pip`` as well. We strongly encourage using ``pip`` to install Arbor. To get help in case of problems installing with pip, run pip with the ``--verbose`` flag, and attach the output (along with the pip command itself) to a ticket on `Arbor's issues page `_. Getting Arbor ------------- Every point release of Arbor is pushed to the Python Package Index. For x86-64 Linux and MacOS platforms, we provide binary wheels. The easiest way to get Arbor is with `pip `_: .. code-block:: bash # Recommended but optional: install Arbor in a virtual environment python -m venv arbor_env source arbor_env/bin/activate # Download and install Arbor pip install arbor To test that Arbor is available, try the following in a Python interpreter to see information about the version and enabled features: .. code-block:: python >>> import arbor as A >>> A.print_config() You are now ready to use Arbor! You can continue reading these documentation pages, have a look at the :ref:`Python API reference`, or visit the :ref:`tutorial`. .. Warning:: For builds from Arbor's source, you will need to have some development packages installed. Installing Arbor for any other platforms than listed above, ``pip`` will attempt a build from source and thus require these packages as well. * Ubuntu/Debian: ``git cmake gcc python3-dev python3-pip`` * Fedora/CentOS/OpenSuse: ``git cmake gcc-c++ python3-devel python3-pip`` * MacOS: get ``brew`` `at brew.sh `_ and run ``brew install cmake clang python3`` * Windows: the simplest way is to use `WSL `_ and then follow the instructions for Ubuntu. .. _in_python_custom: Customising Arbor ^^^^^^^^^^^^^^^^^ If you wish to get the latest Arbor straight from the master branch in our git repository, you can run: .. code-block:: bash pip install git+https://github.com/arbor-sim/arbor.git If you want to work on Arbor's code, you can get a copy of our repo and point `pip` at the local directory: .. code-block:: bash # get your copy of the Arbor source git clone https://github.com/arbor-sim/arbor.git --recursive # make your changes and then instruct pip to build and install the local source pip install ./arbor/ Every time you make changes to the code, you'll have to repeat the second step. .. _in_python_adv: Advanced options ^^^^^^^^^^^^^^^^ Arbor comes with a few compilation options, some of them related to advanced forms of parallelism and other features. The options and flags are the same :ref:`as documented for the CMAKE build `, but they are passed differently. To enable more, they must be placed in the ``CMAKE_ARGS`` environment variable. The simplest way to do this is by prepending the ``pip`` command with ``CMAKE_ARGS=""``, where you place the arguments separated by space inside the quotes. The following flags can be used to configure the installation: * ``ARB_WITH_MPI=``: Enable MPI support, requires MPI library. Default ``OFF``. If you intend to use ``mpi4py``, you need to install the package before building Arbor, as binding it requires access to its headers. * ``ARB_GPU=``: Enable GPU support for NVIDIA GPUs with nvcc using ``cuda``, or with clang using ``cuda-clang`` (both require cudaruntime). Enable GPU support for AMD GPUs with hipcc using ``hip``. By default set to ``none``, which disables GPU support. * ``ARB_VECTORIZE=``: Enable vectorization. The architecture argument, documented below, may also have to be set appropriately to generated vectorized code. See :ref:`install-architecture` for details. * ``ARB_ARCH=``: CPU micro-architecture to target. The advised default is ``native``. See `the GNU GCC documentation `_ for a full list of options. .. note:: There are more, advanced flags that can be set. We are using ``scikit-build-core`` and ``CMake`` under the hood, so all flags and options valid in ``CMake`` can be used in this fashion. Detailed instructions on how to install using CMake are in the :ref:`Python configuration ` section of the :ref:`installation guide `. CMake is recommended if you need more control over compilation and installation, plan to use Arbor with C++, or if you are integrating with package managers such as Spack and EasyBuild. In the examples below we assume you are installing from a local copy. **Vanilla install** with no additional features enabled: .. code-block:: bash pip install ./arbor **With MPI support**. This might require loading an MPI module or setting the ``CC`` and ``CXX`` :ref:`environment variables `: .. code-block:: bash CMAKE_ARGS="-DARB_WITH_MPI=ON" pip install ./arbor **Compile with** :ref:`vectorization ` on a system with a SkyLake :ref:`architecture `: .. code-block:: bash CMAKE_ARGS="-DARB_VECTORIZE=ON -DARB_ARCH=skylake" pip install ./arbor **Enable NVIDIA GPUs (compiled with nvcc)**. This requires the :ref:`CUDA toolkit `: .. code-block:: bash CMAKE_ARGS="-DARB_GPU=cuda" pip install ./arbor **Enable NVIDIA GPUs (compiled with clang)**. This also requires the :ref:`CUDA toolkit `: .. code-block:: bash CMAKE_ARGS="-DARB_GPU=cuda-clang" pip install ./arbor **Enable AMD GPUs (compiled with hipcc)**. This requires setting the ``CC`` and ``CXX`` :ref:`environment variables `: .. code-block:: bash CC=clang CXX=hipcc CMAKE_ARGS="-DARB_GPU=hip" pip install ./arbor Note on 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.