================================================================================
              Quick instructions for compilation and use of KGEC 3.0
                       (scalar and mpi parallelized)
================================================================================


To install KGEC:
----------------

Prerequisites:

- Fortran 90 compilers (Makefiles for Intel or GNU provided).

- A working Quantum Espresso installation (serial or mpi-parallel).
  A minimum build of pw and pp is required. KGEC 3.0 supports the
  following QE versions:

      5.1.2   5.2.1   5.4.0
      6.0     6.1     6.2.1   6.3     6.4.1
      7.0     7.1     7.2     7.3     7.3.1   7.4     7.4.1   7.5

  (Pick whichever is already installed in your environment.)

- Another option is to have 5.2.1 modified and installed using Intel
  compilers to use with Profess@QE.

KGEC will inherit the build environment, including mpi-parallelization
if present, (not thread parallelization) of QE.

The installation steps are the following:
1) Set the QE variable in the root Makefile to the root dir of your QE
   installation, or use the default ($HOME/prgs/qe/qe-gnu/$(QEV)-$(TYPE)).
2) Build, selecting the QE version with QEV on the command line:

       make QEV=7.5

   QEV defaults to 5.1.2 if not specified. The DQEV preprocessor flag
   is auto-derived from QEV; override only to force a specific stanza.
   The resulting kgec.x is placed under gnu/for-qe-$(QEV)-$(TYPE)/.


To run the code:
----------------

Serial execution:

To execute kegec serial use the standard command line instruction

$KGEC_DIR/kgec.x < $INP_DIR/$kgec.in > $OUT_DIR/$kgec.out 

where:

- $KGEC_DIR contains the directory name where the executable is.
- kgec.x is the executable.
- $INP_DIR contains the directory name of the input file.
- kgec.in is the input file name.
- $OUT_DIR contains the directory name of the output file.
- kgec.out is the output file name.


Parallel execution:

The code is mpi-parallelized over k-points, plane waves and bands. To take 
advantage of that use QE standard for execution. For example, using the
same definitions as for serial execution:

mpiexec -n 8 $KGEC_DIR/kegec.x -nk 2 -nb 2 -np 2 < $INP_DIR/kegec.in \
> $OUT_DIR/kgec.out

will run in parallel spanning 8 processes, with 2 dedicated to k-points
parallelization, 2 to bands parallelization and 2 to plane waves.


To run an example:
------------------

1) change to ./example/run dir
2) execute QE with the Al-fcc.in and Al.UPF files provided
3) Once QE has run successfuly run kgec.x in the same directory using kgec.in 
as input file
4) compare results with the reference data in ./examples/reference

For more details see the ../docs/KGEC-guide*.pdf file.

