Verified Commit 1de5820a authored by Adel Kara Slimane's avatar Adel Kara Slimane
Browse files

Add INSTALL.rst

parent eda12ee3
Install and run
===============
The requirements come from kwant and tkwant. Install instructions and
dependencies on Kwant `are given
here <https://kwant-project.org/doc/1/pre/install>`__, they have been
used to write a more thorough guide in what follows.
Packages for Ubuntu
~~~~~~~~~~~~~~~~~~~
1. Enable the “universe” and “multiverse” repositories: open an
application called “Software & updates”. In “Ubuntu Software” tab,
check the the repos corresponding to “universe” and “multiverse”.
2. Install some additional packages
.. code:: shell
$ sudo apt install git cython3 g++ g++-7 libhwloc-dev libibverbs-dev libjs-jquery-ui libblas-dev libmumps-scotch-5.1.2 libnuma-dev libscotch-6.0 libstdc++-7-dev g++ gfortran libmumps-scotch-dev build-essential libopenblas-dev liblapack-dev librsb-dev
3. Install python dependencies
.. code:: shell
$ sudo apt install python3-pip ipython3 python3-mpi4py python3-dill python3-scipy python3-dev python3-setuptools python3-matplotlib python3-pytest python3-sympy python-matplotlib-data python3-cycler python3-dateutil python3-decorator python3-ipython python3-ipython-genutils python3-mpmath python3-pickleshare python3-prompt-toolkit python3-pygments python3-pyparsing python3-simplegeneric python3-traitlets python3-wcwidth
4. Install python virtualenv to be able to have python virtual environments:
.. code:: shell
$ sudo apt install python3-virtualenv virtualenv
Packages for Fedora
~~~~~~~~~~~~~~~~~~~
The same tools and libraries need to be installed, but they have
different names.
1. Additionnal packages
.. code:: shell
$ sudo dnf install scotch scotch-devel MUMPS-openmpi-devel MUMPS-openmpi MUMPS MUMPS-devel MUMPS-mpich mpich mpich-devel metis metis-devel openblas* metis64 metis64-devel git gcc gcc-c++ gcc-gfortran lapack-static lapack-devel lapack64-static lapack64-devel``
2. Python packages
.. code:: shell
$ sudo dnf install python3-pip python3-dill python3-Cython python3-devel python3-scipy python3-setuptools python3-matplotlib python3-pytest python3-sympy python3-cycler python3-dateutil python3-decorator python3-ipython python3-matplotlib python3-mpmath python3-pickleshare python3-pygments python3-pyparsing python3-simplegeneric python3-sympy python3-traitlets python3-wcwidth python3-configparser python3-mpi4py-mpich python3-mpi4py-openmpi``
3. Install python virtualenv to be able to have python virtual environments:
.. code:: shell
$ sudo dnf install python3-virtualenv python3-virtualenv-api python3-virtualenv-clone python3-virtualenvwrapper python3-pytest-virtualenv``
Install instructions for Linux systems
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1. **Optional: Use a virtual environment** Create a folder that will
contain all the virtual environment folders, then create a virtual
environment in it (a folder that will contain all the pip3 installs)
and finally activate it (it will change the paths so that pip3 will
install packages in it and you use its python3 executable)
.. code:: shell
$ mkdir envs
$ cd envs
$ virtualenv --system-site-packages tkwantoperator
$ source tkwantoperator/bin/activate
*Note*: the last line “activates” the virtual environment. All pip
installs will be made in it. Deactivating the virtual environment
simply amounts to write
.. code:: shell
$ deactivate
Removing a virtual environment simply amounts to deleting its root folder,
in our case by deleting the folder ``envs/tkwantoperator``.
2. **Fedora specific:** Load openmpi environment
.. code:: shell
$ module load mpi/openmpi-x86_64 # can be mpi/mpich-x86_64
$ export CPATH=/usr/include/openmpi-x86_64/ # can be /usr/include/mpich-x86_64/, it should be consistent with the above line
3. Install latest tkwant, kwantspectrum and tkwantoperator:
.. code:: shell
$ pip3 install git+https://gitlab.kwant-project.org/kwant/tkwant.git
$ pip3 install git+https://gitlab.kwant-project.org/kwant/kwantspectrum.git@069a5c5beca0be954dd7a0810e306d425e90edec
$ pip3 install git+https://gitlab.kwant-project.org/kwant/tkwantoperator.git
*Note*: To install updates in any of the git repositories, simply redo the pip install.
Running scripts
~~~~~~~~~~~~~~~
You should now be able to use kwant, tkwant and tkwantoperator in the command line in
that virtual environment (if a virtual environment has been used). For example one can run the example
from the tutorial ``quantum_dot.py`` in the ``doc/source/tutorial`` folder:
.. code:: shell
python3 doc/source/tutorial/quantum_dot.py
.. _parallel-calculations:
Parallel calculations
^^^^^^^^^^^^^^^^^^^^^
To make the simulation faster, it is possible to run scripts on several
parallel cores. For example, one can run ``quantum_dot.py`` on 4 cores
with the following command:
.. code:: shell
mpirun -n 4 -bind-to none python3 doc/examples/quantum_dot.py
The ``-bind-to none`` option is there to not force the OS to use specific
threads to run the 4 copies. If the option is not used, the code will run
on the first 4 threads of the machine: if a second script is run in parallel
using the same command, the same cores will be used to run it, which will make
the simulation slower, since the same cores are used for both simulations.
There’s also the possibility of
choosing the threads on which to run the script
.. code:: shell
mpirun -n 5 --cpu-set 0-4 --bind-to core python3 doc/examples/quantum_dot.py
Where threads 0,1,2,3,4 will be used for the calculations, the same
command can be written:
.. code:: shell
mpirun -n 5 --cpu-set 0,1,2,3,4 --bind-to core python3 doc/examples/quantum_dot.py
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment