Runtime Parameters

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.in in the working directory using key = value syntax. Unlike the API, the driver requires task to 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
`constants_choice`	Physical constants source.	`internal` (`internal`, `aims`)
`cs_threshold`	Screening threshold when reading RI coefficient data.	1e-6
`i_state_high`	Last state index for printed QP energies, exclusive.	999999
`i_state_low`	First state index for printed QP energies, inclusive.	0
`output_energy_qp`	Output quasiparticle energies for external BSE workflows.	false
`output_gw_spec_func`	Output GW spectral-function data.	false
`output_hamgnn`	Output GW energies for HamGNN machine-learning workflows.	false
`output_level`	Verbosity level for driver output.	`info` (`silent`, `critical`, `info`, `warn`, `debug`)
`sf_omega_end`	Ending frequency for spectral-function output.	1.0
`sf_omega_start`	Starting frequency for spectral-function output.	0.0
`sf_omega_step`	Frequency step for spectral-function output.	0.1
`sf_state_end`	Last state index for spectral-function output, exclusive.	-1
`sf_state_start`	First state index for spectral-function output, inclusive.	-1
`task`	Task type.	required (`rpa`, `g0w0`, `exx`, `exx_band`)
`use_pyatb`	Use PyATB mean-field data for dielectric head/wing calculations.	false
`use_spinor_wfc`	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
`fn_band_kpath_info`	Band-path k-point metadata filename.	`band_kpath_info`
`fn_basis`	Deprecated combined basis-set fallback filename.	`basis_out`
`fn_basis_aux`	Auxiliary-basis metadata filename.	`basis_aux_out`
`fn_basis_aux_shrink`	Compressed auxiliary-basis metadata filename used with `use_shrink_abfs = true`.	`basis_aux_shrink_out`
`fn_basis_wfc`	Wave-function basis metadata filename.	`basis_wfc_out`
`fn_bz_sampling`	Brillouin-zone sampling filename.	`bz_sampling_out`
`fn_dielfunc`	Dielectric-function filename for dielectric-head correction.	`dielecfunc_out`
`fn_eigocc_scf`	SCF eigenvalue and occupation filename.	`band_out`
`fn_stru`	Structure-data filename.	`stru_out`
`fn_vxc_scf`	SCF exchange-correlation potential filename.	`vxc_out`
`input_dir`	Input directory to find and read the AO dataset.	`./`
`input_preset`	Preset for producer-specific input filenames and head/wing velocity readers.	`fhi-aims` (`fhi-aims`, `aims`, `abacus`, `abacus-legacy`)
`prefix_coul_cut`	Prefix of truncated Coulomb matrix files.	`coulomb_cut`
`prefix_coul_full`	Prefix of bare Coulomb matrix files.	`coulomb_mat`
`prefix_eigvecs_scf`	Prefix of SCF Kohn-Sham eigenvector files.	`KS_eigenvector`
`prefix_lri_coeff`	Prefix of localized RI coefficient files.	`Cs_data`
`prefix_lri_coeff_shrink`	Prefix of compressed-auxiliary-basis RI coefficient files.	`Cs_shrinked_data`
`prefix_shrink_sinvS`	Prefix of shrink auxiliary-basis transform files.	`shrink_sinvS_`
`prefix_velocity`	Prefix of velocity/momentum-matrix files.	`mommat_ks_kpt_`
`version_coul_reader`	Coulomb reader-version selector.	-1
`version_lri_reader`	Local RI coefficient reader-version selector.	-1

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), int32 natoms, double omega (Hartree), double weight (Hartree), int32 nblocks, then natoms int32 atom_naux values. The block table stores zero-based atom-pair indices and absolute int64 payload offsets. Each payload is a dense row-major complex atom-pair block; the assembled matrix M is in the auxiliary-basis response convention and must not be pre-normalized by Coulomb. The energy consumer constructs Pi = V^(-1/2) M V^(-1/2), with the configured Coulomb eigenvalue filter, before evaluating the trace-log. Coulomb v1 files use the same auxiliary atom-pair block convention and are indexed by one-based canonical q-star representative.

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
`fn_sternheimer_partial_manifest`	Sternheimer partial-response manifest with rows	empty
`fn_sternheimer_qpoints`	Sternheimer q-point manifest filename with rows `iq qx qy qz qweight`.	empty
`fn_sternheimer_qstar_routes`	Explicit inverse routes from every full-q member to the discrete	empty
`fn_sternheimer_symmetry_routes`	Explicit fixed-q inverse routes provided by the producer for reconstruction	empty
`prefix_sternheimer_chi0`	Prefix of Sternheimer chi0 v1 response files.	`v1_sternheimer_chi0_iq_`
`prefix_sternheimer_kresolved`	Optional prefix for fixed-q k-resolved Sternheimer response matrices.	empty
`prefix_sternheimer_reconstructed`	Optional prefix for reconstructed full-q Sternheimer chi0 v1 files.	empty
`prefix_sternheimer_symmetry_diagnostic`	Optional prefix for fixed-q Sternheimer symmetry route diagnostics.	empty
`sternheimer_iq`	One-based q index for Sternheimer-RPA postprocessing.	1
`sternheimer_matrix_only`	Reconstruct only fixed-q aggregate and k-resolved response matrices.	false
`sternheimer_qweight`	q-point weight for Sternheimer-RPA postprocessing.	1.0
`use_rpa_gamma`	Include the Gamma-point contribution in the reported RPA q sum.	true

