Dataset Format

Dataset Format#

This page documents the formats of the input data files required by the LibRPA driver.

Driver input names#

The standalone driver reads dataset files from input_dir. By default, single-file inputs are named stru_out, bz_sampling_out, basis_wfc_out, basis_aux_out, and band_out. Additional optional single-file inputs use dielecfunc_out, vxc_out, and band_kpath_info. These exact filenames can be changed in librpa.in with fn_stru, fn_bz_sampling, fn_basis_wfc, fn_basis_aux, fn_eigocc_scf, fn_dielfunc, fn_vxc_scf, and fn_band_kpath_info.

The combined basis_out file selected by fn_basis is deprecated and is read only as a fallback when split basis files are absent. When use_shrink_abfs = t, reader-v1 datasets should also provide basis_aux_shrink_out, or the filename selected by fn_basis_aux_shrink, for the compressed auxiliary basis. The old fn_basis_shrink input key is still accepted as an alias.

Multi-file inputs are selected by prefix. The defaults are Cs_data for localized RI coefficients, Cs_shrinked_data for compressed-auxiliary-basis RI coefficients, coulomb_mat for bare Coulomb matrices, coulomb_cut for truncated Coulomb matrices, and KS_eigenvector for SCF Kohn-Sham eigenvectors. These prefixes can be changed with prefix_lri_coeff, prefix_lri_coeff_shrink, prefix_coul_full, prefix_coul_cut, and prefix_eigvecs_scf. For example, prefix_coul_full = coulomb_mat matches files such as coulomb_mat_0.txt. For shrink reader-v1 datasets, keep the full and shrink coefficient families distinct, for example prefix_lri_coeff = v1_Cs_data_ and prefix_lri_coeff_shrink = v1_Cs_shrinked_data_. The LRI reader rejects identical full/shrink prefixes and filters the other family when one prefix is a leading substring of the other.

`stru_out`#

The file stru_out contains structural information.

Its contents are arranged in the following order:

Lattice vectors: 3 lines, each containing 3 floating-point numbers, in units of Bohr.
Reciprocal lattice vectors: 3 lines, each containing 3 floating-point numbers, in units of Bohr\({}^{-1}\).
Number of atoms: 1 line containing the number of atoms in the unit cell, n_atoms.
Atomic coordinates and types: n_atoms lines, each containing the Cartesian coordinates and the atom type of one atom.

After the atom rows, stru_out may end or may contain an optional tail. The tail can contain a symmetry block directly. In older files, the legacy Brillouin-zone section below may come before the symmetry block.

The symmetry block starts with one line containing the number of operations and the fractional-coordinate convention:

n_symops row

or

n_symops col

Use row for operations applied as x' = x * R + t. Use col for operations applied as x' = R * x + t, which is the Spglib convention. Each of the next n_symops lines contains one integer rotation matrix and one fractional translation:

R11 R12 R13 R21 R22 R23 R31 R32 R33 t1 t2 t3

Include the identity operation when providing the block; symmetry-enabled calculations require it.

Older stru_out files may also contain the following Brillouin-zone sampling entries. LibRPA no longer reads k-points from stru_out; datasets must provide bz_sampling_out.

k-point grid dimensions: 1 line containing three integers, nkx, nky, and nkz. The total number of k-points in the full grid is
```
nkpts = nkx * nky * nkz
```
Full k-point list: nkpts lines, each containing 3 floating-point numbers giving the Cartesian coordinates of one k-point, in units of Bohr\({}^{-1}\).
Mapping to irreducible k-points: nkpts lines, each containing 1 integer. Suppose the integer on the n-th line is m. This means that the irreducible representative of the n-th k-point in the full k-point set is the m-th k-point in the full set.

Basis files#

The split basis files basis_wfc_out, basis_aux_out, and basis_aux_shrink_out use the same format. They describe, respectively, the wave-function basis, the full auxiliary basis, and the shrink auxiliary basis.

The first line contains three entries:

total number of atom types, n_atom_types
total number of basis functions in this basis
a string specifying the convention used for the Bloch-sum phase, basis ordering, and real spherical harmonics

Recognized producer presets are aims, abacus, openmx, pyscf, and fallback. fallback means the convention is not known from this file.

For example:

2        26    abacus

The next n_atom_types lines provide the size for each atom type. Each line contains:

