Manual

The complete WEST reference for input parameters.

Note

Not all input parameters listed below are mandatory. Check Quick Reference or Tutorials pages to see examples of input files.

See also

WESTpy is a Python package, designed to assist users of the WEST code in pre- and post-processing massively parallel calculations. Click here to know more.

See also

The input file is given according to the YAML Notation (https://yaml.org/).

input_west

qe_prefix

Type	string
Default	“pwscf”
Description	Prefix prepended to the Quantum ESPRESSO save folder.

west_prefix

Type	string
Default	“west”
Description	Prefix prepended to the WEST save and restart folders.

outdir

Type	string
Default	“./”
Description	Directory for: input, temporary, and output files.

wstat_control

wstat_calculation

Type	string
Default	“S”
Description	Available options are: “S” : Start from scratch. “R” : Restart from an interrupted run. You should restart with the same number of MPI tasks and parallelization flags. “E” : Calculation of the response is external, i.e. outsourced to a server.

n_pdep_eigen

Type	int
Default	dynamically set to match the number of electrons
Description	Number of PDEP eigenpotentials.

n_pdep_times

Type	int
Default	4
Description	Maximum dimension of the search space = n_pdep_eigen * n_pdep_times.

n_pdep_maxiter

Type	int
Default	100
Description	Maximum number of iterations in PDEP.

n_dfpt_maxiter

Type	int
Default	250
Description	Maximum number of iterations in DFPT.

n_pdep_read_from_file

Type	int
Default	0
Description	Number of PDEP eigenpotentials that can be read from file.

n_steps_write_restart

Type	int
Default	1
Description	Available options are: If ( n_steps_write_restart > 0 ) A checkpoint is written every n_steps_write_restart iterations in the Davidson loop. If ( n_steps_write_restart <= 0 ) A checkpoint is NEVER written in the Davidson loop. Restart will not be possible.

trev_pdep

Type	float
Default	0.001
Description	Absolute convergence threshold for PDEP eigenvalues.

trev_pdep_rel

Type	float
Default	0.1
Description	Relative convergence threshold for PDEP eigenvalues.

tr2_dfpt

Type	float
Default	1.e-16
Description	Convergence threshold in DFPT. Note that in the first PDEP iterations a reduced threshold for DFPT could be used by the code in order to speed up the computation.

l_kinetic_only

Type	bool
Default	False
Description	If (True), then only the kinetic term in the Hamiltonian is kept.

l_minimize_exx_if_active

Type	bool
Default	False
Description	If (True), then the exact-exchange term in the Hamiltonian is computed with the cutoff of the wavefunction. Used only when n_exx_lowrank = 0.

n_exx_lowrank

Type	int
Default	dynamically set to match the number of bands, read from the ground state
Description	If ( n_exx_lowrank > 0 ), then the exact-exchange is computed with a low-rank approximation of rank n_exx_lowrank.

l_use_ecutrho

Type	bool
Default	False
Description	If (True), then the eigenpotentials are represented with ecutrho instead of ecutwfc.

qlist

Type	list of int
Default	[1,2,…,number of q-points]
Description	List of q-points to compute.

wfreq_control

wfreq_calculation

Type	string
Default	“XWGQ”
Description	Available options are: “XWGQ” : Compute the QP corrections. “XwGQ” : Restart an interrupted “XWGQ” run if “W” has finished but “G” and “Q” have not. “XwgQ” : Restart an interrupted “XWGQ” run if “W” and “G” have finished but “Q” has not. “XWGQH” : Compute the QP corrections and parameters of QDET effective Hamiltonian. Only available for Gamma-point sampling. “XwGQH” : Restart an interrupted “XWGQH” run if “W” has finished but “G”, “Q”, and “H” have not. “X” : Compute the HF corrections. “XWO” : Compute the optical properties. “XWGQP” : Compute the QP corrections, and plot spectral functions. “XWGQOP” : Compute the QP corrections and optical properties, and plot spectral functions.

n_pdep_eigen_to_use

Type	int
Default	dynamically set to match the number of electrons
Description	Number of PDEP eigenvectors to use in wfreq. They are read from previous wstat run. This value cannot exceed n_pdep_eigen (defined in wstat_control) and is used to check the convergence of the calculation.

qp_bandrange

Type	2-dim list of int
Default	[1,2]
Description	Compute the QP corrections from band qp_bandrange[0] to band qp_bandrange[1]. Used only when qp_bands is not set. If qp_bands is set, the value of qp_bandrange is discarded.

qp_bands

Type	list of int
Default	[0]
Description	List of bands to compute the QP corrections. If nspin = 2, two distinct sets of bands can be specified for the two spin channels, for example, [[1, 3, 4], [2, 3, 4]]. If nspin = 2 and qp_bands specifies only one set of bands, then the same bands are used for both channels. If qp_bands is not set, it is determined from qp_bandrange as [qp_bandrange(1), qp_bandrange(1)+1, …, qp_bandrange(2)].

macropol_calculation

Type	string
Default	“C”
Description	Available options are: “N” : None. Choice valid for isolated systems. “C” : Include long-wavelength limit. Choice valid for condensed systems.

n_lanczos

Type	int
Default	30
Description	Number of Lanczos chains.

n_imfreq

Type	int
Default	128
Description	Number of frequecies used to sample the imaginary frequency axis in the range [0,ecut_imfreq].

n_refreq

Type	int
Default	272
Description	Number of frequecies used to sample the real frequency axis in the range [0,ecut_refreq].

ecut_imfreq

Type	float
Default	dynamically set to the cutoff energy of the density, read from the ground state
Description	Cutoff for the imaginary frequencies (in Ry).

ecut_refreq

Type	float
Default	2.0
Description	Cutoff for the real frequencies (in Ry).

wfreq_eta

Type	float
Default	0.05 / 13.6056980659
Description	Energy shift of the poles (in Ry).

n_secant_maxiter

Type	int
Default	21
Description	Maximum number of iterations in the secant solver.

trev_secant

Type	float
Default	0.05 / 13.6056980659
Description	Convergence energy threshold (in Ry) for the secant solver.

l_enable_lanczos

Type	bool
Default	True
Description	If (False), then Lanczos solvers are turned off.

l_qdet_verbose

Type	bool
Default	False
Description	Controls what two-body terms of the QDET effective Hamiltonian are written to file. If (False), then only the partially screened two-body terms are written to file. If (True), then the fully screened, partially screened, and bare two-body terms are written to file.

l_enable_off_diagonal

Type	bool
Default	False
Description	If (False), then only the diagonal matrix elements of the \({G_0 W_0}\) self-energy are evaluated (i.e., same band). If (True), then both the diagonal and off-diagonal matrix elements of the \({G_0 W_0}\) self-energy are evaluated (mixing different bands). In this case the upper triangular part of the self-energy matrix is calculated and written to file according to \({ {\left[ \Sigma \right]}_{ij} = \frac{1}{2} \mathrm{Re} \; \left[ {\left[ \Sigma \right]}_{ij} (\epsilon^{\mathrm{QP}}_i) + {\left[ \Sigma \right]}_{ij}(\epsilon^{\mathrm{QP}}_j) \right] }\). l_enable_off_diagonal can be set to True only when the Brillouin Zone is sampled at the \({\Gamma}\)-point.

n_pdep_eigen_off_diagonal

Type	int
Default	0
Description	Deprecated parameter.

l_enable_gwetot

Type	bool
Default	False
Description	Deprecated parameter.

o_restart_time

Type	float
Default	0.0
Description	Deprecated parameter.

ecut_spectralf

Type	2-dim list of float
Default	[-2.0,1.0]
Description	Energy cutoff (in Ry) for the real frequencies. Used when wfreq_caculation contains the runlevel “P”.

n_spectralf

Type	int
Default	204
Description	Number of frequecies used to plot the spectral function (the “P” runlevel), sampling the interval [ecut_spectralf[0],ecut_spectralf[1]].

qdet_dc

Type	string
Default	“DC2025”
Description	Controls how the QDET double counting is treated. Used only when wfreq_calculation contains “H”. “DC2025” : 2025 version of refined double counting. “DC2022” : 2022 version of double counting. “HFDC” : Hartree-Fock double counting.

westpp_control

westpp_calculation

Type	string
Default	“R”
Description	Available options are: “R” : Output rho, the electronic density. “W” : Output the electronic wavefunctions. “E” : Output the eigenpotentials. “S” : Output the screened exchange constant. “D” : Output the dipole matrix elements. “L” : Output the localization factor and the inverse participation ratio. “X” : Output the exciton state. “P” : Output the density response to exciton state. “B” : Output the unitary transformation matrix of Boys/Wannier localization. “C” : Output the decomposition of BSE/TDDFT excited state, and the transition dipole moments. “M” : Output the spin multiplicity of the BSE/TDDFT excited state (<S^2>, nspin = 2).

westpp_range

Type	list of int
Default	[1,2]
Description	Range of bands in W, S, D, L, or B run. Range of PDEP eigenpotentials in E run. Range of excited states in X, P, C, or M run.

westpp_format

Type	string
Default	“C”
Description	Available options for the output fortmat are: “C” : Cube. “X” : Planar average yz. “Y” : Planar average xz. “Z” : Planar average xy. “S” : Spherical average.

westpp_sign

Type	bool
Default	False
Description	If (True), then the sign of the wavefunction/eigenpotential is kept in the output file.

westpp_n_pdep_eigen_to_use

Type	int
Default	1
Description	Number of PDEP eigenpotentials to read/use. Used only when westpp_calculation = “E”.

westpp_r0

Type	3-dim list of floats (a vector)
Default	[0.0, 0.0, 0.0]
Description	Position of the center (in a.u.) for spherical average plot or localization factor in a sphere.

westpp_nr

Type	int
Default	100
Description	Number of points in the spherical average plot or localization factor in a sphere.

westpp_rmax

Type	float
Default	1.0
Description	Max radius (in a.u.) for the spherical average plot or localization factor in a sphere.

westpp_epsinfty

Type	float
Default	1.0
Description	Macroscopic relative dielectric constant. Used only when westpp_calculation = “S”.

westpp_box

Type	6-dim list of floats (a vector)
Default	[0.0, 0.0, 0.0, 0.0, 0.0, 0.0]
Description	Box [x_0, x_1, y_0, y_1, z_0, z_1] (in a.u.) within which the localization factor is computed (the “L” runlevel).

westpp_n_liouville_to_use

Type	int
Default	1
Description	Number of Liouville eigenvectors to read/use. Used only when westpp_calculation = “X”, “P”, “C”, or “M”.

westpp_l_spin_flip

Type	bool
Default	False
Description	If (True), then a spin-flip calculation is performed. Used only when westpp_calculation = “C” or “M” and nspin = 2.

westpp_l_compute_tdm

Type	bool
Default	False
Description	If (True), then the transition dipole moment is computed. Used only when westpp_calculation = “C”.

westpp_wannier_tr_rel

Type	float
Default	1e-6
Description	Relative convergence threshold for Wannier localization. Used only when westpp_calculation = “B”.

westpp_l_dipole_realspace

Type	bool
Default	False
Description	Controls how the dipole is computed. Used only when westpp_calculation = “C”. If (False), then the dipole is computed in the reciprocal space by computing [H,r]. Choice valid for isolated and condensed systems. If (True), then the dipole is computed in the real space. Choice valid for isolated systems only.

server_control

document

Type	jsonizable object
Default	“{}”
Description	The document is serialized into a JSON string and passed to the server (see West/Pytools/west_clientserver.py).

wbse_init_control

wbse_init_calculation

Type	string
Default	“S”
Description	Available options are: “S” : Start from scratch. “R” : Restart from an interrupted run. You should restart with the same number of MPI tasks and parallelization flags.

solver

Type	string
Default	“BSE”
Description	Available options are: “BSE” : Bethe-Salpeter equation. “TDDFT” : Time-dependent density-functional theory.

bse_method

Type	string
Default	“PDEP”
Description	Available options are: “PDEP” : Use the PDEP eigenpotentials to compute screened exchange integrals. “FF_QBOX” : Use the finite field method with Qbox coupling to compute screened exchange integrals.

n_pdep_eigen_to_use

Type	int
Default	dynamically set to match the number of electrons
Description	Number of PDEP eigenvectors to use in wbse_init. They are read from previous wstat run. This value cannot exceed n_pdep_eigen (defined in wstat_control) and is used to check the convergence of the calculation.

localization

Type	string
Default	“N”
Description	Available options are: “N” : Kohn-Sham orbitals are not localized. “B” : Bisected orbitals are used. Valid only when bse_method = “FF_QBOX”. “W” : Wannier orbitals are used.

wannier_tr_rel

Type	float
Default	1e-6
Description	Relative convergence threshold for Wannier localization. Used only when localization = “W”.

wfc_from_qbox

Type	string
Default	“qb_wfc”
Description	Name of the file that contains Qbox wavefunctions. Used only when bse_method = “FF_QBOX” and localization = “B”.

bisection_info

Type	string
Default	“bis_info”
Description	Name of the file that contains info about bisection. Used only when bse_method = “FF_QBOX” and localization = “B”.

chi_kernel

Type	string
Default	“CHI”
Description	Available options are: “CHI” : \({W = v_c + v_c \chi v_c}\) “XC_CHI” : \({W = v_c + (v_c+f_{xc}) \chi v_c}\) \({W}\) and \({v_c}\) are the screened and bare Coulomb interactions, respectively, \({\chi}\) is the density-density response function, \({f_{xc}}\) is the exchange-correlation potential. In addition to \({\chi}\), \({\chi_{\mathrm{RPA}}}\) or \({\chi_{\mathrm{IPA}}}\) may be requested by specifying “approximation: RPA” or “approximation: IPA” in the document keyword of the server_control section (see also West/Pytools/west_clientserver.py).

overlap_thr

Type	float
Default	0.0
Description	If the overlap between two orbitals is below this threshold, the corresponding screened exchange integral is not computed. Used only when localization = “B” or “W”.

n_trunc_bands

Type	int
Default	0
Description	If n_trunc_bands > 0, then the n_trunc_bands lowest occupied bands are not considered when summing over occupied bands.

wbse_control

wbse_calculation

Type	string
Default	“D”
Description	Available options are: “D” : Diagonalize the Liouville super-operator with the Davidson iterative solver. “d” : Restart the calculation for wbse_calculation = “D” from an interrupted run. You should restart with the same number of MPI tasks and parallelization flags. “L” : Compute the absorption spectrum with the Lanczos method. “l” : Restart the calculation for wbse_calculation = “L” from an interrupted run. You should restart with the same number of MPI tasks and parallelization flags.

qp_correction

Type	string
Default	“None”
Description	Available options are: “None” : Quasiparticle corrections are not added. Specify the name of the wfreq output file (in JSON format) from which quasiparticle corrections are read.

scissor_ope

Type	float
Default	0.0
Description	Value of the scissor operator (in Ry).

n_liouville_eigen

Type	int
Default	1
Description	Number of Liouville eigenvectors and eigenvalues. Used only when wbse_calculation = “D” or “d”.

n_liouville_times

Type	int
Default	4
Description	Maximum dimension of the search space = n_liouville_eigen * n_liouville_times. Used only when wbse_calculation = “D” or “d”.

n_liouville_maxiter

Type	int
Default	100
Description	Maximum number of iterations of the Davidson method. Used only when wbse_calculation = “D” or “d”.

n_liouville_read_from_file

Type	int
Default	0
Description	Number of Liouville eigenvectors that can be read from file. Used only when wbse_calculation = “D” or “d”.

trev_liouville

Type	float
Default	0.001
Description	Absolute convergence threshold for Liouville eigenvalues. Used only when wbse_calculation = “D” or “d”.

trev_liouville_rel

Type	float
Default	0.1
Description	Relative convergence threshold for Liouville eigenvalues. Used only when wbse_calculation = “D” or “d”.

n_lanczos

Type	int
Default	1000
Description	Number of Lanczos iterations to be performed. Used only when wbse_calculation = “L” or “l”.

n_steps_write_restart

Type	int
Default	1
Description	Available options are: If ( n_steps_write_restart > 0 ) A checkpoint is written every n_steps_write_restart iterations in the Davidson or Lanczos loop. If ( n_steps_write_restart <= 0 ) A checkpoint is NEVER written in the Davidson or Lanczos loop. Restart will not be possible.

wbse_ipol

Type	string
Default	“XX”
Description	Controls which components of the polarizability tensor (alpha) are computed: “XX”: alpha_xx. “YY”: alpha_yy. “ZZ”: alpha_zz. “XYZ”: three Lanczos chains are sequentially performed and the full polarizability tensor and the absorption coefficient are computed.

l_dipole_realspace

Type	bool
Default	False
Description	Controls how the dipole is computed. Used only when wbse_calculation = “L” or “l”. If (False), then the dipole is computed in the reciprocal space by computing [H,r]. Choice valid for isolated and condensed systems. If (True), then the dipole is computed in the real space. Choice valid for isolated systems only.

wbse_epsinfty

Type	float
Default	1.0
Description	Macroscopic relative dielectric constant.

spin_excitation

Type	string
Default	“S”
Description	Used only when nspin = 1. If nspin = 2, use instead l_spin_flip to choose spin-conserving or spin-flip excitations. Available options are: “S” : Singlet. “T” : Triplet. Valid only when solver = “BSE”.

l_preconditioning

Type	bool
Default	False
Description	If (True), then preconditioning is used. Used only when wbse_calculation = “D” or “d”. Should be set to True in most cases.

l_pre_shift

Type	bool
Default	False
Description	If (True), then the preconditioner is shifted by the corresponding Kohn-Sham orbital energy. Used only when wbse_calculation = “D” or “d” and l_preconditioning is True. Should be set to True for isolated systems and False for perodic systems.

l_spin_flip

Type	bool
Default	False
Description	If (True), then a spin-flip calculation is performed. Used only when wbse_calculation = “D” or “d” and nspin = 2.

l_spin_flip_kernel

Type	bool
Default	False
Description	If (True), then the spin-flip kernel is used in the spin-flip calculations. Used only in spin-flip TDDFT calculations. Should be set to False for spin-flip BSE calculations.

l_spin_flip_alda0

Type	bool
Default	False
Description	If (True), then the ALDA0 approximation is used in the spin-flip kernel, i.e. the gradient correction to the exchange-correlation potential is discarded in the spin-flip kernel. Used only in spin-flip TDDFT calculations using GGA type exchange-correlation functionals and when l_spin_flip_kernel is True.

l_print_spin_flip_kernel

Type	bool
Default	False
Description	If (True), then the spin-flip kernel is written to a cube file. Used only in spin-flip TDDFT calculations and when l_spin_flip_kernel is True.

spin_flip_cut

Type	float
Default	1e-3
Description	Spin-flip cutoff to prevent divergence by setting values to zero on a grid point if the density on this point is smaller than spin_flip_cut. Used only in spin-flip TDDFT calculations.

l_forces

Type	bool
Default	False
Description	If (True), then analytical forces are computed for the forces_state excited state. Used only when wbse_calculation = “D” or “d”.

forces_state

Type	int
Default	1
Description	Excited state for which analytical forces are computed. Used only when l_forces is True.

forces_zeq_cg_tr

Type	float
Default	1e-10
Description	Convergence threshold in the CG method that solves the Z vector equation. Used only when l_forces is True.

forces_zeq_n_cg_maxiter

Type	int
Default	500
Description	Maximum number of iterations in the CG solver of the Z vector equation. Used only when l_forces is True.

ddvxc_fd_coeff

Type	float
Default	1e-2
Description	Finite difference step size to compute the second derivative of the local part of the exchange-correlation kernel. Used only when l_forces is True.

forces_inexact_krylov

Type	int
Default	0
Description	Apply the inexact krylov subspace approximation in the CG solver of the Z vector equation. Used only when l_forces is True. 0 : Do not apply the approximation. 1 : Skip the exact-exchange term once the CG solver converges to forces_inexact_krylov_tr. 2 : Skip the K_1d term once the CG solver converges to forces_inexact_krylov_tr. 3 : Skip the K_2d term once the CG solver converges to forces_inexact_krylov_tr. 4 : Skip the K_1d and K_2d terms once the CG solver converges to forces_inexact_krylov_tr. 5 : Skip the exact-exchange, K_1d, and K_2d terms once the CG solver converges to forces_inexact_krylov_tr.

forces_inexact_krylov_tr

Type	float
Default	1e-16
Description	Apply the inexact krylov subspace approximation if the norm of the residual vector is smaller than this threshold. Used only when l_forces is True.

l_minimize_exx_if_active

Type	bool
Default	False
Description	If (True), then the exact-exchange term in the Hamiltonian is computed with the cutoff of the wavefunction. Used only when n_exx_lowrank = 0.

n_exx_lowrank

Type	int
Default	dynamically set to match the number of bands, read from the ground state
Description	If ( n_exx_lowrank > 0 ), then the exact-exchange is computed with a low-rank approximation of rank n_exx_lowrank.

l_reduce_io

Type	bool
Default	True
Description	Deprecated parameter.