In the next sections we proceed to describe these files with the help
of some examples.
Here is a first example for a perfect fcc Cu crystal:
! POSTBMD for FCC Cu a0 = 3.61 a_1 = 0.0 0.5 0.5 a_2 = 0.5 0.0 0.5 a_3 = 0.5 0.5 0.5 unit_cell_grid = 5 5 5 number_of_ions = 1 Positions = Unit 0.0 0.0 0.0This example shows that it is possible to generate a supercell from the primitive cell, without having to enter the coordinates of all the atoms. The systems will be composed of 125 atoms with an fcc lattice constant of 18.05 Ang.
A second example for a GaAs crystal illustrates the differences in POSTBMD for a system with multiple species:
! POSTBMD for GaAs a0 = 5.65 a_1 = 1.0 0.0 0.0 a_2 = 0.0 1.0 0.0 a_3 = 0.0 0.0 1.0 unit_cell_grid = 2 2 2 number_of_ions = 4 4 Positions = Unit 1 0.00 0.00 0.00 2 0.25 0.25 0.25 1 0.00 0.50 0.50 2 0.25 0.75 0.75 1 0.50 0.00 0.50 2 0.75 0.25 0.75 1 0.50 0.50 0.00 2 0.75 0.75 0.25Let us first describe all the keywords that can (or must) be specified in the POSTBMD file:
a0: (optional)
Lattice constant which will multiply the lattice vectors, if not present
it is assumed to be equal to one.
a_1, a_2 and a_3:
The three vectors that define the unit-cell, these three line have
to be present in the POSTBMD file, if not an error will occur and the program
will stop.
number_of_ions:
Number of ions per species in the cell. For a system with only one
species of atoms there will be only one number, for a systems with two
species there will be two, etc., ... Actually the program will count how
many numbers are given on that line to determine how many species there
are in the system. This numbers of species should be compatible with the
number found in TBPARAM, if not the program will stop. The total
number of ions is the sum of all the number found on this line, this is
the number of lines that will be read after the positions keyword.
unit_cell_grid: (optional)
Three integers (Nx, Ny, Nz) used to generate
a super-cell by repeating the unit-cell Nx times along a1,
Ny times along a3, and Nz times
along a3. The lattice vectors will be rescaled accordingly,
and the total number of ions will be
number_of_ions
times NxNyNz.
positions:
Indicates if the positions of the ions are given in units of the lattice
constants (positions = unitcell) or in Cartesian coordinates (positions
= cartesian). This line should be immediately followed by the ionic
coordinates. To make this clearer, suppose we have the following POSTBMD
file (for hcp Ti):
a0 = 2.871567965 a_1 = 0.50 -0.86602540378443864676 0.0 a_2 = 0.50 0.86602540378443864676 0.0 a_3 = 0.0 0.0 1.58 number_of_ions = 2 unit_cell_grid = 2 2 2 positions = unit 0.0 0.0 0.0 0.33333333333333333333 0.66666666666666666666 0.5the cartesian coordinates of the second atom would be given by (we rounded up to the second decimal to save space):
( X ) ( 0.50 0.50 0.00 ) ( 1/3 ) ( Y ) = a0 ( -0.87 0.87 0.00 ) x ( 2/3 ) ( Z ) ( 0.00 0.00 1.58 ) ( 1/2 )The coordinates can be given in two ways, depending on whether or not the specie of each atom is given in the first column. So the first possibility is to give an integer which identifies the specie followed by the X, Y and Z coordinates:
! POSTBMD for GaAs a0 = 5.65 a_1 = 1.0 0.0 0.0 a_2 = 0.0 1.0 0.0 a_3 = 0.0 0.0 1.0 unit_cell_grid = 2 2 2 number_of_ions = 4 4 Positions = Unit 1 0.00 0.00 0.00 2 0.25 0.25 0.25 1 0.00 0.50 0.50 2 0.25 0.75 0.75 1 0.50 0.00 0.50 2 0.75 0.25 0.75 1 0.50 0.50 0.00 2 0.75 0.75 0.25The second possibility is to give only the X, Y and Z coordinates, in which case the coordinates are assumed to be grouped by species, i.e. in this example the first four coordinates are for the Ga atoms and the four last for the As:
! POSTBMD for GaAs a0 = 5.65 a_1 = 1.0 0.0 0.0 a_2 = 0.0 1.0 0.0 a_3 = 0.0 0.0 1.0 unit_cell_grid = 2 2 2 number_of_ions = 4 4 Positions = Unit 0.00 0.00 0.00 0.00 0.50 0.50 0.50 0.00 0.50 0.50 0.50 0.00 0.25 0.25 0.25 0.25 0.75 0.75 0.75 0.25 0.75 0.75 0.75 0.25Note that one cannot mix the two syntaxes, if you choose to give the species in the first column you should do so for all atoms.
velocities: (optional)
Same convention as for positions but for the velocities. This
part is optional, if not velocities are given the program will be initialize
with random velocities consistent with the target temperature.
freeze: (optional)
This keyword should be immediately followed by three LOGICAL
flags per atoms (these must be in uppercase), indicating for each atom
what degree of freedom will be frozen, i.e. for the X, Y and Z coordinates
respectively. In the present version of the code we recommend that all
three flags for the X, Y and Z degree of freedom should be the same. Freezing
an atom has three consequences : the atom will remain fixed during the
simulation, the velocity of this atom will be set to zero and the force
for this atom will not be calculated.
Finally here is a slightly more complicated POSTBMD file, using all the keywords described above. This example file is for the simulation of a small Cu cluster composed of four atoms, in a large super-cell:
! POSTBMD for Cu4 cluster a0 = 12.0 a_1 = 1.0 0.0 0.0 a_2 = 0.0 1.0 0.0 a_3 = 0.0 0.0 1.0 number_of_ions = 4 Positions = Cartesian 0.0 0.0 0.0 2.8 0.0 0.0 0.0 2.5 0.0 1.5 1.2 1.0 Velocities = Unit -5.19016e-05 5.88313e-06 -2.75206e-05 -5.44472e-06 -1.45381e-05 -2.72095e-05 1.42977e-05 -9.61665e-06 -1.92899e-05 -4.97803e-06 3.46058e-05 -3.38563e-05 Freeze T T T F F F F F F F F F
system_name = "Bulk Mo at 75 K, Langevin dynamics" number_of_ionic_steps = 1000 dt = 3.0 ! time step for MD ionic_eom_algo = 1 ! Verlet ... this is a comment ionic_thermostat = 2 temperature = 75.0 ionic_friction = 0.05 elec_algo_gs = 2 sigma = 0.06 ! broadening of the occupations in eVThe keywords (KW) may appear in any order. You can have more than one command per line separated by a semi-column. Comments may be added anywhere after an exclamation mark.
The string specified by the system_name KW will be printed at the start of the OUTTBMD file, it is the ``title'' of the simulation. The next two line indicates that the simulation will be run for a thousand steps (number_of_ionic_steps = 1000) using a time step of 3 fs (dt = 3.0), in other words the simulation length will be of 3 ps.
The KW ionic_eom_algo is used to indicate which numerical algorithm which will be used the integrate the ionic equations of motion, here we specify Verlet's algorithm (this is also the default, so we could have omitted this line).
By default the MD simulation is performed in the micro-canonical ensemble (in which case the total energy is conserved), but by means of the ionic_thermostat KW on can do simulations that will sample the canonical ensemble, either using Langevin dynamics or by coupling the ionic motion to a Nosé-Hoover thermostat. In this example we would perform Langevin dynamics. The temperature is given by the KW temperature. Langevin dynamics requires that a friction coefficient is specified using the KW ionic_friction. This may also be used to performed damped dynamics in order to minimize the energy of the system, as shown in one of the examples below.
All KW so far were related to the motion of the ions, the last two line specify KWs related to the electronic part. The most important KW is elec_algo_gs with which on chooses how the electronic energy is calculated at each ionic step. The last KW is sigma, which specifies the width of the Fermi-Dirac distribution to calculate the occupation of the states close to the Fermi level.
In this example elec_algo_gs is set to 2, which indicates that the electronic structure will be calculated using diagonalization. For the time being the only other possible choice is 4, which specifies using the O(N2) kernel polynomial method. The later method is however limited to orthogonal TB models and has not yet been thoroughly tested.
Almost all keywords have a default value, so you only need to specify the keywords for which the default value is not adequate.
NOTE : a word of caution, the input file is not checked for unknown keywords, this mean that if there is a typing mistake in your INTBMD file, that command will simply be ignored and the default value will be assumed.
Most of the keywords are self-explanatory but to obtains a more detailed description of all the keyword please look at Appendix A.
In addition to the parameters themselves TBPARAM contains additional information, such as the number of species, the type of the atoms, the atomic masses and the number of electrons per atom which is used to calculate the total number of electrons in the system. The data in TBPARAM is also used to define the cut-off distance beyond which matrix-elements between two atomic orbitals are neglected.
For the TBPARAM files needed for other models, please contact the author.
You can either enter give the program all the k-points you want to use by hand or you can let DoD-TBMD generate them for you:
a) Explicit k-points
To explicitly specify the k-points to be used the KPTS file should look like this (e.g. for 4 k-points, the text in italics is comment NOT to be included in the KPTS file):
4 number of k-points 0.25 0.25 0.25 0.25 k-point #1: k1 k2 k3 weight -0.25 0.25 0.25 0.25 k-point #2: k1 k2 k3 weight 0.25 -0.25 0.25 0.25 k-point #3: k1 k2 k3 weight -0.25 -0.25 0.25 0.25 k-point #4: k1 k2 k3 weightThe format is very simple: the first line gives the number of k-points and each line after that gives the coordinates of a k-point (in units of the reciprocal lattice vectors) and its relative weight. Note that the weights will be by the code normalized so the sum of the weights of all k-points gives 1.
b) Automatic k-points generation
To let the code generate the k-points for you, the KPTS file should look like this:
A N1 N2 N3The first line is the letter "A", a label that tells the code to generate the k-points. The second line specifies the size of the Monkhorst-Pack k-point grid to be N1xN2xN3. So for instance to generate a 2x2x2 grid your KPTS file would look like this:
A 2 2 2
Note that since DoD-TBMD was written for running MD simulations,
no symmetry other than time-reversal symmetry (i.e. -k is equivalent to
k) is taken into account to reduce the k-points set to the irreducible
set. So if you ask for a 2x2x2 grid you will end up with 4 k-points or
if you ask for a 5x5x5 grid the code will generate 65 k-points (i.e. (125-1)/2
+ 1, since for uneven N1, N2 and N3 the
gamma-point will be part of the k-points set).
We now describe briefly all the output file generated by TBMD.
OUTTBMD
This is the main output file. The ionic positions, the energies, the forces are all printing out in this file. Most of the output is labeled and should be self-explanatory. All energies are given in eV and distances in Angstroms.
Example of an
OUTTBMD file (edited for space).
ERRTBMD
File containing possible error and/or warning messages. If the simulation
does not run as expected or crashes check this file first. If you think
you found a bug, please send possible error messages to the author or check
the bugs report page.
File containing all the information regarding the current configuration of the system, information which is saved every save_freq steps. This files contains at least the current positions and velocities of the systems. In addition all the information necessary to continue the simulation seamlessly (except for rounding errors) is also save to this file, the detailed information depends on the type of simulation. To continue a simulation after it stopped or crashed simply use the last POSCONT file and copy it to POSTBMD:
>cp POSCONT POSTBMDand in INTBMD set start = 1, this will continue the simulation from the configuration that was last saved as if it hadn't stopped/crashed.
The files described below contain information that is saved every
save_freq
MD steps. The information that is saved and the file to which it is saved
is controlled by adding save_to_file
keywords in
INTBMD. For instance to save the velocities in a file
called
VEL add the following line to INTBMD:
save_to_file = velocities VELNote: The quantities that are saved by default are indicated with a "*".
File in which the positions of the ions are saved every save_freq MD steps. The coordinates saved in this file can then be used to compute statistical averages.
The default name (POS) of this file can be changed by inserting the following line in INTBMD
save_to_file = positions new_file_name
The temperature, the kinetic energy, potential energy and total energy of the system are saved to this file every save_freq MD steps. The different energies are indicated at the top of the file. To make these energies easier to plot each energy is shifted by the value at the first MD step (i.e. at time step 0 all energies in ENE should be zero, that first step is not printed however). The absolute energies can be founf in the OUTTBMD file, if needed. These are different depending on the type of simulation that is performed. For instance for a micro-canonical simulation the total energy should be a constant of motion. It is a good idea to plot these energies as a function of time to check the soundness of the simulation.
The default name (ENE) of this file can be changed by inserting the following line in INTBMD
save_to_file = Energy new_file_name
If diagonalization is used to compute the electronic structure, the eigenvalues, occupation numbers and Fermi-level can be saved to this file every save_freq MD steps. These eigenvalues can be used to calculate the density of states as an ensemble average.
The default name (EIG) of this file can be changed by inserting the following line in INTBMD
save_to_file = eigenvalues new_file_name
File in which the velocities of the ions are saved every save_freq MD steps. The velocities saved in this file can then be used to compute statistical averages.
The default name (VEL) of this file can be changed by inserting the following line in INTBMD
save_to_file = Velocities new_file_name
File in which the forces on the ions are saved every save_freq MD steps.
The default name (FOR) of this file can be changed by inserting the following line in INTBMD
save_to_file = forces new_file_name
File in which the local energies of each ion are saved every save_freq MD steps.
The default name (ELOC) of this file can be changed by inserting the following line in INTBMD
save_to_file = elocal new_file_name