1  Description of the command structure

- a label
- a label followed by a character, integer and/or fix-point or
- a character, integer and/or fix-point constant.

- labels can be in upper or lower case,
- compulsory labels, i.e. these that must be included in the input command file, are marked "·" and the optional ones "°",
- the compulsory labels must follow the order given below; the optional ones can be inserted anywhere between title and stop labels,
- optional parameters are enclosed in square brackets,
- r denotes a fix-point constant, i - an integer, c - a string of characters,
- exclamation mark placed anywhere in an input line starts a comment; what follows "!" is ignored.

• TITLE

  Format:

  title
        c
  c is any string of up to 80 characters describing the current case. This string is used as a header of disk output files containing orbitals and potentials.
• METHOD

  Format:

  method c
  Select the type of calculation.

  
  c: HF - Hartree-Fock method
  c: HFS - Hartree-Fock-Slater method
  c: OED - One Electron Diatomic states
• NUCLEI

  Format:

  nuclei Z_A     Z_B    R     [  c  ]
  Set the nuclei charges and the bond length.

  
  Z_A: nuclear charge of centre A (integer)
  Z_B: nuclear charge of centre B (integer)
  R: bond length (real)
  c: angstrom - the internuclear separation can be given in angstrom units if this string is included (the conversion factor 0.529177249 is used)

  If |Z_A-Z_B| < 10^-6 then the molecule is considered to be a homonuclear one (this threshold can be changed by redefining HOMOLEVL variable in blk_data.inc.raw).

  
  ° HOMO

  Format:

  homo
  This label is used to impose explicitly D_¥ h symmetry upon orbitals of homonuclear molecules in order to improve scf/sor convergence.

  
  ° BREAK

  Format:

  break
  When this label is present homonuclear molecules are calculated in C_¥ v symmetry and the D_¥ h symmetry labels (u or g) are superfluous (see below).
• CONFIG

  Format:

  config i

  
  i: the total charge of a system

  The following cards define molecular orbitals and their occupation. Note that the last orbital description card must contain an extra label end.
  The possible formats are:

  Format:

  i      c

  
  i: number of fully occupied orbitals of a given irreducible representation (irrep) of the C_¥ v group; 2 electrons make s orbitals fully occupied and 4 electrons are needed for filling the orbitals belonging to the other irreps
  c: symbol of the C_¥ v irrep to which the orbitals belong (sigma, pi, delta or phi)

  Format:

  i      c₁     c₂

  
  i: number of fully occupied orbitals of a given irrep of the D_¥ h group
  c₁: symbol of the C_¥ v irrep to which the orbitals belong (sigma, pi, delta or phi)
  c₂: symbol for the inversion symmetry of the D_¥ h irreps (u or g)

  Use this format for a homonuclear molecule unless break command is included.

  Format:

  i      c₁    c₂    [c₃    [  c₄    [  c₅  ]  ]  ]

  
  i: number of orbitals of a given irrep of the C_¥ v group
  c₁: symbol for the C_¥ v irreps to which the orbitals belong (sigma, pi, delta, phi)
  c₂-c₅: +,  - or . (a dot); +/- denotes spin up/down electron and . denotes an unoccupied spin orbital

  Format:

  i      c₁    c₂    c₃    [  c₄    [  c₅    [  c₆  ]  ]  ]

  
  i: number of orbitals of a given irrep of the D_¥ h group
  c₁: symbol for the C_¥ v irrep to which the orbitals belong (sigma, pi, delta, phi)
  c₂: symbol for the inversion symmetry of the D_¥ h irrep (u or g)
  c₃-c₆: +,  - or . (a dot); +/- denotes spin up/down electron and . denotes an unoccupied spin orbital

  
  ° GRID
  Two possible formats are (the second one is retained for the backward compatibility):

  Format:

  grid n_n R_¥
  An integer and a real define a single 2d grid.

  
  n_n: the number of grid points in n variable
  R_¥: the practical infinity

  n_m is calculated so as to make the step size in m variable equal to the stepsize in n variable. n_n and n_m have to meet special conditions. If the conditions are not fulfilled the nearest (but smaller) appropriate values are used.

  Format:

  grid n_n n_m R_¥
  Two integers and one real define a single 2d grid.

  
  n_n: the number of grid points in n variable
  n_m: the number of grid points in m variable
  R_¥: the practical infinity

  n_n and n_m have to meet special conditions. If the conditions are not fulfilled the nearest (but smaller) appropriate values are used.

  
  ° SUBGRID

  Format:

  subgrid n_grids
                   n_n n_m⁽¹⁾   [  n_m⁽²⁾    [  n_m⁽³⁾  ]  ]
                   h_m⁽¹⁾   [  s⁽²⁾[  s⁽³⁾ ]  ]
  Define up to 3 subgrids.

  
  n_grids: number of subgrids (integer)
  n_n: the number of grid points in n variable (integer)
  n_m⁽¹⁾¼n_m⁽³⁾: number of points in the m direction for each of the subgrids (integers)
  h_m⁽¹⁾: the step size in m variable for the first subgrid (real)
  s⁽²⁾ s⁽³⁾: step sizes (reals) for other subgrids are defined as h_m⁽²⁾=s⁽²⁾ h_m⁽¹⁾, h_m⁽³⁾=s⁽³⁾ h_m⁽¹⁾

  Note that either GRID of SUBGRID label must be included in the input command file.
  ° INTERP

  Format:

  interp
  Use this label to change the grid between separate runs of the program. The restriction is that only a number of grid points in one of the variables or R_¥ can be changed at a time.
• INITIAL

  Format:

  initial i₁    i₂  [  i₃  ]

  
  i₁: determine the initial source of orbitals and potentials:
  • i₁=1 - molecular orbitals are formed as a linear combination of hydrogenic functions on centres A and B; in the case of HF or HFS calculations Coulomb (exchange) potentials are approximated as a linear combination of Thomas-Fermi (1/r) potentials at the two centres; if method OED is chosen the potential function is approximated as a linear combination of Z_A/r₁ and Z_B/r₂ terms and the exchange potentials are set to zero
  • i₁=2 - GAUSSIAN94 output is used to retrieve exponents and expansion coefficients of (uncontracted) molecular orbitals (it is assumed that the output is contained in gauss94.out and gauss94.pun files) and Coulomb and exchange potentials are initialized as in i₁=1 case; see routine PREPG94 for more details
  • i₁=3 - GAUSSIAN94 modified output is used to retrieve exponents and expansion coefficients of molecular orbitals (it is assumed that the output is contained in gauss94l.out file) and Coulomb and exchange potentials are initialized as in i₁=1 case; see routine PREPG94L for details
  • i₁=5 - initial orbitals and potentials are retrieved from disk files created in a previous run
  • i₁=6 - orbitals and Coulomb potentials are retrieved from disk files and exchange potentials are initialized as in i₁=1 case (convenient when going from HFS to HF calculations)
  
  i₂: specifies how exchange potentials will be read/written and manipulated (stored in memory). The program always keeps all orbitals and Coulomb potentials in core. The exchange potentials can also be all kept in core (if there is enough memory). However, during a relaxation of a particular orbital only a fraction of them is in fact needed. Thus all exchange potentials can be kept on disk as separate files (named fort.31, fort.32, ... during a run) and only relevant ones are being retrieved when necessary.¹
  • i₂=0 - read exchange potentials as separate files and write them back as separate files
  • i₂=1 - read all exchange potentials in a file but write them out as separate files
  • i₂=2 - read all exchange potentials separately but write them out as a single file
  • i₂=3 - read and write exchange potentials in the form of a single file
  
  i₃: if i₁=1 then this parameter must be set to 1 or 2. In such a case the initialization of each of the orbitals has to be defined in terms of the linear combination of atom centered hydrogen-like functions. For each orbital include a card of the following format (the order of orbitals should match the order specified under the config label):

  Format:

  c_A    n_A     l_A     z_A         c_B    n_B    l_B     z_B        i₁        [  i₂  ]
  where

  
  c_A - mixing coefficient for a hydrogenic orbital on the Z_A centre (real),
  n_A - its principle quantum number (integer)
  l_A - its orbital quantum number (integer)
  z_A - the effective nuclear charge if i₃=1 or a screening parameter if i₃=2 (real)
  c_B - mixing coefficient for a hydrogenic orbital on the Z_B centre (real),
  n_B - its principle quantum number (integer)
  l_B - its orbital quantum number (integer)
  z_B - the effective nuclear charge if i₃=1 or a screening parameter if i₃=2 (real)
  i₁ - set to 1 to freeze the orbital during scf; otherwise set to 0 (integer)
  i₂ - a number of successive over-relaxations for a given orbital (integer); if omitted is set to 10

  
  ° FEFIELD

  Format:

  fefield r

  
  r: a strength of an external static electric field directed along the internuclear axis (in atomic units)

  
  ° MULTIPOL

  Format:

  multipol r

  
  r: if r > 0 multipole moment expansion coefficients are recalculated when the maximum error in orbital energy is reduced by r (the default value is 1.15). To suppress recalculation of the coefficients set r to a negative real number. This is useful when generating potentials from a set of fixed orbitals, e.g from GAUSSIAN94 orbitals.

  
  ° SCF

  Format:

  scf [  i₁  [  i₂  [  i₃  [  i₄  [i₅]  ]  ]  ]  ]

  
  i₁: maximum number of scf iterations (default 1000); to skip the scf step set i₁ to a negative integer,
  i₂: every i₂ scf iterations orbitals and potentials are saved on disk (default 100). If i₂=0 functions are saved on disk upon completion of the scf process. If i₂ < 0 functions are never written to disk,
  i₃: if the maximum error in orbital energy is less than 10^-i₃ than the scf process is terminated (the default value is 10),
  i₄: if the maximum error in orbital norm is less than 10^-i₄ than scf process is terminated (the default is 10),
  i₅: the level of output during scf process
  • i₅=1 - the orbital convergence rate, orbital energy and normalization of every orbital is printed in every scf iteration
  • i₅=2 - the orbital convergence rate, orbital energy and normalization of the worst converged orbital is printed in every scf iteration (default)
  • i₅=3 - the orbital convergence rate, orbital energy and normalization of the worst converged orbital is printed every i₂ iterations. Printing of "... multipole moment expansion coefficients (re)calculated ..." communique is suppressed

  Total energy is printed every i₂ iterations.

  
  ° FIX

  Format:

  fix [  i₁  [  i₂  [  i₃  ]  ]  ]
  If i₁, i₂ or i₃ are set to 1 then orbitals, Coulomb potentials or exchange potentials, respectively, are kept frozen during the scf/sor process (the respective default values are 0, 0 and 2). If i₃=2 then exchange potentials are relaxed only once during an scf cycle. i₂ and i₃ cannot be set to 1 if hydrogenic orbitals are used to initiate the orbitals.

  
  ° CONV

  Format:

  conv [  i₁  [  i₂  [  i₃  ]  ]  ]
  Sometimes the convergence threshold (for energy and/or normalization) is set too low and cannot be satisfied on a given grid and as a result the SCF/SOR process continues in vain. The iterations are stopped if orbital energies or orbital norms display no improvment over a given number of i₂ and i₃ most recent iterations, respectively (the default values are set to 20). The monitoring begins after i₁ initial iterations (default 250).

  
  ° XALPHA

  Format:

  xalpha alpha
  If this label is present the Slater exchange approximation, i.e. V_x=-³/₂a([3/(p)] r)^1/3, is used and the parameter a can be modified. This approximation is useful to quickly improve the initial HF orbitals. a is a real number and 0.7 is its default value.

  
  ° SOR

  Format:

  sor [  i₁  [  i₂  [  i₃  ]  ]  ]
  Change default values of sor parameters.

  
  i₁: the number of (MC)SOR iterations (over each subgrid) for a given function being relaxed in a single SCF cycle (the default value is 10)
  i₂: a scaling factor used to change i₁ when relaxing potentials (see RELCOUL1/2 and RELEXCH1/2). The new value of (MC)SOR iterations is calculalated as i₁/i₂; the default value of i₂ is 1.
  i₃: if i₁=1 (2) SOR (MCSOR) method is used to solve Poisson equations for orbitals and potentials (the default value is 1); if i₁=3 SOR method is used to solve Poisson equations for orbitals and MCSOR - for potentials
