To perform the self-consistent field (SCF) calculation in ReSpect is as easy as executing the command

/path/to/ReSpect/respect --scf --inp=my-input-file --scratch=/path/to/scratch/directory

from a directory containing my-input-file.inp. There are three mandatory arguments to SCF

• --scf
  which invokes the SCF procedure;

• --scratch
  which specifies the path to a scratch directory;

• --inp
  which specifies the name of an input file.

To control the SCF procedure, my-input-file.inp should contain an input block scf: with some SCF-specific keywords. A comprehensive list of the keywords can be found here. A simple example of my-input-file.inp is

#1c DFT calculation of SeH2 molecule, employing the
#scalar-relativistic DKH2 Hamiltonian and PBE functional

scf:

     method: ks-dkh2/pbe

     geometry:
          Se    0.000000000   -0.000008000   -0.077624000
          H     0.000000000    1.049076000    0.961901000
          H     0.000000000   -1.048465000    0.962534000

     basis:
            H:  upc-1
            Se: ucc-pvdz

     charge:        0
     multiplicity:  1
     maxiterations: 30
     convergence:   1.0e-5

There are several important and worth-to-remember aspects associated with the input syntax, namely

• the input is case-insensitive
  This means that the program does not distinguish between uppercase and lowercase letters.

• the input is insensitive to the number of blank lines and/or comment lines
  All comments begin with the number sign (#), can start anywhere on a line and continue until the end of the line.

• the input is compliant with the dictionary syntax of the YAML markup language
  This means that each input line is represented either by a single block: statement or by a simple keyword:value pair, such as

block1:
    keyword1: value1 
    keyword2: value2  
    ...
    block2: 
      keyword3: value3
      keyword4: value4
      ...
    block3: 
           keyword5: value5
           keyword6: value6
           ...

It is essential to remember that all members of one block: are lines beginning at the same indentation level. Whitespace indentation is used to denote the block structure; however, tab characters are never allowed as indentation. The only exception to the YAML-based input syntax is the block geometry: which utilizes a simple xyz format for the molecular geometry specification.

Q: Is there a way to launch SCF calculations without the need to explicitly setup the scratch path by "--scratch=/path/to/scratch/directory"?

Yes, the argument "--scratch=/path/to/scratch/directory" can be saved to the file .respectrc in your home directory. If both the file and the command line argument exist, then ReSpect takes the scratch directory setting from the command line.

Q: How to set the number of processors for parallel SCF calculations?

For OpenMP parallel calculations, the number of processors can be controlled from the command line by the argument --nt=N, where N ideally refers to the total number of physical cores of a machine. Thus, the command line for launching an OpenMP parallel SCF job reads

/path/to/ReSpect/respect --nt=N --scf --inp=my-input-file

Note, however, we have assumed here that the scratch path is setup through the file .respectrc (see the previous discussion).

Q: How to restart an SCF calculation?

ReSpect offers a rather flexible framework for restarting SCF as it allows restarting between various Hamiltonians and/or different basis sets. SCF calculations can be restarted simply by creating the symbolic link to the data file of the previous job

ln -sf my-old-job.50 my-new-job.50

and by adding an extra argument --restart to the command line when restarting new job

/path/to/ReSpect/respect --restart --scf --inp=my-new-job

However, some caution is needed here as the restart process rewrites all the previous SCF data, both in the output file (my-new-job.out_scf) as well as in the checkpoint file (my-new-job.50). If needed, make a backup of these files prior to the restart.

Q: Is it possible to recover an SCF job from a scratch directory?

If the ReSpect job for any reason fails and the scratch directory is still accessible, it is possible to recover the failed calculation. After running the command

/path/to/ReSpect/respect --recover-job=/path/to/scratch/directory

file respect_checkpoint_file.50 will be created in the current directory. Using this file, you can now restart the SCF calculation as described in the tip How to restart an SCF calculation?.

Q: How to improve the SCF convergence and/or reduce the number of SCF iterations in relativistic two-component (2c) and four-component (4c) calculations?

One easy way to improve the SCF convergence and/or reduce the number of SCF iterations in relativistic 2c and 4c calculations is to provide a good initial guess to molecular orbitals/spinors. Here, we recommend to perform two consecutive SCFs; the first one serves as a quick and reliable initial guess and is typically performed with a one-component scalar-relativistic DKH2 Hamiltonian, while the second SCF, restarted from the first one, can proceed with a desired 2c or 4c Hamiltonian and normally exhibits a rapid convergence.

In practice, DKH2 Hamiltonian is selected on input by the keyword method:hf-dkh2 for Hartree-Fock calculations and by the keyword method:ks-dkh2/dft-functional for Kohn-Sham DFT calculations. The restart process itself requires just to replace the DKH2 Hamiltonian either by the 2c X2C Hamiltonian

• method:hf-dkh2 → method:hf-1eX2C

• method:ks-dkh2/dft-functional → method:ks-1eX2C/dft-functional

or by the 4c Dirac—Coulomb Hamiltonian

• method:hf-dkh2 → method:mdhf

• method:ks-dkh2/dft-functional → method:mdks/dft-functional

and to relaunch the SCF procedure with the additional argument --restart in the command line

/path/to/ReSpect/respect --restart --scf --inp=my-input-file