############
Introduction
############

What is pyqcm?
==============

pyqcm is a python module that interfaces with a library written in C++: **qcm**.
This library provides a collection of functions that help implement quantum cluster methods.
Specifically, it provides an exact diagonalization solver for small clusters on which a Hubbard-like model is defined and provides functions to define infinite-lattice models and to embed the clusters into the lattice via *Cluster Perturbation Theory* (CPT). Methods like the *Variational Cluster Approximation* (VCA) and *Cluster Dynamical Mean Field Theory* (CDMFT) are then implemented from qcm by the pyqcm module, which is written in Python only.

This document is not a review of the above methods; the reader is referred to the appropriate review articles for that. It is strictly a user's manual for the pyqcm module.
Some degree of understanding of the above methods is however necessary to proceed.
This document also provides insights as to the inner working of the code, and therefore constitutes also an embryonic developer's manual.


Installation
============

Dependencies
------------

Pyqcm is written in Python but requires the compilation of its core C++ library
(**qcm**) provided with the distribution, and depends on **BLAS-LAPACK** for elementary (non sparse) linear algebra, the **Eigen** library for linear algebra and sparse linear algebra, and the **PRIMME** eigensolver (optional). Numerical integration is provided by the **cubature** library, which is bundled with the distribution.


Minimal installation
--------------------

These instructions are for installing Pyqcm and its core library.

The source code can be cloned with the following command::

    git clone https://dsenech@bitbucket.org/dsenechQCM/qcm_wed.git

Compiling can be done with pip::

    cd <path_to_qcm_wed_folder>
    pip install .

The previous instructions, however, do not install an optimized executable and
can be significantly slower. For state of the art performance, see the Advanced
installation instruction below.


Advanced installation
---------------------

These instruction allow to finely tune the configuration of Pyqcm and its optional dependencies. These options are set before installing pyqcm with pip and are configurable through the CMAKE_ARGS environment variable such as:
export CMAKE_ARGS="[BUILD_ARG1]=[VALUE1] [BUILD_ARG2]=[VALUE2] ..."

Optional build arguments and their values include:

* ``-DBLA_VENDOR=[value]``: BLAS implementation to use. See `CMake vendor documentation <https://cmake.org/cmake/help/latest/module/FindBLAS.html?highlight=bla_vendor#blas-lapack-vendors>`_ for more information (recommended: do not specify or ``FlexiBLAS`` on `Alliance cluster <https://docs.alliancecan.ca/wiki/BLAS_and_LAPACK>`_).
* ``-DWITH_PRIMME=0/1``: Whether to use or not the PRIMME library and its eigensolver for finding ground state of the Hamiltonian (needs ``-DEIGEN_HAMILTONIAN=1``, default not used).
* ``-DDOWNLOAD_PRIMME=0/1``: Specify to download and compile automatically the PRIMME eigensolver library (needs ``-DWITH_PRIMME=1``, not downloaded by default).
* ``-DPRIMME_DIR=[path_to_PRIMME_root_dir]``: Specify the path to the PRIMME root directory for linking qcm_wed library against if not download automatically (default not set).
* ``-DWITH_GF_OPT_KERNEL=0/1``: If true, automatically detect host processor AVX2 capabilities (i.e. Intel processors after 2014 and AMD processors after 2015) and compile the optimized (5 times quicker) kernel for Green function evaluation accordingly (default yes).
* ``-DQCM_DEBUG=0/1``: Enable extra verbose information for debug purpose (default no).
* ``-DCMAKE_C_COMPILER=[gcc/icc/clang/...]``: The C compiler to use to compile qcm and its automatically downloaded dependencies.
* ``-DCMAKE_CXX_COMPILER=[g++/icpc/clang++/...]``: The C++ compiler to use to compile qcm and its automatically downloaded dependencies (must match the C compiler, for example ``gcc`` with ``g++``).
* ``-DAPPLE_LIBOMP_PREFIX=[path]``: Custom path to the OpenMP library ``libomp`` on Apple computer.
* ``-DUSE_OPENMP=0/1``: Enable parallelization using OpenMP (default yes).

For a full-capability build, use::

    export CMAKE_ARGS="-DEIGEN_HAMILTONIAN=1 -DWITH_PRIMME=1 -DDOWNLOAD_PRIMME=1 -DWITH_GF_OPT_KERNEL=1 -DUSE_OPENMP=1"

Lastly, compile with::

    pip install .

See also the file ``INSTALL`` in the root of pyqcm folder which contains more information.