1.1. Self-consistent calculation

In this section, I will teach you how to compute the electronic ground-state density of bulk silicon using RESCU. Copy the following input file and save it to a text file named si_scf.txt.

info.calculationType = 'self-consistent'
info.savepath = 'results/si_scf';
atom.element = [1 1]
atom.xyz = 10.25*[0 0 0;0.25 0.25 0.25]
domain.latvec = 10.25*[0.0 0.5 0.5;0.5 0.0 0.5;0.5 0.5 0.0]
domain.lowres = 0.5
element.species = 'si'
element.path = './Si_TM_LDA.mat'
kpoint.gridn = [4,4,4]

Then copy the Si pseudopotential file from the database to ./Si_TM_LDA.mat. Execute RESCU and use the -i option to point to the input file.

rescu -i si_scf.txt;

The results will be saved to results/si_scf.mat (as determined by the info.savepath keyword.

The system information and the simulation parameters are defined by keywords. The keywords generally have self-explanatory names, but you may refer to the input reference file inputDescription.m located int the doc directory for more information. I will briefly describe the keywords found in the above example.

  • info.calculationType tells RESCU to perform a self-consistent calculation.

  • info.savepath is the path and name prefix of the file where RESCU writes its results. RESCU appends the rank number to the file name prefix, which for serial calculations is always 0.

  • atom.element is a vector defining the element type of each atom. In the case of bulk silicon, there are two atoms of the silicon element defined below.

  • atom.xyz is an array of row-vectors containing the position of each atom.

  • domain.latvec defines the lattice vectors, which must be written as an array of row-vectors.

  • domain.lowres controls the real space resolution.

  • element is a structure array containing the atomic information.

  • element.species is a tag for the element structure. It is usually the chemical symbol of the corresponding element.

  • element.path is a string containing the path to the pseudo-potential file associated with the element.

  • kpoint.gridn sets the number of k-points used to sample the first Brillouin zone.

This is the minimal set of keywords for a self-consistent calculation. I suggest that you keep these definitions close or remember them.

1.2. Read results

During the calculation, RESCU displays some information about the simulation parameters and the state of the calculation. This is recorded in a file whose path is given by the keyword info.outfile. The default value is ./resculog.out. If the file exists, the output is appended to the existing content. Upon completion, the results are saved to info.savepath as a MAT-file.

In MATLAB, you can load the results by clicking on the file in the file explorer or by typing the following command:

rescuStruct = load('results/al_scf.mat');

You can then use the variable explorer to skim through the results and extract data.

You can also read the results using Python. I suggest using the h5py and numpy modules. Here is an example were we load the self-consistent ground-state density.

import h5py, numpy as np
f = h5py.File('results/si_scf.mat')
list(f.keys())
list(f['rho'].keys())
rhofinal = f['rho']['final'].value

I first create an HDF5 object using h5py.File; MATLAB structures are mapped to Python dictionaries. I then use list(f.keys()) to navigate the structure. The result is found in the value attribute.

The output data is stored in a structure similar to the input data. In fact, a lot of the output data is just a replicate of the input data. The additional data is described in the document outputDescription.m found in the doc directory. Like the inputDescription.m file, it may be read as is or executed within MATLAB, which makes the exploration easier.