Brief introduction of the input files¶

Input¶

The Input file describes the basic information about the system and the parameters required to calculate the function. For a complete list of the input parameters, please consult this input list.

The following is an example of a Input file:

INPUT_PARAMETERS
{
    nspin                          4
    package                        ABACUS
    fermi_energy                   9.481194886038594
    fermi_energy_unit              eV
    HR_route                       data-HR-sparse_SPIN0.csr
    SR_route                       data-SR-sparse_SPIN0.csr
    rR_route                       new-data-rR-tr_SPIN4
    HR_unit                        Ry
    rR_unit                        Bohr
    max_kpoint_num                 8000
}

LATTICE
{
    lattice_constant               1.8897162
    lattice_constant_unit          Bohr
    lattice_vector
    -2.069  -3.583614  0.000000
     2.069  -3.583614  0.000000
     0.000   2.389075  9.546667
}

BAND_STRUCTURE
{
    wf_collect                     0
    kpoint_mode                    line
    kpoint_num                     5
    high_symmetry_kpoint
    0.00000 0.00000 0.0000 100  # G
    0.00000 0.00000 0.5000 100  # Z
    0.50000 0.50000 0.0000 100  # F
    0.00000 0.00000 0.0000 100  # G
    0.50000 0.00000 0.0000 1    # L
}

The Input file consists of three main sections (INPUT_PARAMETERS, LATTICE, FUNCTION), each of which is represented by the keyword + {}, namely:

KEYWORD
{
    parameter  xx
}

The INPUT_PARAMETERS section is utilized to specify public parameters and indicate the HR, SR, and rR files required for the calculation.

The LATTICE section outlines lattice information and includes three parameters: lattice_constant, lattice_constant_unit, and lattice_vector.

The FUNCTION section lists the parameters necessary for each calculation function. These parameters differ depending on the specific function being used.

NOTE:

The keyword of the section must be capitalized, and the parameters in the section must be lowercase.
Each parameter value is provided by specifying the name of the input variable and then putting the value after the name, separated by one or more blank characters(space or tab).
Any line starting with # or // will be ignored. To ignore a function section, add # in front of the section name. This will cause all parameters within that function section to be ignored.
Proper case is required to avoid reading errors. For example, eV must not be written as ev, and Bohr must not be written as bohr.

HR, SR, rR¶

HR, SR, and rR are important input files for PYATB and contain information about the tight binding model, which can be generated by ABACUS.

In the PYATB program, if only the Bands module is used, it is enough to provide HR and SR, and specifying rR is not required. However, when the functions of the calculations are related to the Geometric module or Optical module, the rR file must be specified.

How to generate HR, SR, rR files using ABACUS¶

Run the scf calculation of ABACUS normally, specifies the parameters out_mat_hs2 and out_mat_r in the INPUT file, and three files of sparse format data-HR-sparse_SPIN0.csr, data-SR-sparse_ SPIN0.csr, data-rR-sparse.csr (and data-HR-sparse_SPIN1.csr when nspin is 2), will be generated in OUT* folder.

NOTE:

nspin=4 and nspin=1, nspin=2 output different files. nspin=4 files contain imaginary numbers, so the correct nspin parameter needs to be strictly specified when executing pyatb programs.

Format description of HR, SR, rR¶

We use the file data-HR-sparse_SPIN0.csr as an example to explain the format of HR. This file contains a series of \(H(R)\) matrices, where each R corresponds to an \(H(R)\) matrix. The specific format of the file is as follows:

The dimension of the \(H(R)\) matrix is recorded on the first line, for example, Matrix Dimension of H(R): 270, indicating that each \(H(R)\) matrix is a 270*270 matrix.
The number of R is recorded on the second line, for example, Matrix number of H(R): 97, indicating that there are a total of 97 \(H(R)\) matrices.
Starting from the third line, every 4 lines form a group, recording the sparse matrix of \(H(R)\). Following the example above, the file still has 4*97 lines left, divided into 97 groups.
- The first line of each group contains 4 integers. The first three numbers represent the (x, y, z) fractional coordinates of R, and the last number represents the number of non-zero elements in the sparse matrix.
- The second to fourth lines of each group record the data, indices, and indptr information of the sparse matrix in csr format.

The sparse matrix csr format is explained below, with reference to Wikipedia. Please refer to Sparse matrix.

We will use the following matrix as an example:

\[\begin{split} \left[ \begin{array}{cccc} 4 & 2 & 0 & 0\\ 0 & 3 & 0 & 0\\ 0 & 4 & 5 & 0\\ 0 & 0 & 0 & 0\\ \end{array} \right] \end{split}\]

The sparse matrix in csr format has three sets of data, corresponding to three lines in the output file. The first line contains the non-zero element data, the second line contains the column indices of the non-zero elements indices, and the third line contains the row offset indptr.

Note that our counting starts from 0.

First, the first row of the matrix is 4 2 0 0, which has 2 non-zero elements 4 2, with corresponding column indices 0 1. The second row of the matrix is 0 3 0 0, which has 1 non-zero element 3, with corresponding column index 1. The third row of the matrix has 2 non-zero elements 4 5, with corresponding column indices 1 2. The fourth row is all zeros and has no non-zero elements.

Therefore, we have:

data = [4, 2, 3, 4, 5]  # non-zero elements
indices = [0, 1, 1, 1, 2]  # column indices of each non-zero element

'''
The number of non-zero elements in each row from the first to 
the fourth row is 2, 1, 2, 0, respectively;
the corresponding offset values are 0, 2, 3, 5, 5. 
These values are used to record the starting offset of each 
row's first element in the data array, and can also be used 
for the indices array. The number of non-zero elements in 
each row can be obtained by subtracting the previous offset value 
from the current offset value, i.e., 2-0=2, 3-2=1, 5-3=2, 5-5=0.
'''

# the dimension of this array must be the number of rows of the matrix plus 1.
indptr = [0, 2, 3, 5, 5]  

NOTE:

When the npsin parameter in the PYATB Input file is set to 1 or 2, the HR matrix read is purely real. When nspin is set to 4, the HR matrix read is complex, with matrix elements in the format of (real part, imaginary part).

The file format for the SR matrix is identical to that of the HR matrix. The rR matrix format is slightly different because it includes the \(r_x\), \(r_y\), and \(r_z\) directions. We use data-rR-sparse.csr as an example to illustrate the rR file format.

The first line is Matrix Dimension of r(R): 270.
The second line is Matrix number of r(R): 97.
The third line consists of three numbers, representing the fractional coordinates (x, y, z) of R.
Starting from the fourth line, every 4 lines form a group, with a total of three groups, recording the \(r_x(R)\), \(r_y(R)\), and \(r_z(R)\) matrices respectively. After that, the loop is performed for different R.
- The first line of each group is an integer, recording the number of non-zero elements in the sparse matrix.
- The second to fourth lines of each group are in the csr format of the sparse matrix, recording the data, indices, and indptr information respectively.

Other file¶

For the calculation of some functions, structure files and NAOs (numerical atomic orbital bases) files are also required.

The structure file

This file describes the structural information about the system, e.g., lattice constant, lattice vectors, and positions of the atoms within a unit cell. The structure file format of ABACUS is currently used.
The NAOs files

This file describes the numerical atomic orbitals used to expand the Hamiltonian. The NAOs file format of ABACUS is currently used.