INSTALL

Python 2 vs Python 3 
====================

Short version: **particles** only supports Python 3.

Long version:  initially, **particles** supported both Python 2 and Python 3.
However, Python 2 has been deprecated, and supporting it has become
troublesome. The last version to support it has been turned into a release; you
may find in the releases section of the github page (first release, April 15,
2020). 


Requirements
============

The short version: install The Anaconda_ distribution 
to get all the scientific computing libraries you may ever need in one go. 

.. _Anaconda: https://www.anaconda.com/distribution 

The long version: **particles** requires the following libraries: 

* `NumPy <http://www.numpy.org/>`_ 
* `SciPy <http://www.scipy.org/>`_ 
* `numba <https://numba.pydata.org/>`_
* `joblib <https://joblib.readthedocs.io/>`_

In addition, it is **strongly recommended** to install the following plotting
libraries:  

* `Matplotlib <http://matplotlib.org/>`_
* `seaborn <https://seaborn.pydata.org/>`_

Most of the examples require these libraries to plot results. 

Again, the easiest way to install all these libraries in one go is to simply
install the Anaconda_ distribution.  Manual installation is of course also
possible; e.g. on Ubuntu/Debian:: 

    sudo apt install python-numpy python-scipy python-numba python-matplotlib python-seaborn

However, in the maintainer's experience, conda is usually less hassle, and 
runs faster (because it install a more efficient version of low-level libraries
such as BLAS). 

Installation: recommended method
================================

The package is available on Github_ and may be installed using git::

    cd some_folder_of_your_choosing
    git clone https://github.com/nchopin/particles.git
    cd particles
    pip install --user .

Replace option `--user` by `-e` if you want to install in editable mode; in that
way you may edit yourself the package (in the folder you chose), and then
import the modified version. 

.. _Github: https://github.com/nchopin/particles.git

Installation: alternative method
================================

The package is also available on PyPI_ (the Python package index), so you may
install it by running pip. On a Linux machine:: 

    pip install --user particles

.. _PyPi: https://pypi.python.org/pypi 

Option ``--user`` lets you install the package in your home directory, rather than
globally for all users. 

The only drawback of this method is that it installs only the modules of the
package, and not the additional examples (e.g. the datasets and scripts that 
were used to generate the plots found in the book).