Updated unified README.md for D7.5

cp2k/README.md

@@ -102,13 +102,83 @@ See the ``PizDaint`` subdirectory for an example arch file that enables GPU acce
 
 
 ## Running the UEABS benchmarks
+**The exact input files used to generate the results presented in deliverable D7.5 are included in machine-specific subdirectories accompanying this README**
 
+After building the hybrid MPI+OpenMP version of CP2K you have an executable ending in `.psmp`. The general way to run the benchmarks with the hybrid parallel executable is, e.g. for 2 threads per rank:
 
-### Test Case A: H2O-1024
+```
+export OMP_NUM_THREADS=2
+parallel_launcher launcher_options path_to_cp2k.psmp -i inputfile -o logfile
+```
+
+Where:
+
+- The parallel_launcher is mpirun, mpiexec, or some variant such as aprun on Cray systems or srun when using Slurm. 
 
+- launcher\_options specifies parallel placement in terms of total numbers of nodes, MPI ranks/tasks, tasks per node, and OpenMP threads per task (which should be equal to the value given to OMP\_NUM\_THREADS). This is not necessary if parallel runtime options are picked up by the launcher from the job environment.
+
+You can try any combination of tasks per node and OpenMP threads per task to investigate absolute performance and scaling on the machine of interest. 
+
+### Test Case A: H2O-512
+
+Test Case A is the H2O-512 benchmark included in the CP2K distribution (in ``/tests/QS/benchmark/``) and consists of ab-initio molecular dynamics simulation of 512 liquid water molecules using the Born-Oppenheimer approach via Quickstep DFT. 
 
 ### Test Case B: LiH-HFX
 
+Test Case B is the LiH-HFX benchmark included in the CP2K distribution (in ``/tests/QS/benchmark_HFX/LiH``) and consists of a DFT energy calculation for a 216 atom LiH crystal. 
+
+Provided input files include:
+
+- ``input_bulk_HFX_3.inp``: input for the actual benchmark HFX run
+- ``input_bulk_B88_3.inp``: needed to generate an initial wave function (wfn file) for the HFX run - this should be run once before running the actual HFX benchmark
+
+After the B88 run has been performed once, you should rename the resulting wavefunction file for use in the HFX benchmark runs as follows:
+
+```
+cp LiH_bulk_3-RESTART.wfn B88.wfn
+```
+
+#### Notes
+The amount of memory available per MPI process must be altered according to the number of MPI processes being used. If this is not done the benchmark will crash with an out of memory (OOM) error. The input file keyword ``MAX_MEMORY`` in ``input_bulk_HFX_3.inp`` needs to be changed as follows:  
+
+```
+MAX_MEMORY 14000
+```  
+
+should be changed to  
+
+```
+MAX_MEMORY new_value
+```  
+
+The new value of ``MAX_MEMORY`` is chosen by dividing the total amount of memory available on a node by the number of MPI processes being used per node. 
+
+If a shorter runtime is desirable, the following line in ``input_bulk_HFX_3.inp``:  
+
+```
+MAX_SCF 20
+```  
+
+may be changed to  
+
+```
+MAX_SCF 1
+```  
+
+in order to reduce the maximum number of SCF cycles and hence the execution time. 
+
+If the runtime or required memory needs to be reduced so the benchmark can run on a smaller number of nodes, the OPT1 basis set can be used instead of the default OPT2. To this end, the line  
+
+```
+BASIS_SET OPT2
+```  
+
+in ``input_bulk_B88_3.inp`` and in ``input_bulk_HFX_3.inp`` should be changed to  
+  
+```
+BASIS_SET OPT1
+```  
 
 ### Test Case C: H2O-DFT-LS
 
+Test Case C is the H2O-DFT-LS benchmark included in the CP2K distribution (in ``tests/QS/benchmark_DM_LS``) and consists of a single-point energy calculation using linear-scaling DFT of 2048 water molecules.