Introduction

What is pyqcm?

pyqcm is a python module that interfaces with a library written in C++: qcm. This library provide 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 Pertrubation 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 consitutes also a embryonic developer’s manual.

Installation

Pyqcm is written in Python but required the compilation of its core C++ library (qcm) provided with the distribution, and depends on CUBA for numerical integration and BLAS-LAPACK for elementary (non sparse) linear algebra. Optional dependencies are Eigen for high performance linear algebra (although qcm implements one, it is not as performant on many core system) and PRIMME eigensolver.

Basic installation

These instructions just install Pyqcm, its core library, and automatically download and compile numerical integration library CUBA.

The source code can be cloned with the following command:

#from bitbucket:
git clone https://dsenech@bitbucket.org/dsenechQCM/qcm_wed.git
#or, from github:
git clone https://github.com/dsenech/qcm_wed.git

Compiling can be done with pip:

cd <path_to_qcm_wed_folder>
pip install .

Advanced installation

These instruction allow to finely tune the configuration of Pyqcm (e.g. its optional dependencies).

Clone the source code as above:

#from bitbucket
git clone https://dsenech@bitbucket.org/dsenechQCM/qcm_wed.git
git checkout Moise/modular_Hamiltonian #dev version

Specify the build configuration by exporting the CMAKE_ARGS environment variable:

export CMAKE_ARGS="[BUILD_ARG1]=[VALUE1] [BUILD_ARG2]=[VALUE2] ..."

Optional build arguments and their values include:

  • -DDOWNLOAD_CUBA=0/1: Specify to download and compile automatically the CUBA integration library.

  • -DCUBA_DIR=[path_to_CUBA_root_dir]: If CUBA not downloaded from above, specify the path to CUBA directory for linking Pyqcm against (must contain compiled Cuba library libcuba.a along with the header cuba.h).

  • -DBLA_VENDOR=[value]: BLAS implementation to use. See CMake vendor documentation for more information (recommended: do not specify or FlexiBLAS on Alliance cluster).

  • -DEIGEN_HAMILTONIAN=0/1: Specify to compile with Eigen format for the Hamiltonian for better performance in the diagonalisation solver on multi-core machine (require Eigen library).

  • -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).

  • -DDOWNLOAD_PRIMME=0/1: Specify to download and compile automatically the PRIMME eigensolver library (needs -DWITH_PRIMME=1).

  • -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.

For a full-capability build, use:

export CMAKE_ARGS="-DDOWNLOAD_CUBA=1 -DEIGEN_HAMILTONIAN=1 -DWITH_PRIMME=1 -DDOWNLOAD_PRIMME=1"

Lastly, compile with:

pip install .

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