# Self-consistent calculation {#sec:si_tuto_scf}

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`.

``` shell
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.

``` shell
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.

# Read results {#sec:si_tuto_loadresults}

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:

``` shell
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.

``` shell
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.
