Introductory Tutorials

These introductory tutorials will give you an overview of how to run CONQUEST, the files and parameter settings required, and what output to expect.

Bulk silicon: input, output and SCF

We start with a very basic introduction to the input required for CONQUEST, the output generated, and the self-consistency (SCF) procedure; it uses the same system (bulk silicon) as the first of the examples in the manual, but provides more detail. The files are found in docs/tutorials/Introductory_1.

CONQUEST requires the following files to run:

  • The input file: Conquest_input

  • A coordinates file (name set in Conquest_input with the flag IO.Coordinates; no default)

  • Ion files (suffix .ion), which provide the pseudopotentials and pseudo-atomic orbitals (PAOs) (names set in Conquest_input in the ChemicalSpeciesLabel block)

We will discuss the files and their contents, and then how to run the code and interpret the output.

Conquest_input file

The Conquest_input file requires the user to provide a certain minimal amount of information, with most parameters having reasonable defaults set. The file that is provided for this tutorial gives the most basic parameters:

# Input/Output
IO.Title Bulk Si 8 atoms static
IO.Coordinates ionpos.dat

# General Parameters
General.NumberOfSpecies 1

%block ChemicalSpeciesLabel
1  28.0850   Si_SZ

# Moving Atoms
AtomMove.TypeOfRun static

# Finding the density matrix
DM.SolutionMethod diagon

# k-points
Diag.GammaCentred T
Diag.MPMesh T
Diag.MPMeshX 2
Diag.MPMeshY 2
Diag.MPMeshZ 2

The most important entries are:

  • the coordinate file (IO.Coordinates);

  • the number of species (General.NumberOfSpecies);

  • the specification for the species (the block ChemicalSpeciesLabel gives the atomic mass and the ion file name for all species);

  • the type of run (AtomMove.TypeOfRun which defaults to static)

The job title is purely for the user’s convenience and reference. The remaining parameters given above, which related to the Brillouin zone sampling, will be discussed in more detail in the next tutorial; these settings suffice for now.

The species entries in the ChemicalSpeciesLabel block have three entries: the species number (which must be ordered); the atomic mass; and the species label. The ion file which is read for each species is, by default, species_label.ion: for this tutorial, it is Si_SZ.ion. (A file name can be specified after the species label for each species by setting the flag General.PAOFromFiles T.)


As described briefly in the manual, the coordinate file requires an orthorhombic simulation cell, with coordinates specified either in fractional form (the default) or Cartesian (if the tag IO.FractionalAtomicCoords F is set). The units for distance are Bohr radii by default, though can be changed to Angstroms (set General.DistanceUnits Ang). The file in this case, ionpos.dat, is:

10.2600  0.0000   0.0000
 0.0000 10.2600   0.0000
 0.0000  0.0000  10.2600
 0.0000  0.0000  0.0000   1 T T T
 0.5000  0.5000  0.0000   1 T T T
 0.5000  0.0000  0.5000   1 T T T
 0.0000  0.5000  0.5000   1 T T T
 0.2500  0.2500  0.2500   1 T T T
 0.2500  0.7500  0.7500   1 T T T
 0.7500  0.2500  0.7500   1 T T T
 0.7500  0.7500  0.2500   1 T T T

The first three lines specify the simulation cell axes (any non-zero off-diagonal entries will be discarded in the present version). The fourth line specifies the total number of atoms in the system. The subsequent lines give the coordinates, the species index, and then three flags which control whether the atom is free to move in the Cartesian directions (x/y/z). (CONQUEST checks for possible errors in the coordinates: atoms which are too close to each other (less than find parameter) or Cartesian coordinates in the input file when fractional coordinates have been specified.) CONQUEST can also read and write PDB files(ref).

Ion files

Ion files contain the pseudopotentials and pseudo-atomic orbitals (PAOs) for a given species. The ion file needed for this tutorial, Si_SZ.ion, is included along with the input files. In general, ion files are generated by the utility MakeIonFiles, which is found in tools/BasisGeneration and documented somewhere. The input files required for all elements with the LDA, PBE GGA and PBEsol GGA are found in pseudo-and-pao/. Default basis sets with different accuracies can be generated by adjusting the basis size in the Conquest_ion_input file (minimal/small/medium/large). Further details are found somewhere.

Output files and running CONQUEST

By default, the output is written to the file Conquest_out, though this can be changed: to a different file, using the input parameter IO.OutputFile; or to the console (stdout), using the input parameter IO.WriteOutToFile. The amount of output is controlled using the input parameter IO.Iprint (different areas of the code can be set to have different output levels, with all levels defaulting to the global IO.Iprint level).

Detailed discussion of the output file is a little difficult while we’re reworking the output, so I’m postponing this for now

  • Beginning: a summary of the job

  • Bibliography

  • Energies and residuals

  • Forces and stresses

The SCF cycle

Go to top.

Bulk silicon: parameters to converge

  • The files that are needed

    • Coordinates

    • Ion files

    • Input file: Conquest_input

  • Integration grid

  • Brillouin zone sampling

  • Possibly basis set size

The Monkhorst-Pack mesh (Diag.MPMesh) offers a convenient way to do this systematically. Full documentation is found in the diagonalisation section of the manual.

Go to top.

Bulk silicon: analysis

  • The files that are needed

    • Coordinates

    • Ion files

    • Input file: Conquest_input

  • Total DOS

  • Atom-projected DOS

  • Band structure output

  • Charge density and bands

  • Atomic charges

Go to top.