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 24 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 24 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, and automatically deleted upon successful termination (unless the -k command-line flag is specified). 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 25 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 25 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 26 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. It is shown mainly for illustration purposes, as the work directory is automatically deleted after a successful execution (unless the -k command-line flag is given).

Listing 26 Typical directory tree after a viperleed.calc run.
my_surface/
├── Deltas/
│   ├── Deltas_001.zip
│   └── ...
├── history/
│   ├── t001.r001_<timestamp>/
│   │   └── ...
│   ├── ...
│   └── bookkeeper.log
├── OUT/
│   ├── THEOBEAMS.csv
│   ├── Rfactor_analysis_refcalc.pdf
│   └── ...
├── SUPP/
│   ├── original_inputs/
│   │   └── ...
│   ├── POSCAR_bulk
│   ├── POSCAR_bulk_appended
│   ├── POSCAR_oricell
│   └── ...
├── Tensors/
│   ├── Tensors_001.zip
│   └── ...
├── history.info
├── DISPLACEMENTS        <-- input
├── EXPBEAMS.csv         <-- input
├── IVBEAMS              <-- input, or created by calc
├── PARAMETERS_ori       <-- input for the run that just finished
├── PARAMETERS           <-- output, edited by calc
├── PHASESHIFTS          <-- input, or created by calc
├── POSCAR_ori           <-- input for the run that just finished
├── POSCAR               <-- output, edited by calc
├── POSCAR_user          <-- input of the very first run
├── VIBROCC_ori          <-- input for the run that just finished
├── VIBROCC              <-- output, created or edited by calc
└── viperleed-calc-<timestamp>.log

my_work/                 <-- deleted upon successful termination
├── manifest
└── ...

Information about the progress of the calculation and about errors in the user input are printed to the terminal and recorded in the viperleed-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 SUPP directory collects files POSCAR_bulk, POSCAR_bulk_appended, and POSCAR_oricell, which are helpful to asses the correctness of the detected plane group and bulk structure.

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. At the end of each run, POSCAR_ori contains the same input as given at the beginning of the run (this is identical to POSCAR_user for the very first execution). A copy of the same file can be found in the SUPP/original_inputs/ folder. Instead, the POSCAR file in the root directory at the end of an execution is always the output of that run. Typically, this is the one resulting from a structural optimization. A copy of the same file can be found in the OUT directory. Both files are kept in the root directory at the end of a viperleed.calc execution for easier comparison.

Files PARAMETERS and VIBROCC follow the same convention as POSCAR: *_ori-suffixed files correspond to the inputs given for the viperleed.calc run that just finished (copies are in SUPP/original_inputs/), while those without a suffix are the ouputs of such a run (copies are in OUT). This renaming of files is such that viperleed.calc will automatically use the outputs of a previous execution as inputs for the next one. You can manually invoke the Bookkeeper utility after viperleed.calc if you want a different behavior for a specific run.

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

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.

The results of each viperleed.calc run are automatically collected into the history folder. See the Bookkeeper page for more details on how viperleed.calc results are organized in history. A plain-text history.info file contains a summary of information about each such run. It can be used as an electronic logbook to keep track of which calculations were executed. See this section for more information on the contents of the history.info file.

Tip

It is very good practice to add some comments to the Notes section of each entry that Bookkeeper adds to the history.info file. This allows you to quickly recall what was done without digging through the subfolders of the history directory. Typical notes for a first run include information about which sample, which raw data, and which initial structural model were used for the calculation. Normally, entries for subsequent runs should be complemented with notes concerning why the run was executed, some comments about the outcome, and, potentially, a reasoning about how to proceed further.

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.