• OMEGA

  Format:

  omega
         w_orb⁽¹⁾  [  w_orb⁽²⁾   [  w_orb⁽³⁾  ]  ]
         w_pot⁽¹⁾  [  w_pot⁽²⁾   [  w_pot⁽³⁾  ]  ]
  Up to three real numbers in each line setting over-relaxation parameter w for relaxation of orbitals and potentials for each subgrid. If the second or the third parameter is omitted, the value for the first subgrid is used.

  Note that a semiempirical formula can be used to calculate a near-optimal value of w_pot by specifying w_pot⁽¹⁾ as a negative real number.

  
  ° ORDER

  Format:

  order [  i₁  [  i₂  [  i₃  ]  ]  ]
  Up to three integers defining the ordering of mesh points on subgrids.

  
  i_k=1: natural ordering
  i_k=2: 'middle' type of sweep (the default)

  
  ° FERMI

  Format:

  fermi r_A r_B
  When this label is present, the Fermi nuclear charge distribution is used. Optional parameters r_A and r_B define the atomic masses (in amu) of nuclei A and B. If omitted the corresponding values from the table of atomic masses are taken (see blk_data).

  
  ° GAUSS

  Format:

  gauss r_A r_B
  When this label is present, the Gauss nuclear charge distribution is used. Optional parameters r_A and r_B define the atomic masses (in amu) of nuclei A and B. If omitted the corresponding values from the table of atomic masses are taken (see blk_data).

  
  ° DEBUG

  Format:

  debug i₁¼i₂₀
  Up to 20 different debug flags can be set at a time. If the integer i_k is encountered the debug flag i_k is set, i.e. idbg(i_k)=1    (1 £ i_k < 600).
