How to run and directory organization

In ViPErLEED, each set of calculations for one system must have its own directory. This is because the input and output files have case sensitive, fixed names, see the list of files. A typical approach is to create one such directory for each experimental dataset and each time a new structural model (i.e., POSCAR file) is considered.

Listing 23 shows an example directory tree with the files needed to start a LEED-I(V) calculation in ViPErLEED. See the installation instructions for a guide on how to install ViPErLEED. See also the Examples section for some working calculations to help you get started.

Minimum input

To set up a ViPErLEED calculation, first create a source directory (in this example my_surface) and place all input files inside.

Listing 23 Minimum input directory tree for a reference calculation.
my_surface/
├── IVBEAMS or EXPBEAMS.csv
├── PARAMETERS
└── POSCAR

The minimum information required to start a reference calculation is contained in three files:

To run also a delta amplitudes calculation or a structure search, you additionally need to provide a DISPLACEMENTS file that contains the requested perturbations of the structure.

Note

A domain calculation , that is, with multiple coexisting surface structures, requires a slightly different directory tree. See the domain-calculation section.

Starting the calculation

Once you have set up the input files you are ready to start the calculation. You can start it by invoking viperleed calc via the command line. A list of all available command-line options can be found here.

A typical call may look like this:

tensorleed_path="path/to/tensorleed_dir"
work_path="path/to/work_dir"

viperleed calc -w $work_path -t $tensorleed_path

Tip

As LEED-I(V) calculations can take a long time, it is a good idea to start them in a “detached” manner, for example using nohup or in a tmux session. This way, the calculation will not be aborted if the user logs out (or the connection of an ssh session breaks).

SET tensorleed_path="path\to\tensorleed_dir"
SET work_path="path\to\work_dir"

viperleed calc -w %work_path% -t %tensorleed_path%

The directory at work_path is the one where the calculation will be executed and all temporary files will be stored. It is created if it does not exist. The tensorleed_path is the path to the Tensor-LEED source code. If the -t option is not given, ViPErLEED looks for the TensErLEED source code under the path specified by the VIPERLEED_TENSORLEED environment variable (see also Setting an environment variable).

HPC systems

If you are running ViPErLEED on a high-performance computing (HPC) system with a workload scheduler such as slurm, make sure to load the required compilers, MPI implementations, and Python packages/environment in the submission script (e.g., via module load mpiifort).

Such a submission script usually contains details on the requested hardware (e.g., declared via #SBATCH in slurm) and instructions on which precompiled packages to make available. Listing 24 shows an example for a submission script for the Vienna Scientific Cluster (VSC-4), which uses the slurm workload manager. The script first loads the required Intel compilers and conda distribution, before executing ViPErLEED using the viperleed command.

Listing 24 Example submission script for running viperleed.calc using slurm, as on the Vienna Scientific Cluster.
#!/bin/bash

#SBATCH -J viperleed  # job name
#SBATCH -N 1          # 1 node

#SBATCH --qos=skylake_0096
#SBATCH --partition=skylake_0096

# source .bashrc to initialize conda
source ~/.bashrc
module purge

# load Intel compilers
module load compiler/2022.0.1
module load mkl/2022.0.1
module load mpi/2021.5.0

# load conda
module load miniconda3/4.12.0-intel-2021.5.0-kwofrye

# activate conda environment
conda activate viperleed


# viperleed source code location
tensorleed_path=$DATA/viperleed_tensorleed

# location of the input files
work_path=$DATA/calculations/example/work

echo "Working directory:   $work_path"
echo "ViPErLEED Source:    $tensorleed_path"
echo

viperleed calc -w $work_path -t $tensorleed_path

Directory organization

viperleed.calc executes calculations in a work directory, distinct from the directory containing the input files. The path to such work directory can be specified via the -w command-line option. There are two main reasons for running the calculations in a dedicated directory: (i) viperleed.calc creates a large number of files to handle TensErLEED and its input/output, and (ii) some HPC systems do not allow execution of jobs in the “user space” that typically contains the input files.

Upon starting execution, viperleed.calc copies all the input files into the work directory, runs all requested calculations, and then copies the relevant output files back to the input directory. For this purpose, it also creates a manifest file that lists the files and directories to be copied back.

Listing 25 shows an example of the directory tree after a run. The my_work directory may be on a different file-system path (including a different drive, a network path, or a remote server) or be a subfolder of my_surface.

Listing 25 Typical directory tree after a viperleed.calc run.
my_surface/
├── Deltas/
│   ├── Deltas_001.zip
│   └── ...
├── OUT/
│   ├── THEOBEAMS.csv
│   ├── Rfactor_analysis_refcalc.pdf
│   └── ...
├── SUPP/
│   ├── POSCAR_bulk
│   ├── POSCAR_bulk_appended
│   ├── POSCAR_oricell
│   └── ...
├── Tensors/
│   ├── Tensors_001.zip
│   └── ...
├── workhistory/
│   └── ...
├── calc-<timestamp>.log
├── DISPLACEMENTS        <-- input
├── EXPBEAMS.csv         <-- input
├── IVBEAMS              <-- input, or created by calc
├── PARAMETERS           <-- input, may be edited by calc
├── PHASESHIFTS          <-- input, or created by calc
├── POSCAR               <-- input, may be edited by calc
├── POSCAR_user          <-- input
└── VIBROCC              <-- input, or created by calc

my_work/
├── manifest
└── ...

viperleed.calc will create the additional input files IVBEAMS, PHASESHIFTS, and VIBROCC if not provided by the user; see the respective sections for details.

During the very first run, the original POSCAR file is renamed to POSCAR_user, while the new POSCAR contains the structure as interpreted by viperleed.calc. See the section on the POSCAR file for more details.

Information about the progress of the calculation and about errors in the user input are printed to the terminal and recorded in the calc-<timestamp>.log file. It is always a good idea to check the log file thoroughly for WARNING and ERROR messages.

The OUT directory (created automatically) contains the results of the calculation, see the list of output files for details. viperleed.calc also produces some supplementary files, stored in the SUPP directory. These files contain intermediate results or may be of interest for debugging purposes. For example, the files POSCAR_bulk, POSCAR_bulk_appended and POSCAR_oricell which are helpful to asses the correctness of the detected plane group and bulk structure will be stored in the SUPP directory.

If a refercence calculation is run with Tensor output, a Tensors directory will be created that stores the tensor files. Similarly, if a delta-amplitudes calculation is run, a Deltas directory will be created that contains the resulting delta files.

In case of automated multiple-search runs (which can be specified in the DISPLACEMENTS file), viperleed.calc creates a workhistory directory. It contains one subfolder for each intermediate run, storing input and output files that will be overwritten during subsequent runs.

Note

For multi-domain calculations the input structure will be different, as separate directories are used for the inputs of each domain. See the domain-calculation section for more details.