===========================================================================
 AtomPAW -- Installation Guide
===========================================================================

AtomPAW generates Projector Augmented-Wave (PAW) setups for use with
electronic structure codes based on Density-Functional Theory (DFT).

For general information, please visit the official website:
  http://users.wfu.edu/natalie/papers/pwpaw

---------------------------------------------------------------------------
 Table of Contents
---------------------------------------------------------------------------
  1. Prerequisites
  2. Getting the source code
  3. Quick start
     3a. Installation via Autotools
     3b. Installation via CMake
  4. Configuration options (Autotools)
  5. CMake options
  6. Environment variables
  7. Build and install
  8. Troubleshooting
  9. Contact
---------------------------------------------------------------------------


1. Prerequisites
================

Required:
  - A Fortran 90 compiler (gfortran, ifort, ifx, nagfor, ...)
  - A BLAS/LAPACK library (OpenBLAS, MKL, LAPACK reference, Accelerate on macOS, ...)
  - GNU Autotools: autoconf (>= 2.62), automake (>= 1.10), libtool (>= 2.2.2)
    [only needed when building from the Git repository with Autotools]
  - CMake (>= 3.20) [only needed when building with CMake]

Optional:
  - LibXC (>= 2.x): collection of exchange-correlation functionals
      https://www.tddft.org/programs/libxc/


2. Getting the source code
==========================

From the official website (tarball -- recommended for end-users):
  Download a release tarball from http://users.wfu.edu/natalie/papers/pwpaw
  The tarball already contains a pre-generated `configure` script; skip
  directly to section 3.

From the Git repository:
  git clone https://github.com/atompaw/atompaw.git
  cd atompaw

  You must first generate the `configure` script by running:

    ./bootstrap.sh

  This calls aclocal, autoconf, and automake in the correct order.
  It requires Autotools to be installed on your system.


3. Quick start
==============

3a. Installation via Autotools
-------------------------------

The standard three-step build for a simple installation:

  ./configure --prefix=/path/to/install
  make
  make install

This installs the `atompaw` executable under /path/to/install/bin/.

If BLAS/LAPACK are not found automatically (see section 8), use:

  ./configure --prefix=/path/to/install \
              --with-linalg-prefix=/path/to/blas_lapack
  make
  make install


3b. Installation via CMake
---------------------------

CMake is the most straightforward installation method.
Once inside the AtomPAW source directory, simply run:

  mkdir build && cd build
  cmake .. -DCMAKE_INSTALL_PREFIX=/path/to/install
  make
  make install

The BLAS/LAPACK library should be automatically detected. If not, add
the following on the `cmake ..` line:

  -DBLAS_ROOT=/path/to/blas -DLAPACK_ROOT=/path/to/lapack