• STOP

  Format:

  stop
  This label indicates the end of input data.

2  Examples of input command cards

1. ²S ground state of the Th⁺⁸⁹ one-electron system.

   TITLE   
        Th+89  point/finite  nucleus R = 2.5  
   METHOD OED
   NUCLEI  90.0 0.0  2.0
   CONFIG 89
     1 sigma +  end
   GRID 169 193  2.5 
   INITIAL  1 3 1
    1.0 1 0 90.0   0.0   1 0  1.0  0 
   SCF  30 10 8
   omega
    1.80  
    1.80  
   ! fermi 232.0 0.0
   STOP
   
   
2. First excited ²S state of the Th⁺⁸⁹ one-electron system.

   TITLE   
        Th+89  point/finite  nucleus R = 2.5  
   METHOD OED
   NUCLEI  90.0 0.0  2.0
   CONFIG 88
     1 sigma +
     1 sigma +  end
   GRID 169 193  2.5 
   INITIAL  5 3 1
    1.0 2 0 90.0   0.0   1 0  1.0  0 
    1.0 1 0 90.0   0.0   1 0  1.0  1 ! 1s orbital must be kept frozen
   SCF  30 10 8 
   omega
    1.80  
    1.80  
   !fermi 232.0 0.0
   STOP
   
   
3. Hartree-Fock ground state of the beryllium atom.

   TITLE 
      Be R_inf=35.0 bohr  R = 2.3860 bohr
   METHOD  hf ! or METHOD HFS
   NUCLEI  4.0  0.0  2.386  
   CONFIG  0
           2 sigma  end
   GRID   91 35.0  
   grid 169 35.0   
   INITIAL  1 3 1 
    1.0   2 0 4.0     0.0   1 0 9.0  0  
    1.0   1 0 4.0     0.0   1 0 9.0  0  
   SCF 3000 10 12 12 1
   ! note that omega for potentials is set automatically
   conv 150 150 
   omega 
     1.92
    -1.87
   stop
   
   
4. Hartree-Fock ground state energy of the hydrogen molecule.

   title   
     H2: [169x193;35]  R = 1.4au  
   method hf
   !nuclei  1.0 1.0  1.4
   nuclei  1.0 1.0  2.0
   !homo
   !break 
   config 0
     1 sigma g end
   !grid 169 193  35.0 
   grid 169  40.0 
   initial  1 3 1
    1.0 1 0 1.0   1.0   1 0  1.0  0 
   scf  1000 10 16 16 
   omega
     1.95  
    -1.87 
   stop
   
   
