Driver Usage#

Data preparation#

To run the LibRPA driver for RPA/GW calculation, you need to export necessary data from atomic-basis first-principles code. The data include

  • Atomistic structure

  • one-particle orbital energies, occupation numbers and wave functions

  • Bloch vectors used in periodic calculation

  • Triple co-efficients of resolution of identity (RI)

  • Coulomb matrix under the auxiliary basis for RI

FHI-aims#

Export of data required by LibRPA from FHI-aims is supported since the release version 231212 and also in the latest master branch. You can switch it on by adding to your control.in file:

output librpa
# legacy switch before 240507 release
print_librpa_input .true.

It will dump necessary data files for many-body computation tasks. Please refer to the FHI-aims manual for more details of the output librpa tag.

ABACUS#

Similar to the case with FHI-aims, the latest master branch of ABACUS supports the export of files required by LibRPA. You only need to add the following line to the INPUT file of ABACUS:

rpa 1

LibRPA job#

Input file#

Before triggering the LibRPA driver, an input file named librpa.in is required at the working directory. An example is below:

task = rpa
input_dir = .
nfreq = 16
cs_threshold = 1e-4

The driver will read the parameters defined in the file and run the calculation Please refer to the guide page of runtime parameters for more information about the driver and API parameters.

By default, input_preset = fhi-aims (also accepted as aims) preserves the historical driver filenames, including stru_out, basis_out, band_out, mommat_ks_kpt_*.dat, Cs_data_*, and coulomb_mat_* under input_dir. For current ABACUS output, select:

input_preset = abacus

This selects the short reader-v1 names: stru_out.txt, band_out.txt, vxc.txt, bz_sample.txt, basis_map.txt, wfc_basis.txt, aux_basis.txt, aux_basis_s.txt, KS_wfc_*, Cs_*, Cs_shrink_*, sinvS_*, V_cut_*, and V_full_*. It also changes prefix_velocity to velocity_matrix.

PyATB head/wing sidecars retain their KS_eigenvector_* filename contract. LibRPA reads those files independently of the KS_wfc_* ABACUS preset.

For ABACUS datasets produced before PR #7849 (merge commit 42f8ad905d56 on develop), select:

input_preset = abacus-legacy

If a host code exports the same data under different names, set the corresponding fn_* or prefix_* driver parameters in librpa.in:

fn_eigocc_scf = band_out_alt
prefix_lri_coeff = Cs_data_alt
prefix_coul_full = coulomb_mat_alt
prefix_coul_cut = coulomb_cut_alt

If stru_out contains symmetry operations, the driver builds a symmetry context from the structure, basis metadata, and k-point grids. Runtime use_symmetry_* switches then decide whether calculation paths use that context.

QSGW with an optional band path#

Use task = qsgw for molecular and periodic QSGW. The driver also computes the band-path channel when the file selected by fn_band_kpath_info (default band_kpath_info) exists under input_dir; this requires matching band energies, wavefunctions, and full Vxc matrices. Without the metadata file, only the SCF grid is computed, including for periodic inputs. The driver does not infer geometry or create a path. qsgw is the only QSGW task name; older inputs must switch their task value to qsgw.

Mixing is selected automatically after SCF input validation. One global SCF k point with a full BvK mesh product of 1 permits none or linear; other SCF meshes force effective none with beta 1, including a one-point IBZ of a larger mesh. The default mixer remains none. For a single-k supercell, for example:

qsgw_mixer = linear
qsgw_mixing_beta = 0.2

The log records requested/effective mixer, SCF count and mesh. This input convention does not detect physical isolation: a Gamma-only solid also enters the single-k route and can use none. Band-path presence/count does not affect the route; grid and path use the same effective beta. Geometry, Coulomb and head/wing settings remain unchanged. Remove the obsolete qsgw_system_type key from input files.

With band inputs, the existing band-cut options remain active and each iteration writes KS_band_spin_S_N.dat, EXX_band_spin_S_N.dat, and QSGW_band_spin_S_N.dat for plotting. Native per-update QP diagnostics are written when qsgw_output_qp = true; see QSGW. The driver writes energy data rather than PNG figures. Continue a checkpoint with the same band-channel presence and original band inputs. See QSGW for the full Vxc input, option-6 head/wing feedback, output and restart requirements.

