Runtime Parameters#
Runtime parameters and options in LibRPA are generally managed through the LibrpaOptions object.
When using the API, assign values to the corresponding attributes before calling compute routines. API defaults are set by librpa_init_options(), the C++ librpa::Options constructor, or
opts%init()in the Fortran API.When using the driver, parameters are read from
librpa.inin the working directory usingkey = valuesyntax. Unlike the API, the driver requirestaskto be explicitly specified.
Note
Rows marked Experimental expose development, diagnostic, or less-tested code paths.
Use them as opt-in features and validate results against reference calculations before production use.
For API use, switch values are set with LIBRPA_SWITCH_ON and LIBRPA_SWITCH_OFF in C/C++.
The Fortran wrapper exposes these fields as logical values.
Overview#
Driver#
These parameters are available only through the standalone driver.
Parameter Name |
Description |
Default Value |
Since |
|---|---|---|---|
Physical constants source. |
|
||
Screening threshold when reading RI coefficient data. |
1e-6 |
||
Last state index for printed QP energies, exclusive. |
999999 |
||
First state index for printed QP energies, inclusive. |
0 |
||
Output quasiparticle energies for external BSE workflows. |
false |
||
Output GW spectral-function data. |
false |
||
Output GW energies for HamGNN machine-learning workflows. |
false |
||
Verbosity level for driver output. |
|
||
Ending frequency for spectral-function output. |
1.0 |
||
Starting frequency for spectral-function output. |
0.0 |
||
Frequency step for spectral-function output. |
0.1 |
||
Last state index for spectral-function output, exclusive. |
-1 |
||
First state index for spectral-function output, inclusive. |
-1 |
||
Task type. |
required ( |
||
Use PyATB mean-field data for dielectric head/wing calculations. |
false |
||
Read wavefunctions in spinor format. |
false |
Input Files#
These parameters are used to locate dataset files.
Filename parameters are interpreted relative to input_dir.
Prefix parameters match all files in input_dir whose names begin with the given value.
Parameter Name |
Description |
Default Value |
Since |
|---|---|---|---|
Band-path k-point metadata filename. |
|
||
Deprecated combined basis-set fallback filename. |
|
||
Auxiliary-basis metadata filename. |
|
||
Compressed auxiliary-basis metadata filename used with |
|
Unreleased |
|
Wave-function basis metadata filename. |
|
||
Brillouin-zone sampling filename. |
|
||
Dielectric-function filename for dielectric-head correction. |
|
||
SCF eigenvalue and occupation filename. |
|
||
Structure-data filename. |
|
||
SCF exchange-correlation potential filename. |
|
||
Input directory to find and read the AO dataset. |
|
||
Preset for producer-specific input filenames and head/wing velocity readers. |
|
||
Prefix of truncated Coulomb matrix files. |
|
||
Prefix of bare Coulomb matrix files. |
|
||
Bare three-dimensional Coulomb prefix for |
empty (required for task=hartree or qsgw_update_hartree=true) |
||
Prefix of SCF Kohn-Sham eigenvector files. |
|
||
Prefix of localized RI coefficient files. |
|
||
Dedicated unwrapped, full-precision LRI coefficient prefix for Hartree |
empty (required when qsgw_update_hartree=true) |
Unreleased |
|
Prefix of compressed-auxiliary-basis RI coefficient files. |
|
||
Prefix of shrink auxiliary-basis transform files. |
|
Unreleased |
|
Prefix of velocity/momentum-matrix files. |
|
||
Coulomb reader-version selector. |
-1 |
||
Local RI coefficient reader-version selector. |
-1 |
Hartree operator#
The experimental standalone task = hartree builds complete spatial AO
matrices from the loaded physical density. It requires an explicit bare
three-dimensional q=0 metric with reciprocal G=0 set to zero; no ordinary
EXX Coulomb prefix is substituted. See the Hartree guide.
This endpoint does not update the QSGW Hamiltonian.
Parameter Name |
Description |
Default Value |
Since |
|---|---|---|---|
Positive maximum complex AO-entry comparison tolerance, in Hartree. |
-1 (report only) |
||
Optional complete complex ABACUS Hartree H(R) CSR reference. |
empty |
||
Reference CSR energy conversion to Hartree (0.5 for Rydberg input). |
0.5 |
Sternheimer RPA#
These experimental driver parameters select aggregate or partial Sternheimer response inputs. This is the consumer-side v1 contract; the producer/export implementation is outside this change and the format remains provisional.
A Sternheimer chi0 v1 response file is a native-endian binary file with marker -41073291.
Its header is: int32 iq (one-based), int32 ifreq (one-based), int32 naux, int32 value_flag
(0 for real double or 1 for complex
omega and frequency weight are in Hartree; q-point weights are dimensionless BZ weights.
In a partial run, fn_sternheimer_partial_manifest rows are iq ik_full ifreq response_file
with one-based iq/ifreq and zero-based ik_full. The file
v1_sternheimer_full_kpoints.dat is required beside that manifest; its rows are contiguous
zero-based ik_full kx ky kz records covering the full BvK grid. If symmetry route files
are supplied, both start with version 1: fixed-q routes use one-based iq and zero-based
k indices, while q-star member_iq is one-based; each inverse route maps a stored member
back to its representative using spatial_isym, time_reversal, and fold_G exactly as recorded.
A minimal partial-mode setup is: fn_sternheimer_qpoints = v1_sternheimer_qpoints.dat fn_sternheimer_partial_manifest = v1_sternheimer_partial_manifest.dat prefix_coul_full = v1_coulomb_full_iq_ prefix_sternheimer_reconstructed = v1_sternheimer_reconstructed_iq_ The q-point manifest must include Gamma even when use_rpa_gamma is false, because the manifest describes the producer grid. An analytic head/wing replacement enabled through replace_w_head with option_dielect_func=3 or 4 overrides that exclusion and includes Gamma in the RPA sum; qavg head/wing additionally requires option_dielect_func=3.
Parameter Name |
Description |
Default Value |
Since |
|---|---|---|---|
Sternheimer partial-response manifest with rows |
empty |
||
Sternheimer q-point manifest filename with rows |
empty |
||
Explicit inverse routes from every full-q member to the discrete |
empty |
||
Explicit fixed-q inverse routes provided by the producer for reconstruction |
empty |
||
Prefix of Sternheimer chi0 v1 response files. |
|
||
Optional prefix for fixed-q k-resolved Sternheimer response matrices. |
empty |
||
Optional prefix for reconstructed full-q Sternheimer chi0 v1 files. |
empty |
||
Optional prefix for fixed-q Sternheimer symmetry route diagnostics. |
empty |
||
One-based q index for Sternheimer-RPA postprocessing. |
1 |
||
Reconstruct only fixed-q aggregate and k-resolved response matrices. |
false |
||
q-point weight for Sternheimer-RPA postprocessing. |
1.0 |
||
Include the Gamma-point contribution in the reported RPA q sum. |
true |
Common Settings#
Parameter Name |
Description |
Default Value |
Since |
|---|---|---|---|
Maximal transition energy when generating minimax grids. |
-1.0 |
||
Minimal transition energy when generating minimax grids. |
-1.0 |
||
Regulation for minimax grids generation. |
0.0 |
||
Number of time/frequency points. |
16 |
||
BvK remapping convention for band interpolation. |
1 |
||
Output directory for results. |
librpa.d/ |
||
Scheme of parallelization. |
LIBRPA_ROUTING_AUTO |
||
Directory to read restart checkpoint files from. Empty uses |
empty |
||
Frequency interval for even-spaced grids, in Hartree. |
0.0 |
||
Maximum frequency for grid generation, in Hartree. |
1000.0 |
||
Minimum frequency for grid generation, in Hartree. |
0.005 |
||
Time interval for even-spaced grids, in Hartree^-1. |
0.0 |
||
Minimum time for grid generation, in Hartree^-1. |
0.005 |
||
Type of time/frequency grids. |
LIBRPA_TFGRID_UNSET |
||
Flag to specify parallel distribution of eigenvectors of SCF starting point. |
false |
||
Threshold for real-space Coulomb matrices. |
0.0 |
Coulomb Matrices#
Parameter Name |
Description |
Default Value |
Since |
|---|---|---|---|
Switch of outputting ABACUS-compatible GW Green’s-function data. |
false |
||
Switch of using full Coulomb interaction in \(\varepsilon = 1 - v \chi^0\). |
true |
||
Switch of using full Coulomb interaction in exact-exchange operator. |
false |
||
Switch of using full Coulomb interaction in \(W^c = (\varepsilon^{-1} - 1) v\). |
false |
||
Switch of using the symmetry context in exact-exchange paths. |
false |
||
Switch of using the symmetry context in GW paths. |
false |
||
Switch of using the symmetry context in RPA/chi0 paths. |
false |
Response function#
These parameters may affect subsequent calculations using response function as input, e.g. RPA, GW.
Parameter Name |
Description |
Default Value |
Since |
|---|---|---|---|
Method to compute the response function chi0. |
LIBRPA_METHOD_AUTO |
||
Threshold for real-space Green’s function in response function calculation. |
0.0 |
||
Maximum estimated local chi0 tensor bytes per LibRI collection chunk; 0 keeps one-shot collection. |
0 |
||
Number of first-index atoms per LibRI chi0 collection chunk; 0 keeps one-shot collection. |
0 |
||
Maximal number of bands for computing response function. |
-1 (< 0 for all bands) |
||
Number of lowest bands excluded from both Green’s functions forming the response function. |
0 |
RPA correlation#
Parameter Name |
Description |
Default Value |
Since |
|---|---|---|---|
Flag to control whether to use ScaLAPACK to compute RPA correlation energy. |
true |
Constrained RPA#
These experimental driver parameters apply to standalone task = crpa
and optional U evaluation during task = g0w0 or task = qsgw with crpa_enabled = true.
crpa_model_file reuses an existing cRPA input. G0W0 evaluates U once;
during QSGW, crpa_interval selects entering state indices and the final
updated state is always evaluated.
Orbital analysis is enabled by default for scalar and two-component spinor states;
With standalone task = crpa, crpa_analysis_only = true skips RI/Coulomb
inputs and screening for window inspection; neither A nor B is required.
Coupled GW calculations require crpa_analysis_only = false.
For screening with crpa_response_mode = bands, A selects the original KS
bands on both branches of the excluded response Pd; specify exactly one
A energy-window or band-list selector. With crpa_response_mode = orbital_weights,
both A selectors must be omitted, including in analysis-only runs.
B independently selects the band space used to construct local output
orbitals; screening in either response mode requires exactly one B
energy-window or band-list selector.
Calculations use scalar or spinor full-grid LIBRI and native positive imaginary
frequencies; see the cRPA guide for supported numerical settings,
orbital conventions and the distinction between the first node and U(0).
Parameter Name |
Description |
Default Value |
Since |
|---|---|---|---|
Analyze orbital character only; skip RI/Coulomb input and screening. |
false |
Unreleased |
|
Species supplying first-radial correlated atomic trials for the declared parent frame. |
Empty |
Unreleased |
|
Compute cRPA U during G0W0 ( |
false |
Unreleased |
|
Positive imaginary broadening for requested real-frequency interactions, in eV. |
0.05 |
Unreleased |
|
Absolute tolerance for static/real-axis subset and node residual diagnostics, in eV. |
0.01 |
Unreleased |
|
Electronic-state interval for cRPA during QSGW; the final state is always evaluated. |
1 |
Unreleased |
|
Species supplying the first radial p shell of a dp parent frame. |
Empty |
Unreleased |
|
Import only cRPA model/analysis parameters from an existing native input file. |
none |
Unreleased |
|
B: distinct zero-based original KS indices shared by all spin/k points. |
Empty |
Unreleased |
|
B: inclusive absolute-Hartree lower/upper pairs for projecting atomic trials. |
Empty |
Unreleased |
|
Output Mulliken/Lowdin weights and Gaussian PDOS before cRPA screening. |
true |
Unreleased |
|
Native model output container: npz or human-readable dat files. Both retain the same model. |
npz |
Unreleased |
|
Save current E/f, complex parent/output projectors, H/density and U in compact NumPy |
true |
Unreleased |
|
Reported subset of the jointly normalized parent frame: s, p, sp, d, dp, eg or t2g. |
d |
Unreleased |
|
Include C, S and AO coefficients Phi in the model archives for changing the local frame. |
false |
Unreleased |
|
Estimate U(0) with native Padé of U-v; retain entrywise numerical status and fit spread. |
true |
Unreleased |
|
Native spatial or interleaved SOC S(R) CSR input, relative to the main |
SR.csr |
Unreleased |
|
Atomic trials projected into B and jointly metric-normalized: s, p, sp, d, dp, eg or t2g. |
d |
Unreleased |
|
Upper PDOS grid edge in eV relative to |
14 |
Unreleased |
|
Lower PDOS grid edge in eV relative to |
-10 |
Unreleased |
|
PDOS energy zero: vbm (highest occupied KS pole) or fermi. |
vbm |
Unreleased |
|
Gaussian standard deviation in eV (not FWHM). |
0.15 |
Unreleased |
|
PDOS grid spacing in eV. |
0.02 |
Unreleased |
|
Real frequencies in eV relative to bosonic zero; an empty list skips real-axis output. |
Empty |
Unreleased |
|
Positive metric/KS orthogonality tolerance. Frobenius residual gates use |
1.0e-10 |
Unreleased |
|
A: distinct zero-based original KS indices shared by all spin/k points. |
Empty |
Unreleased |
|
Response rule: bands uses binary A windows/lists; orbital_weights uses |
bands |
Unreleased |
|
A: inclusive absolute-Hartree lower/upper pairs selecting original KS states |
Empty |
Unreleased |
|
Explicit species labels in numeric structure-type order, separated by spaces. |
Empty |
Unreleased |
|
Transport the complete parent Phi through B after each QSGW update, without screening. |
false |
Unreleased |
|
Smallest retained probability of a previous parent direction; default 0.99. |
0.99 |
Unreleased |
ABF Compression#
Parameter Name |
Description |
Default Value |
Since |
|---|---|---|---|
Flag to use a compressed auxiliary basis. |
false |
||
Flag to compress response function using shrinked basis. |
true |
GW#
Parameter Name |
Description |
Default Value |
Since |
|---|---|---|---|
Relative maximum source residual requested by AAA. |
1.0e-13 |
||
Analytic continuation method for GW energies, spectra and QSGW matrices. |
LIBRPA_ANACON_PADE |
||
Number of points in the optional GW analytic-continuation frequency grid. |
-1 |
||
Relative ridge penalty on denominator coefficients. |
10.0 |
||
Ridge penalty on scaled nonconstant rational coefficients. |
1.0e-12 |
||
Type of optional frequency grid used for GW analytic continuation. |
LIBRPA_TFGRID_UNSET |
||
Absolute zero-based reference state index for Hedin shifts. |
-1 |
||
Number of lowest bands excluded from the Green’s function multiplying Wc in the correlation self-energy. |
0 |
||
Maximal number of bands for computing correlation self-energy. |
-1 (< 0 for all bands) |
||
Pade selected-node count, AAA support cap, or ridge coefficient count. |
-1 (uses the source point count) |
||
Number of parameters for the source-grid fit used to resample GW analytic continuation. |
-1 |
||
Option of computing dielectric function on imaginary axis. |
0 |
||
Quasi-particle equation solver option. |
0 |
||
If enabled, keep the final unconverged QPE iterate instead of outputting NaN. |
false |
||
Damping factor for quasi-particle equation solver updates. |
0.1 |
||
Maximum number of iterations for the quasi-particle equation solver; must be positive. |
10000 |
||
Convergence threshold for the quasi-particle equation solver, in Hartree. |
1.0e-6 |
||
Flag of reading NAO correlation self-energy matrix in real-space/frequency form. |
false |
||
Flag of replacing head of screened interaction by macroscopic dielectric function. |
false |
||
First regular Coulomb-eigenbasis channel used by RPA head/wing correction. |
0 |
||
RPA Gamma correction mode: “qavg” keeps the current head/wing q-average, |
|||
Broadening/shift used for Green’s function in spectral-function output, in Hartree. |
0.01 |
||
Broadening/shift used for correlation self-energy in spectral-function output, in Hartree. |
0.01 |
||
Threshold of eigenvalues to perform square root of Coulomb matrices. |
0.0 |
||
Switch of using the strict 2D analytic dielectric function. |
false |
||
Flag of using cholesky factorization for computing Wc from chi0. |
false |
||
Flag of using ELPA for sqrt Coulomb matrix. |
Build-dependent: true with |
||
Flag of using GPU for computing Wc from chi0. |
Build-dependent: true when a CUDA/HIP build detects a device, false otherwise. |
||
Compute and apply Hedin shifts in QP solves. |
false |
||
If enabled, adapt the QPE damping factor during the solve. |
false |
||
Test-only switch to recover the legacy non-adaptive QPE update. |
false |
||
Flag of using ScaLAPACK for computing Wc from chi0. |
true |
G0W0 native velocity#
The standalone g0w0 driver and its g0w0_band alias can construct analytic
head/wing velocity from the original DFT H(R), S(R), and r(R). The driver
preset option_dielect_func = 6 selects native velocity and then resolves
to the existing numerical option 3. It requires replace_w_head = true,
use_scalapack_gw_wc = true, and use_pyatb = false. An omitted velocity
selector becomes native; explicit native is accepted and explicit
file is rejected. The log records requested option 6 and effective
option 3. QSGW also supports option 6 with its current_hr velocity
convention, described below. Standalone cRPA also accepts option 6 and
reuses these native velocity fields for its constrained optical calculation.
Other tasks reject option 6. Direct
library/API callers use option 3 with the public velocity setter or
librpa_prepare_native_velocity.
Existing options 3 and 4 still accept g0w0_headwing_velocity = native;
their default file uses the existing velocity reader.
The native path retains the loaded SCF energies,
wavefunctions, and occupations and does not solve a second eigenproblem.
It requires complete AO-spinor/band frames. Scalar input uses a uniform
full-BZ mesh; SOC also accepts paired IBZ states with complete magnetic
k stars and normalized multiplicity weights. One/two collinear spin channels or one two-component SOC channel
are supported. SOC requires full complex H and full-dimension S/r of
dimension 2 * N_AO, with use_spinor_wfc = true; both spinor components
are retained in AO-major/spinor-minor order. IBZ head/wing uses joint
source-gauge velocity and spinor reconstruction. K-point-parallel SCF
eigenvectors are disabled on that IBZ route. See the native head/wing example in
Driver Usage.
Parameter Name |
Description |
Default Value |
Since |
|---|---|---|---|
Original DFT H(R) CSR for spin 0, relative to |
empty |
Unreleased |
|
Original DFT H(R) CSR for spin 1 in a collinear two-spin calculation. |
empty |
Unreleased |
|
Three-component r(R) CSR with its original full real-space support. |
empty |
Unreleased |
|
Dimensionless S(R) CSR with its original full real-space support. |
empty |
Unreleased |
|
G0W0 analytic head/wing velocity source: file (existing reader) or native. |
file |
Unreleased |
|
H(R) input energy unit: Ha, Ry, or eV, converted once into Hartree. |
Ry |
Unreleased |
|
r(R) input length unit: Bohr or Angstrom, converted once into Bohr. |
Bohr |
Unreleased |
QSGW#
Use task = qsgw for molecular and periodic QSGW; this is the only QSGW
task name, and older inputs must switch their task value. Presence of
fn_band_kpath_info (default band_kpath_info) enables the existing
band channel alongside the SCF grid and requires matching band E/C and
full band Vxc inputs. Without that metadata file, only the SCF grid is
computed, including for periodic inputs. Geometry does not select the
channel. qsgw_cut_mode = 1 selects the shifted-reference cut on both
the SCF grid and optional band path. The retained empty-state count
defaults to 10, and the shift defaults to 2 eV (explicit
qsgw_cut_shift_ha values are in Hartree). HR export is enabled by default.
Each band-enabled iteration writes KS_band_spin_S_N.dat,
EXX_band_spin_S_N.dat, and QSGW_band_spin_S_N.dat for plotting;
figures are not generated automatically. Keep band-channel presence and
original path inputs unchanged when restarting a checkpoint.
These experimental parameters apply to task = qsgw.
qsgw_update_hartree = true adds the physical density-difference Hartree
potential to each update. It defaults to true and requires separate
prefix_coul_hartree and unwrapped binary-v1 prefix_lri_coeff_hartree
inputs matched to the selected auxiliary basis. Ordinary GW full/cut
Coulomb matrices and folded coefficients remain unchanged.
option_dielect_func = 6 selects
qsgw_headwing_velocity = current_hr and resolves to existing numerical
option 3: rebuild velocity from the current native-baseline Hamiltonian
in the entering E/C frame, then rebuild analytic head/wing using the live
E/C/f and the body frequency nodes. Previous head/wing data are cleared
before each rebuild. This needs dimensionless qsgw_fn_sr and Bohr
qsgw_fn_rr, plus matching native hrs1_nao.csr in Ry (and
hrs2_nao.csr for two physical collinear channels). The native DFT
baseline and complete current correction use the same reconstruction
as formal HR export; no velocity file is needed.
The preset requires replace_w_head = true, use_scalapack_gw_wc = true,
and use_pyatb = false. An omitted selector or explicit current_hr is
accepted; explicit reference or rotate_reference is rejected.
The log records requested option 6 and effective option 3.
Existing option 3 with current_hr remains equivalent; option 3/4 with
other supported velocity conventions keeps its existing behavior.
This is an experimental full, unshifted mesh path with complete square
AO-spinor/state frames and replicated wavefunctions. SOC uses one physical
channel and two components with full-dimension S/r. Explicit magnetic
operations and paired IBZ source E/C/f and Vxc can be expanded internally
to the full mesh when all three symmetry switches are enabled. Live-state
and endpoint-weight covariance checks must pass before magnetic reduction.
Finite-BvK interpolation retains the off-mesh and convergence limitations
described in QSGW.
Independent-grid head/wing and Hartree updates are not supported.
Mixing is selected after SCF input validation. The single-k route needs
global loaded SCF count 1 and full BvK mesh product 1 and permits
requested none or linear. Other meshes force effective none with
beta 1, even if linear was requested; a one-point IBZ from a larger
mesh uses this periodic route. The log records requested/effective
mixer, SCF count and mesh. The mixer default stays none; single-k
linear uses qsgw_mixing_beta (default 0.2), with beta 1 giving direct
updates. Band-path presence/count is independent, and grid/path use the
same effective beta. This input convention does not detect physical
isolation: Gamma-only solids also enter the single-k route and can use
none. Geometry, Coulomb and head/wing are unchanged. Remove obsolete
qsgw_system_type from inputs. Existing checkpoint effective-beta checks
retain the format: old single-k molecular restarts need the same mixer
and beta, without a type setting; periodic-route checkpoints with
effective beta below 1 cannot continue, while effective-beta-1 checkpoints
remain compatible. Adaptive automatic mixing belongs to a separate
branch; this implementation supports only none and linear.
Full Vxc matrices are read directly using the producer’s spin and
k-point filenames under input_dir. Standard ABACUS out_mat_xc
output is already in the initial KS-state basis, so the default
qsgw_vxc_basis = state applies despite its _nao filename suffix.
Use qsgw_vxc_basis = nao only for genuine ABACUS AO matrices.
Parameter Name |
Description |
Default Value |
Since |
|---|---|---|---|
Full band Vxc matrix prefix, relative to |
Empty (producer default) |
||
Full SCF Vxc matrix prefix, relative to |
Empty (producer default) |
||
Checkpoint written after every complete update; relative to |
|
Unreleased |
|
Maximum eigenvalue change used for convergence, in eV. |
1.0e-4 |
||
QSGW H_QSGW cut: 0 uncut, 1 shifted KS diagonal (formerly mode 2). |
0 |
||
Hamiltonian energy shift applied to cut states in mode 1, in Hartree. |
2.0 / 27.211386245988 (2 eV in Hartree with internal constants) |
||
Export the complete SCF-grid Hamiltonian before each QSGW diagonalization. |
true |
Unreleased |
|
Three-component r(R) input for current_hr or HR export: native ABACUS CSR in Bohr, |
rr.csr |
Unreleased |
|
S(R) input for current_hr or HR export: native ABACUS CSR, dimensionless, with its |
srs1_nao.csr |
Unreleased |
|
Analytic head/wing velocity convention: reference (legacy head-only), |
reference |
Unreleased |
|
Maximum global QSGW iteration, including restored updates. |
10 |
||
Earliest global QSGW iteration at which convergence may terminate the run. |
1 |
||
Fixed-basis Hamiltonian mixing ( |
|
||
Linear Hamiltonian mixing fraction for the single-k SCF branch. |
0.2 |
||
Solve the diagonal G0W0 quasiparticle equation on every entering QSGW state. |
true |
Unreleased |
|
Checkpoint to restore at a completed QSGW iteration; relative to cwd. |
|
Unreleased |
|
Number of unoccupied states retained by the QSGW H_QSGW cut. |
10 |
||
Include V_H[D_t-D_DFT] in each QSGW update, using current physical occupations. |
true |
Unreleased |
|
Basis of the full Vxc matrices: |
|
||
Write per-iteration matrices used by numerical regression tests. |
false |
LibRI Filtering#
These parameters are active for LibRI-enabled builds and LibRI routing.
Parameter Name |
Description |
Default Value |
Since |
|---|---|---|---|
Threshold of real-space LRI triple coefficients to compute response function using LibRI. |
0.0 |
||
Threshold of real-space Green’s function to compute response function using LibRI. |
0.0 |
||
Threshold of real-space LRI triple coefficients to compute exact exchange using LibRI. |
0.0 |
||
Threshold of real-space density matrices to compute exact exchange using LibRI. |
0.0 |
||
Threshold of real-space Coulomb matrices to compute exact exchange using LibRI. |
0.0 |
||
Threshold of real-space LRI triple coefficients to compute GW correlation self-energy using LibRI. |
0.0 |
||
Threshold of real-space Green’s function to compute GW correlation self-energy using LibRI. |
0.0 |
||
Threshold of correlation screened Coulomb matrix to compute GW correlation self-energy using LibRI. |
0.0 |
Output Control#
Parameter Name |
Description |
Default Value |
Since |
|---|---|---|---|
Half-open Wc frequency output end index; negative means all remaining frequencies. |
-1 |
||
First zero-based Wc frequency index to output. |
0 |
||
Half-open KS-state end index when exporting KS-basis matrices; negative |
-1 |
||
First zero-based KS state included in both dimensions when exporting the |
0 |
||
Output exact-exchange matrix in KS basis and k-space. |
false |
||
Output exact-exchange matrix in NAO basis and k-space as dense binary files. |
false |
||
Output real-space NAO exact-exchange blocks after symmetry restoration, |
false |
||
Output KS-diagonal correlation self-energy in k-space, imaginary frequency domain. |
false |
||
Output correlation self-energy matrix in KS basis (k-space, imaginary frequency domain). |
false |
||
Output correlation self-energy matrix in NAO basis (k-space, imaginary frequency domain). |
false |
||
Output correlation self-energy matrix in NAO basis (real space, imaginary frequency domain). |
false |
||
Output correlation self-energy matrix in NAO basis (real space, imaginary time domain). |
false |
||
Output Wc matrix in ABFs (real space, imaginary frequency domain). |
false |
||
Output Wc(R, iw) as atom-pair blocks instead of full matrices. |
true |
Driver Compatibility Aliases#
The driver still accepts a few older input keys for backward compatibility, and may remove them in the future.
Alias Name |
Preferred Name |
Notes |
|---|---|---|
|
|
|
|
Old spelling for selecting spinor-format driver input |
|
|
Old spelling |
|
|
Old spelling |
|
|
Old spelling |
|
|
Old spelling |
|
|
|
g0w0_band is accepted as a deprecated alias of g0w0.
For details on all API parameters, see section below or visit the API documentation of struct LibrpaOptions.
Parameter Details#
(API) anacon_aaa_tolerance
Relative maximum source residual requested by AAA.
Type:
doubleDefault: 1.0e-13
(API) anacon_method
Analytic continuation method for GW energies, spectra and QSGW matrices.
Type:
enum/stringDefault: LIBRPA_ANACON_PADE
Available driver values: pade, aaa, ridge.
(API) anacon_nfreq
Number of points in the optional GW analytic-continuation frequency grid.
Type:
intDefault: -1
Status: Experimental
Negative values use the source grid nfreq when the analytic-continuation
grid is built. Zero is invalid. Positive values select that many points;
if this equals the source nfreq and no new grid type is selected, the
original grid is reused.
(API) anacon_ridge_den_weight
Relative ridge penalty on denominator coefficients.
Type:
doubleDefault: 10.0
(API) anacon_ridge_lambda
Ridge penalty on scaled nonconstant rational coefficients.
Type:
doubleDefault: 1.0e-12
(API) anacon_tfgrids_type
Type of optional frequency grid used for GW analytic continuation.
Type:
enum/stringDefault: LIBRPA_TFGRID_UNSET
Status: Experimental
When unset and anacon_nfreq does not request a different grid size,
analytic continuation uses the original GW self-energy grid.
(API) chi0_method
Method to compute the response function chi0.
Type:
enum/stringDefault: LIBRPA_METHOD_AUTO
Available driver values: auto, space_time, conventional.
auto selects space_time for grids with time nodes, and conventional for
frequency-only grids. The unset value is the same as auto.
space_time uses the real-space Green’s function at the time nodes, and needs a grid
with time nodes.
conventional sums over band transitions at the frequency nodes of any grid.
It is available for RPA energies only. It requires replicated scalar or collinear
eigenvectors on the full k mesh, use_symmetry_rpa = false, and
use_shrink_abfs = false.
GW and cRPA use space_time, and stop on a frequency-only grid or with conventional.
(Driver) constants_choice
Physical constants source.
Type:
stringDefault:
internal(internal,aims)
(Driver) crpa_analysis_only
Analyze orbital character only; skip RI/Coulomb input and screening.
Type:
boolDefault: false
Status: Experimental
Since: Unreleased
A/B selections and correlated species are not required in this mode.
Requires task=crpa and crpa_output_analysis=true; incompatible with crpa_enabled=true.
(Driver) crpa_enabled
Compute cRPA U during G0W0 (task=g0w0 or g0w0_band) or QSGW (task=qsgw).
Type:
boolDefault: false
Status: Experimental
Since: Unreleased
G0W0 evaluates U once; QSGW evaluates selected entering states and the final state.
Requires crpa_analysis_only=false; use task=crpa for standalone screening.
(Driver) crpa_eta_ev
Positive imaginary broadening for requested real-frequency interactions, in eV.
Type:
doubleDefault: 0.05
Status: Experimental
Since: Unreleased
(Driver) crpa_fit_tol_ev
Absolute tolerance for static/real-axis subset and node residual diagnostics, in eV.
Type:
doubleDefault: 0.01
Status: Experimental
Since: Unreleased
(Driver) crpa_interval
Electronic-state interval for cRPA during QSGW; the final state is always evaluated.
Type:
intDefault: 1
Status: Experimental
Since: Unreleased
(Driver) crpa_ligand_species
Species supplying the first radial p shell of a dp parent frame.
Type:
stringDefault: Empty
Status: Experimental
Since: Unreleased
Must differ from crpa_correlated_species; spectator species are not selected.
Required for standalone or coupled screening when crpa_parent_orbitals=dp.
Not required when crpa_analysis_only=true.
(Driver) crpa_model_file
Import only cRPA model/analysis parameters from an existing native input file.
Type:
stringDefault: none
Status: Experimental
Since: Unreleased
Main-input cRPA assignments override imported settings; shared GW options stay in the main input.
(Driver) crpa_orbital_bands
B: distinct zero-based original KS indices shared by all spin/k points.
Type:
std::vector<int>Default: Empty
Status: Experimental
Since: Unreleased
For screening in either response mode, specify exactly one of this parameter
and crpa_orbital_windows_ha. Not required when crpa_analysis_only=true.
(Driver) crpa_orbital_windows_ha
B: inclusive absolute-Hartree lower/upper pairs for projecting atomic trials.
Type:
std::vector<double>Default: Empty
Status: Experimental
Since: Unreleased
Does not change KS poles, occupations, or the response selection A.
For screening in either response mode, specify exactly one of this parameter
and crpa_orbital_bands. Not required when crpa_analysis_only=true.
(Driver) crpa_output_analysis
Output Mulliken/Lowdin weights and Gaussian PDOS before cRPA screening.
Type:
boolDefault: true
Status: Experimental
Since: Unreleased
Uses existing scalar/spinor KS states and spatial S; includes every radial shell. Spinor weights sum both components in one stored spin channel.
(Driver) crpa_output_format
Native model output container: npz or human-readable dat files. Both retain the same model.
Type:
stringDefault: npz
Status: Experimental
Since: Unreleased
(Driver) crpa_output_model
Save current E/f, complex parent/output projectors, H/density and U in compact NumPy
Type:
boolDefault: true
Status: Experimental
Since: Unreleased
archives.
(Driver) crpa_output_orbitals
Reported subset of the jointly normalized parent frame: s, p, sp, d, dp, eg or t2g.
Type:
stringDefault: d
Status: Experimental
Since: Unreleased
Must be a subset of crpa_parent_orbitals; it does not select response bands A.
(Driver) crpa_output_raw
Include C, S and AO coefficients Phi in the model archives for changing the local frame.
Type:
boolDefault: false
Status: Experimental
Since: Unreleased
(Driver) crpa_output_static
Estimate U(0) with native Padé of U-v; retain entrywise numerical status and fit spread.
Type:
boolDefault: true
Status: Experimental
Since: Unreleased
(Driver) crpa_overlap_file
Native spatial or interleaved SOC S(R) CSR input, relative to the main input_dir.
Type:
stringDefault: SR.csr
Status: Experimental
Since: Unreleased
(Driver) crpa_parent_orbitals
Atomic trials projected into B and jointly metric-normalized: s, p, sp, d, dp, eg or t2g.
Type:
stringDefault: d
Status: Experimental
Since: Unreleased
eg/t2g refer to global Cartesian axes, using the first radial shell.
(Driver) crpa_pdos_max_ev
Upper PDOS grid edge in eV relative to crpa_pdos_reference.
Type:
doubleDefault: 14
Status: Experimental
Since: Unreleased
(Driver) crpa_pdos_min_ev
Lower PDOS grid edge in eV relative to crpa_pdos_reference.
Type:
doubleDefault: -10
Status: Experimental
Since: Unreleased
(Driver) crpa_pdos_reference
PDOS energy zero: vbm (highest occupied KS pole) or fermi.
Type:
stringDefault: vbm
Status: Experimental
Since: Unreleased
(Driver) crpa_pdos_sigma_ev
Gaussian standard deviation in eV (not FWHM).
Type:
doubleDefault: 0.15
Status: Experimental
Since: Unreleased
(Driver) crpa_pdos_step_ev
PDOS grid spacing in eV.
Type:
doubleDefault: 0.02
Status: Experimental
Since: Unreleased
(Driver) crpa_real_frequencies_ev
Real frequencies in eV relative to bosonic zero; an empty list skips real-axis output.
Type:
std::vector<double>Default: Empty
Status: Experimental
Since: Unreleased
(Driver) crpa_residual_tol
Positive metric/KS orthogonality tolerance. Frobenius residual gates use
Type:
doubleDefault: 1.0e-10
Status: Experimental
Since: Unreleased
this value times sqrt(matrix dimension); input KS states are never repaired.
(Driver) crpa_response_bands
A: distinct zero-based original KS indices shared by all spin/k points.
Type:
std::vector<int>Default: Empty
Status: Experimental
Since: Unreleased
For screening with crpa_response_mode=bands, specify exactly one of this parameter
and crpa_response_windows_ha. Optional in analysis-only bands mode. Must be empty for
crpa_response_mode=orbital_weights, including analysis-only runs.
(Driver) crpa_response_mode
Response rule: bands uses binary A windows/lists; orbital_weights uses
Type:
stringDefault: bands
Status: Experimental
Since: Unreleased
probabilities from the actual output orbitals, without an A selector.
(Driver) crpa_response_windows_ha
A: inclusive absolute-Hartree lower/upper pairs selecting original KS states
Type:
std::vector<double>Default: Empty
Status: Experimental
Since: Unreleased
on both occupied and empty branches of Pd. Independent of output window B.
For screening with crpa_response_mode=bands, specify exactly one of this parameter
and crpa_response_bands. Optional in analysis-only bands mode. Must be empty for
crpa_response_mode=orbital_weights, including analysis-only runs.
(Driver) crpa_species_labels
Explicit species labels in numeric structure-type order, separated by spaces.
Type:
stringDefault: Empty
Status: Experimental
Since: Unreleased
Required for task=crpa, including analysis-only runs, or crpa_enabled=true.
(Driver) crpa_track_orbitals
Transport the complete parent Phi through B after each QSGW update, without screening.
Type:
boolDefault: false
Status: Experimental
Since: Unreleased
false; the first call uses the declared atomic trials. Restart retains the parent.
(Driver) crpa_tracking_min_capture
Smallest retained probability of a previous parent direction; default 0.99.
Type:
doubleDefault: 0.99
Status: Experimental
Since: Unreleased
A loss stops the calculation and requires a wider declared B.
(Driver) cs_threshold
Screening threshold when reading RI coefficient data.
Type:
doubleDefault: 1e-6
(Driver) fn_band_kpath_info
Band-path k-point metadata filename.
Type:
stringDefault:
band_kpath_info
For QSGW, presence under input_dir enables the existing band channel
and requires matching band E/C and full Vxc; absence runs only the
SCF grid. This input-driven behavior uses task=qsgw.
Keep band-channel presence and inputs unchanged across a restart.
(Driver) fn_basis
Deprecated combined basis-set fallback filename.
Type:
stringDefault:
basis_outStatus: Deprecated: Use
fn_basis_wfcandfn_basis_auxinstead.
(Driver) fn_basis_aux
Auxiliary-basis metadata filename.
Type:
stringDefault:
basis_aux_out
(Driver) fn_basis_aux_shrink
Compressed auxiliary-basis metadata filename used with use_shrink_abfs = true.
Type:
stringDefault:
basis_aux_shrink_outStatus: Experimental
Since: Unreleased
(Driver) fn_basis_wfc
Wave-function basis metadata filename.
Type:
stringDefault:
basis_wfc_out
(Driver) fn_bz_sampling
Brillouin-zone sampling filename.
Type:
stringDefault:
bz_sampling_out
(Driver) fn_dielfunc
Dielectric-function filename for dielectric-head correction.
Type:
stringDefault:
dielecfunc_out
(Driver) fn_eigocc_scf
SCF eigenvalue and occupation filename.
Type:
stringDefault:
band_out
(Driver) fn_sternheimer_partial_manifest
Sternheimer partial-response manifest with rows
Type:
stringDefault: empty
Status: Experimental
iq ik_full ifreq response_file.
An empty value preserves aggregate Sternheimer response input.
(Driver) fn_sternheimer_qpoints
Sternheimer q-point manifest filename with rows iq qx qy qz qweight.
Type:
stringDefault: empty
Status: Experimental
An empty value preserves the single-q sternheimer_iq mode.
(Driver) fn_sternheimer_qstar_routes
Explicit inverse routes from every full-q member to the discrete
Type:
stringDefault: empty
Status: Experimental
q-star representative provided by the producer.
(Driver) fn_sternheimer_symmetry_routes
Explicit fixed-q inverse routes provided by the producer for reconstruction
Type:
stringDefault: empty
Status: Experimental
under the symmetry subgroup preserved by the discrete Hamiltonian.
(Driver) fn_stru
Structure-data filename.
Type:
stringDefault:
stru_out
(Driver) fn_vxc_scf
SCF exchange-correlation potential filename.
Type:
stringDefault:
vxc_out
(Driver) g0w0_fn_hr
Original DFT H(R) CSR for spin 0, relative to input_dir or absolute.
Type:
stringDefault: empty
Status: Experimental
Since: Unreleased
(Driver) g0w0_fn_hr_spin1
Original DFT H(R) CSR for spin 1 in a collinear two-spin calculation.
Type:
stringDefault: empty
Status: Experimental
Since: Unreleased
(Driver) g0w0_fn_rr
Three-component r(R) CSR with its original full real-space support.
Type:
stringDefault: empty
Status: Experimental
Since: Unreleased
(Driver) g0w0_fn_sr
Dimensionless S(R) CSR with its original full real-space support.
Type:
stringDefault: empty
Status: Experimental
Since: Unreleased
(Driver) g0w0_headwing_velocity
G0W0 analytic head/wing velocity source: file (existing reader) or native.
Type:
stringDefault: file
Status: Experimental
Since: Unreleased
Native uses the original DFT H(R)/S(R)/r(R) and the loaded SCF E/C frame.
(Driver) g0w0_hr_unit
H(R) input energy unit: Ha, Ry, or eV, converted once into Hartree.
Type:
stringDefault: Ry
Status: Experimental
Since: Unreleased
(Driver) g0w0_rr_unit
r(R) input length unit: Bohr or Angstrom, converted once into Bohr.
Type:
stringDefault: Bohr
Status: Experimental
Since: Unreleased
(API) gf_threshold
Threshold for real-space Green’s function in response function calculation.
Type:
doubleDefault: 0.0
(Driver) hartree_check_tolerance
Positive maximum complex AO-entry comparison tolerance, in Hartree.
Type:
doubleDefault: -1 (report only)
Status: Experimental
A negative value only reports differences; a positive gate requires a reference.
(Driver) hartree_fn_reference
Optional complete complex ABACUS Hartree H(R) CSR reference.
Type:
stringDefault: empty
Status: Experimental
Relative paths are resolved from input_dir. No gauge shift is fitted.
(Driver) hartree_reference_scale
Reference CSR energy conversion to Hartree (0.5 for Rydberg input).
Type:
doubleDefault: 0.5
Status: Experimental
(Driver) i_state_high
Last state index for printed QP energies, exclusive.
Type:
intDefault: 999999
Negative values enable automatic selection from a Fermi-level/gap energy window. The current upper bound is \(E_F + \frac{1}{2}E_g + 0.5 \text{Ha}\). Values larger than the number of states are truncated.
(Driver) i_state_low
First state index for printed QP energies, inclusive.
Type:
intDefault: 0
Negative values enable automatic selection from a Fermi-level/gap energy window. The current lower bound is \(E_F - \frac{1}{2}E_g - 0.5 \text{Ha}\).
(API) ifreq_output_wc_end
Half-open Wc frequency output end index; negative means all remaining frequencies.
Type:
intDefault: -1
Status: Experimental
(API) ifreq_output_wc_start
First zero-based Wc frequency index to output.
Type:
intDefault: 0
Status: Experimental
(Driver) input_dir
Input directory to find and read the AO dataset.
Type:
stringDefault:
./
(Driver) input_preset
Preset for producer-specific input filenames and head/wing velocity readers.
Type:
stringDefault:
fhi-aims(fhi-aims,aims,abacus,abacus-legacy)
aims is an alias for fhi-aims.
abacus-legacy is for input before ABACUS PR #7849
(merge commit 42f8ad905d56 on develop).
(API) istate_output_mat_end
Half-open KS-state end index when exporting KS-basis matrices; negative
Type:
intDefault: -1
Status: Experimental
means all remaining states.
(API) istate_output_mat_start
First zero-based KS state included in both dimensions when exporting the
Type:
intDefault: 0
Status: Experimental
KS-basis exact-exchange and correlation self-energy matrices. Matrix construction is unaffected.
(API) istate_ref_hedin_shift
Absolute zero-based reference state index for Hedin shifts.
Type:
intDefault: -1
Status: Experimental
This index is not relative to i_state_low. A negative value applies a per-state shift; a nonnegative
value uses that state at each k-point and spin channel for all states in
the same channel.
(API) libri_chi0_collect_max_bytes
Maximum estimated local chi0 tensor bytes per LibRI collection chunk; 0 keeps one-shot collection.
Type:
long longDefault: 0
Status: Experimental
(API) libri_chi0_collect_s0_chunk
Number of first-index atoms per LibRI chi0 collection chunk; 0 keeps one-shot collection.
Type:
intDefault: 0
Status: Experimental
(API) libri_chi0_threshold_C
Threshold of real-space LRI triple coefficients to compute response function using LibRI.
Type:
doubleDefault: 0.0
(API) libri_chi0_threshold_G
Threshold of real-space Green’s function to compute response function using LibRI.
Type:
doubleDefault: 0.0
(API) libri_exx_threshold_C
Threshold of real-space LRI triple coefficients to compute exact exchange using LibRI.
Type:
doubleDefault: 0.0
(API) libri_exx_threshold_D
Threshold of real-space density matrices to compute exact exchange using LibRI.
Type:
doubleDefault: 0.0
(API) libri_exx_threshold_V
Threshold of real-space Coulomb matrices to compute exact exchange using LibRI.
Type:
doubleDefault: 0.0
(API) libri_g0w0_threshold_C
Threshold of real-space LRI triple coefficients to compute GW correlation self-energy using LibRI.
Type:
doubleDefault: 0.0
(API) libri_g0w0_threshold_G
Threshold of real-space Green’s function to compute GW correlation self-energy using LibRI.
Type:
doubleDefault: 0.0
(API) libri_g0w0_threshold_Wc
Threshold of correlation screened Coulomb matrix to compute GW correlation self-energy using LibRI.
Type:
doubleDefault: 0.0
(API) minimax_emax
Maximal transition energy when generating minimax grids.
Type:
doubleDefault: -1.0
Status: Experimental
This option is introduced for test of supercell to fix the minimax frequency points
(API) minimax_emin
Minimal transition energy when generating minimax grids.
Type:
doubleDefault: -1.0
Status: Experimental
When set negative (the default), the minimal energy is decided by the mean-field input and set to the energy gap. For now, it is suggested to manually set this option for gapless systems.
(API) minimax_regulation
Regulation for minimax grids generation.
Type:
doubleDefault: 0.0
Status: Experimental
(API) n_bands_chi0
Maximal number of bands for computing response function.
Type:
intDefault: -1 (< 0 for all bands)
Status: Experimental
(API) n_bands_exclude_chi0
Number of lowest bands excluded from both Green’s functions forming the response function.
Type:
intDefault: 0
Applies independently at each input k-point and spin, for both signs of imaginary time. Valid range: 0 through the number of input bands. The input band ordering is retained. Does not modify occupations, EXX, output state ranges, or analytic/external head corrections.
(API) n_bands_exclude_sigc
Number of lowest bands excluded from the Green’s function multiplying Wc in the correlation self-energy.
Type:
intDefault: 0
Applies independently at each input k-point and spin, for both signs of imaginary time. Valid range: 0 through the number of input bands. The input band ordering is retained. Does not modify occupations, EXX, output state ranges, or analytic/external head corrections.
(API) n_bands_sigc
Maximal number of bands for computing correlation self-energy.
Type:
intDefault: -1 (< 0 for all bands)
Status: Experimental
(API) n_params_anacon
Pade selected-node count, AAA support cap, or ridge coefficient count.
Type:
intDefault: -1 (uses the source point count)
(API) n_params_anacon_resample
Number of parameters for the source-grid fit used to resample GW analytic continuation.
Type:
intDefault: -1
Status: Experimental
Negative values use n_params_anacon.
This parameter only works when resampling imaginary-frequency grids is enabled via
a different frequency grids type (anacon_tfgrids_type) or number of grids points
(anacon_nfreq) from the direct evaluation of \(\Sigma_c(i\omega)\).
(API) nfreq
Number of time/frequency points.
Type:
intDefault: 16
(API) option_bvk_remap
BvK remapping convention for band interpolation.
Type:
intDefault: 1
Available values:
0: map each atom-pair R to one nearest BvK image; equally split inconsistent opposite-pair ties to preserve the adjoint relation.
1: Wigner-Seitz remapping; split over all nearest BvK images at equal distance.
(API) option_dielect_func
Option of computing dielectric function on imaginary axis.
Type:
intDefault: 0
Available values:
0: use data directly read from input
1: cubic-spline interpolation from input data
2: dielectric model fitting from input data
3: analytic head and wing correction
4: analytic head correction
5: use input data directly; replace the head along the largest-eigenvalue vector of the Gamma s-only Coulomb submatrix, zero-padded to all ABFs. Includes all s shells, preserves wings, and requires auxiliary l-shell metadata. Input data must match the current frequency grid.
53: analytic head and wing correction along the Gamma s-submatrix head direction, projected onto the retained Coulomb space and normalized. Requires auxiliary l-shell metadata and the ScaLAPACK Wc path. Supported for three-dimensional G0W0 and G0W0 band calculations only. Standalone G0W0/cRPA/QSGW drivers also accept preset 6. G0W0 differentiates original H/S/r; QSGW differentiates its complete current native-baseline Hamiltonian. Both resolve to numerical option 3 for analytic head and wing. This requires
replace_w_headanduse_scalapack_gw_wc, anduse_pyatb=false. API callers supply velocity or numerical H/S/r blocks and select 3/4; they must not pass driver preset 6 into a numerical options struct.
(API) option_qpe_solver
Quasi-particle equation solver option.
Type:
intDefault: 0
Available values:
0: damped residual-mixing self-consistent solver
1: quasi-Newton self-consistent solver using the selected continuation derivative
2: perturbative solver linearized at the mean-field energy
(API) output_abacus_gw_gf
Switch of outputting ABACUS-compatible GW Green’s-function data.
Type:
boolDefault: false
Status: Experimental
(API) output_dir
Output directory for results.
Type:
stringDefault: librpa.d/
Set with librpa_set_output_dir() or librpa::Options::set_output_dir()
so directory normalization is applied.
(Driver) output_energy_qp
Output quasiparticle energies for external BSE workflows.
Type:
boolDefault: false
Status: Experimental
(API) output_exx_ks_mat_k
Output exact-exchange matrix in KS basis and k-space.
Type:
boolDefault: false
Status: Experimental
(API) output_exx_mat_k
Output exact-exchange matrix in NAO basis and k-space as dense binary files.
Type:
boolDefault: false
Status: Experimental
Files in output_dir are named ExxK_kgrid_ispin_S_ik_K.bin or
ExxK_band_B_ispin_S_ik_K.bin, with zero-based indices. Spinor blocks
include _spinor_BRA_KET before _ik. Values are in Hartree and include
the exchange minus sign. All NAOs are exported, independently of the
KS-state output range, when the k-space EXX potential is constructed.
Binary layout: native-endian int32 dimension and int32 scalar byte size (8),
then row-major real/imaginary float64 pairs, without threshold filtering.
(API) output_exx_mat_r
Output real-space NAO exact-exchange blocks after symmetry restoration,
Type:
boolDefault: false
Status: Experimental
before redistribution for k-space projection. One file per MPI rank and
spin/spinor channel in output_dir:
ExxR_ispin_SS_s_BK_myid_NNNNN.bin (B, K: bra and ket spinor indices).
Shares the indexed layout of the Sigma_c(R,iw) output. Native byte order.
Header (48 bytes, fields in this order): char[8] magic “LIBRPAIJ”, uint32
endian marker 0x01020304, int32 version (1), int32 kind (0 for ExxR), int32
nprocs and int32 myid (size of the writing MPI communicator and the rank of this
file), int32 scalar type (0 double, 1 complex double), uint64 run_id, uint64
block count. Then one record per block with int32[7] (R1, R2, R3, I, J, rows,
columns) and the uint64 absolute payload offset, followed by the row-major
payloads. Scalar-spinor runs store real doubles; spinor runs store complex
doubles. Values are in Hartree and include the exchange minus sign. Only stored
blocks are written, without additional threshold filtering. After MPI summation
each (I,J,R) block is written by exactly one rank, so the partition into files
depends on the number of ranks.
The run_id is nonzero and equal in all files of one output. Files of an earlier
run in the same directory are not removed. A reader must take the file set from
the file of rank 0: its nprocs and run_id; use exactly the ranks 0..nprocs-1 with
this run_id; ignore files of higher ranks; and reject duplicate (I,J,R) blocks.
Independent of the KS-state output range.
(API) output_gw_sigc_ks_kf
Output KS-diagonal correlation self-energy in k-space, imaginary frequency domain.
Type:
boolDefault: false
Status: Experimental
(API) output_gw_sigc_ks_mat_kf
Output correlation self-energy matrix in KS basis (k-space, imaginary frequency domain).
Type:
boolDefault: false
Status: Experimental
(API) output_gw_sigc_mat_kf
Output correlation self-energy matrix in NAO basis (k-space, imaginary frequency domain).
Type:
boolDefault: false
Status: Experimental
Dense binary files in output_dir use the same layout as output_exx_mat_k:
SigcKF_kgrid_ispin_S_ik_K_ifreq_F.bin or
SigcKF_band_B_ispin_S_ik_K_ifreq_F.bin, with zero-based indices.
Spinor blocks include _spinor_BRA_KET before _ik. Values are in Hartree;
all NAOs are exported without threshold filtering.
(API) output_gw_sigc_mat_rf
Output correlation self-energy matrix in NAO basis (real space, imaginary frequency domain).
Type:
boolDefault: false
Status: Experimental
One file per MPI rank, spin/spinor channel and frequency in output_dir:
SigcRF_ispin_SS_s_BK_iomega_FFF_myid_NNNNN.bin. The layout and the rules for
readers are those of output_exx_mat_r, with kind 1 and a header of 56 bytes: the
frequency (double) follows the block count. Payloads are complex doubles. The
run_id is the same in all files of the output, whatever the spin, spinor and
frequency.
(API) output_gw_sigc_mat_rt
Output correlation self-energy matrix in NAO basis (real space, imaginary time domain).
Type:
boolDefault: false
Status: Experimental
(Driver) output_gw_spec_func
Output GW spectral-function data.
Type:
boolDefault: false
Status: Experimental
(Driver) output_hamgnn
Output GW energies for HamGNN machine-learning workflows.
Type:
boolDefault: false
Status: Experimental
(Driver) output_level
Verbosity level for driver output.
Type:
enum/stringDefault:
info(silent,critical,info,warn,debug)
It is parsed to the global API function set_output_level.
(API) output_wc_rf
Output Wc matrix in ABFs (real space, imaginary frequency domain).
Type:
boolDefault: false
Status: Experimental
(API) output_wc_rf_atom_pair
Output Wc(R, iw) as atom-pair blocks instead of full matrices.
Type:
boolDefault: true
Status: Experimental
(API) override_qpe_solver_nan
If enabled, keep the final unconverged QPE iterate instead of outputting NaN.
Type:
boolDefault: false
Status: Diagnostic
(API) parallel_routing
Scheme of parallelization.
Type:
enum/stringDefault: LIBRPA_ROUTING_AUTO
Available driver values: auto, atompair, rtau, libri.
(Driver) prefix_coul_cut
Prefix of truncated Coulomb matrix files.
Type:
stringDefault:
coulomb_cut
(Driver) prefix_coul_full
Prefix of bare Coulomb matrix files.
Type:
stringDefault:
coulomb_mat
(Driver) prefix_coul_hartree
Bare three-dimensional Coulomb prefix for task=hartree or QSGW Hartree feedback, with reciprocal
Type:
stringDefault: empty (required for task=hartree or qsgw_update_hartree=true)
Status: Experimental
G=0 set to zero. Must be supplied explicitly; no EXX metric fallback.
(Driver) prefix_eigvecs_scf
Prefix of SCF Kohn-Sham eigenvector files.
Type:
stringDefault:
KS_eigenvector
(Driver) prefix_lri_coeff
Prefix of localized RI coefficient files.
Type:
stringDefault:
Cs_data
(Driver) prefix_lri_coeff_hartree
Dedicated unwrapped, full-precision LRI coefficient prefix for Hartree
Type:
stringDefault: empty (required when qsgw_update_hartree=true)
Status: Experimental
Since: Unreleased
feedback. Uses existing binary v1 blocks with true physical translations
and the auxiliary basis selected by use_shrink_abfs; no normal Cs fallback.
(Driver) prefix_lri_coeff_shrink
Prefix of compressed-auxiliary-basis RI coefficient files.
Type:
stringDefault:
Cs_shrinked_dataStatus: Experimental
(Driver) prefix_shrink_sinvS
Prefix of shrink auxiliary-basis transform files.
Type:
stringDefault:
shrink_sinvS_Status: Experimental
Since: Unreleased
(Driver) prefix_sternheimer_chi0
Prefix of Sternheimer chi0 v1 response files.
Type:
stringDefault:
v1_sternheimer_chi0_iq_Status: Experimental
(Driver) prefix_sternheimer_kresolved
Optional prefix for fixed-q k-resolved Sternheimer response matrices.
Type:
stringDefault: empty
Status: Experimental
An empty value disables the diagnostic output.
(Driver) prefix_sternheimer_reconstructed
Optional prefix for reconstructed full-q Sternheimer chi0 v1 files.
Type:
stringDefault: empty
Status: Experimental
An empty value disables the diagnostic output.
(Driver) prefix_sternheimer_symmetry_diagnostic
Optional prefix for fixed-q Sternheimer symmetry route diagnostics.
Type:
stringDefault: empty
Status: Experimental
An empty value disables the diagnostic output.
(Driver) prefix_velocity
Prefix of velocity/momentum-matrix files.
Type:
stringDefault:
mommat_ks_kpt_
(Driver) prefix_vxc_band
Full band Vxc matrix prefix, relative to input_dir unless absolute.
Type:
stringDefault: Empty (producer default)
Status: Experimental
Used by QSGW; defaults to band_vxc_mat (aims) or band_vxc (ABACUS).
(Driver) prefix_vxc_scf
Full SCF Vxc matrix prefix, relative to input_dir unless absolute.
Type:
stringDefault: Empty (producer default)
Status: Experimental
Used by QSGW; defaults to xc_matr (aims) or vxc (ABACUS).
(API) qpe_solver_damp_factor
Damping factor for quasi-particle equation solver updates.
Type:
doubleDefault: 0.1
Used as the initial and maximum factor when adaptive damping is enabled.
(API) qpe_solver_n_iter_max
Maximum number of iterations for the quasi-particle equation solver; must be positive.
Type:
intDefault: 10000
(API) qpe_solver_thres
Convergence threshold for the quasi-particle equation solver, in Hartree.
Type:
doubleDefault: 1.0e-6
(Driver) qsgw_checkpoint_file
Checkpoint written after every complete update; relative to output_dir.
Type:
stringDefault:
qsgw_checkpoint.binStatus: Experimental
Since: Unreleased
Use none to disable checkpoint output.
(Driver) qsgw_convergence_tolerance_ev
Maximum eigenvalue change used for convergence, in eV.
Type:
doubleDefault: 1.0e-4
Status: Experimental
(Driver) qsgw_cut_mode
QSGW H_QSGW cut: 0 uncut, 1 shifted KS diagonal (formerly mode 2).
Type:
intDefault: 0
Status: Experimental
Applies to the SCF grid and optional band path; HR exports the actual cut H.
(Driver) qsgw_cut_shift_ha
Hamiltonian energy shift applied to cut states in mode 1, in Hartree.
Type:
doubleDefault: 2.0 / 27.211386245988 (2 eV in Hartree with internal constants)
Status: Experimental
The omitted default is 2 eV converted using the selected constants. Applies to the SCF grid and optional band path.
(Driver) qsgw_export_hamiltonian_for_pyatb
Export the complete SCF-grid Hamiltonian before each QSGW diagonalization.
Type:
boolDefault: true
Status: Experimental
Since: Unreleased
Writes full complex Ry CSR as hrsS_nao_qsgw_iter_NNNN.csr, with H padded
to the actual H/S/r support union. Preserves native DFT hrs1_nao.csr
(also hrs2_nao.csr for two physical collinear channels) and transforms
only the complete current correction. Native DFT H input is in Ry;
S/r use qsgw_fn_sr and qsgw_fn_rr defaults. Requires a complete unshifted
mesh, independently of head/wing and band inputs. SOC retains the full
complex spinor matrix. current_hr differentiates this same native-baseline
reconstruction; its checkpoints bind the native DFT H as well as S/r.
(Driver) qsgw_fn_rr
Three-component r(R) input for current_hr or HR export: native ABACUS CSR in Bohr,
Type:
stringDefault: rr.csr
Status: Experimental
Since: Unreleased
with its full real-space support; path relative to input_dir or absolute.
(Driver) qsgw_fn_sr
S(R) input for current_hr or HR export: native ABACUS CSR, dimensionless, with its
Type:
stringDefault: srs1_nao.csr
Status: Experimental
Since: Unreleased
full real-space support; path relative to input_dir or absolute.
(Driver) qsgw_headwing_velocity
Analytic head/wing velocity convention: reference (legacy head-only),
Type:
stringDefault: reference
Status: Experimental
Since: Unreleased
rotate_reference (fixed initial operator in current eigenstates), or
current_hr (velocity of the complete current native-baseline Hamiltonian,
matching formal HR export; requires native hrs1/hrs2_nao.csr in Ry).
Standalone option_dielect_func=6 selects current_hr if omitted and
rejects an explicit reference or rotate_reference. It resolves to
numerical option 3, with the same current-HR calculation and scope.
The QSGW option-6 preset selects current_hr; explicit option 4 keeps reference.
(Driver) qsgw_max_iter
Maximum global QSGW iteration, including restored updates.
Type:
intDefault: 10
Status: Experimental
(Driver) qsgw_min_iter
Earliest global QSGW iteration at which convergence may terminate the run.
Type:
intDefault: 1
Status: Experimental
(Driver) qsgw_mixer
Fixed-basis Hamiltonian mixing (none or linear).
Type:
stringDefault:
noneStatus: Experimental
After reading SCF input, linear is allowed only for one loaded k point
on a one-point full BvK mesh. Multi-k meshes automatically use none.
Band-path points do not affect this selection. A Gamma-only solid also
enters the single-k branch; select none for a direct update there.
(Driver) qsgw_mixing_beta
Linear Hamiltonian mixing fraction for the single-k SCF branch.
Type:
doubleDefault: 0.2
Status: Experimental
(Driver) qsgw_output_qp
Solve the diagonal G0W0 quasiparticle equation on every entering QSGW state.
Type:
boolDefault: true
Status: Experimental
Since: Unreleased
Reuses the existing EXX/Sigma matrices in the current eigenbasis and the G0W0 analytic-continuation/QPE options. Writes qsgw_qp.csv for the SCF grid and optional band path, plus energy_qp_N and GW_band_spin_S_N.dat in the ordinary G0W0 file formats for each update. These diagnostic roots do not enter the QSGW update.
(Driver) qsgw_restart_file
Checkpoint to restore at a completed QSGW iteration; relative to cwd.
Type:
stringDefault:
noneStatus: Experimental
Since: Unreleased
(Driver) qsgw_unoccupied_keep
Number of unoccupied states retained by the QSGW H_QSGW cut.
Type:
intDefault: 10
Status: Experimental
Applies to the SCF grid and optional band path when cut mode 1 is selected.
(Driver) qsgw_update_hartree
Include V_H[D_t-D_DFT] in each QSGW update, using current physical occupations.
Type:
boolDefault: true
Status: Experimental
Since: Unreleased
Requires a dedicated prefix_coul_hartree bare 3D G=0-zero metric matching
the selected auxiliary basis. Ordinary GW Coulomb inputs remain required.
(Driver) qsgw_vxc_basis
Basis of the full Vxc matrices: state or nao (ABACUS AO input).
Type:
stringDefault:
stateStatus: Experimental
Applies to both SCF and band matrices. The ABACUS _nao filename suffix
does not determine the matrix basis: standard out_mat_xc exports states.
(Driver) qsgw_write_iteration_matrices
Write per-iteration matrices used by numerical regression tests.
Type:
boolDefault: false
Status: Experimental
(API) read_sigc_mat_rf
Flag of reading NAO correlation self-energy matrix in real-space/frequency form.
Type:
boolDefault: false
Status: Experimental
Reads indexed SigcRF .bin checkpoints. The file of rank 0 gives the number of ranks and the run_id of the checkpoint; files of higher ranks in the directory are ignored with a warning, and a missing file, a file of another run, or a rank count that disagrees with the header stops the run. The number of ranks of the restart job may differ. Legacy .dat checkpoints remain readable but are deprecated and will be removed in a future release; for them the number of ranks is still taken from the largest rank in the file names.
(API) replace_w_head
Flag of replacing head of screened interaction by macroscopic dielectric function.
Type:
boolDefault: false
(API) restart_from_dir
Directory to read restart checkpoint files from. Empty uses output_dir.
Type:
stringDefault: empty
Status: Experimental
Set with librpa_set_restart_from_dir() or librpa::Options::set_restart_from_dir()
so directory normalization is applied.
(API) rpa_headwing_body_start
First regular Coulomb-eigenbasis channel used by RPA head/wing correction.
Type:
intDefault: 0
Status: Experimental
Zero uses channel 1 in the current analytic 3D/2D head/wing path. Minus one is reserved for Sternheimer finite-part Coulomb input and keeps every retained positive Coulomb eigenchannel as a regular body channel.
(API) rpa_headwing_mode
RPA Gamma correction mode: “qavg” keeps the current head/wing q-average,
Type:
stringDefault: not documented
“head_only” replaces only the analytic head before the ordinary trace-log.
(API) sf_gf_omega_shift
Broadening/shift used for Green’s function in spectral-function output, in Hartree.
Type:
doubleDefault: 0.01
Status: Experimental
(Driver) sf_omega_end
Ending frequency for spectral-function output.
Type:
doubleDefault: 1.0
Status: Experimental
(Driver) sf_omega_start
Starting frequency for spectral-function output.
Type:
doubleDefault: 0.0
Status: Experimental
(Driver) sf_omega_step
Frequency step for spectral-function output.
Type:
doubleDefault: 0.1
Status: Experimental
(API) sf_sigc_omega_shift
Broadening/shift used for correlation self-energy in spectral-function output, in Hartree.
Type:
doubleDefault: 0.01
Status: Experimental
(Driver) sf_state_end
Last state index for spectral-function output, exclusive.
Type:
intDefault: -1
Status: Experimental
Negative values inherit i_state_high after QP state-range normalization.
(Driver) sf_state_start
First state index for spectral-function output, inclusive.
Type:
intDefault: -1
Status: Experimental
Negative values inherit i_state_low after QP state-range normalization.
(API) sqrt_coulomb_threshold
Threshold of eigenvalues to perform square root of Coulomb matrices.
Type:
doubleDefault: 0.0
(Driver) sternheimer_iq
One-based q index for Sternheimer-RPA postprocessing.
Type:
intDefault: 1
Status: Experimental
(Driver) sternheimer_matrix_only
Reconstruct only fixed-q aggregate and k-resolved response matrices.
Type:
boolDefault: false
Status: Experimental
This diagnostic mode skips q-star coverage, Coulomb input, and RPA energy.
(Driver) sternheimer_qweight
q-point weight for Sternheimer-RPA postprocessing.
Type:
doubleDefault: 1.0
Status: Experimental
(Driver) task
Task type.
Type:
stringDefault: required (
rpa,g0w0,exx,exx_band,hartree)
(API) tfgrids_freq_interval
Frequency interval for even-spaced grids, in Hartree.
Type:
doubleDefault: 0.0
(API) tfgrids_freq_max
Maximum frequency for grid generation, in Hartree.
Type:
doubleDefault: 1000.0
(API) tfgrids_freq_min
Minimum frequency for grid generation, in Hartree.
Type:
doubleDefault: 0.005
(API) tfgrids_time_interval
Time interval for even-spaced grids, in Hartree^-1.
Type:
doubleDefault: 0.0
(API) tfgrids_time_min
Minimum time for grid generation, in Hartree^-1.
Type:
doubleDefault: 0.005
(API) tfgrids_type
Type of time/frequency grids.
Type:
enum/stringDefault: LIBRPA_TFGRID_UNSET
Available driver values: GL, GC-I, GL-II, minimax, evenspaced, evenspaced_tf.
The driver maps the unset API value to minimax.
Only minimax and evenspaced_tf have time nodes.
The other grids have frequency nodes only. See chi0_method.
(API) use_2d_dielectric
Switch of using the strict 2D analytic dielectric function.
Type:
boolDefault: false
Status: Experimental
With replace_w_head=true and option_dielect_func=3, the Gamma-cell average
uses the 2D \(2\pi/q\) asymptotics in the fixed full-Ewald Coulomb eigenbasis.
Both dielectric screening and finite-q Wc use full 2D Ewald Coulomb; no cut
Coulomb matrix is used by this path. The standalone reader-v1 driver obtains
the auxiliary-basis monopole norm from producer metadata and computes the
PW-to-auxiliary normalization internally; it is not a runtime parameter.
(API) use_cholesky_gw_wc
Flag of using cholesky factorization for computing Wc from chi0.
Type:
boolDefault: false
Status: Experimental
(API) use_elpa_sqrt_coulomb
Flag of using ELPA for sqrt Coulomb matrix.
Type:
boolDefault: Build-dependent: true with
LIBRPA_USE_ELPA, false otherwise.Status: Experimental
(API) use_fullcoul_eps
Switch of using full Coulomb interaction in \(\varepsilon = 1 - v \chi^0\).
Type:
boolDefault: true
The strict 2D analytic head/wing path requires this switch to be true so that the fixed Gamma Coulomb eigenbasis is defined by the full Ewald matrix.
(API) use_fullcoul_exx
Switch of using full Coulomb interaction in exact-exchange operator.
Type:
boolDefault: false
(API) use_fullcoul_wc
Switch of using full Coulomb interaction in \(W^c = (\varepsilon^{-1} - 1) v\).
Type:
boolDefault: false
The strict 2D analytic head/wing path requires this switch to be true. It uses the full 2D Ewald interaction at every finite q and analytically replaces the singular Gamma head/wing of the complete Wc matrix.
(API) use_gpu_replace_scalapack
Flag of using GPU for computing Wc from chi0.
Type:
boolDefault: Build-dependent: true when a CUDA/HIP build detects a device, false otherwise.
Status: Experimental
(API) use_hedin_shift
Compute and apply Hedin shifts in QP solves.
Type:
boolDefault: false
Status: Experimental
and evaluate the correlation self-energy in QP solves at $\( \Sigma_c(E - E_F - \Delta_{rks}). \)$
(API) use_kpara_scf_eigvec
Flag to specify parallel distribution of eigenvectors of SCF starting point.
Type:
boolDefault: false
Status: Experimental
(Driver) use_pyatb
Use PyATB mean-field data for dielectric head/wing calculations.
Type:
boolDefault: false
Status: Experimental
(API) use_qpe_adaptive_damp
If enabled, adapt the QPE damping factor during the solve.
Type:
boolDefault: false
(API) use_qpe_legacy_update
Test-only switch to recover the legacy non-adaptive QPE update.
Type:
boolDefault: false
Status: Diagnostic
Ignored when adaptive damping is enabled.
(Driver) use_rpa_gamma
Include the Gamma-point contribution in the reported RPA q sum.
Type:
boolDefault: true
(API) use_scalapack_ecrpa
Flag to control whether to use ScaLAPACK to compute RPA correlation energy.
Type:
boolDefault: true
(API) use_scalapack_gw_wc
Flag of using ScaLAPACK for computing Wc from chi0.
Type:
boolDefault: true
(API) use_shrink_abfs
Flag to use a compressed auxiliary basis.
Type:
boolDefault: false
Status: Experimental
(API) use_shrink_chi
Flag to compress response function using shrinked basis.
Type:
boolDefault: true
Status: Experimental
(Driver) use_spinor_wfc
Read wavefunctions in spinor format.
Type:
boolDefault: false
(API) use_symmetry_exx
Switch of using the symmetry context in exact-exchange paths.
Type:
boolDefault: false
Status: Experimental
(API) use_symmetry_gw
Switch of using the symmetry context in GW paths.
Type:
boolDefault: false
Status: Experimental
(API) use_symmetry_rpa
Switch of using the symmetry context in RPA/chi0 paths.
Type:
boolDefault: false
Status: Experimental
(Driver) version_coul_reader
Coulomb reader-version selector.
Type:
intDefault: -1
Status: Experimental
Available values:
-1: auto-detect from the first file matching the prefix.
0: legacy text or binary rectangular matrix blocks.
1: binary v1 files with atom-pair blocks.
(Driver) version_lri_reader
Local RI coefficient reader-version selector.
Type:
intDefault: -1
Status: Experimental
Available values:
-1: auto-detect from the first file matching the prefix.
0: legacy text or legacy binary files.
1: binary v1 files with a block table and payload offsets.
(API) vq_threshold
Threshold for real-space Coulomb matrices.
Type:
doubleDefault: 0.0