atom type index
number of basis functions for this atom type

For example:

1        13
2        13

The remaining content gives the l-shell layout. There are n_atom_types blocks, one for each atom type. In each block:

the first line contains the atom type index and the number of radial functions
the following lines list the angular momentum quantum number l for each radial function, one integer per line

For example:

Each radial function with angular momentum l contributes 2*l + 1 basis functions. In the example above, atom type 1 has 1 + 1 + 3 + 3 + 5 = 13 basis functions.

`basis_out` (deprecated)#

basis_out is the legacy combined basis file. New datasets should write basis_wfc_out, basis_aux_out, and, when use_shrink_abfs = t, basis_aux_shrink_out. The driver still reads basis_out as a fallback when basis_wfc_out and basis_aux_out are absent.

The first line contains four entries:

total number of atom types, n_atom_types
total number of wave-function basis functions
total number of auxiliary basis functions
the basis convention string

The next n_atom_types lines contain:

atom type index
number of wave-function basis functions for this atom type
number of auxiliary basis functions for this atom type

After that, basis_out stores the l-shell blocks for the wave-function basis, then the same block structure for the auxiliary basis.

`bz_sampling_out`#

This file describes the Brillouin-zone sampling used in the calculation, including the full k-point grid and its reduction to the irreducible set.

Its structure is as follows. The first line contains three integers:

nk1
nk2
nk3

These specify the number of k-point divisions along the three reciprocal lattice directions. For example:

3   3   3

The second line contains two integers:

number of SCF k-points, the same value as in band_out
number of irreducible k-points for Coulomb matrices

Here “SCF k-points” means the k-point dimension used to store SCF eigenvalues, occupation numbers, and Kohn-Sham eigenvectors in band_out and KS_eigenvector_xxx.txt.

For example:

27     14

This means that the Kohn-Sham SCF data contains 27 k-points, of which 14 are used as Coulomb-matrix representatives.

The next n_k_points lines describe the SCF k-points. Each line contains ten fields:

k-point index in the SCF set (1-based)
k-point weight; the sum over the n_k_points rows must be 1
fractional coordinate k1
fractional coordinate k2
fractional coordinate k3
Cartesian coordinate kx
Cartesian coordinate ky
Cartesian coordinate kz
index of the corresponding irreducible Coulomb k-point
index of its representative in the SCF k-point list

For example:

2   0.37037037037E-01   0.00000000000E+00   0.00000000000E+00   0.33333333333E+00   0.00000000000E+00   0.00000000000E+00   0.35439508162E+00   2   2

This line indicates that SCF k-point 2

has weight 0.037037037037
has fractional coordinates (0, 0, 1/3)
has Cartesian coordinates (0, 0, 0.35439508162)
maps to irreducible Coulomb k-point 2
whose representative in the SCF k-point list is also point 2

Older files may contain irreducible-k-point weight summaries after these rows. LibRPA ignores those summaries because the row weights above are already authoritative.

A few remarks

If the SCF k-point count equals nk1 * nk2 * nk3, no spatial symmetry was used to shrink the SCF k-list.
If that count is larger than the Coulomb irreducible count, time-reversal symmetry was used for Coulomb matrices.
If the SCF k-point count is smaller than nk1 * nk2 * nk3, spatial symmetry was used and stru_out must provide symmetry operations.

`Cs_data*`#

These files contain the localized RI triple coefficients. The same format rules apply to the files selected by prefix_lri_coeff_shrink, whose default prefix is Cs_shrinked_data.

LibRPA supports two reader versions:

version_lri_reader = 0: legacy text or legacy binary files
version_lri_reader = 1: binary v1 files with a block table and payload offsets
version_lri_reader = -1: auto-detect from the first file matching the prefix

Do not mix legacy and v1 files under the same prefix. Files are discovered by prefix only, so suffixes such as .txt, .dat, or no suffix are all accepted by the v1 reader. For full/shrink Cs reads, the two prefix families are treated as distinct; a full prefix must not select shrink files and vice versa.

Legacy text format#

In plain text format, each file has a header with two integers: total number of atoms and number of periodic unit cells. Then till the end of file, the data is formatted as blocks of RI coefficient \(C\) on each pair of atoms and unit cell