Common Settings#

Parameter Name	Description	Default Value
`minimax_emax`	Maximal transition energy when generating minimax grids.	-1.0
`minimax_emin`	Minimal transition energy when generating minimax grids.	-1.0
`minimax_regulation`	Regulation for minimax grids generation.	0.0
`nfreq`	Number of time/frequency points.	16
`option_bvk_remap`	BvK remapping convention for band interpolation.	1
`output_dir`	Output directory for results.	librpa.d/
`parallel_routing`	Scheme of parallelization.	LIBRPA_ROUTING_AUTO
`restart_from_dir`	Directory to read restart checkpoint files from. Empty uses `output_dir`.	empty
`tfgrids_freq_interval`	Frequency interval for even-spaced grids, in Hartree.	0.0
`tfgrids_freq_max`	Maximum frequency for grid generation, in Hartree.	1000.0
`tfgrids_freq_min`	Minimum frequency for grid generation, in Hartree.	0.005
`tfgrids_time_interval`	Time interval for even-spaced grids, in Hartree^-1.	0.0
`tfgrids_time_min`	Minimum time for grid generation, in Hartree^-1.	0.005
`tfgrids_type`	Type of time/frequency grids.	LIBRPA_TFGRID_UNSET
`use_kpara_scf_eigvec`	Flag to specify parallel distribution of eigenvectors of SCF starting point.	false
`vq_threshold`	Threshold for real-space Coulomb matrices.	0.0

Coulomb Matrices#

Parameter Name	Description	Default Value
`output_abacus_gw_gf`	Switch of outputting ABACUS-compatible GW Green’s-function data.	false
`use_fullcoul_eps`	Switch of using full Coulomb interaction in \(\varepsilon = 1 - v \chi^0\).	true
`use_fullcoul_exx`	Switch of using full Coulomb interaction in exact-exchange operator.	false
`use_fullcoul_wc`	Switch of using full Coulomb interaction in \(W^c = (\varepsilon^{-1} - 1) v\).	false
`use_symmetry_exx`	Switch of using the symmetry context in exact-exchange paths.	false
`use_symmetry_gw`	Switch of using the symmetry context in GW paths.	false
`use_symmetry_rpa`	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
`gf_threshold`	Threshold for real-space Green’s function in response function calculation.	0.0
`libri_chi0_collect_max_bytes`	Maximum estimated local chi0 tensor bytes per LibRI collection chunk; 0 keeps one-shot collection.	0
`libri_chi0_collect_s0_chunk`	Number of first-index atoms per LibRI chi0 collection chunk; 0 keeps one-shot collection.	0
`n_bands_chi0`	Maximal number of bands for computing response function.	-1 (< 0 for all bands)
`n_bands_exclude_chi0`	Number of lowest bands excluded from both Green’s functions forming the response function.	0

RPA correlation#

Parameter Name	Description	Default Value	Since
`use_scalapack_ecrpa`	Flag to control whether to use ScaLAPACK to compute RPA correlation energy.	true

ABF Compression#