5. Hartree-Fock ground state of the BF molecule.

   TITLE 
      BF: R = 2.386 bohr  
   METHOD HF
   NUCLEI  5.0  9.0  2.386    
   CONFIG  0
    1 pi       
    5 sigma     end
   ! initial orbitals are taken from GAUSSIAN94 output (see bf.inp)
   ! bf_g94.out and bf_g94.pun files must be copied into a working
   ! directory as gauss94.out and gauss94.pun files, respectively
   INITIAL  2 3   
   GRID 169 35.0 
   SCF 200 20 8 
   omega 
    1.85  
    1.97
   multipol -1
   fix 1 0 2        ! orbitals are not relaxed   
   STOP
   
   
6. HF calculations for the lowest ³P state of the carbon atom.

   TITLE 
    3P C   R = 2.386  
   METHOD HF
   NUCLEI  6.0  0.0  2.386    
   CONFIG  0
    1 pi   + . + 
    1 sigma 
    1 sigma   end
   GRID    169 30.0  
   INITIAL   1 3 1 
    1.0   2 1 5.0     0.0   1 0 9.0   0 
    1.0   2 0 6.0     0.0   1 0 9.0   0  
    1.0   1 0 6.0     0.0   1 0 9.0   0 
   SCF 400 20 12 12 
   omega 
    1.80
    1.87   
   STOP
   
   
7. HF calculations for the lowest ²P state of the C⁺ ion.

   TITLE 
    1P C+   R = 2.386  
   METHOD HF
   NUCLEI  6.0  0.0  2.386    
   CONFIG  1
    1 pi   +
    1 sigma 
    1 sigma   end
   GRID   169 30.0  
   INITIAL   1 3 1 ! or INITIAL  5 3 1 and using 3P results
    1.0   2 1 5.0     0.0   1 0 9.0   0 
    1.0   2 0 6.0     0.0   1 0 9.0   0  
    1.0   1 0 6.0     0.0   1 0 9.0   0 
   SCF 500 20 7 
   omega 
    1.82 
    1.87   
   STOP
   
   
8. HF calculations for the lowest state of the C₂ molecule.

   TITLE 
     C2     R = 2.358 
   METHOD HF
   NUCLEI  6.0 6.0 2.358 
   homo
   !break
   CONFIG  0
    1 pi    u 
    1 sigma u
    1 sigma g
    1 sigma u 
    1 sigma g end
   GRID  169 193 40.0 
   INITIAL   2 3 0
   ! just a couple of dozen iterations to start with
   SCF 50 10 10 10 1
   ! note the small value of overrelaxation parameter for orbitals
   ! often initial scf/sor iterations have to be require slower
   ! convergence rates
   omega 
    1.25
    1.85
   STOP
   
   

   
   
   

   TITLE 
     C2     R = 2.358 
   METHOD HF
   NUCLEI  6.0 6.0 2.358 
   homo
   !break
   CONFIG  0
    1 pi    u 
    1 sigma u
    1 sigma g
    1 sigma u 
    1 sigma g end
   GRID  169 193 40.0 
   INITIAL   5 3 0
   SCF 500 10 10 10 1
   ! the overrelaxation parameter for potentials is at its more or less
   ! optimal value
   omega 
    1.75
    1.85
   STOP
   
   
9. HF calculations for the lowest state of the N₂ molecule.

   TITLE 
       N2     R = 2.068       
   METHOD HF
   NUCLEI  7.0 7.0 2.068
   homo
   CONFIG  0
    1 pi    u 
    1 sigma g 
    1 sigma u
    2 sigma g 
    1 sigma u end
   GRID  169 193 40.0  
   INITIAL   1 3 1
    0.5   2 1 5.0     0.5   2 1 5.0   0
    1.5   2 1 5.0     0.0   2 1 5.0   0
    0.5   2 0 7.0    -0.5   2 0 7.0   0
    0.5   2 0 7.0     0.5   2 0 7.0   0 
    0.5   1 0 7.0     0.5   1 0 7.0   0
    0.5   1 0 7.0    -0.5   1 0 7.0   0  
   SCF 2000 10 10 10 2
   omega 
    1.65
    1.85   
   STOP
   
   
