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 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-dkh2method:hf-1eX2C

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

Useful Links

Our Contacts

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