Tutorial Ground State

Author: Xavier Andrade

Qball commands

Qball input is based on commands that are executed in the sequence they appear in the input files. If Qball encounters an unknown command in the input file, it assumes that command is the name of an input file that contains additional commands to execute.

Some input is controlled by variables. The values of these variables can be defined by the set command. You can find a summary of the commands and variables here.

Something important to notice is that, as Qball receives commands, it executes them sequentially. Therefore the order of the sentences in the input file matters.

Creating the input file

We will now generate a basic Qball input file. This can be a text file with any name you prefer. I suggest you call it hydrogen.i.

First we define the simulation cell by setting the cell variable:

 set cell 15 0 0 0 15 0 0 0 15 bohr

The values define the lattice vectors of the simulation cell. In this case we use atomic units (bohr).

Now we need to define the types of the atoms/ions we intend to simulate using the species command

 species hydrogen H_PBE.xml

The first argument is the name of the species. This name will later be used to define the coordinates of instances of the species in our simulation cell. The second argument is the name of a pseudopotential file. Qball uses its own pseudopotential format. You can download the file here. On many systems, you can get the file directly from the terminal by typing wget https://raw.githubusercontent.com/LLNL/qball/master/examples/sih4/H_PBE.xml.

Now we need to add the actual atoms using the atom command

 atom H1 hydrogen 0.0 0.0 0.0 bohr

The first argument is a unique name for the atom. The second argument is the name of the species, declared previously using species. The next three numbers give the position of the atom in the cell.

Optionally, you can add the velocity of the atom as another three numbers.

Next, we define the size of the plane-wave basis by setting the energy cutoff using the ecut variable

 set ecut 30 rydberg

Now we specify the optimization method, or eigensolver, for the electronic wave-functions. In this case we use the preconditioned steepest descent (PSD) method

 set wf_dyn PSD

We also specify the cutoff for the preconditioner

 set ecutprec 4 rydberg

Finally, we set the converge criterion for the self-consistent iteration as

 set threshold_scf 1e-5 4

This tells the program that we consider the calculation converged once the energy change is less than 1e-5 over the course of 4 iterations.

Now that we have set all the values, we can start the calculation. First we call set the initial electronic wave-functions with a random value using the command

 randomize_wf

and we begin the calculation with the run command

 run 0 100

The first value is the number of ionic iterations: 0 in this case since we are just doing an electronic ground state calculation. The second value is the maximum number of self-consistent iterations.

Running qball

Now we are ready to run qball. To do this just type

 qball hydrogen.i

Depending on your system configuration, you might need to add the full path to the qball executable (/usr/local/bin/qball for example), or you might need to add some command to get the job to run in the queue.

Once executed, qball will print a lot of output to the terminal. This output is in XML format, to make it easier to parse by other codes. Unfortunately this makes the output a bit harder for humans to read.

Let's have a look at the output. It's more convenient to do this if you redirect the output to a file, like this

 qball hydrogen.i > out.log

Now read the file using less out.log or your favorite text file reader.

First qball will print some information about the version and the system it is running on. Then it will print back the command it receives, like this

 <!-- [qball] set cell 15 0 0 0 15 0 0 0 15 bohr -->

Note that qball prints <!--- ---> around the output. This syntax defines a line as an XML comment, so that XML parsers don't get confused by it.

After each command, qball will print certain output about what qball is doing regarding the execution of that command. Have a look at each command and its output.

The command that does the actual work is run. Find the place in the output file where this command was executed. (If you are using less, the / command can be used to search.)

You will see the output for each self-consistent field (SCF) iteration is a line like this

 <etotal_int scf_iter="0">      5.15484219 </etotal_int>

that gives the total energy for the iteration.

After the SCF is converged, qball will print the different energies

 <ekin>        0.40379697 </ekin>
 <econf>       0.00000000 </econf>
 <eps>        -0.23865373 </eps>
 <enl>         0.00000000 </enl>
 <ecoul>      -0.37773034 </ecoul>
 <exc>        -0.22929078 </exc>
 <esr>         0.00000000 </esr>
 <eself>       0.39894228 </eself>
 <ets>         0.00000000 </ets>
 <etotal>     -0.44187788 </etotal>

and the cell, coordinates, velocities and forces for the ions

 <atomset>
 <unit_cell 
    a=" 15.00000000   0.00000000   0.00000000"
    b="  0.00000000  15.00000000   0.00000000"
    c="  0.00000000   0.00000000  15.00000000" />
   <atom name="H1" species="hydrogen">
   <position> 0.00000000 0.00000000 0.00000000 </position>
   <velocity> 0.00000000 0.00000000 0.00000000 </velocity>
   <force> -0.00002845 -0.00000682 -0.00001089 </force>
   </atom>
 </atomset>