In the following, we use silicon as an example to demonstrate the features of PERTURBO (see the directory “example02-silicon-perturbo/perturbo”). To run perturbo.x one first needs to generate the file ‘prefix’_epr.h5 (in this case, si_epr.h5), which is prepared using qe2pert.x as we discuss in this section. The file si_epr.h5 is inside the directory “example02-silicon-perturbo/qe2pert”. We also provide reference output results in the directory “References”.

Calculation modes

Each PERTURBO feature corresponds to a separate run of perturbo.x, called a calculation mode. For each calculation mode, at least two files must be always presented in the run folder: 1) ‘prefix’_epr.h5 and 2) input file (usually called pert.in). Different calculation modes require some additional input files. The parameters specified in the input file pert.in depend on the calculation mode. The main input parameter controlling the calculation mode is calc_mode. Here is a brief summary of the calc_mode options, and the corresponding tasks carried out by PERTURBO:

  • 'bands': interpolate electronic band structures using Wannier functions.
  • 'phdisp': interpolate phonon dispersion by Fourier transforming real-space interatomic force constants.
  • 'ephmat': interpolate e-ph matrix elements using Wannier functions.
  • 'setup': setup for transport calculations or carrier dynamics simulations.
  • 'imsigma': compute the e-ph self-energy for electronic crystal momenta read from a list.
  • 'meanfp': compute the e-ph mean free path, also output the corresponding band velocity and relaxation time.
  • 'trans': compute electrical conductivity for metals, semiconductors, and insulators, or carrier mobility for semiconductors, using either the state-dependent RTA approach or the iterative approach of the BTE.
  • 'trans-pp': postprocessing of the ‘trans’ calculation, compute the Seebeck coefficient.
  • 'dynamics-run': ultrafast hot carrier dynamics via the time-dependent Boltzmann transport equation.
  • 'dynamics-pp': postprocessing of the ‘dynamics-run’ calculation, compute the BZ-averaged energy-dependent carrier population.

The next sections of the tutorial are dedicated to the detailed description of each calculation mode. For a brief overview, a list of the required input files, and an example input file for each calculation mode, please refer to the Interactive workflow page.

Output files

The data computed in a Perturbo calculation are outputted to the following files:

  • YAML files: store the inputs and outputs of the calculation
  • HDF5 files: store results of the calculation that are too large to be stored in a YAML file
  • ASCII text files (legacy): store the same data as in the YAML files, but in an outdated format - not recommended

The format of the output files (YAML file, HDF5 files, and ASCII text files) are specific to each calc_mode and can be found in the corresponding tutorial.

The data computed in any Perturbo calculation are outputted to a YAML file. YAML is a human-friendly data serialization language compatible with several programming languages, including Python, Julia, and C++. Input parameter output_yaml controls whether data is outputted to the YAML file (default true), and input parameter yaml_fname controls the name of the YAML file (default ‘prefix’_‘calc_mode’.yml). Additionally, data that are too large to be appropriately stored in a YAML file are stored in HDF5 files, which can be processed in high-level languages such as Python or Julia.

We provide Perturbopy, a Python package that can read Perturbo output YAML files (and, if needed, the HDF5 files) and postprocess the data. We recommend using Perturbopy after running a Perturbo calculation to export, visualize, and analyze the data.

While we recommend processing output data using the YAML files, Perturbo also outputs the data to plain ASCII text files. All of the information in these ASCII files is also given in the YAML and HDF5 files. The ASCII files are retained primarily for legacy purposes. The names and descriptions of these ASCII files depend on the calc_mode and can be found under the relevant tutorials wherever the following symbol is seen:

ASCII Icon Click to show ASCII text outputs of this calculation
In these sections throughout the tutorials, find descriptions of the ASCII files that provide the same output data as in the YAML files, but in an alternate format.


YAML file structure

The exact structure of the Perturbo YAML file depends on the calc_mode and can be found in the respective tutorials. However, all of the calculation modes share several common fields, which we describe below.

---
program: perturbo

start date and time:
   date: 15 August 2023
   time: " 8:28:46"

parallelization:
   type: MPI+OpenMP
   number of MPI tasks:  12
   number of OpenMP threads:  16
   number of nodes:   3

input parameters:
   after conversion:
      band_max:                   6
      band_min:                   5
	  ......
      yaml_fname:          pert_output.yml


basic data:
   alat:          10.2640000000
   alat units:       bohr
   ......

imsigma:
   ......

timings:

   time units: s

   PERTURBO:
      cpu:      3230.61073300
      wall:      208.71964002
      calls:         1

   init_eph_wan:
      ......

   calc_selfel:
      ......
...
  • The program field specifies the program being executed, either perturbo or qe2pert (in this case, perturbo).
  • The start date and time field provides information on the date and time at which the program was initiated.
  • The parallelization section provides information on the MPI and OpenMP parallelization and the number of nodes on which the program was executed.
  • The input parameters section lists all of the input parameters. Note that these parameters are listed under a section entitled after conversion, which indicates that they are presented in Rydberg atomic units (regardless of the units in the pert.in file)
  • The section labeled basic data describes material properties stored in the ‘prefix’_epr.h5 file from the qe2pert.x step, described here.
  • Next, there are section(s) specific to the particular calc_mode being run. Here, since we are running an 'imsigma' calculation, this section is entitled imsigma. More details on these sections can be found in their respective tutorials.
  • Finally, the section labeled timings describes the CPU time, wall time, and number of calls to various subroutines and the full Perturbo calculation. The relevant subroutines are also calc_mode dependent.