The LibXC library (collection of exchange-correlation functionals,
see https://libxc.gitlab.io) is optional and should be automatically
detected. If not, add the following on the `cmake ..` line:

  -DLIBXC_ROOT=/path/to/libxc


4. Configuration options (Autotools)
=====================================

Run `./configure --help` for the complete list. The most useful options
are described below.

Installation prefix:
  --prefix=DIR
      Install atompaw under DIR (default: /usr/local).
      The executable will be placed in DIR/bin/atompaw.

Linear algebra (BLAS/LAPACK):
  --with-linalg-prefix=DIR
      Root directory of the BLAS/LAPACK installation.
      configure will look for headers in DIR/include and
      libraries in DIR/lib (or DIR/lib64).

  --with-linalg-libs=FLAGS
      Explicit linker flags for BLAS/LAPACK, e.g.:
        --with-linalg-libs="-L/opt/openblas/lib -lopenblas"
      Use this when the library layout is non-standard.

LibXC (optional):
  --enable-libxc
      Activate LibXC support (disabled by default).

  --with-libxc-prefix=DIR
      Root directory of the LibXC installation.

  --with-libxc-incs=FLAGS
      Explicit include flags for LibXC headers, e.g.:
        --with-libxc-incs="-I/opt/libxc/include"

  --with-libxc-libs=FLAGS
      Explicit linker flags for LibXC, e.g.:
        --with-libxc-libs="-L/opt/libxc/lib -lxcf90 -lxc"

Fortran compiler selection:
  --with-fc-vendor=VENDOR
      Force a specific compiler vendor (gnu, intel, nag, ...).

  --with-fc-version=VERSION
      Force a specific compiler version.


5. CMake options
================

Run `cmake -LA ..` from the build directory for the complete list.
The most useful options (passed as -DOPTION=VALUE on the cmake line):

Installation prefix:
  CMAKE_INSTALL_PREFIX=DIR
      Install atompaw under DIR (default: /usr/local).

Fortran compiler:
  CMAKE_Fortran_COMPILER=PATH
      Path to the Fortran compiler to use, e.g.:
        -DCMAKE_Fortran_COMPILER=ifort

Build type:
  CMAKE_BUILD_TYPE=Release|Debug|RelWithDebInfo
      Optimization level (default: Release).

Linear algebra (BLAS/LAPACK):
  BLAS_ROOT=DIR
      Root directory of the BLAS installation.
  LAPACK_ROOT=DIR
      Root directory of the LAPACK installation.

LibXC (optional):
  LIBXC_ROOT=DIR
      Root directory of the LibXC installation.
      LibXC support is enabled automatically when this is set
      or when LibXC is found in standard system paths.

Example combining several options:

  cmake .. -DCMAKE_INSTALL_PREFIX=/opt/atompaw \
           -DCMAKE_Fortran_COMPILER=ifort \
           -DCMAKE_BUILD_TYPE=Release \
           -DBLAS_ROOT=/opt/mkl \
           -DLAPACK_ROOT=/opt/mkl \
           -DLIBXC_ROOT=/opt/libxc


6. Environment variables
========================

Environment variables can be set on the configure command line or
exported before running configure:

  FC          Fortran compiler to use (e.g. FC=ifort or FC=gfortran)
  FCFLAGS     Fortran compiler flags (overrides AtomPAW defaults)
  LDFLAGS     Linker flags
  LIBS        Additional libraries to link
  LINALG_PREFIX   Equivalent to --with-linalg-prefix
  LIBXC_PREFIX    Equivalent to --with-libxc-prefix

Examples:

  # Use Intel Fortran with MKL
  ./configure FC=ifort \
              FCFLAGS="-O2 -xHost" \
              --with-linalg-libs="-mkl"

  # Use gfortran with OpenBLAS installed in /opt/openblas
  ./configure FC=gfortran \
              --with-linalg-prefix=/opt/openblas

  # Enable LibXC with a custom installation path
  ./configure --enable-libxc \
              --with-libxc-prefix=/opt/libxc


7. Build and install
====================

After running configure successfully:

  make              # compile AtomPAW
  make install      # install the atompaw binary

To build in a separate directory (out-of-source build, recommended):

  mkdir build && cd build
  ../configure --prefix=/path/to/install [options]
  make
  make install

Useful make targets:

  make clean          Remove compiled object files and the binary
  make distclean      Remove all files generated by configure and make
                      (restores the source tree to a pristine state)
  make uninstall      Remove the installed files from PREFIX


8. Troubleshooting
==================

BLAS/LAPACK not found:
  If configure cannot find a BLAS/LAPACK library automatically, specify
  its location explicitly:

    --with-linalg-prefix=/path/to/openblas
  or
    --with-linalg-libs="-L/path/to/lib -lblas -llapack"

  On macOS, Apple's Accelerate framework can be used:
    --with-linalg-libs="-framework Accelerate"

  On systems with Intel MKL, the simplest flag is usually:
    --with-linalg-libs="-mkl"   (with ifort)
    --with-linalg-libs="-lmkl_rt"  (generic)

LibXC not found:
  Make sure LibXC was compiled with the same Fortran compiler as AtomPAW.
  Then point configure to its installation:
    --enable-libxc --with-libxc-prefix=/path/to/libxc

Compiler not found:
  Set FC to the full path of your Fortran compiler:
    FC=/usr/local/bin/gfortran-13 ./configure ...

Regenerating configure after editing configure.ac:
  If you modify configure.ac, regenerate configure with:
    ./bootstrap.sh
  or
    autoreconf -fi


9. Contact
==========

Bug reports and questions can be sent to the AtomPAW developers:
  natalie@wfu.edu
  marc.torrent@cea.fr

Source code and issue tracker:
  https://github.com/atompaw/atompaw

===========================================================================