Parameter Name	Description	Default Value	Since
`use_shrink_abfs`	Flag to use a compressed auxiliary basis.	false
`use_shrink_chi`	Flag to compress response function using shrinked basis.	true

GW#

Parameter Name	Description	Default Value
`anacon_nfreq`	Number of points in the optional GW analytic-continuation frequency grid.	-1
`anacon_tfgrids_type`	Type of optional frequency grid used for GW analytic continuation.	LIBRPA_TFGRID_UNSET
`istate_ref_hedin_shift`	Absolute zero-based reference state index for Hedin shifts.	-1
`n_bands_exclude_sigc`	Number of lowest bands excluded from the Green’s function multiplying Wc in the correlation self-energy.	0
`n_bands_sigc`	Maximal number of bands for computing correlation self-energy.	-1 (< 0 for all bands)
`n_params_anacon`	Number of parameters for analytic continuation.	-1 (uses all `nfreq` data)
`n_params_anacon_resample`	Number of parameters for the source-grid Pade used to resample GW analytic continuation.	-1
`option_dielect_func`	Option of computing dielectric function on imaginary axis.	0
`option_qpe_solver`	Quasi-particle equation solver option.	0
`override_qpe_solver_nan`	If enabled, keep the final unconverged QPE iterate instead of outputting NaN.	false
`qpe_solver_damp_factor`	Damping factor for quasi-particle equation solver updates.	0.1
`qpe_solver_n_iter_max`	Maximum number of iterations for the quasi-particle equation solver; must be positive.	10000
`qpe_solver_thres`	Convergence threshold for the quasi-particle equation solver, in Hartree.	1.0e-6
`read_sigc_mat_rf`	Flag of reading NAO correlation self-energy matrix in real-space/frequency form.	false
`replace_w_head`	Flag of replacing head of screened interaction by macroscopic dielectric function.	false
`rpa_headwing_body_start`	First regular Coulomb-eigenbasis channel used by RPA head/wing correction.	0
`rpa_headwing_mode`	RPA Gamma correction mode: “qavg” keeps the current head/wing q-average,
`sf_gf_omega_shift`	Broadening/shift used for Green’s function in spectral-function output, in Hartree.	0.01
`sf_sigc_omega_shift`	Broadening/shift used for correlation self-energy in spectral-function output, in Hartree.	0.01
`sqrt_coulomb_threshold`	Threshold of eigenvalues to perform square root of Coulomb matrices.	0.0
`use_2d_dielectric`	Switch of using the strict 2D analytic dielectric function.	false
`use_cholesky_gw_wc`	Flag of using cholesky factorization for computing Wc from chi0.	false
`use_elpa_sqrt_coulomb`	Flag of using ELPA for sqrt Coulomb matrix.	Build-dependent: true with `LIBRPA_USE_ELPA`, false otherwise.
`use_gpu_replace_scalapack`	Flag of using GPU for computing Wc from chi0.	Build-dependent: true when a CUDA/HIP build detects a device, false otherwise.
`use_hedin_shift`	Compute and apply Hedin shifts in QP solves.	false
`use_qpe_adaptive_damp`	If enabled, adapt the QPE damping factor during the solve.	false
`use_qpe_legacy_update`	Test-only switch to recover the legacy non-adaptive QPE update.	false
`use_scalapack_gw_wc`	Flag of using ScaLAPACK for computing Wc from chi0.	true

QSGW#

