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.	`./`
`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_`
`version_coul_reader`	Coulomb reader-version selector.	-1
`version_lri_reader`	Local RI coefficient reader-version selector.	-1

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.	6
`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)

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_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 2D 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

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_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.