diff --git a/LICENSE b/LICENSE
index a73acc428659dd673ca109540047a3f9ecb4839f..ec85388ddb0c580e3b3d1f4d59ef6977bd52cd12 100644
--- a/LICENSE
+++ b/LICENSE
@@ -1,28 +1,11 @@
-Copyright (c) 2016, Eidgenössische Technische Hochschule Zürich and
-Forschungszentrum Jülich GmbH.
-All rights reserved.
+Copyright 2016-2020 Eidgenössische Technische Hochschule Zürich and Forschungszentrum Jülich GmbH.
-Redistribution and use in source and binary forms, with or without modification,
-are permitted provided that the following conditions are met:
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
-1. Redistributions of source code must retain the above copyright notice, this
- list of conditions and the following disclaimer.
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
-2. Redistributions in binary form must reproduce the above copyright notice,
- this list of conditions and the following disclaimer in the documentation
- and/or other materials provided with the distribution.
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
-3. Neither the name of the copyright holder nor the names of its contributors
- may be used to endorse or promote products derived from this software without
- specific prior written permission.
+3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
-ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
-WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
-DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
-ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
-(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
-LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
-ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
-(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
-SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
diff --git a/doc/python.rst b/doc/python.rst
index 63c57f2cda7d809a95c37d9bcdaf095e74328d75..c46630b9514db85a08897359e9f90136279d5200 100644
--- a/doc/python.rst
+++ b/doc/python.rst
@@ -3,87 +3,67 @@
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.
+Arbor's Python wrapper will be the most convenient interface for most users.
-To test that Arbor is available, try the following in a `Python 3 <python2_>`_ interpreter:
-
-.. code-block:: python
+Getting Arbor
+-------------
- >>> import arbor
- >>> print(arbor.__config__)
- {'mpi': True, 'mpi4py': True, 'gpu': False, 'version': '0.2.3-dev'}
- >>> print(arbor.__version__)
- 0.2.3-dev
+The easiest way to get Arbor is with
+`pip <https://packaging.python.org/tutorials/installing-packages>`_:
-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``.
+.. code-block:: bash
-Performance
---------------
+ pip3 install arbor
-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.
+It is also possible to use Setuptools directly on a local copy of the source code:
-.. _python2:
-
-Python 2
-----------
+.. code-block:: bash
-Python 2 reached `end of life <https://pythonclock.org/>`_ 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
-:ref:`configuring CMake <install-python>`, support is only provided for using
-Arbor with Python 3.6 and later.
+ # use setuptools and python directly
+ git clone https://github.com/arbor-sim/arbor.git --recursive
+ python3 install ./arbor/setup.py
-Installing
--------------
+.. note::
+ Arbor's Setuptools process simplifies installation for common configurations
+ on laptops and workstations by calling CMake under the hood.
-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 <https://packaging.python.org/tutorials/installing-packages>`_.
+ To install Arbor on a HPC cluster, or to configure Arbor with system-specific
+ options, we recommend using the :ref:`CMake build process <installarbor>`.
-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.
+To test that Arbor is available in Python, try the following in a `Python 3 <python2_>`_ interpreter
+to see information about the version and enabled features:
-.. code-block:: bash
+.. code-block:: python
- 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
+ >>> import arbor
+ >>> print(arbor.__version__)
+ >>> print(arbor.__config__)
-This will install Arbor as a site-wide package with only multi-threading enabled.
+Advanced Options
+^^^^^^^^^^^^^^^^^^
-To enable more advanced forms of parallelism, the following flags can optionally
-be passed to the pip install command:
+By default Arbor is installed with multi-threading enabled.
+To enable more advanced forms of parallelism, the following optional flags can
+be used to configure the installation:
-* ``--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 to ``native``.
+* ``--mpi``: Enable MPI support (requires MPI library).
+* ``--gpu``: Enable NVIDIA CUDA support (requires cudaruntime and nvcc).
+* ``--vec``: Enable vectorization. This might require choosing an appropriate architecture using ``--arch``.
+* ``--arch``: CPU micro-architecture to target. By default this is set to ``native``.
-If calling ``setup.py`` the flags must to come after ``install`` on the command line,
+If calling ``setup.py`` the flags must 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.
+below demonstrate this for both pip and ``setup.py``.
-Vanilla install with no additional options/features enabled:
+**Vanilla install** with no additional features enabled:
.. code-block:: bash
- pip3 install ./arbor
+ pip3 install arbor
python3 ./arbor/setup.py install
-Enable MPI support. This might require loading an MPI module or setting the ``CC`` and ``CXX``
-:ref:`environment variables <install-mpi>`.
+**With MPI support**. This might require loading an MPI module or setting the ``CC`` and ``CXX``
+:ref:`environment variables <install-mpi>`:
.. code-block:: bash
@@ -95,11 +75,10 @@ Compile with :ref:`vectorization <install-vectorize>` on a system with SkyLake
.. code-block:: bash
- pip3 install --install-option='--vec' --install-option='--arch=skylake' ./arbor
+ 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 :ref:`CUDA toolkit <install-gpu>`
-is installed and the CUDA compiler nvcc is available:
+**Enable NVIDIA GPUs**. This requires the :ref:`CUDA toolkit <install-gpu>`:
.. code-block:: bash
@@ -107,9 +86,9 @@ is installed and the CUDA compiler nvcc is available:
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
+ Setuptools compiles the Arbor C++ library and
+ wrapper, which can take a few minutes. Pass the ``--verbose`` flag to pip
+ to see the individual steps being performed if you are concerned that progress
is halting.
.. Note::
@@ -121,23 +100,45 @@ is installed and the CUDA compiler nvcc is available:
and installation.
.. Note::
- If there is an error installing with pip you want to report,
+ To report problems installing with pip,
run pip with the ``--verbose`` flag, and attach the output (along with
- the pip command itself) to a ticket on the
- `Arbor GitHub <https://github.com/arbor-sim/arbor/issues>`_.
- For example, ``pip3 install --install-option='--mpi' --verbose .``.
+ the pip command itself) to a ticket on
+ `Arbor's issues page <https://github.com/arbor-sim/arbor/issues>`_.
Dependencies
^^^^^^^^^^^^^
-If a downstream dependency of Arbor that requires Arbor be built with
+If a downstream dependency requires Arbor be built with
a specific feature enabled, use ``requirements.txt`` to
`define the constraints <https://pip.pypa.io/en/stable/reference/pip_install/#per-requirement-overrides>`_.
-For example, a package that depends on `arbor` would version 0.3 or later
-with MPI support would add the following to its requirements.
+For example, a package that depends on `arbor` version 0.3 or later
+with MPI support would add the following to its requirements:
.. code-block:: python
arbor >= 0.3 --install-option='--gpu' \
--install-option='--mpi'
+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.
+
+.. _python2:
+
+Python 2
+----------
+
+Python 2 reached `end of life <https://pythonclock.org/>`_ in January 2020.
+Arbor only provides support for Python 3.6 and later.
+
+.. note::
+ It might be possible to install and run Arbor
+ using Python 2.7 by setting the ``PYTHON_EXECUTABLE`` variable when
+ :ref:`configuring CMake <install-python>`.
+ However, Arbor is not tested against Python 2.7, and we won't be able
+ to provide support.
+
+
diff --git a/python/readme.md b/python/readme.md
new file mode 100644
index 0000000000000000000000000000000000000000..b25b57be669f586d3a788aac37de605cd066386c
--- /dev/null
+++ b/python/readme.md
@@ -0,0 +1,10 @@
+# Arbor
+
+The Arbor Python package is a wrapper around the high-performance C++ library Arbor, for
+constructing and running simulations multi-compartment neuron models, from single cell models
+to large networks.
+
+Documentation is available online at [Read the Docs](https://arbor.readthedocs.io/en/latest/python.html).
+
+[Submit a ticket](https://github.com/arbor-sim/arbor) if you have any questions or want help.
+
diff --git a/setup.cfg b/setup.cfg
new file mode 100644
index 0000000000000000000000000000000000000000..aaac5cf4e6368d6be3f74f71d89cb1beb058c30f
--- /dev/null
+++ b/setup.cfg
@@ -0,0 +1,2 @@
+[metadata]
+description-file = python/readme.md