SCF Tutorial

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


     method: ks-dkh2/pbe

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

            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  
          keyword3: value3
          keyword4: value4
               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 the file and the argument exist, then ReSpect takes the scratch directory setting from the file.

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 a 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 be adding an extra argument --restart to the command line

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

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

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

One easy way to reduce the number of SCF iterations in relativistic 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-dkh2method:hf-nucX2C

  • method:ks-dkh2/dft-functionalmethod:ks-nucX2C/dft-functional

or by the 4c Dirac—Coulomb Hamiltonian

  • method:hf-dkh2method:mdhf

  • method:ks-dkh2/dft-functionalmethod: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

Latest Posts

Our Contacts

Hylleraas Centre
Department of Chemistry
UiT The Arctic University of Norway
Tromsø, NO-9037 Norway