1. Quick Start¶

This section gives the opportunity to the prospective user to quickly set-up the necessary environment to install and test the ChASE library without the necessity of having access to a computing cluster. In the following, we provide simple step-by-step instructions on how to install ChASE on a laptop or a workstation equipped with a Linux or Unix OS. Because ChASE uses CMake for auto-detecting dependencies and managing configuration options across different platforms, it can be easily configured on any Linux and Unix based operating systems. Multiple examples are also provided, and user can utilize them to directly test ChASE on a matrix of his choice.

1.1. Getting ChASE¶

ChASE can be easily obtained by cloning the repository directly using git:

git clone https://github.com/ChASE-library/ChASE

It is also recommended that you check out the latest stable tag:

git checkout v1.3.0

1.2. Dependencies¶

In addition to a recent C++ compiler ChASE’s external dependencies are CMake , MPI , BLAS , LAPACK. To enhance the usability of the ready-to-use examples, it is also necessary to install the Boost library.

1.2.1. Installing dependencies on Linux¶

The following instructions for the installation of the prerequisite modules have been tested on the Ubuntu operating system (e.g., version 18.10), but they should work as well with most modern Linux OS.

1.2.1.1. CMake¶

Install CMake by executing the following command:

sudo apt-get install cmake

1.2.1.2. GNU compiler¶

To install the GNU C compiler, GNU C++ compiler, build utility for the compilation, and add some development tools execute the following command:

sudo apt-get install build-essential

1.2.1.3. Installing BLAS and LAPACK¶

The Basic Linear Algebra Subprograms (BLAS) and Linear Algebra PACKage (LAPACK) are both used heavily within ChASE. On most installations of Ubuntu, there are two optimized BLAS/LAPACK version available: OpenBLAS and ATLAS. To install them use either of the following commands:

sudo apt-get install libopenblas-dev
or
sudo apt-get install libatlas-dev liblapack-dev

1.2.1.4. Installing MPI¶

ChASE requires an implementation of the Message Passing Interface (MPI) communication protocol. The two most commonly used MPI implementations are MPICH, and OpenMPI.

MPICH can be installed by executing the following command:

sudo apt-get install libmpich2-dev

while OpenMPI can be installed by executing:

sudo apt-get install libopenmpi-dev

1.2.2. Installing dependencies on macOS¶

On any Apple computer running a macOS we warmly invite to use MacPorts (XCode is required and can be downloaded directly using the Apple Store application) to install the required dependencies. The installation of MacPorts and any of the supported ports requires administration privileges.

1.2.2.1. CMake¶

Install CMake by executing the following command:

sudo port install cmake

1.2.2.2. GNU compiler¶

To install the GNU C compiler, GNU C++ compiler, and GNU Fortran compiler execute the following commands:

sudo port install gcc10
sudo port select --set gcc mp-gcc10

1.2.2.3. Installing BLAS and LAPACK¶

The Basic Linear Algebra Subprograms (BLAS) and Linear Algebra PACKage (LAPACK) are both used heavily within ChASE. On an Apple computer one can either use the Accelerate framework, which is provided out of the box, or one could install OpenBLAS by executing the following command:

sudo port install OpenBLAS +native

1.2.2.4. Installing MPI¶

ChASE requires an implementation of the Message Passing Interface (MPI) communication protocol. The two most commonly used MPI implementations are MPICH, and OpenMPI.

MPICH can be installed by executing the following commands:

sudo port install mpich
sudo port select --set mpi mpich-mp-fortran

while OpenMPI can be installed by executing:

sudo port install openmpi
sudo port select --set mpi openmpi-mp-fortran

1.3. Quick Installation and Execution¶

Installing the ChASE library on Linux or macOS requires cloning the source files from a public github repository and compile them in few steps. An example, provided with the source files, can be used to run ChASE on a single computing node for the solution of an isolated Hermitian standard eigenproblem.

1.3.1. Building and Installing the ChASE library¶

On a Linux system with MPI and CMake installed in the standard locations, ChASE can be build by executing in order the following commands (after having cloned the repository):

cd ChASE/
mkdir build
cd build/
cmake .. -DCMAKE_INSTALL_PREFIX=${ChASEROOT}
make install

In the commands above, the variable ${CHASEROOT} is the path to install ChASE on user’s laptops. CMake will auto-detect the dependencies and select the default installed modules. In order to select a specific module installation, one can manually specify several build options, especially when multiple versions of libraries or several different compilers are available on the system. For instance, any C++, C, or Fortran compiler can be selected by setting the CMAKE_CXX_COMPILER, CMAKE_C_COMPILER, and CMAKE_Fortran_COMPILER variables, respectively. The following provides an illustration of such setting.

-D CMAKE_CXX_COMPILER=/usr/bin/g++ \
-D CMAKE_C_COMPILER=/usr/bin/gcc   \
-D CMAKE_Fortran_COMPILER=/usr/bin/gfortran

Analogously, it may be necessary to manually specify the paths to the MPI implementation by, for example, setting the following variables.

-D MPI_CXX_COMPILER=/usr/bin/mpicxx \
-D MPI_C_COMPILER=/usr/bin/mpicc \
-D MPI_Fortran_COMPILER=/usr/bin/mpif90

For instance, installing ChASE on an Apple computer with gcc and Accelerate, one could execute the following command:

cmake -DCMAKE_CXX_COMPILER=g++ -DCMAKE_C_COMPILER=gcc -DCMAKE_Fortran_COMPILER=gfortran ..

Note

If you want to try with ChASE or use ChASE as standalone eigensolver, the CMake flag -DCMAKE_INSTALL_PREFIX=${ChASEROOT} is not mandatory.

1.3.2. Quick Hands-on by Examples¶

For a quick test and usage of the library, we provide various ready-to-use examples which use ChASE to solve eigenproblems. Some of these examples make the additional use of the C++ library Boost for the parsing of command line values. Thus Boost should also be provided before the installation of ChASE if users would like to build ChASE with these examples. In order to build these examples together with ChASE the sequence of building commands should be slightly modified as below:

cd ChASE/
mkdir build
cd build/
cmake .. -DCMAKE_INSTALL_PREFIX=${ChASEROOT} -DBUILD_WITH_EXAMPLES=ON
make install

Executing ChASE using the ready-to-use examples is rather straightforward. For instance, 0. Hello World is executed by simply typing the line below:

./0_hello_world/0_hello_world

In this example, a Clement matrix is generated and default values of parameters are used.

To run this example with MPI, start the command with the mpi launcher of your choice, e.g. mpirun or srun.

For sake of completeness we provide a complete list of parameters in this example below.

Parameter (default value)	Description
N (=1001)	Size of the Input Matrix
nev (=40)	Wanted Number of Eigenpairs
nex (=20)	Extra Search Dimensions
deg (=20)	Initial filtering degree, value set by `config.SetDeg(20)`
tol (=1e-10)	Minimum tolerance required to declare eigenpairs converged, value set by `config.SetTol(1e-10)`
opt (=true)	If optimize the degree of filter internally by ChASE, value set by `config.SetOpt(true)`

Note

For the quick test and benchmark, user can modify some of parameters, e.g., to change the size of matrix N which will generate a clement matrix of different size, to change the number of wanted eigepairs nev, etc.

Note

For the fine tuning of more parameters in ChASE, please visit Configuration, in which we provide a class to set up all the parameters of eigensolvers. For the suggestion of selecting values of parameters, please visit Parameters and Configurations.

Note

For a complete explanation of all the examples, please visit Examples.