About this document
------------------------------------------------------------------------
This document describes how to tests your build of VASP.6.X.
It closely follows the information you will find at:
http://www.vasp.at/wiki/index.php/Validation_tests
If you can access the aformentioned link we recommend
you do so right now and forget about this document
(since the information on our wiki is more complete
and up-to-date), if not, please continue reading.
# 1. The VASP testsuite
------------------------------------------------------------------------
The VASP testsuite is located in `root/testsuite` where `root` is the
root directory of the build system.
vasp.X.X.X (root directory)
|
----------------------------------------------
| | | | |
arch bin testsuite build src
|
------------------------------------------
| | | | | |
tests README.md tools POTCARS runtest makefile
|
------------------
| | |
test1 test2 ... testN
* `testsuite/`
Testsuite root directory. Holds several subdirectories and
the main bash-script `runtest` that runs the tests and
validates the results.
* `testsuite/tests`
Holds a whole bunch of subdirectories that in turn contain the
input files (`INCAR.?.*`, `KPOINTS`, and `POSCAR`), and reference
output (`OUTCAR.ref`, `OSZICAR.ref` etc.) for the test
calculations.
* `testsuite/POTCARS`
Holds the `POTCAR` files (potentials), one for each individual
test calculation.
The naming convention for these files is:
`POTCAR.name-of-test-subdirectory`
* `testsuite/tools`
Contains a bash-script (`call_compare`) and a Fortran source file
(`compare_numbertable_new.f90`). The latter is compiled as:
$(FC) -o compare_numbertable_new compare_numbertable_new.f90
where `$(FC)` is the Fortran compiler binary path
that has to be set in `root/makefile.include`
(see Sec. 3.2 of`root/README.md`).
* `testsuite/runtest`
Main execution script that orchestrates which tests are executed
based on set environment variables.
* `testsuite/makefile`
Autoconf makefile containing some simple rules that either
compile `compare_numbertable_new.f90` (`make numbertable`),
execute a small selection of tests (`make test`) or execute
all test (`make test_all`).
# 2. Running the tests
------------------------------------------------------------------------
## 2.1 Run the tests with `make` (recommended)
After building the `vasp_std`, `vasp_gam`, and `vasp_ncl`
executables (e.g. by means of `make all`), you can test your
build by means of:
make test
(either in `root` or `root/testsuite`).
The above will run a subset of tests from the testsuite (the so-called
`FAST CATEGORY` of tests) that will take roughly 1.5 hours to complete
on 4 cores.
The full testsuite may be executed by means of:
make test_all
The output of the tests (`stdout+stderr`) is written to
`root/testsuite/testsuite.log`.
Tests that fail write an `ERROR` to `root/testsuite/testsuite.log` and
the tests that were not passed successfully will be listed at the end of
this file (and `make` will exit in error).
To clean up after running the testsuite, execute:
make cleantest
in `root/testsuite`.
## 2.2 Configuring the testsuite manually
The testsuite may be manually configured by means of a several
environment variables (with the naming convention: `VASP_TESTSUITE_*`).
* `VASP_TESTSUITE_EXE_STD`:
The command that runs the standard version of VASP.
Default:
VASP_TESTSUITE_EXE_STD="mpirun -np 4 root/bin/vasp_std"
**N.B.**: Specify the absolute path your *standard* executable
(e.g. `vasp_std` or `vasp_gpu`).
* `VASP_TESTSUITE_EXE_GAM`:
The command that runs the gamma-only version of VASP.
Default:
VASP_TESTSUITE_EXE_GAM="mpirun -np 4 root/bin/vasp_gam"
**N.B.**: Specify the absolute path to your *gamma-only* executable
(e.g. `vasp_gam`).
* `VASP_TESTSUITE_EXE_NCL`:
The command that runs the non-collinear version of VASP.
Default:
VASP_TESTSUITE_EXE_NCL="mpirun -np 4 root/bin/vasp_ncl"
**N.B.**: Specify the absolute path to your *non-collinear* executable
(e.g. `vasp_ncl` or `vasp_gpu_ncl`).
* `VASP_TESTSUITE_CUDA`:
Set `VASP_TESTSUITE_CUDA=Y` to exclude all tests that can not
be executed with the CUDA-GPU port of VASP.
Default:
VASP_TESTSUITE_CUDA=
* `VASP_TESTSUITE_INCAR_PREPEND`:
Additional INCAR tags used for every execution of VASP
in the testsuite.
Default:
VASP_TESTSUITE_INCAR_PREPEND=
* `VASP_TESTSUITE_TESTS`:
Selection of tests to be executed.
Default:
VASP_TESTSUITE_TESTS=
**N.B.**: A convenient way to execute a specific test is to set
`VASP_TESTSUITE_TESTS` to a particular test, e.g. by means of:
export VASP_TESTSUITE_TESTS="bulk_GaAs_ACFDT"
and to run `make test` from the `root` or `root/testsuite` directory.
* `VASP_TESTSUITE_SKIP_TESTS`:
Selection of tests to be skipped.
Default:
VASP_TESTSUITE_SKIP_TESTS=
* `VASP_TESTSUITE_POTENTIALS`:
Path to the POTCAR files.
Default:
VASP_TESTSUITE_POTENTIALS=root/testsuite/POTCARS
* #### CATEGORIES:
A variety of environment variables can be set to run or exclude
tests belonging to specific categories.
Default: not set
For instance:
* `VASP_TESTSUITE_SKIP_LREAL`:
Skips all tests that use the real space PAW projection scheme
(LREAL/=F) if set to: `Y`, i.e.,
export VASP_TESTSUITE_SKIP_LREAL=Y
or
* `VASP_TESTSUITE_RUN_LREAL`:
Runs only tests that use the real space PAW projection scheme
(`LREAL=A` or `LREAL=`.TRUE.) if set to: `Y`.
export VASP_TESTSUITE_RUN_LREAL=Y
The following variables may be set to skip categories of tests:
* `VASP_TESTSUITE_SKIP_NOCUDA`:
Skip all tests that can not be excuted with the CUDA-GPU port.
* `VASP_TESTSUITE_SKIP_HYB`:
Skip all hybrid functional tests.
* `VASP_TESTSUITE_SKIP_GAMMA`:
Skip all tests of the gamma-only version.
* `VASP_TESTSUITE_SKIP_NCL`:
Skip all tests of the non-collinear version.
* `VASP_TESTSUITE_SKIP_SOC`:
Skip all tests involving Spin-Orbit Coupling.
* `VASP_TESTSUITE_SKIP_MD`:
Skip all Molecular Dynamics tests.
* `VASP_TESTSUITE_SKIP_TBMD`:
Skip all constrained molecular dynamics tests.
* `VASP_TESTSUITE_SKIP_RPA`:
Skip all tests that involve the Random-Phase Approximation
(GW and ACFDT).
* `VASP_TESTSUITE_SKIP_GW`:
Skip all GW tests.
* `VASP_TESTSUITE_SKIP_ACFDT`:
Skip all ACFDT tests.
* `VASP_TESTSUITE_SKIP_CRPA`:
Skip all tests of the Constrained-RPA.
* `VASP_TESTSUITE_SKIP_BSE`:
Skip all Bethe-Salpeter-Equation tests.
* `VASP_TESTSUITE_SKIP_NOSYM`:
Skip all tests that do not use symmetry.
* `VASP_TESTSUITE_SKIP_LREAL`:
Skip all tests that use the real-space PAW projection scheme.
* `VASP_TESTSUITE_SKIP_LRESP`:
Skip all linear response tests.
* `VASP_TESTSUITE_SKIP_PEAD`:
Skip all tests that use the PEAD method.
* `VASP_TESTSUITE_SKIP_NCORE1`:
Skip all tests that may only be executed with `NCORE=1`.
* `VASP_TESTSUITE_SKIP_WAN90`:
Skip all tests that need to execute `wannier90`.
The following variables may be set to run only tests that belong
to a specific category (or categories):
* `VASP_TESTSUITE_RUN_HYB`
* `VASP_TESTSUITE_RUN_GAMMA`
* `VASP_TESTSUITE_RUN_NCL`
* `VASP_TESTSUITE_RUN_SOC`
* `VASP_TESTSUITE_RUN_MD`
* `VASP_TESTSUITE_RUN_TBMD`
* `VASP_TESTSUITE_RUN_RPA`
* `VASP_TESTSUITE_RUN_GW`
* `VASP_TESTSUITE_RUN_ACFDT`
* `VASP_TESTSUITE_RUN_CRPA`
* `VASP_TESTSUITE_RUN_BSE`
* `VASP_TESTSUITE_RUN_NOSYM`
* `VASP_TESTSUITE_RUN_LREAL`
* `VASP_TESTSUITE_RUN_FAST`
* `VASP_TESTSUITE_RUN_LRESP`
* `VASP_TESTSUITE_RUN_PEAD`
* `VASP_TESTSUITE_RUN_NCORE1`
* `VASP_TESTSUITE_RUN_WAN90`
## 2.2. Directly execute the `runtest` script
Besides by means of `make` the testsuite may be invoked by executing
the `root/testsuite/runtest` script directly.
There are two ways to execute the `runtest` script:
1. Change into the `root/testsuite` directory and run the tests in
the `FAST CATEGORY` by means of:
./runtest -f|--fast
or ALL tests with
./runtest -a|--all
2. Change into `root/testsuite`, adapt one of the example
configuration files in `root/testsuite` and run the testsuite with:
./runtest myconfig.conf
**N.B.I**: To pipe the full output to a file (`testsuite.log`) add
`> testsuite.log 2>&1` to the commands above.
**N.B.II**: On our wiki we maintain a small collection of configuration files:
http://www.vasp.at/wiki/index.php/Validation_tests#Configuration_templates.
**N.B.III**: When you want to run the testsuite by executing the `runtest`
directly you will *first* have to build the `compare_numbertable_new` utility,
by means of:
make numbertable
(in `root/testsuite`).
For each test that fails `runtest` writes an `ERROR` to `stdout` and
the tests that were not passed successfully will be listed at the end of
the run.
In case of a successful run, `runtest` script will exit with error code 0
(indicates successful exit on Unix-based OS), otherwise the error code 1
is returned.
# 3. The output of the tests
------------------------------------------------------------------------
If one runs the tests by means of `make`, as recommended in Sec. 2.1,
all output (`stdout+stderr`) will be written to `root/testsuite/testsuite.log`.
Tests that fail write an `ERROR` to `root/testsuite/testsuite.log` and
the tests that were not passed successfully will be listed at the end of
this file (and `make` will exit in error).
# 4. What if tests fail ...
------------------------------------------------------------------------
Please check our wiki:
http://www.vasp.at/wiki/index.php/Validation_tests#What_if_tests_fail