.. _install:
============
Installation
============
Requirements
============
In order to install PyNAO, the following packages must be installed
* git
* gcc
* gfortran
* build-essential
* liblapack-dev
* libfftw3-dev
* make
* cmake
* zlib1g-dev
* python3
* python3-pip
In addition, you will need to install a BLAS library. The choice of the BLAS
library is crucial in order to achieve optimal performances.
We recommand you to use `openBLAS `_ or
`Intel MKL `_.
PyNAO will need also the following python libraries
* wheel (for installation)
* pytest (for testing)
* pytest-cov (for testing)
* numpy
* scipy
* h5py
* numba
* pyscf
Some of the examples make use of the `ASE `_ package,
therefore its installation is recommended. ASE can be handy to launch Siesta
calculations from Python script and to setup the molecular system.
.. note::
Installing PySCF via conda may give an error when calling libxc library. For
details see issue `1183 `_ on PySCF
repository. To solve the issue, install PySCF via source as instructed on their
`website `_
.. note::
If pyscf 1.7 is installed, you may get an issue with h5py
(see issue `1003 on pyscf repository `_).
Use the work around given in the issue thread.
PyNAO uses DFT results from `Siesta `_
or `PySCF `_. PySCF is a requirement as shown above,
but one may use DFT Siesta outputs as inputs for PyNAO, therefore, you may want
to install Siesta as well.
.. note::
Currently, Siesta 5.0 or above is not supported. We advise you to install
Siesta 4.1
PyNAO Installation
==================
Standard installation with pip
------------------------------
On Ubuntu and similar OS, PyNAO can easily be instaaled using the Blas and Lapack
libraries.
>>> apt-get update
>>> apt-get install git gcc gfortran build-essential libopenblas-dev liblapack-dev libfftw3-dev make cmake zlib1g-dev python3 python3-pip
>>> pip3 install -r requirements.txt
>>> export CC=gcc && export FC=gfortran && export CXX=g++
>>> python3 setup.py bdist_wheel
>>> cd dist && pip3 install pynao-0.1.1-py3-none-any.whl
.. note::
By default, the installation will use the ``lib/cmake_user_inc_examples/cmake.user.inc-gnu-openmp``
``cmake.arch.inc`` file. For optimal performances, you may want to edit yourself
the ``cmake.arch.inc`` file. See section **Architecture file cmake.arch.inc**
for more details.
Standard installation with conda
--------------------------------
Install `conda `_ and run
>>> apt-get update
>>> apt-get install git gcc gfortran build-essential libopenblas-dev liblapack-dev libfftw3-dev make cmake zlib1g-dev
>>> conda env create -f environment.yml
>>> conda activate pynao
>>> conda install -c pyscf pyscf=1.7
Edit the file ``envs/pynao/lib/python3.7/site-packages/pyscf/lib/misc.py`` and comment
line 46, 47 (`1003 on pyscf repository `_).
One can also install PySCF 2.0, but it must to be installed from source (see
note above).
>>> export CC=gcc && export FC=gfortran && export CXX=g++
>>> python setup.py bdist_wheel
>>> cd dist && pip install pynao-0.1.1-py3-none-any.whl
Advance Installation with Anaconda and MKL
------------------------------------------
For optimal performances, we advise you to use `Anaconda Python `_
environment. This for three reasons
* First, in Anaconda, NumPy and SciPy libraries are compiled with MKL Blas library (offering in general better performances).
* You can easily use the MKL library included in Anaconda to compile PyNAO (even if it is still possible to use your custom MKL installation).
In the following, we assume Anaconda is installed under ``${HOME}/anaconda3``.
To properly compile PyNAO with Anaconda, perform the following steps
>>> apt-get update
>>> apt-get install git gcc gfortran build-essential liblapack-dev libfftw3-dev make cmake zlib1g-dev python3 python3-pip
>>> mkdir -p ${HOME}/anaconda3/lib/mkl/lib
>>> ln -s ${HOME}/anaconda3/lib/libmkl* ${HOME}/anaconda3/lib/mkl/lib/
>>> export CC=gcc && export FC=gfortran && export CXX=g++
>>> pip install ase
>>> conda install -c pyscf pyscf<2.0
Now, go to ``pynao`` root folder
>>> cp lib/cmake_user_inc_examples/cmake.user.inc-singularity.anaconda.gnu.mkl lib/cmake.arch.inc
Edit the file ``lib/cmake.arch.inc`` to indicate the proper path to MKL library.
You should replace the line ``set(MKLROOT "/opt/conda/lib/mkl/lib")`` by
``set(MKLROOT "${HOME}/anaconda3/lib/mkl/lib")``
then you can finish the installation
>>> python setup.py bdist_wheel
>>> pip install dist/pynao-0.1.1-py3-none-any.whl
Architecture file cmake.arch.inc
--------------------------------
For optimal performances, it is advised to edit the ``cmake.arch.inc`` file.
This file contains platform specific instruction such as BLAS and LAPACK libraries
definition (with MKL for example).
You can find examples in the folder ``lib/cmake_user_inc_examples``
Docker container
----------------
If `Docker `_ is installed on your system,
you can easily use PyNAO by simply
docker run -p 8888:8888 -it mbarbry/pynao:latest
The container starts an jupyter notebook. You can connect to it with your web
browser via the address http://127.0.0.1:8888/lab
The PyNAO tutorials are presents in the `tutorial-pynao` folder.
You can as well simply run a Python script via
docker run -p 8888:8888 -v $(pwd):/usr/src/app -it mbarbry/pynao:latest /usr/bin/python3 yourScript.py
The docker image contains all the require dependency as well as a serial compilation
of Siesta. More optimal Docker containers of Siesta can be found in the
`Atomic-scale Simulation Environments `_.
Singularity container
---------------------
We provide in ``share/singularity-img`` a collection of
`Singularity `_ recipes that are optimized.
If possible, we advise you to use these recipes to use PyNAO. To build the container
>>> sudo singularity build path2pynao/share/singularity-img/pynao-sing.mkl.gpu pynao-image.img
and to run PyNAO script
>>> singularity run pynao-image.img pynao_script.py
GPU support
-----------
Some part of the code can be accelerated using Nvidia GPUs via the cuBlas library.
For this you need to install the `cupy `_ library
>>> pip install cupy
or via `conda`
>>> conda install cupy
You can then pass the argument ``GPU=True`` in order to use GPU for your calculations.
GPU will mainly impact performances for large systems.