README.mini-DFT

This is the README file for MiniDFT

1) Description

Mini-DFT is a plane-wave denstity functional theory (DFT) mini-app for modeling
materials.  Given an set of atomic coordinates and pseudopotentials, miniDFT
computes self-consistent solutions of the Kohn-Sham equations using either the 
LDA, PBE or PBE0 exchange-correlation functionals. For each iteration of the 
self-consistent field cycle, the Hamiltonian matrix is constructed and then 
diagonalized. To build the Hamiltonian matrix, Fast Fourier Transforms are used 
to tranform orbitals from the plane wave basis (where the kinetic energy is 
most readily computed) to real space (where the potential is evaluated) and 
back. Davidson diagonalization is used to compute the orbital energies and 
update the orbital coefficients.

The miniDFT mini-app was excised from PWscf, part of the the general-purpose 
Quantum ESPRESSO (QE) suite. A copy of the GPL is provided in the 'License' 
file in this directory.

Despite being directly derivated from PWscf, miniDFT uses a different format for
pseudopotential files because miniDFT does not include QE's I/O toolkit.

This README file describes the procedure for running the miniDFT benchmark 
calculations.

This miniDFT distribution consists of three top-level directories.
src: source code and makefiles for miniDFT
test: small input files for build validation
benchmark: input files for performance measurement


2) How to Build miniDFT:

miniDFT requires ScaLAPACK, BLAS and FFT libraries. miniDFT currently support 
only FFTW3 interface.

Define the miniDFT root directory 

$ export MDFT_ROOT=/path/to/miniDFT

Move to the src directory.

$ cd $MDFT_ROOT/src

Edit Makefile and initiate the build

$ vim Makefile
$ make


3) Validate the build

You can test the build using the small input (small.pbs and small.in). The 
total energy should match the total energy to within 10^-5 Ry:

!    total energy              =   -2888.59081781 Ry


4) How to run miniDFT

The -in flag (required) is used to identify the input file read by miniDFT.

The -nbgrp flag (optional) enables band-group parallelism to improve the 
parallel scaling.  The number of task groups must be a divisor of the number 
of MPI ranks. The default value for bgrp is 1.  The chosen value must evenly 
divide the total number of MPI tasks used in the calculation.

The -ndiag flag (optional) sets the number of MPI ranks used for 
diagonalizaton and it must be a square integer. The default value for ndiag is 
the largest square integer less than half the total number of MPI ranks per 
group.

The -ntg flag (optional) enables task-group parallelism to improve the parallel 
scaling of the FFTs. The number of task groups must be a divisor of the number 
of MPI ranks. The default 
value for ntg is 1.

The -npool flag (optional) divides the MPI ranks into "pools". K-points are 
distributed among pools, and individual k-points can be evaluated with very 
little communication between pools. The default value for npool is 1.

To run the code, do someting like:

$ export OMP_NUM_THREADS=6
$ mpirun -np 32 ./mini_dft -in small.in -nbgrp 4 > small.out