Basic input options

Now we will move to a more complicated (and realistic) input file. We will obtain the ground state of the nitrogen atom. We will introduce several basic input variables and will give a more detailed description of the output for this example.

The input files

This sample input file lets us obtain the ground state of the nitrogen atom, within the LDA approximation, in a closed-shell (unpolarized) configuration (as explained below, you need an auxiliary .xyz input). Note that this is not the correct ground state of the nitrogen atom! However, it will permit us to describe some of the most important input variables:

CalculationMode = gs
UnitsOutput = eV_Angstrom

Nitrogen_mass = 14.0

%Species
 'N' | species_pseudo | set | standard | lmax | 1 | lloc | 0 | mass | Nitrogen_mass
%

XYZCoordinates = 'N.xyz'

ExtraStates = 1
%Occupations
  2 | 1 | 1 | 1
  %

BoxShape = sphere
Radius = 5.0*angstrom
Spacing = 0.18*angstrom

We have introduced here several new variables:

• UnitsOutput = eV_Angstrom: Two different unit systems may be used for output: the usual atomic units (which is the default, and the ones used internally in the code); and the system in which the Ångström is substituted for the atomic unit of length, and the electronvolt is substituted for the atomic unit of energy. You can find a more detailed description of units in Octopus in the Units page of the manual.

• The following entry in the input file is not a variable that Octopus will read directly, but rather illustrates the possibility of writing “user-defined” values and expressions to simplify the input file. In this case, we define the nitrogen mass (Nitrogen_mass = 14.0) (note that in this case, as an exception, the value is expected to be in the so-called “atomic mass units”, rather than in “atomic units”). This definition may be used elsewhere in the input file.

• The Species block should contain the list of species that are present in the system to be studied. In this case we have only one species: nitrogen. The first field is a string that defines the name of the species, “N” in this case. The second field defines the type of species, in this case species_pseudo. Then a list of parameters follows. The parameters are specified by a first field with the parameter name and the field that follows with the value of the parameter. Some parameters are specific to a certain species while others are accepted by all species. In our example set instructs Octopus to use a pseudopotential for nitrogen from the standard set. This happens to be a Troullier-Martins pseudopotential defined in the N.psf file found in the directory share/octopus/pseudopotentials/PSF . Then come maximum lmax - component of the pseudopotential to consider in the calculation, and the lloc - component to consider as local. Generally, you want to set the maximum ‘‘l’’ to the highest available in the pseudopotential and the local ‘‘l’’ equal to the maximum ‘‘l’’. Finally, the mass of the species can also be modified from the default values by setting mass parameter.

• XYZCoordinates = 'N.xyz': The geometry of the molecule (in this case, a single atom in the grid origin) is described in this case in a file with the well known XYZ format. The file for this outrageously simple case is given by:

1
This is a comment line
N 0 0 0

• ExtraStates = 1: By default, Octopus performs spin-unpolarized calculations (restricted closed-shell, in Hartree-Fock terminology). It then places two electrons in each orbital. The number of orbitals, or Kohn-Sham states, is then calculated by counting the number of valence electrons present in the system, and dividing by two. In this case, since we have five valence electrons, the code would use three orbitals. However, we know beforehand that the HOMO orbital has a three-fold degeneracy, and as a consequence we need to put each one of the three p electrons in a different orbital. We therefore need one more orbital, which we get with this line in the input file.

• %Occupations block: Generally, the occupations of the Kohn-Sham orbitals are automatically decided by the code, filling the lowest-energy orbitals. However, if we have degeneracies in the LUMO as in this case, the user may want to accommodate the electrons in a certain predefined way. In this example, the obvious way to fill the orbitals of the nitrogen atom is to put two electrons in the first and deepest orbital (the s orbital), and then one electron on each of the second, third and fourth orbitals (the p orbitals, which should be degenerate).

• BoxShape = sphere: This is the choice of the shape of the simulation box, which in this case is set to be a sphere (other possible choices are minimum, cylinder, or parallelepiped).

Output

Once you have constructed the input file and created the N.xyz file, you may unleash Octopus on it. Lets now go over some of the sections of the output.

Species

****************************** Species *******************************
  Species 'N'
    type             : pseudopotential
    file             : '/home/luedersm/Octopus_foss-2020b/share/octopus/pseudopotentials/PSF/N.psf'
    file format      : PSF
    valence charge   : 5.0
    atomic number    :   7
    form on file     : semilocal
    orbital origin   : calculated
    lmax             : 1
    llocal           : 0
    projectors per l : 1
    total projectors : 1
    application form : kleinman-bylander
    orbitals         : 16
    bound orbitals   : 16

**********************************************************************

Here the code searches for the needed pseudopotential files, and informs the user about its success or failure. In this case, only the N.psf file is required. Once that file has been processed, some information about it is written to the output. One of the most important pieces of information to be found here is the valence charge, which tells us how many electrons from this species will be considered in the calculation.

Grid

******************************** Grid ********************************
Simulation Box:
  Type = sphere
  Radius  [A] =   5.000
Main mesh:
  Spacing [A] = ( 0.180, 0.180, 0.180)    volume/point [A^3] =      0.00583
  # inner mesh =      89727
  # total mesh =     127183
  Grid Cutoff [eV] =  1160.586810    Grid Cutoff [Ry] =    85.301565
**********************************************************************

This step is about the construction of the mesh. As requested in the input file, a sphere of radius 5 Å is used, which contains a cubic regular real-space grid with spacing 0.18 Å. This implies 89727 points (inner mesh = 89727). For the sake of comparison with plane-wave-based codes, this is more or less equivalent to a plane-wave calculation that imposes a density cutoff of 1160.595 eV = 42.6 Hartree (except that in this case there is no artificial periodic repetition of the system).