These experimental driver parameters apply only to task = qsgw or task = qsgw_band. Same-grid analytic head-only updates are enabled with replace_w_head = true and option_dielect_func = 4. The aligned velocity remains in the immutable mf0 basis while live eigenvalues and eigenvectors are updated after each diagonalization. Independent-grid head/wing and Hartree updates are not supported. Linear mixing is regression-tested for molecular QSGW only; the current solid-state benchmark uses qsgw_mixer = none. 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
`prefix_vxc_band`	Full band Vxc matrix prefix, relative to `input_dir` unless absolute.	Empty (producer default)
`prefix_vxc_scf`	Full SCF Vxc matrix prefix, relative to `input_dir` unless absolute.	Empty (producer default)
`qsgw_band0_cut_mode`	qsgw_band H_QSGW cut: 0 uncut, 1 KS diagonal, 2 shifted KS diagonal.	0
`qsgw_band0_cut_shift_ha`	Hamiltonian energy shift applied to cut states in mode 2, in Hartree.	20.0
`qsgw_band0_unoccupied_keep`	Number of unoccupied states retained by qsgw_band H_QSGW cut.	10
`qsgw_convergence_tolerance_ev`	Maximum eigenvalue change used for convergence, in eV.	1.0e-4
`qsgw_max_iter`	Maximum number of QSGW updates.	10
`qsgw_min_iter`	Minimum number of QSGW updates before convergence may terminate the run.	1
`qsgw_mixer`	Fixed-basis Hamiltonian mixing (`none` or `linear`).	`none`
`qsgw_mixing_beta`	Linear Hamiltonian mixing fraction.	0.2
`qsgw_vxc_basis`	Basis of the full Vxc matrices: `state` or `nao` (ABACUS AO input).	`state`
`qsgw_write_iteration_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
`libri_chi0_threshold_C`	Threshold of real-space LRI triple coefficients to compute response function using LibRI.	0.0
`libri_chi0_threshold_G`	Threshold of real-space Green’s function to compute response function using LibRI.	0.0
`libri_exx_threshold_C`	Threshold of real-space LRI triple coefficients to compute exact exchange using LibRI.	0.0
`libri_exx_threshold_D`	Threshold of real-space density matrices to compute exact exchange using LibRI.	0.0
`libri_exx_threshold_V`	Threshold of real-space Coulomb matrices to compute exact exchange using LibRI.	0.0
`libri_g0w0_threshold_C`	Threshold of real-space LRI triple coefficients to compute GW correlation self-energy using LibRI.	0.0
`libri_g0w0_threshold_G`	Threshold of real-space Green’s function to compute GW correlation self-energy using LibRI.	0.0
`libri_g0w0_threshold_Wc`	Threshold of correlation screened Coulomb matrix to compute GW correlation self-energy using LibRI.	0.0

Output Control#

Parameter Name	Description	Default Value
`ifreq_output_wc_end`	Half-open Wc frequency output end index; negative means all remaining frequencies.	-1
`ifreq_output_wc_start`	First zero-based Wc frequency index to output.	0
`istate_output_mat_end`	Half-open KS-state end index when exporting KS-basis matrices; negative	-1
`istate_output_mat_start`	First zero-based KS state included in both dimensions when exporting the	0
`output_exx_ks_mat_k`	Output exact-exchange matrix in KS basis and k-space.	false
`output_exx_mat_k`	Output exact-exchange matrix in NAO basis and k-space as dense binary files.	false
`output_exx_mat_r`	Output real-space NAO exact-exchange blocks after symmetry restoration,	false
`output_gw_sigc_ks_kf`	Output KS-diagonal correlation self-energy in k-space, imaginary frequency domain.	false
`output_gw_sigc_ks_mat_kf`	Output correlation self-energy matrix in KS basis (k-space, imaginary frequency domain).	false
`output_gw_sigc_mat_kf`	Output correlation self-energy matrix in NAO basis (k-space, imaginary frequency domain).	false
`output_gw_sigc_mat_rf`	Output correlation self-energy matrix in NAO basis (real space, imaginary frequency domain).	false
`output_gw_sigc_mat_rt`	Output correlation self-energy matrix in NAO basis (real space, imaginary time domain).	false
`output_wc_rf`	Output Wc matrix in ABFs (real space, imaginary frequency domain).	false
`output_wc_rf_atom_pair`	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
`debug`	`output_level`	`debug = true` maps to `output_level = debug`
`use_soc`	`use_spinor_wfc`	Old spelling for selecting spinor-format driver input
`tfgrid_type`	`tfgrids_type`	Old spelling
`gf_R_threshold`	`gf_threshold`	Old spelling
`output_gw_sigc_ks_if`	`output_gw_sigc_ks_kf`	Old spelling
`output_gw_sigc_mat`	`output_gw_sigc_ks_mat_kf`	Old spelling
`option_output_Wc_Rf_mat`	`output_wc_rf`, `ifreq_output_wc_start`, `ifreq_output_wc_end`	`0` disables output, `1` maps to `[0,1)`, `2` maps to `[0,all)`

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.