i_atom_1  i_atom_2  n_1  n_2  n_3  n_basis_1  n_basis_2  n_aux_basis_1
C(1, 1, 1)
...
C(n_aux_basis_1, n_basis_2, n_basis_1)

Here C is the RI coefficients between the atom i_atom_1 and i_atom_2 in unit cells separated by lattice vector \(\mathbf{R} = n_1 \mathbf{a}_1 + n_2 \mathbf{a}_2 + n_3 \mathbf{a}_3\). The auxiliary basis is located on i_atom_1. The number of basis functions on i_atom_1 and i_atom_2 are n_basis_1 and n_basis_2, respectively. The number of auxiliary functions is n_aux_basis_1. The indices of C runs in the Fortran order, i. e. the first index runs the fastest.

Equivalently, the file order is

for i in basis_1:
  for j in basis_2:
    for mu in aux_basis_1:
      C(mu, j, i)

and LibRPA stores the loaded block as a row-major matrix Cs(i * n_basis_2 + j, mu).

Legacy binary format#

In binary format, the data is organized similarly in the plain text format, except for an extra integer is included in the header, which is the number of atom pairs and lattice vectors included in the file. The coefficients are saved in double precision. To better illustrate the format of binary file, the following Python snippet could be helpful

import struct
import numpy as np

# ensure that "Cs_data_0" exists and was generated with binary output mode in DFT code
cfile_path = "Cs_data_0.txt"

with open(cfile_path, 'rb') as h:
    n_atoms, n_cells, n_apcell_file = struct.unpack('iii', h.read(12))
    for _ in range(n_apcell_file):
        a1, a2, r1, r2, r3, nb1, nb2, nbb1 = struct.unpack('i' * 8, h.read(4 * 8))
        apcell = (a1, a2, r1, r2, r3)
        array_size = nb1 * nb2 * nbb1
        array = np.array(struct.unpack('d' * array_size, h.read(8 * array_size)))
        array = np.reshape(array, (nb1, nb2, nbb1))
        apcells[apcell] = array

Binary v1 format#

The v1 LRI coefficient format is designed for random-access reading and parallel scheduling. It begins with a fixed-size binary header followed by a block table and dense double-precision payloads. All integer fields use native 32-bit or 64-bit binary representation as listed below, and all floating-point fields are native double precision.

Header:

Field	Type	Meaning
`marker`	`int32`	must be `-10267453`
`n_atoms`	`int32`	number of atoms
`n_cells`	`int32`	number of periodic unit cells represented by the dataset
`n_apcell_file`	`int64`	number of valid atom-pair/cell blocks in this file
`n_apcell_file_max`	`int64`	number of reserved block-table records

The header is followed by n_apcell_file_max block-table records. The first n_apcell_file records are valid; the remaining records, if any, must be zero-filled padding.

Each block-table record has the following fields:

Field	Type	Meaning
`i_atom_1`	`int32`	1-based atom index for the auxiliary-basis center
`i_atom_2`	`int32`	1-based atom index for the second orbital-basis center
`R1`, `R2`, `R3`	`int32`	unit-cell displacement between the two atoms
`max_abs`	`double`	maximum absolute coefficient in the block, used for threshold filtering
`offset`	`int64`	absolute byte offset of this block’s payload from the start of the file

The v1 record does not store n_basis_1, n_basis_2, or n_aux_basis_1. Those dimensions are reconstructed from the wave-function and auxiliary basis metadata that have already been loaded from the dataset, normally from basis_out:

n_basis_1     = number of wave-function basis functions on i_atom_1
n_basis_2     = number of wave-function basis functions on i_atom_2
n_aux_basis_1 = number of auxiliary basis functions on i_atom_1

The payload for one record contains n_basis_1 * n_basis_2 * n_aux_basis_1 double-precision values in the same logical order as the legacy format:

for i in basis_1:
  for j in basis_2:
    for mu in aux_basis_1:
      C(mu, j, i)

When writing or inspecting v1 files from Python, this corresponds to:

import struct
import numpy as np

marker = -10267453

with open("Cs_data_0.dat", "rb") as h:
    marker_read, n_atoms, n_cells = struct.unpack("iii", h.read(12))
    if marker_read != marker:
        raise ValueError("not an LRI coefficient v1 file")
    n_blocks, n_blocks_reserved = struct.unpack("qq", h.read(16))

    records = []
    for _ in range(n_blocks_reserved):
        ia1, ia2, r1, r2, r3 = struct.unpack("iiiii", h.read(20))
        max_abs, offset = struct.unpack("dq", h.read(16))
        records.append((ia1, ia2, (r1, r2, r3), max_abs, offset))

    ia1, ia2, R, max_abs, offset = records[0]
    # The dimensions come from basis_out. These are example values.
    n_basis_1, n_basis_2, n_aux_basis_1 = 5, 5, 18
    h.seek(offset)
    raw = h.read(8 * n_basis_1 * n_basis_2 * n_aux_basis_1)
    coeff = np.frombuffer(raw, dtype=np.float64).reshape(
        (n_basis_1, n_basis_2, n_aux_basis_1)
    )

Legacy Cs files can be converted one file at a time with:

c++ -std=c++17 -O2 -o convert_legacy_Cs.exe utilities/convert_legacy_Cs.cpp
./convert_legacy_Cs.exe Cs_data_0.txt Cs_data_0.dat --overwrite

Then set version_lri_reader = 1 in librpa.in, or leave version_lri_reader = -1 to auto-detect the v1 marker.

`band_out`#

This file contains band energies and occupation numbers from the mean-field starting-point calculation. It has a 5-line header

n_k_points
n_spins
n_states
n_basis
e_fermi

The first 4 lines contain an integer in each. The 5th line is a float number, which is the Fermi energy in Hartree unit.

The remaining lines consists of n_k_points*n_spins blocks of n_states+1 lines, in the format of

i_k_point    i_spin
1           f_1        e_1_ha      e_1_ev
2           f_2        e_2_ha      e_2_ev
3           f_3        e_3_ha      e_3_ev
...
n           f_n        e_n_ha      e_n_ev
...

This block contains the energies and occupation numbers of states \(\left|\psi_{n,k\sigma}\right\rangle\) i_k_point marks the index of SCF k-point \(k\). i_spin specify the spin channel \(\sigma\). In each of the following lines, the first integer species the index of state. The 3 float numbers stand for the occupation number, the energy in Hartree unit and that in electronvolt unit, respectively. For spin-unpolarized calculation, f_n is a number from 0 to 2, otherwise it is from 0 to 1.

`KS_eigenvector*`#

These files contain the wave functions (eigenvectors) from the starting-point calculation expanded by orbital basis. LibRPA auto-detects the legacy text format and the binary v1 format from the file header. Do not mix legacy and v1 files under the same prefix_eigvecs_scf.

Legacy text format#

Each file can be divided in blocks of n_states*n_basis*n_spins+1 lines, where n_states, n_basis and n_spins will be extracted from band_out. Each block stores the data for a particular k-point, \(c^i_{n,k\sigma}\):

i_k_point
c(1,1,1)_real c(1,1,1)_imag
...
c(i,n,s)_real c(i,n,s)_imag
...

The first line contains single integer, the index of the SCF k-point of following data. The remaining lines store the data with running index \(i\), \(n\), \(\sigma\) in C-style row-major order, i. e., spin index runs fastest, then state index and finally basis index. Each line has two float numbers, which are the real and imaginary part of \(c^i_{n,k\sigma}\).

Binary v1 format#

The binary v1 format is intended for parallel k-point reading. Values are native-endian; integers are int32 unless stated otherwise. The leading header stores:

int32 marker          = -12345679
int32 kind            = 28
int32 nkpoints_local
int32 nspins
int32 nstates
int32 nbasis_wfc

Only kind = 28, packed complex<double>, is currently implemented. Each complex number is stored as two consecutive double values, real then imaginary.

The header is followed by nkpoints_local block records:

int32 ik              # 1-based SCF k-point index
int64 payload_offset  # absolute byte offset in this file

Each payload block contains one k-point with nspins * nspinor * nstates * nbasis complex numbers. For non-spinor data, nspinor = 1 and nbasis = nbasis_wfc. For spinor data, nspinor = 2 and nbasis = nbasis_wfc / 2.

The payload order is:

for ispin
  for ispinor
    for istate
      for ibasis

where ibasis is the fastest index.

`velocity_matrix`#

This file stores the PyATB velocity matrix used by the head/wing correction. LibRPA auto-detects the legacy text format and the binary v1 format from the file header.

Legacy text format#

The legacy text file starts with:

nkpoints
nspins
nbands
naos

It then stores blocks ordered by spin, k-point, and Cartesian component:

ialpha ik ispin
v(1,1)_real v(1,1)_imag
...
v(i,j)_real v(i,j)_imag

All indices in the block header are 1-based.

Binary v1 format#

Values are native-endian. Integers are int32 unless stated otherwise. The leading header stores:

int32 marker          = -12345680
int32 kind            = 29
int32 nkpoints_local
int32 nspins
int32 nbands
int32 naos
int32 nalpha          = 3

Only kind = 29, packed complex<double>, is currently implemented. Each complex number is stored as two consecutive double values, real then imaginary.

The header is followed by nkpoints_local block records:

int32 ik              # 1-based source k-point index
int64 payload_offset  # absolute byte offset in this file

A parallel producer may split the source k-points across several files named velocity_matrix, velocity_matrix_1.dat, velocity_matrix_2.dat, etc. In that case each file uses its own nkpoints_local, while ik still refers to the 1-based index in k_path_info.

Each payload block contains one source k-point with nspins * 3 * nbands * nbands complex numbers. The payload order is:

for ispin
  for ialpha
    for iband
      for jband

where jband is the fastest index.

`coulomb_mat*`#

These files contain the bare Coulomb matrices in the auxiliary basis. The truncated Coulomb matrices used in GW are selected by prefix_coul_cut, whose default prefix is coulomb_cut, and use the same formats.

LibRPA supports two reader versions:

version_coul_reader = 0: legacy text or legacy binary rectangular matrix blocks
version_coul_reader = 1: binary v1 files with atom-pair blocks
version_coul_reader = -1: auto-detect from the first file matching the prefix

Do not mix legacy and v1 Coulomb files under the same prefix. The legacy reader expects filenames that both start with the selected prefix and end in .txt. The v1 reader discovers files by prefix only, so binary files such as coulomb_full_iq_1.dat are accepted if prefix_coul_full = coulomb_full_iq.

Legacy text format#

A single header line contains an integer, the number of irreducible k-point at which the Coulomb matrices are computed. The remaining part of the file is organized in blocks

n_aux_basis    row_start    row_end    col_start    col_end
i_k_point      k_weight
v(row_start, col_start  )_real       v(row_start, col_start  )_imag
v(row_start, col_start+1)_real       v(row_start, col_start+1)_imag
...
v(row_end, col_end)_real             v(row_end, col_end)_imag

where

integer n_aux_basis is the total number of auxiliary basis functions.
integer row_start, row_end, col_start and col_end mark the submatrix of the full Coulomb matrix that this block contain.
integer i_k_point is the index of k-point of the current Coulomb matrix, in the full k-point list.
float number k_weight is the weight of the irreducible k-points.

After the block header, there should be (row_end-row_start+1) times (col_end-col_start+1) lines for the actual matrix element data. Each line contains two float numbers, which are the real and imaginary parts of the element. The data is ordered in C-style row major.

Legacy binary format#

The legacy binary Coulomb format stores the same rectangular blocks as the legacy text format. It starts with two native int32 values:

total number of irreducible q-points
number of q-point blocks stored in this file

Each q-point block then contains:

Field	Type	Meaning
`n_aux_basis`	`int32`	total number of auxiliary basis functions
`row_start`, `row_end`	`int32`	1-based inclusive row range
`col_start`, `col_end`	`int32`	1-based inclusive column range
`i_q_point`	`int32`	1-based q-point index in the full k-point list
`q_weight`	`double`	weight of the irreducible q-point
payload	`complex<double>[]`	dense row-major block values

Here complex<double> is stored as two consecutive double values, real part first and imaginary part second.

Binary v1 atom-pair format#

The v1 Coulomb format stores one q-point per file. Each file contains dense atom-pair blocks in the auxiliary basis. Only upper-triangular atom pairs I <= J are stored because the full matrix is Hermitian.

Header:

Field	Type	Meaning
`marker`	`int32`	must be `-20129433`
`i_q_point`	`int32`	1-based q-point index in the full k-point list
`n_aux_basis`	`int32`	total number of auxiliary basis functions
`value_flag`	`int32`	`0` for real double payloads, `1` for complex payloads
`n_atoms`	`int32`	number of atoms
`n_blocks`	`int32`	number of stored atom-pair blocks

The header is followed by n_atoms int32 values giving the number of auxiliary basis functions on each atom. These counts must sum to n_aux_basis and must match basis_out.

Next comes a block table with n_blocks records:

Field	Type	Meaning
`i_pair`	`int32`	zero-based upper-triangular atom-pair index
`offset`	`int64`	absolute byte offset of this atom-pair payload

The atom-pair index enumerates upper-triangular pairs in this order:

(0,0), (0,1), ..., (0,n_atoms-1), (1,1), (1,2), ...

For a pair (I, J) with I <= J, the corresponding index is:

i_pair = I * n_atoms - I * (I - 1) / 2 + (J - I)

Each payload is a dense row-major matrix of shape (n_aux_basis_on_atom_I, n_aux_basis_on_atom_J). If value_flag = 1, values are stored as complex<double> pairs real, imag. If value_flag = 0, values are stored as real double values and LibRPA sets the imaginary part to zero.

Unlike the legacy format, v1 Coulomb files do not store q-point weights. Keep bz_sampling_out in the dataset so q-point weights and irreducible q-point mapping are available separately.

A minimal Python reader for the v1 header and the first atom-pair block is:

import struct
import numpy as np

marker = -20129433

with open("coulomb_full_iq_1.dat", "rb") as h:
    header = struct.unpack("iiiiii", h.read(24))
    marker_read, iq, naux, value_flag, n_atoms, n_blocks = header
    if marker_read != marker:
        raise ValueError("not a Coulomb v1 file")

    atom_naux = struct.unpack(f"{n_atoms}i", h.read(4 * n_atoms))
    table = []
    for _ in range(n_blocks):
        i_pair = struct.unpack("i", h.read(4))[0]
        offset = struct.unpack("q", h.read(8))[0]
        table.append((i_pair, offset))

    i_pair, offset = table[0]
    nrow, ncol = atom_naux[0], atom_naux[0]
    h.seek(offset)
    if value_flag == 1:
        block = np.frombuffer(h.read(16 * nrow * ncol), dtype=np.complex128)
    else:
        block = np.frombuffer(h.read(8 * nrow * ncol), dtype=np.float64)
    block = block.reshape((nrow, ncol))

Legacy Coulomb files can be converted to v1 with the MPI converter:

mpicxx -std=c++17 -O2 -o convert_legacy_coulomb_mat_mpi.exe \
  utilities/convert_legacy_coulomb_mat_mpi.cpp
mpirun -np 4 ./convert_legacy_coulomb_mat_mpi.exe /path/to/dataset \
  -i coulomb_mat -o coulomb_full_iq

Use the generated prefix in librpa.in:

prefix_coul_full = coulomb_full_iq
version_coul_reader = 1

For truncated Coulomb data, convert the coulomb_cut files with a separate output prefix and set prefix_coul_cut accordingly.

`coulomb_cut*`#

These files are the same as coulomb_mat*, but store the truncated Coulomb to be used in the GW calculation.

`dielecfunc_out`#

The file dielecfunc_out stores the macroscopic dielectric function on the imaginary-frequency grid used for dielectric-head correction.

Each data line contains three columns:

imaginary frequency
real part of the dielectric function
imaginary part of the dielectric function

LibRPA reads the first two columns for the imaginary-frequency dielectric function; the third column is accepted for compatibility with exported data that writes complex values.

`vxc_out`#

The file vxc_out stores the exchange-correlation potential for electronic states on the SCF k-point grid.

The header consists of three lines:

n_k_points
n_spins
n_states

The header is followed by n_k_points * n_spins * n_states data lines. Each line contains two columns and corresponds to one state identified by the tuple (i_k, i_spin, i_state). The data are ordered such that i_state runs fastest, followed by i_spin, and then i_k. In other words, the lines are arranged as

# i_k       i_spin      i_state
    0            0            0
    0            0            1
    0            0            2
...
    0            0   n_states-1
    0            1            0
...
    1            0            0
...

The two columns contain the same exchange-correlation potential, first in Hartree unit while the second in eV.

Input files for band structure calculation#

For band-structure calculations, LibRPA reads the following input files:

band_kpath_info
band_KS_eigenvalue_k_{ik:05d}.txt
band_KS_eigenvector_k_{ik:05d}.txt
band_vxc_k_{ik:05d}.txt

Here ik is the 1-based index of the k-point along the band path, written with five digits.

`band_kpath_info`#

The file band_kpath_info defines the k-point path used for the band-structure calculation.

The first line contains four integers:

number of basis functions
number of states
number of spin channels
number of k-points on the band path

For example:

18    18     1    10

The remaining n_kpath_points lines each contain three floating-point numbers, giving the fractional coordinates of one k-point on the band path.

For example:

0.500000000000000000E+00   0.500000000000000000E+00   0.500000000000000000E+00

Each such line represents one k-point in fractional reciprocal coordinates.

`band_KS_eigenvalue_k_{ik:05d}.txt`#

For each k-point on the band path, the file band_KS_eigenvalue_k_{ik:05d}.txt stores the Kohn-Sham eigenvalues used by LibRPA. Each line corresponds to one state and contains five columns:

spin index
state index
occupation number
Kohn-Sham eigenvalue in Hartree
Kohn-Sham eigenvalue in eV

For example:

1       3   0.200000000000000000E+01  -0.658097773108510893E+02  -0.179077515426494506E+04

This line indicates that, at the selected k-point,

the spin index is 1
the state index is 3
the occupation number is 2.0
the eigenvalue is given both in Hartree and in eV

The data are ordered such that state index i_state runs fastest and followed by spin index i_spin.

`band_vxc_k_{ik:05d}.txt`#

For each k-point on the band path, the file band_vxc_k_{ik:05d}.txt stores the diagonal matrix elements of the exchange-correlation potential for the corresponding Kohn-Sham states.

Each line contains three columns:

spin index
state index
exchange-correlation potential in Hartree

For example:

1       3  -0.562542321738239171E+01

This line gives the exchange-correlation potential for state 3 in spin channel 1 at the selected k-point. The data are ordered such that state index i_state runs fastest and followed by spin index i_spin.

`band_KS_eigenvector_k_{ik:05d}.txt`#

For each k-point on the band path, the file band_KS_eigenvector_k_{ik:05d}.txt stores the Kohn-Sham eigenvectors at that k-point. The file contains a complex array of shape (n_spins, n_states, n_basis), written in binary format using C-style ordering.

Shrink transform v1 format#

When use_shrink_abfs = t, prefix_shrink_sinvS selects the transform from the compressed auxiliary basis back to the full auxiliary basis. The default legacy prefix is shrink_sinvS_; reader-v1 producer runs should use v1_shrink_sinvS_.

The reader-v1 binary format starts with:

int32 marker = -30241621
int32 nblocks

Each block record stores:

int32 iq (1-based irreducible q-point index)
int32 nrow_total, int32 ncol_total
int32 begin_row, int32 end_row, int32 begin_col, int32 end_col
double q_weight
int64 payload_offset

The payload is row-major complex<double> data for the rectangular block described by the row and column range. Multiple files and blocks may contribute to the same q-point.

Dataset Format

Contents

Dataset Format#

Driver input names#

stru_out#

Basis files#

basis_out (deprecated)#

bz_sampling_out#

Cs_data*#

Legacy text format#

Legacy binary format#

Binary v1 format#

band_out#

KS_eigenvector*#

Legacy text format#

Binary v1 format#

velocity_matrix#

Legacy text format#

Binary v1 format#

coulomb_mat*#

Legacy text format#

Legacy binary format#

Binary v1 atom-pair format#

coulomb_cut*#

dielecfunc_out#

vxc_out#

Input files for band structure calculation#

band_kpath_info#

band_KS_eigenvalue_k_{ik:05d}.txt#

band_vxc_k_{ik:05d}.txt#

band_KS_eigenvector_k_{ik:05d}.txt#

Shrink transform v1 format#

`stru_out`#

`basis_out` (deprecated)#

`bz_sampling_out`#

`Cs_data*`#

`band_out`#

`KS_eigenvector*`#

`velocity_matrix`#

`coulomb_mat*`#

`coulomb_cut*`#

`dielecfunc_out`#

`vxc_out`#

`band_kpath_info`#

`band_KS_eigenvalue_k_{ik:05d}.txt`#

`band_vxc_k_{ik:05d}.txt`#

`band_KS_eigenvector_k_{ik:05d}.txt`#