Mixing

Input: [MixField = potential] (what to mix during SCF cycles)
Input: [MixingScheme = broyden]

During the self-consistent procedure one has to use a mixing scheme to help convergence. One can mix either the density or the potential, and there are several mixing schemes available.

Eigensolver

**************************** Eigensolver *****************************
Input: [Eigensolver = cg]
Input: [Preconditioner = pre_filter]
Info: Generating weights for finite-difference discretization of Preconditioner
Input: [PreconditionerFilterFactor = 0.5000]
Input: [SubspaceDiagonalization = standard]
**********************************************************************

Here we see that the eigensolver used will be simple conjugate gradients (cg), and a preconditioner is used to speed up its convergence.

LCAO

After some output you should see something like:

Info: Performing initial LCAO calculation with      4 orbitals.
Info: Getting Hamiltonian matrix elements.
ETA: .......1......2.......3......4......5.......6......7.......8......9......0

Eigenvalues [eV]
 #st  Spin   Eigenvalue      Occupation
   1   --   -17.398866       2.000000
   2   --    -6.414013       1.000000
   3   --    -6.414013       1.000000
   4   --    -6.414013       1.000000
Info: Ground-state restart information will be written to 'restart/gs'.

This is the first step of a ground-state calculation: obtaining a reasonably good starting density and Kohn-Sham orbitals to feed in the self-consistent (SCF) procedure. For this purpose, Octopus performs an initial calculation restricted to the basis set of atomic orbitals ( Linear Combination of Atomic Orbitals, LCAO). The resulting eigenvalues of this calculation are written to standard output.

Wavefunction kind

 Info: SCF using real wavefunctions.

Very often one can work with real wave-functions. This is particularly helpful as calculations with real wave-functions are much faster than with complex ones. However, if a magnetic field is present, if the system is periodic, or if spin-orbit coupling is present, complex wave-functions are mandatory. But don’t worry: the program is able to figure out by itself what to use.

SCF

*********************** SCF CYCLE ITER #    1 ************************
 etot  = -2.56360502E+02 abs_ev   =  1.98E-01 rel_ev   =  3.66E-03
 ediff =        9.42E+00 abs_dens =  2.27E-01 rel_dens =  4.55E-02
Matrix vector products:     25
Converged eigenvectors:      0

#  State  Eigenvalue [eV]  Occupation    Error
      1      -17.420048    2.000000   ( 1.2E-02)
      2       -6.465997    1.000000   ( 2.3E-02)
      3       -6.465997    1.000000   ( 2.3E-02)
      4       -6.465997    1.000000   ( 2.3E-02)

Density of states:

---------------------------------------------------------------------%
---------------------------------------------------------------------%
---------------------------------------------------------------------%
---------------------------------------------------------------------%
---------------------------------------------------------------------%
---------------------------------------------------------------------%
---------------------------------------------------------------------%
%--------------------------------------------------------------------%
%--------------------------------------------------------------------%
%--------------------------------------------------------------------%
                                                                     ^


Elapsed time for SCF step     1:          0.12
**********************************************************************

Now the SCF cycle starts. For every step, Octopus outputs several pieces of information:

• The values abs_dens and rel_dens are to monitor the absolute and relative convergence of the density, while rel_ev and abs_ev are two alternative measures of the convergence, based on measuring the difference between input and output eigenvalues. The SCF procedure, by default, is stopped when rel_dens is smaller than $10^{-5}$. This may be altered with the appropriate input variables (see in the manual the variables ConvAbsDens, ConvRelDens, ConvAbsEv and ConvRelEv).

• The line Matrix vector products: 108 tells us that the Hamiltonian was applied 108 times. This gives us an idea of the computational cost.

• The line Converged eigenvectors: 0 tells us that upon completion of the diagonalization procedure, none of the orbitals met the required precision criterion for the wavefunctions. In a following example, we will modify this criterion in the input file.

• The list of eigenvalues is then printed, along with their errors: how much they deviate from “exact” eigenvalues of the current Hamiltonian. This number is the so-called “residue”.

You can now take a look at the file static/info that will hold a summary of the calculation.

Restarting

Any ground-state calculation may be restarted later (to refine it if it did not converge properly, or with any other purpose), provided that the contents of the restart directory are preserved. You can try this now, just by running Octopus again. You will notice that Octopus did not give any warning after the line

 Info: Loading restart information.

This is useful if you change slightly the parameters of the simulation (for example the XC functional or the convergence criteria). If you change the grid parameters Octopus will not be able to restart from the previous calculation. If you do not want Octopus to try to restart a calculation, you can set the variable FromScratch.

In case you ware wondering what the restart information looks like, you can have a look at the contents of the restart directory. This is where the files needed to restart a calculation are stored. It may contain several sub-directories depending on the calculations previously performed. In this case, it just contains one:

 % ls restart
 gs
 % ls restart/gs

0000000001.obf	density.obf    dv_010101.obf   grid	    vhxc
0000000002.obf	df_010101.obf  dv_010102.obf   indices.obf  vhxc.obf
0000000003.obf	df_010102.obf  dv_010103.obf   mixing	    vin_old_0101.obf
0000000004.obf	df_010103.obf  dv_010104.obf   occs	    wfns
density		df_010104.obf  f_old_0101.obf  states

Octopus stores each individual state in a different binary (yet platform-independent) file. In this case, we only have four states (files 0000000001.obf to 0000000004.obf ). Some other useful quantities, like the density, are also stored in binary form. The other files are text files that contain diverse control information. It is unlikely that you will ever have to work directly with these files, but you may take a look around if you are curious.