Native G0W0 head/wing velocity#

For analytic head/wing correction, the standalone g0w0 driver and its g0w0_band alias accept option_dielect_func = 6. This experimental preset adds an internal velocity calculation from the original DFT H(R), S(R), and r(R), then uses the existing option-3 analytic head/wing prescription. Velocity is evaluated in the SCF eigenframe already loaded by the driver, retaining the SCF energies, wavefunctions, occupations, and frequency/response prescription. No PyATB velocity export or second eigensolve is required.

An ABACUS example, in addition to the ordinary RI/Coulomb and mean-field inputs, is:

task = g0w0
input_preset = abacus
replace_w_head = true
option_dielect_func = 6
use_scalapack_gw_wc = true
g0w0_fn_hr = OUT.ABACUS/data-HR-sparse_SPIN0.csr
g0w0_fn_sr = OUT.ABACUS/data-SR-sparse_SPIN0.csr
g0w0_fn_rr = OUT.ABACUS/data-rR-sparse.csr
g0w0_hr_unit = Ry
g0w0_rr_unit = Bohr
use_pyatb = false
use_kpara_scf_eigvec = false
use_symmetry_rpa = false
use_symmetry_gw = false
use_symmetry_exx = false

Option 6 requires replace_w_head = true, use_scalapack_gw_wc = true, and use_pyatb = false. It selects g0w0_headwing_velocity = native when the selector is omitted; an explicit native is also accepted, while an explicit file is rejected. The driver log records requested option 6 and effective numerical option 3. Other tasks reject option 6. Direct library/API callers must use option 3 and either supply velocity through the public setter or construct it with librpa_prepare_native_velocity; option 6 is resolved only by the standalone G0W0 driver.

The previous explicit selection remains supported with the same H/S/r inputs and other settings. Native option 3 also requires use_scalapack_gw_wc = true to consume the analytic wings:

option_dielect_func = 3
g0w0_headwing_velocity = native

Use filenames that match the producer. For two collinear spin channels, also set g0w0_fn_hr_spin1 to the second spin’s Hamiltonian. Paths can be absolute or relative to input_dir; H, S and r retain their independent real-space supports. H units can be Ha, Ry or eV, and position units Bohr or Angstrom. Units are decoded once into Ha/Bohr. S is dimensionless, and the structure reader supplies the lattice in Bohr. Option 4 uses the same native velocity for the existing analytic head-only prescription. The g0w0_band task alias accepts the same options.

The current native mode requires complete square AO/band frames and a uniform full-BZ mesh, with scalar or SOC wavefunctions. Symmetry reduction and k-point-parallel SCF eigenvectors are unsupported. It checks the metric residual against 1e-6, Hamiltonian frame and Hermiticity residuals against 1e-4 eV, and the imaginary velocity diagonal against 1e-8 Ha Bohr. These input checks establish frame consistency within their tolerances; they do not certify material or basis convergence.

For options 3 and 4, the default g0w0_headwing_velocity = file preserves the existing reader. Option 6 does not change either existing prescription. With output_level = debug, either path writes g0w0_velocity.csv and g0w0_headwing.csv under output_dir, containing complete complex velocity, head and auxiliary-wing arrays. The head/wing snapshot is written before Wc consumes the auxiliary wing. These diagnostic files do not change the response calculation.

Run the calculation#

After setting up the input file librpa.in, the LibRPA driver can be called by issuing:

/path/to/LibRPA/build/chi0_main.exe

To run with multiple processes using MPI, you can simply invoke the relevant MPI driver, for example

mpirun -np <nprocs> /path/to/LibRPA/build/chi0_main.exe

where <nprocs> is the number of MPI processes. In addition, you want to run with multiple threads, you need to specify the environment variable OMP_NUM_THREADS. For example

export OMP_NUM_THREADS=4
mpirun -np 4 /path/to/LibRPA/build/chi0_main.exe

This will run the LibRPA calculation using 4 MPI processes, each with 4 OpenMP threads.

Task-specific guides#