particles/INSTALL at master · Meruem10/particles · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
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/>`_

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
    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: a simpler 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 install 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).

Troubleshooting
===============

If the two methods above fail, you may try this::

    cd some_folder_of_your_choosing
    git clone https://github.com/nchopin/particles.git
    python setup.py install --force

This will install the package, without compiling the little bit of Fortran code
that is used in module `qmc`. At this stage, you may already use the package if
you do not use anything related to quasi-Monte Carlo (i.e. option ``qmc`` in
class `SMC`). In addition, you may compile manually the said piece of Fortran
as follows::

    pip show particles  # tells you the folder where the package is installed
    cd where_particles_is_installed/particles
    f2py3 -c ../src/LowDiscrepancy.f -m lowdiscrepancy

Replace f2py3 by f2py if you use Python 2.  Make sure a Fortran compiler is
installed on your machine (e.g. package gfortran on Ubuntu).  Utility `f2py` is
part of Numpy; see here_.

.. _here: https://docs.scipy.org/doc/numpy/f2py/