10. HF calculations for the lowest state of the F₂ molecule.

    TITLE 
     F2     R = 2.668  (1.4118449A)
    METHOD HF
    NUCLEI  7.0 7.0 2.668
    homo
    !break
    CONFIG  0
     1 pi    u
     1 sigma g 
     1 sigma u
     1 sigma g
     1 sigma u 
     1 sigma g end
    GRID  169 193 40.0  
    INITIAL   2 3 
    SCF 100 10 10 10
    omega 
     1.75
     1.75   
    STOP
    
    

3  Description of the data file structure of the program

2dhf_output.orb containing molecular orbitals (in the order specified by the input data following config label) followed by their normalization factors, orbital energies, Lagrange multipliers and multipole moment expansion coefficients (see WTDISK for more details),

2dhf_output.coul containing corresponding Coulomb potentials and

2dhf_output.exch containing all exchange potentials if i₂ parameter on initial card is 2 or 3 or

fort.31, fort.32, ... if i₂ is 0 or 1 where each file contains the exchange potential for a particular pair of orbitals.

4  How to run the program?

xhf c₁  [  c₂   [  c₃  ]  ]

• c₁ is either
  • the prefix of a command data file which name is of the form c₁.data,
  • rename to change the names of temporary files with 2dhf_input/2dhf_output prefixes into the corresponding names with prefixes specified by c₂ and/or c₃ strings. This is useful when the command xhf is aborted and files with 2dhf_input/2dhf_output prefixes are left. It is thus recommended that the process x2dhf itself should be killed, if necessary, not xhf itself.
  • remove to remove all temporary files.
• c₂ is either
  • the prefix of names of output files produced by the program if c₂ is the last command argument, i.e. the output files 2dhf_output.orb, 2dhf_output.coul and 2dhf_output.exch (fort.31, ...) are renamed as c₂.orb, c₂.coul, c₂.exch (c₂.fort.31, ...), respectively,
  • the prefix of names of input files required by the program to continue calculations, i.e. the input files c₂.orb, c₂.coul, c₂.exch (c₂.fort.31, ...) are moved into 2dhf_input.orb, 2dhf_input.coul, and 2dhf_input.exch (fort.31, ...).
• c₃ is the prefix of names of output files generated by the program.

    xhf be be-1

    xhf be be-1 be-2

    xhf be be-2 be-1

5  How to stop the program?

6  Useful hints

• The program should be easy to use provided you can start a calculation for a specific system. You should not encounter any serious problems when the system contains atoms from the first two rows of the Periodic Table. Then even the rough hydrogenic estimates of the orbitals should prove adequate and after the initial couple of dozen of iterations a smooth convergence should set in.
  If, however, a system contains more than 15-20 electrons the initial estimates of the orbitals have to be good enough to avoid divergences. Then, you have to choose the parameters of the hydrogenic orbitals carefully or perform the finite basis set calculations using the Gaussian94 to provide the initialization data for orbitals.
• Do not start calculations on too dense a grid. For example, the 61×61 grid is sufficient to check the quality of the initial data for the Ne₂ system.
• At the very beginning set the maximum number of scf iterations to something between 20 and 50 and/or impose crude convergence criteria for the orbital energy and normalization.
• Choose small values of the relaxation parameters (1 < w < 1.2) to avoid divergence in the first few dozens of iterations. Later on the parameters should be increased to a desired (optimum) values (see the Ne₂ example).
  The dependence of the optimum value of the relaxation parameter w_pot on the grid size is illustrated by the following table:

  nn×nm	wpot
  50 × 50	1.89
  100 × 100	1.94
  159 × 100	1.96
  300 × 300	1.98

  Now it is possible to set w_pot to its near-optimal value by using a semiempirical formula (B.Sobczak MSc Thesis, Torun 2002); see the description of the OMEGA label above.
  Optimum values of the orbital relaxation parameter are somewhat smaller and are not directly related to the grid size. In most cases choosing 1.75 £ w_orb £ 1.85 should lead to fairly good convergence rates.

Footnotes: