From 2ee94ed28040b0e0bf492800ca35b958160fe938 Mon Sep 17 00:00:00 2001 From: Bonan Zhu Date: Sun, 12 Jul 2026 13:49:09 +0800 Subject: [PATCH 1/9] docs: regenerate input parameters in RTD build --- .readthedocs.yaml | 34 ++++ docs/advanced/input_files/input-main.md | 259 +++++++++++++++--------- docs/generate_input_main.py | 12 +- docs/parameters.yaml | 158 +++++++++++---- 4 files changed, 327 insertions(+), 136 deletions(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index db95d725eba..8c8d52898d1 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -9,6 +9,40 @@ build: os: ubuntu-22.04 tools: python: "3.11" + apt_packages: + - build-essential + - cmake + - gfortran + - git + - libfftw3-dev + - liblapack-dev + - libopenblas-dev + - ninja-build + - pkg-config + jobs: + pre_build: + - > + cmake -S . -B build-rtd-docs -G Ninja + -DCMAKE_BUILD_TYPE=Release + -DENABLE_MPI=OFF + -DENABLE_LCAO=OFF + -DUSE_OPENMP=OFF + -DUSE_ELPA=OFF + -DUSE_CUDA=OFF + -DUSE_ROCM=OFF + -DBUILD_TESTING=OFF + -DENABLE_LIBXC=OFF + -DENABLE_LIBRI=OFF + -DENABLE_DFTD4=OFF + -DENABLE_RAPIDJSON=OFF + -DENABLE_MLALGO=OFF + -DENABLE_FLOAT_FFTW=OFF + -DENABLE_CNPY=OFF + -DCOMMIT_INFO=OFF + -DGIT_SUBMODULE=OFF + -DMKLROOT=OFF + - cmake --build build-rtd-docs --target abacus_pw_ser --parallel 2 + - ./build-rtd-docs/abacus_pw_ser --generate-parameters-yaml > docs/parameters.yaml # Build documentation in the "docs/" directory with Sphinx sphinx: diff --git a/docs/advanced/input_files/input-main.md b/docs/advanced/input_files/input-main.md index d1b5622bdd6..9ab47c87ed3 100644 --- a/docs/advanced/input_files/input-main.md +++ b/docs/advanced/input_files/input-main.md @@ -17,6 +17,7 @@ - [kpar](#kpar) - [bndpar](#bndpar) - [latname](#latname) + - [assume\_isolated](#assume_isolated) - [init\_wfc](#init_wfc) - [init\_chg](#init_chg) - [init\_vel](#init_vel) @@ -25,6 +26,8 @@ - [diago\_proc](#diago_proc) - [nbspline](#nbspline) - [kspacing](#kspacing) + - [koffset](#koffset) + - [kmesh\_type](#kmesh_type) - [min\_dist\_coef](#min_dist_coef) - [device](#device) - [precision](#precision) @@ -306,8 +309,6 @@ - [exx\_pca\_threshold](#exx_pca_threshold) - [exx\_c\_threshold](#exx_c_threshold) - [exx\_cs\_inv\_thr](#exx_cs_inv_thr) - - [shrink\_abfs\_pca\_thr](#shrink_abfs_pca_thr) - - [shrink\_lu\_inv\_thr](#shrink_lu_inv_thr) - [exx\_v\_threshold](#exx_v_threshold) - [exx\_dm\_threshold](#exx_dm_threshold) - [exx\_c\_grad\_threshold](#exx_c_grad_threshold) @@ -323,10 +324,6 @@ - [rpa\_ccp\_rmesh\_times](#rpa_ccp_rmesh_times) - [exx\_symmetry\_realspace](#exx_symmetry_realspace) - [out\_ri\_cv](#out_ri_cv) - - [out\_unshrinked\_v](#out_unshrinked_v) - - [exx\_coul\_moment](#exx_coul_moment) - - [exx\_rotate\_abfs](#exx_rotate_abfs) - - [exx\_multip\_moments\_threshold](#exx_multip_moments_threshold) - [Exact Exchange (PW)](#exact-exchange-pw) - [exxace](#exxace) - [exx\_gamma\_extrapolation](#exx_gamma_extrapolation) @@ -393,11 +390,15 @@ - [sc\_thr](#sc_thr) - [nsc](#nsc) - [nsc\_min](#nsc_min) - - [sc\_scf\_nmin](#sc_scf_nmin) - [alpha\_trial](#alpha_trial) - [sccut](#sccut) - [sc\_drop\_thr](#sc_drop_thr) - [sc\_scf\_thr](#sc_scf_thr) + - [sc\_direction\_only](#sc_direction_only) + - [sc\_lambda\_strategy](#sc_lambda_strategy) + - [sc\_scan\_lambda\_start](#sc_scan_lambda_start) + - [sc\_scan\_lambda\_end](#sc_scan_lambda_end) + - [sc\_scan\_steps](#sc_scan_steps) - [vdW correction](#vdw-correction) - [vdw\_method](#vdw_method) - [vdw\_d4\_xc](#vdw_d4_xc) @@ -665,6 +666,19 @@ - triclinic: triclinic - **Default**: none +### assume_isolated + +- **Type**: String +- **Description**: Used to perform a calculation assuming an isolated system in a 3D supercell. + + Available options are: + + - none: regular periodic calculation without isolated-system correction. + - makov-payne, m-p, mp: compute the Makov-Payne correction to the total energy and estimate a corrected vacuum level for eigenvalue alignment. This option is available only for cubic lattices (latname = sc, fcc, or bcc). + + Theory: G. Makov and M. C. Payne, Phys. Rev. B 51, 4014 (1995). +- **Default**: none + ### init_wfc - **Type**: String @@ -739,6 +753,18 @@ > Note: If gamma_only is set to be true, kspacing is invalid. - **Default**: 0.0 +### koffset + +- **Type**: Vector of Real (3 values) +- **Description**: Set offsets for automatic k-point mesh generated by kspacing, in each reciprocal direction. This parameter is only effective when kspacing > 0.0 and gamma_only is false. +- **Default**: 0.0 0.0 0.0 + +### kmesh_type + +- **Type**: String +- **Description**: Set mesh type used for automatic k-point mesh generated by kspacing. Available options are gamma and mp. This parameter is only effective when kspacing > 0.0 and gamma_only is false. +- **Default**: gamma + ### min_dist_coef - **Type**: Real @@ -770,7 +796,7 @@ ### gint_precision - **Type**: String -- **Availability**: *Used only for LCAO basis set on CPU.* +- **Availability**: *Used only for LCAO basis set.* - **Description**: Specifies the precision when performing grid integral in LCAO calculations. - single: single precision - double: double precision @@ -1115,7 +1141,7 @@ - cg: The conjugate-gradient (CG) method. - bpcg: The BPCG method, which is a block-parallel Conjugate Gradient (CG) method, typically exhibits higher acceleration in a GPU environment. - dav: The Davidson algorithm. - - dav_subspace: The Davidson algorithm without orthogonalization operation, this method is the most recommended for efficiency. pw_diag_ndim can be set to 2 for this method. + - dav_subspace: The Davidson algorithm without orthogonalization operation, this method is the most recommended for efficiency. `pw_diag_ndim` can be set to 2 for this method. For numerical atomic orbitals basis, @@ -1124,13 +1150,20 @@ - scalapack_gvx: Use Scalapack to diagonalize the Hamiltonian. - cusolver: Use CUSOLVER to diagonalize the Hamiltonian, at least one GPU is needed. - cusolvermp: Use CUSOLVER to diagonalize the Hamiltonian, supporting multi-GPU devices. Note that you should set the number of MPI processes equal to the number of GPUs. - - elpa: The ELPA solver supports both CPU and GPU. By setting the device to GPU, you can launch the ELPA solver with GPU acceleration (provided that you have installed a GPU-supported version of ELPA, which requires you to manually compile and install ELPA, and the ABACUS should be compiled with -DUSE_ELPA=ON and -DUSE_CUDA=ON). The ELPA solver also supports multi-GPU acceleration. + - elpa: The ELPA solver supports both CPU and GPU. By setting the `device` to GPU, you can launch the ELPA solver with GPU acceleration (provided that you have installed a GPU-supported version of ELPA, which requires you to manually compile and install ELPA, and the ABACUS should be compiled with -DUSE_ELPA=ON and -DUSE_CUDA=ON). The ELPA solver also supports multi-GPU acceleration. - If you set ks_solver=genelpa for basis_type=pw, the program will stop with an error message: + If you set ks_solver=`genelpa` for basis_type=`pw`, the program will stop with an error message: ``text genelpa can not be used with plane wave basis. `` Then the user has to correct the input file and restart the calculation. +- **Default**: + - PW basis: cg. + - LCAO basis: + - genelpa (if compiling option `USE_ELPA` has been set) + - lapack (if compiling option `ENABLE_MPI` has not been set) + - scalapack_gvx (if compiling option `USE_ELPA` has not been set and compiling option `ENABLE_MPI` has been set) + - cusolver (if compiling option `USE_CUDA` has been set) ### nbands @@ -1367,14 +1400,14 @@ ### scf_thr - **Type**: Real -- **Description**: It's the density threshold for electronic iteration. It represents the charge density error between two sequential densities from electronic iterations. This criterion is always enabled. If `scf_ene_thr` is set, its total-energy criterion is applied as an additional convergence check only after the charge-density criterion (`scf_thr`) has been satisfied, and only from the second SCF iteration onward (`iter > 1`). For local-orbital calculations, 1e-6 is usually accurate enough. +- **Description**: It's the density threshold for electronic iteration. It represents the charge density error between two sequential densities from electronic iterations. Usually for local orbitals, usually 1e-6 may be accurate enough. - **Default**: 1.0e-9 (plane-wave basis), or 1.0e-7 (localized atomic orbital basis). - **Unit**: Ry if scf_thr_type=1, dimensionless if scf_thr_type=2 ### scf_ene_thr - **Type**: Real -- **Description**: It's the energy threshold for electronic iteration. The compared quantity is the total-energy difference evaluated from the charge densities before and after the `Hpsi` operation in one SCF step. It is not the same as the screen-output `EDIFF`, which is the energy difference before `Hpsi` and after charge mixing (i.e., across both `Hpsi` and charge-mixing operations). +- **Description**: It's the energy threshold for electronic iteration. It represents the total energy error between two sequential densities from electronic iterations. - **Default**: -1.0. If the user does not set this parameter, it will not take effect. - **Unit**: eV @@ -1778,7 +1811,29 @@ - **Type**: Integer \[Integer\](optional) - **Description**: The first integer controls whether to output the charge density on real space grids: - - 1: Output the charge density (in Bohr^-3) on real space grids into the density files in the folder OUT.{suffix} too, which can be read in NSCF calculation. + - 1: Output the charge density (in Bohr^-3) on real space grids into the density files in the folder `OUT.${suffix}`. The files are named as: + - nspin = 1: `chg.cube`; + - nspin = 2: `chgs1.cube`, and `chgs2.cube`; + - nspin = 4: `chgs1.cube`, `chgs2.cube`, `chgs3.cube`, and `chgs4.cube`; + - When using the Meta-GGA functional, additional files containing the kinetic energy density are also output: + - nspin = 1: `tau.cube`; + - nspin = 2: `taus1.cube`, and `taus2.cube`; + - nspin = 4: `taus1.cube`, `taus2.cube`, `taus3.cube`, and `taus4.cube`; + - 2: On top of 1, also output the initial charge density files. The files are named as: + - out_freq_ion = 0: + - nspin = 1: `chg_ini.cube`; + - nspin = 2: `chgs1_ini.cube` and `chgs2_ini.cube`; + - nspin = 4: `chgs1_ini.cube`, `chgs2_ini.cube`, `chgs3_ini.cube`, and `chgs4_ini.cube`; + - output at every step (overwrite same file) + - out_freq_ion > 0: + - nspin = 1: `chgg{geom_step}_ini.cube` (e.g., `chgg1_ini.cube`); + - nspin = 2: `chgs1g{geom_step}_ini.cube` and `chgs2g{geom_step}_ini.cube`; + - nspin = 4: `chgs1g{geom_step}_ini.cube`, `chgs2g{geom_step}_ini.cube`, `chgs3g{geom_step}_ini.cube`, and `chgs4g{geom_step}_ini.cube`. + - output every out_freq_ion steps + Here, {geom_step} denotes the geometry step index, starting from 1 (geom_step = istep + 1). + - -1: Disable the charge density auto-back-up file `{suffix}-CHARGE-DENSITY.restart`, useful for large systems. + + The second integer controls the precision of the charge density output. If not given, `3` is used as default. For restarting from this file and other high-precision calculations, `10` is recommended. In molecular dynamics simulations, the output frequency is controlled by out_freq_ion. @@ -1794,9 +1849,17 @@ - nspin = 4: pots1.cube, pots2.cube, pots3.cube, and pots4.cube - 2: Output the electrostatic potential on real space grids into OUT.{suffix}/pot_es.cube. The Python script named tools/02_postprocessing/average_pot/aveElecStatPot.py can be used to calculate the average electrostatic potential along the z-axis and outputs it into ElecStaticPot_AVE. Please note that the total local potential refers to the local component of the self-consistent potential, excluding the non-local pseudopotential. The distinction between the local potential and the electrostatic potential is as follows: local potential = electrostatic potential + XC potential. - 3: Apart from 1, also output the total local potential of the initial charge density. The files are named as: - - nspin = 1: pots1_ini.cube; - - nspin = 2: pots1_ini.cube and pots2_ini.cube; - - nspin = 4: pots1_ini.cube, pots2_ini.cube, pots3_ini.cube, and pots4_ini.cube + - out_freq_ion = 0: + - nspin = 1: `pot_ini.cube`; + - nspin = 2: `pots1_ini.cube` and `pots2_ini.cube`; + - nspin = 4: `pots1_ini.cube`, `pots2_ini.cube`, `pots3_ini.cube`, and `pots4_ini.cube`; + - output at every step (overwrite same file) + - out_freq_ion > 0: + - nspin = 1: `potg{geom_step}_ini.cube` (e.g., `potg1_ini.cube`); + - nspin = 2: `pots1g{geom_step}_ini.cube` and `pots2g{geom_step}_ini.cube`; + - nspin = 4: `pots1g{geom_step}_ini.cube`, `pots2g{geom_step}_ini.cube`, `pots3g{geom_step}_ini.cube`, and `pots4g{geom_step}_ini.cube`. + - output every out_freq_ion steps + Here, {geom_step} denotes the geometry step index, starting from 1 (geom_step = istep + 1). The optional second integer controls the output precision. If not provided, the default precision is 8. @@ -1810,19 +1873,18 @@ - **Type**: Boolean \[Integer\](optional) - **Availability**: *Numerical atomic orbital basis* - **Description**: Whether to output the density matrix for each k-point into files in the folder OUT.${suffix}. For current develop versions, out_dmk writes *_nao.txt files and includes a g{istep} index in the file name: - - For gamma only case: - - nspin = 1 and 4: dmg1_nao.txt; - - nspin = 2: dms1g1_nao.txt and dms2g1_nao.txt for the two spin channels. - - For multi-k points case: - - nspin = 1 and 4: dmk1g1_nao.txt, dmk2g1_nao.txt, ...; - - nspin = 2: dmk1s1g1_nao.txt... and dmk1s2g1_nao.txt... for the two spin channels. - - Here, g{istep} denotes the geometry/step index in the output file name. - - > Note: Version difference (develop vs 3.10-LTS): - > - > - In develop, out_dmk supports both gamma-only and multi-k-point density-matrix output. - > - In 3.10-LTS, the corresponding keyword is out_dm, and the output files are SPIN1_DM and SPIN2_DM, etc. + - For gamma only case: + - nspin = 1 and 4: dmg1_nao.txt; + - nspin = 2: dms1g1_nao.txt and dms2g1_nao.txt for the two spin channels. + - For multi-k points case: + - nspin = 1 and 4: dmk1g1_nao.txt, dmk2g1_nao.txt, ...; + - nspin = 2: dmk1s1g1_nao.txt... and dmk1s2g1_nao.txt... for the two spin channels. + + Here, g{istep} denotes the geometry/step index in the output file name. + + > Note: Version difference (develop vs 3.10-LTS): + - In develop, out_dmk supports both gamma-only and multi-k-point density-matrix output. + - In 3.10-LTS, the corresponding keyword is out_dm, and the output files are SPIN1_DM and SPIN2_DM, etc. - **Default**: False ### out_dmr @@ -2057,7 +2119,7 @@ - **Type**: Boolean - **Availability**: *Numerical atomic orbital basis (not gamma-only algorithm)* -- **Description**: Whether to print Hamiltonian matrices H(R) in npz format. The output files are named output_HR0.npz, output_HR1.npz, and so on according to spin channel. This feature requires ABACUS to be built with CNPY. +- **Description**: Whether to print Hamiltonian matrices H(R) in npz format. This feature does not work for gamma-only calculations. - **Default**: False - **Unit**: Ry @@ -2065,14 +2127,15 @@ - **Type**: Boolean - **Availability**: *Numerical atomic orbital basis (not gamma-only algorithm)* -- **Description**: Whether to print Hamiltonian matrices H(R) and overlap matrix S(R) in npz format. The output files are named output_SR.npz, output_HR0.npz, output_HR1.npz, and so on according to spin channel. This feature requires ABACUS to be built with CNPY. +- **Description**: Whether to print Hamiltonian matrices H(R) and overlap matrix S(R) in npz format. This feature does not work for gamma-only calculations. - **Default**: False +- **Unit**: Ry ### out_dm_npz - **Type**: Boolean - **Availability**: *Numerical atomic orbital basis (not gamma-only algorithm)* -- **Description**: Whether to print density matrices DM(R) in npz format. The output files are named output_DM0.npz, output_DM1.npz, and so on according to spin channel. This feature requires ABACUS to be built with CNPY. +- **Description**: Whether to print density matrices DM(R) in npz format. This feature does not work for gamma-only calculations. - **Default**: False ### out_mul @@ -2154,12 +2217,14 @@ - **Availability**: *Only for Kohn-Sham DFT and Orbital Free DFT.* - **Description**: Whether to output the electron localization function (ELF) in the folder `OUT.${suffix}`. The files are named as - nspin = 1: - - elf.cube: ${\rm{ELF}} = \frac{1}{1+\chi^2}$, $\chi = \frac{\frac{1}{2}\sum_{i}{f_i |\nabla\psi_{i}|^2} - \frac{|\nabla\rho|^2}{8\rho}}{\frac{3}{10}(3\pi^2)^{2/3}\rho^{5/3}}$; + - elftot.cube: ${\rm{ELF}} = \frac{1}{1+\chi^2}$, $\chi = \frac{\frac{1}{2}\sum_{i}{f_i |\nabla\psi_{i}|^2} - \frac{|\nabla\rho|^2}{8\rho}}{\frac{3}{10}(3\pi^2)^{2/3}\rho^{5/3}}$; - nspin = 2: - - elf1.cube, elf2.cube: ${\rm{ELF}}_\sigma = \frac{1}{1+\chi_\sigma^2}$, $\chi_\sigma = \frac{\frac{1}{2}\sum_{i}{f_i |\nabla\psi_{i,\sigma}|^2} - \frac{|\nabla\rho_\sigma|^2}{8\rho_\sigma}}{\frac{3}{10}(6\pi^2)^{2/3}\rho_\sigma^{5/3}}$; - - elf.cube: ${\rm{ELF}} = \frac{1}{1+\chi^2}$, $\chi = \frac{\frac{1}{2}\sum_{i,\sigma}{f_i |\nabla\psi_{i,\sigma}|^2} - \sum_{\sigma}{\frac{|\nabla\rho_\sigma|^2}{8\rho_\sigma}}}{\sum_{\sigma}{\frac{3}{10}(6\pi^2)^{2/3}\rho_\sigma^{5/3}}}$; + - elfs1.cube, elfs2.cube: ${\rm{ELF}}_\sigma = \frac{1}{1+\chi_\sigma^2}$, $\chi_\sigma = \frac{\frac{1}{2}\sum_{i}{f_i |\nabla\psi_{i,\sigma}|^2} - \frac{|\nabla\rho_\sigma|^2}{8\rho_\sigma}}{\frac{3}{10}(6\pi^2)^{2/3}\rho_\sigma^{5/3}}$; + - elftot.cube: ${\rm{ELF}} = \frac{1}{1+\chi^2}$, $\chi = \frac{\frac{1}{2}\sum_{i,\sigma}{f_i |\nabla\psi_{i,\sigma}|^2} - \sum_{\sigma}{\frac{|\nabla\rho_\sigma|^2}{8\rho_\sigma}}}{\sum_{\sigma}{\frac{3}{10}(6\pi^2)^{2/3}\rho_\sigma^{5/3}}}$; - nspin = 4 (noncollinear): - - elf.cube: ELF for total charge density, ${\rm{ELF}} = \frac{1}{1+\chi^2}$, $\chi = \frac{\frac{1}{2}\sum_{i}{f_i |\nabla\psi_{i}|^2} - \frac{|\nabla\rho|^2}{8\rho}}{\frac{3}{10}(3\pi^2)^{2/3}\rho^{5/3}}$ + - elftot.cube: ELF for total charge density, ${\rm{ELF}} = \frac{1}{1+\chi^2}$, $\chi = \frac{\frac{1}{2}\sum_{i}{f_i |\nabla\psi_{i}|^2} - \frac{|\nabla\rho|^2}{8\rho}}{\frac{3}{10}(3\pi^2)^{2/3}\rho^{5/3}}$ + + When `out_freq_ion > 0`, a geometry step suffix `g{#}` is appended to the file names (e.g., `elftotg1.cube`, `elfs1g1.cube`). The second integer controls the precision of the kinetic energy density output, if not given, will use 3 as default. For purpose restarting from this file and other high-precision involved calculation, recommend to use 10. @@ -2429,9 +2494,9 @@ - tf: Thomas-Fermi (TF) functional - vw: von Weizsacker (vW) functional - tf+: TF + vW functional - - wt: Wang-Teter (WT) functional (supports GPU acceleration when device=gpu) - - ext-wt: Extended Wang-Teter (ext-WT) functional - - xwm: Xu-Wang-Ma (XWM) functional + - wt: Wang-Teter (WT) functional + - ext-wt: Extended Wang-Teter functional + - xwm: XWM functional - lkt: Luo-Karasiev-Trickey (LKT) functional - ml: Machine learning KEDF - mpn: MPN KEDF (automatically sets ml parameters) @@ -2505,7 +2570,7 @@ - **Type**: Real - **Availability**: *OFDFT with of_kinetic=ext-wt* - **Description**: Parameter kappa for EXT-WT KEDF. -- **Default**: $\dfrac{1}{2(4/3)^{1/3}-1} \approx 0.832$ +- **Default**: 1.0 / (2.0 * std::pow(4./3., 1./3.) - 1.0) ### of_wt_rho0 @@ -3005,18 +3070,6 @@ - **Description**: By default, the Coulomb matrix inversion required for obtaining LRI coefficients is performed using LU decomposition. However, this approach may suffer from numerical instabilities when a large set of auxiliary basis functions (ABFs) is employed. When exx_cs_inv_thr > 0, the inversion is instead carried out via matrix diagonalization. Eigenvalues smaller than exx_cs_inv_thr are discarded to improve numerical stability. A relatively safe and commonly recommended value is 1e-5. - **Default**: -1 -### shrink_abfs_pca_thr - -- **Type**: Real -- **Description**: Threshold to shrink the auxiliary basis for GW/RPA calculations. -- **Default**: -1 - -### shrink_lu_inv_thr - -- **Type**: Real -- **Description**: Threshold for obtaining the inverse of the overlap matrix by LU decomposition in the auxiliary-basis representation. -- **Default**: 1e-6 - ### exx_v_threshold - **Type**: Real @@ -3114,30 +3167,6 @@ - **Description**: Whether to output the coefficient tensor C(R) and ABFs-representation Coulomb matrix V(R) for each atom pair and cell in real space. - **Default**: false -### out_unshrinked_v - -- **Type**: Boolean -- **Description**: Whether to output the large Vq matrix in the unshrinked auxiliary basis. -- **Default**: false - -### exx_coul_moment - -- **Type**: Boolean -- **Description**: Whether to use the moment method for Coulomb calculation. -- **Default**: false - -### exx_rotate_abfs - -- **Type**: Boolean -- **Description**: Whether to rotate the auxiliary basis for Coulomb calculation. -- **Default**: false - -### exx_multip_moments_threshold - -- **Type**: Real -- **Description**: Threshold to screen multipole moments in Coulomb calculation. -- **Default**: 1e-10 - [back to top](#full-list-of-input-keywords) ## Exact Exchange (PW) @@ -3220,7 +3249,6 @@ - berendsen: Berendsen thermostat, see md_nraise in detail. - rescaling: velocity Rescaling method 1, see md_tolerance in detail. - rescale_v: velocity Rescaling method 2, see md_nraise in detail. - - csvr: Canonical Sampling through Velocity Rescaling, see md_csvr_tau in detail. - **Default**: nhc ### md_tfirst @@ -3475,7 +3503,8 @@ ### md_csvr_tau - **Type**: Real -- **Description**: The characteristic time scale for the CSVR (Canonical Sampling through Velocity Rescaling) thermostat. Larger values give weaker coupling (longer relaxation time), smaller values give stronger coupling (shorter relaxation time). Recommended value: 100 * md_dt. +- **Availability**: *md_thermostat = csvr* +- **Description**: The characteristic time scale for the CSVR (Canonical Sampling through Velocity Rescaling) thermostat. Larger values give weaker coupling, smaller values give stronger coupling. Recommended value: 100 * md_dt. - **Default**: 100.0 - **Unit**: fs @@ -3496,9 +3525,13 @@ ### cal_syns -- **Type**: Boolean +- **Type**: Boolean [Integer](optional) - **Description**: Whether to calculate and output asynchronous overlap matrix for Hefei-NAMD interface. When enabled, calculates <phi(t-1)|phi(t)> by computing overlap between basis functions at atomic positions from previous time step and current time step. The overlap is calculated by shifting atom positions backward by velocity x md_dt. Output file: OUT.*/syns_nao.csr in CSR format. + - 0 or false: disable + - 1 or true: enable with default precision (8 digits) + - 1 5: enable with custom precision (5 digits) + > Note: Only works with LCAO basis and molecular dynamics calculations. Requires atomic velocities. Output starts from the second MD step (istep > 0). - **Default**: False @@ -3628,13 +3661,6 @@ - **Description**: Minimum number of spin-constrained iteration - **Default**: 2 -### sc_scf_nmin - -- **Type**: Integer -- **Availability**: *sc_mag_switch is true* -- **Description**: Minimum number of outer scf loop before initializing lambda loop -- **Default**: 2 - ### alpha_trial - **Type**: Real @@ -3665,6 +3691,50 @@ - **Description**: Density error threshold for inner loop of spin-constrained SCF - **Default**: 1.0e-4 +### sc_direction_only + +- **Type**: Boolean +- **Availability**: *sc_mag_switch is true* +- **Description**: When true, only the direction of the magnetic moment is constrained to the target direction, while the magnitude is allowed to vary freely. This is useful for studying magnetic anisotropy or when the magnitude of the moment is determined by the electronic structure rather than an external constraint. + + When false (default), both the direction and magnitude of the magnetic moment are constrained to the target values. +- **Default**: False + +### sc_lambda_strategy + +- **Type**: String +- **Availability**: *sc_mag_switch is true* +- **Description**: Lambda update strategy for spin-constrained DFT: + - bfgs: BFGS quasi-Newton method + - linear_response: linear response (Scheme B) + - augmented_lagrangian: augmented Lagrangian (Scheme C) + - hybrid_delayed: hybrid delayed update (Scheme D) + - linear_scan: linear sweep of lambda for testing magnetic moment response +- **Default**: bfgs + +### sc_scan_lambda_start + +- **Type**: Float +- **Availability**: *sc_lambda_strategy is linear_scan* +- **Description**: Starting lambda value for linear_scan strategy. Only used when sc_lambda_strategy=linear_scan. +- **Default**: 0.0 +- **Unit**: eV/uB + +### sc_scan_lambda_end + +- **Type**: Float +- **Availability**: *sc_lambda_strategy is linear_scan* +- **Description**: Ending lambda value for linear_scan strategy. Only used when sc_lambda_strategy=linear_scan. +- **Default**: 1.0 +- **Unit**: eV/uB + +### sc_scan_steps + +- **Type**: Integer +- **Availability**: *sc_lambda_strategy is linear_scan* +- **Description**: Number of lambda values to scan. Only used when sc_lambda_strategy=linear_scan. +- **Default**: 20 + [back to top](#full-list-of-input-keywords) ## vdW correction @@ -3680,22 +3750,25 @@ - none: no vdW correction > Note: ABACUS supports automatic setting of DFT-D3 parameters for common functionals. To benefit from this feature, please specify the parameter dft_functional explicitly, otherwise the autoset procedure will crash. If not satisfied with the built-in parameters, any manual setting on vdw_s6, vdw_s8, vdw_a1 and vdw_a2 will overwrite the automatic values. - - > Note: DFT-D4 support requires ABACUS to be configured with ENABLE_DFTD4=ON and a CMake-installed dftd4 library exporting dftd4-config.cmake. DFT-D4 damping parameters are loaded from the external library. - **Default**: none ### vdw_d4_xc - **Type**: String - **Availability**: *vdw_method is set to d4* -- **Description**: Functional name passed to the DFT-D4 library to load its internal damping parameters. If set to default, ABACUS infers the functional name from dft_functional or pseudopotential metadata. +- **Description**: Functional name used to load DFT-D4 damping parameters from the DFT-D4 library. + If set to default, ABACUS infers the functional name from dft_functional or pseudopotential metadata. - **Default**: default ### vdw_d4_model - **Type**: String - **Availability**: *vdw_method is set to d4* -- **Description**: DFT-D4 dispersion model used by the external DFT-D4 library. Available options are d4 for the standard D4 model and d4s for the smooth D4S model. +- **Description**: DFT-D4 dispersion model used by the external DFT-D4 library. + Available options are: + + - d4: standard D4 model + - d4s: smooth D4S model - **Default**: d4 ### vdw_s6 @@ -3790,7 +3863,7 @@ - **Type**: String - **Availability**: *vdw_cutoff_type is set to radius* -- **Description**: Defines the cutoff radius when vdw_cutoff_type is set to radius. The default values depend on the chosen vdw_method. For DFT-D4, this controls the two-body dispersion cutoff, while the three-body cutoff is internally limited to the DFT-D4 default value of 40 Bohr. +- **Description**: Defines the radius of the cutoff sphere when vdw_cutoff_type is set to radius. The default values depend on the chosen vdw_method. - **Unit**: defined by vdw_radius_unit (default Bohr) ### vdw_radius_unit @@ -3813,7 +3886,7 @@ - **Type**: Real - **Availability**: *vdw_method is set to d3_0, d3_bj, or d4* -- **Description**: The cutoff radius when calculating coordination numbers. The default is 40 Bohr for DFT-D3 and 30 Bohr for DFT-D4. +- **Description**: The cutoff radius when calculating coordination numbers. - **Default**: 40 - **Unit**: defined by vdw_cn_thr_unit (default: Bohr) diff --git a/docs/generate_input_main.py b/docs/generate_input_main.py index 16a9e398bbe..4e138034d7f 100644 --- a/docs/generate_input_main.py +++ b/docs/generate_input_main.py @@ -173,8 +173,16 @@ def generate_parameter_markdown(param: Dict[str, str]) -> str: # Default if param.get('default_value', '') != '': - default_text = escape_md_text(str(param['default_value'])) - lines.append(f"- **Default**: {default_text}") + default_text = escape_md_text(str(param['default_value'])).strip('\n') + if '\n' in default_text: + lines.append("- **Default**:") + for line in default_text.split('\n'): + if line.strip(): + lines.append(f" {line}" if not line.startswith(' ') else line) + else: + lines.append("") + else: + lines.append(f"- **Default**: {default_text}") # Unit if param.get('unit', '') != '': diff --git a/docs/parameters.yaml b/docs/parameters.yaml index 02820d175d4..66f9c614321 100644 --- a/docs/parameters.yaml +++ b/docs/parameters.yaml @@ -137,6 +137,20 @@ parameters: default_value: none unit: "" availability: "" + - name: assume_isolated + category: System variables + type: String + description: | + Used to perform a calculation assuming an isolated system in a 3D supercell. + + Available options are: + * none: regular periodic calculation without isolated-system correction. + * makov-payne, m-p, mp: compute the Makov-Payne correction to the total energy and estimate a corrected vacuum level for eigenvalue alignment. This option is available only for cubic lattices (latname = sc, fcc, or bcc). + + Theory: G. Makov and M. C. Payne, Phys. Rev. B 51, 4014 (1995). + default_value: none + unit: "" + availability: "" - name: init_wfc category: System variables type: String @@ -823,7 +837,7 @@ parameters: category: Electronic structure type: Real description: | - It's the density threshold for electronic iteration. It represents the charge density error between two sequential densities from electronic iterations. This criterion is always enabled. If `scf_ene_thr` is set, the total-energy criterion (`scf_ene_thr`) is evaluated conditionally after the charge-density criterion (`scf_thr`) is satisfied, and not on the first iteration. For local-orbital calculations, 1e-6 is usually accurate enough. + It's the density threshold for electronic iteration. It represents the charge density error between two sequential densities from electronic iterations. Usually for local orbitals, usually 1e-6 may be accurate enough. default_value: "1.0e-9 (plane-wave basis), or 1.0e-7 (localized atomic orbital basis)." unit: "Ry if scf_thr_type=1, dimensionless if scf_thr_type=2" availability: "" @@ -831,7 +845,7 @@ parameters: category: Electronic structure type: Real description: | - It's the energy threshold for electronic iteration. The compared quantity is the total-energy difference evaluated from the charge densities before and after the `Hpsi` operation in one SCF step. It is not the same as the screen-output `EDIFF`, which is the energy difference before `Hpsi` and after charge mixing (i.e., across both `Hpsi` and charge-mixing operations). + It's the energy threshold for electronic iteration. It represents the total energy error between two sequential densities from electronic iterations. default_value: "-1.0. If the user does not set this parameter, it will not take effect." unit: eV availability: "" @@ -1379,7 +1393,6 @@ parameters: * berendsen: Berendsen thermostat, see md_nraise in detail. * rescaling: velocity Rescaling method 1, see md_tolerance in detail. * rescale_v: velocity Rescaling method 2, see md_nraise in detail. - * csvr: Canonical Sampling through Velocity Rescaling, see md_csvr_tau in detail. default_value: nhc unit: "" availability: "" @@ -2857,7 +2870,18 @@ parameters: - nspin = 1: `tau.cube`; - nspin = 2: `taus1.cube`, and `taus2.cube`; - nspin = 4: `taus1.cube`, `taus2.cube`, `taus3.cube`, and `taus4.cube`; - - 2: On top of 1, also output the initial charge density files with a suffix name as '_ini', such as `taus1_ini.cube`, etc. + - 2: On top of 1, also output the initial charge density files. The files are named as: + - out_freq_ion = 0: + - nspin = 1: `chg_ini.cube`; + - nspin = 2: `chgs1_ini.cube` and `chgs2_ini.cube`; + - nspin = 4: `chgs1_ini.cube`, `chgs2_ini.cube`, `chgs3_ini.cube`, and `chgs4_ini.cube`; + - output at every step (overwrite same file) + - out_freq_ion > 0: + - nspin = 1: `chgg{geom_step}_ini.cube` (e.g., `chgg1_ini.cube`); + - nspin = 2: `chgs1g{geom_step}_ini.cube` and `chgs2g{geom_step}_ini.cube`; + - nspin = 4: `chgs1g{geom_step}_ini.cube`, `chgs2g{geom_step}_ini.cube`, `chgs3g{geom_step}_ini.cube`, and `chgs4g{geom_step}_ini.cube`. + - output every out_freq_ion steps + Here, {geom_step} denotes the geometry step index, starting from 1 (geom_step = istep + 1). - -1: Disable the charge density auto-back-up file `{suffix}-CHARGE-DENSITY.restart`, useful for large systems. The second integer controls the precision of the charge density output. If not given, `3` is used as default. For restarting from this file and other high-precision calculations, `10` is recommended. @@ -2878,9 +2902,17 @@ parameters: * nspin = 4: pots1.cube, pots2.cube, pots3.cube, and pots4.cube * 2: Output the electrostatic potential on real space grids into OUT.{suffix}/pot_es.cube. The Python script named tools/02_postprocessing/average_pot/aveElecStatPot.py can be used to calculate the average electrostatic potential along the z-axis and outputs it into ElecStaticPot_AVE. Please note that the total local potential refers to the local component of the self-consistent potential, excluding the non-local pseudopotential. The distinction between the local potential and the electrostatic potential is as follows: local potential = electrostatic potential + XC potential. * 3: Apart from 1, also output the total local potential of the initial charge density. The files are named as: - * nspin = 1: pots1_ini.cube; - * nspin = 2: pots1_ini.cube and pots2_ini.cube; - * nspin = 4: pots1_ini.cube, pots2_ini.cube, pots3_ini.cube, and pots4_ini.cube + * out_freq_ion = 0: + * nspin = 1: `pot_ini.cube`; + * nspin = 2: `pots1_ini.cube` and `pots2_ini.cube`; + * nspin = 4: `pots1_ini.cube`, `pots2_ini.cube`, `pots3_ini.cube`, and `pots4_ini.cube`; + * output at every step (overwrite same file) + * out_freq_ion > 0: + * nspin = 1: `potg{geom_step}_ini.cube` (e.g., `potg1_ini.cube`); + * nspin = 2: `pots1g{geom_step}_ini.cube` and `pots2g{geom_step}_ini.cube`; + * nspin = 4: `pots1g{geom_step}_ini.cube`, `pots2g{geom_step}_ini.cube`, `pots3g{geom_step}_ini.cube`, and `pots4g{geom_step}_ini.cube`. + * output every out_freq_ion steps + Here, {geom_step} denotes the geometry step index, starting from 1 (geom_step = istep + 1). The optional second integer controls the output precision. If not provided, the default precision is 8. @@ -2895,17 +2927,18 @@ parameters: type: "Boolean \\[Integer\\](optional)" description: | Whether to output the density matrix for each k-point into files in the folder OUT.${suffix}. For current develop versions, out_dmk writes *_nao.txt files and includes a g{istep} index in the file name: - * For gamma only case: - * nspin = 1 and 4: dmg1_nao.txt; - * nspin = 2: dms1g1_nao.txt and dms2g1_nao.txt for the two spin channels. - * For multi-k points case: - * nspin = 1 and 4: dmk1g1_nao.txt, dmk2g1_nao.txt, ...; - * nspin = 2: dmk1s1g1_nao.txt... and dmk1s2g1_nao.txt... for the two spin channels. - Here, g{istep} denotes the geometry/step index in the output file name. + * For gamma only case: + * nspin = 1 and 4: dmg1_nao.txt; + * nspin = 2: dms1g1_nao.txt and dms2g1_nao.txt for the two spin channels. + * For multi-k points case: + * nspin = 1 and 4: dmk1g1_nao.txt, dmk2g1_nao.txt, ...; + * nspin = 2: dmk1s1g1_nao.txt... and dmk1s2g1_nao.txt... for the two spin channels. + + Here, g{istep} denotes the geometry/step index in the output file name. - [NOTE] Version difference (develop vs 3.10-LTS): - * In develop, out_dmk supports both gamma-only and multi-k-point density-matrix output. - * In 3.10-LTS, the corresponding keyword is out_dm, and the output files are SPIN1_DM and SPIN2_DM, etc. + [NOTE] Version difference (develop vs 3.10-LTS): + * In develop, out_dmk supports both gamma-only and multi-k-point density-matrix output. + * In 3.10-LTS, the corresponding keyword is out_dm, and the output files are SPIN1_DM and SPIN2_DM, etc. default_value: "False" unit: "" availability: Numerical atomic orbital basis @@ -3160,7 +3193,7 @@ parameters: category: Output information type: Boolean description: | - Whether to print Hamiltonian matrices H(R) in npz format. The output files are named output_HR0.npz, output_HR1.npz, and so on according to spin channel. This feature requires ABACUS to be built with CNPY. + Whether to print Hamiltonian matrices H(R) in npz format. This feature does not work for gamma-only calculations. default_value: "False" unit: Ry availability: Numerical atomic orbital basis (not gamma-only algorithm) @@ -3168,15 +3201,15 @@ parameters: category: Output information type: Boolean description: | - Whether to print Hamiltonian matrices H(R) and overlap matrix S(R) in npz format. The output files are named output_SR.npz, output_HR0.npz, output_HR1.npz, and so on according to spin channel. This feature requires ABACUS to be built with CNPY. + Whether to print Hamiltonian matrices H(R) and overlap matrix S(R) in npz format. This feature does not work for gamma-only calculations. default_value: "False" - unit: "" + unit: Ry availability: Numerical atomic orbital basis (not gamma-only algorithm) - name: out_dm_npz category: Output information type: Boolean description: | - Whether to print density matrices DM(R) in npz format. The output files are named output_DM0.npz, output_DM1.npz, and so on according to spin channel. This feature requires ABACUS to be built with CNPY. + Whether to print density matrices DM(R) in npz format. This feature does not work for gamma-only calculations. default_value: "False" unit: "" availability: Numerical atomic orbital basis (not gamma-only algorithm) @@ -3271,12 +3304,14 @@ parameters: description: | Whether to output the electron localization function (ELF) in the folder `OUT.${suffix}`. The files are named as * nspin = 1: - * elf.cube: ${\rm{ELF}} = \frac{1}{1+\chi^2}$, $\chi = \frac{\frac{1}{2}\sum_{i}{f_i |\nabla\psi_{i}|^2} - \frac{|\nabla\rho|^2}{8\rho}}{\frac{3}{10}(3\pi^2)^{2/3}\rho^{5/3}}$; + * elftot.cube: ${\rm{ELF}} = \frac{1}{1+\chi^2}$, $\chi = \frac{\frac{1}{2}\sum_{i}{f_i |\nabla\psi_{i}|^2} - \frac{|\nabla\rho|^2}{8\rho}}{\frac{3}{10}(3\pi^2)^{2/3}\rho^{5/3}}$; * nspin = 2: - * elf1.cube, elf2.cube: ${\rm{ELF}}_\sigma = \frac{1}{1+\chi_\sigma^2}$, $\chi_\sigma = \frac{\frac{1}{2}\sum_{i}{f_i |\nabla\psi_{i,\sigma}|^2} - \frac{|\nabla\rho_\sigma|^2}{8\rho_\sigma}}{\frac{3}{10}(6\pi^2)^{2/3}\rho_\sigma^{5/3}}$; - * elf.cube: ${\rm{ELF}} = \frac{1}{1+\chi^2}$, $\chi = \frac{\frac{1}{2}\sum_{i,\sigma}{f_i |\nabla\psi_{i,\sigma}|^2} - \sum_{\sigma}{\frac{|\nabla\rho_\sigma|^2}{8\rho_\sigma}}}{\sum_{\sigma}{\frac{3}{10}(6\pi^2)^{2/3}\rho_\sigma^{5/3}}}$; + * elfs1.cube, elfs2.cube: ${\rm{ELF}}_\sigma = \frac{1}{1+\chi_\sigma^2}$, $\chi_\sigma = \frac{\frac{1}{2}\sum_{i}{f_i |\nabla\psi_{i,\sigma}|^2} - \frac{|\nabla\rho_\sigma|^2}{8\rho_\sigma}}{\frac{3}{10}(6\pi^2)^{2/3}\rho_\sigma^{5/3}}$; + * elftot.cube: ${\rm{ELF}} = \frac{1}{1+\chi^2}$, $\chi = \frac{\frac{1}{2}\sum_{i,\sigma}{f_i |\nabla\psi_{i,\sigma}|^2} - \sum_{\sigma}{\frac{|\nabla\rho_\sigma|^2}{8\rho_\sigma}}}{\sum_{\sigma}{\frac{3}{10}(6\pi^2)^{2/3}\rho_\sigma^{5/3}}}$; * nspin = 4 (noncollinear): - * elf.cube: ELF for total charge density, ${\rm{ELF}} = \frac{1}{1+\chi^2}$, $\chi = \frac{\frac{1}{2}\sum_{i}{f_i |\nabla\psi_{i}|^2} - \frac{|\nabla\rho|^2}{8\rho}}{\frac{3}{10}(3\pi^2)^{2/3}\rho^{5/3}}$ + * elftot.cube: ELF for total charge density, ${\rm{ELF}} = \frac{1}{1+\chi^2}$, $\chi = \frac{\frac{1}{2}\sum_{i}{f_i |\nabla\psi_{i}|^2} - \frac{|\nabla\rho|^2}{8\rho}}{\frac{3}{10}(3\pi^2)^{2/3}\rho^{5/3}}$ + + When `out_freq_ion > 0`, a geometry step suffix `g{#}` is appended to the file names (e.g., `elftotg1.cube`, `elfs1g1.cube`). The second integer controls the precision of the kinetic energy density output, if not given, will use 3 as default. For purpose restarting from this file and other high-precision involved calculation, recommend to use 10. @@ -3775,8 +3810,6 @@ parameters: * none: no vdW correction [NOTE] ABACUS supports automatic setting of DFT-D3 parameters for common functionals. To benefit from this feature, please specify the parameter dft_functional explicitly, otherwise the autoset procedure will crash. If not satisfied with the built-in parameters, any manual setting on vdw_s6, vdw_s8, vdw_a1 and vdw_a2 will overwrite the automatic values. - - [NOTE] DFT-D4 support requires ABACUS to be configured with ENABLE_DFTD4=ON and a CMake-installed dftd4 library exporting `dftd4-config.cmake`. DFT-D4 damping parameters are loaded from the external library. default_value: none unit: "" availability: "" @@ -3784,7 +3817,8 @@ parameters: category: vdW correction type: String description: | - Functional name passed to the DFT-D4 library to load its internal damping parameters. If set to default, ABACUS infers the functional name from dft_functional or pseudopotential metadata. + Functional name used to load DFT-D4 damping parameters from the DFT-D4 library. + If set to default, ABACUS infers the functional name from dft_functional or pseudopotential metadata. default_value: default unit: "" availability: vdw_method is set to d4 @@ -3792,8 +3826,11 @@ parameters: category: vdW correction type: String description: | - DFT-D4 dispersion model used by the external DFT-D4 library. Available options are d4 for the standard D4 model and d4s for the smooth D4S model. - default_value: d4 + DFT-D4 dispersion model used by the external DFT-D4 library. + Available options are: + * d4: standard D4 model + * d4s: smooth D4S model + default_value: "d4" unit: "" availability: vdw_method is set to d4 - name: vdw_s6 @@ -3904,7 +3941,7 @@ parameters: category: vdW correction type: String description: | - Defines the cutoff radius when vdw_cutoff_type is set to radius. The default values depend on the chosen vdw_method. For DFT-D4, this controls the two-body dispersion cutoff, while the three-body cutoff is internally limited to the DFT-D4 default value of 40 Bohr. + Defines the radius of the cutoff sphere when vdw_cutoff_type is set to radius. The default values depend on the chosen vdw_method. default_value: "" unit: defined by vdw_radius_unit (default Bohr) availability: vdw_cutoff_type is set to radius @@ -3930,10 +3967,10 @@ parameters: category: vdW correction type: Real description: | - The cutoff radius when calculating coordination numbers. The default is 40 Bohr for DFT-D3 and 30 Bohr for DFT-D4. + The cutoff radius when calculating coordination numbers. default_value: "40" unit: "defined by vdw_cn_thr_unit (default: Bohr)" - availability: vdw_method is set to d3_0, d3_bj, or d4 + availability: "vdw_method is set to d3_0, d3_bj, or d4" - name: vdw_cn_thr_unit category: vdW correction type: String @@ -4278,14 +4315,6 @@ parameters: default_value: "2" unit: "" availability: sc_mag_switch is true - - name: sc_scf_nmin - category: Spin-Constrained DFT - type: Integer - description: | - Minimum number of outer scf loop before initializing lambda loop - default_value: "2" - unit: "" - availability: sc_mag_switch is true - name: alpha_trial category: Spin-Constrained DFT type: Real @@ -4318,6 +4347,53 @@ parameters: default_value: "1.0e-4" unit: "" availability: sc_mag_switch is true + - name: sc_direction_only + category: Spin-Constrained DFT + type: Boolean + description: | + When true, only the direction of the magnetic moment is constrained to the target direction, while the magnitude is allowed to vary freely. This is useful for studying magnetic anisotropy or when the magnitude of the moment is determined by the electronic structure rather than an external constraint. + + When false (default), both the direction and magnitude of the magnetic moment are constrained to the target values. + default_value: "False" + unit: "" + availability: sc_mag_switch is true + - name: sc_lambda_strategy + category: Spin-Constrained DFT + type: String + description: | + Lambda update strategy for spin-constrained DFT: + * bfgs: BFGS quasi-Newton method + * linear_response: linear response (Scheme B) + * augmented_lagrangian: augmented Lagrangian (Scheme C) + * hybrid_delayed: hybrid delayed update (Scheme D) + * linear_scan: linear sweep of lambda for testing magnetic moment response + default_value: bfgs + unit: "" + availability: sc_mag_switch is true + - name: sc_scan_lambda_start + category: Spin-Constrained DFT + type: Float + description: | + Starting lambda value for linear_scan strategy. Only used when sc_lambda_strategy=linear_scan. + default_value: "0.0" + unit: eV/uB + availability: sc_lambda_strategy is linear_scan + - name: sc_scan_lambda_end + category: Spin-Constrained DFT + type: Float + description: | + Ending lambda value for linear_scan strategy. Only used when sc_lambda_strategy=linear_scan. + default_value: "1.0" + unit: eV/uB + availability: sc_lambda_strategy is linear_scan + - name: sc_scan_steps + category: Spin-Constrained DFT + type: Integer + description: | + Number of lambda values to scan. Only used when sc_lambda_strategy=linear_scan. + default_value: "20" + unit: "" + availability: sc_lambda_strategy is linear_scan - name: qo_switch category: Quasiatomic Orbital (QO) analysis type: Boolean From 4c3d43bf6d8f77bf6109a80e75ac63a0611c5563 Mon Sep 17 00:00:00 2001 From: Bonan Zhu Date: Sun, 12 Jul 2026 14:23:27 +0800 Subject: [PATCH 2/9] docs: preserve generated INPUT metadata --- .readthedocs.yaml | 2 +- docs/advanced/input_files/input-main.md | 49 ++++++++++++++++- docs/parameters.yaml | 55 ++++++++++++++++++- .../read_input_item_exx_dftu.cpp | 36 ++++++++++++ .../module_parameter/read_input_item_md.cpp | 3 +- .../read_input_item_output.cpp | 6 +- 6 files changed, 140 insertions(+), 11 deletions(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 8c8d52898d1..6253a4466ef 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -42,7 +42,7 @@ build: -DGIT_SUBMODULE=OFF -DMKLROOT=OFF - cmake --build build-rtd-docs --target abacus_pw_ser --parallel 2 - - ./build-rtd-docs/abacus_pw_ser --generate-parameters-yaml > docs/parameters.yaml + - ./build-rtd-docs/source/abacus_pw_ser --generate-parameters-yaml > docs/parameters.yaml # Build documentation in the "docs/" directory with Sphinx sphinx: diff --git a/docs/advanced/input_files/input-main.md b/docs/advanced/input_files/input-main.md index a1c0496f93e..1db92d43d7d 100644 --- a/docs/advanced/input_files/input-main.md +++ b/docs/advanced/input_files/input-main.md @@ -336,6 +336,12 @@ - [rpa\_ccp\_rmesh\_times](#rpa_ccp_rmesh_times) - [exx\_symmetry\_realspace](#exx_symmetry_realspace) - [out\_ri\_cv](#out_ri_cv) + - [out\_unshrinked\_v](#out_unshrinked_v) + - [exx\_coul\_moment](#exx_coul_moment) + - [exx\_rotate\_abfs](#exx_rotate_abfs) + - [exx\_multip\_moments\_threshold](#exx_multip_moments_threshold) + - [shrink\_abfs\_pca\_thr](#shrink_abfs_pca_thr) + - [shrink\_lu\_inv\_thr](#shrink_lu_inv_thr) - [Exact Exchange (PW)](#exact-exchange-pw) - [exxace](#exxace) - [exx\_gamma\_extrapolation](#exx_gamma_extrapolation) @@ -2247,7 +2253,7 @@ - **Type**: Boolean - **Availability**: *Numerical atomic orbital basis (not gamma-only algorithm)* -- **Description**: Whether to print Hamiltonian matrices H(R) in npz format. This feature does not work for gamma-only calculations. +- **Description**: Whether to print Hamiltonian matrices H(R) in npz format. The output files are named output_HR0.npz, output_HR1.npz, and so on according to spin channel. This feature requires ABACUS to be built with CNPY. - **Default**: False - **Unit**: Ry @@ -2255,7 +2261,7 @@ - **Type**: Boolean - **Availability**: *Numerical atomic orbital basis (not gamma-only algorithm)* -- **Description**: Whether to print Hamiltonian matrices H(R) and overlap matrix S(R) in npz format. This feature does not work for gamma-only calculations. +- **Description**: Whether to print Hamiltonian matrices H(R) and overlap matrix S(R) in npz format. The output files are named output_SR.npz, output_HR0.npz, output_HR1.npz, and so on according to spin channel. This feature requires ABACUS to be built with CNPY. - **Default**: False - **Unit**: Ry @@ -2263,7 +2269,7 @@ - **Type**: Boolean - **Availability**: *Numerical atomic orbital basis (not gamma-only algorithm)* -- **Description**: Whether to print density matrices DM(R) in npz format. This feature does not work for gamma-only calculations. +- **Description**: Whether to print density matrices DM(R) in npz format. The output files are named output_DM0.npz, output_DM1.npz, and so on according to spin channel. This feature requires ABACUS to be built with CNPY. - **Default**: False ### out_mul @@ -3295,6 +3301,42 @@ - **Description**: Whether to output the coefficient tensor C(R) and ABFs-representation Coulomb matrix V(R) for each atom pair and cell in real space. - **Default**: false +### out_unshrinked_v + +- **Type**: Boolean +- **Description**: Whether to output the large Vq matrix in the unshrinked auxiliary basis. +- **Default**: false + +### exx_coul_moment + +- **Type**: Boolean +- **Description**: Whether to use the moment method for Coulomb calculation. +- **Default**: false + +### exx_rotate_abfs + +- **Type**: Boolean +- **Description**: Whether to rotate the auxiliary basis for Coulomb calculation. +- **Default**: false + +### exx_multip_moments_threshold + +- **Type**: Real +- **Description**: Threshold to screen multipole moments in Coulomb calculation. +- **Default**: 1e-10 + +### shrink_abfs_pca_thr + +- **Type**: Real +- **Description**: Threshold to shrink the auxiliary basis for GW/RPA calculations. +- **Default**: -1 + +### shrink_lu_inv_thr + +- **Type**: Real +- **Description**: Threshold for obtaining the inverse of the overlap matrix by LU decomposition in the auxiliary-basis representation. +- **Default**: 1e-6 + [back to top](#full-list-of-input-keywords) ## Exact Exchange (PW) @@ -3377,6 +3419,7 @@ - berendsen: Berendsen thermostat, see md_nraise in detail. - rescaling: velocity Rescaling method 1, see md_tolerance in detail. - rescale_v: velocity Rescaling method 2, see md_nraise in detail. + - csvr: Canonical Sampling through Velocity Rescaling, see md_csvr_tau in detail. - **Default**: nhc ### md_tfirst diff --git a/docs/parameters.yaml b/docs/parameters.yaml index bcb562fa693..12f6be411a5 100644 --- a/docs/parameters.yaml +++ b/docs/parameters.yaml @@ -1399,6 +1399,7 @@ parameters: * berendsen: Berendsen thermostat, see md_nraise in detail. * rescaling: velocity Rescaling method 1, see md_tolerance in detail. * rescale_v: velocity Rescaling method 2, see md_nraise in detail. + * csvr: Canonical Sampling through Velocity Rescaling, see md_csvr_tau in detail. default_value: nhc unit: "" availability: "" @@ -3321,7 +3322,7 @@ parameters: category: Output information type: Boolean description: | - Whether to print Hamiltonian matrices H(R) in npz format. This feature does not work for gamma-only calculations. + Whether to print Hamiltonian matrices H(R) in npz format. The output files are named output_HR0.npz, output_HR1.npz, and so on according to spin channel. This feature requires ABACUS to be built with CNPY. default_value: "False" unit: Ry availability: Numerical atomic orbital basis (not gamma-only algorithm) @@ -3329,7 +3330,7 @@ parameters: category: Output information type: Boolean description: | - Whether to print Hamiltonian matrices H(R) and overlap matrix S(R) in npz format. This feature does not work for gamma-only calculations. + Whether to print Hamiltonian matrices H(R) and overlap matrix S(R) in npz format. The output files are named output_SR.npz, output_HR0.npz, output_HR1.npz, and so on according to spin channel. This feature requires ABACUS to be built with CNPY. default_value: "False" unit: Ry availability: Numerical atomic orbital basis (not gamma-only algorithm) @@ -3337,7 +3338,7 @@ parameters: category: Output information type: Boolean description: | - Whether to print density matrices DM(R) in npz format. This feature does not work for gamma-only calculations. + Whether to print density matrices DM(R) in npz format. The output files are named output_DM0.npz, output_DM1.npz, and so on according to spin channel. This feature requires ABACUS to be built with CNPY. default_value: "False" unit: "" availability: Numerical atomic orbital basis (not gamma-only algorithm) @@ -4314,6 +4315,54 @@ parameters: default_value: "false" unit: "" availability: "" + - name: out_unshrinked_v + category: Exact Exchange (LCAO) + type: Boolean + description: | + Whether to output the large Vq matrix in the unshrinked auxiliary basis. + default_value: "false" + unit: "" + availability: "" + - name: exx_coul_moment + category: Exact Exchange (LCAO) + type: Boolean + description: | + Whether to use the moment method for Coulomb calculation. + default_value: "false" + unit: "" + availability: "" + - name: exx_rotate_abfs + category: Exact Exchange (LCAO) + type: Boolean + description: | + Whether to rotate the auxiliary basis for Coulomb calculation. + default_value: "false" + unit: "" + availability: "" + - name: exx_multip_moments_threshold + category: Exact Exchange (LCAO) + type: Real + description: | + Threshold to screen multipole moments in Coulomb calculation. + default_value: "1e-10" + unit: "" + availability: "" + - name: shrink_abfs_pca_thr + category: Exact Exchange (LCAO) + type: Real + description: | + Threshold to shrink the auxiliary basis for GW/RPA calculations. + default_value: "-1" + unit: "" + availability: "" + - name: shrink_lu_inv_thr + category: Exact Exchange (LCAO) + type: Real + description: | + Threshold for obtaining the inverse of the overlap matrix by LU decomposition in the auxiliary-basis representation. + default_value: "1e-6" + unit: "" + availability: "" - name: dft_plus_u category: DFT+U correction type: Integer diff --git a/source/source_io/module_parameter/read_input_item_exx_dftu.cpp b/source/source_io/module_parameter/read_input_item_exx_dftu.cpp index 8f5f926a174..85468b18aca 100644 --- a/source/source_io/module_parameter/read_input_item_exx_dftu.cpp +++ b/source/source_io/module_parameter/read_input_item_exx_dftu.cpp @@ -567,36 +567,72 @@ void ReadInput::item_exx() { Input_Item item("out_unshrinked_v"); item.annotation = "whether to output the large Vq matrix in unshrinked auxiliary basis"; + item.category = "Exact Exchange (LCAO)"; + item.type = "Boolean"; + item.description = "Whether to output the large Vq matrix in the unshrinked auxiliary basis."; + item.default_value = "false"; + item.unit = ""; + item.availability = ""; read_sync_bool(input.out_unshrinked_v); this->add_item(item); } { Input_Item item("exx_coul_moment"); item.annotation = "whether to use moment method for Coulomb calculation"; + item.category = "Exact Exchange (LCAO)"; + item.type = "Boolean"; + item.description = "Whether to use the moment method for Coulomb calculation."; + item.default_value = "false"; + item.unit = ""; + item.availability = ""; read_sync_bool(input.exx_coul_moment); this->add_item(item); } { Input_Item item("exx_rotate_abfs"); item.annotation = "whether to rotate auxiliary basis for Coulomb calculation"; + item.category = "Exact Exchange (LCAO)"; + item.type = "Boolean"; + item.description = "Whether to rotate the auxiliary basis for Coulomb calculation."; + item.default_value = "false"; + item.unit = ""; + item.availability = ""; read_sync_bool(input.exx_rotate_abfs); this->add_item(item); } { Input_Item item("exx_multip_moments_threshold"); item.annotation = "threshold to screen multipole moments in Coulomb calculation"; + item.category = "Exact Exchange (LCAO)"; + item.type = "Real"; + item.description = "Threshold to screen multipole moments in Coulomb calculation."; + item.default_value = "1e-10"; + item.unit = ""; + item.availability = ""; read_sync_double(input.exx_multip_moments_threshold); this->add_item(item); } { Input_Item item("shrink_abfs_pca_thr"); item.annotation = "threshold to shrink auxiliary basis for GW/RPA"; + item.category = "Exact Exchange (LCAO)"; + item.type = "Real"; + item.description = "Threshold to shrink the auxiliary basis for GW/RPA calculations."; + item.default_value = "-1"; + item.unit = ""; + item.availability = ""; read_sync_double(input.shrink_abfs_pca_thr); this->add_item(item); } { Input_Item item("shrink_lu_inv_thr"); item.annotation = "threshold to get inverse of overlap matrix by LU decomposition in auxiliary basis representation"; + item.category = "Exact Exchange (LCAO)"; + item.type = "Real"; + item.description = "Threshold for obtaining the inverse of the overlap matrix by LU decomposition in the auxiliary-basis representation."; + item.default_value = "1e-6"; + item.unit = ""; + item.availability = ""; read_sync_double(input.shrink_LU_inv_thr); this->add_item(item); } diff --git a/source/source_io/module_parameter/read_input_item_md.cpp b/source/source_io/module_parameter/read_input_item_md.cpp index 76d393b438b..ac9054cc119 100644 --- a/source/source_io/module_parameter/read_input_item_md.cpp +++ b/source/source_io/module_parameter/read_input_item_md.cpp @@ -83,7 +83,8 @@ void ReadInput::item_md() * anderson: Anderson thermostat, see md_nraise in detail. * berendsen: Berendsen thermostat, see md_nraise in detail. * rescaling: velocity Rescaling method 1, see md_tolerance in detail. -* rescale_v: velocity Rescaling method 2, see md_nraise in detail.)"; +* rescale_v: velocity Rescaling method 2, see md_nraise in detail. +* csvr: Canonical Sampling through Velocity Rescaling, see md_csvr_tau in detail.)"; item.default_value = "nhc"; item.unit = ""; item.availability = ""; diff --git a/source/source_io/module_parameter/read_input_item_output.cpp b/source/source_io/module_parameter/read_input_item_output.cpp index af2ce8c6964..035fdcae1f1 100644 --- a/source/source_io/module_parameter/read_input_item_output.cpp +++ b/source/source_io/module_parameter/read_input_item_output.cpp @@ -1187,7 +1187,7 @@ The circle order of the charge density on real space grids is: x is the outer lo item.annotation = "output H(R) matrix in npz format"; item.category = "Output information"; item.type = "Boolean"; - item.description = "Whether to print Hamiltonian matrices H(R) in npz format. This feature does not work for gamma-only calculations."; + item.description = "Whether to print Hamiltonian matrices H(R) in npz format. The output files are named output_HR0.npz, output_HR1.npz, and so on according to spin channel. This feature requires ABACUS to be built with CNPY."; item.default_value = "False"; item.unit = "Ry"; item.availability = "Numerical atomic orbital basis (not gamma-only algorithm)"; @@ -1209,7 +1209,7 @@ The circle order of the charge density on real space grids is: x is the outer lo item.annotation = "output H(R) and S(R) matrices in npz format"; item.category = "Output information"; item.type = "Boolean"; - item.description = "Whether to print Hamiltonian matrices H(R) and overlap matrix S(R) in npz format. This feature does not work for gamma-only calculations."; + item.description = "Whether to print Hamiltonian matrices H(R) and overlap matrix S(R) in npz format. The output files are named output_SR.npz, output_HR0.npz, output_HR1.npz, and so on according to spin channel. This feature requires ABACUS to be built with CNPY."; item.default_value = "False"; item.unit = "Ry"; item.availability = "Numerical atomic orbital basis (not gamma-only algorithm)"; @@ -1231,7 +1231,7 @@ The circle order of the charge density on real space grids is: x is the outer lo item.annotation = "output DM(R) matrix in npz format"; item.category = "Output information"; item.type = "Boolean"; - item.description = "Whether to print density matrices DM(R) in npz format. This feature does not work for gamma-only calculations."; + item.description = "Whether to print density matrices DM(R) in npz format. The output files are named output_DM0.npz, output_DM1.npz, and so on according to spin channel. This feature requires ABACUS to be built with CNPY."; item.default_value = "False"; item.unit = ""; item.availability = "Numerical atomic orbital basis (not gamma-only algorithm)"; From 003c1a5636f36b23ec5a4a631f8a4c97a20bc043 Mon Sep 17 00:00:00 2001 From: Bonan Zhu Date: Sun, 12 Jul 2026 16:29:13 +0800 Subject: [PATCH 3/9] docs: add local manual build instructions --- docs/README.md | 106 +++++++++++++++++++++++++++++++++++++++++++++++++ docs/conf.py | 2 +- 2 files changed, 107 insertions(+), 1 deletion(-) create mode 100644 docs/README.md diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000000..29a84ad536f --- /dev/null +++ b/docs/README.md @@ -0,0 +1,106 @@ +# ABACUS Documentation + +These files are the source for the ABACUS manual published on Read the Docs. + +Read the Docs builds a minimal serial ABACUS binary, regenerates +`docs/parameters.yaml` from that binary, and lets Sphinx regenerate +`docs/advanced/input_files/input-main.md` during the documentation build. + +## Build the Manual Locally + +Run the following commands from the repository root. + +1. Create a Python virtual environment with `uv`: + + ```bash + uv venv --python python3 .venv + ``` + +1. Install the documentation requirements: + + ```bash + uv pip install --python .venv/bin/python -r docs/requirements.txt sphinx ninja + ``` + +1. Build the reduced ABACUS executable used for INPUT parameter metadata: + + ```bash + cmake -S . -B build-rtd-docs -G Ninja \ + -DCMAKE_BUILD_TYPE=Release \ + -DENABLE_MPI=OFF \ + -DENABLE_LCAO=OFF \ + -DUSE_OPENMP=OFF \ + -DUSE_ELPA=OFF \ + -DUSE_CUDA=OFF \ + -DUSE_ROCM=OFF \ + -DBUILD_TESTING=OFF \ + -DENABLE_LIBXC=OFF \ + -DENABLE_LIBRI=OFF \ + -DENABLE_DFTD4=OFF \ + -DENABLE_RAPIDJSON=OFF \ + -DENABLE_MLALGO=OFF \ + -DENABLE_FLOAT_FFTW=OFF \ + -DENABLE_CNPY=OFF \ + -DCOMMIT_INFO=OFF \ + -DGIT_SUBMODULE=OFF \ + -DMKLROOT=OFF + cmake --build build-rtd-docs --target abacus_pw_ser --parallel 2 + ``` + +1. Regenerate the INPUT parameter files: + + ```bash + ./build-rtd-docs/source/abacus_pw_ser --generate-parameters-yaml > docs/parameters.yaml + .venv/bin/python docs/generate_input_main.py docs/parameters.yaml \ + --output docs/advanced/input_files/input-main.md + ``` + +1. Build the HTML manual: + + ```bash + .venv/bin/sphinx-build -b html docs build-docs/html + ``` + +1. Open `build-docs/html/index.html` in a browser. + +## INPUT Parameter Reference + +The INPUT parameter reference is generated from metadata registered in +`source/source_io/module_parameter/read_input_item_*.cpp`. + +- `docs/parameters.yaml` is an intermediate YAML dump produced by + `abacus --generate-parameters-yaml`. +- `docs/advanced/input_files/input-main.md` is generated from that YAML file. +- `docs/conf.py` refreshes `input-main.md` automatically when + `docs/parameters.yaml` exists. + +The Read the Docs build no longer depends on a committed `docs/parameters.yaml` +because `.readthedocs.yaml` regenerates it before Sphinx runs. A local Sphinx +build also succeeds without `docs/parameters.yaml` when the checked-in +`input-main.md` is already present, but a fresh INPUT reference still requires +an ABACUS binary. + +For now, keep both generated files in PRs that change INPUT metadata, following +the repository contribution guide. Dropping `docs/parameters.yaml` from version +control is technically possible after the project also updates the contributor +guide and PR template to make the generated-file policy explicit. + +## Optional Read the Docs Container Test + +To smoke-test the Read the Docs environment locally, use the same image as the +hosted build: + +```bash +docker run --rm -v "$PWD:/project" -w /project \ + readthedocs/build:ubuntu-22.04-2024.01.29 \ + /bin/bash -lc 'python -m pip install -r docs/requirements.txt sphinx ninja && + cmake -S . -B build-rtd-docs -G Ninja -DCMAKE_BUILD_TYPE=Release \ + -DENABLE_MPI=OFF -DENABLE_LCAO=OFF -DUSE_OPENMP=OFF -DUSE_ELPA=OFF \ + -DUSE_CUDA=OFF -DUSE_ROCM=OFF -DBUILD_TESTING=OFF \ + -DENABLE_LIBXC=OFF -DENABLE_LIBRI=OFF -DENABLE_DFTD4=OFF \ + -DENABLE_RAPIDJSON=OFF -DENABLE_MLALGO=OFF -DENABLE_FLOAT_FFTW=OFF \ + -DENABLE_CNPY=OFF -DCOMMIT_INFO=OFF -DGIT_SUBMODULE=OFF -DMKLROOT=OFF && + cmake --build build-rtd-docs --target abacus_pw_ser --parallel 2 && + ./build-rtd-docs/source/abacus_pw_ser --generate-parameters-yaml > docs/parameters.yaml && + sphinx-build -b html docs /tmp/abacus-docs-html' +``` diff --git a/docs/conf.py b/docs/conf.py index bf96df8cb7b..101f2609227 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -57,7 +57,7 @@ # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. # This pattern also affects html_static_path and html_extra_path. -exclude_patterns = [] +exclude_patterns = ['README.md'] # -- Options for HTML output ------------------------------------------------- From 49f47e2219959f3cfc9ae3c4326498c6b4beca18 Mon Sep 17 00:00:00 2001 From: Bonan Zhu Date: Sun, 12 Jul 2026 17:27:16 +0800 Subject: [PATCH 4/9] docs: generate input reference without checked-in yaml --- .../abacus-governance.instructions.md | 5 +- .github/workflows/test.yml | 13 +- .readthedocs.yaml | 1 - AGENTS.md | 8 +- docs/CONTRIBUTING.md | 24 +- docs/README.md | 57 +- docs/advanced/input_files/input-main.md | 2 +- docs/conf.py | 102 +- docs/developers_guide/agent_governance.md | 6 +- docs/generate_input_main.py | 48 +- docs/parameters.yaml | 4973 ----------------- docs/tests/test_conf_input_docs.py | 73 + 12 files changed, 240 insertions(+), 5072 deletions(-) delete mode 100644 docs/parameters.yaml create mode 100644 docs/tests/test_conf_input_docs.py diff --git a/.github/instructions/abacus-governance.instructions.md b/.github/instructions/abacus-governance.instructions.md index 6e0e09df09e..0a1f2a5a2b8 100644 --- a/.github/instructions/abacus-governance.instructions.md +++ b/.github/instructions/abacus-governance.instructions.md @@ -23,8 +23,9 @@ Apply these instructions when reviewing or changing ABACUS code: - Require LF line endings for text files. `.bat` and `.cmd` files are the CRLF exceptions. - For INPUT parameter behavior changes, require synchronized updates to - `docs/parameters.yaml` and `docs/advanced/input_files/input-main.md`, or a - clear no-update explanation in the PR. + `docs/advanced/input_files/input-main.md`, or a clear no-update explanation + in the PR. The parameter YAML stream is generated transiently and is not stored + in the repository. - Check that new source files are linked through the relevant `CMakeLists.txt` unless the PR explains generated or indirect inclusion. - Keep default C++ changes compatible with the repository C++11 baseline. diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index ee633a76cae..6b141943a62 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -89,24 +89,17 @@ jobs: ABACUS_BIN=$(find build -name "abacus_*" -type f -executable | head -1) echo "Using binary: ${ABACUS_BIN}" - # Check 1: parameters.yaml matches C++ Input_Item definitions + # Generate transient parameter metadata from C++ Input_Item definitions ${ABACUS_BIN} --generate-parameters-yaml > /tmp/parameters_generated.yaml - if ! diff -q docs/parameters.yaml /tmp/parameters_generated.yaml; then - echo "error: docs/parameters.yaml is out of sync with C++ source" - echo "Fix: ${ABACUS_BIN} --generate-parameters-yaml > docs/parameters.yaml" - diff docs/parameters.yaml /tmp/parameters_generated.yaml || true - exit 1 - fi - echo " parameters.yaml: OK" - # Check 2: input-main.md matches regenerated markdown + # Check: input-main.md matches regenerated markdown pip install -q pyyaml python docs/generate_input_main.py \ /tmp/parameters_generated.yaml \ --output /tmp/input-main-generated.md if ! diff -q docs/advanced/input_files/input-main.md /tmp/input-main-generated.md; then echo "error: input-main.md is out of sync" - echo "Fix: python docs/generate_input_main.py docs/parameters.yaml" + echo "Fix: ${ABACUS_BIN} --generate-parameters-yaml | python docs/generate_input_main.py - --output docs/advanced/input_files/input-main.md" diff docs/advanced/input_files/input-main.md /tmp/input-main-generated.md || true exit 1 fi diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 6253a4466ef..8696b231d8c 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -42,7 +42,6 @@ build: -DGIT_SUBMODULE=OFF -DMKLROOT=OFF - cmake --build build-rtd-docs --target abacus_pw_ser --parallel 2 - - ./build-rtd-docs/source/abacus_pw_ser --generate-parameters-yaml > docs/parameters.yaml # Build documentation in the "docs/" directory with Sphinx sphinx: diff --git a/AGENTS.md b/AGENTS.md index e95e177691f..96ad3fac115 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -26,9 +26,10 @@ rules. Read the complete governance document before making or reviewing changes: - Use LF line endings for text files. Only `.bat` and `.cmd` files may use CRLF. - Keep source file additions deterministic: update the relevant `CMakeLists.txt` or explain why the file is generated or included indirectly. -- INPUT parameter behavior changes must update `docs/parameters.yaml` and +- INPUT parameter behavior changes must update `docs/advanced/input_files/input-main.md`, or the PR must state why no update - is required. + is required. The parameter YAML stream is generated transiently by the ABACUS + binary and is not stored in the repository. - Report the exact verification performed. Do not claim completion without fresh test or check output. @@ -37,8 +38,7 @@ rules. Read the complete governance document before making or reviewing changes: - Core C++ implementation lives under `source/`; source additions must be wired through the relevant `CMakeLists.txt`. - INPUT parsing and help metadata live under `source/source_io/`; user-facing - INPUT docs live in `docs/parameters.yaml` and - `docs/advanced/input_files/input-main.md`. + INPUT docs live in `docs/advanced/input_files/input-main.md`. - Unit tests are colocated under module `test/` directories such as `source/source_md/test/`; integration and workflow tests are selected through CTest labels and patterns. diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 5ada0540ef8..1e7f7a2992a 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -174,11 +174,11 @@ An practical example is class [LCAO_Deepks](https://github.com/deepmodeling/abac ABACUS includes a built-in help system that allows users to query INPUT parameters directly from the command line (e.g., `abacus -h ecutwfc`). Parameter metadata is defined inline in the C++ source files (`source/source_io/module_parameter/read_input_item_*.cpp`) using `Input_Item` registrations. -A checked-in file `docs/parameters.yaml` contains a YAML dump of all parameter metadata, generated from the binary itself. This file is used by Sphinx to produce the online documentation page `input-main.md`. +A checked-in file `docs/advanced/input_files/input-main.md` contains the generated INPUT parameter reference. Sphinx refreshes this file from an ABACUS executable when the executable is available. -### When to Update `docs/parameters.yaml` +### When to Update `input-main.md` -You **must** regenerate `docs/parameters.yaml` whenever you: +You **must** regenerate `docs/advanced/input_files/input-main.md` whenever you: - Add a new INPUT parameter - Remove an existing INPUT parameter @@ -186,25 +186,23 @@ You **must** regenerate `docs/parameters.yaml` whenever you: ### How to Regenerate -After building and installing ABACUS, run: +After building ABACUS, run: ```bash -abacus --generate-parameters-yaml > docs/parameters.yaml +abacus --generate-parameters-yaml \ + | python3 docs/generate_input_main.py - \ + --output docs/advanced/input_files/input-main.md ``` -Then verify the YAML is valid: +You can also let Sphinx refresh the page during a documentation build: ```bash -python3 -c "import yaml; d=yaml.safe_load(open('docs/parameters.yaml')); print(len(d['parameters']), 'parameters')" +ABACUS_BINARY=/path/to/abacus sphinx-build -b html docs build-docs/html ``` -You can also regenerate the markdown documentation locally: +If no ABACUS executable is available, Sphinx emits a warning and continues with the checked-in `input-main.md`, which may not be up to date. -```bash -python3 docs/generate_input_main.py docs/parameters.yaml --output docs/advanced/input_files/input-main.md -``` - -**Important:** Include the updated `docs/parameters.yaml` and `input-main.md` in your commit when submitting a PR that modifies INPUT parameters. Reviewers should verify the YAML changes match the C++ source changes and the `input-main.md` is updated. +**Important:** Include the updated `input-main.md` in your commit when submitting a PR that modifies INPUT parameters. Reviewers should verify the generated documentation matches the C++ source changes. ### Parameter Documentation Format diff --git a/docs/README.md b/docs/README.md index 29a84ad536f..0221bc5816e 100644 --- a/docs/README.md +++ b/docs/README.md @@ -3,8 +3,8 @@ These files are the source for the ABACUS manual published on Read the Docs. Read the Docs builds a minimal serial ABACUS binary, regenerates -`docs/parameters.yaml` from that binary, and lets Sphinx regenerate -`docs/advanced/input_files/input-main.md` during the documentation build. +`docs/advanced/input_files/input-main.md` from that binary during the +documentation build, and emits a warning if no ABACUS executable is available. ## Build the Manual Locally @@ -47,43 +47,46 @@ Run the following commands from the repository root. cmake --build build-rtd-docs --target abacus_pw_ser --parallel 2 ``` -1. Regenerate the INPUT parameter files: - - ```bash - ./build-rtd-docs/source/abacus_pw_ser --generate-parameters-yaml > docs/parameters.yaml - .venv/bin/python docs/generate_input_main.py docs/parameters.yaml \ - --output docs/advanced/input_files/input-main.md - ``` - 1. Build the HTML manual: ```bash - .venv/bin/sphinx-build -b html docs build-docs/html + ABACUS_BINARY=./build-rtd-docs/source/abacus_pw_ser \ + .venv/bin/sphinx-build -b html docs build-docs/html ``` + If `ABACUS_BINARY` is not set, `docs/conf.py` looks for the Read the Docs + build binary and then for `abacus` or `abacus_pw_ser` on `PATH`. + 1. Open `build-docs/html/index.html` in a browser. +If no ABACUS executable is available, the Sphinx build still continues with the +checked-in `docs/advanced/input_files/input-main.md` and prints a warning that +the INPUT parameter reference may not be up to date. + +## Regenerate Only the INPUT Reference + +To refresh only the generated INPUT reference after building ABACUS: + +```bash +./build-rtd-docs/source/abacus_pw_ser --generate-parameters-yaml \ + | .venv/bin/python docs/generate_input_main.py - \ + --output docs/advanced/input_files/input-main.md +``` + ## INPUT Parameter Reference The INPUT parameter reference is generated from metadata registered in `source/source_io/module_parameter/read_input_item_*.cpp`. -- `docs/parameters.yaml` is an intermediate YAML dump produced by - `abacus --generate-parameters-yaml`. -- `docs/advanced/input_files/input-main.md` is generated from that YAML file. -- `docs/conf.py` refreshes `input-main.md` automatically when - `docs/parameters.yaml` exists. - -The Read the Docs build no longer depends on a committed `docs/parameters.yaml` -because `.readthedocs.yaml` regenerates it before Sphinx runs. A local Sphinx -build also succeeds without `docs/parameters.yaml` when the checked-in -`input-main.md` is already present, but a fresh INPUT reference still requires -an ABACUS binary. +- `abacus --generate-parameters-yaml` produces a transient YAML stream; it is + not stored in the repository. +- `docs/advanced/input_files/input-main.md` is generated from that metadata. +- `docs/conf.py` refreshes `input-main.md` automatically when it can find an + ABACUS executable. -For now, keep both generated files in PRs that change INPUT metadata, following -the repository contribution guide. Dropping `docs/parameters.yaml` from version -control is technically possible after the project also updates the contributor -guide and PR template to make the generated-file policy explicit. +Keep `docs/advanced/input_files/input-main.md` in PRs that change INPUT +metadata. The YAML dump is intentionally transient so there is only one +generated reference file to maintain. ## Optional Read the Docs Container Test @@ -101,6 +104,6 @@ docker run --rm -v "$PWD:/project" -w /project \ -DENABLE_RAPIDJSON=OFF -DENABLE_MLALGO=OFF -DENABLE_FLOAT_FFTW=OFF \ -DENABLE_CNPY=OFF -DCOMMIT_INFO=OFF -DGIT_SUBMODULE=OFF -DMKLROOT=OFF && cmake --build build-rtd-docs --target abacus_pw_ser --parallel 2 && - ./build-rtd-docs/source/abacus_pw_ser --generate-parameters-yaml > docs/parameters.yaml && + export ABACUS_BINARY=./build-rtd-docs/source/abacus_pw_ser && sphinx-build -b html docs /tmp/abacus-docs-html' ``` diff --git a/docs/advanced/input_files/input-main.md b/docs/advanced/input_files/input-main.md index 1db92d43d7d..34a552343ec 100644 --- a/docs/advanced/input_files/input-main.md +++ b/docs/advanced/input_files/input-main.md @@ -1,6 +1,6 @@ # Full List of INPUT Keywords - + diff --git a/docs/conf.py b/docs/conf.py index 101f2609227..6f97f0af117 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -101,30 +101,94 @@ } -# -- Auto-generate INPUT keyword documentation from YAML parameter dump ------ +# -- Auto-generate INPUT keyword documentation from ABACUS metadata ---------- +import shutil +import subprocess +import sys from pathlib import Path -def generate_input_docs(app): - """Auto-generate input-main.md from parameters.yaml before building. - - Workflow: - abacus --generate-parameters-yaml > docs/parameters.yaml - # Then Sphinx calls this hook, which runs generate_input_main.py - """ - docs_dir = Path(__file__).resolve().parent - yaml_path = docs_dir / 'parameters.yaml' - if not yaml_path.exists(): - print(f"Warning: {yaml_path} not found. " - "Run: abacus --generate-parameters-yaml > docs/parameters.yaml") - return - import sys - sys.path.insert(0, str(docs_dir)) - from generate_input_main import generate - generate( - yaml_path=yaml_path, +try: + from sphinx.util import logging as sphinx_logging + logger = sphinx_logging.getLogger(__name__) +except Exception: + logger = None + + +def warn_input_docs(message): + if logger is not None: + logger.warning(message) + else: + print(f"Warning: {message}") + + +def candidate_abacus_binaries(repo_root): + """Return candidate ABACUS binaries for local and Read the Docs builds.""" + env_binary = os.environ.get('ABACUS_BINARY') or os.environ.get('ABACUS_EXECUTABLE') + candidates = [] + if env_binary: + candidates.append(Path(env_binary)) + candidates.extend([ + repo_root / 'build-rtd-docs' / 'source' / 'abacus_pw_ser', + repo_root / 'build-rtd-docs' / 'abacus_pw_ser', + ]) + for binary_name in ['abacus', 'abacus_pw_ser']: + path_binary = shutil.which(binary_name) + if path_binary: + candidates.append(Path(path_binary)) + return candidates + + +def find_abacus_binary(repo_root): + for candidate in candidate_abacus_binaries(repo_root): + if candidate.exists() and os.access(candidate, os.X_OK): + return candidate + return None + + +def refresh_input_docs(docs_dir, abacus_binary=None, warn=warn_input_docs): + """Refresh input-main.md from an ABACUS executable, if one is available.""" + docs_dir = Path(docs_dir) + repo_root = docs_dir.parent + binary = Path(abacus_binary) if abacus_binary else find_abacus_binary(repo_root) + if binary is None or not binary.exists() or not os.access(binary, os.X_OK): + warn( + "ABACUS executable not found; INPUT parameter documentation may not " + "be up to date. Set ABACUS_BINARY=/path/to/abacus or build the " + "reduced documentation binary first." + ) + return False + + env = os.environ.copy() + env.setdefault('OMP_NUM_THREADS', '1') + result = subprocess.run( + [str(binary), '--generate-parameters-yaml'], + cwd=repo_root, + env=env, + text=True, + capture_output=True, + ) + if result.returncode != 0: + detail = result.stderr.strip() or result.stdout.strip() + warn( + "ABACUS could not generate INPUT parameter metadata; documentation " + f"may not be up to date. Command: {binary} --generate-parameters-yaml" + + (f". Output: {detail}" if detail else "") + ) + return False + + sys.path.insert(0, str(Path(__file__).resolve().parent)) + import yaml + from generate_input_main import generate_from_data + generate_from_data( + data=yaml.safe_load(result.stdout), output=docs_dir / 'advanced' / 'input_files' / 'input-main.md', ) + return True + + +def generate_input_docs(app): + refresh_input_docs(Path(__file__).resolve().parent) def setup(app): app.connect('builder-inited', generate_input_docs) diff --git a/docs/developers_guide/agent_governance.md b/docs/developers_guide/agent_governance.md index 8127076cbc6..dd489fd2a55 100644 --- a/docs/developers_guide/agent_governance.md +++ b/docs/developers_guide/agent_governance.md @@ -215,11 +215,13 @@ setup workflows and should be added only through a later governance change. ## INPUT Parameter Changes Changes to parameter metadata, default values, type, availability, description, -or parsing behavior must include both: +or parsing behavior must include: -- `docs/parameters.yaml` - `docs/advanced/input_files/input-main.md` +The parameter YAML stream is generated transiently from the ABACUS binary and +is not stored in the repository. + If the diff touches parameter internals but does not change user-visible INPUT behavior, the PR must state why no documentation update is required. diff --git a/docs/generate_input_main.py b/docs/generate_input_main.py index 4e138034d7f..9b38572b282 100644 --- a/docs/generate_input_main.py +++ b/docs/generate_input_main.py @@ -3,15 +3,12 @@ Generate input-main.md from a YAML parameter dump. Usage: - # Generate YAML first: - abacus --generate-parameters-yaml > docs/parameters.yaml - - # Then generate markdown: - python docs/generate_input_main.py docs/parameters.yaml [--output FILE] + # Generate markdown from an ABACUS parameter YAML dump: + abacus --generate-parameters-yaml | python docs/generate_input_main.py - [--output FILE] Can also be imported from conf.py: - from generate_input_main import generate - generate(yaml_path, output) + from generate_input_main import generate_from_data + generate_from_data(data, output) """ import argparse @@ -240,20 +237,13 @@ def generate_toc(sorted_categories: OrderedDict) -> str: return '\n'.join(lines) -def generate(yaml_path: Path, output: Path, verbose: bool = False): +def generate_from_data(data: Dict, output: Path, verbose: bool = False): """ - Core generation logic. Can be called from conf.py or CLI. + Generate markdown from loaded parameter metadata. """ - yaml_path = Path(yaml_path) output = Path(output) - if not yaml_path.exists(): - raise FileNotFoundError(f"YAML file not found: {yaml_path}") - - with open(yaml_path, 'r') as f: - data = yaml.safe_load(f) - - all_params = data.get('parameters', []) + all_params = (data or {}).get('parameters', []) print(f"Total: {len(all_params)} documented parameters") # Group by category @@ -279,7 +269,7 @@ def generate(yaml_path: Path, output: Path, verbose: bool = False): md_parts = [ "# Full List of INPUT Keywords", "", - "", + "", "", "", "", @@ -301,14 +291,32 @@ def generate(yaml_path: Path, output: Path, verbose: bool = False): print(f"Categories: {len(sorted_categories)}") +def generate(yaml_path: Path, output: Path, verbose: bool = False): + """ + Core generation logic. Can be called from the CLI. + """ + yaml_path = Path(yaml_path) + + if str(yaml_path) == '-': + data = yaml.safe_load(sys.stdin) + else: + if not yaml_path.exists(): + raise FileNotFoundError(f"YAML file not found: {yaml_path}") + + with open(yaml_path, 'r') as f: + data = yaml.safe_load(f) + + generate_from_data(data, output=output, verbose=verbose) + + def main(): parser = argparse.ArgumentParser( description='Generate input-main.md from YAML parameter dump' ) parser.add_argument( 'yaml_file', - type=Path, - help='Path to parameters.yaml (generated by abacus --generate-parameters-yaml)' + type=str, + help='Path to parameter YAML, or - to read from standard input' ) parser.add_argument( '--output', diff --git a/docs/parameters.yaml b/docs/parameters.yaml deleted file mode 100644 index 12f6be411a5..00000000000 --- a/docs/parameters.yaml +++ /dev/null @@ -1,4973 +0,0 @@ -# Auto-generated by: abacus --generate-parameters-yaml -# Do not edit manually. -parameters: - - name: suffix - category: System variables - type: String - description: | - In each run, ABACUS will generate a subdirectory in the working directory. This subdirectory contains all the information of the run. The subdirectory name has the format: OUT.suffix, where the suffix is the name you can pick up for your convenience. - default_value: ABACUS - unit: "" - availability: "" - - name: ntype - category: System variables - type: Integer - description: | - Number of different atom species in the calculation. - default_value: "0" - unit: "" - availability: "" - - name: calculation - category: System variables - type: String - description: | - Specify the type of calculation. - - * scf: perform self-consistent electronic structure calculations - * nscf: perform non-self-consistent electronic structure calculations. A charge density file is required - * relax: perform structure relaxation calculations, the relax_nmax parameter depicts the maximal number of ionic iterations - * cell-relax: perform cell relaxation calculations - * md: perform molecular dynamics simulations - * get_pchg: obtain partial (band-decomposed) charge densities (for LCAO basis only). See out_pchg for more information - * get_wf: obtain real space wave functions (for LCAO basis only). See out_wfc_norm and out_wfc_re_im for more information - * get_s: obtain the overlap matrix formed by localized orbitals (for LCAO basis with multiple k points). the file name is SR.csr with file format being the same as that generated by out_mat_hs2 - * gen_bessel: generates projectors, i.e., a series of Bessel functions, for the DeePKS method (for LCAO basis only) - * gen_opt_abfs: generate opt-ABFs as discussed in this article - * test_memory: obtain a rough estimation of memory consumption for the calculation - * test_neighbour: obtain information of neighboring atoms (for LCAO basis only), please specify a positive search_radius manually - default_value: scf - unit: "" - availability: "" - - name: esolver_type - category: System variables - type: String - description: | - Choose the energy solver. - * ksdft: Kohn-Sham density functional theory - * ofdft: orbital-free density functional theory - * tdofdft: time-dependent orbital-free density functional theory - * sdft: stochastic density functional theory - * tddft: real-time time-dependent density functional theory (RT-TDDFT) - * lj: Leonard Jones potential - * dp: DeeP potential - * nep: Neuroevolution Potential - * ks-lr: Kohn-Sham density functional theory + LR-TDDFT (Under Development Feature) - * lr: LR-TDDFT with given KS orbitals (Under Development Feature) - default_value: ksdft - unit: "" - availability: "" - - name: symmetry - category: System variables - type: String - description: | - Takes value 1, 0 or -1. - * -1: No symmetry will be considered. It is recommended to set -1 for non-colinear + soc calculations, where time reversal symmetry is broken sometimes. - * 0: Only time reversal symmetry would be considered in symmetry operations, which implied k point and -k point would be treated as a single k point with twice the weight. - * 1: Symmetry analysis will be performed to determine the type of Bravais lattice and associated symmetry operations. (point groups, space groups, primitive cells, and irreducible k-points) - - [NOTE] When symmetry is enabled (value 1), k-points are reduced to the irreducible Brillouin zone (IBZ). For explicit k-point lists with custom weights (see KPT file), the custom weights are preserved during symmetry reduction. For Monkhorst-Pack grids, uniform weights are used. - default_value: default - unit: "" - availability: "" - - name: symmetry_prec - category: System variables - type: Real - description: | - The accuracy for symmetry analysis. Typically, the default value is good enough, but if the lattice parameters or atom positions in STRU file are not accurate enough, this value should be enlarged. - [NOTE] Note: if calculation==cell_relax, this value can be dynamically changed corresponding to the variation of accuracy of the lattice parameters and atom positions during the relaxation. - default_value: "1.0e-6" - unit: Bohr - availability: "" - - name: symmetry_autoclose - category: System variables - type: Boolean - description: | - Control how to deal with error in symmetry analysis due to inaccurate lattice parameters or atom positions in STRU file, especially useful when calculation==cell-relax - * False: quit with an error message - * True: automatically set symmetry to 0 and continue running without symmetry analysis - default_value: "True" - unit: "" - availability: symmetry==1 - - name: cal_force - category: System variables - type: Boolean - description: | - If set to True, calculate the force at the end of the electronic iteration. - default_value: "False" - unit: "" - availability: "" - - name: kpar - category: System variables - type: Integer - description: | - Divide all processors into kpar groups, and k points will be distributed among each group. The value taken should be less than or equal to the number of k points as well as the number of MPI processes. - default_value: "1" - unit: "" - availability: "" - - name: bndpar - category: System variables - type: Integer - description: | - Divide all processors into bndpar groups, and bands (only stochastic orbitals now) will be distributed among each group. It should be larger than 0. - default_value: "1" - unit: "" - availability: "" - - name: latname - category: System variables - type: String - description: | - Specifies the type of Bravias lattice. When set to none, the three lattice vectors are supplied explicitly in STRU file. - - Available options are: - * none: free structure - * sc: simple cubic - * fcc: face-centered cubic - * bcc: body-centered cubic - * hexagonal: hexagonal - * trigonal: trigonal - * st: simple tetragonal - * bct: body-centered tetragonal - * so: orthorhombic - * baco: base-centered orthorhombic - * fco: face-centered orthorhombic - * bco: body-centered orthorhombic - * sm: simple monoclinic - * bacm: base-centered monoclinic - * triclinic: triclinic - default_value: none - unit: "" - availability: "" - - name: assume_isolated - category: System variables - type: String - description: | - Used to perform a calculation assuming an isolated system in a 3D supercell. - - Available options are: - * none: regular periodic calculation without isolated-system correction. - * makov-payne, m-p, mp: compute the Makov-Payne correction to the total energy and estimate a corrected vacuum level for eigenvalue alignment. This option is available only for cubic lattices (latname = sc, fcc, or bcc). - - Theory: G. Makov and M. C. Payne, Phys. Rev. B 51, 4014 (1995). - default_value: none - unit: "" - availability: "" - - name: init_wfc - category: System variables - type: String - description: | - The type of the starting wave functions. - - Available options are: - * atomic: from atomic pseudo wave functions. If they are not enough, other wave functions are initialized with random numbers. - * atomic+random: add small random numbers on atomic pseudo-wavefunctions - * file: from binary files wf*.dat, which are output by setting out_wfc_pw to 2. - * random: random numbers - * nao: from numerical atomic orbitals. If they are not enough, other wave functions are initialized with random numbers. - * nao+random: add small random numbers on numerical atomic orbitals - - [NOTE] Only the file option is useful for the lcao basis set, which is mostly used when calculation is set to get_wf and get_pchg. - default_value: atomic - unit: "" - availability: "" - - name: init_chg - category: System variables - type: String - description: | - This variable is used for both plane wave set and localized orbitals set. It indicates the type of starting density. - - * atomic: the density is starting from the summation of the atomic density of single atoms. - * file: the density will be read in from a binary file charge-density.dat first. If it does not exist, the charge density will be read in from cube files. - * wfc: the density will be calculated by wavefunctions and occupations. - * dm: the density will be calculated by real space density matrix(DMR) of LCAO base. - * dm_no_renormalize: same as dm, but the charge density is not renormalized to the number of electrons. - * hr: the real space Hamiltonian matrix(HR) will be read in from file hrs1_nao.csr in directory read_file_dir. - * auto: Abacus first attempts to read the density from a file; if not found, it defaults to using atomic density. - default_value: atomic - unit: "" - availability: "" - - name: init_vel - category: System variables - type: Boolean - description: | - * True: read the atom velocity (atomic unit : 1 a.u. = 21.877 Angstrom/fs) from the atom file (STRU) and determine the initial temperature md_tfirst. If md_tfirst is unset or less than zero, init_vel is autoset to be true. - * False: assign value to atom velocity using Gaussian distributed random numbers. - default_value: "False" - unit: "" - availability: "" - - name: mem_saver - category: System variables - type: Integer - description: | - Save memory when performing nscf calculations. - * 0: no memory saving techniques are used. - * 1: a memory saving technique will be used for many k point calculations. - default_value: "0" - unit: "" - availability: Used only for nscf calculations with plane wave basis set. - - name: cal_stress - category: System variables - type: Boolean - description: | - If set to True, calculate the stress at the end of the electronic iteration. - default_value: "False" - unit: "" - availability: "" - - name: diago_proc - category: System variables - type: Integer - description: | - * 0: it will be set to the number of MPI processes. - * >0: it specifies the number of processes used for carrying out diagonalization. Must be less than or equal to total number of MPI processes. - default_value: "0" - unit: "" - availability: Used only for plane wave basis set. - - name: nbspline - category: System variables - type: Integer - description: | - If set to a natural number, a Cardinal B-spline interpolation will be used to calculate Structure Factor. nbspline represents the order of B-spline basis and a larger one can get more accurate results but cost more. It is turned off by default. - default_value: "-1" - unit: "" - availability: "" - - name: kspacing - category: System variables - type: Vector of Real (1 or 3 values) - description: | - Set the smallest allowed spacing between k points, unit in 1/bohr. It should be larger than 0.0, and suggest smaller than 0.25. When you have set this value > 0.0, then the KPT file is unnecessary. The default value 0.0 means that ABACUS will read the applied KPT file. - - [NOTE] If gamma_only is set to be true, kspacing is invalid. - default_value: "0.0" - unit: "" - availability: "" - - name: koffset - category: System variables - type: Vector of Real (3 values) - description: | - Set offsets for automatic k-point mesh generated by kspacing, in each reciprocal direction. This parameter is only effective when kspacing > 0.0 and gamma_only is false. - default_value: 0.0 0.0 0.0 - unit: "" - availability: "" - - name: kmesh_type - category: System variables - type: String - description: | - Set mesh type used for automatic k-point mesh generated by kspacing. Available options are gamma and mp. This parameter is only effective when kspacing > 0.0 and gamma_only is false. - default_value: gamma - unit: "" - availability: "" - - name: min_dist_coef - category: System variables - type: Real - description: | - A factor related to the allowed minimum distance between two atoms. At the beginning, ABACUS will check the structure, and if the distance of two atoms is shorter than min_dist_coef*(standard covalent bond length), we think this structure is unreasonable. - default_value: "0.2" - unit: "" - availability: "" - - name: device - category: System variables - type: String - description: | - Specifies the computing device for ABACUS. - - Available options are: - * cpu: for CPUs via Intel, AMD, or Other supported CPU devices - * gpu: for GPUs via CUDA or ROCm. - - [NOTE] ks_solver must also be set to the algorithms supported. lcao_in_pw currently does not support gpu. - default_value: cpu - unit: "" - availability: "" - - name: precision - category: System variables - type: String - description: | - Specifies the precision when performing scf calculation. - * single: single precision - * double: double precision - default_value: double - unit: "" - availability: Used only for plane wave basis set. - - name: gint_precision - category: System variables - type: String - description: | - Specifies the precision when performing grid integral in LCAO calculations. - * single: single precision - * double: double precision - * mix: mixed precision, starting from single precision and switching to double precision when the SCF residual becomes small enough - default_value: double - unit: "" - availability: Used only for LCAO basis set. - - name: timer_enable_nvtx - category: System variables - type: Boolean - description: | - Controls whether NVTX profiling labels are emitted by the timer. This feature is only effective on CUDA platforms. - - * True: Enable NVTX profiling labels in the timer. - * False: Disable NVTX profiling labels in the timer. - default_value: "False" - unit: "" - availability: "" - - name: cell_factor - category: System variables - type: Real - description: | - Used in the construction of the pseudopotential tables. For cell-relax calculations, this is automatically set to 2.0. - default_value: "1.2" - unit: "" - availability: "" - - name: dm_to_rho - category: System variables - type: Boolean - description: | - Reads density matrix in npz format and calculates electron density. - default_value: "False" - unit: "" - availability: "" - - name: chg_extrap - category: System variables - type: String - description: | - Charge extrapolation method for MD and relaxation calculations. - default_value: default - unit: "" - availability: "" - - name: ecutwfc - category: Plane wave related variables - type: Real - description: | - Energy cutoff for plane wave functions. Note that even for localized orbitals basis, you still need to setup an energy cutoff for this system. Because our local pseudopotential parts and the related force are calculated from plane wave basis set. - [NOTE] ecutwfc and ecutrho can be set simultaneously. If only one parameter is set, abacus will automatically set another parameter based on the 4-time relationship. - default_value: "50 for PW basis, 100 for LCAO basis" - unit: Ry - availability: "" - - name: ecutrho - category: Plane wave related variables - type: Real - description: | - Energy cutoff for charge density and potential. For norm-conserving pseudopotential you should stick to the default value, you can reduce it by a little but it will introduce noise especially on forces and stress. - default_value: "4*ecutwfc" - unit: Ry - availability: "" - - name: nx - category: Plane wave related variables - type: Integer - description: | - If set to a positive number, specifies the number of FFT grid points in x direction. If set to 0, the number will be calculated from ecutrho. - - [NOTE] You must specify all three dimensions (nx, ny, nz) for this setting to be used. - default_value: "0" - unit: "" - availability: "" - - name: ny - category: Plane wave related variables - type: Integer - description: | - If set to a positive number, specifies the number of FFT grid points in y direction. If set to 0, the number will be calculated from ecutrho. - - [NOTE] You must specify all three dimensions (nx, ny, nz) for this setting to be used. - default_value: "0" - unit: "" - availability: "" - - name: nz - category: Plane wave related variables - type: Integer - description: | - If set to a positive number, specifies the number of FFT grid points in z direction. If set to 0, the number will be calculated from ecutrho. - - [NOTE] You must specify all three dimensions (nx, ny, nz) for this setting to be used. - default_value: "0" - unit: "" - availability: "" - - name: ndx - category: Plane wave related variables - type: Integer - description: | - If set to a positive number, specifies the number of FFT grid points for the dense part of charge density in x direction. If set to 0, the number will be calculated from ecutwfc. - - [NOTE] You must specify all three dimensions (ndx, ndy, ndz) for this setting to be used. These parameters must be used combined with nx, ny, nz. If nx, ny, nz are unset, ndx, ndy, ndz are used as nx, ny, nz. - default_value: "0" - unit: "" - availability: "" - - name: ndy - category: Plane wave related variables - type: Integer - description: | - If set to a positive number, specifies the number of FFT grid points for the dense part of charge density in y direction. If set to 0, the number will be calculated from ecutwfc. - - [NOTE] You must specify all three dimensions (ndx, ndy, ndz) for this setting to be used. These parameters must be used combined with nx, ny, nz. If nx, ny, nz are unset, ndx, ndy, ndz are used as nx, ny, nz. - default_value: "0" - unit: "" - availability: "" - - name: ndz - category: Plane wave related variables - type: Integer - description: | - If set to a positive number, specifies the number of FFT grid points for the dense part of charge density in z direction. If set to 0, the number will be calculated from ecutwfc. - - [NOTE] You must specify all three dimensions (ndx, ndy, ndz) for this setting to be used. These parameters must be used combined with nx, ny, nz. If nx, ny, nz are unset, ndx, ndy, ndz are used as nx, ny, nz. - default_value: "0" - unit: "" - availability: "" - - name: pw_seed - category: Plane wave related variables - type: Integer - description: | - Specify the random seed to initialize wave functions. Only positive integers are available. - default_value: "0" - unit: "" - availability: Only used for plane wave basis. - - name: diag_subspace - category: Plane wave related variables - type: Integer - description: | - The method to diagonalize subspace in dav_subspace method. - * 0: by LAPACK - * 1: by GenELPA - * 2: by ScaLAPACK - default_value: "0" - unit: "" - availability: "" - - name: erf_ecut - category: Plane wave related variables - type: Real - description: | - Used in variable-cell molecular dynamics (or in stress calculation). See erf_sigma for details. - default_value: "0.0" - unit: Ry - availability: "" - - name: fft_mode - category: Plane wave related variables - type: Integer - description: | - Set the mode of FFTW. - * 0: FFTW_ESTIMATE - * 1: FFTW_MEASURE - * 2: FFTW_PATIENT - * 3: FFTW_EXHAUSTIVE - default_value: "0" - unit: "" - availability: "" - - name: erf_height - category: Plane wave related variables - type: Real - description: | - Used in variable-cell molecular dynamics (or in stress calculation). See erf_sigma for details. - default_value: "0.0" - unit: Ry - availability: "" - - name: erf_sigma - category: Plane wave related variables - type: Real - description: | - In order to recover the accuracy of a constant energy cutoff calculation, the kinetic functional is modified, which is used in variable-cell molecular dynamics (or in stress calculation). - default_value: "0.1" - unit: Ry - availability: "" - - name: stru_file - category: Input files - type: String - description: | - The name of the structure file containing various information about atom species, including pseudopotential files, local orbitals files, cell information, atom positions, and whether atoms should be allowed to move. - default_value: STRU - unit: "" - availability: "" - - name: kpoint_file - category: Input files - type: String - description: | - The name of the k-point file that includes the k-point information of Brillouin zone. - default_value: KPT - unit: "" - availability: "" - - name: pseudo_dir - category: Input files - type: String - description: | - The directory of pseudopotential files. This parameter is combined with the pseudopotential filenames in the STRU file to form the complete pseudopotential file paths. - default_value: "\"\"" - unit: "" - availability: "" - - name: orbital_dir - category: Input files - type: String - description: | - The directory to save numerical atomic orbitals. This parameter is combined with orbital filenames in the STRU file to form the complete orbital file paths. - default_value: "\"\"" - unit: "" - availability: "" - - name: read_file_dir - category: Input files - type: String - description: | - Location of files, such as the electron density (chgs1.cube), required as a starting point. - default_value: OUT.$suffix - unit: "" - availability: "" - - name: restart_load - category: Input files - type: Boolean - description: | - If restart_save is set to true and an electronic iteration is finished, calculations can be restarted from the charge density file, which are saved in the former calculation. - default_value: "False" - unit: "" - availability: Used only when numerical atomic orbitals are employed as basis set. - - name: basis_type - category: Electronic structure - type: String - description: | - Choose the basis set. - * pw: Using plane-wave basis set only. - * lcao: Using localized atomic orbital sets. - * lcao_in_pw: Expand the localized atomic set in plane-wave basis, non-self-consistent field calculation not tested. - default_value: pw - unit: "" - availability: "" - - name: ks_solver - category: Electronic structure - type: String - description: | - Choose the diagonalization methods for the Hamiltonian matrix expanded in a certain basis set. - - For plane-wave basis, - - * cg: The conjugate-gradient (CG) method. - * bpcg: The BPCG method, which is a block-parallel Conjugate Gradient (CG) method, typically exhibits higher acceleration in a GPU environment. - * dav: The Davidson algorithm. - * dav_subspace: The Davidson algorithm without orthogonalization operation, this method is the most recommended for efficiency. `pw_diag_ndim` can be set to 2 for this method. - - For numerical atomic orbitals basis, - - * lapack: Use LAPACK to diagonalize the Hamiltonian, only used for serial version - * genelpa: Use GEN-ELPA to diagonalize the Hamiltonian. - * scalapack_gvx: Use Scalapack to diagonalize the Hamiltonian. - * cusolver: Use CUSOLVER to diagonalize the Hamiltonian, at least one GPU is needed. - * cusolvermp: Use CUSOLVER to diagonalize the Hamiltonian, supporting multi-GPU devices. Note that you should set the number of MPI processes equal to the number of GPUs. - * elpa: The ELPA solver supports both CPU and GPU. By setting the `device` to GPU, you can launch the ELPA solver with GPU acceleration (provided that you have installed a GPU-supported version of ELPA, which requires you to manually compile and install ELPA, and the ABACUS should be compiled with -DUSE_ELPA=ON and -DUSE_CUDA=ON). The ELPA solver also supports multi-GPU acceleration. - - If you set ks_solver=`genelpa` for basis_type=`pw`, the program will stop with an error message: - - ``text genelpa can not be used with plane wave basis. `` - - Then the user has to correct the input file and restart the calculation. - default_value: "\n - PW basis: cg.\n - LCAO basis:\n - genelpa (if compiling option `USE_ELPA` has been set)\n - lapack (if compiling option `ENABLE_MPI` has not been set)\n - scalapack_gvx (if compiling option `USE_ELPA` has not been set and compiling option `ENABLE_MPI` has been set)\n - cusolver (if compiling option `USE_CUDA` has been set)" - unit: "" - availability: "" - - name: nbands - category: Electronic structure - type: Integer - description: | - The number of Kohn-Sham orbitals to calculate. It is recommended to setup this value, especially when smearing techniques are utilized, more bands should be included. - default_value: "" - unit: "" - availability: "" - - name: nelec - category: Electronic structure - type: Real - description: | - * 0.0: The total number of electrons will be calculated by the sum of valence electrons (i.e. assuming neutral system). - * >0.0: this denotes the total number of electrons in the system. Must be less than 2*nbands. - default_value: "0.0" - unit: "" - availability: "" - - name: nelec_delta - category: Electronic structure - type: Real - description: | - The total number of electrons will be calculated by nelec+nelec_delta. - default_value: "0.0" - unit: "" - availability: "" - - name: nupdown - category: Electronic structure - type: Real - description: | - * 0.0: no constrain apply to system. - * >0.0: The different number of electrons between spin-up and spin-down channels. The range of value must be in [-nelec ~ nelec]. It is one type of constrainted DFT method, two Fermi energies will be calculated. - default_value: "0.0" - unit: "" - availability: "" - - name: dft_functional - category: Electronic structure - type: String - description: | - In our package, the XC functional can either be set explicitly using the dft_functional keyword in INPUT file. If dft_functional is not specified, ABACUS will use the xc functional indicated in the pseudopotential file. On the other hand, if dft_functional is specified, it will overwrite the functional from pseudopotentials and performs calculation with whichever functional the user prefers. We further offer two ways of supplying exchange-correlation functional. The first is using 'short-hand' names. A complete list of 'short-hand' expressions can be found in the source code. Supported density functionals are: - * LDA functionals - * LDA (equivalent with PZ and SLAPZNOGXNOGC), PWLDA - * GGA functionals - * PBE (equivalent with SLAPWPBXPBC), PBESOL, REVPBE, WC, BLYP, BP(referred to BP86), PW91, HCTH, OLYP, BLYP_LR - * meta-GGA functionals - * SCAN (require LIBXC) - * Hybrid functionals - * PBE0, HF - * If LIBXC is available, additional short-hand names of hybrid functionals are supported: HSE(referred to HSE06), B3LYP, LC_PBE, LC_WPBE, LRC_WPBE, LRC_WPBEH, CAM_PBEH, WP22, CWP22, MULLER (equivalent with POWER) - * Hybrid meta-GGA functionals - * SCAN0 (require LIBXC) - - The other way is only available when compiling with LIBXC, and it allows for supplying exchange-correlation functionals as combinations of LIBXC keywords for functional components, joined by a plus sign, for example, dft_functional='LDA_X_1D_EXPONENTIAL+LDA_C_1D_CSC'. - default_value: Used the same as DFT functional as specified in the pseudopotential files. - unit: "" - availability: "" - - name: xc_temperature - category: Electronic structure - type: Real - description: | - Specifies temperature when using temperature-dependent XC functionals (KSDT and so on). - default_value: "0.0" - unit: Ry - availability: "" - - name: xc_exch_ext - category: Electronic structure - type: Integer followed by Real values - description: | - Customized parameterization on the exchange part of XC functional. The first value should be the LibXC ID of the original functional, and latter values are external parameters. Default values are those of Perdew-Burke-Ernzerhof (PBE) functional. For more information on LibXC ID of functionals, please refer to LibXC. For parameters of functionals of interest, please refer to the source code of LibXC, such as PBE functional interface in LibXC: gga_x_pbe.c. - - [NOTE] Solely setting this keyword will take no effect on XC functionals. One should also set dft_functional to the corresponding functional to apply the customized parameterization. Presently this feature can only support parameterization on one exchange functional. - default_value: 101 0.8040 0.2195149727645171 - unit: "" - availability: "" - - name: xc_corr_ext - category: Electronic structure - type: Integer followed by Real values - description: | - Customized parameterization on the correlation part of XC functional. The first value should be the LibXC ID of the original functional, and latter values are external parameters. Default values are those of Perdew-Burke-Ernzerhof (PBE) functional. For more information on LibXC ID of functionals, please refer to LibXC. For parameters of functionals of interest, please refer to the source code of LibXC, such as PBE functional interface in LibXC: gga_c_pbe.c. - - [NOTE] Solely setting this keyword will take no effect on XC functionals. One should also set dft_functional to the corresponding functional to apply the customized parameterization. Presently this feature can only support parameterization on one correlation functional. - default_value: 130 0.06672455060314922 0.031090690869654895034 1.0 - unit: "" - availability: "" - - name: pseudo_rcut - category: Electronic structure - type: Real - description: | - Cut-off of radial integration for pseudopotentials. - default_value: "15" - unit: Bohr - availability: "" - - name: pseudo_mesh - category: Electronic structure - type: Boolean - description: | - * 0: Use a mesh for radial integration of pseudopotentials. - * 1: Use the mesh that is consistent with quantum espresso - default_value: "0" - unit: "" - availability: "" - - name: nspin - category: Electronic structure - type: Integer - description: | - The number of spin components of wave functions. - * 1: Spin degeneracy - * 2: Collinear spin polarized. - * 4: For the case of noncollinear polarized, nspin will be automatically set to 4 without being specified by the user. - default_value: "1" - unit: "" - availability: "" - - name: smearing_method - category: Electronic structure - type: String - description: | - It indicates which occupation and smearing method is used in the calculation. - * fixed: fixed occupations (available for non-coductors only) - * gauss or gaussian: Gaussian smearing method. - * mp: methfessel-paxton smearing method; recommended for metals. - * mp2: 2-nd methfessel-paxton smearing method; recommended for metals. - * mv or cold: marzari-vanderbilt smearing method. - * fd: Fermi-Dirac smearing method: and smearing_sigma below is the temperature (in Ry). - default_value: gauss - unit: "" - availability: "" - - name: smearing_sigma - category: Electronic structure - type: Real - description: | - Energy range for smearing. - default_value: "0.015" - unit: Ry - availability: "" - - name: smearing_sigma_temp - category: Electronic structure - type: Real - description: | - Energy range for smearing, smearing_sigma = 1/2 kB smearing_sigma_temp. - default_value: "2 * smearing_sigma / kB." - unit: K - availability: "" - - name: mixing_type - category: Electronic structure - type: String - description: | - Charge mixing methods. - * plain: Just simple mixing. - * pulay: Standard Pulay method. P. Pulay Chemical Physics Letters, (1980) - * broyden: Simplified modified Broyden method. D.D. Johnson Physical Review B (1988) - - In general, the convergence of the Broyden method is slightly faster than that of the Pulay method. - default_value: broyden - unit: "" - availability: "" - - name: mixing_beta - category: Electronic structure - type: Real - description: | - In general, the formula of charge mixing can be written as rho_new = rho_old + mixing_beta * drho, where rho_new represents the new charge density after charge mixing, rho_old represents the charge density in previous step, drho is obtained through various mixing methods, and mixing_beta is set by this parameter. A lower value of 'mixing_beta' results in less influence of drho on rho_new, making the self-consistent field (SCF) calculation more stable. However, it may require more steps to achieve convergence. We recommend the following options: - * 0.8: nspin=1 - * 0.4: nspin=2 and nspin=4 - * 0: keep charge density unchanged, usually used for restarting with init_chg=file or testing. - * 0.1 or less: if convergence of SCF calculation is difficult to reach, please try 0 < mixing_beta < 0.1. - A progressive tuning strategy might help, for example, 0.4 -> 0.1 -> 0.025. - - Note: For low-dimensional large systems, the setup of mixing_beta=0.1, mixing_ndim=20, and mixing_gg0=1.0 usually works well. - - For spin-polarized calculations (nspin=2 or nspin=4) that are difficult to converge, try reducing both mixing_beta and mixing_beta_mag simultaneously, e.g., mixing_beta=0.1 and mixing_beta_mag=0.1 or lower. - default_value: "0.8 for nspin=1, 0.4 for nspin=2 and nspin=4." - unit: "" - availability: "" - - name: mixing_beta_mag - category: Electronic structure - type: Real - description: | - Mixing parameter of magnetic density. - - If SCF convergence is difficult with spin polarization (nspin=2 or nspin=4), try reducing both mixing_beta and mixing_beta_mag simultaneously, e.g., mixing_beta=0.1 and mixing_beta_mag=0.1 or lower. - default_value: "4*mixing_beta, but the maximum value is 1.6." - unit: "" - availability: "" - - name: mixing_ndim - category: Electronic structure - type: Integer - description: | - It indicates the mixing dimensions in Pulay or Broyden. Pulay and Broyden method use the density from previous mixing_ndim steps and do a charge mixing based on this density. - - For systems that are difficult to converge, one could try increasing the value of 'mixing_ndim' to enhance the stability of the self-consistent field (SCF) calculation. - default_value: "8" - unit: "" - availability: "" - - name: mixing_restart - category: Electronic structure - type: Real - description: | - If the density difference between input and output drho is smaller than mixing_restart, SCF will restart at next step which means SCF will restart by using output charge density from perivos iteration as input charge density directly, and start a new mixing. Notice that mixing_restart will only take effect once in one SCF. - default_value: "0" - unit: "" - availability: "" - - name: mixing_dmr - category: Electronic structure - type: Boolean - description: | - At n-th iteration which is calculated by drho= 0.0" - - name: mixing_gg0 - category: Electronic structure - type: Real - description: | - Whether to perfom Kerker scaling for charge density. - * >0: The high frequency wave vectors will be suppressed by multiplying a scaling factor. Setting mixing_gg0 = 1.0 is normally a good starting point. Kerker preconditioner will be automatically turned off if mixing_beta <= 0.1. - * 0: No Kerker scaling is performed. - - For systems that are difficult to converge, particularly metallic systems, enabling Kerker scaling may aid in achieving convergence. - default_value: "1.0" - unit: "" - availability: "" - - name: mixing_gg0_mag - category: Electronic structure - type: Real - description: | - Whether to perfom Kerker preconditioner of magnetic density. Note: we do not recommand to open Kerker preconditioner of magnetic density unless the system is too hard to converge. - default_value: "0.0" - unit: "" - availability: "" - - name: mixing_gg0_min - category: Electronic structure - type: Real - description: | - The minimum kerker coefficient. - default_value: "0.1" - unit: "" - availability: "" - - name: mixing_angle - category: Electronic structure - type: Real - description: | - Normal broyden mixing can give the converged result for a given magnetic configuration. If one is not interested in the energies of a given magnetic configuration but wants to determine the ground state by relaxing the magnetic moments' directions, one cannot rely on the standard Broyden mixing algorithm. To enhance the ability to find correct magnetic configuration for non-colinear calculations, ABACUS implements a promising mixing method proposed by J. Phys. Soc. Jpn. 82 (2013) 114706. Here, mixing_angle is the angle mixing parameter. In fact, only mixing_angle=1.0 is implemented currently. - * <=0: Normal broyden mixing - * >0: Angle mixing for the modulus with mixing_angle=1.0 - default_value: "-10.0" - unit: "" - availability: Only relevant for non-colinear calculations nspin=4. - - name: mixing_tau - category: Electronic structure - type: Boolean - description: | - Whether to mix the kinetic energy density. - * True: The kinetic energy density will also be mixed. It seems for general cases, SCF converges fine even without this mixing. However, if there is difficulty in converging SCF for meta-GGA, it might be helpful to turn this on. - * False: The kinetic energy density will not be mixed. - default_value: "False" - unit: "" - availability: Only relevant for meta-GGA calculations. - - name: mixing_dftu - category: Electronic structure - type: Boolean - description: | - Whether to mix the occupation matrices. - * True: The occupation matrices will also be mixed by plain mixing. From experience this is not very helpful if the +U calculation does not converge. - * False: The occupation matrices will not be mixed. - default_value: "False" - unit: "" - availability: Only relevant for DFT+U calculations. - - name: gamma_only - category: Electronic structure - type: Boolean - description: | - Whether to use gamma_only algorithm. - * 0: more than one k-point is used and the ABACUS is slower compared to the gamma only algorithm. - * 1: ABACUS uses gamma only, the algorithm is faster and you don't need to specify the k-points file. - - Note: If gamma_only is set to 1, the KPT file will be overwritten. So make sure to turn off gamma_only for multi-k calculations. - default_value: "0" - unit: "" - availability: Only used in localized orbitals set - - name: scf_nmax - category: Electronic structure - type: Integer - description: | - This variable indicates the maximal iteration number for electronic iterations. - default_value: "100" - unit: "" - availability: "" - - name: scf_thr - category: Electronic structure - type: Real - description: | - It's the density threshold for electronic iteration. It represents the charge density error between two sequential densities from electronic iterations. Usually for local orbitals, usually 1e-6 may be accurate enough. - default_value: "1.0e-9 (plane-wave basis), or 1.0e-7 (localized atomic orbital basis)." - unit: "Ry if scf_thr_type=1, dimensionless if scf_thr_type=2" - availability: "" - - name: scf_ene_thr - category: Electronic structure - type: Real - description: | - It's the energy threshold for electronic iteration. It represents the total energy error between two sequential densities from electronic iterations. - default_value: "-1.0. If the user does not set this parameter, it will not take effect." - unit: eV - availability: "" - - name: scf_thr_type - category: Electronic structure - type: Integer - description: | - Choose the calculation method of convergence criterion. - * 1: the criterion is defined in reciprocal space, which is used in SCF of PW basis with unit Ry. - * 2: the criterion is defined in real space, where is the number of electron, which is used in SCF of LCAO with unit dimensionless. - default_value: "1 (plane-wave basis), or 2 (localized atomic orbital basis)." - unit: "" - availability: "" - - name: scf_os_stop - category: Electronic structure - type: Boolean - description: | - For systems that are difficult to converge, the SCF process may exhibit oscillations in charge density, preventing further progress toward the specified convergence criteria and resulting in continuous oscillation until the maximum number of steps is reached; this greatly wastes computational resources. To address this issue, this function allows ABACUS to terminate the SCF process early upon detecting oscillations, thus reducing subsequent meaningless calculations. The detection of oscillations is based on the slope of the logarithm of historical drho values. To this end, Least Squares Method is used to calculate the slope of the logarithmically taken drho for the previous scf_os_ndim iterations. If the calculated slope is larger than scf_os_thr, stop the SCF. - - * 0: The SCF will continue to run regardless of whether there is oscillation or not. - * 1: If the calculated slope is larger than scf_os_thr, stop the SCF. - default_value: "false" - unit: "" - availability: "" - - name: scf_os_thr - category: Electronic structure - type: Real - description: | - The slope threshold to determine if the SCF is stuck in a charge density oscillation. If the calculated slope is larger than scf_os_thr, stop the SCF. - default_value: "-0.01" - unit: "" - availability: "" - - name: scf_os_ndim - category: Electronic structure - type: Integer - description: | - To determine the number of old iterations' drho used in slope calculations. - default_value: mixing_ndim - unit: "" - availability: "" - - name: sc_os_ndim - category: Electronic structure - type: Integer - description: | - To determine the number of old iterations to judge oscillation, it occured, more accurate lambda with DeltaSpin method would be calculated, only for PW base. - default_value: "5" - unit: "" - availability: "" - - name: lspinorb - category: Electronic structure - type: Boolean - description: | - Whether to consider spin-orbit coupling (SOC) effect in the calculation. - * True: Consider spin-orbit coupling effect. When enabled: - * nspin is automatically set to 4 (noncollinear spin representation) - * Symmetry is automatically disabled (SOC breaks inversion symmetry) - * Requires full-relativistic pseudopotentials with has_so=true in the UPF header - * False: Do not consider spin-orbit coupling effect. - * Common Error: "no soc upf used for lspinorb calculation" - ensure you are using full-relativistic pseudopotentials - default_value: "False" - unit: "" - availability: "" - - name: noncolin - category: Electronic structure - type: Boolean - description: | - Whether to allow non-collinear magnetic moments, where magnetization can point in arbitrary directions (x, y, z components) rather than being constrained to the z-axis. - * True: Allow non-collinear polarization. When enabled: - * nspin is automatically set to 4 - * Wave function dimension is doubled (npol=2), and the number of occupied states is doubled - * Charge density has 4 components (Pauli spin matrices) - * Cannot be used with gamma_only=true - * Can be combined with lspinorb=true for SOC effects with non-collinear magnetism - * False: Do not allow non-collinear polarization (magnetization constrained to z-axis). - * Relationship with lspinorb: - * noncolin=0, lspinorb=1: SOC with z-axis magnetism only (for non-magnetic materials with SOC) - * noncolin=1, lspinorb=0: Non-collinear magnetism without SOC - * noncolin=1, lspinorb=1: Both non-collinear magnetism and SOC - default_value: "False" - unit: "" - availability: "" - - name: soc_lambda - category: Electronic structure - type: Real - description: | - Modulates the strength of spin-orbit coupling effect. Sometimes, for some real materials, both scalar-relativistic and full-relativistic pseudopotentials cannot describe the exact spin-orbit coupling. Artificial modulation may help in such cases. - - soc_lambda, which has value range [0.0, 1.0], is used to modulate SOC effect: - * soc_lambda 0.0: Scalar-relativistic case (no SOC) - * soc_lambda 1.0: Full-relativistic case (full SOC) - * Intermediate values: Partial-relativistic SOC (interpolation between scalar and full) - - Use case: When experimental or high-level theoretical results suggest that the SOC effect is weaker or stronger than what full-relativistic pseudopotentials predict, you can adjust this parameter to match the target behavior. - default_value: "1.0" - unit: "" - availability: Only works when lspinorb=true - - name: dfthalf_type - category: Electronic structure - type: Integer - description: | - DFT-1/2 type: - * 0: DFT-1/2 is off. - * 1: Shell DFT-1/2 method is used. - default_value: "0" - unit: "" - availability: "" - - name: pw_diag_thr - category: Plane wave related variables - type: Real - description: | - Only used when you use ks_solver = cg/dav/dav_subspace/bpcg. It indicates the threshold for the first electronic iteration, from the second iteration the pw_diag_thr will be updated automatically. For nscf calculations with planewave basis set, pw_diag_thr should be <= 1e-3. - default_value: "0.01" - unit: "" - availability: "" - - name: diago_smooth_ethr - category: Plane wave related variables - type: Boolean - description: | - If TRUE, the smooth threshold strategy, which applies a larger threshold (10e-5) for the empty states, will be implemented in the diagonalization methods. (This strategy should not affect total energy, forces, and other ground-state properties, but computational efficiency will be improved.) If FALSE, the smooth threshold strategy will not be applied. - default_value: "false" - unit: "" - availability: "" - - name: use_k_continuity - category: Plane wave related variables - type: Boolean - description: | - If TRUE, the wavefunctions at k-point will be initialized from the converged wavefunctions at the nearest k-point, which can speed up the SCF convergence. Only works for PW basis. - default_value: "false" - unit: "" - availability: Used only for plane wave basis set. - - name: pw_diag_nmax - category: Plane wave related variables - type: Integer - description: | - Only useful when you use ks_solver = cg/dav/dav_subspace/bpcg. It indicates the maximal iteration number for cg/david/dav_subspace/bpcg method. - default_value: "50" - unit: "" - availability: "basis_type==pw, ks_solver==cg/dav/dav_subspace/bpcg" - - name: pw_diag_ndim - category: Plane wave related variables - type: Integer - description: | - Only useful when you use ks_solver = dav or ks_solver = dav_subspace. It indicates dimension of workspace(number of wavefunction packets, at least 2 needed) for the Davidson method. A larger value may yield a smaller number of iterations in the algorithm but uses more memory and more CPU time in subspace diagonalization. - default_value: "4" - unit: "" - availability: "" - - name: diago_cg_prec - category: Plane wave related variables - type: Integer - description: | - Preconditioner type for conjugate gradient diagonalization method. - default_value: "1" - unit: "" - availability: "" - - name: nb2d - category: System variables - type: Integer - description: | - In LCAO calculations, the Hamiltonian and overlap matrices are distributed across 2D processor grid. This parameter controls the 2D block size for distribution. - default_value: "0" - unit: "" - availability: "" - - name: lmaxmax - category: Numerical atomic orbitals related variables - type: Integer - description: | - If not equals to 2, then the maximum l channels on LCAO is set to lmaxmax. If 2, then the number of l channels will be read from the LCAO data sets. Normally no input should be supplied for this variable so that it is kept as its default. - default_value: "2." - unit: "" - availability: "" - - name: lcao_ecut - category: Numerical atomic orbitals related variables - type: Real - description: | - Energy cutoff (in Ry) for two-center integrals in LCAO. The two-center integration table are obtained via a k space integral whose upper limit is about sqrt(lcao_ecut). - default_value: ecutwfc - unit: "" - availability: "" - - name: lcao_dk - category: Numerical atomic orbitals related variables - type: Real - description: | - the interval of k points for two-center integrals. The two-center integration table are obtained via a k space integral on a uniform grid with spacing lcao_dk. - default_value: "0.01" - unit: Bohr - availability: "" - - name: lcao_dr - category: Numerical atomic orbitals related variables - type: Real - description: | - r spacing of the integration table of two-center integrals. - default_value: "0.01" - unit: Bohr - availability: "" - - name: lcao_rmax - category: Numerical atomic orbitals related variables - type: Real - description: | - Maximum distance for the two-center integration table. - default_value: "30" - unit: Bohr - availability: "" - - name: search_radius - category: Numerical atomic orbitals related variables - type: Real - description: | - Searching radius in finding the neighbouring atoms. By default the radius will be automatically determined by the cutoffs of orbitals and nonlocal beta projectors. - default_value: "-1" - unit: Bohr - availability: "" - - name: "bx" - category: Numerical atomic orbitals related variables - type: Integer - description: | - In the matrix operation of grid integral, bx/by/bz grids (in x, y, z directions) are treated as a whole as a matrix element. A different value will affect the calculation speed. The default is 0, which means abacus will automatically calculate these values. - default_value: "0" - unit: "" - availability: "" - - name: by - category: Numerical atomic orbitals related variables - type: Integer - description: | - In the matrix operation of grid integral, bx/by/bz grids (in x, y, z directions) are treated as a whole as a matrix element. A different value will affect the calculation speed. The default is 0, which means abacus will automatically calculate these values. - default_value: "0" - unit: "" - availability: "" - - name: bz - category: Numerical atomic orbitals related variables - type: Integer - description: | - In the matrix operation of grid integral, bx/by/bz grids (in x, y, z directions) are treated as a whole as a matrix element. A different value will affect the calculation speed. The default is 0, which means abacus will automatically calculate these values. - default_value: "0" - unit: "" - availability: "" - - name: elpa_num_thread - category: Numerical atomic orbitals related variables - type: Integer - description: | - Number of threads used in one elpa calculation. - - If the number is below 0 or 0 or beyond the max number of threads, all elpa calculation will be using all mpi threads - default_value: "-1" - unit: "" - availability: "" - - name: num_stream - category: Numerical atomic orbitals related variables - type: Integer - description: | - The number of CUDA streams used in LCAO calculations with GPU acceleration. - default_value: "4" - unit: "" - availability: "" - - name: bessel_nao_ecut - category: NAOs - type: String - description: | - "Energy cutoff" (in Ry) of spherical Bessel functions. The number of spherical Bessel functions that constitute the radial parts of NAOs is determined by sqrt(bessel_nao_ecut)*bessel_nao_rcut/. - default_value: ecutwfc - unit: "" - availability: "" - - name: bessel_nao_tolerence - category: NAOs - type: Real - description: | - Tolerance when searching for the zeros of spherical Bessel functions. - default_value: "1.0e-12" - unit: "" - availability: "" - - name: bessel_nao_rcut - category: NAOs - type: Vector of Real (N values) - description: | - Cutoff radius (in Bohr) and the common node of spherical Bessel functions used to construct the NAOs. - default_value: "6.0" - unit: "" - availability: "" - - name: bessel_nao_smooth - category: NAOs - type: Boolean - description: | - If True, NAOs will be smoothed near the cutoff radius. See bessel_nao_rcut and bessel_nao_sigma for parameters. - default_value: "True" - unit: "" - availability: "" - - name: bessel_nao_sigma - category: NAOs - type: Real - description: | - Smoothing range (in Bohr). See also bessel_nao_smooth. - default_value: "0.1" - unit: "" - availability: "" - - name: relax_method - category: Geometry relaxation - type: Vector of string - description: | - The methods to do geometry optimization. The available algorithms depend on the relax_new setting. - - First element (algorithm selection): - * cg: Conjugate gradient (CG) algorithm. Available for both relax_new = True (default, simultaneous optimization) and relax_new = False (nested optimization). See relax_new for implementation details. - * bfgs: Broyden–Fletcher–Goldfarb–Shanno (BFGS) quasi-Newton algorithm. Only available when relax_new = False. - * lbfgs: Limited-memory BFGS algorithm, suitable for large systems. Only available when relax_new = False. - * cg_bfgs: Mixed method starting with CG and switching to BFGS when force convergence reaches relax_cg_thr. Only available when relax_new = False. - * sd: Steepest descent algorithm. Only available when relax_new = False. Not recommended for production use. - * fire: Fast Inertial Relaxation Engine method, a molecular-dynamics-based relaxation algorithm. Use by setting calculation to md and md_type to fire. Ionic velocities must be set in STRU file. See fire for details. - - Second element (BFGS variant, only when first element is bfgs): - * 1: Traditional BFGS that updates the Hessian matrix B and then inverts it. - * 2 or omitted: Default BFGS that directly updates the inverse Hessian (recommended). - - [NOTE] In the 3.10-LTS version, the type of this parameter is std::string. It can be set to "cg", "bfgs", "cg_bfgs", "bfgs_trad", "lbfgs", "sd", "fire". - default_value: cg 1 - unit: "" - availability: "" - - name: relax_new - category: Geometry relaxation - type: Boolean - description: | - Controls which implementation of geometry relaxation to use. At the end of 2022, a new implementation of the Conjugate Gradient (CG) method was introduced for relax and cell-relax calculations, while the old implementation was kept for backward compatibility. - - - * True (default): Use the new CG implementation with the following features: - * Simultaneous optimization of ionic positions and cell parameters (for cell-relax) - * Line search algorithm for step size determination - * Only CG algorithm is available (relax_method must be cg) - * Supports advanced cell constraints: fixed_axes = "shape", "volume", "a", "b", "c", etc. - * Supports fixed_ibrav to maintain lattice type - * More efficient for variable-cell relaxation - * Step size controlled by relax_scale_force - - - False: Use the old implementation with the following features: - * Nested optimization procedure: ionic positions optimized first, then cell parameters (for cell-relax) - * Multiple algorithms available: cg, bfgs, lbfgs, sd, cg_bfgs - * Limited cell constraints: only fixed_axes = "volume" is supported - * Traditional approach with separate ionic and cell optimization steps - default_value: "True" - unit: "" - availability: "" - - name: relax_scale_force - category: Geometry relaxation - type: Real - description: | - The paramether controls the size of the first conjugate gradient step. A smaller value means the first step along a new CG direction is smaller. This might be helpful for large systems, where it is safer to take a smaller initial step to prevent the collapse of the whole configuration. - default_value: "0.5" - unit: "" - availability: Only used when relax_new set to True - - name: relax_nmax - category: Geometry relaxation - type: Integer - description: | - The maximal number of ionic iteration steps. If set to 0, the code performs a quick "dry run", stopping just after initialization. This is useful to check for input correctness and to have the summary printed. - default_value: "1 for SCF, 50 for relax and cell-relax calcualtions" - unit: "" - availability: "" - - name: relax_cg_thr - category: Geometry relaxation - type: Real - description: | - When relax_method is set to cg_bfgs, a mixed algorithm of conjugate gradient (CG) and Broyden–Fletcher–Goldfarb–Shanno (BFGS) is used. The ions first move according to the CG method, then switch to the BFGS method when the maximum force on atoms is reduced below this threshold. - default_value: "0.5" - unit: eV/Angstrom - availability: Only used when relax_new = False and relax_method = cg_bfgs - - name: force_thr - category: Geometry relaxation - type: Real - description: | - Threshold of the force convergence. The threshold is compared with the largest force among all of the atoms. The recommended value for using atomic orbitals is 0.04 eV/Angstrom (0.0016 Ry/Bohr). The parameter is equivalent to force_thr_ev except for the unit, you can choose either you like. - default_value: "0.001" - unit: Ry/Bohr (25.7112 eV/Angstrom) - availability: "" - - name: force_thr_ev - category: Geometry relaxation - type: Real - description: | - Threshold of the force convergence. The threshold is compared with the largest force among all of the atoms. The recommended value for using atomic orbitals is 0.04 eV/Angstrom (0.0016 Ry/Bohr). The parameter is equivalent to force_thr except for the unit. You may choose either you like. - default_value: "0.0257112" - unit: eV/Angstrom (0.03889 Ry/Bohr) - availability: "" - - name: force_zero_out - category: Geometry relaxation - type: Real - description: | - The atomic forces that are smaller than force_zero_out will be treated as zero. - default_value: "0.0" - unit: eV/Angstrom - availability: "" - - name: relax_bfgs_w1 - category: Geometry relaxation - type: Real - description: | - Controls the Wolfe condition for the Broyden–Fletcher–Goldfarb–Shanno (BFGS) algorithm used in geometry relaxation. This parameter sets the sufficient decrease condition (c1 in Wolfe conditions). For more information, see Phys. Chem. Chem. Phys., 2000, 2, 2177. - default_value: "0.01" - unit: "" - availability: Only used when relax_new = False and relax_method is bfgs or cg_bfgs - - name: relax_bfgs_w2 - category: Geometry relaxation - type: Real - description: | - Controls the Wolfe condition for the Broyden–Fletcher–Goldfarb–Shanno (BFGS) algorithm used in geometry relaxation. This parameter sets the curvature condition (c2 in Wolfe conditions). For more information, see Phys. Chem. Chem. Phys., 2000, 2, 2177. - default_value: "0.5" - unit: "" - availability: Only used when relax_new = False and relax_method is bfgs or cg_bfgs - - name: relax_bfgs_rmax - category: Geometry relaxation - type: Real - description: | - Maximum allowed total displacement of all atoms during geometry optimization. The sum of atomic displacements can increase during optimization steps but cannot exceed this value. - default_value: "0.8" - unit: Bohr - availability: Only used when relax_new = False and relax_method is bfgs or cg_bfgs - - name: relax_bfgs_rmin - category: Geometry relaxation - type: Real - description: | - Minimum allowed total displacement of all atoms. When the total atomic displacement falls below this value and force convergence is not achieved, the calculation will terminate. Note: This parameter is not used in the default BFGS algorithm (relax_method = bfgs 2 or bfgs). - default_value: "1e-5" - unit: Bohr - availability: Only used when relax_new = False and relax_method = bfgs 1 (traditional BFGS) - - name: relax_bfgs_init - category: Geometry relaxation - type: Real - description: | - Initial total displacement of all atoms in the first BFGS step. This sets the scale for the initial movement. - default_value: "0.5" - unit: Bohr - availability: Only used when relax_new = False and relax_method is bfgs or cg_bfgs - - name: stress_thr - category: Geometry relaxation - type: Real - description: | - The threshold of the stress convergence. The threshold is compared with the largest component of the stress tensor. - default_value: "0.5" - unit: kbar - availability: "" - - name: press1 - category: Geometry relaxation - type: Real - description: | - The external pressures along three axes. Positive input value is taken as compressive stress. - default_value: "0" - unit: kbar - availability: "" - - name: press2 - category: Geometry relaxation - type: Real - description: | - The external pressures along three axes. Positive input value is taken as compressive stress. - default_value: "0" - unit: kbar - availability: "" - - name: press3 - category: Geometry relaxation - type: Real - description: | - The external pressures along three axes. Positive input value is taken as compressive stress. - default_value: "0" - unit: kbar - availability: "" - - name: fixed_axes - category: Geometry relaxation - type: String - description: | - Specifies which cell degrees of freedom are fixed during variable-cell relaxation. The available options depend on the relax_new setting: - - When relax_new = True (default), all options are available: - * None: Default; all cell parameters can relax freely - * volume: Relaxation with fixed volume (allows shape changes) - * shape: Fix shape but allow volume changes (hydrostatic pressure only) - * a: Fix the a-axis lattice vector during relaxation - * b: Fix the b-axis lattice vector during relaxation - * c: Fix the c-axis lattice vector during relaxation - * ab: Fix both a and b axes during relaxation - * ac: Fix both a and c axes during relaxation - * bc: Fix both b and c axes during relaxation - - When relax_new = False, all options are now available: - * None: Default; all cell parameters can relax freely - * volume: Relaxation with fixed volume (allows shape changes). Volume is preserved by rescaling the lattice after each update. - * shape: Fix shape but allow volume changes (hydrostatic pressure only). Stress tensor is replaced with isotropic pressure. - * a, b, c, ab, ac, bc: Fix specific lattice vectors. Gradients for fixed vectors are set to zero. - - [NOTE] For VASP users, see the ISIF correspondence table in the geometry optimization documentation. Both implementations now support all constraint types. - default_value: None - unit: "" - availability: Only used when calculation is set to cell-relax - - name: fixed_ibrav - category: Geometry relaxation - type: Boolean - description: | - * True: the lattice type will be preserved during relaxation. The lattice vectors are reconstructed to match the specified Bravais lattice type after each update. - * False: No restrictions are exerted during relaxation in terms of lattice type - - [NOTE] Note: it is possible to use fixed_ibrav with fixed_axes, but please make sure you know what you are doing. For example, if we are doing relaxation of a simple cubic lattice (latname = "sc"), and we use fixed_ibrav along with fixed_axes = "volume", then the cell is never allowed to move and as a result, the relaxation never converges. When both are used, fixed_ibrav is applied first, then fixed_axes = "volume" rescaling is applied. - default_value: "False" - unit: "" - availability: Can be used with both relax_new = True and relax_new = False. A specific latname must be provided. - - name: fixed_atoms - category: Geometry relaxation - type: Boolean - description: | - * True: The direct coordinates of atoms will be preserved during variable-cell relaxation. - * False: No restrictions are exerted on positions of all atoms. However, users can still fix certain components of certain atoms by using the m keyword in STRU file. For the latter option, check the end of this instruction. - default_value: "False" - unit: "" - availability: "" - - name: md_type - category: Molecular dynamics - type: String - description: | - Control the algorithm to integrate the equation of motion for molecular dynamics (MD), see md.md in detail. - - * fire: a MD-based relaxation algorithm, named fast inertial relaxation engine. - * nve: NVE ensemble with velocity Verlet algorithm. - * nvt: NVT ensemble, see md_thermostat in detail. - * npt: Nose-Hoover style NPT ensemble, see md_pmode in detail. - * langevin: NVT ensemble with Langevin thermostat, see md_damp in detail. - * msst: MSST method, see msst_direction, msst_vel, msst_qmass, msst_vis, msst_tscale in detail. - default_value: nvt - unit: "" - availability: "" - - name: md_nstep - category: Molecular dynamics - type: Integer - description: | - The total number of molecular dynamics steps. - default_value: "10" - unit: "" - availability: "" - - name: md_dt - category: Molecular dynamics - type: Real - description: | - The time step used in molecular dynamics calculations. - default_value: "1.0" - unit: fs - availability: "" - - name: md_thermostat - category: Molecular dynamics - type: String - description: | - Specify the temperature control method used in NVT ensemble. - - * nhc: Nose-Hoover chain, see md_tfreq and md_tchain in detail. - * anderson: Anderson thermostat, see md_nraise in detail. - * berendsen: Berendsen thermostat, see md_nraise in detail. - * rescaling: velocity Rescaling method 1, see md_tolerance in detail. - * rescale_v: velocity Rescaling method 2, see md_nraise in detail. - * csvr: Canonical Sampling through Velocity Rescaling, see md_csvr_tau in detail. - default_value: nhc - unit: "" - availability: "" - - name: md_tfirst - category: Molecular dynamics - type: Real - description: | - The temperature used in molecular dynamics calculations. - - If md_tfirst is unset or less than zero, init_vel is autoset to be true. If init_vel is true, the initial temperature will be determined by the velocities read from STRU. In this case, if velocities are unspecified in STRU, the initial temperature is set to zero. - - If md_tfirst is set to a positive value and init_vel is true simultaneously, please make sure they are consistent, otherwise abacus will exit immediately. - - Note that md_tlast is only used in NVT/NPT simulations. If md_tlast is unset or less than zero, md_tlast is set to md_tfirst. If md_tlast is set to be different from md_tfirst, ABACUS will automatically change the temperature from md_tfirst to md_tlast. - default_value: No default - unit: K - availability: "" - - name: md_tlast - category: Molecular dynamics - type: Real - description: | - The temperature used in molecular dynamics calculations. - - If md_tfirst is unset or less than zero, init_vel is autoset to be true. If init_vel is true, the initial temperature will be determined by the velocities read from STRU. In this case, if velocities are unspecified in STRU, the initial temperature is set to zero. - - If md_tfirst is set to a positive value and init_vel is true simultaneously, please make sure they are consistent, otherwise abacus will exit immediately. - - Note that md_tlast is only used in NVT/NPT simulations. If md_tlast is unset or less than zero, md_tlast is set to md_tfirst. If md_tlast is set to be different from md_tfirst, ABACUS will automatically change the temperature from md_tfirst to md_tlast. - default_value: No default - unit: K - availability: "" - - name: md_prec_level - category: Molecular dynamics - type: Integer - description: | - Determine the precision level of variable-cell molecular dynamics calculations. - * 0: FFT grids do not change, only G vectors and K vectors are changed due to the change of lattice vector. This level is suitable for cases where the variation of the volume and shape is not large, and the efficiency is relatively higher. - * 2: FFT grids change per step. This level is suitable for cases where the variation of the volume and shape is large, such as the MSST method. However, accuracy comes at the cost of efficiency. - default_value: "0" - unit: "" - availability: "" - - name: md_restart - category: Molecular dynamics - type: Boolean - description: | - Control whether to restart molecular dynamics calculations and time-dependent density functional theory calculations. - * True: ABACUS will read in {md_step}, then read in the corresponding STRU_MD_suffix/STRU/ automatically. For tddft, ABACUS will also read in WFC_NAO_K${kpoint} of the last step (You need to set out_wfc_lcao=1 and out_app_flag=0 to obtain this file). - * False: ABACUS will start molecular dynamics calculations normally from the first step. - default_value: "False" - unit: "" - availability: "" - - name: md_restartfreq - category: Molecular dynamics - type: Integer - description: | - The output frequency of OUT.{suffix}/STRIU/, which are used to restart molecular dynamics calculations, see md_restart in detail. - default_value: "5" - unit: "" - availability: "" - - name: md_dumpfreq - category: Molecular dynamics - type: Integer - description: | - The output frequency of OUT.${suffix}/MD_dump in molecular dynamics calculations, which including the information of lattices and atoms. - default_value: "1" - unit: "" - availability: "" - - name: dump_force - category: Molecular dynamics - type: Boolean - description: | - Whether to output atomic forces into the file OUT.${suffix}/MD_dump. - default_value: "True" - unit: "" - availability: "" - - name: dump_vel - category: Molecular dynamics - type: Boolean - description: | - Whether to output atomic velocities into the file OUT.${suffix}/MD_dump. - default_value: "True" - unit: "" - availability: "" - - name: dump_virial - category: Molecular dynamics - type: Boolean - description: | - Whether to output lattice virials into the file OUT.${suffix}/MD_dump. - default_value: "True" - unit: "" - availability: "" - - name: md_seed - category: Molecular dynamics - type: Integer - description: | - The random seed to initialize random numbers used in molecular dynamics calculations. - * < 0: No srand() function is called. - * >= 0: The function srand(md_seed) is called. - default_value: "-1" - unit: "" - availability: "" - - name: md_tfreq - category: Molecular dynamics - type: Real - description: | - Control the frequency of temperature oscillations during the simulation. If it is too large, the temperature will fluctuate violently; if it is too small, the temperature will take a very long time to equilibrate with the atomic system. - - Note: It is a system-dependent empirical parameter, ranging from 1/(40*md_dt) to 1/(100*md_dt). An improper choice might lead to the failure of jobs. - default_value: 1/40/md_dt - unit: "" - availability: "" - - name: md_tchain - category: Molecular dynamics - type: Integer - description: | - Number of thermostats coupled with the particles in the NVT/NPT ensemble based on the Nose-Hoover style non-Hamiltonian equations of motion. - default_value: "1" - unit: "" - availability: "" - - name: md_pmode - category: Molecular dynamics - type: String - description: | - Determine the precision level of variable-cell molecular dynamics calculations. - * 0: FFT grids do not change, only G vectors and K vectors are changed due to the change of lattice vector. This level is suitable for cases where the variation of the volume and shape is not large, and the efficiency is relatively higher. - * 2: FFT grids change per step. This level is suitable for cases where the variation of the volume and shape is large, such as the MSST method. However, accuracy comes at the cost of efficiency. - default_value: iso - unit: "" - availability: "" - - name: ref_cell_factor - category: Molecular dynamics - type: Real - description: | - Construct a reference cell bigger than the initial cell. The reference cell has to be large enough so that the lattice vectors of the fluctuating cell do not exceed the reference lattice vectors during MD. Typically, 1.02 ~ 1.10 is sufficient. However, the cell fluctuations depend on the specific system and thermodynamic conditions. So users must test for a proper choice. This parameters should be used in conjunction with erf_ecut, erf_height, and erf_sigma. - default_value: "1.0" - unit: "" - availability: "" - - name: md_pcouple - category: Molecular dynamics - type: String - description: | - The coupled lattice vectors will scale proportionally in NPT ensemble based on the Nose-Hoover style non-Hamiltonian equations of motion. - * none: Three lattice vectors scale independently. - * xyz: Lattice vectors x, y, and z scale proportionally. - * xy: Lattice vectors x and y scale proportionally. - * xz: Lattice vectors x and z scale proportionally. - * yz: Lattice vectors y and z scale proportionally. - default_value: none - unit: "" - availability: "" - - name: md_pfirst - category: Molecular dynamics - type: Real - description: | - The target pressure used in NPT ensemble simulations, the default value of md_plast is md_pfirst. If md_plast is set to be different from md_pfirst, ABACUS will automatically change the target pressure from md_pfirst to md_plast. - default_value: "-1.0" - unit: kbar - availability: "" - - name: md_plast - category: Molecular dynamics - type: Real - description: | - The target pressure used in NPT ensemble simulations, the default value of md_plast is md_pfirst. If md_plast is set to be different from md_pfirst, ABACUS will automatically change the target pressure from md_pfirst to md_plast. - default_value: "-1.0" - unit: kbar - availability: "" - - name: md_pfreq - category: Molecular dynamics - type: Real - description: | - The frequency of pressure oscillations during the NPT ensemble simulation. If it is too large, the pressure will fluctuate violently; if it is too small, the pressure will take a very long time to equilibrate with the atomic system. - - Note: It is a system-dependent empirical parameter. An improper choice might lead to the failure of jobs. - default_value: 1/400/md_dt - unit: "" - availability: "" - - name: md_pchain - category: Molecular dynamics - type: Integer - description: | - The number of thermostats coupled with the barostat in the NPT ensemble based on the Nose-Hoover style non-Hamiltonian equations of motion. - default_value: "1" - unit: "" - availability: "" - - name: lj_rule - category: Molecular dynamics - type: Integer - description: | - The Lennard-Jones potential between two atoms equals: $\sigma_k\sigma(i,j)$ - default_value: "2" - unit: "" - availability: "" - - name: lj_eshift - category: Molecular dynamics - type: Boolean - description: | - It True, the LJ potential is shifted by a constant such that it is zero at the cut-off distance. - default_value: "False" - unit: "" - availability: "" - - name: lj_rcut - category: Molecular dynamics - type: Real - description: | - Cut-off radius for Leonard Jones potential, beyond which the interaction will be neglected. It can be a single value, which means that all pairs of atoms types share the same cut-off radius. Otherwise, it should be a multiple-component vector, containing values, see details in lj_rule. - default_value: No default - unit: Angstrom - availability: "" - - name: lj_epsilon - category: Molecular dynamics - type: Real - description: | - The vector representing the matrix for Leonard Jones potential. See details in lj_rule. - default_value: No default - unit: eV - availability: "" - - name: lj_sigma - category: Molecular dynamics - type: Real - description: | - The vector representing the matrix for Leonard Jones potential. See details in lj_rule. - default_value: No default - unit: Angstrom - availability: "" - - name: pot_file - category: Molecular dynamics - type: String - description: | - The filename of DP/NEP potential files, see md.md in detail. - default_value: graph.pb - unit: "" - availability: "" - - name: dp_rescaling - category: Molecular dynamics - type: Real - description: | - Rescaling factor to use a temperature-dependent DP. Energy, stress and force calculated by DP will be multiplied by this factor. - default_value: "1.0" - unit: "" - availability: esolver_type = dp. - - name: dp_fparam - category: Molecular dynamics - type: Real - description: | - The frame parameter for dp potential. The array size is dim_fparam, then all frames are assumed to be provided with the same fparam. - default_value: "{}" - unit: "" - availability: esolver_type = dp. - - name: dp_aparam - category: Molecular dynamics - type: Real - description: | - The atomic parameter for dp potential. The array size can be (1) natoms x dim_aparam, then all frames are assumed to be provided with the same aparam; (2) dim_aparam, then all frames and atoms are assumed to be provided with the same aparam. - default_value: "{}" - unit: "" - availability: esolver_type = dp. - - name: msst_direction - category: Molecular dynamics - type: Integer - description: | - The direction of the shock wave in the MSST method. - * 0: x direction - * 1: y direction - * 2: z direction - default_value: "2" - unit: "" - availability: "" - - name: msst_vel - category: Molecular dynamics - type: Real - description: | - The velocity of the shock wave in the MSST method. - default_value: "0.0" - unit: Angstrom/fs - availability: "" - - name: msst_vis - category: Molecular dynamics - type: Real - description: | - Artificial viscosity in the MSST method. - default_value: "0.0" - unit: "g/(mol*Angstrom*fs)" - availability: "" - - name: msst_tscale - category: Molecular dynamics - type: Real - description: | - The reduction percentage of the initial temperature used to compress volume in the MSST method. - default_value: "0.01" - unit: "" - availability: "" - - name: msst_qmass - category: Molecular dynamics - type: Real - description: | - Inertia of the extended system variable. You should set a number larger than 0. - default_value: No default - unit: "" - availability: "" - - name: md_damp - category: Molecular dynamics - type: Real - description: | - The damping parameter used to add fictitious force in the Langevin method. - default_value: "1.0" - unit: fs - availability: "" - - name: md_csvr_tau - category: Molecular dynamics - type: Real - description: | - The characteristic time scale for the CSVR (Canonical Sampling through Velocity Rescaling) thermostat. Larger values give weaker coupling, smaller values give stronger coupling. Recommended value: 100 * md_dt. - default_value: "100.0" - unit: fs - availability: md_thermostat = csvr - - name: md_tolerance - category: Molecular dynamics - type: Real - description: | - The temperature tolerance for velocity rescaling. Velocities are rescaled if the current and target temperature differ more than md_tolerance. - default_value: "100.0" - unit: K - availability: "" - - name: md_nraise - category: Molecular dynamics - type: Integer - description: | - * Anderson: The "collision frequency" parameter is given as 1/md_nraise. - * Berendsen: The "rise time" parameter is given in units of the time step: tau = md_nraise*md_dt, so md_dt/tau = 1/md_nraise. - * Rescale_v: Every md_nraise steps the current temperature is rescaled to the target temperature. - default_value: "1" - unit: "" - availability: "" - - name: cal_syns - category: Molecular dynamics - type: "Boolean [Integer](optional)" - description: | - Whether to calculate and output asynchronous overlap matrix for Hefei-NAMD interface. When enabled, calculates by computing overlap between basis functions at atomic positions from previous time step and current time step. The overlap is calculated by shifting atom positions backward by velocity x md_dt. Output file: OUT.*/syns_nao.csr in CSR format. - - * 0 or false: disable - * 1 or true: enable with default precision (8 digits) - * 1 5: enable with custom precision (5 digits) - - [NOTE] Only works with LCAO basis and molecular dynamics calculations. Requires atomic velocities. Output starts from the second MD step (istep > 0). - default_value: "False" - unit: "" - availability: "" - - name: dmax - category: Molecular dynamics - type: Real - description: | - The maximum displacement of all atoms in one step. This parameter is useful when cal_syns = True. - default_value: "0.01" - unit: bohr - availability: "" - - name: of_kinetic - category: "OFDFT: orbital free density functional theory" - type: String - description: | - Kinetic energy functional type: - * tf: Thomas-Fermi (TF) functional - * vw: von Weizsacker (vW) functional - * tf+: TF + vW functional - * wt: Wang-Teter (WT) functional - * ext-wt: Extended Wang-Teter functional - * xwm: XWM functional - * lkt: Luo-Karasiev-Trickey (LKT) functional - * ml: Machine learning KEDF - * mpn: MPN KEDF (automatically sets ml parameters) - * cpn5: CPN5 KEDF (automatically sets ml parameters) - default_value: wt - unit: "" - availability: OFDFT - - name: of_method - category: "OFDFT: orbital free density functional theory" - type: String - description: | - The optimization method used in OFDFT. - * cg1: Polak-Ribiere. Standard CG algorithm. - * cg2: Hager-Zhang (generally faster than cg1). - * tn: Truncated Newton algorithm. - default_value: tn - unit: "" - availability: OFDFT - - name: of_conv - category: "OFDFT: orbital free density functional theory" - type: String - description: | - Criterion used to check the convergence of OFDFT. - * energy: Total energy changes less than of_tole. - * potential: The norm of potential is less than of_tolp. - * both: Both energy and potential must satisfy the convergence criterion. - default_value: energy - unit: "" - availability: OFDFT - - name: of_tole - category: "OFDFT: orbital free density functional theory" - type: Real - description: | - Tolerance of the energy change for determining the convergence. - default_value: "2e-6" - unit: Ry - availability: OFDFT - - name: of_tolp - category: "OFDFT: orbital free density functional theory" - type: Real - description: | - Tolerance of potential for determining the convergence. - default_value: "1e-5" - unit: Ry - availability: OFDFT - - name: of_tf_weight - category: "OFDFT: orbital free density functional theory" - type: Real - description: | - Weight of TF KEDF (kinetic energy density functional). - default_value: "1.0" - unit: "" - availability: "OFDFT with of_kinetic=tf, tf+, wt, ext-wt, xwm" - - name: of_vw_weight - category: "OFDFT: orbital free density functional theory" - type: Real - description: | - Weight of vW KEDF (kinetic energy density functional). - default_value: "1.0" - unit: "" - availability: "OFDFT with of_kinetic=vw, tf+, wt, ext-wt, lkt, xwm" - - name: of_wt_alpha - category: "OFDFT: orbital free density functional theory" - type: Real - description: | - Parameter alpha of WT KEDF (kinetic energy density functional). - default_value: "" - unit: "" - availability: "OFDFT with of_kinetic=wt, ext-wt" - - name: of_wt_beta - category: "OFDFT: orbital free density functional theory" - type: Real - description: | - Parameter beta of WT KEDF (kinetic energy density functional). - default_value: "" - unit: "" - availability: "OFDFT with of_kinetic=wt, ext-wt" - - name: of_extwt_kappa - category: "OFDFT: orbital free density functional theory" - type: Real - description: | - Parameter kappa for EXT-WT KEDF. - default_value: "1.0 / (2.0 * std::pow(4./3., 1./3.) - 1.0)" - unit: "" - availability: OFDFT with of_kinetic=ext-wt - - name: of_wt_rho0 - category: "OFDFT: orbital free density functional theory" - type: Real - description: | - The average density of system. - default_value: "0.0" - unit: Bohr^-3 - availability: OFDFT with of_kinetic=wt - - name: of_hold_rho0 - category: "OFDFT: orbital free density functional theory" - type: Boolean - description: | - Whether to fix the average density rho0. - * True: rho0 will be fixed even if the volume of system has changed, it will be set to True automatically if of_wt_rho0 is not zero. - * False: rho0 will change if volume of system has changed. - default_value: "False" - unit: "" - availability: OFDFT with of_kinetic=wt - - name: of_lkt_a - category: "OFDFT: orbital free density functional theory" - type: Real - description: | - Parameter a of LKT KEDF (kinetic energy density functional). - default_value: "1.3" - unit: "" - availability: OFDFT with of_kinetic=lkt - - name: of_xwm_rho_ref - category: "OFDFT: orbital free density functional theory" - type: Real - description: | - Reference charge density for XWM kinetic energy functional. If set to 0, the program will use average charge density. - default_value: "0.0" - unit: "" - availability: OFDFT with of_kinetic=xwm - - name: of_xwm_kappa - category: "OFDFT: orbital free density functional theory" - type: Real - description: | - Parameter for XWM kinetic energy functional. See PHYSICAL REVIEW B 100, 205132 (2019) for optimal values. - default_value: "0.0" - unit: "" - availability: OFDFT with of_kinetic=xwm - - name: of_read_kernel - category: "OFDFT: orbital free density functional theory" - type: Boolean - description: | - Whether to read in the kernel file. - * True: The kernel of WT KEDF (kinetic energy density functional) will be filled from the file specified by of_kernel_file. - * False: The kernel of WT KEDF (kinetic energy density functional) will be filled from formula. - default_value: "False" - unit: "" - availability: OFDFT with of_kinetic=wt - - name: of_kernel_file - category: "OFDFT: orbital free density functional theory" - type: String - description: | - The name of WT kernel file. - default_value: WTkernel.txt - unit: "" - availability: OFDFT with of_read_kernel=True - - name: of_full_pw - category: "OFDFT: orbital free density functional theory" - type: Boolean - description: | - Whether to use full planewaves. - * True: Ecut will be ignored while collecting planewaves, so that all planewaves will be used in FFT. - * False: Only use the planewaves inside ecut, the same as KSDFT. - default_value: "True" - unit: "" - availability: OFDFT - - name: of_full_pw_dim - category: "OFDFT: orbital free density functional theory" - type: Integer - description: | - Specify the parity of FFT dimensions. - * 0: either odd or even. - * 1: odd only. - * 2: even only. - - Note: Even dimensions may cause slight errors in FFT. It should be ignorable in ofdft calculation, but it may make Cardinal B-spline interpolation unstable, so please set of_full_pw_dim = 1 if nbspline != -1. - default_value: "0" - unit: "" - availability: OFDFT with of_full_pw = True - - name: of_ml_gene_data - category: "ML-KEDF: machine learning based kinetic energy density functional for OFDFT" - type: Boolean - description: | - Controls the generation of machine learning training data. When enabled, training data in .npy format will be saved in the directory OUT.${suffix}/. - default_value: "False" - unit: "" - availability: Used only for KSDFT with plane wave basis - - name: of_ml_device - category: "ML-KEDF: machine learning based kinetic energy density functional for OFDFT" - type: String - description: | - Run Neural Network on GPU or CPU. - * cpu: CPU - * gpu: GPU - default_value: cpu - unit: "" - availability: OFDFT - - name: of_ml_feg - category: "ML-KEDF: machine learning based kinetic energy density functional for OFDFT" - type: Integer - description: | - The method to incorporate the Free Electron Gas (FEG) limit. - * 0: Do not incorporate the FEG limit. - * 1: Incorporate the FEG limit by translation. - * 3: Incorporate the FEG limit by nonlinear transformation using softplus function. - default_value: "0" - unit: "" - availability: OFDFT - - name: of_ml_nkernel - category: "ML-KEDF: machine learning based kinetic energy density functional for OFDFT" - type: Integer - description: | - Number of kernel functions. - default_value: "1" - unit: "" - availability: OFDFT - - name: of_ml_kernel - category: "ML-KEDF: machine learning based kinetic energy density functional for OFDFT" - type: Vector of Integer - description: | - Containing nkernel (see of_ml_nkernel) elements. The i-th element specifies the type of the i-th kernel function. - * 1: Wang-Teter kernel function. - * 2: Modified Yukawa function, and alpha is specified by of_ml_yukawa_alpha. - * 3: Truncated kinetic kernel (TKK), the file containing TKK is specified by of_ml_kernel_file. - default_value: "1" - unit: "" - availability: OFDFT - - name: of_ml_kernel_scaling - category: "ML-KEDF: machine learning based kinetic energy density functional for OFDFT" - type: Vector of Real - description: | - Containing nkernel (see of_ml_nkernel) elements. The i-th element specifies the RECIPROCAL of scaling parameter of the i-th kernel function. - default_value: "1.0" - unit: "" - availability: OFDFT - - name: of_ml_yukawa_alpha - category: "ML-KEDF: machine learning based kinetic energy density functional for OFDFT" - type: Vector of Real - description: | - Containing nkernel (see of_ml_nkernel) elements. The i-th element specifies the parameter alpha of i-th kernel function. ONLY used for Yukawa kernel function. - default_value: "1.0" - unit: "" - availability: OFDFT - - name: of_ml_kernel_file - category: "ML-KEDF: machine learning based kinetic energy density functional for OFDFT" - type: Vector of String - description: | - Containing nkernel (see of_ml_nkernel) elements. The i-th element specifies the file containing the i-th kernel function. ONLY used for TKK. - default_value: none - unit: "" - availability: OFDFT - - name: of_ml_gamma - category: "ML-KEDF: machine learning based kinetic energy density functional for OFDFT" - type: Boolean - description: | - Local descriptor: gamma = (rho / rho0)^(1/3). - default_value: "False" - unit: "" - availability: OFDFT - - name: of_ml_p - category: "ML-KEDF: machine learning based kinetic energy density functional for OFDFT" - type: Boolean - description: | - Semi-local descriptor: p = |nabla rho|^2 / [2 (3 pi^2)^(1/3) rho^(4/3)]^2. - default_value: "False" - unit: "" - availability: OFDFT - - name: of_ml_q - category: "ML-KEDF: machine learning based kinetic energy density functional for OFDFT" - type: Boolean - description: | - Semi-local descriptor: q = nabla^2 rho / [4 (3 pi^2)^(2/3) rho^(5/3)]. - default_value: "False" - unit: "" - availability: OFDFT - - name: of_ml_tanhp - category: "ML-KEDF: machine learning based kinetic energy density functional for OFDFT" - type: Boolean - description: | - Semi-local descriptor: tanhp = tanh(chi_p * p). - default_value: "False" - unit: "" - availability: OFDFT - - name: of_ml_tanhq - category: "ML-KEDF: machine learning based kinetic energy density functional for OFDFT" - type: Boolean - description: | - Semi-local descriptor: tanhq = tanh(chi_q * q). - default_value: "False" - unit: "" - availability: OFDFT - - name: of_ml_chi_p - category: "ML-KEDF: machine learning based kinetic energy density functional for OFDFT" - type: Real - description: | - Hyperparameter chi_p: tanhp = tanh(chi_p * p). - default_value: "1.0" - unit: "" - availability: OFDFT - - name: of_ml_chi_q - category: "ML-KEDF: machine learning based kinetic energy density functional for OFDFT" - type: Real - description: | - Hyperparameter chi_q: tanhq = tanh(chi_q * q). - default_value: "1.0" - unit: "" - availability: OFDFT - - name: of_ml_gammanl - category: "ML-KEDF: machine learning based kinetic energy density functional for OFDFT" - type: Vector of Integer - description: | - Containing nkernel (see of_ml_nkernel) elements. The i-th element controls the non-local descriptor gammanl defined by the i-th kernel function. - default_value: "0" - unit: "" - availability: OFDFT - - name: of_ml_pnl - category: "ML-KEDF: machine learning based kinetic energy density functional for OFDFT" - type: Vector of Integer - description: | - Containing nkernel (see of_ml_nkernel) elements. The i-th element controls the non-local descriptor pnl defined by the i-th kernel function. - default_value: "0" - unit: "" - availability: OFDFT - - name: of_ml_qnl - category: "ML-KEDF: machine learning based kinetic energy density functional for OFDFT" - type: Vector of Integer - description: | - Containing nkernel (see of_ml_nkernel) elements. The i-th element controls the non-local descriptor qnl defined by the i-th kernel function. - default_value: "0" - unit: "" - availability: OFDFT - - name: of_ml_xi - category: "ML-KEDF: machine learning based kinetic energy density functional for OFDFT" - type: Vector of Integer - description: | - Containing nkernel (see of_ml_nkernel) elements. The i-th element controls the non-local descriptor xi defined by the i-th kernel function. - default_value: "0" - unit: "" - availability: OFDFT - - name: of_ml_tanhxi - category: "ML-KEDF: machine learning based kinetic energy density functional for OFDFT" - type: Vector of Integer - description: | - Containing nkernel (see of_ml_nkernel) elements. The i-th element controls the non-local descriptor tanhxi defined by the i-th kernel function. - default_value: "0" - unit: "" - availability: OFDFT - - name: of_ml_tanhxi_nl - category: "ML-KEDF: machine learning based kinetic energy density functional for OFDFT" - type: Vector of Integer - description: | - Containing nkernel (see of_ml_nkernel) elements. The i-th element controls the non-local descriptor tanhxi_nl defined by the i-th kernel function. - default_value: "0" - unit: "" - availability: OFDFT - - name: of_ml_tanh_pnl - category: "ML-KEDF: machine learning based kinetic energy density functional for OFDFT" - type: Vector of Integer - description: | - Containing nkernel (see of_ml_nkernel) elements. The i-th element controls the non-local descriptor tanh_pnl defined by the i-th kernel function. - default_value: "0" - unit: "" - availability: OFDFT - - name: of_ml_tanh_qnl - category: "ML-KEDF: machine learning based kinetic energy density functional for OFDFT" - type: Vector of Integer - description: | - Containing nkernel (see of_ml_nkernel) elements. The i-th element controls the non-local descriptor tanh_qnl defined by the i-th kernel function. - default_value: "0" - unit: "" - availability: OFDFT - - name: of_ml_tanhp_nl - category: "ML-KEDF: machine learning based kinetic energy density functional for OFDFT" - type: Vector of Integer - description: | - Containing nkernel (see of_ml_nkernel) elements. The i-th element controls the non-local descriptor tanhp_nl defined by the i-th kernel function. - default_value: "0" - unit: "" - availability: OFDFT - - name: of_ml_tanhq_nl - category: "ML-KEDF: machine learning based kinetic energy density functional for OFDFT" - type: Vector of Integer - description: | - Containing nkernel (see of_ml_nkernel) elements. The i-th element controls the non-local descriptor tanhq_nl defined by the i-th kernel function. - default_value: "0" - unit: "" - availability: OFDFT - - name: of_ml_chi_xi - category: "ML-KEDF: machine learning based kinetic energy density functional for OFDFT" - type: Vector of Real - description: | - Containing nkernel (see of_ml_nkernel) elements. The i-th element specifies the hyperparameter chi_xi of non-local descriptor tanhxi defined by the i-th kernel function. - default_value: "1.0" - unit: "" - availability: OFDFT - - name: of_ml_chi_pnl - category: "ML-KEDF: machine learning based kinetic energy density functional for OFDFT" - type: Vector of Real - description: | - Containing nkernel (see of_ml_nkernel) elements. The i-th element specifies the hyperparameter chi_pnl of non-local descriptor tanh_pnl defined by the i-th kernel function. - default_value: "1.0" - unit: "" - availability: OFDFT - - name: of_ml_chi_qnl - category: "ML-KEDF: machine learning based kinetic energy density functional for OFDFT" - type: Vector of Real - description: | - Containing nkernel (see of_ml_nkernel) elements. The i-th element specifies the hyperparameter chi_qnl of non-local descriptor tanh_qnl defined by the i-th kernel function. - default_value: "1.0" - unit: "" - availability: OFDFT - - name: of_ml_local_test - category: "ML-KEDF: machine learning based kinetic energy density functional for OFDFT" - type: Boolean - description: | - FOR TEST. Read in the density, and output the F and Pauli potential. - default_value: "False" - unit: "" - availability: OFDFT - - name: ml_exx - category: "ML-KEDF: machine learning based kinetic energy density functional for OFDFT" - type: Boolean - description: | - Whether to use machine learning based exact exchange (ML-EXX). - default_value: "False" - unit: "" - availability: "" - - name: method_sto - category: Electronic structure (SDFT) - type: Integer - description: | - Different methods to do stochastic DFT - * 1: Calculate twice, this method cost less memory but is slower. - * 2: Calculate once but needs much more memory. This method is much faster. Besides, it calculates with a smaller nche_sto. However, when the memory is not enough, only method 1 can be used. - * other: use 2 - default_value: "2" - unit: "" - availability: esolver_type = sdft - - name: nbands_sto - category: Electronic structure (SDFT) - type: Integer or string - description: | - The number of stochastic orbitals - * > 0: Perform stochastic DFT. Increasing the number of bands improves accuracy and reduces stochastic errors; To perform mixed stochastic-deterministic DFT, you should set nbands, which represents the number of KS orbitals. - * 0: Perform Kohn-Sham DFT. - * all: All complete basis sets are used to replace stochastic orbitals with the Chebyshev method (CT), resulting in the same results as KSDFT without stochastic errors. - default_value: "256" - unit: "" - availability: esolver_type = sdft - - name: nche_sto - category: Electronic structure (SDFT) - type: Integer - description: | - Chebyshev expansion orders for stochastic DFT. - default_value: "100" - unit: "" - availability: esolver_type = sdft - - name: emin_sto - category: Electronic structure (SDFT) - type: Real - description: | - Trial energy to guess the lower bound of eigen energies of the Hamiltonian Operator. - default_value: "0.0" - unit: Ry - availability: esolver_type = sdft - - name: emax_sto - category: Electronic structure (SDFT) - type: Real - description: | - Trial energy to guess the upper bound of eigen energies of the Hamiltonian Operator. - default_value: "0.0" - unit: Ry - availability: esolver_type = sdft - - name: seed_sto - category: Electronic structure (SDFT) - type: Integer - description: | - The random seed to generate stochastic orbitals. - * >= 0: Stochastic orbitals have the form of exp(i*theta), where theta is a uniform distribution in [0, 2*pi). - * 0: the seed is decided by time(NULL). - * <= -1: Stochastic orbitals have the form of +1 or -1 with equal probability. - * -1: the seed is decided by time(NULL). - default_value: "0" - unit: "" - availability: esolver_type = sdft - - name: initsto_ecut - category: Electronic structure (SDFT) - type: Real - description: | - Stochastic wave functions are initialized in a large box generated by "4*initsto_ecut". initsto_ecut should be larger than ecutwfc. In this method, SDFT results are the same when using different cores. Besides, coefficients of the same G are the same when ecutwfc is rising to initsto_ecut. If it is smaller than ecutwfc, it will be turned off. - default_value: "0.0" - unit: Ry - availability: esolver_type = sdft - - name: initsto_freq - category: Electronic structure (SDFT) - type: Integer - description: | - Frequency (once each initsto_freq steps) to generate new stochastic orbitals when running md. - * positive integer: Update stochastic orbitals - * 0: Never change stochastic orbitals. - default_value: "0" - unit: "" - availability: esolver_type = sdft - - name: npart_sto - category: Electronic structure (SDFT) - type: Integer - description: | - Make memory cost to 1/npart_sto times of the previous one when running the post process of SDFT like DOS or conductivities. - default_value: "1" - unit: "" - availability: method_sto = 2 and out_dos = 1 or cal_cond = True - - name: deepks_out_labels - category: DeePKS - type: Integer - description: | - Print labels and descriptors for DeePKS in OUT.${suffix}. The names of these files start with "deepks". - * 0 : No output. - * 1 : Output intermediate files needed during DeePKS training. - * 2 : Output target labels for label preperation. The label files are named as deepks_.npy or deepks_.csr, where the units and formats are the same as label files .npy or .csr required for training, except that the first dimension (nframes) is excluded. System structrue files are also given in deepks_atom.npy and deepks_box.npy in the unit of Bohr, which means lattice_constant should be set to 1 when training. - - [NOTE] When deepks_out_labels equals 1, the path of a numerical descriptor (an orb file) is needed to be specified under the NUMERICAL_DESCRIPTOR tag in the STRU file. This is not needed when deepks_out_labels equals 2. - default_value: "0" - unit: "" - availability: Numerical atomic orbital basis - - name: deepks_out_freq_elec - category: DeePKS - type: Integer - description: | - When deepks_out_freq_elec is greater than 0, print labels and descriptors for DeePKS in OUT.${suffix}/DeePKS_Labels_Elec per deepks_out_freq_elec electronic iterations, with suffix _e* to distinguish different steps. Often used with deepks_out_labels equals 1. - default_value: "0" - unit: "" - availability: Numerical atomic orbital basis - - name: deepks_out_base - category: DeePKS - type: String - description: | - Print labels and descriptors calculated by base functional ( determined by deepks_out_base ) and target functional ( determined by dft_functional ) for DeePKS in per deepks_out_freq_elec electronic iterations. The SCF process, labels and descriptors output of the target functional are all consistent with those when the target functional is used alone. The only additional output under this configuration is the labels of the base functional. Often used with deepks_out_labels equals 1. - default_value: None - unit: "" - availability: Numerical atomic orbital basis and deepks_out_freq_elec is greater than 0 - - name: deepks_scf - category: DeePKS - type: Boolean - description: | - perform self-consistent field iteration in DeePKS method - - [NOTE] A trained, traced model file is needed. - default_value: "False" - unit: "" - availability: Numerical atomic orbital basis - - name: deepks_equiv - category: DeePKS - type: Boolean - description: | - whether to use equivariant version of DeePKS - - [NOTE] The equivariant version of DeePKS-kit is still under development, so this feature is currently only intended for internal usage. - default_value: "False" - unit: "" - availability: Numerical atomic orbital basis - - name: deepks_model - category: DeePKS - type: String - description: | - the path of the trained, traced neural network model file generated by deepks-kit - default_value: None - unit: "" - availability: Numerical atomic orbital basis and deepks_scf is true - - name: bessel_descriptor_lmax - category: DeePKS - type: Integer - description: | - the maximum angular momentum of the Bessel functions generated as the projectors in DeePKS - NOte: To generate such projectors, set calculation type to gen_bessel in ABACUS. See also calculation. - default_value: "2" - unit: "" - availability: gen_bessel calculation - - name: bessel_descriptor_ecut - category: DeePKS - type: String - description: | - energy cutoff of Bessel functions - default_value: same as ecutwfc - unit: Ry - availability: gen_bessel calculation - - name: bessel_descriptor_tolerence - category: DeePKS - type: Real - description: | - tolerance for searching the zeros of Bessel functions - default_value: "1.0e-12" - unit: "" - availability: gen_bessel calculation - - name: bessel_descriptor_rcut - category: DeePKS - type: Real - description: | - cutoff radius of Bessel functions - default_value: "6.0" - unit: Bohr - availability: gen_bessel calculation - - name: bessel_descriptor_smooth - category: DeePKS - type: Boolean - description: | - smooth the Bessel functions at radius cutoff - default_value: "False" - unit: "" - availability: gen_bessel calculation - - name: bessel_descriptor_sigma - category: DeePKS - type: Real - description: | - smooth parameter at the cutoff radius of projectors - default_value: "0.1" - unit: Bohr - availability: gen_bessel calculation - - name: deepks_bandgap - category: DeePKS - type: Integer - description: | - include bandgap label for DeePKS training - * 0: Don't include bandgap label - * 1: Include target bandgap label (see deepks_band_range for more details) - * 2: Include multiple bandgap label (see deepks_band_range for more details) - * 3: Used for systems containing H atoms. Here HOMO is defined as the max occupation except H atoms and the bandgap label is the energy between HOMO and (HOMO + 1) - default_value: "0" - unit: "" - availability: Numerical atomic orbital basis and deepks_scf is true - - name: deepks_band_range - category: DeePKS - type: "Integer*2" - description: | - The first value should not be larger than the second one and the meaning differs in different cases below - * deepks_bandgap is 1: Bandgap label is the energy between LUMO + deepks_band_range[0] and LUMO + deepks_band_range[1]. If not set, it will calculate energy between HOMO and LUMO states. - * deepks_bandgap is 2: Bandgap labels are energies between HOMO and all states in range [LUMO + deepks_band_range[0], LUMO + deepks_band_range[1]] (Thus there are deepks_band_range[1] - deepks_band_range[0] + 1 bandgaps in total). If HOMO is included in the setting range, it will be ignored since it will always be zero and has no valuable messages (deepks_band_range[1] - deepks_band_range[0] bandgaps in this case). NOTICE: The set range can be greater than, less than, or include the value of HOMO. In the bandgap label, we always calculate the energy of the state in the set range minus the energy of HOMO state, so the bandgap can be negative if the state is lower than HOMO. - default_value: "-1 0" - unit: "" - availability: "Numerical atomic orbital basis, deepks_scf is true, and deepks_bandgap is 1 or 2" - - name: deepks_v_delta - category: DeePKS - type: Integer - description: | - Include V_delta/V_delta_R (Hamiltonian in k/real space) label for DeePKS training. When deepks_out_labels is true and deepks_v_delta > 0 (k space), ABACUS will output deepks_hbase.npy, deepks_vdelta.npy and deepks_htot.npy(htot=hbase+vdelta). When deepks_out_labels is true and deepks_v_delta < 0 (real space), ABACUS will output deepks_hrtot.csr, deepks_hrdelta.csr. Some more files output for different settings. NOTICE: To match the unit Normally used in DeePKS, the unit of Hamiltonian in k space is Hartree. However, currently in R space the unit is still Ry. - * deepks_v_delta = 1: deepks_vdpre.npy, which is used to calculate V_delta during DeePKS training. - * deepks_v_delta = 2: deepks_phialpha.npy and deepks_gevdm.npy, which can be used to calculate deepks_vdpre.npy. A recommanded method for memory saving. - * deepks_v_delta = -1: deepks_vdrpre.npy, which is used to calculate V_delta_R during DeePKS training. - * deepks_v_delta = -2: deepks_phialpha_r.npy and deepks_gevdm.npy, which can be used to calculate deepks_vdrpre.npy. A recommanded method for memory saving. - default_value: "0" - unit: "" - availability: Numerical atomic orbital basis - - name: deepks_out_unittest - category: DeePKS - type: Boolean - description: | - generate files for constructing DeePKS unit test - - [NOTE] Not relevant when running actual calculations. When set to 1, ABACUS needs to be run with only 1 process. - default_value: "False" - unit: "" - availability: "" - - name: estep_per_md - category: "RT-TDDFT: Real-Time Time-Dependent Density Functional Theory" - type: Integer - description: | - The number of electronic propagation steps between two ionic steps. - default_value: "1" - unit: "" - availability: "" - - name: td_dt - category: "RT-TDDFT: Real-Time Time-Dependent Density Functional Theory" - type: Real - description: | - The time step used in electronic propagation. Setting td_dt will reset the value of md_dt to td_dt * estep_per_md. - default_value: md_dt / estep_per_md - unit: fs - availability: "" - - name: td_edm - category: "RT-TDDFT: Real-Time Time-Dependent Density Functional Theory" - type: Integer - description: | - Method to calculate the energy-density matrix, mainly affects the calculation of force and stress. - * 0: Using the original formula. - * 1: Using the formula for ground state (deprecated). Note that this usually does not hold if wave function is not the eigenstate of the Hamiltonian. - default_value: "0" - unit: "" - availability: "" - - name: td_print_eij - category: "RT-TDDFT: Real-Time Time-Dependent Density Functional Theory" - type: Real - description: | - Controls the printing of Hamiltonian matrix elements. - * < 0: Suppress all output. - * >= 0: Print only elements with either i or j exceeding td_print_eij. - default_value: "-1" - unit: Ry - availability: "" - - name: td_propagator - category: "RT-TDDFT: Real-Time Time-Dependent Density Functional Theory" - type: Integer - description: | - Methods of electronic propagation. - * 0: Crank-Nicolson, based on matrix inversion. - * 1: 4th-order Taylor expansion of exponential. - * 2: Enforced time-reversal symmetry (ETRS). - * 3: Crank-Nicolson, based on solving linear equation. - default_value: "0" - unit: "" - availability: "" - - name: td_vext - category: "RT-TDDFT: Real-Time Time-Dependent Density Functional Theory" - type: Boolean - description: | - * True: Add a laser-material interaction (external electric field). - * False: No external electric field. - default_value: "False" - unit: "" - availability: "" - - name: td_vext_dire - category: "RT-TDDFT: Real-Time Time-Dependent Density Functional Theory" - type: String - description: | - Specifies the direction(s) of the external electric field when td_vext is enabled. For example, td_vext_dire 1 2 indicates that external electric fields are applied to both the x and y directions simultaneously. Electric field parameters can also be written as strings. For example, td_gauss_phase 0 1.5707963 indicates that the Gaussian type electric fields in the x and y directions have a phase delay of pi/2. - * 1: The external field direction is along the x-axis. - * 2: The external field direction is along the y-axis. - * 3: The external field direction is along the z-axis. - default_value: "1" - unit: "" - availability: "" - - name: td_stype - category: "RT-TDDFT: Real-Time Time-Dependent Density Functional Theory" - type: Integer - description: | - Type of electric field in the space domain, i.e. the gauge of the electric field. - * 0: Length gauge. - * 1: Velocity gauge. - * 2: Hybrid gauge. See J. Chem. Theory Comput. 2025, 21, 3335-3341 for more information. - default_value: "0" - unit: "" - availability: "" - - name: td_ttype - category: "RT-TDDFT: Real-Time Time-Dependent Density Functional Theory" - type: String - description: | - Type of electric field in the time domain. - * 0: Gaussian type function. - * 1: Trapezoid type function. - * 2: Trigonometric type function. - * 3: Heaviside type function. - default_value: "0" - unit: "" - availability: "" - - name: td_tstart - category: "RT-TDDFT: Real-Time Time-Dependent Density Functional Theory" - type: Integer - description: | - The initial time step when the time-dependent electric field is activated. - default_value: "1" - unit: "" - availability: "" - - name: td_tend - category: "RT-TDDFT: Real-Time Time-Dependent Density Functional Theory" - type: Integer - description: | - The final time step when the time-dependent electric field is deactivated. The field remains active between td_tstart and td_tend. - default_value: "1000" - unit: "" - availability: "" - - name: td_lcut1 - category: "RT-TDDFT: Real-Time Time-Dependent Density Functional Theory" - type: Real - description: | - The lower bound of the interval in the length gauge RT-TDDFT, where the coordinate is the fractional coordinate. - default_value: "0.05" - unit: "" - availability: "" - - name: td_lcut2 - category: "RT-TDDFT: Real-Time Time-Dependent Density Functional Theory" - type: Real - description: | - The upper bound of the interval in the length gauge RT-TDDFT, where the coordinate is the fractional coordinate. - default_value: "0.95" - unit: "" - availability: "" - - name: td_gauss_freq - category: "RT-TDDFT: Real-Time Time-Dependent Density Functional Theory" - type: String - description: | - Frequency of the Gaussian type electric field. - default_value: "22.13" - unit: 1/fs - availability: "" - - name: td_gauss_phase - category: "RT-TDDFT: Real-Time Time-Dependent Density Functional Theory" - type: String - description: | - Phase of the Gaussian type electric field. - default_value: "0.0" - unit: "" - availability: "" - - name: td_gauss_sigma - category: "RT-TDDFT: Real-Time Time-Dependent Density Functional Theory" - type: String - description: | - Pulse width (standard deviation) of the Gaussian type electric field. - default_value: "30.0" - unit: fs - availability: "" - - name: td_gauss_t0 - category: "RT-TDDFT: Real-Time Time-Dependent Density Functional Theory" - type: String - description: | - Step number of the time center of the Gaussian type electric field. - default_value: "100" - unit: "" - availability: "" - - name: td_gauss_amp - category: "RT-TDDFT: Real-Time Time-Dependent Density Functional Theory" - type: String - description: | - Amplitude of the Gaussian type electric field. - default_value: "0.25" - unit: V/Angstrom - availability: "" - - name: td_trape_freq - category: "RT-TDDFT: Real-Time Time-Dependent Density Functional Theory" - type: String - description: | - Frequency of the trapezoid type electric field. - default_value: "1.60" - unit: 1/fs - availability: "" - - name: td_trape_phase - category: "RT-TDDFT: Real-Time Time-Dependent Density Functional Theory" - type: String - description: | - Phase of the trapezoid type electric field. - default_value: "0.0" - unit: "" - availability: "" - - name: td_trape_t1 - category: "RT-TDDFT: Real-Time Time-Dependent Density Functional Theory" - type: String - description: | - Step number of the time interval t1 of the trapezoid type electric field. - default_value: "1875" - unit: "" - availability: "" - - name: td_trape_t2 - category: "RT-TDDFT: Real-Time Time-Dependent Density Functional Theory" - type: String - description: | - Step number of the time interval t2 of the trapezoid type electric field. - default_value: "5625" - unit: "" - availability: "" - - name: td_trape_t3 - category: "RT-TDDFT: Real-Time Time-Dependent Density Functional Theory" - type: String - description: | - Step number of the time interval t3 of the trapezoid type electric field. - default_value: "7500" - unit: "" - availability: "" - - name: td_trape_amp - category: "RT-TDDFT: Real-Time Time-Dependent Density Functional Theory" - type: String - description: | - Amplitude of the trapezoid type electric field. - default_value: "2.74" - unit: V/Angstrom - availability: "" - - name: td_trigo_freq1 - category: "RT-TDDFT: Real-Time Time-Dependent Density Functional Theory" - type: String - description: | - Frequency 1 of the trigonometric type electric field. - default_value: "1.164656" - unit: 1/fs - availability: "" - - name: td_trigo_freq2 - category: "RT-TDDFT: Real-Time Time-Dependent Density Functional Theory" - type: String - description: | - Frequency 2 of the trigonometric type electric field. - default_value: "0.029116" - unit: 1/fs - availability: "" - - name: td_trigo_phase1 - category: "RT-TDDFT: Real-Time Time-Dependent Density Functional Theory" - type: String - description: | - Phase 1 of the trigonometric type electric field. - default_value: "0.0" - unit: "" - availability: "" - - name: td_trigo_phase2 - category: "RT-TDDFT: Real-Time Time-Dependent Density Functional Theory" - type: String - description: | - Phase 2 of the trigonometric type electric field. - default_value: "0.0" - unit: "" - availability: "" - - name: td_trigo_amp - category: "RT-TDDFT: Real-Time Time-Dependent Density Functional Theory" - type: String - description: | - Amplitude of the trigonometric type electric field. - default_value: "2.74" - unit: V/Angstrom - availability: "" - - name: td_heavi_t0 - category: "RT-TDDFT: Real-Time Time-Dependent Density Functional Theory" - type: String - description: | - Step number of the switch time of the Heaviside type electric field. - default_value: "100" - unit: "" - availability: "" - - name: td_heavi_amp - category: "RT-TDDFT: Real-Time Time-Dependent Density Functional Theory" - type: String - description: | - Amplitude of the Heaviside type electric field. - default_value: "1.0" - unit: V/Angstrom - availability: "" - - name: init_vecpot_file - category: "RT-TDDFT: Real-Time Time-Dependent Density Functional Theory" - type: Boolean - description: | - Initialize vector potential through file or not. - * True: Initialize vector potential from file At.dat (unit: a.u.). It consists of four columns, representing the step number and vector potential on each direction. - * False: Calculate vector potential by integrating the electric field. - default_value: "False" - unit: "" - availability: "" - - name: ocp - category: "RT-TDDFT: Real-Time Time-Dependent Density Functional Theory" - type: Boolean - description: | - * True: Fixes the band occupations based on the values specified in ocp_set. - * False: Does not fix the band occupations. - default_value: "False" - unit: "" - availability: "" - - name: ocp_set - category: "RT-TDDFT: Real-Time Time-Dependent Density Functional Theory" - type: String - description: | - If ocp is set to 1, ocp_set must be provided as a string specifying the occupation numbers for each band across all k-points. The format follows a space-separated pattern, where occupations are assigned sequentially to bands for each k-point. A shorthand notation Nx can be used to repeat a value x for N bands. - * Example: - 1 10*1 0 1 represents occupations for 13 bands, where the 12th band is fully unoccupied (0), and all others are occupied (1). - * For a system with multiple k-points, the occupations must be specified for all k-points, following their order in the output file kpoints (may lead to fractional occupations). - * Incorrect specification of ocp_set could lead to inconsistencies in electron counting, causing the calculation to terminate with an error. - default_value: None - unit: "" - availability: "" - - name: of_cd - category: "TDOFDFT: time dependent orbital free density functional theory" - type: Boolean - description: | - Added the current dependent(CD) potential. (https://doi.org/10.1103/PhysRevB.98.144302) - * True: Added the CD potential. - * False: Not added the CD potential. - default_value: "False" - unit: "" - availability: TDOFDFT - - name: of_mcd_alpha - category: "TDOFDFT: time dependent orbital free density functional theory" - type: Real - description: | - The value of the parameter alpha in modified CD potential method. mCDPotential=alpha*CDPotential (proposed in paper PhysRevB.98.144302) - default_value: "1.0" - unit: "" - availability: TDOFDFT - - name: xc_kernel - category: Linear Response TDDFT (Under Development Feature) - type: String - description: | - The exchange-correlation kernel used in the calculation. Currently supported: RPA, LDA, PBE, HSE, HF. - default_value: LDA - unit: "" - availability: "" - - name: lr_init_xc_kernel - category: Linear Response TDDFT (Under Development Feature) - type: "Vector of String (>=1 values)" - description: | - The method to initalize the xc kernel. - * "default": Calculate xc kernel from the ground-state charge density. - * "file": Read the xc kernel on grid from the provided files. The following words should be the paths of ".cube" files, where the first 1 (nspin==1) or 3 (nspin==2, namely spin-aa, spin-ab and spin-bb) will be read in. The parameter xc_kernel will be invalid. Now only LDA-type kernel is supported as the potential will be calculated by directly multiplying the transition density. - * "from_charge_file": Calculate fxc from the charge density read from the provided files. The following words should be the paths of ".cube" files, where the first nspin files will be read in. - default_value: "\"default\"" - unit: "" - availability: "" - - name: lr_solver - category: Linear Response TDDFT (Under Development Feature) - type: String - description: | - The method to solve the Casida equation in LR-TDDFT under Tamm-Dancoff approximation (TDA). - * dav/dav_subspace/cg: Construct and diagonalize the Hamiltonian matrix iteratively with Davidson/Non-ortho-Davidson/CG algorithm. - * lapack: Construct the full matrix and directly diagonalize with LAPACK. - * spectrum: Calculate absorption spectrum only without solving Casida equation. - default_value: dav - unit: "" - availability: "" - - name: lr_thr - category: Linear Response TDDFT (Under Development Feature) - type: Real - description: | - The convergence threshold of iterative diagonalization solver for LR-TDDFT. It is a pure-math number with the same meaning as pw_diag_thr, but since the Casida equation is a one-shot eigenvalue problem, it is also the convergence threshold of LR-TDDFT. - default_value: "1e-2" - unit: "" - availability: "" - - name: nocc - category: Linear Response TDDFT (Under Development Feature) - type: Integer - description: | - The number of occupied orbitals (up to HOMO) used in the LR-TDDFT calculation. - * Note: If the value is illegal ( > nelec/2 or <= 0), it will be autoset to nelec/2. - default_value: nband - unit: "" - availability: "" - - name: nvirt - category: Linear Response TDDFT (Under Development Feature) - type: Integer - description: | - The number of virtual orbitals (starting from LUMO) used in the LR-TDDFT calculation. - default_value: "1" - unit: "" - availability: "" - - name: lr_nstates - category: Linear Response TDDFT (Under Development Feature) - type: Integer - description: | - The number of 2-particle states to be solved. - default_value: "0" - unit: "" - availability: "" - - name: lr_unrestricted - category: Linear Response TDDFT (Under Development Feature) - type: Boolean - description: | - Whether to use unrestricted construction for LR-TDDFT (the matrix size will be doubled). - * True: Always use unrestricted LR-TDDFT. - * False: Use unrestricted LR-TDDFT only when the system is open-shell. - default_value: "False" - unit: "" - availability: "" - - name: abs_wavelen_range - category: Linear Response TDDFT (Under Development Feature) - type: Real Real - description: | - The range of the wavelength for the absorption spectrum calculation. - default_value: 0.0 0.0 - unit: nm - availability: "" - - name: out_wfc_lr - category: Linear Response TDDFT (Under Development Feature) - type: Boolean - description: | - Whether to output the eigenstates (excitation energy) and eigenvectors (excitation amplitude) of the LR-TDDFT calculation. The output files are OUT.{suffix}/Excitation_Amplitude_${processor_rank}.dat. - default_value: "False" - unit: "" - availability: "" - - name: abs_gauge - category: Linear Response TDDFT (Under Development Feature) - type: String - description: | - Whether to use length or velocity gauge to calculate the absorption spectrum in LR-TDDFT. - default_value: length - unit: "" - availability: "" - - name: abs_broadening - category: Linear Response TDDFT (Under Development Feature) - type: Real - description: | - The broadening factor for the absorption spectrum calculation. - default_value: "0.01" - unit: "" - availability: "" - - name: out_freq_ion - category: Output information - type: Integer - description: | - Controls the output interval in ionic steps. When set to a positive integer, information such as charge density, local potential, electrostatic potential, Hamiltonian matrix, overlap matrix, density matrix, and Mulliken population analysis is printed every n ionic steps. - - [NOTE] In RT-TDDFT calculations, this parameter is inactive; output frequency is instead controlled by out_freq_td. - default_value: "0" - unit: "" - availability: "" - - name: out_freq_td - category: Output information - type: Integer - description: | - Controls the output interval in completed electronic evolution steps during RT-TDDFT calculations. When set to a positive integer n, detailed information (see out_freq_ion) is printed every n electron time-evolution steps (i.e., every STEP OF ELECTRON EVOLVE). For example, if you wish to output information once per ionic step, you should set out_freq_td equal to estep_per_md, since one ionic step corresponds to estep_per_md electronic evolution steps. - - [NOTE] This parameter is only active in RT-TDDFT mode (esolver_type = tddft). It has no effect in ground-state calculations. - default_value: "0" - unit: "" - availability: "" - - name: out_freq_elec - category: Output information - type: Integer - description: | - Output the charge density (only binary format, controlled by out_chg), wavefunction (controlled by out_wfc_pw) per out_freq_elec electronic iterations. Note that they are always output when converged or reach the maximum iterations scf_nmax. - default_value: scf_nmax - unit: "" - availability: "" - - name: out_chg - category: Output information - type: "Integer \\[Integer\\](optional)" - description: | - The first integer controls whether to output the charge density on real space grids: - - 1: Output the charge density (in Bohr^-3) on real space grids into the density files in the folder `OUT.${suffix}`. The files are named as: - - nspin = 1: `chg.cube`; - - nspin = 2: `chgs1.cube`, and `chgs2.cube`; - - nspin = 4: `chgs1.cube`, `chgs2.cube`, `chgs3.cube`, and `chgs4.cube`; - - When using the Meta-GGA functional, additional files containing the kinetic energy density are also output: - - nspin = 1: `tau.cube`; - - nspin = 2: `taus1.cube`, and `taus2.cube`; - - nspin = 4: `taus1.cube`, `taus2.cube`, `taus3.cube`, and `taus4.cube`; - - 2: On top of 1, also output the initial charge density files. The files are named as: - - out_freq_ion = 0: - - nspin = 1: `chg_ini.cube`; - - nspin = 2: `chgs1_ini.cube` and `chgs2_ini.cube`; - - nspin = 4: `chgs1_ini.cube`, `chgs2_ini.cube`, `chgs3_ini.cube`, and `chgs4_ini.cube`; - - output at every step (overwrite same file) - - out_freq_ion > 0: - - nspin = 1: `chgg{geom_step}_ini.cube` (e.g., `chgg1_ini.cube`); - - nspin = 2: `chgs1g{geom_step}_ini.cube` and `chgs2g{geom_step}_ini.cube`; - - nspin = 4: `chgs1g{geom_step}_ini.cube`, `chgs2g{geom_step}_ini.cube`, `chgs3g{geom_step}_ini.cube`, and `chgs4g{geom_step}_ini.cube`. - - output every out_freq_ion steps - Here, {geom_step} denotes the geometry step index, starting from 1 (geom_step = istep + 1). - - -1: Disable the charge density auto-back-up file `{suffix}-CHARGE-DENSITY.restart`, useful for large systems. - - The second integer controls the precision of the charge density output. If not given, `3` is used as default. For restarting from this file and other high-precision calculations, `10` is recommended. - - In molecular dynamics simulations, the output frequency is controlled by out_freq_ion. - - [NOTE] In the 3.10-LTS version, the file names are SPIN1_CHG.cube and SPIN1_CHG_INI.cube, etc. - default_value: 0 3 - unit: "" - availability: "" - - name: out_pot - category: Output information - type: "Integer \\[Integer\\](optional)" - description: | - * 1: Output the total local potential (i.e., local pseudopotential + Hartree potential + XC potential + external electric field (if exists) + dipole correction potential (if exists) + ...) on real space grids (in Ry) into files in the folder OUT.{suffix}. The files are named as: - * nspin = 1: pots1.cube; - * nspin = 2: pots1.cube and pots2.cube; - * nspin = 4: pots1.cube, pots2.cube, pots3.cube, and pots4.cube - * 2: Output the electrostatic potential on real space grids into OUT.{suffix}/pot_es.cube. The Python script named tools/02_postprocessing/average_pot/aveElecStatPot.py can be used to calculate the average electrostatic potential along the z-axis and outputs it into ElecStaticPot_AVE. Please note that the total local potential refers to the local component of the self-consistent potential, excluding the non-local pseudopotential. The distinction between the local potential and the electrostatic potential is as follows: local potential = electrostatic potential + XC potential. - * 3: Apart from 1, also output the total local potential of the initial charge density. The files are named as: - * out_freq_ion = 0: - * nspin = 1: `pot_ini.cube`; - * nspin = 2: `pots1_ini.cube` and `pots2_ini.cube`; - * nspin = 4: `pots1_ini.cube`, `pots2_ini.cube`, `pots3_ini.cube`, and `pots4_ini.cube`; - * output at every step (overwrite same file) - * out_freq_ion > 0: - * nspin = 1: `potg{geom_step}_ini.cube` (e.g., `potg1_ini.cube`); - * nspin = 2: `pots1g{geom_step}_ini.cube` and `pots2g{geom_step}_ini.cube`; - * nspin = 4: `pots1g{geom_step}_ini.cube`, `pots2g{geom_step}_ini.cube`, `pots3g{geom_step}_ini.cube`, and `pots4g{geom_step}_ini.cube`. - * output every out_freq_ion steps - Here, {geom_step} denotes the geometry step index, starting from 1 (geom_step = istep + 1). - - The optional second integer controls the output precision. If not provided, the default precision is 8. - - In molecular dynamics calculations, the output frequency is controlled by out_freq_ion. - - [NOTE] In the 3.10-LTS version, the file names are SPIN1_POT.cube and SPIN1_POT_INI.cube, etc. - default_value: "0" - unit: "" - availability: "" - - name: out_dmk - category: Output information - type: "Boolean \\[Integer\\](optional)" - description: | - Whether to output the density matrix for each k-point into files in the folder OUT.${suffix}. For current develop versions, out_dmk writes *_nao.txt files and includes a g{istep} index in the file name: - * For gamma only case: - * nspin = 1 and 4: dmg1_nao.txt; - * nspin = 2: dms1g1_nao.txt and dms2g1_nao.txt for the two spin channels. - * For multi-k points case: - * nspin = 1 and 4: dmk1g1_nao.txt, dmk2g1_nao.txt, ...; - * nspin = 2: dmk1s1g1_nao.txt... and dmk1s2g1_nao.txt... for the two spin channels. - - Here, g{istep} denotes the geometry/step index in the output file name. - - [NOTE] Version difference (develop vs 3.10-LTS): - * In develop, out_dmk supports both gamma-only and multi-k-point density-matrix output. - * In 3.10-LTS, the corresponding keyword is out_dm, and the output files are SPIN1_DM and SPIN2_DM, etc. - default_value: "False" - unit: "" - availability: Numerical atomic orbital basis - - name: out_dmr - category: Output information - type: "Boolean \\[Integer\\](optional)" - description: | - Whether to output the density matrix with Bravias lattice vector R index into files in the folder OUT.${suffix}. The files are named as dmr{s}{spin index}{g}{geometry index}{_nao} + {".csr"}. Here, 's' refers to spin, where s1 means spin up channel while s2 means spin down channel, and the sparse matrix format 'csr' is mentioned in out_mat_hs2. Finally, if out_app_flag is set to false, the file name contains the optional 'g' index for each ionic step that may have different geometries, and if out_app_flag is set to true, the density matrix with respect to Bravias lattice vector R accumulates during ionic steps: - * nspin = 1: dmrs1_nao.csr; - * nspin = 2: dmrs1_nao.csr and dmrs2_nao.csr for the two spin channels. - - [NOTE] In the 3.10-LTS version, the parameter is named out_dm1, and the file names are data-DMR-sparse_SPIN0.csr and data-DMR-sparse_SPIN1.csr, etc. - default_value: "False" - unit: "" - availability: Numerical atomic orbital basis (multi-k points) - - name: out_wfc_pw - category: Output information - type: Integer - description: | - Whether to output the electronic wavefunction coefficients into files and store them in the folder OUT.${suffix}. The files are named as wf{k}{k-point index}{s}{spin index}{g}{geometry index}{e}{electronic iteration index}{_pw} + {".txt"/".dat"}. Here, the s index refers to spin but the label will not show up for non-spin-polarized calculations, where s1 means spin up channel while s2 means spin down channel, and s4 refers to spinor wave functions that contains both spin channels with spin-orbital coupling or noncollinear calculations enabled. For scf or nscf calculations, g index will not appear, but the g index appears for geometry relaxation and molecular dynamics, where one can use the out_freq_ion command to control. To print out the electroinc wave functions every few SCF iterations, use the out_freq_elec command and the e index will appear in the file name. - * 0: no output - * 1: (txt format) - * non-gamma-only with nspin=1: wfk1_pw.txt, wfk2_pw.txt, ...; - * non-gamma-only with nspin=2: wfk1s1_pw.txt, wfk1s2_pw.txt, wfk2s1_pw.txt, wfk2s2_pw.txt, ...; - * non-gamma-only with nspin=4: wfk1s4_pw.txt, wfk2s4_pw.txt, ...; - * 2: (binary format) - * non-gamma-only with nspin=1: wfk1_pw.dat, wfk2_pw.dat, ...; - * non-gamma-only with nspin=2: wfk1s1_pw.dat, wfk1s2_pw.dat, wfk2s1_pw.dat, wfk2s2_pw.dat, ...; - * non-gamma-only with nspin=4: wfk1s4_pw.dat, wfk2s4_pw.dat, ...; - - [NOTE] In the 3.10-LTS version, the file names are WAVEFUNC1.dat, WAVEFUNC2.dat, etc. - default_value: "0" - unit: "" - availability: "Output electronic wave functions in plane wave basis, or transform the real-space electronic wave function into plane wave basis (see get_wf option in calculation with NAO basis)" - - name: out_wfc_lcao - category: Output information - type: Integer - description: | - Whether to output the electronic wavefunction coefficients into files and store them in the folder OUT.${suffix}. The files are named as wf{s}{spin index}{k(optional)}{k-point index}{g(optional)}{geometry index1}{_nao} + {".txt"/".dat"}. Here, 's' refers to spin, where s1 means spin up channel while s2 means spin down channel, and 's12' refer to spinor wave functions that contains both spin channels with spin-orbital coupling or noncollinear calculations enabled. In addition, if 'gamma_only' is set to 0, then the optinoal k-point sampling index appears with the k-point index attached to the electronic wave function file names. Finally, if out_app_flag is set to false, the file name contains the optional 'g' index for each ionic step that may have different geometries, and if out_app_flag is set to true, the wave functions accumulate during ionic steps. If the out_app_flag is set to false, a new folder named WFC will be created, and the wave function files will be saved into it. - * 0: no output - * 1: (txt format) - * gamma-only: wfs1_nao.txt or wfs2_nao.txt, ...; - * non-gamma-only: wfs1k1_nao.txt or wfs1k2_nao.txt, ...; - * 2: (binary format) - * gamma-only: wfs1_nao.dat or wfs2_nao.dat, ...; - * non-gamma-only: wfs1k1_nao.dat or wfs1k2_nao.dat, .... - - The corresponding sequence of the orbitals can be seen in Basis Set. - - Also controled by out_freq_ion and out_app_flag. - - [NOTE] In the 3.10-LTS version, the file names are WFC_NAO_GAMMA1_ION1.txt and WFC_NAO_K1_ION1.txt, etc. - default_value: "0" - unit: "" - availability: Numerical atomic orbital basis - - name: out_dos - category: Output information - type: Integer - description: | - Whether to output the density of states (DOS). For more information, refer to the dos.md. - * 0: no output - * 1: output the density of states (DOS) - * nspin=1 or 4: doss1g{geom}_{basis}.txt, where geom is the geometry index when cell changes or ions move while basis is either pw or nao. - * nspin=2: doss1g{geom}_{basis}.txt and doss2g{geom}_{basis}.txt for two spin channles. - * 2: (LCAO) output the density of states (DOS) and the projected density of states (PDOS) - * 3: output the Fermi surface file (fermi.bxsf) in BXSF format that can be visualized by XCrySDen - default_value: "0" - unit: "" - availability: "" - - name: out_ldos - category: Output information - type: "Integer \\[Integer\\](optional)" - description: | - Whether to output the local density of states (LDOS), optionally output precision can be set by a second parameter, default is 3. - * 0: no output - * 1: output the partial charge density for given bias (controlled by stm_bias) in cube file format, which can be used to plot scanning tunneling spectroscopys to mimick STM images using the Python script plot.py. - * 2: output LDOS along a line in real space (controlled by ldos_line). Parameters used to control DOS output are also valid for LDOS. - * 3: output both two LDOS modes above. - default_value: "0" - unit: "" - availability: "" - - name: out_band - category: Output information - type: "Boolean \\[Integer\\](optional)" - description: | - Whether to output the eigenvalues of the Hamiltonian matrix (in eV) into the running log during electronic iterations and into a file at the end of calculations. The former can be used with the 'out_freq_elec' parameter while the latter option allows the output precision to be set via a second parameter, with a default value of 8. The output file names are: - * nspin = 1 or 4: eig.txt; - * nspin = 2: eigs1.txt and eigs2.txt; - * For more information, refer to the band.md - default_value: "False" - unit: "" - availability: "" - - name: out_proj_band - category: Output information - type: Boolean - description: | - Whether to output the projected band structure. For more information, refer to the band.md - default_value: "False" - unit: "" - availability: "" - - name: out_stru - category: Output information - type: Boolean - description: | - Whether to output structure files per ionic step in geometry relaxation calculations into OUT.{istep}_D, where ${istep} is the ionic step. - default_value: "False" - unit: "" - availability: "" - - name: out_level - category: Output information - type: String - description: | - Control the output level of information in OUT.{calculation}.log. - * ie: electronic iteration level, which prints useful information for electronic iterations; - * i: geometry relaxation level, which prints some information for geometry relaxations additionally; - * m: molecular dynamics level, which does not print some information for simplicity. - default_value: ie - unit: "" - availability: "" - - name: out_mat_hs - category: Output information - type: "Boolean \\[Integer\\](optional)" - description: | - Whether to print the upper triangular part of the Hamiltonian matrices and overlap matrices for each k-point into files in the directory OUT.${suffix}. The second number controls precision. For more information, please refer to hs_matrix.md. Also controled by out_freq_ion and out_app_flag. - * For gamma only case: - * nspin = 1: hks1_nao.txt for the Hamiltonian matrix and sks1_nao.txt for the overlap matrix; - * nspin = 2: hks1_nao.txt and hks2_nao.txt for the Hamiltonian matrix and sks1_nao.txt for the overlap matrix. Note that the code will not output sks2_nao.txt because it is the same as sks1_nao.txt; - * nspin = 4: hks12_nao.txt for the Hamiltonian matrix and sks12_nao.txt for the overlap matrix. - * For multi-k points case: - * nspin = 1: hks1k1_nao.txt for the Hamiltonian matrix at the 1st k-point, and sks1k1_nao.txt for the overlap matrix for the 1st k-point, ...; - * nspin = 2: hks1k1_nao.txt and hks2k1_nao.txt for the two spin channels of the Hamiltonian matrix at the 1st k-point, and sks1k1_nao.txt for the overlap matrix for the 1st k-point. Note that the code will not output sks2k1_nao.txt because it is the same as sks1k1_nao.txt, ...; - * nspin = 4: hks12k1_nao.txt for the Hamiltonian matrix at the 1st k-point, and sks12k1_nao.txt for the overlap matrix for the 1st k-point, ...; - - [NOTE] In the 3.10-LTS version, the file names are data-0-H and data-0-S, etc. - default_value: False 8 - unit: Ry - availability: Numerical atomic orbital basis - - name: out_mat_hs2 - category: Output information - type: "Boolean \\[Integer\\](optional)" - description: | - Whether to print files containing the Hamiltonian matrix and overlap matrix into files in the directory OUT.${suffix}. For more information, please refer to hs_matrix.md. - - [NOTE] In the 3.10-LTS version, the file names are data-HR-sparse_SPIN0.csr and data-SR-sparse_SPIN0.csr, etc. - default_value: "False [8]" - unit: Ry - availability: Numerical atomic orbital basis (not gamma-only algorithm) - - name: out_mat_tk - category: Output information - type: "Boolean \\[Integer\\](optional)" - description: | - Whether to print the upper triangular part of the kinetic matrices for each k-point into OUT.${suffix}/tks1ki_nao.txt, where i is the index of k points. One may optionally provide a second parameter to specify the precision. - - [NOTE] In the 3.10-LTS version, the file names are data-TR-sparse_SPIN0.csr, etc. - default_value: "False [8]" - unit: Ry - availability: Numerical atomic orbital basis - - name: out_mat_r - category: Output information - type: "Boolean \\[Integer\\](optional)" - description: | - Whether to print the matrix representation of the position matrix into files named rxrs1_nao.csr, ryrs1_nao.csr, rzrs1_nao.csr in the directory OUT.${suffix}. The optional second parameter controls text output precision. If calculation is set to get_s, the position matrix can be obtained without scf iterations. For more information, please refer to position_matrix.md. - - [NOTE] In the 3.10-LTS version, the file name is data-rR-sparse.csr. - default_value: False 8 - unit: Bohr - availability: Numerical atomic orbital basis (not gamma-only algorithm) - - name: out_mat_t - category: Output information - type: "Boolean \\[Integer\\](optional)" - description: | - Generate files containing the kinetic energy matrix. The optional second parameter controls text output precision. The format will be the same as the Hamiltonian matrix and overlap matrix as mentioned in out_mat_hs2. The name of the files will be trs1_nao.csr and so on. Also controled by out_freq_ion and out_app_flag. - - [NOTE] In the 3.10-LTS version, the file name is data-TR-sparse_SPIN0.csr. - default_value: False 8 - unit: Ry - availability: Numerical atomic orbital basis (not gamma-only algorithm) - - name: out_mat_dh - category: Output information - type: Integer - description: | - Whether to print files containing the derivatives of the Hamiltonian matrix. The format will be the same as the Hamiltonian matrix and overlap matrix as mentioned in out_mat_hs2. The name of the files will be dhrxs1_nao.csr, dhrys1_nao.csr, dhrzs1_nao.csr and so on. Also controled by out_freq_ion and out_app_flag. - - Format: [precision] [iat1 iat2 ...]. The first value (0/1) enables/disables output. The second optional value sets the output precision (default: 8). Starting from the third value, 1-based atom indices can be listed to restrict output to derivatives with respect to those specific atoms only; if no atom indices are given, all atoms are written. - - [NOTE] In the 3.10-LTS version, the file name is data-dHRx-sparse_SPIN0.csr and so on. - default_value: 0 8 - unit: Ry/Bohr - availability: Numerical atomic orbital basis (not gamma-only algorithm) - - name: out_mat_dh_t - category: Output information - type: Integer - description: | - Whether to print files containing the derivatives of the kinetic energy matrix dT/dR. - - See out_mat_dh for format details (enable, precision, atom indices). - default_value: 0 8 - unit: Ry/Bohr - availability: "" - - name: out_mat_dh_vl - category: Output information - type: Integer - description: | - Whether to print files containing the derivatives of the local pseudopotential matrix dV^L/dR. - - See out_mat_dh for format details. - default_value: 0 8 - unit: Ry/Bohr - availability: "" - - name: out_mat_dh_vnl - category: Output information - type: Integer - description: | - Whether to print files containing the derivatives of the nonlocal pseudopotential matrix dV^NL/dR. - - See out_mat_dh for format details. - default_value: 0 8 - unit: Ry/Bohr - availability: "" - - name: out_mat_dh_vh - category: Output information - type: Integer - description: | - Whether to print files containing the derivatives of the Hartree matrix dV^H/dR. - - See out_mat_dh for format details. - default_value: 0 8 - unit: Ry/Bohr - availability: "" - - name: out_mat_dh_vxc - category: Output information - type: Integer - description: | - Whether to print files containing the derivatives of the XC matrix dV^XC/dR. - - See out_mat_dh for format details. - default_value: 0 8 - unit: Ry/Bohr - availability: "" - - name: out_mat_dh_exx - category: Output information - type: Integer - description: | - Whether to print files containing the derivatives of the exact-exchange matrix dV^EXX/dR. - - See out_mat_dh for format details. - default_value: 0 8 - unit: Ry/Bohr - availability: "" - - name: out_mat_h_t - category: Output information - type: Integer - description: | - Whether to print files containing the kinetic energy matrix T(R) in CSR format. - - See out_mat_hs2 for format details. - default_value: 0 8 - unit: Ry - availability: "" - - name: out_mat_h_vnl - category: Output information - type: Integer - description: | - Whether to print files containing the nonlocal pseudopotential matrix Vnl(R) in CSR format. - - See out_mat_hs2 for format details. - default_value: 0 8 - unit: Ry - availability: "" - - name: out_mat_h_vl - category: Output information - type: Integer - description: | - Whether to print files containing the local pseudopotential matrix Vl(R) in CSR format. - - See out_mat_hs2 for format details. - default_value: 0 8 - unit: Ry - availability: "" - - name: out_mat_h_vh - category: Output information - type: Integer - description: | - Whether to print files containing the Hartree matrix Vh(R) in CSR format. - - See out_mat_hs2 for format details. - default_value: 0 8 - unit: Ry - availability: "" - - name: out_mat_h_vxc - category: Output information - type: Integer - description: | - Whether to print files containing the XC matrix Vxc(R) in CSR format. - - See out_mat_hs2 for format details. - default_value: 0 8 - unit: Ry - availability: "" - - name: out_mat_h_exx - category: Output information - type: Integer - description: | - Whether to print files containing the exact-exchange matrix Vexx(R) in CSR format. - - See out_mat_hs2 for format details. - default_value: 0 8 - unit: Ry - availability: "" - - name: out_mat_ds - category: Output information - type: "Boolean \\[Integer\\](optional)" - description: | - Whether to print files containing the derivatives of the overlap matrix. The optional second parameter controls text output precision. The format will be the same as the overlap matrix as mentioned in out_mat_dh. The name of the files will be dsxrs1_nao.csr and so on. Also controled by out_freq_ion and out_app_flag. This feature can be used with calculation get_s. - - [NOTE] In the 3.10-LTS version, the file name is data-dSRx-sparse_SPIN0.csr and so on. - default_value: False 8 - unit: Ry/Bohr - availability: Numerical atomic orbital basis (not gamma-only algorithm) - - name: out_mat_xc - category: Output information - type: Boolean - description: | - Whether to print the upper triangular part of the exchange-correlation matrices in Kohn-Sham orbital representation: for each k point into files in the directory OUT.i_nao.txt, where {suffix}/vxc_out.dat. If EXX is calculated, the local and EXX part of band energy will also be printed in OUT.{suffix}/vxc_exx_out.dat, respectively. All the vxc_out.dat files contains 3 integers (nk, nspin, nband) followed by nk*nspin*nband lines of energy Hartree and eV. - - [NOTE] In the 3.10-LTS version, the file name is k-$k-Vxc and so on. - default_value: "False" - unit: Ry - availability: Numerical atomic orbital (NAO) and NAO-in-PW basis - - name: out_mat_xc2 - category: Output information - type: "Boolean \\[Integer\\](optional)" - description: | - Whether to print the exchange-correlation matrices in numerical orbital representation: in CSR format in the directory OUT.${suffix}. The name of the files will be vxcrs1_nao.csr and so on. - - [NOTE] In the 3.10-LTS version, the file name is Vxc_R_spin$s and so on. - default_value: False 8 - unit: Ry - availability: Numerical atomic orbital (NAO) basis - - name: out_mat_l - category: Output information - type: "Boolean \\[Integer\\](optional)" - description: | - Whether to print the expectation value of the angular momentum operator , , and in the basis of the localized atomic orbitals. The files are named OUT.{suffix}_Lx.dat, OUT.{suffix}_Ly.dat, and OUT.{suffix}_Lz.dat. The second integer controls the precision of the output. - default_value: False 8 - unit: "" - availability: Numerical atomic orbital (NAO) basis - - name: out_xc_r - category: Output information - type: "Integer \\[Integer\\](optional)" - description: | - The first integer controls whether to output the exchange-correlation (in Bohr^-3) on real space grids using Libxc to folder OUT.${suffix}: - * 0: rho, amag, sigma, exc - * 1: vrho, vsigma - * 2: v2rho2, v2rhosigma, v2sigma2 - * 3: v3rho3, v3rho2sigma, v3rhosigma2, v3sigma3 - * 4: v4rho4, v4rho3sigma, v4rho2sigma2, v4rhosigma3, v4sigma4 The meaning of the files is presented in Libxc - - The second integer controls the precision of the charge density output, if not given, will use 3 as default. - - The circle order of the charge density on real space grids is: x is the outer loop, then y and finally z (z is moving fastest). - default_value: "-1 3" - unit: "" - availability: "" - - name: out_eband_terms - category: Output information - type: Boolean - description: | - Whether to print the band energy terms separately in the file OUT.{term}_out.dat. The terms include the kinetic, pseudopotential (local + nonlocal), Hartree and exchange-correlation (including exact exchange if calculated). - default_value: "False" - unit: "" - availability: Numerical atomic orbital basis - - name: out_hr_npz - category: Output information - type: Boolean - description: | - Whether to print Hamiltonian matrices H(R) in npz format. The output files are named output_HR0.npz, output_HR1.npz, and so on according to spin channel. This feature requires ABACUS to be built with CNPY. - default_value: "False" - unit: Ry - availability: Numerical atomic orbital basis (not gamma-only algorithm) - - name: out_hsr_npz - category: Output information - type: Boolean - description: | - Whether to print Hamiltonian matrices H(R) and overlap matrix S(R) in npz format. The output files are named output_SR.npz, output_HR0.npz, output_HR1.npz, and so on according to spin channel. This feature requires ABACUS to be built with CNPY. - default_value: "False" - unit: Ry - availability: Numerical atomic orbital basis (not gamma-only algorithm) - - name: out_dm_npz - category: Output information - type: Boolean - description: | - Whether to print density matrices DM(R) in npz format. The output files are named output_DM0.npz, output_DM1.npz, and so on according to spin channel. This feature requires ABACUS to be built with CNPY. - default_value: "False" - unit: "" - availability: Numerical atomic orbital basis (not gamma-only algorithm) - - name: out_mul - category: Output information - type: Boolean - description: | - Whether to print the Mulliken population analysis result into OUT.${suffix}/mulliken.txt. In molecular dynamics calculations, the output frequency is controlled by out_freq_ion. - default_value: "False" - unit: "" - availability: Numerical atomic orbital basis - - name: out_app_flag - category: Output information - type: Boolean - description: | - Whether to output r(R), H(R), S(R), T(R), dH(R), dS(R), and wfc matrices in an append manner during molecular dynamics calculations. Check input parameters out_mat_r, out_mat_hs2, out_mat_t, out_mat_dh, out_mat_hs and out_wfc_lcao for more information. - default_value: "true" - unit: "" - availability: Numerical atomic orbital basis (not gamma-only algorithm) - - name: out_ndigits - category: Output information - type: Integer - description: | - Controls the length of decimal part of output data, such as charge density, Hamiltonian matrix, Overlap matrix and so on. - default_value: "8" - unit: "" - availability: out_mat_hs 1 case presently. - - name: out_element_info - category: Output information - type: Boolean - description: | - Whether to print element information into files in the directory OUT.{element_label}, including pseudopotential and orbital information of the element (in atomic Ryberg units). - default_value: "False" - unit: "" - availability: "" - - name: restart_save - category: Output information - type: Boolean - description: | - Whether to save charge density files per ionic step, which are used to restart calculations. According to the value of read_file_dir: - * auto: These files are saved in folder OUT.{read_file_dir}/restart/. - - If EXX(exact exchange) is calculated (i.e. dft_fuctional==hse/hf/pbe0/scan0 or rpa==True), the Hexx(R) files for each processor will also be saved in the above folder, which can be read in EXX calculation with restart_load==True. - default_value: "False" - unit: "" - availability: Numerical atomic orbital basis - - name: rpa - category: Output information - type: Boolean - description: | - Generate output files used in rpa calculations. - - [NOTE] If symmetry is set to 1, additional files containing the necessary information for exploiting symmetry in the subsequent rpa calculation will be output: irreducible_sector.txt, symrot_k.txt and symrot_R.txt. - default_value: "False" - unit: "" - availability: "" - - name: out_pchg - category: Output information - type: String - description: | - Specifies the electronic states to calculate the charge densities with state index for, using a space-separated string of 0s and 1s. Each digit in the string corresponds to a state, starting from the first state. A 1 indicates that the charge density should be calculated for that state, while a 0 means the state will be ignored. The parameter allows a compact and flexible notation (similar to ocp_set), for example the syntax 1 4*0 5*1 0 is used to denote the selection of states: 1 means calculate for the first state, 4*0 skips the next four states, 5*1 means calculate for the following five states, and the final 0 skips the next state. It's essential that the total count of states does not exceed the total number of states (nbands); otherwise, it results in an error, and the process exits. The input string must contain only numbers and the asterisk (*) for repetition, ensuring correct format and intention of state selection. The outputs comprise multiple .cube files following the naming convention pchgi[state]s[spin]k[kpoint].cube. - default_value: none - unit: "" - availability: "For both PW and LCAO. When basis_type = lcao, used when calculation = get_pchg." - - name: out_wfc_norm - category: Output information - type: String - description: | - Specifies the electronic states to calculate the real-space wave function modulus (norm, or known as the envelope function) with state index. The syntax and state selection rules are identical to out_pchg, but the output is the norm of the wave function. The outputs comprise multiple .cube files following the naming convention wfi[state]s[spin]k[kpoint].cube. - default_value: none - unit: "" - availability: "For both PW and LCAO. When basis_type = lcao, used when calculation = get_wf." - - name: out_wfc_re_im - category: Output information - type: String - description: | - Specifies the electronic states to calculate the real and imaginary parts of the wave function with state index. The syntax and state selection rules are identical to out_pchg, but the output contains both the real and imaginary components of the wave function. The outputs comprise multiple .cube files following the naming convention wfi[state]s[spin]k[kpoint][re/im].cube. - default_value: none - unit: "" - availability: "For both PW and LCAO. When basis_type = lcao, used when calculation = get_wf." - - name: if_separate_k - category: Output information - type: Boolean - description: | - Specifies whether to write the partial charge densities for all k-points to individual files or merge them. Warning: Enabling symmetry may produce unwanted results due to reduced k-point weights and symmetry operations in real space. Therefore when calculating partial charge densities, if you are not sure what you want exactly, it is strongly recommended to set symmetry = -1. It is noteworthy that your symmetry setting should remain the same as that in the SCF procedure. - default_value: "false" - unit: "" - availability: "For both PW and LCAO. When basis_type = pw, used if out_pchg is set. When basis_type = lcao, used only when calculation = get_pchg and gamma_only = 0." - - name: out_elf - category: Output information - type: "Integer \\[Integer\\](optional)" - description: | - Whether to output the electron localization function (ELF) in the folder `OUT.${suffix}`. The files are named as - * nspin = 1: - * elftot.cube: ${\rm{ELF}} = \frac{1}{1+\chi^2}$, $\chi = \frac{\frac{1}{2}\sum_{i}{f_i |\nabla\psi_{i}|^2} - \frac{|\nabla\rho|^2}{8\rho}}{\frac{3}{10}(3\pi^2)^{2/3}\rho^{5/3}}$; - * nspin = 2: - * elfs1.cube, elfs2.cube: ${\rm{ELF}}_\sigma = \frac{1}{1+\chi_\sigma^2}$, $\chi_\sigma = \frac{\frac{1}{2}\sum_{i}{f_i |\nabla\psi_{i,\sigma}|^2} - \frac{|\nabla\rho_\sigma|^2}{8\rho_\sigma}}{\frac{3}{10}(6\pi^2)^{2/3}\rho_\sigma^{5/3}}$; - * elftot.cube: ${\rm{ELF}} = \frac{1}{1+\chi^2}$, $\chi = \frac{\frac{1}{2}\sum_{i,\sigma}{f_i |\nabla\psi_{i,\sigma}|^2} - \sum_{\sigma}{\frac{|\nabla\rho_\sigma|^2}{8\rho_\sigma}}}{\sum_{\sigma}{\frac{3}{10}(6\pi^2)^{2/3}\rho_\sigma^{5/3}}}$; - * nspin = 4 (noncollinear): - * elftot.cube: ELF for total charge density, ${\rm{ELF}} = \frac{1}{1+\chi^2}$, $\chi = \frac{\frac{1}{2}\sum_{i}{f_i |\nabla\psi_{i}|^2} - \frac{|\nabla\rho|^2}{8\rho}}{\frac{3}{10}(3\pi^2)^{2/3}\rho^{5/3}}$ - - When `out_freq_ion > 0`, a geometry step suffix `g{#}` is appended to the file names (e.g., `elftotg1.cube`, `elfs1g1.cube`). - - The second integer controls the precision of the kinetic energy density output, if not given, will use 3 as default. For purpose restarting from this file and other high-precision involved calculation, recommend to use 10. - - In molecular dynamics calculations, the output frequency is controlled by out_freq_ion. - default_value: 0 3 - unit: "" - availability: Only for Kohn-Sham DFT and Orbital Free DFT. - - name: out_spillage - category: Output information - type: Integer - description: | - This output is only intentively needed by the ABACUS numerical atomic orbital generation workflow. This parameter is used to control whether to output the overlap integrals between truncated spherical Bessel functions (TSBFs) and plane-wave basis expanded wavefunctions (named as OVERLAP_Q), and between TSBFs (named as OVERLAP_Sq), also their first order derivatives. The output files are named starting with orb_matrix. A value of 2 would enable the output. - default_value: "0" - unit: "" - availability: Only for Kohn-Sham DFT with plane-wave basis. - - name: out_dipole - category: "RT-TDDFT: Real-Time Time-Dependent Density Functional Theory" - type: Boolean - description: | - * True: Output electric dipole moment. - * False: Do not output electric dipole moment. - default_value: "False" - unit: "" - availability: "" - - name: out_current - category: "RT-TDDFT: Real-Time Time-Dependent Density Functional Theory" - type: Integer - description: | - * 0: Do not output current. - * 1: Output current using the two-center integral, faster. - * 2: Output current using the matrix commutation, more precise. - default_value: "0" - unit: "" - availability: "" - - name: out_current_k - category: "RT-TDDFT: Real-Time Time-Dependent Density Functional Theory" - type: Boolean - description: | - * True: Output current for each k-points separately. - * False: Output current in total. - default_value: "False" - unit: "" - availability: "" - - name: out_efield - category: "RT-TDDFT: Real-Time Time-Dependent Density Functional Theory" - type: Boolean - description: | - Whether to output the electric field data to files. When enabled, writes real-time electric field values (unit: V/A) into files named efield_[num].txt, where [num] is the sequential index of the electric field ranges from 0 to N-1 for N configured fields. It is noteworthy that the field type sequence follows td_ttype, while the direction sequence follows td_vext_dire. - * True: Output electric field. - * False: Do not output electric field. - default_value: "False" - unit: "" - availability: "" - - name: out_vecpot - category: "RT-TDDFT: Real-Time Time-Dependent Density Functional Theory" - type: Boolean - description: | - Output vector potential or not (unit: a.u.). - * True: Output vector potential into file At.dat. - * False: Do not output vector potential. - default_value: "False" - unit: "" - availability: "" - - name: cal_symm_repr - category: System variables - type: "Integer \\[Integer\\](optional)" - description: | - Whether to print the matrix representation of symmetry operation to running log file. If the first value is given as 1, then all matrix representations will be printed. The second optional parameter controls the precision (number of digits) to print, default is 3, which is enough for a quick check. - default_value: 1 3 - unit: "" - availability: "" - - name: spillage_outdir - category: Input files - type: String - description: | - The directory to save the spillage files. - default_value: "\"./\"" - unit: "" - availability: Used only for plane wave basis set. - - name: dos_edelta_ev - category: Density of states - type: Real - description: | - The step size in writing Density of States (DOS) - default_value: "0.01" - unit: eV - availability: "" - - name: dos_sigma - category: Density of states - type: Real - description: | - The width of the Gaussian factor when obtaining smeared Density of States (DOS) - default_value: "0.07" - unit: eV - availability: "" - - name: dos_scale - category: Density of states - type: Real - description: | - Defines the energy range of DOS output as (emax-emin)*(1+dos_scale), centered at (emax+emin)/2. This parameter will be used when dos_emin and dos_emax are not set. - default_value: "0.01" - unit: eV - availability: "" - - name: dos_emin_ev - category: Density of states - type: Real - description: | - The minimal range for Density of States (DOS) - * If set, "dos_scale" will be ignored. - default_value: Minimal eigenenergy of - unit: eV - availability: "" - - name: dos_emax_ev - category: Density of states - type: Real - description: | - The maximal range for Density of States (DOS) - * If set, "dos_scale" will be ignored. - default_value: Maximal eigenenergy of - unit: eV - availability: "" - - name: dos_nche - category: Density of states - type: Integer - description: | - The order of Chebyshev expansions when using Stochastic Density Functional Theory (SDFT) to calculate DOS. - default_value: "100" - unit: "" - availability: "" - - name: stm_bias - category: Density of states - type: Real Real(optional) Integer(optional) - description: | - The bias voltage used to calculate local density of states to simulate scanning tunneling microscope, see details in out_ldos. When using three parameters: - - * The first parameter specifies the initial bias voltage value. - * The second parameter defines the voltage increment (step size between consecutive bias values). - * The third parameter determines the total number of voltage points - default_value: "1.0" - unit: V - availability: "" - - name: ldos_line - category: Density of states - type: "Real*6 Integer(optional)" - description: | - Specify the path of the three-dimensional space and display LDOS in the form of a two-dimensional color chart, see details in out_ldos. The first three paramenters are the direct coordinates of the start point, the next three paramenters are the direct coordinates of the end point, and the final one is the number of points along the path, whose default is 100. - default_value: 0.0 0.0 0.0 0.0 0.0 1.0 100 - unit: "" - availability: "" - - name: cal_cond - category: Electronic conductivities - type: Boolean - description: | - Whether to calculate electronic conductivities. - default_value: "False" - unit: "" - availability: basis_type = pw - - name: cond_che_thr - category: Electronic conductivities - type: Real - description: | - Control the error of Chebyshev expansions for conductivities. - default_value: "1e-8" - unit: "" - availability: esolver_type = sdft - - name: cond_dw - category: Electronic conductivities - type: Real - description: | - Frequency interval () for frequency-dependent conductivities. - default_value: "0.1" - unit: eV - availability: basis_type = pw - - name: cond_wcut - category: Electronic conductivities - type: Real - description: | - Cutoff frequency for frequency-dependent conductivities. - default_value: "10.0" - unit: eV - availability: basis_type = pw - - name: cond_dt - category: Electronic conductivities - type: Real - description: | - Time interval () to integrate Onsager coefficients. - default_value: "0.02" - unit: a.u. - availability: basis_type = pw - - name: cond_dtbatch - category: Electronic conductivities - type: Integer - description: | - exp(iH\dt\cond_dtbatch) is expanded with Chebyshev expansion to calculate conductivities. It is faster but costs more memory. - * If cond_dtbatch = 0: Autoset this parameter to make expansion orders larger than 100. - default_value: "0" - unit: "" - availability: esolver_type = sdft - - name: cond_smear - category: Electronic conductivities - type: Integer - description: | - Smearing method for conductivities - * 1: Gaussian smearing - * 2: Lorentzian smearing - default_value: "1" - unit: "" - availability: "" - - name: cond_fwhm - category: Electronic conductivities - type: Real - description: | - FWHM for conductivities. For Gaussian smearing, ; for Lorentzian smearing, . - default_value: "0.4" - unit: eV - availability: basis_type = pw - - name: cond_nonlocal - category: Electronic conductivities - type: Boolean - description: | - Whether to consider nonlocal potential correction when calculating velocity matrix . - * True: . - * False: . - default_value: "True" - unit: "" - availability: basis_type = pw - - name: berry_phase - category: Berry phase and wannier90 interface - type: Boolean - description: | - Controls the calculation of Berry phase - * true: Calculate Berry phase. - * false: Do not calculate Berry phase. - default_value: "false" - unit: "" - availability: "" - - name: gdir - category: Berry phase and wannier90 interface - type: Integer - description: | - The direction of the polarization in the lattice vector for Berry phase calculation - * 1: Calculate the polarization in the direction of the lattice vector a_1 defined in the STRU file. - * 2: Calculate the polarization in the direction of the lattice vector a_2 defined in the STRU file. - * 3: Calculate the polarization in the direction of the lattice vector a_3 defined in the STRU file. - default_value: "3" - unit: "" - availability: "" - - name: towannier90 - category: Berry phase and wannier90 interface - type: Boolean - description: | - Controls the generation of files for the Wannier90 code. - * 1: Generate files for the Wannier90 code. - * 0: Do not generate files for the Wannier90 code. - default_value: "0" - unit: "" - availability: "" - - name: nnkpfile - category: Berry phase and wannier90 interface - type: String - description: | - The file name generated when running "wannier90 -pp ..." command - default_value: seedname.nnkp - unit: "" - availability: "" - - name: wannier_method - category: Berry phase and wannier90 interface - type: Integer - description: | - Only available on LCAO basis, using different methods to generate "\.mmn" file and "\.amn" file. - * 1: Calculated using the lcao_in_pw method, the calculation accuracy can be improved by increasing ecutwfc to maintain consistency with the pw basis set results. - * 2: The overlap between atomic orbitals is calculated using grid integration. The radial grid points are generated using the Gauss-Legendre method, while the spherical grid points are generated using the Lebedev-Laikov method. - default_value: "1" - unit: "" - availability: "" - - name: wannier_spin - category: Berry phase and wannier90 interface - type: String - description: | - The spin direction for the Wannier function calculation when nspin is set to 2 - * up: Calculate spin up for the Wannier function. - * down: Calculate spin down for the Wannier function. - default_value: up - unit: "" - availability: "" - - name: out_wannier_mmn - category: Berry phase and wannier90 interface - type: Boolean - description: | - Write the "*.mmn" file or not. - * 0: don't write the "*.mmn" file. - * 1: write the "*.mmn" file. - default_value: "1" - unit: "" - availability: "" - - name: out_wannier_amn - category: Berry phase and wannier90 interface - type: Boolean - description: | - Write the "*.amn" file or not. - * 0: don't write the "*.amn" file. - * 1: write the "*.amn" file. - default_value: "1" - unit: "" - availability: "" - - name: out_wannier_eig - category: Berry phase and wannier90 interface - type: Boolean - description: | - Write the "*.eig" file or not. - * 0: don't write the "*.eig" file. - * 1: write the "*.eig" file. - default_value: "1" - unit: "" - availability: "" - - name: out_wannier_unk - category: Berry phase and wannier90 interface - type: Boolean - description: | - Write the "UNK.*" file or not. - * 0: don't write the "UNK.*" file. - * 1: write the "UNK.*" file. - default_value: "0" - unit: "" - availability: "" - - name: out_wannier_wvfn_formatted - category: Berry phase and wannier90 interface - type: Boolean - description: | - Write the "UNK.*" file in ASCII format or binary format. - * 0: write the "UNK.*" file in binary format. - * 1: write the "UNK.*" file in ASCII format (text file format). - default_value: "1" - unit: "" - availability: "" - - name: efield_flag - category: Electric field and dipole correction - type: Boolean - description: | - Added the electric field. - * True: A saw-like potential simulating an electric field is added to the bare ionic potential. - * False: Not added the electric field. - default_value: "False" - unit: "" - availability: "" - - name: dip_cor_flag - category: Electric field and dipole correction - type: Boolean - description: | - Added a dipole correction to the bare ionic potential. - * True: A dipole correction is also added to the bare ionic potential. - * False: A dipole correction is not added to the bare ionic potential. - - [NOTE] Note: If you do not want any electric field, the parameter efield_amp should be set to zero. This should ONLY be used in a slab geometry for surface calculations, with the discontinuity FALLING IN THE EMPTY SPACE. - default_value: "False" - unit: "" - availability: With dip_cor_flag = True and efield_flag = True. - - name: efield_dir - category: Electric field and dipole correction - type: Integer - description: | - The direction of the electric field or dipole correction is parallel to the reciprocal lattice vector, so the potential is constant in planes defined by FFT grid points, efield_dir can set to 0, 1 or 2. - * 0: parallel to the first reciprocal lattice vector - * 1: parallel to the second reciprocal lattice vector - * 2: parallel to the third reciprocal lattice vector - default_value: "2" - unit: "" - availability: with efield_flag = True. - - name: efield_pos_max - category: Electric field and dipole correction - type: Real - description: | - Position of the maximum of the saw-like potential along crystal axis efield_dir, within the unit cell, 0 <= efield_pos_max < 1. - default_value: Autoset to center of vacuum - width of vacuum / 20 - unit: "" - availability: with efield_flag = True. - - name: efield_pos_dec - category: Electric field and dipole correction - type: Real - description: | - Zone in the unit cell where the saw-like potential decreases, 0 < efield_pos_dec < 1. - default_value: Autoset to width of vacuum / 10 - unit: "" - availability: with efield_flag = True. - - name: efield_amp - category: Electric field and dipole correction - type: Real - description: | - Amplitude of the electric field. The saw-like potential increases with slope efield_amp in the region from efield_pos_max+efield_pos_dec-1) to (efield_pos_max), then decreases until (efield_pos_max+efield_pos_dec), in units of the crystal vector efield_dir. - - [NOTE] Note: The change of slope of this potential must be located in the empty region, or else unphysical forces will result. - default_value: "0.0" - unit: "a.u., 1 a.u. = 51.4220632*10^10 V/m." - availability: with efield_flag = True. - - name: gate_flag - category: Gate field (compensating charge) - type: Boolean - description: | - Controls the addition of compensating charge by a charged plate for charged cells. - * true: A charged plate is placed at the zgate position to add compensating charge. The direction is determined by efield_dir. - * false: No compensating charge is added. - default_value: "false" - unit: "" - availability: "" - - name: zgate - category: Gate field (compensating charge) - type: Real - description: | - Position of the charged plate in the unit cell - default_value: "0.5" - unit: Unit cell size - availability: "" - - name: block - category: Gate field (compensating charge) - type: Boolean - description: | - Controls the addition of a potential barrier to prevent electron spillover. - * true: A potential barrier is added from block_down to block_up with a height of block_height. If dip_cor_flag is set to true, efield_pos_dec is used to smoothly increase and decrease the potential barrier. - * false: No potential barrier is added. - default_value: "false" - unit: "" - availability: "" - - name: block_down - category: Gate field (compensating charge) - type: Real - description: | - Lower beginning of the potential barrier - default_value: "0.45" - unit: Unit cell size - availability: "" - - name: block_up - category: Gate field (compensating charge) - type: Real - description: | - Upper beginning of the potential barrier - default_value: "0.55" - unit: Unit cell size - availability: "" - - name: block_height - category: Gate field (compensating charge) - type: Real - description: | - Height of the potential barrier - default_value: "0.1" - unit: Rydberg - availability: "" - - name: imp_sol - category: Implicit solvation model - type: Boolean - description: | - Calculate implicit solvation correction - default_value: "False" - unit: "" - availability: "" - - name: eb_k - category: Implicit solvation model - type: Real - description: | - The relative permittivity of the bulk solvent, 80 for water - default_value: "80" - unit: "" - availability: imp_sol is true. - - name: tau - category: Implicit solvation model - type: Real - description: | - The effective surface tension parameter that describes the cavitation, the dispersion, and the repulsion interaction between the solute and the solvent which are not captured by the electrostatic terms - default_value: "1.0798e-05" - unit: "" - availability: "" - - name: sigma_k - category: Implicit solvation model - type: Real - description: | - The width of the diffuse cavity that is implicitly determined by the electronic structure of the solute - default_value: "0.6" - unit: "" - availability: "" - - name: nc_k - category: Implicit solvation model - type: Real - description: | - The value of the electron density at which the dielectric cavity forms - default_value: "0.00037" - unit: "" - availability: "" - - name: vdw_method - category: vdW correction - type: String - description: | - Specifies the method used for Van der Waals (VdW) correction. Available options are: - * d2: Grimme's D2 dispersion correction method - * d3_0: Grimme's DFT-D3(0) dispersion correction method (zero-damping) - * d3_bj: Grimme's DFTD3(BJ) dispersion correction method (BJ-damping) - * d4: Grimme's DFT-D4 dispersion correction method using the external DFT-D4 library - * none: no vdW correction - - [NOTE] ABACUS supports automatic setting of DFT-D3 parameters for common functionals. To benefit from this feature, please specify the parameter dft_functional explicitly, otherwise the autoset procedure will crash. If not satisfied with the built-in parameters, any manual setting on vdw_s6, vdw_s8, vdw_a1 and vdw_a2 will overwrite the automatic values. - default_value: none - unit: "" - availability: "" - - name: vdw_d4_xc - category: vdW correction - type: String - description: | - Functional name used to load DFT-D4 damping parameters from the DFT-D4 library. - If set to default, ABACUS infers the functional name from dft_functional or pseudopotential metadata. - default_value: default - unit: "" - availability: vdw_method is set to d4 - - name: vdw_d4_model - category: vdW correction - type: String - description: | - DFT-D4 dispersion model used by the external DFT-D4 library. - Available options are: - * d4: standard D4 model - * d4s: smooth D4S model - default_value: "d4" - unit: "" - availability: vdw_method is set to d4 - - name: vdw_s6 - category: vdW correction - type: String - description: | - This scale factor is used to optimize the interaction energy deviations in van der Waals (vdW) corrected calculations. The recommended values of this parameter are dependent on the chosen vdW correction method and the DFT functional being used. For DFT-D2, the recommended values are 0.75 (PBE), 1.2 (BLYP), 1.05 (B-P86), 1.0 (TPSS), and 1.05 (B3LYP). If not set, will use values of PBE functional. For DFT-D3, recommended values with different DFT functionals can be found on the here. If not set, will search in ABACUS built-in dataset based on the dft_functional keywords. User set value will overwrite the searched value. - default_value: "" - unit: "" - availability: "vdw_method is set to d2, d3_0, or d3_bj" - - name: vdw_s8 - category: vdW correction - type: String - description: | - This scale factor is relevant for D3(0) and D3(BJ) van der Waals (vdW) correction methods. The recommended values of this parameter with different DFT functionals can be found on the webpage. If not set, will search in ABACUS built-in dataset based on the dft_functional keywords. User set value will overwrite the searched value. - default_value: "" - unit: "" - availability: vdw_method is set to d3_0 or d3_bj - - name: vdw_a1 - category: vdW correction - type: String - description: | - This damping function parameter is relevant for D3(0) and D3(BJ) van der Waals (vdW) correction methods. The recommended values of this parameter with different DFT functionals can be found on the webpage. If not set, will search in ABACUS built-in dataset based on the dft_functional keywords. User set value will overwrite the searched value. - default_value: "" - unit: "" - availability: vdw_method is set to d3_0 or d3_bj - - name: vdw_a2 - category: vdW correction - type: String - description: | - This damping function parameter is only relevant for D3(0) and D3(BJ) van der Waals (vdW) correction methods. The recommended values of this parameter with different DFT functionals can be found on the webpage. If not set, will search in ABACUS built-in dataset based on the dft_functional keywords. User set value will overwrite the searched value. - default_value: "" - unit: "" - availability: vdw_method is set to d3_0 or d3_bj - - name: vdw_d - category: vdW correction - type: Real - description: | - Controls the damping rate of the damping function in the DFT-D2 method. - default_value: "20" - unit: "" - availability: vdw_method is set to d2 - - name: vdw_abc - category: vdW correction - type: Boolean - description: | - Determines whether three-body terms are calculated for DFT-D3 methods. - * True: ABACUS will calculate the three-body term. - * False: The three-body term is not included. - default_value: "False" - unit: "" - availability: vdw_method is set to d3_0 or d3_bj - - name: vdw_c6_file - category: vdW correction - type: String - description: | - Specifies the name of the file containing parameters for each element when using the D2 method. If not set, ABACUS uses the default parameters (Jnm6/mol) stored in the program. To manually set the parameters, provide a file containing the parameters. An example is given by: - - H 0.1 Si 9.0 - - Namely, each line contains the element name and the corresponding parameter. - default_value: default - unit: "" - availability: vdw_method is set to d2 - - name: vdw_c6_unit - category: vdW correction - type: String - description: | - Specifies the unit of the provided parameters in the D2 method. Available options are: - * Jnm6/mol (J nm^6/mol) - * eVA (eV Angstrom) - default_value: Jnm6/mol - unit: "" - availability: vdw_C6_file is not default - - name: vdw_r0_file - category: vdW correction - type: String - description: | - Specifies the name of the file containing parameters for each element when using the D2 method. If not set, ABACUS uses the default parameters (Angstrom) stored in the program. To manually set the parameters, provide a file containing the parameters. An example is given by: - - Li 1.0 Cl 2.0 - - Namely, each line contains the element name and the corresponding parameter. - default_value: default - unit: "" - availability: vdw_method is set to d2 - - name: vdw_r0_unit - category: vdW correction - type: String - description: | - Specifies the unit for the parameters in the D2 method when manually set by the user. Available options are: - * A (Angstrom) - * Bohr - default_value: "A" - unit: "" - availability: vdw_R0_file is not default - - name: vdw_cutoff_type - category: vdW correction - type: String - description: | - Determines the method used for specifying the cutoff radius in periodic systems when applying Van der Waals correction. Available options are: - * radius: The supercell is selected within a sphere centered at the origin with a radius defined by vdw_cutoff_radius. - * period: The extent of the supercell is explicitly specified using the vdw_cutoff_period keyword. - default_value: radius - unit: "" - availability: "" - - name: vdw_cutoff_radius - category: vdW correction - type: String - description: | - Defines the radius of the cutoff sphere when vdw_cutoff_type is set to radius. The default values depend on the chosen vdw_method. - default_value: "" - unit: defined by vdw_radius_unit (default Bohr) - availability: vdw_cutoff_type is set to radius - - name: vdw_radius_unit - category: vdW correction - type: String - description: | - Specify the unit of vdw_cutoff_radius. Available options are: - * A(Angstrom) - * Bohr - default_value: Bohr - unit: "" - availability: vdw_cutoff_type is set to radius - - name: vdw_cutoff_period - category: vdW correction - type: Integer Integer Integer - description: | - The three integers supplied here explicitly specify the extent of the supercell in the directions of the three basis lattice vectors. - default_value: 3 3 3 - unit: "" - availability: vdw_cutoff_type is set to period - - name: vdw_cn_thr - category: vdW correction - type: Real - description: | - The cutoff radius when calculating coordination numbers. - default_value: "40" - unit: "defined by vdw_cn_thr_unit (default: Bohr)" - availability: "vdw_method is set to d3_0, d3_bj, or d4" - - name: vdw_cn_thr_unit - category: vdW correction - type: String - description: | - Unit of the coordination number cutoff (vdw_cn_thr). Available options are: - * A(Angstrom) - * Bohr - default_value: Bohr - unit: "" - availability: "" - - name: exx_fock_alpha - category: Exact Exchange (Common) - type: Real - description: | - Fraction of full-ranged Fock exchange $1/r$ in range-separated hybrid functionals. - default_value: see hybrid_func_params - unit: "" - availability: "" - - name: exx_erfc_alpha - category: Exact Exchange (Common) - type: Real - description: | - Fraction of short-ranged Fock exchange $\mathrm{erfc}(\omega r)/r$ in range-separated hybrid functionals. - default_value: see hybrid_func_params - unit: "" - availability: "" - - name: exx_erfc_omega - category: Exact Exchange (Common) - type: Real - description: | - Range-separation parameter $\omega$ in the short-ranged Fock term $\mathrm{erfc}(\omega r)/r$. - default_value: see hybrid_func_params - unit: "" - availability: "" - - name: exx_separate_loop - category: Exact Exchange (Common) - type: Boolean - description: | - There are two types of iterative approaches provided by ABACUS to evaluate Fock exchange. - * False: Start with a GGA-Loop, and then Hybrid-Loop, in which EXX Hamiltonian is updated with electronic iterations. - * True: A two-step method is employed, i.e. in the inner iterations, density matrix is updated, while in the outer iterations, is calculated based on density matrix that converges in the inner iteration. - default_value: "True" - unit: "" - availability: "" - - name: exx_hybrid_step - category: Exact Exchange (Common) - type: Integer - description: | - The maximal iteration number of the outer-loop, where the Fock exchange is calculated - default_value: "100" - unit: "" - availability: exx_separate_loop==1 - - name: exx_mixing_beta - category: Exact Exchange (Common) - type: Real - description: | - Mixing parameter for densty matrix in each iteration of the outer-loop - default_value: "1.0" - unit: "" - availability: exx_separate_loop==1 - - name: exx_fock_lambda - category: Exact Exchange (LCAO in PW) - type: Real - description: | - It is used to compensate for divergence points at G=0 in the evaluation of Fock exchange using lcao_in_pw method. - default_value: "0.3" - unit: "" - availability: basis_type==lcao_in_pw - - name: exx_pca_threshold - category: Exact Exchange (LCAO) - type: Real - description: | - To accelerate the evaluation of four-center integrals (), the product of atomic orbitals are expanded in the basis of auxiliary basis functions (ABF): . The size of the ABF (i.e. number of ) is reduced using principal component analysis. When a large PCA threshold is used, the number of ABF will be reduced, hence the calculation becomes faster. However, this comes at the cost of computational accuracy. A relatively safe choice of the value is 1e-4. - default_value: "1E-4" - unit: "" - availability: "" - - name: exx_c_threshold - category: Exact Exchange (LCAO) - type: Real - description: | - See also the entry exx_pca_threshold. Smaller components (less than exx_c_threshold) of the matrix are neglected to accelerate calculation. The larger the threshold is, the faster the calculation and the lower the accuracy. A relatively safe choice of the value is 1e-4. - default_value: "1E-4" - unit: "" - availability: "" - - name: exx_cs_inv_thr - category: Exact Exchange (LCAO) - type: Real - description: | - By default, the Coulomb matrix inversion required for obtaining LRI coefficients is performed using LU decomposition. However, this approach may suffer from numerical instabilities when a large set of auxiliary basis functions (ABFs) is employed. When exx_cs_inv_thr > 0, the inversion is instead carried out via matrix diagonalization. Eigenvalues smaller than exx_cs_inv_thr are discarded to improve numerical stability. A relatively safe and commonly recommended value is 1e-5. - default_value: "-1" - unit: "" - availability: "" - - name: exx_v_threshold - category: Exact Exchange (LCAO) - type: Real - description: | - See also the entry exx_pca_threshold. With the approximation , the four-center integral in Fock exchange is expressed as , where is a double-center integral. Smaller values of the V matrix can be truncated to accelerate calculation. The larger the threshold is, the faster the calculation and the lower the accuracy. A relatively safe choice of the value is 0, i.e. no truncation. - default_value: "1E-1" - unit: "" - availability: "" - - name: exx_dm_threshold - category: Exact Exchange (LCAO) - type: Real - description: | - The Fock exchange can be expressed as where D is the density matrix. Smaller values of the density matrix can be truncated to accelerate calculation. The larger the threshold is, the faster the calculation and the lower the accuracy. A relatively safe choice of the value is 1e-4. - default_value: "1E-4" - unit: "" - availability: "" - - name: exx_c_grad_threshold - category: Exact Exchange (LCAO) - type: Real - description: | - See also the entry exx_pca_threshold. is used in force. Smaller components (less than exx_c_grad_threshold) of the matrix are neglected to accelerate calculation. The larger the threshold is, the faster the calculation and the lower the accuracy. A relatively safe choice of the value is 1e-4. - default_value: "1E-4" - unit: "" - availability: "" - - name: exx_v_grad_threshold - category: Exact Exchange (LCAO) - type: Real - description: | - See also the entry exx_pca_threshold. With the approximation , the four-center integral in Fock exchange is expressed as , where is a double-center integral. is used in force. Smaller values of the V matrix can be truncated to accelerate calculation. The larger the threshold is, the faster the calculation and the lower the accuracy. A relatively safe choice of the value is 0, i.e. no truncation. - default_value: "1E-1" - unit: "" - availability: "" - - name: exx_c_grad_r_threshold - category: Exact Exchange (LCAO) - type: Real - description: | - See also the entry exx_pca_threshold. is used in stress. Smaller components (less than exx_c_grad_r_threshold) of the matrix are neglected to accelerate calculation. The larger the threshold is, the faster the calculation and the lower the accuracy. A relatively safe choice of the value is 1e-4. - default_value: "1E-4" - unit: "" - availability: "" - - name: exx_v_grad_r_threshold - category: Exact Exchange (LCAO) - type: Real - description: | - See also the entry exx_pca_threshold. With the approximation , the four-center integral in Fock exchange is expressed as , where is a double-center integral. is used in force and stress. Smaller values of the V matrix can be truncated to accelerate calculation. The larger the threshold is, the faster the calculation and the lower the accuracy. A relatively safe choice of the value is 0, i.e. no truncation. - default_value: "1E-1" - unit: "" - availability: "" - - name: exx_ccp_rmesh_times - category: Exact Exchange (LCAO) - type: String - description: | - This parameter determines how many times larger the radial mesh required for calculating Columb potential is to that of atomic orbitals. The value should be larger than 0. Reducing this value can effectively increase the speed of self-consistent calculations using hybrid functionals. - default_value: "" - unit: "" - availability: "" - - name: exx_opt_orb_lmax - category: Exact Exchange (LCAO) - type: Integer - description: | - The maximum l of the spherical Bessel functions, when the radial part of opt-ABFs are generated as linear combinations of spherical Bessel functions. A reasonable choice is 2. - default_value: "0" - unit: "" - availability: calculation==gen_opt_abfs - - name: exx_opt_orb_ecut - category: Exact Exchange (LCAO) - type: Real - description: | - The cut-off of plane wave expansion, when the plane wave basis is used to optimize the radial ABFs. A reasonable choice is 60. - default_value: "0" - unit: Ry - availability: calculation==gen_opt_abfs - - name: exx_opt_orb_tolerence - category: Exact Exchange (LCAO) - type: Real - description: | - The threshold when solving for the zeros of spherical Bessel functions. A reasonable choice is 1e-12. - default_value: "1E-12" - unit: "" - availability: calculation==gen_opt_abfs - - name: exx_real_number - category: Exact Exchange (LCAO) - type: String - description: | - * True: Enforce LibRI to use double data type. - * False: Enforce LibRI to use complex data type. Setting it to True can effectively improve the speed of self-consistent calculations with hybrid functionals. - default_value: depends on the gamma_only option - unit: "" - availability: "" - - name: exx_singularity_correction - category: Exact Exchange (LCAO) - type: String - description: | - * spencer: see Phys. Rev. B 77, 193110 (2008). - * revised_spencer: see Phys. Rev. Mater. 5, 013807 (2021). Set the scheme of Coulomb singularity correction. - default_value: default - unit: "" - availability: "" - - name: rpa_ccp_rmesh_times - category: Exact Exchange (LCAO) - type: Real - description: | - How many times larger the radial mesh required is to that of atomic orbitals in the postprocess calculation of the bare Coulomb matrix for RPA, GW, etc. - default_value: "10" - unit: "" - availability: "" - - name: exx_symmetry_realspace - category: Exact Exchange (LCAO) - type: Boolean - description: | - * False: only rotate k-space density matrix D(k) from irreducible k-points to accelerate diagonalization - * True: rotate both D(k) and Hexx(R) to accelerate both diagonalization and EXX calculation - default_value: "True" - unit: "" - availability: symmetry==1 and exx calculation (dft_fuctional==hse/hf/pbe0/scan0 or rpa==True) - - name: out_ri_cv - category: Exact Exchange (LCAO) - type: Boolean - description: | - Whether to output the coefficient tensor C(R) and ABFs-representation Coulomb matrix V(R) for each atom pair and cell in real space. - default_value: "false" - unit: "" - availability: "" - - name: out_unshrinked_v - category: Exact Exchange (LCAO) - type: Boolean - description: | - Whether to output the large Vq matrix in the unshrinked auxiliary basis. - default_value: "false" - unit: "" - availability: "" - - name: exx_coul_moment - category: Exact Exchange (LCAO) - type: Boolean - description: | - Whether to use the moment method for Coulomb calculation. - default_value: "false" - unit: "" - availability: "" - - name: exx_rotate_abfs - category: Exact Exchange (LCAO) - type: Boolean - description: | - Whether to rotate the auxiliary basis for Coulomb calculation. - default_value: "false" - unit: "" - availability: "" - - name: exx_multip_moments_threshold - category: Exact Exchange (LCAO) - type: Real - description: | - Threshold to screen multipole moments in Coulomb calculation. - default_value: "1e-10" - unit: "" - availability: "" - - name: shrink_abfs_pca_thr - category: Exact Exchange (LCAO) - type: Real - description: | - Threshold to shrink the auxiliary basis for GW/RPA calculations. - default_value: "-1" - unit: "" - availability: "" - - name: shrink_lu_inv_thr - category: Exact Exchange (LCAO) - type: Real - description: | - Threshold for obtaining the inverse of the overlap matrix by LU decomposition in the auxiliary-basis representation. - default_value: "1e-6" - unit: "" - availability: "" - - name: dft_plus_u - category: DFT+U correction - type: Integer - description: | - Determines whether to calculate the plus U correction, which is especially important for correlated electrons. - * 1: Calculate plus U correction with radius-adjustable localized projections (with parameter onsite_radius). - * 2: Calculate plus U correction using first zeta of NAOs as projections (this is old method for testing). - * 0: Do not calculate plus U correction. - default_value: "0" - unit: "" - availability: "" - - name: dft_plus_dmft - category: DFT+U correction - type: Boolean - description: | - Whether to enable DFT+DMFT calculation. True: DFT+DMFT; False: standard DFT calculation. - default_value: "False" - unit: "" - availability: basis_type==lcao - - name: orbital_corr - category: DFT+U correction - type: Vector of Integer (n values where n is the number of atomic types) - description: | - Specifies which orbits need plus U correction for each atom type ( for atom type 1, 2, 3, respectively). - * -1: The plus U correction will not be calculated for this atom. - * 1: For p-electron orbits, the plus U correction is needed. - * 2: For d-electron orbits, the plus U correction is needed. - * 3: For f-electron orbits, the plus U correction is needed. - default_value: "-1" - unit: "" - availability: "" - - name: hubbard_u - category: DFT+U correction - type: Vector of Real (n values where n is the number of atomic types) - description: | - Specifies the Hubbard Coulomb interaction parameter U (eV) in plus U correction, which should be specified for each atom unless the Yukawa potential is used. - - [NOTE] Note: Since only the simplified scheme by Duradev is implemented, the 'U' here is actually U-effective, which is given by Hubbard U minus Hund J. - default_value: "0.0" - unit: "" - availability: "" - - name: yukawa_potential - category: DFT+U correction - type: Boolean - description: | - Determines whether to use the local screen Coulomb potential method to calculate the values of U and J. - * True: hubbard_u does not need to be specified. - * False: hubbard_u does need to be specified. - default_value: "False" - unit: "" - availability: "" - - name: yukawa_lambda - category: DFT+U correction - type: Real - description: | - The screen length of Yukawa potential. If left to default, the screen length will be calculated as an average of the entire system. It's better to stick to the default setting unless there is a very good reason. - default_value: Calculated on the fly. - unit: "" - availability: DFT+U with yukawa_potential = True. - - name: uramping - category: DFT+U correction - type: Real - description: | - Once uramping > 0.15 eV. DFT+U calculations will start SCF with U = 0 eV, namely normal LDA/PBE calculations. Once SCF restarts when drho 0." - - name: omc - category: DFT+U correction - type: Integer - description: | - The parameter controls the form of occupation matrix control used. - * 0: No occupation matrix control is performed, and the onsite density matrix will be calculated from wavefunctions in each SCF step. - * 1: The first SCF step will use an initial density matrix read from a file named initial_onsite.dm, but for later steps, the onsite density matrix will be updated. - * 2: The same onsite density matrix from initial_onsite.dm will be used throughout the entire calculation. - - [NOTE] The easiest way to create initial_onsite.dm is to run a DFT+U calculation, look for a file named onsite.dm in the OUT.prefix directory, and make replacements there. The format of the file is rather straight-forward. - default_value: "0" - unit: "" - availability: "" - - name: onsite_radius - category: DFT+U correction - type: Real - description: | - * The onsite_radius parameter facilitates modulation of the single-zeta portion of numerical atomic orbitals used for DFT+U projections. - * The modulation algorithm applies a smooth truncation to the orbital tail followed by normalization. A representative profile is $f(r)=\frac{1}{2}\left[1+\operatorname{erf}\!\left(\frac{r_c-r}{\sigma}\right)\right]$, where $r_c$ is the cutoff radius and $\sigma=\gamma r_c$ controls smoothness. - default_value: "3.0" - unit: Bohr - availability: dft_plus_u is set to 1 - - name: sc_mag_switch - category: Spin-Constrained DFT - type: Boolean - description: | - Switch to control spin-constrained DFT calculation - default_value: "False" - unit: "" - availability: "" - - name: decay_grad_switch - category: Spin-Constrained DFT - type: Boolean - description: | - Switch to control gradient break condition in spin-constrained DFT - default_value: "False" - unit: "" - availability: "" - - name: sc_thr - category: Spin-Constrained DFT - type: Real - description: | - Convergence criterion of spin-constrained iteration (RMS) in uB - default_value: "1.0e-6" - unit: uB - availability: sc_mag_switch is true - - name: nsc - category: Spin-Constrained DFT - type: Integer - description: | - Maximal number of spin-constrained iteration - default_value: "100" - unit: "" - availability: sc_mag_switch is true - - name: nsc_min - category: Spin-Constrained DFT - type: Integer - description: | - Minimum number of spin-constrained iteration - default_value: "2" - unit: "" - availability: sc_mag_switch is true - - name: alpha_trial - category: Spin-Constrained DFT - type: Real - description: | - Initial trial step size for lambda in eV/uB^2 - default_value: "0.01" - unit: eV/uB^2 - availability: sc_mag_switch is true - - name: sccut - category: Spin-Constrained DFT - type: Real - description: | - Maximal step size for lambda in eV/uB - default_value: "3.0" - unit: eV/uB - availability: sc_mag_switch is true - - name: sc_drop_thr - category: Spin-Constrained DFT - type: Real - description: | - Convergence criterion ratio of lambda iteration in Spin-constrained DFT - default_value: "1.0e-2" - unit: "" - availability: sc_mag_switch is true - - name: sc_scf_thr - category: Spin-Constrained DFT - type: Real - description: | - Density error threshold for inner loop of spin-constrained SCF - default_value: "1.0e-4" - unit: "" - availability: sc_mag_switch is true - - name: sc_direction_only - category: Spin-Constrained DFT - type: Boolean - description: | - When true, only the direction of the magnetic moment is constrained to the target direction, while the magnitude is allowed to vary freely. This is useful for studying magnetic anisotropy or when the magnitude of the moment is determined by the electronic structure rather than an external constraint. - - When false (default), both the direction and magnitude of the magnetic moment are constrained to the target values. - default_value: "False" - unit: "" - availability: sc_mag_switch is true - - name: sc_lambda_strategy - category: Spin-Constrained DFT - type: String - description: | - Lambda update strategy for spin-constrained DFT: - * bfgs: BFGS quasi-Newton method - * linear_response: linear response (Scheme B) - * augmented_lagrangian: augmented Lagrangian (Scheme C) - * hybrid_delayed: hybrid delayed update (Scheme D) - * linear_scan: linear sweep of lambda for testing magnetic moment response - default_value: bfgs - unit: "" - availability: sc_mag_switch is true - - name: sc_scan_lambda_start - category: Spin-Constrained DFT - type: Float - description: | - Starting lambda value for linear_scan strategy. Only used when sc_lambda_strategy=linear_scan. - default_value: "0.0" - unit: eV/uB - availability: sc_lambda_strategy is linear_scan - - name: sc_scan_lambda_end - category: Spin-Constrained DFT - type: Float - description: | - Ending lambda value for linear_scan strategy. Only used when sc_lambda_strategy=linear_scan. - default_value: "1.0" - unit: eV/uB - availability: sc_lambda_strategy is linear_scan - - name: sc_scan_steps - category: Spin-Constrained DFT - type: Integer - description: | - Number of lambda values to scan. Only used when sc_lambda_strategy=linear_scan. - default_value: "20" - unit: "" - availability: sc_lambda_strategy is linear_scan - - name: qo_switch - category: Quasiatomic Orbital (QO) analysis - type: Boolean - description: | - Whether to let ABACUS output QO analysis required files - default_value: "False" - unit: "" - availability: "" - - name: qo_basis - category: Quasiatomic Orbital (QO) analysis - type: String - description: | - Type of QO basis function: - * hydrogen: hydrogen-like basis - * pswfc: read basis from pseudopotential - * szv: single-zeta valence basis - default_value: szv - unit: "" - availability: "" - - name: qo_strategy - category: Quasiatomic Orbital (QO) analysis - type: Vector of String (1 or n values where n is the number of atomic types) - description: | - Strategy to generate radial orbitals for QO analysis. For hydrogen: energy-valence, for pswfc and szv: all - default_value: "for hydrogen: energy-valence, for pswfc and szv: all" - unit: "" - availability: "" - - name: qo_screening_coeff - category: Quasiatomic Orbital (QO) analysis - type: Vector of Real (n values where n is the number of atomic types; 1 value allowed for qo_basis=pswfc) - description: | - The screening coefficient for each atom type to rescale the shape of radial orbitals - default_value: "0.1" - unit: Bohr^-1 - availability: "" - - name: qo_thr - category: Quasiatomic Orbital (QO) analysis - type: Real - description: | - The convergence threshold determining the cutoff of generated orbital. Lower threshold will yield orbital with larger cutoff radius. - default_value: "1.0e-6" - unit: "" - availability: "" - - name: pexsi_npole - category: PEXSI - type: Integer - description: | - The number of poles used in the pole expansion method, should be a even number. - default_value: "40" - unit: "" - availability: "" - - name: pexsi_inertia - category: PEXSI - type: Boolean - description: | - Whether inertia counting is used at the very beginning. - default_value: "True" - unit: "" - availability: "" - - name: pexsi_nmax - category: PEXSI - type: Integer - description: | - Maximum number of PEXSI iterations after each inertia counting procedure. - default_value: "80" - unit: "" - availability: "" - - name: pexsi_comm - category: PEXSI - type: Boolean - description: | - Whether to construct PSelInv communication pattern. - default_value: "True" - unit: "" - availability: "" - - name: pexsi_storage - category: PEXSI - type: Boolean - description: | - Whether to use symmetric storage space used by the Selected Inversion algorithm for symmetric matrices. - default_value: "True" - unit: "" - availability: "" - - name: pexsi_ordering - category: PEXSI - type: Integer - description: | - Ordering strategy for factorization and selected inversion. 0: Parallel ordering using ParMETIS, 1: Sequential ordering using METIS, 2: Multiple minimum degree ordering - default_value: "0" - unit: "" - availability: "" - - name: pexsi_row_ordering - category: PEXSI - type: Integer - description: | - Row permutation strategy for factorization and selected inversion, 0: No row permutation, 1: Make the diagonal entry of the matrix larger than the off-diagonal entries. - default_value: "1" - unit: "" - availability: "" - - name: pexsi_nproc - category: PEXSI - type: Integer - description: | - Number of processors for PARMETIS. Only used if pexsi_ordering == 0. - default_value: "1" - unit: "" - availability: "" - - name: pexsi_symm - category: PEXSI - type: Boolean - description: | - Whether the matrix is symmetric. - default_value: "True" - unit: "" - availability: "" - - name: pexsi_trans - category: PEXSI - type: Boolean - description: | - Whether to factorize the transpose of the matrix. - default_value: "False" - unit: "" - availability: "" - - name: pexsi_method - category: PEXSI - type: Integer - description: | - The pole expansion method to be used. 1 for Cauchy Contour Integral method, 2 for Moussa optimized method. - default_value: "1" - unit: "" - availability: "" - - name: pexsi_nproc_pole - category: PEXSI - type: Integer - description: | - The point parallelizaion of PEXSI. Recommend two points parallelization. - default_value: "1" - unit: "" - availability: "" - - name: pexsi_temp - category: PEXSI - type: Real - description: | - Temperature in Fermi-Dirac distribution, in Ry, should have the same effect as the smearing sigma when smearing method is set to Fermi-Dirac. - default_value: "0.015" - unit: "" - availability: "" - - name: pexsi_gap - category: PEXSI - type: Real - description: | - Spectral gap, this can be set to be 0 in most cases. - default_value: "0" - unit: "" - availability: "" - - name: pexsi_delta_e - category: PEXSI - type: Real - description: | - Upper bound for the spectral radius of S^{-1}H. - default_value: "20" - unit: "" - availability: "" - - name: pexsi_mu_lower - category: PEXSI - type: Real - description: | - Initial guess of lower bound for mu. - default_value: "-10" - unit: "" - availability: "" - - name: pexsi_mu_upper - category: PEXSI - type: Real - description: | - Initial guess of upper bound for mu. - default_value: "10" - unit: "" - availability: "" - - name: pexsi_mu - category: PEXSI - type: Real - description: | - Initial guess for mu (for the solver). - default_value: "0" - unit: "" - availability: "" - - name: pexsi_mu_thr - category: PEXSI - type: Real - description: | - Stopping criterion in terms of the chemical potential for the inertia counting procedure. - default_value: "0.05" - unit: "" - availability: "" - - name: pexsi_mu_expand - category: PEXSI - type: Real - description: | - If the chemical potential is not in the initial interval, the interval is expanded by this value. - default_value: "0.3" - unit: "" - availability: "" - - name: pexsi_mu_guard - category: PEXSI - type: Real - description: | - Safe guard criterion in terms of the chemical potential to reinvoke the inertia counting procedure. - default_value: "0.2" - unit: "" - availability: "" - - name: pexsi_elec_thr - category: PEXSI - type: Real - description: | - Stopping criterion of the PEXSI iteration in terms of the number of electrons compared to numElectronExact. - default_value: "0.001" - unit: "" - availability: "" - - name: pexsi_zero_thr - category: PEXSI - type: Real - description: | - if the absolute value of CCS matrix element is less than this value, it will be considered as zero. - default_value: "1e-10" - unit: "" - availability: "" - - name: out_alllog - category: Output information - type: Boolean - description: | - Whether to print information into individual logs from all ranks in an MPI run. - * True: Information from each rank will be written into individual files named OUT.{calculation}_{suffix}/running_${calculation}.log. - default_value: "False" - unit: "" - availability: "" - - name: nurse - category: Variables useful for debugging - type: Integer - description: | - Debugging flag for developers - default_value: "0" - unit: "" - availability: "" - - name: t_in_h - category: Variables useful for debugging - type: Boolean - description: | - Specify whether to include kinetic term in obtaining the Hamiltonian matrix. - * 0: No. - * 1: Yes. - default_value: "1" - unit: "" - availability: "" - - name: vl_in_h - category: Variables useful for debugging - type: Boolean - description: | - Specify whether to include local pseudopotential term in obtaining the Hamiltonian matrix. - * 0: No. - * 1: Yes. - default_value: "1" - unit: "" - availability: "" - - name: vnl_in_h - category: Variables useful for debugging - type: Boolean - description: | - Specify whether to include non-local pseudopotential term in obtaining the Hamiltonian matrix. - * 0: No. - * 1: Yes. - default_value: "1" - unit: "" - availability: "" - - name: vh_in_h - category: Variables useful for debugging - type: Boolean - description: | - Specify whether to include Hartree potential term in obtaining the Hamiltonian matrix. - * 0: No. - * 1: Yes. - default_value: "1" - unit: "" - availability: "" - - name: vion_in_h - category: Variables useful for debugging - type: Boolean - description: | - Specify whether to include local ionic potential term in obtaining the Hamiltonian matrix. - * 0: No. - * 1: Yes. - default_value: "1" - unit: "" - availability: "" - - name: test_force - category: Variables useful for debugging - type: Boolean - description: | - Specify whether to output the detailed components in forces. - * 0: No. - * 1: Yes. - default_value: "0" - unit: "" - availability: "" - - name: test_stress - category: Variables useful for debugging - type: Boolean - description: | - Specify whether to output the detailed components in stress. - * 0: No. - * 1: Yes. - default_value: "0" - unit: "" - availability: "" - - name: test_skip_ewald - category: Variables useful for debugging - type: Boolean - description: | - Specify whether to skip the calculation of the ewald energy. - * 0: No. - * 1: Yes. - default_value: "0" - unit: "" - availability: "" - - name: ri_hartree_benchmark - category: Linear Response TDDFT - type: String - description: | - Whether to use the RI approximation for the Hartree term in LR-TDDFT for benchmark (with FHI-aims/ABACUS read-in style) - default_value: none - unit: "" - availability: "" - - name: aims_nbasis - category: Linear Response TDDFT - type: A number(ntype) of Integers - description: | - Atomic basis set size for each atom type (with the same order as in STRU) in FHI-aims. - default_value: "{} (empty list, where ABACUS use its own basis set size)" - unit: "" - availability: ri_hartree_benchmark = aims - - name: rdmft - category: Reduced Density Matrix Functional Theory - type: Boolean - description: | - Whether to perform rdmft calculation (reduced density matrix funcional theory) - default_value: "false" - unit: "" - availability: "" - - name: rdmft_power_alpha - category: Reduced Density Matrix Functional Theory - type: Real - description: | - The alpha parameter of power-functional(or other exx-type/hybrid functionals) which used in RDMFT, g(occ_number) = occ_number^alpha - default_value: "0.656" - unit: "" - availability: "" - - name: "exxace" - category: Exact Exchange (PW) - type: Boolean - description: | - Whether to use the ACE method (https://doi.org/10.1021/acs.jctc.6b00092) to accelerate the calculation the Fock exchange matrix. Should be set to true most of the time. - * True: Use the ACE method to calculate the Fock exchange operator. - * False: Use the traditional method to calculate the Fock exchange operator. - default_value: "True" - unit: "" - availability: exx_separate_loop==True. - - name: exx_gamma_extrapolation - category: Exact Exchange (PW) - type: Boolean - description: | - Whether to use the gamma point extrapolation method to calculate the Fock exchange operator. See https://doi.org/10.1103/PhysRevB.79.205114 for details. Should be set to true most of the time. - default_value: "True" - unit: "" - availability: "" - - name: ecutexx - category: Exact Exchange (PW) - type: Real - description: | - The energy cutoff for EXX (Fock) exchange operator in plane wave basis calculations. Reducing ecutexx below ecutrho may significantly accelerate EXX computations. This speed improvement comes with a reduced numerical accuracy in the exchange energy calculation. - default_value: same as ecutrho - unit: Ry - availability: "" - - name: exx_thr_type - category: Exact Exchange (PW) - type: String - description: | - The type of threshold used to judge whether the outer loop has converged in the separate loop EXX calculation. - * energy: use the change of exact exchange energy to judge convergence. - * density: if the change of charge density difference between two successive outer loop iterations is seen as converged according to scf_thr, then the outer loop is seen as converged. - default_value: density - unit: "" - availability: "" - - name: exx_ene_thr - category: Exact Exchange (PW) - type: Real - description: | - The threshold for the change of exact exchange energy to judge convergence of the outer loop in the separate loop EXX calculation. - default_value: "1e-5" - unit: Ry - availability: exx_thr_type==energy diff --git a/docs/tests/test_conf_input_docs.py b/docs/tests/test_conf_input_docs.py new file mode 100644 index 00000000000..697896f51e6 --- /dev/null +++ b/docs/tests/test_conf_input_docs.py @@ -0,0 +1,73 @@ +import stat +import sys +import tempfile +import unittest +from pathlib import Path + +sys.path.insert(0, str(Path(__file__).resolve().parents[1])) +import conf + + +PARAMETER_YAML = """\ +parameters: + - key: ecutwfc + name: ecutwfc + category: Plane wave related variables + type: double + default_value: 100 + unit: Ry + description: Plane wave kinetic energy cutoff. +""" + + +class InputDocsGenerationTest(unittest.TestCase): + def test_refreshes_input_docs_from_abacus_binary_without_writing_yaml_file(self): + with tempfile.TemporaryDirectory() as tmpdir: + tmp_path = Path(tmpdir) + docs_dir = tmp_path / "docs" + docs_dir.mkdir() + fake_abacus = tmp_path / "abacus" + fake_abacus.write_text( + "#!/bin/sh\n" + "if [ \"$1\" = \"--generate-parameters-yaml\" ]; then\n" + f" cat <<'EOF'\n{PARAMETER_YAML}EOF\n" + " exit 0\n" + "fi\n" + "exit 1\n" + ) + fake_abacus.chmod(fake_abacus.stat().st_mode | stat.S_IXUSR) + + warnings = [] + refreshed = conf.refresh_input_docs( + docs_dir=docs_dir, + abacus_binary=fake_abacus, + warn=warnings.append, + ) + + output = docs_dir / "advanced" / "input_files" / "input-main.md" + self.assertTrue(refreshed) + self.assertTrue(output.exists()) + self.assertIn("ecutwfc", output.read_text()) + self.assertFalse((docs_dir / "parameters.yaml").exists()) + self.assertEqual([], warnings) + + def test_warns_when_abacus_binary_is_not_available(self): + with tempfile.TemporaryDirectory() as tmpdir: + docs_dir = Path(tmpdir) / "docs" + docs_dir.mkdir() + warnings = [] + + refreshed = conf.refresh_input_docs( + docs_dir=docs_dir, + abacus_binary=docs_dir / "missing-abacus", + warn=warnings.append, + ) + + self.assertFalse(refreshed) + self.assertEqual([], list(docs_dir.rglob("input-main.md"))) + self.assertEqual(1, len(warnings)) + self.assertIn("may not be up to date", warnings[0]) + + +if __name__ == "__main__": + unittest.main() From 6658864ffeed62659aaf8e90f15f73cc4370d70e Mon Sep 17 00:00:00 2001 From: Bonan Zhu Date: Sun, 12 Jul 2026 17:37:36 +0800 Subject: [PATCH 5/9] tools: align governance input docs check --- .../agent_governance_check.py | 7 +++---- .../test_agent_governance_check.py | 20 ++++++++++++++++--- 2 files changed, 20 insertions(+), 7 deletions(-) diff --git a/tools/03_code_analysis/agent_governance_check.py b/tools/03_code_analysis/agent_governance_check.py index 19488c16cd1..9391d4c5ccb 100644 --- a/tools/03_code_analysis/agent_governance_check.py +++ b/tools/03_code_analysis/agent_governance_check.py @@ -465,12 +465,11 @@ def check_input_parameter_docs( ) -> None: if not input_parameter_changed(changed, lines): return - has_yaml = "docs/parameters.yaml" in changed and not statuses.get("docs/parameters.yaml", "").startswith("D") has_markdown = ( "docs/advanced/input_files/input-main.md" in changed and not statuses.get("docs/advanced/input_files/input-main.md", "").startswith("D") ) - if has_yaml and has_markdown: + if has_markdown: return if pr_body and pr_body_allows_no_input_doc_update(pr_body): return @@ -480,8 +479,8 @@ def check_input_parameter_docs( BLOCK, "source/source_io/module_parameter", None, - "INPUT parameter behavior appears to change without both docs/parameters.yaml and input-main.md updates.", - "Regenerate docs/parameters.yaml and docs/advanced/input_files/input-main.md, or state why no INPUT documentation update is required in the PR.", + "INPUT parameter behavior appears to change without an input-main.md update.", + "Regenerate docs/advanced/input_files/input-main.md from the ABACUS parameter metadata, or state why no INPUT documentation update is required in the PR.", ) diff --git a/tools/03_code_analysis/test_agent_governance_check.py b/tools/03_code_analysis/test_agent_governance_check.py index d5b6bff299a..9143cb1b946 100644 --- a/tools/03_code_analysis/test_agent_governance_check.py +++ b/tools/03_code_analysis/test_agent_governance_check.py @@ -251,7 +251,6 @@ def test_allows_input_parameter_changes_with_required_docs(self): "source/source_io/module_parameter/read_input_item_model.cpp", 'Input_Item item("new_switch");\nitem.default_value = "0";\n', ) - self.write("docs/parameters.yaml", "parameters: []\n") self.write("docs/advanced/input_files/input-main.md", "# INPUT\n") head = self.commit_change() @@ -259,8 +258,24 @@ def test_allows_input_parameter_changes_with_required_docs(self): self.assertEqual(result.returncode, 0, result.stdout + result.stderr) - def test_blocks_input_parameter_change_when_required_docs_are_deleted(self): + def test_allows_input_parameter_changes_with_markdown_and_deleted_yaml(self): self.write("docs/parameters.yaml", "parameters: []\n") + self.git("add", ".") + self.git("commit", "-m", "add legacy parameter yaml") + base = self.git("rev-parse", "HEAD").stdout.strip() + self.write( + "source/source_io/module_parameter/read_input_item_model.cpp", + 'Input_Item item("new_switch");\nitem.default_value = "0";\n', + ) + self.write("docs/advanced/input_files/input-main.md", "# INPUT\n") + (self.repo / "docs" / "parameters.yaml").unlink() + head = self.commit_change() + + result = self.run_checker("--base", base, "--head", head) + + self.assertEqual(result.returncode, 0, result.stdout + result.stderr) + + def test_blocks_input_parameter_change_when_required_docs_are_deleted(self): self.write("docs/advanced/input_files/input-main.md", "# INPUT\n") self.git("add", ".") self.git("commit", "-m", "add input docs") @@ -269,7 +284,6 @@ def test_blocks_input_parameter_change_when_required_docs_are_deleted(self): "source/source_io/module_parameter/read_input_item_model.cpp", 'Input_Item item("new_switch");\nitem.default_value = "0";\n', ) - (self.repo / "docs" / "parameters.yaml").unlink() (self.repo / "docs" / "advanced" / "input_files" / "input-main.md").unlink() head = self.commit_change() From c969a48187cb24ad3fc81db585b10b26f3e72ce6 Mon Sep 17 00:00:00 2001 From: Bonan Zhu Date: Sun, 12 Jul 2026 21:13:49 +0800 Subject: [PATCH 6/9] docs: fail RTD input reference refresh errors --- docs/README.md | 9 +++-- docs/conf.py | 34 +++++++++++++---- docs/tests/test_conf_input_docs.py | 60 ++++++++++++++++++++++++++++++ 3 files changed, 91 insertions(+), 12 deletions(-) diff --git a/docs/README.md b/docs/README.md index 0221bc5816e..4d9d4c905b3 100644 --- a/docs/README.md +++ b/docs/README.md @@ -4,7 +4,8 @@ These files are the source for the ABACUS manual published on Read the Docs. Read the Docs builds a minimal serial ABACUS binary, regenerates `docs/advanced/input_files/input-main.md` from that binary during the -documentation build, and emits a warning if no ABACUS executable is available. +documentation build, and fails the build if the INPUT reference cannot be +refreshed. ## Build the Manual Locally @@ -59,9 +60,9 @@ Run the following commands from the repository root. 1. Open `build-docs/html/index.html` in a browser. -If no ABACUS executable is available, the Sphinx build still continues with the -checked-in `docs/advanced/input_files/input-main.md` and prints a warning that -the INPUT parameter reference may not be up to date. +For local builds, if no ABACUS executable is available, the Sphinx build still +continues with the checked-in `docs/advanced/input_files/input-main.md` and +prints a warning that the INPUT parameter reference may not be up to date. ## Regenerate Only the INPUT Reference diff --git a/docs/conf.py b/docs/conf.py index 6f97f0af117..60126aa2382 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -122,12 +122,23 @@ def warn_input_docs(message): print(f"Warning: {message}") +def input_docs_refresh_required(env=None): + env = os.environ if env is None else env + return env.get('READTHEDOCS') == 'True' + + +def handle_input_docs_failure(message, warn, fail_on_error): + if fail_on_error: + raise RuntimeError(message) + warn(message) + + def candidate_abacus_binaries(repo_root): """Return candidate ABACUS binaries for local and Read the Docs builds.""" env_binary = os.environ.get('ABACUS_BINARY') or os.environ.get('ABACUS_EXECUTABLE') - candidates = [] if env_binary: - candidates.append(Path(env_binary)) + return [Path(env_binary)] + candidates = [] candidates.extend([ repo_root / 'build-rtd-docs' / 'source' / 'abacus_pw_ser', repo_root / 'build-rtd-docs' / 'abacus_pw_ser', @@ -146,16 +157,18 @@ def find_abacus_binary(repo_root): return None -def refresh_input_docs(docs_dir, abacus_binary=None, warn=warn_input_docs): +def refresh_input_docs(docs_dir, abacus_binary=None, warn=warn_input_docs, fail_on_error=False): """Refresh input-main.md from an ABACUS executable, if one is available.""" docs_dir = Path(docs_dir) repo_root = docs_dir.parent binary = Path(abacus_binary) if abacus_binary else find_abacus_binary(repo_root) if binary is None or not binary.exists() or not os.access(binary, os.X_OK): - warn( + handle_input_docs_failure( "ABACUS executable not found; INPUT parameter documentation may not " "be up to date. Set ABACUS_BINARY=/path/to/abacus or build the " - "reduced documentation binary first." + "reduced documentation binary first.", + warn, + fail_on_error, ) return False @@ -170,10 +183,12 @@ def refresh_input_docs(docs_dir, abacus_binary=None, warn=warn_input_docs): ) if result.returncode != 0: detail = result.stderr.strip() or result.stdout.strip() - warn( + handle_input_docs_failure( "ABACUS could not generate INPUT parameter metadata; documentation " f"may not be up to date. Command: {binary} --generate-parameters-yaml" - + (f". Output: {detail}" if detail else "") + + (f". Output: {detail}" if detail else ""), + warn, + fail_on_error, ) return False @@ -188,7 +203,10 @@ def refresh_input_docs(docs_dir, abacus_binary=None, warn=warn_input_docs): def generate_input_docs(app): - refresh_input_docs(Path(__file__).resolve().parent) + refresh_input_docs( + Path(__file__).resolve().parent, + fail_on_error=input_docs_refresh_required(), + ) def setup(app): app.connect('builder-inited', generate_input_docs) diff --git a/docs/tests/test_conf_input_docs.py b/docs/tests/test_conf_input_docs.py index 697896f51e6..7cce650f856 100644 --- a/docs/tests/test_conf_input_docs.py +++ b/docs/tests/test_conf_input_docs.py @@ -2,6 +2,7 @@ import sys import tempfile import unittest +from unittest import mock from pathlib import Path sys.path.insert(0, str(Path(__file__).resolve().parents[1])) @@ -21,6 +22,22 @@ class InputDocsGenerationTest(unittest.TestCase): + def test_readthedocs_environment_requires_fresh_input_docs(self): + self.assertTrue(conf.input_docs_refresh_required({"READTHEDOCS": "True"})) + self.assertFalse(conf.input_docs_refresh_required({"READTHEDOCS": "False"})) + self.assertFalse(conf.input_docs_refresh_required({})) + + def test_explicit_abacus_binary_path_disables_fallback_search(self): + with tempfile.TemporaryDirectory() as tmpdir: + repo_root = Path(tmpdir) + fallback_binary = repo_root / "build-rtd-docs" / "source" / "abacus_pw_ser" + fallback_binary.parent.mkdir(parents=True) + fallback_binary.write_text("#!/bin/sh\nexit 0\n") + fallback_binary.chmod(fallback_binary.stat().st_mode | stat.S_IXUSR) + + with mock.patch.dict("os.environ", {"ABACUS_BINARY": str(repo_root / "missing-abacus")}): + self.assertIsNone(conf.find_abacus_binary(repo_root)) + def test_refreshes_input_docs_from_abacus_binary_without_writing_yaml_file(self): with tempfile.TemporaryDirectory() as tmpdir: tmp_path = Path(tmpdir) @@ -68,6 +85,49 @@ def test_warns_when_abacus_binary_is_not_available(self): self.assertEqual(1, len(warnings)) self.assertIn("may not be up to date", warnings[0]) + def test_required_refresh_raises_when_abacus_binary_is_not_available(self): + with tempfile.TemporaryDirectory() as tmpdir: + docs_dir = Path(tmpdir) / "docs" + docs_dir.mkdir() + warnings = [] + + with self.assertRaises(RuntimeError) as caught: + conf.refresh_input_docs( + docs_dir=docs_dir, + abacus_binary=docs_dir / "missing-abacus", + warn=warnings.append, + fail_on_error=True, + ) + + self.assertIn("may not be up to date", str(caught.exception)) + self.assertEqual([], warnings) + + def test_required_refresh_raises_when_abacus_metadata_generation_fails(self): + with tempfile.TemporaryDirectory() as tmpdir: + tmp_path = Path(tmpdir) + docs_dir = tmp_path / "docs" + docs_dir.mkdir() + fake_abacus = tmp_path / "abacus" + fake_abacus.write_text( + "#!/bin/sh\n" + "echo 'metadata generation failed' >&2\n" + "exit 2\n" + ) + fake_abacus.chmod(fake_abacus.stat().st_mode | stat.S_IXUSR) + warnings = [] + + with self.assertRaises(RuntimeError) as caught: + conf.refresh_input_docs( + docs_dir=docs_dir, + abacus_binary=fake_abacus, + warn=warnings.append, + fail_on_error=True, + ) + + self.assertIn("could not generate INPUT parameter metadata", str(caught.exception)) + self.assertIn("metadata generation failed", str(caught.exception)) + self.assertEqual([], warnings) + if __name__ == "__main__": unittest.main() From 2665ead5f3ea3607a12bdde186a93f3e0550390c Mon Sep 17 00:00:00 2001 From: Bonan Zhu <33688599+zhubonan@users.noreply.github.com> Date: Mon, 14 Sep 2026 20:32:12 +0800 Subject: [PATCH 7/9] Update docs/README.md Co-authored-by: SY Wang --- docs/README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/README.md b/docs/README.md index 4d9d4c905b3..2652689b34d 100644 --- a/docs/README.md +++ b/docs/README.md @@ -14,7 +14,8 @@ Run the following commands from the repository root. 1. Create a Python virtual environment with `uv`: ```bash - uv venv --python python3 .venv + python3 -m venv .venv + source .venv/bin/activate ``` 1. Install the documentation requirements: From 408e321a485e4d42c81616c419fe9c52213c09cd Mon Sep 17 00:00:00 2001 From: Bonan Zhu Date: Mon, 14 Sep 2026 23:01:35 +0800 Subject: [PATCH 8/9] docs: clarify local documentation build dependencies --- docs/README.md | 38 +++++++++++++++++++++++++++++--------- docs/requirements.txt | 1 + 2 files changed, 30 insertions(+), 9 deletions(-) diff --git a/docs/README.md b/docs/README.md index 2652689b34d..e840c7e48a0 100644 --- a/docs/README.md +++ b/docs/README.md @@ -11,19 +11,23 @@ refreshed. Run the following commands from the repository root. -1. Create a Python virtual environment with `uv`: +1. Create a Python virtual environment: ```bash python3 -m venv .venv source .venv/bin/activate ``` -1. Install the documentation requirements: +1. Install the Python documentation requirements: ```bash - uv pip install --python .venv/bin/python -r docs/requirements.txt sphinx ninja + pip3 install -r docs/requirements.txt ``` +The reduced ABACUS build also requires a C++ compiler, a Fortran compiler, +CMake, Ninja, FFTW3, BLAS, and LAPACK. These are system/build dependencies, +not Python documentation dependencies. + 1. Build the reduced ABACUS executable used for INPUT parameter metadata: ```bash @@ -49,6 +53,18 @@ Run the following commands from the repository root. cmake --build build-rtd-docs --target abacus_pw_ser --parallel 2 ``` +1. (Optional) Refresh the checked-in INPUT reference manually: + + The ABACUS executable emits the parameter metadata as a transient YAML + stream. Pipe that stream directly to the Markdown generator; no + `docs/parameters.yaml` file is created or maintained. + + ```bash + ./build-rtd-docs/source/abacus_pw_ser --generate-parameters-yaml \ + | .venv/bin/python docs/generate_input_main.py - \ + --output docs/advanced/input_files/input-main.md + ``` + 1. Build the HTML manual: ```bash @@ -67,7 +83,8 @@ prints a warning that the INPUT parameter reference may not be up to date. ## Regenerate Only the INPUT Reference -To refresh only the generated INPUT reference after building ABACUS: +To refresh only the generated INPUT reference after building ABACUS, pipe the +transient YAML stream directly into the Markdown generator: ```bash ./build-rtd-docs/source/abacus_pw_ser --generate-parameters-yaml \ @@ -96,16 +113,19 @@ To smoke-test the Read the Docs environment locally, use the same image as the hosted build: ```bash -docker run --rm -v "$PWD:/project" -w /project \ +docker run --rm --user root -v "$PWD:/project" -w /project \ readthedocs/build:ubuntu-22.04-2024.01.29 \ - /bin/bash -lc 'python -m pip install -r docs/requirements.txt sphinx ninja && - cmake -S . -B build-rtd-docs -G Ninja -DCMAKE_BUILD_TYPE=Release \ + /bin/bash -lc 'apt-get update && + apt-get install -y build-essential cmake gfortran git libfftw3-dev \ + liblapack-dev libopenblas-dev ninja-build pkg-config python3-pip && + python3 -m pip install -r docs/requirements.txt && + cmake -S . -B /tmp/build-rtd-docs -G Ninja -DCMAKE_BUILD_TYPE=Release \ -DENABLE_MPI=OFF -DENABLE_LCAO=OFF -DUSE_OPENMP=OFF -DUSE_ELPA=OFF \ -DUSE_CUDA=OFF -DUSE_ROCM=OFF -DBUILD_TESTING=OFF \ -DENABLE_LIBXC=OFF -DENABLE_LIBRI=OFF -DENABLE_DFTD4=OFF \ -DENABLE_RAPIDJSON=OFF -DENABLE_MLALGO=OFF -DENABLE_FLOAT_FFTW=OFF \ -DENABLE_CNPY=OFF -DCOMMIT_INFO=OFF -DGIT_SUBMODULE=OFF -DMKLROOT=OFF && - cmake --build build-rtd-docs --target abacus_pw_ser --parallel 2 && - export ABACUS_BINARY=./build-rtd-docs/source/abacus_pw_ser && + cmake --build /tmp/build-rtd-docs --target abacus_pw_ser --parallel 2 && + export READTHEDOCS=True ABACUS_BINARY=/tmp/build-rtd-docs/source/abacus_pw_ser && sphinx-build -b html docs /tmp/abacus-docs-html' ``` diff --git a/docs/requirements.txt b/docs/requirements.txt index 5665feaa124..be229cdbec3 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -3,3 +3,4 @@ myst_parser[linkify] sphinx-book-theme deepmodeling-sphinx>=0.3.0 pyyaml +sphinx From 9faa9204978aeb1686cccb136cf4983fbf6f8888 Mon Sep 17 00:00:00 2001 From: Bonan Zhu Date: Thu, 17 Sep 2026 10:42:03 +0800 Subject: [PATCH 9/9] docs: generate input reference during builds --- .../abacus-governance.instructions.md | 8 +- .github/workflows/test.yml | 20 +- .gitignore | 2 + AGENTS.md | 12 +- docs/CONTRIBUTING.md | 14 +- docs/README.md | 29 +- docs/advanced/input_files/input-main.md | 5327 ----------------- docs/conf.py | 52 +- docs/developers_guide/agent_governance.md | 19 +- docs/developers_guide/input_availability.md | 5 +- docs/tests/test_conf_input_docs.py | 41 +- .../agent_governance_check.py | 64 - .../test_agent_governance_check.py | 50 +- 13 files changed, 64 insertions(+), 5579 deletions(-) delete mode 100644 docs/advanced/input_files/input-main.md diff --git a/.github/instructions/abacus-governance.instructions.md b/.github/instructions/abacus-governance.instructions.md index 0a1f2a5a2b8..c77b837b1db 100644 --- a/.github/instructions/abacus-governance.instructions.md +++ b/.github/instructions/abacus-governance.instructions.md @@ -22,10 +22,10 @@ Apply these instructions when reviewing or changing ABACUS code: usually warnings unless the PR records a narrow reason. - Require LF line endings for text files. `.bat` and `.cmd` files are the CRLF exceptions. -- For INPUT parameter behavior changes, require synchronized updates to - `docs/advanced/input_files/input-main.md`, or a clear no-update explanation - in the PR. The parameter YAML stream is generated transiently and is not stored - in the repository. +- For INPUT parameter behavior or documentation changes, require updates to the + relevant C++ `Input_Item` registration. The parameter YAML stream and + `docs/advanced/input_files/input-main.md` are generated transiently during + documentation builds and are not stored in the repository. - Check that new source files are linked through the relevant `CMakeLists.txt` unless the PR explains generated or indirect inclusion. - Keep default C++ changes compatible with the repository C++11 baseline. diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index f4d728ea9b7..5745988589f 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -121,26 +121,18 @@ jobs: ccache --show-stats ccache --show-stats >> "${GITHUB_STEP_SUMMARY}" - - name: Check documentation consistency + - name: Check INPUT documentation generation run: | ABACUS_BIN=$(find build -name "abacus_*" -type f -executable | head -1) echo "Using binary: ${ABACUS_BIN}" - # Generate transient parameter metadata from C++ Input_Item definitions - ${ABACUS_BIN} --generate-parameters-yaml > /tmp/parameters_generated.yaml - - # Check: input-main.md matches regenerated markdown + # Verify the INPUT reference can be generated from C++ Input_Item definitions pip install -q pyyaml - python docs/generate_input_main.py \ - /tmp/parameters_generated.yaml \ + ${ABACUS_BIN} --generate-parameters-yaml \ + | python docs/generate_input_main.py - \ --output /tmp/input-main-generated.md - if ! diff -q docs/advanced/input_files/input-main.md /tmp/input-main-generated.md; then - echo "error: input-main.md is out of sync" - echo "Fix: ${ABACUS_BIN} --generate-parameters-yaml | python docs/generate_input_main.py - --output docs/advanced/input_files/input-main.md" - diff docs/advanced/input_files/input-main.md /tmp/input-main-generated.md || true - exit 1 - fi - echo " input-main.md: OK" + test -s /tmp/input-main-generated.md + echo " INPUT reference generation: OK" - name: Integrated Tests Preparation env: diff --git a/.gitignore b/.gitignore index 78283c1cc0d..55bf47447ea 100644 --- a/.gitignore +++ b/.gitignore @@ -29,3 +29,5 @@ toolchain/abacus_env.sh .trae .codex compile_commands.json +# Generated by the Sphinx INPUT documentation hook. +/docs/advanced/input_files/input-main.md diff --git a/AGENTS.md b/AGENTS.md index 4431611173f..3316062b1e6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -53,10 +53,10 @@ rules. Read the complete governance document before making or reviewing changes: - Use LF line endings for text files. Only `.bat` and `.cmd` files may use CRLF. - Keep source file additions deterministic: update the relevant `CMakeLists.txt` or explain why the file is generated or included indirectly. -- INPUT parameter behavior changes must update - `docs/advanced/input_files/input-main.md`, or the PR must state why no update - is required. The parameter YAML stream is generated transiently by the ABACUS - binary and is not stored in the repository. +- INPUT parameter behavior and documentation changes must update the relevant + C++ `Input_Item` registration. The parameter YAML stream and + `docs/advanced/input_files/input-main.md` are generated transiently during + documentation builds and are not stored in the repository. - Report the exact verification performed. Do not claim completion without fresh test or check output. - For multi-step refactors (e.g., splitting a large `.cpp` into several @@ -72,8 +72,8 @@ rules. Read the complete governance document before making or reviewing changes: - Core C++ implementation lives under `source/`; source additions must be wired through the relevant `CMakeLists.txt`. -- INPUT parsing and help metadata live under `source/source_io/`; user-facing - INPUT docs live in `docs/advanced/input_files/input-main.md`. +- INPUT parsing and help metadata live under `source/source_io/`; Sphinx + generates the user-facing INPUT reference during the documentation build. - Unit tests are colocated under module `test/` directories such as `source/source_md/test/`; integration and workflow tests are selected through CTest labels and patterns. diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index eb721c7a8ff..8506bd7f244 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -174,14 +174,14 @@ An practical example is class [LCAO_Deepks](https://github.com/deepmodeling/abac ABACUS includes a built-in help system that allows users to query INPUT parameters directly from the command line (e.g., `abacus -h ecutwfc`). Parameter metadata is defined inline in the C++ source files under `source/source_io/module_parameter/` using `Input_Item` registrations. -The C++ `Input_Item` registrations are the source of truth for parameter metadata. A checked-in file `docs/advanced/input_files/input-main.md` contains the generated INPUT parameter reference; do not edit it manually. Sphinx refreshes this file from an ABACUS executable when the executable is available. +The C++ `Input_Item` registrations are the source of truth for parameter metadata. Sphinx generates `docs/advanced/input_files/input-main.md` from an ABACUS executable during every documentation build. The generated YAML stream and Markdown file are not stored in the repository. Availability expressions follow the grammar and invariants in [`developers_guide/input_availability.md`](developers_guide/input_availability.md). -### When to Update `input-main.md` +### When INPUT Documentation Changes -You **must** regenerate `docs/advanced/input_files/input-main.md` whenever you: +Update the relevant C++ `Input_Item` registration whenever you: - Add a new INPUT parameter - Remove an existing INPUT parameter @@ -189,12 +189,12 @@ You **must** regenerate `docs/advanced/input_files/input-main.md` whenever you: ### How to Regenerate -After building ABACUS, run: +After building ABACUS, preview the generated reference with: ```bash abacus --generate-parameters-yaml \ | python3 docs/generate_input_main.py - \ - --output docs/advanced/input_files/input-main.md + --output /tmp/input-main.md ``` You can also let Sphinx refresh the page during a documentation build: @@ -203,9 +203,7 @@ You can also let Sphinx refresh the page during a documentation build: ABACUS_BINARY=/path/to/abacus sphinx-build -b html docs build-docs/html ``` -If no ABACUS executable is available, Sphinx emits a warning and continues with the checked-in `input-main.md`, which may not be up to date. - -**Important:** Include the updated `input-main.md` in your commit when submitting a PR that modifies INPUT parameters. CI regenerates this file from the built binary and rejects any mismatch. Do not fix a documentation mismatch by editing the generated file by hand; update the C++ `Input_Item` registration and regenerate it instead. +If no ABACUS executable is available, or if generation fails, Sphinx stops with an error. Do not add generated YAML or `input-main.md` files to a commit; update the C++ `Input_Item` registration instead. CI verifies that the reference can be generated successfully. ### Parameter Documentation Format diff --git a/docs/README.md b/docs/README.md index 77c06c8848a..7561c61b97d 100644 --- a/docs/README.md +++ b/docs/README.md @@ -53,16 +53,17 @@ not Python documentation dependencies. cmake --build build-rtd-docs --target abacus_pw_ser --parallel 2 ``` -1. (Optional) Refresh the checked-in INPUT reference manually: +1. (Optional) Generate the INPUT reference manually for inspection: The ABACUS executable emits the parameter metadata as a transient YAML - stream. Pipe that stream directly to the Markdown generator; no - `docs/parameters.yaml` file is created or maintained. + stream. Pipe that stream directly to the Markdown generator; neither + `docs/parameters.yaml` nor `docs/advanced/input_files/input-main.md` is + maintained in the repository. ```bash ./build-rtd-docs/abacus_pw_ser --generate-parameters-yaml \ | .venv/bin/python docs/generate_input_main.py - \ - --output docs/advanced/input_files/input-main.md + --output /tmp/input-main.md ``` 1. Build the HTML manual: @@ -77,9 +78,9 @@ not Python documentation dependencies. 1. Open `build-docs/html/index.html` in a browser. -For local builds, if no ABACUS executable is available, the Sphinx build still -continues with the checked-in `docs/advanced/input_files/input-main.md` and -prints a warning that the INPUT parameter reference may not be up to date. +Every documentation build requires an ABACUS executable. If no executable is +available, or if parameter generation fails, Sphinx stops with an error rather +than publishing incomplete or stale INPUT documentation. ## Regenerate Only the INPUT Reference @@ -89,7 +90,7 @@ transient YAML stream directly into the Markdown generator: ```bash ./build-rtd-docs/abacus_pw_ser --generate-parameters-yaml \ | .venv/bin/python docs/generate_input_main.py - \ - --output docs/advanced/input_files/input-main.md + --output /tmp/input-main.md ``` ## INPUT Parameter Reference @@ -99,13 +100,13 @@ The INPUT parameter reference is generated from metadata registered in - `abacus --generate-parameters-yaml` produces a transient YAML stream; it is not stored in the repository. -- `docs/advanced/input_files/input-main.md` is generated from that metadata. -- `docs/conf.py` refreshes `input-main.md` automatically when it can find an - ABACUS executable. +- `docs/advanced/input_files/input-main.md` is generated from that metadata + during every Sphinx build and is not stored in the repository. +- `docs/conf.py` requires an ABACUS executable and fails the build if the INPUT + reference cannot be generated. -Keep `docs/advanced/input_files/input-main.md` in PRs that change INPUT -metadata. The YAML dump is intentionally transient so there is only one -generated reference file to maintain. +PRs that change INPUT metadata only update the C++ `Input_Item` registrations. +The YAML stream and Markdown reference are both transient build artifacts. ## Optional Read the Docs Container Test diff --git a/docs/advanced/input_files/input-main.md b/docs/advanced/input_files/input-main.md deleted file mode 100644 index 9ba5db77325..00000000000 --- a/docs/advanced/input_files/input-main.md +++ /dev/null @@ -1,5327 +0,0 @@ -# Full List of INPUT Keywords - - - - - -- [Full List of INPUT Keywords](#full-list-of-input-keywords) - - [System variables](#system-variables) - - [suffix](#suffix) - - [ntype](#ntype) - - [cell\_replica](#cell_replica) - - [calculation](#calculation) - - [socket\_driver](#socket_driver) - - [esolver\_type](#esolver_type) - - [symmetry](#symmetry) - - [symmetry\_prec](#symmetry_prec) - - [symmetry\_autoclose](#symmetry_autoclose) - - [cal\_force](#cal_force) - - [kpar](#kpar) - - [bndpar](#bndpar) - - [latname](#latname) - - [assume\_isolated](#assume_isolated) - - [init\_wfc](#init_wfc) - - [init\_chg](#init_chg) - - [init\_vel](#init_vel) - - [mem\_saver](#mem_saver) - - [cal\_stress](#cal_stress) - - [diago\_proc](#diago_proc) - - [nbspline](#nbspline) - - [kspacing](#kspacing) - - [koffset](#koffset) - - [kmesh\_type](#kmesh_type) - - [min\_dist\_coef](#min_dist_coef) - - [device](#device) - - [precision](#precision) - - [gint\_precision](#gint_precision) - - [timer\_enable\_nvtx](#timer_enable_nvtx) - - [cell\_factor](#cell_factor) - - [dm\_to\_rho](#dm_to_rho) - - [chg\_extrap](#chg_extrap) - - [nb2d](#nb2d) - - [cal\_symm\_repr](#cal_symm_repr) - - [Input files](#input-files) - - [stru\_file](#stru_file) - - [kpoint\_file](#kpoint_file) - - [pseudo\_dir](#pseudo_dir) - - [orbital\_dir](#orbital_dir) - - [read\_file\_dir](#read_file_dir) - - [restart\_load](#restart_load) - - [spillage\_outdir](#spillage_outdir) - - [Plane wave related variables](#plane-wave-related-variables) - - [ecutwfc](#ecutwfc) - - [ecutrho](#ecutrho) - - [nx](#nx) - - [ny](#ny) - - [nz](#nz) - - [ndx](#ndx) - - [ndy](#ndy) - - [ndz](#ndz) - - [pw\_seed](#pw_seed) - - [diag\_subspace](#diag_subspace) - - [erf\_ecut](#erf_ecut) - - [fft\_mode](#fft_mode) - - [erf\_height](#erf_height) - - [erf\_sigma](#erf_sigma) - - [pw\_diag\_thr](#pw_diag_thr) - - [diago\_smooth\_ethr](#diago_smooth_ethr) - - [use\_k\_continuity](#use_k_continuity) - - [pw\_diag\_nmax](#pw_diag_nmax) - - [pw\_diag\_ndim](#pw_diag_ndim) - - [diago\_cg\_prec](#diago_cg_prec) - - [Numerical atomic orbitals related variables](#numerical-atomic-orbitals-related-variables) - - [lmaxmax](#lmaxmax) - - [lcao\_ecut](#lcao_ecut) - - [lcao\_dk](#lcao_dk) - - [lcao\_dr](#lcao_dr) - - [lcao\_rmax](#lcao_rmax) - - [search\_radius](#search_radius) - - [bx](#bx) - - [by](#by) - - [bz](#bz) - - [elpa\_num\_thread](#elpa_num_thread) - - [num\_stream](#num_stream) - - [Electronic structure](#electronic-structure) - - [basis\_type](#basis_type) - - [ks\_solver](#ks_solver) - - [nbands](#nbands) - - [nelec](#nelec) - - [nelec\_delta](#nelec_delta) - - [nupdown](#nupdown) - - [dft\_functional](#dft_functional) - - [xc\_temperature](#xc_temperature) - - [xc\_exch\_ext](#xc_exch_ext) - - [xc\_corr\_ext](#xc_corr_ext) - - [pseudo\_rcut](#pseudo_rcut) - - [pseudo\_mesh](#pseudo_mesh) - - [nspin](#nspin) - - [smearing\_method](#smearing_method) - - [smearing\_sigma](#smearing_sigma) - - [smearing\_sigma\_temp](#smearing_sigma_temp) - - [mixing\_type](#mixing_type) - - [mixing\_beta](#mixing_beta) - - [mixing\_beta\_mag](#mixing_beta_mag) - - [mixing\_ndim](#mixing_ndim) - - [mixing\_restart](#mixing_restart) - - [mixing\_dmr](#mixing_dmr) - - [mixing\_gg0](#mixing_gg0) - - [mixing\_gg0\_mag](#mixing_gg0_mag) - - [mixing\_gg0\_min](#mixing_gg0_min) - - [mixing\_angle](#mixing_angle) - - [mixing\_tau](#mixing_tau) - - [mixing\_dftu](#mixing_dftu) - - [gamma\_only](#gamma_only) - - [scf\_nmax](#scf_nmax) - - [scf\_thr](#scf_thr) - - [scf\_ene\_thr](#scf_ene_thr) - - [scf\_thr\_type](#scf_thr_type) - - [scf\_os\_stop](#scf_os_stop) - - [scf\_os\_thr](#scf_os_thr) - - [scf\_os\_ndim](#scf_os_ndim) - - [sc\_os\_ndim](#sc_os_ndim) - - [lspinorb](#lspinorb) - - [noncolin](#noncolin) - - [soc\_lambda](#soc_lambda) - - [dfthalf\_type](#dfthalf_type) - - [Electronic structure (SDFT)](#electronic-structure-sdft) - - [method\_sto](#method_sto) - - [nbands\_sto](#nbands_sto) - - [nche\_sto](#nche_sto) - - [emin\_sto](#emin_sto) - - [emax\_sto](#emax_sto) - - [seed\_sto](#seed_sto) - - [initsto\_ecut](#initsto_ecut) - - [initsto\_freq](#initsto_freq) - - [npart\_sto](#npart_sto) - - [Geometry relaxation](#geometry-relaxation) - - [relax\_method](#relax_method) - - [relax\_scale\_force](#relax_scale_force) - - [relax\_nmax](#relax_nmax) - - [relax\_cg\_thr](#relax_cg_thr) - - [force\_thr](#force_thr) - - [force\_thr\_ev](#force_thr_ev) - - [force\_zero\_out](#force_zero_out) - - [relax\_bfgs\_w1](#relax_bfgs_w1) - - [relax\_bfgs\_w2](#relax_bfgs_w2) - - [relax\_bfgs\_rmax](#relax_bfgs_rmax) - - [relax\_bfgs\_rmin](#relax_bfgs_rmin) - - [relax\_bfgs\_init](#relax_bfgs_init) - - [stress\_thr](#stress_thr) - - [press1](#press1) - - [press2](#press2) - - [press3](#press3) - - [fixed\_axes](#fixed_axes) - - [fixed\_ibrav](#fixed_ibrav) - - [fixed\_atoms](#fixed_atoms) - - [Output information](#output-information) - - [out\_freq\_ion](#out_freq_ion) - - [out\_freq\_td](#out_freq_td) - - [out\_freq\_elec](#out_freq_elec) - - [out\_chg](#out_chg) - - [out\_pot](#out_pot) - - [out\_dmk](#out_dmk) - - [out\_dmr](#out_dmr) - - [out\_wfc\_pw](#out_wfc_pw) - - [out\_wfc\_lcao](#out_wfc_lcao) - - [out\_dos](#out_dos) - - [out\_ldos](#out_ldos) - - [out\_band](#out_band) - - [out\_proj\_band](#out_proj_band) - - [out\_stru](#out_stru) - - [out\_level](#out_level) - - [out\_hsk](#out_hsk) - - [out\_mat\_hs](#out_mat_hs) - - [out\_hsr](#out_hsr) - - [out\_mat\_hs2](#out_mat_hs2) - - [out\_mat\_tk](#out_mat_tk) - - [out\_mat\_r](#out_mat_r) - - [out\_mat\_t](#out_mat_t) - - [out\_mat\_dh](#out_mat_dh) - - [out\_mat\_dh\_t](#out_mat_dh_t) - - [out\_mat\_dh\_vl](#out_mat_dh_vl) - - [out\_mat\_dh\_vnl](#out_mat_dh_vnl) - - [out\_mat\_dh\_vh](#out_mat_dh_vh) - - [out\_mat\_dh\_vxc](#out_mat_dh_vxc) - - [out\_mat\_dh\_exx](#out_mat_dh_exx) - - [out\_mat\_h\_t](#out_mat_h_t) - - [out\_mat\_h\_vnl](#out_mat_h_vnl) - - [out\_mat\_h\_vl](#out_mat_h_vl) - - [out\_mat\_h\_vh](#out_mat_h_vh) - - [out\_mat\_h\_vxc](#out_mat_h_vxc) - - [out\_mat\_h\_exx](#out_mat_h_exx) - - [out\_mat\_ds](#out_mat_ds) - - [out\_mat\_xc](#out_mat_xc) - - [out\_mat\_xc2](#out_mat_xc2) - - [out\_mat\_l](#out_mat_l) - - [out\_xc\_r](#out_xc_r) - - [out\_eband\_terms](#out_eband_terms) - - [out\_hr\_npz](#out_hr_npz) - - [out\_hsr\_npz](#out_hsr_npz) - - [out\_dm\_npz](#out_dm_npz) - - [out\_mul](#out_mul) - - [out\_app\_flag](#out_app_flag) - - [out\_ndigits](#out_ndigits) - - [out\_element\_info](#out_element_info) - - [restart\_save](#restart_save) - - [rpa](#rpa) - - [rpa\_out\_vel](#rpa_out_vel) - - [rpa\_outdir](#rpa_outdir) - - [out\_pchg](#out_pchg) - - [out\_wfc\_norm](#out_wfc_norm) - - [out\_wfc\_re\_im](#out_wfc_re_im) - - [if\_separate\_k](#if_separate_k) - - [out\_elf](#out_elf) - - [out\_spillage](#out_spillage) - - [out\_alllog](#out_alllog) - - [Density of states](#density-of-states) - - [dos\_edelta\_ev](#dos_edelta_ev) - - [dos\_sigma](#dos_sigma) - - [dos\_scale](#dos_scale) - - [dos\_emin\_ev](#dos_emin_ev) - - [dos\_emax\_ev](#dos_emax_ev) - - [dos\_nche](#dos_nche) - - [stm\_bias](#stm_bias) - - [ldos\_line](#ldos_line) - - [NAOs](#naos) - - [bessel\_nao\_ecut](#bessel_nao_ecut) - - [bessel\_nao\_tolerence](#bessel_nao_tolerence) - - [bessel\_nao\_rcut](#bessel_nao_rcut) - - [bessel\_nao\_smooth](#bessel_nao_smooth) - - [bessel\_nao\_sigma](#bessel_nao_sigma) - - [DeePKS](#deepks) - - [deepks\_out\_labels](#deepks_out_labels) - - [deepks\_out\_freq\_elec](#deepks_out_freq_elec) - - [deepks\_out\_base](#deepks_out_base) - - [deepks\_scf](#deepks_scf) - - [deepks\_equiv](#deepks_equiv) - - [deepks\_model](#deepks_model) - - [bessel\_descriptor\_lmax](#bessel_descriptor_lmax) - - [bessel\_descriptor\_ecut](#bessel_descriptor_ecut) - - [bessel\_descriptor\_tolerence](#bessel_descriptor_tolerence) - - [bessel\_descriptor\_rcut](#bessel_descriptor_rcut) - - [bessel\_descriptor\_smooth](#bessel_descriptor_smooth) - - [bessel\_descriptor\_sigma](#bessel_descriptor_sigma) - - [deepks\_bandgap](#deepks_bandgap) - - [deepks\_band\_range](#deepks_band_range) - - [deepks\_v\_delta](#deepks_v_delta) - - [deepks\_out\_unittest](#deepks_out_unittest) - - [OFDFT: orbital free density functional theory](#ofdft-orbital-free-density-functional-theory) - - [of\_kinetic](#of_kinetic) - - [of\_method](#of_method) - - [of\_conv](#of_conv) - - [of\_tole](#of_tole) - - [of\_tolp](#of_tolp) - - [of\_tf\_weight](#of_tf_weight) - - [of\_vw\_weight](#of_vw_weight) - - [of\_wt\_alpha](#of_wt_alpha) - - [of\_wt\_beta](#of_wt_beta) - - [of\_extwt\_kappa](#of_extwt_kappa) - - [of\_wt\_rho0](#of_wt_rho0) - - [of\_hold\_rho0](#of_hold_rho0) - - [of\_lkt\_a](#of_lkt_a) - - [of\_xwm\_rho\_ref](#of_xwm_rho_ref) - - [of\_xwm\_kappa](#of_xwm_kappa) - - [of\_read\_kernel](#of_read_kernel) - - [of\_kernel\_file](#of_kernel_file) - - [of\_full\_pw](#of_full_pw) - - [of\_full\_pw\_dim](#of_full_pw_dim) - - [ML-KEDF: machine learning based kinetic energy density functional for OFDFT](#ml-kedf-machine-learning-based-kinetic-energy-density-functional-for-ofdft) - - [of\_ml\_gene\_data](#of_ml_gene_data) - - [of\_ml\_device](#of_ml_device) - - [of\_ml\_feg](#of_ml_feg) - - [of\_ml\_nkernel](#of_ml_nkernel) - - [of\_ml\_kernel](#of_ml_kernel) - - [of\_ml\_kernel\_scaling](#of_ml_kernel_scaling) - - [of\_ml\_yukawa\_alpha](#of_ml_yukawa_alpha) - - [of\_ml\_kernel\_file](#of_ml_kernel_file) - - [of\_ml\_gamma](#of_ml_gamma) - - [of\_ml\_p](#of_ml_p) - - [of\_ml\_q](#of_ml_q) - - [of\_ml\_tanhp](#of_ml_tanhp) - - [of\_ml\_tanhq](#of_ml_tanhq) - - [of\_ml\_chi\_p](#of_ml_chi_p) - - [of\_ml\_chi\_q](#of_ml_chi_q) - - [of\_ml\_gammanl](#of_ml_gammanl) - - [of\_ml\_pnl](#of_ml_pnl) - - [of\_ml\_qnl](#of_ml_qnl) - - [of\_ml\_xi](#of_ml_xi) - - [of\_ml\_tanhxi](#of_ml_tanhxi) - - [of\_ml\_tanhxi\_nl](#of_ml_tanhxi_nl) - - [of\_ml\_tanh\_pnl](#of_ml_tanh_pnl) - - [of\_ml\_tanh\_qnl](#of_ml_tanh_qnl) - - [of\_ml\_tanhp\_nl](#of_ml_tanhp_nl) - - [of\_ml\_tanhq\_nl](#of_ml_tanhq_nl) - - [of\_ml\_chi\_xi](#of_ml_chi_xi) - - [of\_ml\_chi\_pnl](#of_ml_chi_pnl) - - [of\_ml\_chi\_qnl](#of_ml_chi_qnl) - - [of\_ml\_local\_test](#of_ml_local_test) - - [ml\_exx](#ml_exx) - - [TDOFDFT: time dependent orbital free density functional theory](#tdofdft-time-dependent-orbital-free-density-functional-theory) - - [of\_cd](#of_cd) - - [of\_mcd\_alpha](#of_mcd_alpha) - - [Electric field and dipole correction](#electric-field-and-dipole-correction) - - [efield\_flag](#efield_flag) - - [dip\_cor\_flag](#dip_cor_flag) - - [efield\_dir](#efield_dir) - - [efield\_pos\_max](#efield_pos_max) - - [efield\_pos\_dec](#efield_pos_dec) - - [efield\_amp](#efield_amp) - - [Gate field (compensating charge)](#gate-field-compensating-charge) - - [gate\_flag](#gate_flag) - - [zgate](#zgate) - - [block](#block) - - [block\_down](#block_down) - - [block\_up](#block_up) - - [block\_height](#block_height) - - [Exact Exchange (Common)](#exact-exchange-common) - - [exx\_fock\_alpha](#exx_fock_alpha) - - [exx\_erfc\_alpha](#exx_erfc_alpha) - - [exx\_erfc\_omega](#exx_erfc_omega) - - [exx\_separate\_loop](#exx_separate_loop) - - [exx\_hybrid\_step](#exx_hybrid_step) - - [exx\_mixing\_beta](#exx_mixing_beta) - - [Exact Exchange (LCAO in PW)](#exact-exchange-lcao-in-pw) - - [exx\_fock\_lambda](#exx_fock_lambda) - - [Exact Exchange (LCAO)](#exact-exchange-lcao) - - [exx\_pca\_threshold](#exx_pca_threshold) - - [exx\_c\_threshold](#exx_c_threshold) - - [exx\_cs\_inv\_thr](#exx_cs_inv_thr) - - [exx\_v\_threshold](#exx_v_threshold) - - [exx\_dm\_threshold](#exx_dm_threshold) - - [exx\_c\_grad\_threshold](#exx_c_grad_threshold) - - [exx\_v\_grad\_threshold](#exx_v_grad_threshold) - - [exx\_c\_grad\_r\_threshold](#exx_c_grad_r_threshold) - - [exx\_v\_grad\_r\_threshold](#exx_v_grad_r_threshold) - - [exx\_ccp\_rmesh\_times](#exx_ccp_rmesh_times) - - [exx\_opt\_orb\_lmax](#exx_opt_orb_lmax) - - [exx\_opt\_orb\_ecut](#exx_opt_orb_ecut) - - [exx\_opt\_orb\_tolerence](#exx_opt_orb_tolerence) - - [exx\_real\_number](#exx_real_number) - - [exx\_singularity\_correction](#exx_singularity_correction) - - [rpa\_ccp\_rmesh\_times](#rpa_ccp_rmesh_times) - - [exx\_symmetry\_realspace](#exx_symmetry_realspace) - - [out\_ri\_cv](#out_ri_cv) - - [out\_unshrinked\_v](#out_unshrinked_v) - - [exx\_coul\_moment](#exx_coul_moment) - - [exx\_rotate\_abfs](#exx_rotate_abfs) - - [exx\_multip\_moments\_threshold](#exx_multip_moments_threshold) - - [shrink\_abfs\_pca\_thr](#shrink_abfs_pca_thr) - - [shrink\_lu\_inv\_thr](#shrink_lu_inv_thr) - - [Exact Exchange (PW)](#exact-exchange-pw) - - [exxace](#exxace) - - [exx\_gamma\_extrapolation](#exx_gamma_extrapolation) - - [ecutexx](#ecutexx) - - [exx\_thr\_type](#exx_thr_type) - - [exx\_ene\_thr](#exx_ene_thr) - - [Molecular dynamics](#molecular-dynamics) - - [md\_type](#md_type) - - [md\_nstep](#md_nstep) - - [md\_dt](#md_dt) - - [md\_thermostat](#md_thermostat) - - [md\_tfirst](#md_tfirst) - - [md\_tlast](#md_tlast) - - [md\_prec\_level](#md_prec_level) - - [md\_restart](#md_restart) - - [md\_restartfreq](#md_restartfreq) - - [md\_dumpfreq](#md_dumpfreq) - - [md\_neighbor\_skin](#md_neighbor_skin) - - [md\_out\_force](#md_out_force) - - [dump\_force](#dump_force) - - [dump\_vel](#dump_vel) - - [dump\_virial](#dump_virial) - - [md\_seed](#md_seed) - - [md\_tfreq](#md_tfreq) - - [md\_tchain](#md_tchain) - - [md\_pmode](#md_pmode) - - [ref\_cell\_factor](#ref_cell_factor) - - [md\_pcouple](#md_pcouple) - - [md\_pfirst](#md_pfirst) - - [md\_plast](#md_plast) - - [md\_pfreq](#md_pfreq) - - [md\_pchain](#md_pchain) - - [lj\_rule](#lj_rule) - - [lj\_eshift](#lj_eshift) - - [lj\_rcut](#lj_rcut) - - [lj\_epsilon](#lj_epsilon) - - [lj\_sigma](#lj_sigma) - - [pot\_file](#pot_file) - - [dp\_rescaling](#dp_rescaling) - - [dp\_fparam](#dp_fparam) - - [dp\_aparam](#dp_aparam) - - [msst\_direction](#msst_direction) - - [msst\_vel](#msst_vel) - - [msst\_vis](#msst_vis) - - [msst\_tscale](#msst_tscale) - - [msst\_qmass](#msst_qmass) - - [md\_damp](#md_damp) - - [md\_csvr\_tau](#md_csvr_tau) - - [md\_tolerance](#md_tolerance) - - [md\_nraise](#md_nraise) - - [cal\_syns](#cal_syns) - - [dmax](#dmax) - - [DFT+U correction](#dftu-correction) - - [dft\_plus\_u](#dft_plus_u) - - [dft\_plus\_dmft](#dft_plus_dmft) - - [orbital\_corr](#orbital_corr) - - [hubbard\_u](#hubbard_u) - - [yukawa\_potential](#yukawa_potential) - - [yukawa\_lambda](#yukawa_lambda) - - [uramping](#uramping) - - [omc](#omc) - - [onsite\_radius](#onsite_radius) - - [Spin-Constrained DFT](#spin-constrained-dft) - - [sc\_mag\_switch](#sc_mag_switch) - - [decay\_grad\_switch](#decay_grad_switch) - - [sc\_thr](#sc_thr) - - [nsc](#nsc) - - [nsc\_min](#nsc_min) - - [alpha\_trial](#alpha_trial) - - [sccut](#sccut) - - [sc\_drop\_thr](#sc_drop_thr) - - [sc\_scf\_thr](#sc_scf_thr) - - [sc\_direction\_only](#sc_direction_only) - - [sc\_lambda\_strategy](#sc_lambda_strategy) - - [sc\_scan\_lambda\_start](#sc_scan_lambda_start) - - [sc\_scan\_lambda\_end](#sc_scan_lambda_end) - - [sc\_scan\_steps](#sc_scan_steps) - - [vdW correction](#vdw-correction) - - [vdw\_method](#vdw_method) - - [vdw\_d4\_xc](#vdw_d4_xc) - - [vdw\_d4\_model](#vdw_d4_model) - - [vdw\_s6](#vdw_s6) - - [vdw\_s8](#vdw_s8) - - [vdw\_a1](#vdw_a1) - - [vdw\_a2](#vdw_a2) - - [vdw\_d](#vdw_d) - - [vdw\_abc](#vdw_abc) - - [vdw\_c6\_file](#vdw_c6_file) - - [vdw\_c6\_unit](#vdw_c6_unit) - - [vdw\_r0\_file](#vdw_r0_file) - - [vdw\_r0\_unit](#vdw_r0_unit) - - [vdw\_cutoff\_type](#vdw_cutoff_type) - - [vdw\_cutoff\_radius](#vdw_cutoff_radius) - - [vdw\_radius\_unit](#vdw_radius_unit) - - [vdw\_cutoff\_width2](#vdw_cutoff_width2) - - [vdw\_cutoff\_width3](#vdw_cutoff_width3) - - [vdw\_cutoff\_period](#vdw_cutoff_period) - - [vdw\_cn\_thr](#vdw_cn_thr) - - [vdw\_cn\_thr\_unit](#vdw_cn_thr_unit) - - [Berry phase and wannier90 interface](#berry-phase-and-wannier90-interface) - - [berry\_phase](#berry_phase) - - [gdir](#gdir) - - [towannier90](#towannier90) - - [nnkpfile](#nnkpfile) - - [wannier\_method](#wannier_method) - - [wannier\_spin](#wannier_spin) - - [out\_wannier\_mmn](#out_wannier_mmn) - - [out\_wannier\_amn](#out_wannier_amn) - - [out\_wannier\_eig](#out_wannier_eig) - - [out\_wannier\_unk](#out_wannier_unk) - - [out\_wannier\_wvfn\_formatted](#out_wannier_wvfn_formatted) - - [RT-TDDFT: Real-Time Time-Dependent Density Functional Theory](#rt-tddft-real-time-time-dependent-density-functional-theory) - - [estep\_per\_md](#estep_per_md) - - [td\_dt](#td_dt) - - [td\_edm](#td_edm) - - [td\_print\_eij](#td_print_eij) - - [td\_propagator](#td_propagator) - - [td\_vext](#td_vext) - - [td\_vext\_dire](#td_vext_dire) - - [td\_stype](#td_stype) - - [td\_ttype](#td_ttype) - - [td\_tstart](#td_tstart) - - [td\_tend](#td_tend) - - [td\_lcut1](#td_lcut1) - - [td\_lcut2](#td_lcut2) - - [td\_gauss\_freq](#td_gauss_freq) - - [td\_gauss\_phase](#td_gauss_phase) - - [td\_gauss\_sigma](#td_gauss_sigma) - - [td\_gauss\_t0](#td_gauss_t0) - - [td\_gauss\_amp](#td_gauss_amp) - - [td\_trape\_freq](#td_trape_freq) - - [td\_trape\_phase](#td_trape_phase) - - [td\_trape\_t1](#td_trape_t1) - - [td\_trape\_t2](#td_trape_t2) - - [td\_trape\_t3](#td_trape_t3) - - [td\_trape\_amp](#td_trape_amp) - - [td\_trigo\_freq1](#td_trigo_freq1) - - [td\_trigo\_freq2](#td_trigo_freq2) - - [td\_trigo\_phase1](#td_trigo_phase1) - - [td\_trigo\_phase2](#td_trigo_phase2) - - [td\_trigo\_amp](#td_trigo_amp) - - [td\_heavi\_t0](#td_heavi_t0) - - [td\_heavi\_amp](#td_heavi_amp) - - [td\_supsine\_amp](#td_supsine_amp) - - [td\_supsine\_freq](#td_supsine_freq) - - [td\_supsine\_phase](#td_supsine_phase) - - [td\_supsine\_sigma](#td_supsine_sigma) - - [td\_supsine\_tstart](#td_supsine_tstart) - - [td\_supsine\_tend](#td_supsine_tend) - - [init\_vecpot\_file](#init_vecpot_file) - - [ocp](#ocp) - - [ocp\_set](#ocp_set) - - [out\_dipole](#out_dipole) - - [out\_current](#out_current) - - [out\_current\_k](#out_current_k) - - [out\_efield](#out_efield) - - [out\_vecpot](#out_vecpot) - - [Variables useful for debugging](#variables-useful-for-debugging) - - [nurse](#nurse) - - [t\_in\_h](#t_in_h) - - [vl\_in\_h](#vl_in_h) - - [vnl\_in\_h](#vnl_in_h) - - [vh\_in\_h](#vh_in_h) - - [vion\_in\_h](#vion_in_h) - - [test\_force](#test_force) - - [test\_stress](#test_stress) - - [test\_skip\_ewald](#test_skip_ewald) - - [Electronic conductivities](#electronic-conductivities) - - [cal\_cond](#cal_cond) - - [cond\_che\_thr](#cond_che_thr) - - [cond\_dw](#cond_dw) - - [cond\_wcut](#cond_wcut) - - [cond\_dt](#cond_dt) - - [cond\_dtbatch](#cond_dtbatch) - - [cond\_smear](#cond_smear) - - [cond\_fwhm](#cond_fwhm) - - [cond\_nonlocal](#cond_nonlocal) - - [Implicit solvation model](#implicit-solvation-model) - - [imp\_sol](#imp_sol) - - [eb\_k](#eb_k) - - [tau](#tau) - - [sigma\_k](#sigma_k) - - [nc\_k](#nc_k) - - [Quasiatomic Orbital (QO) analysis](#quasiatomic-orbital-qo-analysis) - - [qo\_switch](#qo_switch) - - [qo\_basis](#qo_basis) - - [qo\_strategy](#qo_strategy) - - [qo\_screening\_coeff](#qo_screening_coeff) - - [qo\_thr](#qo_thr) - - [PEXSI](#pexsi) - - [pexsi\_npole](#pexsi_npole) - - [pexsi\_inertia](#pexsi_inertia) - - [pexsi\_nmax](#pexsi_nmax) - - [pexsi\_comm](#pexsi_comm) - - [pexsi\_storage](#pexsi_storage) - - [pexsi\_ordering](#pexsi_ordering) - - [pexsi\_row\_ordering](#pexsi_row_ordering) - - [pexsi\_nproc](#pexsi_nproc) - - [pexsi\_symm](#pexsi_symm) - - [pexsi\_trans](#pexsi_trans) - - [pexsi\_method](#pexsi_method) - - [pexsi\_nproc\_pole](#pexsi_nproc_pole) - - [pexsi\_temp](#pexsi_temp) - - [pexsi\_gap](#pexsi_gap) - - [pexsi\_delta\_e](#pexsi_delta_e) - - [pexsi\_mu\_lower](#pexsi_mu_lower) - - [pexsi\_mu\_upper](#pexsi_mu_upper) - - [pexsi\_mu](#pexsi_mu) - - [pexsi\_mu\_thr](#pexsi_mu_thr) - - [pexsi\_mu\_expand](#pexsi_mu_expand) - - [pexsi\_mu\_guard](#pexsi_mu_guard) - - [pexsi\_elec\_thr](#pexsi_elec_thr) - - [pexsi\_zero\_thr](#pexsi_zero_thr) - - [Linear Response TDDFT](#linear-response-tddft) - - [xc\_kernel](#xc_kernel) - - [lr\_init\_xc\_kernel](#lr_init_xc_kernel) - - [lr\_solver](#lr_solver) - - [lr\_thr](#lr_thr) - - [nocc](#nocc) - - [nvirt](#nvirt) - - [lr\_nstates](#lr_nstates) - - [lr\_unrestricted](#lr_unrestricted) - - [abs\_wavelen\_range](#abs_wavelen_range) - - [out\_wfc\_lr](#out_wfc_lr) - - [abs\_gauge](#abs_gauge) - - [abs\_broadening](#abs_broadening) - - [plot\_istate](#plot_istate) - - [exciton\_plot\_type](#exciton_plot_type) - - [exciton\_plot\_format](#exciton_plot_format) - - [exciton\_fixed\_coordinate](#exciton_fixed_coordinate) - - [exciton\_slice\_plane](#exciton_slice_plane) - - [exciton\_slice\_pos](#exciton_slice_pos) - - [exciton\_slice\_npoints](#exciton_slice_npoints) - - [exciton\_slice\_range](#exciton_slice_range) - - [ri\_hartree\_benchmark](#ri_hartree_benchmark) - - [aims\_nbasis](#aims_nbasis) - - [Bethe-Salpeter Equation](#bethe-salpeter-equation) - - [bse\_tda](#bse_tda) - - [bse\_spin\_types](#bse_spin_types) - - [bse\_mem\_save](#bse_mem_save) - - [bse\_ri\_hartree](#bse_ri_hartree) - - [bse\_use\_fine\_kgrid](#bse_use_fine_kgrid) - - [bse\_q\_approx\_mode](#bse_q_approx_mode) - - [bse\_q\_approx\_threshold](#bse_q_approx_threshold) - - [out\_bse\_ab](#out_bse_ab) - - [bse\_continue](#bse_continue) - - [Reduced Density Matrix Functional Theory](#reduced-density-matrix-functional-theory) - - [rdmft](#rdmft) - - [rdmft\_power\_alpha](#rdmft_power_alpha) - - [Density functional perturbation theory](#density-functional-perturbation-theory) - - [dfpt\_qmesh](#dfpt_qmesh) - - [dfpt\_qfile](#dfpt_qfile) - - [dfpt\_compute\_q0](#dfpt_compute_q0) - - [dfpt\_loto](#dfpt_loto) - - [dfpt\_conv\_thr](#dfpt_conv_thr) - - [dfpt\_max\_iter](#dfpt_max_iter) - - [dfpt\_mix\_beta](#dfpt_mix_beta) - -## System variables - -### suffix - -- **Type**: String -- **Description**: In each run, ABACUS will generate a subdirectory in the working directory. This subdirectory contains all the information of the run. The subdirectory name has the format: OUT.suffix, where the suffix is the name you can pick up for your convenience. -- **Default**: ABACUS - -### ntype - -- **Type**: Integer -- **Description**: Number of different atom species in the calculation. -- **Default**: 0 - -### cell_replica - -- **Type**: Three Integers -- **Description**: Replicate the input STRU by Na, Nb, and Nc along its lattice vectors for distributed MDCell workflows. This parameter is only used for classical potentials or machine-learned interatomic potentials. The default is 1 1 1, which preserves the input structure. -- **Default**: 1 1 1 - -### calculation - -- **Type**: String -- **Description**: Specify the type of calculation. - - - scf: perform self-consistent electronic structure calculations - - nscf: perform non-self-consistent electronic structure calculations. A charge density file is required - - relax: perform structure relaxation calculations, the relax_nmax parameter depicts the maximal number of ionic iterations - - cell-relax: perform cell relaxation calculations - - md: perform molecular dynamics simulations - - get_pchg: obtain partial (band-decomposed) charge densities (for LCAO basis only). See out_pchg for more information - - get_wf: obtain real space wave functions (for LCAO basis only). See out_wfc_norm and out_wfc_re_im for more information - - get_s: obtain the overlap matrix formed by localized orbitals (for LCAO basis with multiple k points). The file name is OUT.${suffix}/sr_nao.csr, with the same file format as generated by out_hsr 1 - - gen_bessel: generates projectors, i.e., a series of Bessel functions, for the DeePKS method (for LCAO basis only) - - gen_opt_abfs: generate opt-ABFs as discussed in this article - - test_memory: obtain a rough estimation of memory consumption for the calculation - - test_neighbour: obtain information of neighboring atoms (for LCAO basis only), please specify a positive search_radius manually -- **Default**: scf - -### socket_driver - -- **Type**: Boolean -- **Description**: If set to True, ABACUS keeps the calculation type as scf and receives atomic positions from an external driver through the i-PI socket protocol. - - > Note: Use calculation = scf with socket_driver = True. ABACUS connects to the external i-PI server selected by ABACUS_SOCKET_ADDRESS. If ABACUS_SOCKET_ADDRESS is unset, ABACUS uses localhost:31415. The value can use one of two forms: - - - host:port, for example localhost:31415 or 127.0.0.1:31415, opens a TCP connection to that host and port. Use this when the i-PI server listens on a TCP port. - - path:UNIX, for example /tmp/ipi_abacus_si:UNIX, opens a Unix-domain socket at the given filesystem path. The :UNIX suffix tells ABACUS that the preceding value is a local socket path rather than a TCP host name. This form only works on the same machine. - When using the ASE AbacusSocketIO interface, this environment variable is set automatically from the port or unixsocket calculator argument. - - Socket mode always computes energy. Force and stress extraction follows cal_force and cal_stress independently; disabled properties are sent as protocol padding and marked absent in the ABACUS i-PI extras metadata, not reported as physical zero values. This metadata extension is required for safe optional-property handling: a legacy response with empty extras is accepted only for energy-only use, while a generic client that ignores extras cannot distinguish padding from a computed zero. A non-converged SCF step is returned with scf_converged=false metadata so an external driver can choose its policy. -- **Default**: False - -### esolver_type - -- **Type**: String -- **Description**: Choose the energy solver. - - ksdft: Kohn-Sham density functional theory - - ofdft: orbital-free density functional theory - - tdofdft: time-dependent orbital-free density functional theory - - sdft: stochastic density functional theory - - tddft: real-time time-dependent density functional theory (RT-TDDFT) - - lj: Leonard Jones potential - - dp: DeeP potential - - nep: Neuroevolution Potential - - ks-lr: Kohn-Sham density functional theory + LR-TDDFT (Under Development Feature) - - lr: LR-TDDFT with given KS orbitals (Under Development Feature) - - dfpt: density functional perturbation theory (Under Development Feature) -- **Default**: ksdft - -### symmetry - -- **Type**: String -- **Description**: Takes value 1, 0 or -1. - - -1: No symmetry will be considered. It is recommended to set -1 for non-colinear + soc calculations, where time reversal symmetry is broken sometimes. - - 0: Only time reversal symmetry would be considered in symmetry operations, which implied k point and -k point would be treated as a single k point with twice the weight. - - 1: Symmetry analysis will be performed to determine the type of Bravais lattice and associated symmetry operations (point groups, space groups, primitive cells, and irreducible k-points). For a magnetic system, the symmetry of the initial magnetic structure will be analyzed and preserved. - - > Note: When symmetry is enabled (value 1), k-points are reduced to the irreducible Brillouin zone (IBZ). For explicit k-point lists with custom weights (see KPT file), the custom weights are preserved during symmetry reduction. For Monkhorst-Pack grids, uniform weights are used. -- **Default**: default - -### symmetry_prec - -- **Type**: Real -- **Description**: The accuracy for symmetry analysis. Typically, the default value is good enough, but if the lattice parameters or atom positions in STRU file are not accurate enough, this value should be enlarged. - > Note: if calculation==cell_relax, this value can be dynamically changed corresponding to the variation of accuracy of the lattice parameters and atom positions during the relaxation. -- **Default**: 1.0e-6 -- **Unit**: Bohr - -### symmetry_autoclose - -- **Type**: Boolean -- **Availability**: *[`symmetry`](#symmetry)==1* -- **Description**: Control how to deal with error in symmetry analysis due to inaccurate lattice parameters or atom positions in STRU file, especially useful when calculation==cell-relax - - False: quit with an error message - - True: automatically set symmetry to 0 and continue running without symmetry analysis -- **Default**: True - -### cal_force - -- **Type**: Boolean -- **Description**: If set to True, calculate the force at the end of the electronic iteration. - In socket_driver mode, this flag controls whether the returned frame advertises forces; it is not forced on by the socket protocol. -- **Default**: False - -### kpar - -- **Type**: Integer -- **Description**: Controls k-point parallelism. The value must be positive and should not exceed either the number of k-points or the number of MPI processes. - - For PW calculations, divide all MPI processes into persistent k-point pools. Each pool stores and processes a subset of the k-points. - - For LCAO calculations with lapack, genelpa, elpa, or scalapack_gvx, divide the diagonalization work into temporary k-point pools. After diagonalization, the eigenvalues and distributed wavefunctions are restored for all k-points before occupations, density matrices, and output are evaluated. - - Multi-process LCAO cusolver uses its own active-GPU distribution and does not use this value to define its k-point layout. Other LCAO eigensolvers do not use the temporary k-point-pool implementation. -- **Default**: 1 - -### bndpar - -- **Type**: Integer -- **Availability**: *([`basis_type`](#basis_type)==pw and [`esolver_type`](#esolver_type)==sdft) or ([`basis_type`](#basis_type)==pw and [`esolver_type`](#esolver_type)==ksdft and [`ks_solver`](#ks_solver)==bpcg)* -- **Description**: Controls band-group parallelism for PW SDFT and PW KSDFT calculations using the BPCG eigensolver. - - Within each k-point pool, divide the MPI processes into bndpar band groups. Each group contains NPROC / (kpar * bndpar) processes when bndpar is greater than 1. - - With BPCG, distribute contiguous ranges of global Kohn-Sham bands among the band groups. nbands does not need to be divisible by bndpar, but bndpar cannot exceed a positive nbands. Groups with lower indices receive one additional band when necessary. - - In SDFT, distribute stochastic orbitals among the band groups. When the deterministic Kohn-Sham eigensolver is not BPCG, band group 0 calculates the deterministic orbitals and broadcasts them to the other groups. - - bndpar must be positive and no greater than the number of MPI processes. When bndpar is greater than 1, kpar * bndpar must divide the number of MPI processes exactly. - > Note: For PW calculations on GPU, if the input kpar * bndpar differs from the number of MPI processes, ABACUS automatically sets the effective kpar to NPROC / bndpar. -- **Default**: 1 - -### latname - -- **Type**: String -- **Description**: Specifies the type of Bravias lattice. When set to none, the three lattice vectors are supplied explicitly in STRU file. - - Available options are: - - - none: free structure - - sc: simple cubic - - fcc: face-centered cubic - - bcc: body-centered cubic - - hexagonal: hexagonal - - trigonal: trigonal - - st: simple tetragonal - - bct: body-centered tetragonal - - so: orthorhombic - - baco: base-centered orthorhombic - - fco: face-centered orthorhombic - - bco: body-centered orthorhombic - - sm: simple monoclinic - - bacm: base-centered monoclinic - - triclinic: triclinic -- **Default**: none - -### assume_isolated - -- **Type**: String -- **Description**: Used to perform a calculation assuming an isolated system in a 3D supercell. - - Available options are: - - - none: regular periodic calculation without isolated-system correction. - - makov-payne, m-p, mp: compute the Makov-Payne correction to the total energy and estimate a corrected vacuum level for eigenvalue alignment. This option is available only for cubic lattices (latname = sc, fcc, or bcc). - - Theory: G. Makov and M. C. Payne, Phys. Rev. B 51, 4014 (1995). -- **Default**: none - -### init_wfc - -- **Type**: Vector of string -- **Description**: The method used to initialize wavefunction coefficients. The available options and behavior depend on `basis_type`. - - For `basis_type=pw`, the available options are: - - - `atomic`: Use atomic pseudo wavefunctions from `PP_PSWFC`. If no `PP_PSWFC` states are available, all bands are initialized randomly. If the number of atomic states is smaller than `nbands`, the remaining bands are initialized randomly. - - `atomic+random`: If there are at least `nbands` atomic states, apply an approximately 5% multiplicative random perturbation to the atomic initialization. If there are fewer atomic states than `nbands`, use the atomic states and initialize the remaining bands randomly, as for `atomic`. - - `random`: Initialize all bands with random coefficients. - - `nao`: Use numerical atomic orbitals. If the number of NAO states is smaller than `nbands`, the remaining bands are initialized randomly. - - `nao+random`: Apply an approximately 5% multiplicative random perturbation to the NAO initialization; any bands not covered by NAO states are first initialized randomly. - - `file binary`: Read binary `wf*_pw.dat` files generated with `out_wfc_pw=2` from `read_file_dir`. The files must match the current k points, `nbands`, plane-wave layout, and lattice. The `txt` format is not supported for PW wavefunctions. - - For `basis_type=lcao`, the file options are: - - - `file txt`: Read text `wf*_nao.txt` files generated with `out_wfc_lcao=1` from `read_file_dir`. - - `file binary`: Read binary `wf*_nao.dat` files generated with `out_wfc_lcao=2` from `read_file_dir`. - - The selected format is required; ABACUS does not automatically detect or fall back to the other format. The files must use a compatible NAO basis, match the current k-point and spin setup, and contain enough bands. File initialization matches independent files without geometry-step indices. Files accumulated with `out_app_flag` or files under `WFC/` with a `g*` geometry-step index are not supported. - - For `basis_type=lcao_in_pw`, `init_wfc` is automatically set to `nao`. - - > Note: For `calculation=get_wf` or `calculation=get_pchg`, non-file initialization choices are automatically changed to the file option appropriate for the selected basis. An explicitly selected file format is preserved. If `basis_type=lcao_in_pw` is also used, the final value is `nao`. -- **Default**: atomic - -### init_chg - -- **Type**: String -- **Description**: This variable is used for both plane wave set and localized orbitals set. It indicates the type of starting density. - - - atomic: the density is starting from the summation of the atomic density of single atoms. - - file: the density will be read in from a binary file charge-density.dat first. If it does not exist, the charge density will be read in from cube files. - - wfc: the density will be calculated by wavefunctions and occupations. - - dm: the density will be calculated by real space density matrix(DMR) of LCAO base. - - dm_no_renormalize: same as dm, but the charge density is not renormalized to the number of electrons. - - hr: the real space Hamiltonian matrix(HR) will be read in from file hrs1_nao.csr in directory read_file_dir. - - auto: Abacus first attempts to read the density from a file; if not found, it defaults to using atomic density. -- **Default**: atomic - -### init_vel - -- **Type**: Boolean -- **Description**: - True: read the atom velocity (atomic unit : 1 a.u. = 21.877 Angstrom/fs) from the atom file (STRU) and determine the initial temperature md_tfirst. If md_tfirst is unset or less than zero, init_vel is autoset to be true. - - False: assign value to atom velocity using Gaussian distributed random numbers. -- **Default**: False - -### mem_saver - -- **Type**: Integer -- **Availability**: *[`calculation`](#calculation)==nscf and [`basis_type`](#basis_type)==pw* -- **Description**: Save memory when performing nscf calculations. - - 0: no memory saving techniques are used. - - 1: a memory saving technique will be used for many k point calculations. -- **Default**: 0 - -### cal_stress - -- **Type**: Boolean -- **Description**: If set to True, calculate the stress at the end of the electronic iteration. - In socket_driver mode, this flag independently controls whether the returned frame advertises stress/virial. -- **Default**: False - -### diago_proc - -- **Type**: Integer -- **Availability**: *[`basis_type`](#basis_type)==pw* -- **Description**: - 0: it will be set to the number of MPI processes. - - >0: it specifies the number of processes used for carrying out diagonalization. Must be less than or equal to total number of MPI processes. -- **Default**: 0 - -### nbspline - -- **Type**: Integer -- **Description**: If set to a natural number, a Cardinal B-spline interpolation will be used to calculate Structure Factor. nbspline represents the order of B-spline basis and a larger one can get more accurate results but cost more. It is turned off by default. -- **Default**: -1 - -### kspacing - -- **Type**: Vector of Real (1 or 3 values) -- **Description**: Set the smallest allowed spacing between k points, unit in 1/bohr. It should be larger than 0.0, and suggest smaller than 0.25. When you have set this value > 0.0, then the KPT file is unnecessary. The default value 0.0 means that ABACUS will read the applied KPT file. - - > Note: If gamma_only is set to be true, kspacing is invalid. -- **Default**: 0.0 - -### koffset - -- **Type**: Vector of Real (3 values) -- **Description**: Set offsets for automatic k-point mesh generated by kspacing, in each reciprocal direction. This parameter is only effective when kspacing > 0.0 and gamma_only is false. -- **Default**: 0.0 0.0 0.0 - -### kmesh_type - -- **Type**: String -- **Description**: Set mesh type used for automatic k-point mesh generated by kspacing. Available options are gamma and mp. This parameter is only effective when kspacing > 0.0 and gamma_only is false. -- **Default**: gamma - -### min_dist_coef - -- **Type**: Real -- **Description**: A factor related to the allowed minimum distance between two atoms. At the beginning, ABACUS will check the structure, and if the distance of two atoms is shorter than min_dist_coef*(standard covalent bond length), we think this structure is unreasonable. -- **Default**: 0.2 - -### device - -- **Type**: String -- **Description**: Specifies the computing device for ABACUS. - - Available options are: - - - cpu: for CPUs via Intel, AMD, or Other supported CPU devices - - gpu: for GPUs via CUDA or ROCm. - - > Note: ks_solver must also be set to the algorithms supported. lcao_in_pw currently does not support gpu. -- **Default**: cpu - -### precision - -- **Type**: String -- **Availability**: *[`basis_type`](#basis_type)==pw* -- **Description**: Specifies the precision when performing scf calculation. - - single: single precision - - double: double precision -- **Default**: double - -### gint_precision - -- **Type**: String -- **Availability**: *[`basis_type`](#basis_type)==lcao* -- **Description**: Specifies the precision when performing grid integral in LCAO calculations. - - single: single precision - - double: double precision - - mix: mixed precision, starting from single precision and switching to double precision when the SCF residual becomes small enough -- **Default**: double - -### timer_enable_nvtx - -- **Type**: Boolean -- **Description**: Controls whether NVTX profiling labels are emitted by the timer. This feature is only effective on CUDA platforms. - - - True: Enable NVTX profiling labels in the timer. - - False: Disable NVTX profiling labels in the timer. -- **Default**: False - -### cell_factor - -- **Type**: Real -- **Description**: Used in the construction of the pseudopotential tables. For cell-relax calculations, this is automatically set to 2.0. -- **Default**: 1.2 - -### dm_to_rho - -- **Type**: Boolean -- **Description**: Reads density matrix in npz format and calculates electron density. -- **Default**: False - -### chg_extrap - -- **Type**: String -- **Description**: Charge extrapolation method for MD, relaxation, and socket-driven calculations. - - When set to default, ABACUS chooses second-order for md, first-order for - relax/cell-relax and socket_driver calculations, and atomic for other calculations. Socket-driven - molecular dynamics can explicitly set second-order if the external driver - updates structures smoothly enough for second-order extrapolation. -- **Default**: default - -### nb2d - -- **Type**: Integer -- **Description**: In LCAO calculations, the Hamiltonian and overlap matrices are distributed across 2D processor grid. This parameter controls the 2D block size for distribution. -- **Default**: 0 - -### cal_symm_repr - -- **Type**: Integer \[Integer\](optional) -- **Description**: Whether to print the matrix representation of symmetry operation to running log file. If the first value is given as 1, then all matrix representations will be printed. The second optional parameter controls the precision (number of digits) to print, default is 3, which is enough for a quick check. -- **Default**: 1 3 - -[back to top](#full-list-of-input-keywords) - -## Input files - -### stru_file - -- **Type**: String -- **Description**: The name of the structure file containing various information about atom species, including pseudopotential files, local orbitals files, cell information, atom positions, and whether atoms should be allowed to move. -- **Default**: STRU - -### kpoint_file - -- **Type**: String -- **Description**: The name of the k-point file that includes the k-point information of Brillouin zone. -- **Default**: KPT - -### pseudo_dir - -- **Type**: String -- **Description**: The directory of pseudopotential files. This parameter is combined with the pseudopotential filenames in the STRU file to form the complete pseudopotential file paths. -- **Default**: "" - -### orbital_dir - -- **Type**: String -- **Description**: The directory to save numerical atomic orbitals. This parameter is combined with orbital filenames in the STRU file to form the complete orbital file paths. -- **Default**: "" - -### read_file_dir - -- **Type**: String -- **Description**: Location of files, such as the electron density (chgs1.cube), required as a starting point. -- **Default**: OUT.$suffix - -### restart_load - -- **Type**: Boolean -- **Availability**: *[`basis_type`](#basis_type)==lcao* -- **Description**: If restart_save is set to true and an electronic iteration is finished, calculations can be restarted from the charge density file, which are saved in the former calculation. -- **Default**: False - -### spillage_outdir - -- **Type**: String -- **Availability**: *[`basis_type`](#basis_type)==pw* -- **Description**: The directory to save the spillage files. -- **Default**: "./" - -[back to top](#full-list-of-input-keywords) - -## Plane wave related variables - -### ecutwfc - -- **Type**: Real -- **Description**: Energy cutoff for plane wave functions. Note that even for localized orbitals basis, you still need to setup an energy cutoff for this system. Because our local pseudopotential parts and the related force are calculated from plane wave basis set. - > Note: ecutwfc and ecutrho can be set simultaneously. If only one parameter is set, abacus will automatically set another parameter based on the 4-time relationship. -- **Default**: 50 for PW basis, 100 for LCAO basis -- **Unit**: Ry - -### ecutrho - -- **Type**: Real -- **Description**: Energy cutoff for charge density and potential. For norm-conserving pseudopotential you should stick to the default value, you can reduce it by a little but it will introduce noise especially on forces and stress. -- **Default**: 4*ecutwfc -- **Unit**: Ry - -### nx - -- **Type**: Integer -- **Description**: If set to a positive number, specifies the number of FFT grid points in x direction. If set to 0, the number will be calculated from ecutrho. - - > Note: You must specify all three dimensions (nx, ny, nz) for this setting to be used. -- **Default**: 0 - -### ny - -- **Type**: Integer -- **Description**: If set to a positive number, specifies the number of FFT grid points in y direction. If set to 0, the number will be calculated from ecutrho. - - > Note: You must specify all three dimensions (nx, ny, nz) for this setting to be used. -- **Default**: 0 - -### nz - -- **Type**: Integer -- **Description**: If set to a positive number, specifies the number of FFT grid points in z direction. If set to 0, the number will be calculated from ecutrho. - - > Note: You must specify all three dimensions (nx, ny, nz) for this setting to be used. -- **Default**: 0 - -### ndx - -- **Type**: Integer -- **Description**: If set to a positive number, specifies the number of FFT grid points for the dense part of charge density in x direction. If set to 0, the number will be calculated from ecutwfc. - - > Note: You must specify all three dimensions (ndx, ndy, ndz) for this setting to be used. These parameters must be used combined with nx, ny, nz. If nx, ny, nz are unset, ndx, ndy, ndz are used as nx, ny, nz. -- **Default**: 0 - -### ndy - -- **Type**: Integer -- **Description**: If set to a positive number, specifies the number of FFT grid points for the dense part of charge density in y direction. If set to 0, the number will be calculated from ecutwfc. - - > Note: You must specify all three dimensions (ndx, ndy, ndz) for this setting to be used. These parameters must be used combined with nx, ny, nz. If nx, ny, nz are unset, ndx, ndy, ndz are used as nx, ny, nz. -- **Default**: 0 - -### ndz - -- **Type**: Integer -- **Description**: If set to a positive number, specifies the number of FFT grid points for the dense part of charge density in z direction. If set to 0, the number will be calculated from ecutwfc. - - > Note: You must specify all three dimensions (ndx, ndy, ndz) for this setting to be used. These parameters must be used combined with nx, ny, nz. If nx, ny, nz are unset, ndx, ndy, ndz are used as nx, ny, nz. -- **Default**: 0 - -### pw_seed - -- **Type**: Integer -- **Availability**: *[`basis_type`](#basis_type)==pw* -- **Description**: Specify the random seed to initialize wave functions. Only positive integers are available. -- **Default**: 0 - -### diag_subspace - -- **Type**: Integer -- **Availability**: *[`basis_type`](#basis_type)==pw and [`ks_solver`](#ks_solver)==dav_subspace* -- **Description**: The method to diagonalize subspace in dav_subspace method. - - 0: by LAPACK - - 1: by GenELPA - - 2: by ScaLAPACK -- **Default**: 0 - -### erf_ecut - -- **Type**: Real -- **Description**: Used in variable-cell molecular dynamics (or in stress calculation). See erf_sigma for details. -- **Default**: 0.0 -- **Unit**: Ry - -### fft_mode - -- **Type**: Integer -- **Description**: Set the mode of FFTW. - - 0: FFTW_ESTIMATE - - 1: FFTW_MEASURE - - 2: FFTW_PATIENT - - 3: FFTW_EXHAUSTIVE -- **Default**: 0 - -### erf_height - -- **Type**: Real -- **Description**: Used in variable-cell molecular dynamics (or in stress calculation). See erf_sigma for details. -- **Default**: 0.0 -- **Unit**: Ry - -### erf_sigma - -- **Type**: Real -- **Description**: In order to recover the accuracy of a constant energy cutoff calculation, the kinetic functional is modified, which is used in variable-cell molecular dynamics (or in stress calculation). -- **Default**: 0.1 -- **Unit**: Ry - -### pw_diag_thr - -- **Type**: Real -- **Description**: Only used when you use ks_solver = cg/dav/dav_subspace/bpcg. It indicates the threshold for the first electronic iteration, from the second iteration the pw_diag_thr will be updated automatically. For nscf calculations with planewave basis set, pw_diag_thr should be <= 1e-3. -- **Default**: 0.01 - -### diago_smooth_ethr - -- **Type**: Boolean -- **Description**: If TRUE, the smooth threshold strategy, which applies a larger threshold (10e-5) for the empty states, will be implemented in the diagonalization methods. (This strategy should not affect total energy, forces, and other ground-state properties, but computational efficiency will be improved.) If FALSE, the smooth threshold strategy will not be applied. -- **Default**: false - -### use_k_continuity - -- **Type**: Boolean -- **Availability**: *[`basis_type`](#basis_type)==pw* -- **Description**: If TRUE, the wavefunctions at k-point will be initialized from the converged wavefunctions at the nearest k-point, which can speed up the SCF convergence. Only works for PW basis. -- **Default**: false - -### pw_diag_nmax - -- **Type**: Integer -- **Availability**: *[`basis_type`](#basis_type)==pw and [`ks_solver`](#ks_solver) in [cg, dav, dav_subspace, bpcg]* -- **Description**: Only useful when you use ks_solver = cg/dav/dav_subspace/bpcg. It indicates the maximal iteration number for cg/david/dav_subspace/bpcg method. -- **Default**: 50 - -### pw_diag_ndim - -- **Type**: Integer -- **Description**: Only useful when you use ks_solver = dav or ks_solver = dav_subspace. It indicates dimension of workspace(number of wavefunction packets, at least 2 needed) for the Davidson method. A larger value may yield a smaller number of iterations in the algorithm but uses more memory and more CPU time in subspace diagonalization. -- **Default**: 4 - -### diago_cg_prec - -- **Type**: Integer -- **Description**: Preconditioner type for conjugate gradient diagonalization method. -- **Default**: 1 - -[back to top](#full-list-of-input-keywords) - -## Numerical atomic orbitals related variables - -### lmaxmax - -- **Type**: Integer -- **Description**: If not equals to 2, then the maximum l channels on LCAO is set to lmaxmax. If 2, then the number of l channels will be read from the LCAO data sets. Normally no input should be supplied for this variable so that it is kept as its default. -- **Default**: 2. - -### lcao_ecut - -- **Type**: Real -- **Description**: Energy cutoff (in Ry) for two-center integrals in LCAO. The two-center integration table are obtained via a k space integral whose upper limit is about sqrt(lcao_ecut). -- **Default**: ecutwfc - -### lcao_dk - -- **Type**: Real -- **Description**: the interval of k points for two-center integrals. The two-center integration table are obtained via a k space integral on a uniform grid with spacing lcao_dk. -- **Default**: 0.01 -- **Unit**: Bohr - -### lcao_dr - -- **Type**: Real -- **Description**: r spacing of the integration table of two-center integrals. -- **Default**: 0.01 -- **Unit**: Bohr - -### lcao_rmax - -- **Type**: Real -- **Description**: Maximum distance for the two-center integration table. -- **Default**: 30 -- **Unit**: Bohr - -### search_radius - -- **Type**: Real -- **Description**: Searching radius in finding the neighbouring atoms. By default the radius will be automatically determined by the cutoffs of orbitals and nonlocal beta projectors. -- **Default**: -1 -- **Unit**: Bohr - -### bx - -- **Type**: Integer -- **Description**: In the matrix operation of grid integral, bx/by/bz grids (in x, y, z directions) are treated as a whole as a matrix element. A different value will affect the calculation speed. The default is 0, which means abacus will automatically calculate these values. -- **Default**: 0 - -### by - -- **Type**: Integer -- **Description**: In the matrix operation of grid integral, bx/by/bz grids (in x, y, z directions) are treated as a whole as a matrix element. A different value will affect the calculation speed. The default is 0, which means abacus will automatically calculate these values. -- **Default**: 0 - -### bz - -- **Type**: Integer -- **Description**: In the matrix operation of grid integral, bx/by/bz grids (in x, y, z directions) are treated as a whole as a matrix element. A different value will affect the calculation speed. The default is 0, which means abacus will automatically calculate these values. -- **Default**: 0 - -### elpa_num_thread - -- **Type**: Integer -- **Description**: Number of threads used in one elpa calculation. - - If the number is below 0 or 0 or beyond the max number of threads, all elpa calculation will be using all mpi threads -- **Default**: -1 - -### num_stream - -- **Type**: Integer -- **Description**: The number of CUDA streams used in LCAO calculations with GPU acceleration. -- **Default**: 4 - -[back to top](#full-list-of-input-keywords) - -## Electronic structure - -### basis_type - -- **Type**: String -- **Description**: Choose the basis set. - - pw: Using plane-wave basis set only. - - lcao: Using localized atomic orbital sets. - - lcao_in_pw: Expand the localized atomic set in plane-wave basis, non-self-consistent field calculation not tested. -- **Default**: pw - -### ks_solver - -- **Type**: String -- **Description**: Choose the diagonalization methods for the Hamiltonian matrix expanded in a certain basis set. - - For plane-wave basis, - - - cg: The conjugate-gradient (CG) method. - - dav: The Davidson algorithm. - - dav_subspace: The Davidson algorithm without orthogonalization operation, this method is the most recommended for efficiency. `pw_diag_ndim` can be set to 2 for this method. - - bpcg: The BPCG method, which is a block-parallel Conjugate Gradient (CG) method, typically exhibits higher acceleration in a GPU environment. The BPCG method is currently under testing and is not recommended for use. - - For numerical atomic orbitals basis, - - - lapack: Use LAPACK to diagonalize the Hamiltonian, only used for serial version - - genelpa: Use the CPU-only GEN-ELPA interface to diagonalize the Hamiltonian. - - scalapack_gvx: Use Scalapack to diagonalize the Hamiltonian. - - cusolver: Use CUSOLVER to diagonalize the Hamiltonian, at least one GPU is needed. - - cusolvermp: Use CUSOLVER to diagonalize the Hamiltonian, supporting multi-GPU devices. Note that you should set the number of MPI processes equal to the number of GPUs. - - elpa: The ELPA solver supports both CPU and GPU. By setting the `device` to GPU, you can launch the ELPA solver with GPU acceleration (provided that you have installed a GPU-supported version of ELPA, which requires you to manually compile and install ELPA, and the ABACUS should be compiled with -DENABLE_ELPA=ON and -DUSE_CUDA=ON). The ELPA solver also supports multi-GPU acceleration. - - If you set ks_solver=`genelpa` for basis_type=`pw`, the program will stop with an error message: - - ``text genelpa can not be used with plane wave basis. `` - - Then the user has to correct the input file and restart the calculation. -- **Default**: - - PW basis: cg. - - LCAO basis: - - genelpa (if compiling option `ENABLE_ELPA` has been set) - - lapack (if compiling option `ENABLE_MPI` has not been set) - - scalapack_gvx (if compiling option `ENABLE_ELPA` has not been set and compiling option `ENABLE_MPI` has been set) - - cusolver (if compiling option `USE_CUDA` has been set) - -### nbands - -- **Type**: Integer -- **Description**: The number of Kohn-Sham orbitals to calculate. It is recommended to setup this value, especially when smearing techniques are utilized, more bands should be included. - -### nelec - -- **Type**: Real -- **Description**: - 0.0: The total number of electrons will be calculated by the sum of valence electrons (i.e. assuming neutral system). - - >0.0: this denotes the total number of electrons in the system. Must be less than 2*nbands. -- **Default**: 0.0 - -### nelec_delta - -- **Type**: Real -- **Description**: The total number of electrons will be calculated by nelec+nelec_delta. -- **Default**: 0.0 - -### nupdown - -- **Type**: Real -- **Description**: - 0.0: no constrain apply to system. - - >0.0: The different number of electrons between spin-up and spin-down channels. The range of value must be in [-nelec ~ nelec]. It is one type of constrainted DFT method, two Fermi energies will be calculated. -- **Default**: 0.0 - -### dft_functional - -- **Type**: String -- **Description**: In our package, the XC functional can either be set explicitly using the dft_functional keyword in INPUT file. If dft_functional is not specified, ABACUS will use the xc functional indicated in the pseudopotential file. On the other hand, if dft_functional is specified, it will overwrite the functional from pseudopotentials and performs calculation with whichever functional the user prefers. We further offer two ways of supplying exchange-correlation functional. The first is using 'short-hand' names. A complete list of 'short-hand' expressions can be found in the source code. Supported density functionals are: - - LDA functionals - - LDA (equivalent with PZ and SLAPZNOGXNOGC), PWLDA - - GGA functionals - - PBE (equivalent with SLAPWPBXPBC), PBESOL, REVPBE, WC, BLYP, BP(referred to BP86), PW91, HCTH, OLYP, BLYP_LR - - meta-GGA functionals - - SCAN (require LIBXC) - - Hybrid functionals - - PBE0, HF - - If LIBXC is available, additional short-hand names of hybrid functionals are supported: HSE(referred to HSE06), B3LYP, LC_PBE, LC_WPBE, LRC_WPBE, LRC_WPBEH, CAM_PBEH, WP22, CWP22, MULLER (equivalent with POWER) - - Hybrid meta-GGA functionals - - SCAN0 (require LIBXC) - - The other way is only available when compiling with LIBXC, and it allows for supplying exchange-correlation functionals as combinations of LIBXC keywords for functional components, joined by a plus sign, for example, dft_functional='LDA_X_1D_EXPONENTIAL+LDA_C_1D_CSC'. -- **Default**: Used the same as DFT functional as specified in the pseudopotential files. - -### xc_temperature - -- **Type**: Real -- **Description**: Specifies temperature when using temperature-dependent XC functionals (KSDT and so on). -- **Default**: 0.0 -- **Unit**: Ry - -### xc_exch_ext - -- **Type**: Integer followed by Real values -- **Description**: Customized parameterization of the exchange part of an XC functional. The first value should be the Libxc ID of the original functional, followed by the complete list of external parameters required by the linked Libxc version. If unset, Libxc's own default parameters are used. For functional IDs and parameter definitions, refer to the Libxc documentation and source code. - - > Note: Solely setting this keyword will take no effect on XC functionals. One should also set dft_functional to the corresponding functional to apply the customized parameterization. Presently this feature can only support parameterization on one exchange functional. - -### xc_corr_ext - -- **Type**: Integer followed by Real values -- **Description**: Customized parameterization of the correlation part of an XC functional. The first value should be the Libxc ID of the original functional, followed by the complete list of external parameters required by the linked Libxc version. If unset, Libxc's own default parameters are used. For functional IDs and parameter definitions, refer to the Libxc documentation and source code. - - > Note: Solely setting this keyword will take no effect on XC functionals. One should also set dft_functional to the corresponding functional to apply the customized parameterization. Presently this feature can only support parameterization on one correlation functional. - -### pseudo_rcut - -- **Type**: Real -- **Description**: Cut-off of radial integration for pseudopotentials. -- **Default**: 15 -- **Unit**: Bohr - -### pseudo_mesh - -- **Type**: Boolean -- **Description**: - 0: Use a mesh for radial integration of pseudopotentials. - - 1: Use the mesh that is consistent with quantum espresso -- **Default**: 0 - -### nspin - -- **Type**: Integer -- **Description**: The number of spin components of wave functions. - - 1: Spin degeneracy - - 2: Collinear spin polarized. - - 4: Noncollinear or spin-orbit calculations. Set nspin to 4 explicitly when noncolin or lspinorb is enabled. -- **Default**: 1 - -### smearing_method - -- **Type**: String -- **Description**: It indicates which occupation and smearing method is used in the calculation. - - fixed: fixed occupations (available for non-coductors only) - - gauss or gaussian: Gaussian smearing method. - - mp: methfessel-paxton smearing method; recommended for metals. - - mp2: 2-nd methfessel-paxton smearing method; recommended for metals. - - mv or cold: marzari-vanderbilt smearing method. - - fd: Fermi-Dirac smearing method: and smearing_sigma below is the temperature (in Ry). -- **Default**: gauss - -### smearing_sigma - -- **Type**: Real -- **Description**: Energy range for smearing. -- **Default**: 0.015 -- **Unit**: Ry - -### smearing_sigma_temp - -- **Type**: Real -- **Description**: Energy range for smearing, smearing_sigma = 1/2 kB smearing_sigma_temp. -- **Default**: 2 * smearing_sigma / kB. -- **Unit**: K - -### mixing_type - -- **Type**: String -- **Description**: Charge mixing methods. - - plain: Just simple mixing. - - pulay: Standard Pulay method. P. Pulay Chemical Physics Letters, (1980) - - broyden: Simplified modified Broyden method. D.D. Johnson Physical Review B (1988) - - In general, the convergence of the Broyden method is slightly faster than that of the Pulay method. -- **Default**: broyden - -### mixing_beta - -- **Type**: Real -- **Description**: In general, the formula of charge mixing can be written as rho_new = rho_old + mixing_beta * drho, where rho_new represents the new charge density after charge mixing, rho_old represents the charge density in previous step, drho is obtained through various mixing methods, and mixing_beta is set by this parameter. A lower value of 'mixing_beta' results in less influence of drho on rho_new, making the self-consistent field (SCF) calculation more stable. However, it may require more steps to achieve convergence. We recommend the following options: - - 0.8: nspin=1 - - 0.4: nspin=2 and nspin=4 - - 0: keep charge density unchanged, usually used for restarting with init_chg=file or testing. - - 0.1 or less: if convergence of SCF calculation is difficult to reach, please try 0 < mixing_beta < 0.1. - A progressive tuning strategy might help, for example, 0.4 -> 0.1 -> 0.025. - - Note: For low-dimensional large systems, the setup of mixing_beta=0.1, mixing_ndim=20, and mixing_gg0=1.0 usually works well. - - For spin-polarized calculations (nspin=2 or nspin=4) that are difficult to converge, try reducing both mixing_beta and mixing_beta_mag simultaneously, e.g., mixing_beta=0.1 and mixing_beta_mag=0.1 or lower. -- **Default**: 0.8 for nspin=1, 0.4 for nspin=2 and nspin=4. - -### mixing_beta_mag - -- **Type**: Real -- **Description**: Mixing parameter of magnetic density. - - If SCF convergence is difficult with spin polarization (nspin=2 or nspin=4), try reducing both mixing_beta and mixing_beta_mag simultaneously, e.g., mixing_beta=0.1 and mixing_beta_mag=0.1 or lower. -- **Default**: 4*mixing_beta, but the maximum value is 1.6. - -### mixing_ndim - -- **Type**: Integer -- **Description**: It indicates the mixing dimensions in Pulay or Broyden. Pulay and Broyden method use the density from previous mixing_ndim steps and do a charge mixing based on this density. - - For systems that are difficult to converge, one could try increasing the value of 'mixing_ndim' to enhance the stability of the self-consistent field (SCF) calculation. -- **Default**: 8 - -### mixing_restart - -- **Type**: Real -- **Description**: If the density difference between input and output drho is smaller than mixing_restart, SCF will restart at next step which means SCF will restart by using output charge density from perivos iteration as input charge density directly, and start a new mixing. Notice that mixing_restart will only take effect once in one SCF. -- **Default**: 0 - -### mixing_dmr - -- **Type**: Boolean -- **Availability**: *[`mixing_restart`](#mixing_restart)>0* -- **Description**: At n-th iteration which is calculated by drho<mixing_restart, SCF will start a mixing for real-space density matrix by using the same coefficiences as the mixing of charge density. -- **Default**: false - -### mixing_gg0 - -- **Type**: Real -- **Description**: Controls the Kerker preconditioner for charge-density mixing. - - >0: Enables Kerker scaling to suppress long-wavelength (small-G) charge-density fluctuations. Setting mixing_gg0 = 1.0 is normally a good starting point. This setting has no effect when mixing_beta <= 0.1 because the charge-density Kerker preconditioner is bypassed. - - 0: No Kerker scaling is performed. - - For systems that are difficult to converge, particularly metallic systems, enabling Kerker scaling may aid in achieving convergence. -- **Default**: 1.0 - -### mixing_gg0_mag - -- **Type**: Real -- **Description**: Controls the Kerker preconditioner for magnetic-density mixing. It is disabled by default and is generally only recommended for systems whose magnetic density is difficult to converge. - - The magnetic-density Kerker preconditioner is bypassed when mixing_beta_mag <= 0.1, so mixing_gg0_mag has no effect in that regime. It is also unavailable when the charge-density Kerker preconditioner itself is bypassed. -- **Default**: 0.0 - -### mixing_gg0_min - -- **Type**: Real -- **Description**: Sets the lower bound used by the Kerker filter. The lower bound is evaluated as mixing_gg0_min / mixing_beta for charge-density mixing and mixing_gg0_min / mixing_beta_mag for magnetic-density mixing. - - In the current implementation, the automatic bypass thresholds are fixed independently of mixing_gg0_min: charge-density Kerker is bypassed when mixing_beta <= 0.1, and magnetic-density Kerker is bypassed when mixing_beta_mag <= 0.1. Changing mixing_gg0_min does not change these thresholds or re-enable Kerker. -- **Default**: 0.1 - -### mixing_angle - -- **Type**: Real -- **Availability**: *[`nspin`](#nspin)==4* -- **Description**: Normal broyden mixing can give the converged result for a given magnetic configuration. If one is not interested in the energies of a given magnetic configuration but wants to determine the ground state by relaxing the magnetic moments' directions, one cannot rely on the standard Broyden mixing algorithm. To enhance the ability to find correct magnetic configuration for non-colinear calculations, ABACUS implements a promising mixing method proposed by J. Phys. Soc. Jpn. 82 (2013) 114706. Here, mixing_angle is the angle mixing parameter. In fact, only mixing_angle=1.0 is implemented currently. - - <=0: Normal broyden mixing - - >0: Angle mixing for the modulus with mixing_angle=1.0 -- **Default**: -10.0 - -### mixing_tau - -- **Type**: Boolean -- **Description**: Whether to mix the kinetic energy density. - - True: The kinetic energy density will also be mixed. It seems for general cases, SCF converges fine even without this mixing. However, if there is difficulty in converging SCF for meta-GGA, it might be helpful to turn this on. - - False: The kinetic energy density will not be mixed. - - This setting takes effect only when the selected exchange-correlation functional uses the kinetic energy density, such as a meta-GGA or hybrid meta-GGA functional. -- **Default**: False - -### mixing_dftu - -- **Type**: Boolean -- **Availability**: *[`dft_plus_u`](#dft_plus_u)==1* -- **Description**: Whether to mix the occupation matrices. - - True: The occupation matrices will also be mixed by plain mixing. From experience this is not very helpful if the +U calculation does not converge. - - False: The occupation matrices will not be mixed. -- **Default**: False - -### gamma_only - -- **Type**: Boolean -- **Availability**: *[`basis_type`](#basis_type)==lcao* -- **Description**: Whether to use gamma_only algorithm. - - 0: more than one k-point is used and the ABACUS is slower compared to the gamma only algorithm. - - 1: ABACUS uses gamma only, the algorithm is faster and you don't need to specify the k-points file. - - Note: If gamma_only is set to 1, the KPT file will be overwritten. So make sure to turn off gamma_only for multi-k calculations. -- **Default**: 0 - -### scf_nmax - -- **Type**: Integer -- **Description**: This variable indicates the maximal iteration number for electronic iterations. -- **Default**: 100 - -### scf_thr - -- **Type**: Real -- **Description**: It's the density threshold for electronic iteration. It represents the charge density error between two sequential densities from electronic iterations. Usually for local orbitals, usually 1e-6 may be accurate enough. -- **Default**: 1.0e-9 (plane-wave basis), or 1.0e-7 (localized atomic orbital basis). -- **Unit**: Ry if scf_thr_type=1, dimensionless if scf_thr_type=2 - -### scf_ene_thr - -- **Type**: Real -- **Description**: It's the energy threshold for electronic iteration. It represents the total energy error between two sequential densities from electronic iterations. -- **Default**: -1.0. If the user does not set this parameter, it will not take effect. -- **Unit**: eV - -### scf_thr_type - -- **Type**: Integer -- **Description**: Choose the calculation method of convergence criterion. - - 1: the criterion is defined in reciprocal space, which is used in SCF of PW basis with unit Ry. - - 2: the criterion is defined in real space, where is the number of electron, which is used in SCF of LCAO with unit dimensionless. -- **Default**: 1 (plane-wave basis), or 2 (localized atomic orbital basis). - -### scf_os_stop - -- **Type**: Boolean -- **Description**: For systems that are difficult to converge, the SCF process may exhibit oscillations in charge density, preventing further progress toward the specified convergence criteria and resulting in continuous oscillation until the maximum number of steps is reached; this greatly wastes computational resources. To address this issue, this function allows ABACUS to terminate the SCF process early upon detecting oscillations, thus reducing subsequent meaningless calculations. The detection of oscillations is based on the slope of the logarithm of historical drho values. To this end, Least Squares Method is used to calculate the slope of the logarithmically taken drho for the previous scf_os_ndim iterations. If the calculated slope is larger than scf_os_thr, stop the SCF. - - - 0: The SCF will continue to run regardless of whether there is oscillation or not. - - 1: If the calculated slope is larger than scf_os_thr, stop the SCF. -- **Default**: false - -### scf_os_thr - -- **Type**: Real -- **Description**: The slope threshold to determine if the SCF is stuck in a charge density oscillation. If the calculated slope is larger than scf_os_thr, stop the SCF. -- **Default**: -0.01 - -### scf_os_ndim - -- **Type**: Integer -- **Description**: To determine the number of old iterations' drho used in slope calculations. -- **Default**: mixing_ndim - -### sc_os_ndim - -- **Type**: Integer -- **Description**: To determine the number of old iterations to judge oscillation, it occured, more accurate lambda with DeltaSpin method would be calculated, only for PW base. -- **Default**: 5 - -### lspinorb - -- **Type**: Boolean -- **Description**: Whether to consider spin-orbit coupling (SOC) effect in the calculation. - - True: Consider spin-orbit coupling effect. When enabled: - - nspin must be explicitly set to 4 (noncollinear spin representation) - - Symmetry is automatically disabled (SOC breaks inversion symmetry) - - Requires full-relativistic pseudopotentials with has_so=true in the UPF header - - False: Do not consider spin-orbit coupling effect. - - Common Error: "no soc upf used for lspinorb calculation" - ensure you are using full-relativistic pseudopotentials -- **Default**: False - -### noncolin - -- **Type**: Boolean -- **Description**: Whether to allow non-collinear magnetic moments, where magnetization can point in arbitrary directions (x, y, z components) rather than being constrained to the z-axis. - - True: Allow non-collinear polarization. When enabled: - - nspin must be explicitly set to 4 - - Wave function dimension is doubled (npol=2), and the number of occupied states is doubled - - Charge density has 4 components (Pauli spin matrices) - - Cannot be used with gamma_only=true - - Can be combined with lspinorb=true for SOC effects with non-collinear magnetism - - False: Do not allow non-collinear polarization (magnetization constrained to z-axis). - - Relationship with lspinorb: - - noncolin=0, lspinorb=1: SOC with z-axis magnetism only (for non-magnetic materials with SOC) - - noncolin=1, lspinorb=0: Non-collinear magnetism without SOC - - noncolin=1, lspinorb=1: Both non-collinear magnetism and SOC -- **Default**: False - -### soc_lambda - -- **Type**: Real -- **Availability**: *[`lspinorb`](#lspinorb)==true* -- **Description**: Modulates the strength of spin-orbit coupling effect. Sometimes, for some real materials, both scalar-relativistic and full-relativistic pseudopotentials cannot describe the exact spin-orbit coupling. Artificial modulation may help in such cases. - - soc_lambda, which has value range [0.0, 1.0], is used to modulate SOC effect: - - - soc_lambda 0.0: Scalar-relativistic case (no SOC) - - soc_lambda 1.0: Full-relativistic case (full SOC) - - Intermediate values: Partial-relativistic SOC (interpolation between scalar and full) - - Use case: When experimental or high-level theoretical results suggest that the SOC effect is weaker or stronger than what full-relativistic pseudopotentials predict, you can adjust this parameter to match the target behavior. -- **Default**: 1.0 - -### dfthalf_type - -- **Type**: Integer -- **Description**: DFT-1/2 type: - - 0: DFT-1/2 is off. - - 1: Shell DFT-1/2 method is used. -- **Default**: 0 - -[back to top](#full-list-of-input-keywords) - -## Electronic structure (SDFT) - -### method_sto - -- **Type**: Integer -- **Availability**: *[`esolver_type`](#esolver_type)==sdft* -- **Description**: Different methods to do stochastic DFT - - 1: Calculate twice, this method cost less memory but is slower. - - 2: Calculate once but needs much more memory. This method is much faster. Besides, it calculates with a smaller nche_sto. However, when the memory is not enough, only method 1 can be used. - - other: use 2 -- **Default**: 2 - -### nbands_sto - -- **Type**: Integer or string -- **Availability**: *[`esolver_type`](#esolver_type)==sdft* -- **Description**: The number of stochastic orbitals - - 1-1000000: Perform stochastic DFT. Increasing the number of bands improves accuracy and reduces stochastic errors; To perform mixed stochastic-deterministic DFT, you should set nbands, which represents the number of KS orbitals. - - 0: Invalid. Use all for the complete-basis SDFT mode. - - all: All complete basis sets are used to replace stochastic orbitals with the Chebyshev method (CT), resulting in the same results as KSDFT without stochastic errors. -- **Default**: 256 - -### nche_sto - -- **Type**: Integer -- **Availability**: *[`esolver_type`](#esolver_type)==sdft* -- **Description**: Chebyshev expansion orders for stochastic DFT. -- **Default**: 100 - -### emin_sto - -- **Type**: Real -- **Availability**: *[`esolver_type`](#esolver_type)==sdft* -- **Description**: Trial energy to guess the lower bound of eigen energies of the Hamiltonian Operator. -- **Default**: 0.0 -- **Unit**: Ry - -### emax_sto - -- **Type**: Real -- **Availability**: *[`esolver_type`](#esolver_type)==sdft* -- **Description**: Trial energy to guess the upper bound of eigen energies of the Hamiltonian Operator. -- **Default**: 0.0 -- **Unit**: Ry - -### seed_sto - -- **Type**: Integer -- **Availability**: *[`esolver_type`](#esolver_type)==sdft* -- **Description**: The random seed to generate stochastic orbitals. - - >= 0: Stochastic orbitals have the form of exp(i*theta), where theta is a uniform distribution in [0, 2*pi). - - 0: the seed is decided by time(NULL). - - <= -1: Stochastic orbitals have the form of +1 or -1 with equal probability. - - -1: the seed is decided by time(NULL). -- **Default**: 0 - -### initsto_ecut - -- **Type**: Real -- **Availability**: *[`esolver_type`](#esolver_type)==sdft* -- **Description**: Stochastic wave functions are initialized in a large box generated by "4*initsto_ecut". initsto_ecut should be larger than ecutwfc. In this method, SDFT results are the same when using different cores. Besides, coefficients of the same G are the same when ecutwfc is rising to initsto_ecut. If it is smaller than ecutwfc, it will be turned off. -- **Default**: 0.0 -- **Unit**: Ry - -### initsto_freq - -- **Type**: Integer -- **Availability**: *[`esolver_type`](#esolver_type)==sdft* -- **Description**: Frequency (once each initsto_freq steps) to generate new stochastic orbitals when running md. - - positive integer: Update stochastic orbitals - - 0: Never change stochastic orbitals. -- **Default**: 0 - -### npart_sto - -- **Type**: Integer -- **Availability**: *[`esolver_type`](#esolver_type)==sdft and (([`method_sto`](#method_sto)==2 and [`out_dos`](#out_dos)==1) or ([`basis_type`](#basis_type)==pw and [`cal_cond`](#cal_cond)==true))* -- **Description**: Make memory cost to 1/npart_sto times of the previous one when running the post process of SDFT like DOS or conductivities. -- **Default**: 1 - -[back to top](#full-list-of-input-keywords) - -## Geometry relaxation - -### relax_method - -- **Type**: Vector of string -- **Description**: The method used for geometry optimization. - - First element (algorithm selection): - - - cg: Conjugate gradient (CG) algorithm. - - bfgs: Broyden–Fletcher–Goldfarb–Shanno (BFGS) quasi-Newton algorithm. - - lbfgs: Limited-memory BFGS algorithm, suitable for large systems. - - cg_bfgs: Mixed method starting with CG and switching to BFGS when force convergence reaches relax_cg_thr. - - sd: Steepest descent algorithm. Not recommended for production use. - - Optional second element: - - - cg 1: First optimize ionic positions at fixed cell, then update the cell, and repeat. - - cg 2 or omitted: Simultaneously optimize ionic positions and cell parameters with line search (recommended). - - bfgs 1: Traditional BFGS that updates the Hessian matrix B and then inverts it. - - bfgs 2 or omitted: Default BFGS that directly updates the inverse Hessian (recommended). - - The second element is not accepted by other methods. - - > Note: In the 3.10-LTS version, the type of this parameter is std::string. It can be set to "cg", "bfgs", "cg_bfgs", "bfgs_trad", "lbfgs", "sd", "fire". -- **Default**: cg 2 - -### relax_scale_force - -- **Type**: Real -- **Availability**: *[`relax_method`](#relax_method)=="cg 2"* -- **Description**: The paramether controls the size of the first conjugate gradient step. A smaller value means the first step along a new CG direction is smaller. This might be helpful for large systems, where it is safer to take a smaller initial step to prevent the collapse of the whole configuration. -- **Default**: 0.5 - -### relax_nmax - -- **Type**: Integer -- **Description**: The maximal number of ionic iteration steps. If set to 0, the code performs a quick "dry run", stopping just after initialization. This is useful to check for input correctness and to have the summary printed. -- **Default**: 1 for SCF, 50 for relax and cell-relax calcualtions - -### relax_cg_thr - -- **Type**: Real -- **Availability**: *[`relax_method`](#relax_method)==cg_bfgs* -- **Description**: When relax_method is set to cg_bfgs, a mixed algorithm of conjugate gradient (CG) and Broyden–Fletcher–Goldfarb–Shanno (BFGS) is used. The ions first move according to the CG method, then switch to the BFGS method when the maximum force on atoms is reduced below this threshold. -- **Default**: 0.5 -- **Unit**: eV/Angstrom - -### force_thr - -- **Type**: Real -- **Description**: Threshold of the force convergence. The threshold is compared with the largest force among all of the atoms. The recommended value for using atomic orbitals is 0.04 eV/Angstrom (0.0016 Ry/Bohr). The parameter is equivalent to force_thr_ev except for the unit, you can choose either you like. -- **Default**: 0.001 -- **Unit**: Ry/Bohr (25.7112 eV/Angstrom) - -### force_thr_ev - -- **Type**: Real -- **Description**: Threshold of the force convergence. The threshold is compared with the largest force among all of the atoms. The recommended value for using atomic orbitals is 0.04 eV/Angstrom (0.0016 Ry/Bohr). The parameter is equivalent to force_thr except for the unit. You may choose either you like. -- **Default**: 0.0257112 -- **Unit**: eV/Angstrom (0.03889 Ry/Bohr) - -### force_zero_out - -- **Type**: Real -- **Description**: The atomic forces that are smaller than force_zero_out will be treated as zero. -- **Default**: 0.0 -- **Unit**: eV/Angstrom - -### relax_bfgs_w1 - -- **Type**: Real -- **Availability**: *[`relax_method`](#relax_method) in [bfgs, cg_bfgs]* -- **Description**: Controls the Wolfe condition for the Broyden–Fletcher–Goldfarb–Shanno (BFGS) algorithm used in geometry relaxation. This parameter sets the sufficient decrease condition (c1 in Wolfe conditions). For more information, see Phys. Chem. Chem. Phys., 2000, 2, 2177. -- **Default**: 0.01 - -### relax_bfgs_w2 - -- **Type**: Real -- **Availability**: *[`relax_method`](#relax_method) in [bfgs, cg_bfgs]* -- **Description**: Controls the Wolfe condition for the Broyden–Fletcher–Goldfarb–Shanno (BFGS) algorithm used in geometry relaxation. This parameter sets the curvature condition (c2 in Wolfe conditions). For more information, see Phys. Chem. Chem. Phys., 2000, 2, 2177. -- **Default**: 0.5 - -### relax_bfgs_rmax - -- **Type**: Real -- **Availability**: *[`relax_method`](#relax_method) in [bfgs, cg_bfgs]* -- **Description**: Maximum allowed total displacement of all atoms during geometry optimization. The sum of atomic displacements can increase during optimization steps but cannot exceed this value. -- **Default**: 0.8 -- **Unit**: Bohr - -### relax_bfgs_rmin - -- **Type**: Real -- **Availability**: *[`relax_method`](#relax_method)=="bfgs 1"* -- **Description**: Minimum allowed total displacement of all atoms. When the total atomic displacement falls below this value and force convergence is not achieved, the calculation will terminate. Note: This parameter is not used in the default BFGS algorithm (relax_method = bfgs 2 or bfgs). -- **Default**: 1e-5 -- **Unit**: Bohr - -### relax_bfgs_init - -- **Type**: Real -- **Availability**: *[`relax_method`](#relax_method) in [bfgs, cg_bfgs]* -- **Description**: Initial total displacement of all atoms in the first BFGS step. This sets the scale for the initial movement. -- **Default**: 0.5 -- **Unit**: Bohr - -### stress_thr - -- **Type**: Real -- **Description**: The threshold of the stress convergence. The threshold is compared with the largest component of the stress tensor. -- **Default**: 0.5 -- **Unit**: kbar - -### press1 - -- **Type**: Real -- **Description**: The external pressures along three axes. Positive input value is taken as compressive stress. -- **Default**: 0 -- **Unit**: kbar - -### press2 - -- **Type**: Real -- **Description**: The external pressures along three axes. Positive input value is taken as compressive stress. -- **Default**: 0 -- **Unit**: kbar - -### press3 - -- **Type**: Real -- **Description**: The external pressures along three axes. Positive input value is taken as compressive stress. -- **Default**: 0 -- **Unit**: kbar - -### fixed_axes - -- **Type**: String -- **Availability**: *[`calculation`](#calculation)==cell-relax* -- **Description**: Specifies which cell degrees of freedom are fixed during variable-cell relaxation. The available options depend on relax_method: - - With relax_method = cg 2 (default), all options are available: - - - None: Default; all cell parameters can relax freely - - volume: Relaxation with fixed volume (allows shape changes) - - shape: Fix shape but allow volume changes (hydrostatic pressure only) - - a: Fix the a-axis lattice vector during relaxation - - b: Fix the b-axis lattice vector during relaxation - - c: Fix the c-axis lattice vector during relaxation - - ab: Fix both a and b axes during relaxation - - ac: Fix both a and c axes during relaxation - - bc: Fix both b and c axes during relaxation - - abc: Fix all three lattice vectors during relaxation - - With relax_method set to cg 1, bfgs, lbfgs, sd, or cg_bfgs, None and a, b, c, ab, ac, bc, abc are available. The shape and volume options require cg 2. - - > Note: For VASP users, see the ISIF correspondence table in the geometry optimization documentation. -- **Default**: None - -### fixed_ibrav - -- **Type**: Boolean -- **Availability**: *[`relax_method`](#relax_method)=="cg 2" and [`latname`](#latname)!=none* -- **Description**: - True: the lattice type will be preserved during relaxation. The lattice vectors are reconstructed to match the specified Bravais lattice type after each update. - - False: No restrictions are exerted during relaxation in terms of lattice type - - > Note: it is possible to use fixed_ibrav with fixed_axes, but please make sure you know what you are doing. For example, if we are doing relaxation of a simple cubic lattice (latname = "sc"), and we use fixed_ibrav along with fixed_axes = "volume", then the cell is never allowed to move and as a result, the relaxation never converges. When both are used, fixed_ibrav is applied first, then fixed_axes = "volume" rescaling is applied. -- **Default**: False - -### fixed_atoms - -- **Type**: Boolean -- **Description**: - True: The direct coordinates of atoms will be preserved during variable-cell relaxation. - - False: No restrictions are exerted on positions of all atoms. However, users can still fix certain components of certain atoms by using the m keyword in STRU file. For the latter option, check the end of this instruction. -- **Default**: False - -[back to top](#full-list-of-input-keywords) - -## Output information - -### out_freq_ion - -- **Type**: Integer -- **Description**: Controls the output interval in ionic steps. When set to a positive integer, information such as charge density, local potential, electrostatic potential, Hamiltonian matrix, overlap matrix, density matrix, Mulliken population analysis, and structure files (STRU{istep} or STRU{istep}.cif, when out_stru is 1 or 2) is printed every n ionic steps. - - > Note: In RT-TDDFT calculations, this parameter is inactive; output frequency is instead controlled by out_freq_td. -- **Default**: 0 - -### out_freq_td - -- **Type**: Integer -- **Description**: Controls the output interval in completed electronic evolution steps during RT-TDDFT calculations. When set to a positive integer n, detailed information (see out_freq_ion) is printed every n electron time-evolution steps (i.e., every STEP OF ELECTRON EVOLVE). For example, if you wish to output information once per ionic step, you should set out_freq_td equal to estep_per_md, since one ionic step corresponds to estep_per_md electronic evolution steps. - - > Note: This parameter is only active in RT-TDDFT mode (esolver_type = tddft). It has no effect in ground-state calculations. -- **Default**: 0 - -### out_freq_elec - -- **Type**: Integer -- **Description**: Output the charge density (only binary format, controlled by out_chg), wavefunction (controlled by out_wfc_pw) per out_freq_elec electronic iterations. Note that they are always output when converged or reach the maximum iterations scf_nmax. -- **Default**: scf_nmax - -### out_chg - -- **Type**: Integer \[Integer\](optional) -- **Description**: The first integer controls whether to output the charge density on real space grids: - - 1: Output the charge density (in Bohr^-3) on real space grids into the density files in the folder `OUT.${suffix}`. The files are named as: - - nspin = 1: `chg.cube`; - - nspin = 2: `chgs1.cube`, and `chgs2.cube`; - - nspin = 4: `chgs1.cube`, `chgs2.cube`, `chgs3.cube`, and `chgs4.cube`; - - When using the Meta-GGA functional, additional files containing the kinetic energy density are also output: - - nspin = 1: `tau.cube`; - - nspin = 2: `taus1.cube`, and `taus2.cube`; - - nspin = 4: `taus1.cube`, `taus2.cube`, `taus3.cube`, and `taus4.cube`; - - 2: On top of 1, also output the initial charge density files. The files are named as: - - out_freq_ion = 0: - - nspin = 1: `chg_ini.cube`; - - nspin = 2: `chgs1_ini.cube` and `chgs2_ini.cube`; - - nspin = 4: `chgs1_ini.cube`, `chgs2_ini.cube`, `chgs3_ini.cube`, and `chgs4_ini.cube`; - - output at every step (overwrite same file) - - out_freq_ion > 0: - - nspin = 1: `chgg{geom_step}_ini.cube` (e.g., `chgg1_ini.cube`); - - nspin = 2: `chgs1g{geom_step}_ini.cube` and `chgs2g{geom_step}_ini.cube`; - - nspin = 4: `chgs1g{geom_step}_ini.cube`, `chgs2g{geom_step}_ini.cube`, `chgs3g{geom_step}_ini.cube`, and `chgs4g{geom_step}_ini.cube`. - - output every out_freq_ion steps - Here, {geom_step} denotes the geometry step index, starting from 1 (geom_step = istep + 1). - - -1: Disable the charge density auto-back-up file `{suffix}-CHARGE-DENSITY.restart`, useful for large systems. - - The second integer controls the precision of the charge density output. If not given, `3` is used as default. For restarting from this file and other high-precision calculations, `10` is recommended. - - In molecular dynamics simulations, the output frequency is controlled by out_freq_ion. - - > Note: In the 3.10-LTS version, the file names are SPIN1_CHG.cube and SPIN1_CHG_INI.cube, etc. -- **Default**: 0 3 - -### out_pot - -- **Type**: Integer \[Integer\](optional) -- **Description**: - 1: Output the total local potential (i.e., local pseudopotential + Hartree potential + XC potential + external electric field (if exists) + dipole correction potential (if exists) + ...) on real space grids (in Ry) into files in the folder OUT.{suffix}. The files are named as: - - nspin = 1: pots1.cube; - - nspin = 2: pots1.cube and pots2.cube; - - nspin = 4: pots1.cube, pots2.cube, pots3.cube, and pots4.cube - - 2: Output the electrostatic potential on real space grids into OUT.{suffix}/pot_es.cube. The Python script named tools/02_postprocessing/average_pot/aveElecStatPot.py can be used to calculate the average electrostatic potential along the z-axis and outputs it into ElecStaticPot_AVE. Please note that the total local potential refers to the local component of the self-consistent potential, excluding the non-local pseudopotential. The distinction between the local potential and the electrostatic potential is as follows: local potential = electrostatic potential + XC potential. - - 3: Apart from 1, also output the total local potential of the initial charge density. The files are named as: - - out_freq_ion = 0: - - nspin = 1: `pot_ini.cube`; - - nspin = 2: `pots1_ini.cube` and `pots2_ini.cube`; - - nspin = 4: `pots1_ini.cube`, `pots2_ini.cube`, `pots3_ini.cube`, and `pots4_ini.cube`; - - output at every step (overwrite same file) - - out_freq_ion > 0: - - nspin = 1: `potg{geom_step}_ini.cube` (e.g., `potg1_ini.cube`); - - nspin = 2: `pots1g{geom_step}_ini.cube` and `pots2g{geom_step}_ini.cube`; - - nspin = 4: `pots1g{geom_step}_ini.cube`, `pots2g{geom_step}_ini.cube`, `pots3g{geom_step}_ini.cube`, and `pots4g{geom_step}_ini.cube`. - - output every out_freq_ion steps - Here, {geom_step} denotes the geometry step index, starting from 1 (geom_step = istep + 1). - - The optional second integer controls the output precision. If not provided, the default precision is 8. - - In molecular dynamics calculations, the output frequency is controlled by out_freq_ion. - - > Note: In the 3.10-LTS version, the file names are SPIN1_POT.cube and SPIN1_POT_INI.cube, etc. -- **Default**: 0 - -### out_dmk - -- **Type**: Boolean \[Integer\](optional) -- **Availability**: *[`basis_type`](#basis_type)==lcao* -- **Description**: Whether to output the density matrix for each k-point into files in the folder OUT.${suffix}. For current develop versions, out_dmk writes *_nao.txt files and includes a g{istep} index in the file name: - - For gamma only case: - - nspin = 1 and 4: dmg1_nao.txt; - - nspin = 2: dms1g1_nao.txt and dms2g1_nao.txt for the two spin channels. - - For multi-k points case: - - nspin = 1 and 4: dmk1g1_nao.txt, dmk2g1_nao.txt, ...; - - nspin = 2: dmk1s1g1_nao.txt... and dmk1s2g1_nao.txt... for the two spin channels. - - Here, g{istep} denotes the geometry/step index in the output file name. - - > Note: Version difference (develop vs 3.10-LTS): - - In develop, out_dmk supports both gamma-only and multi-k-point density-matrix output. - - In 3.10-LTS, the corresponding keyword is out_dm, and the output files are SPIN1_DM and SPIN2_DM, etc. -- **Default**: False - -### out_dmr - -- **Type**: Boolean \[Integer\](optional) -- **Availability**: *[`basis_type`](#basis_type)==lcao and [`gamma_only`](#gamma_only)==0* -- **Description**: Whether to output the density matrix with Bravias lattice vector R index into files in the folder OUT.${suffix}. The files are named as dmr{s}{spin index}{g}{geometry index}{_nao} + {".csr"}. Here, 's' refers to spin, where s1 means spin up channel while s2 means spin down channel, and the sparse matrix format 'csr' is mentioned in out_hsr. Finally, if out_app_flag is set to false, the file name contains the optional 'g' index for each ionic step that may have different geometries, and if out_app_flag is set to true, the density matrix with respect to Bravias lattice vector R accumulates during ionic steps: - - nspin = 1: dmrs1_nao.csr; - - nspin = 2: dmrs1_nao.csr and dmrs2_nao.csr for the two spin channels. - - > Note: In the 3.10-LTS version, the parameter is named out_dm1, and the file names are data-DMR-sparse_SPIN0.csr and data-DMR-sparse_SPIN1.csr, etc. -- **Default**: False - -### out_wfc_pw - -- **Type**: Integer -- **Availability**: *[`basis_type`](#basis_type)==pw and [`esolver_type`](#esolver_type)==ksdft* -- **Description**: Controls whether plane-wave Kohn-Sham wavefunction coefficients are written to `OUT.${suffix}/`. - - Available values are: - - - `0`: Do not write wavefunction coefficients. - - `1`: Write text files with the `.txt` suffix. - - `2`: Write binary files with the `.dat` suffix. - - The file-name pattern is `wfk{k}[s{spin}][g{geometry step}][e{electronic iteration}]_pw.txt` for `out_wfc_pw=1` and `wfk{k}[s{spin}][g{geometry step}][e{electronic iteration}]_pw.dat` for `out_wfc_pw=2`. All PW output files include a `k*` label, including Gamma-only calculations. Without geometry-step or electronic-iteration indices, representative names are `wfk1_pw.txt` or `wfk1_pw.dat` for `nspin=1`, `wfk1s1_pw.txt` and `wfk1s2_pw.txt` or their `.dat` equivalents for `nspin=2`, and `wfk1s4_pw.txt` or `wfk1s4_pw.dat` for `nspin=4`. - - With `out_freq_ion=0`, files are written only when the electronic calculation converges or reaches `scf_nmax`; no `g*` or `e*` index is added. During structural relaxation or molecular dynamics, later ionic steps overwrite the same unindexed files. With `out_freq_ion` > 0, output is restricted to the ionic steps selected by `out_freq_ion` and is written when the electronic iteration is a multiple of `out_freq_elec`, when the calculation converges, or when it reaches `scf_nmax`. Both `g*` and `e*` indices are then added, including for a static `calculation=scf` or `calculation=nscf` run. - - With `init_wfc file binary`, ABACUS reads only unindexed binary `wf*_pw.dat` files from `read_file_dir`. Such directly reusable files are normally generated with `out_wfc_pw=2` and `out_freq_ion=0`. Text `wf*_pw.txt` files and files containing `g*` or `e*` indices are not matched automatically. - - > Note: In the 3.10-LTS version, the binary files are named `WAVEFUNC1.dat`, `WAVEFUNC2.dat`, etc. -- **Default**: 0 - -### out_wfc_lcao - -- **Type**: Integer -- **Availability**: *[`basis_type`](#basis_type)==lcao* -- **Description**: Whether to output the electronic wavefunction coefficients into files and store them in the folder OUT.${suffix}. The files are named as wf{s}{spin index}{k(optional)}{k-point index}{g(optional)}{geometry index1}{_nao} + {".txt"/".dat"}. Here, 's' refers to spin, where s1 means spin up channel while s2 means spin down channel, and 's12' refer to spinor wave functions that contains both spin channels with spin-orbital coupling or noncollinear calculations enabled. In addition, if 'gamma_only' is set to 0, then the optinoal k-point sampling index appears with the k-point index attached to the electronic wave function file names. Finally, if out_app_flag is set to false, the file name contains the optional 'g' index for each ionic step that may have different geometries, and if out_app_flag is set to true, the wave functions accumulate during ionic steps. If the out_app_flag is set to false, a new folder named WFC will be created, and the wave function files will be saved into it. - - 0: no output - - 1: (txt format) - - gamma-only: wfs1_nao.txt or wfs2_nao.txt, ...; - - non-gamma-only: wfs1k1_nao.txt or wfs1k2_nao.txt, ...; - - 2: (binary format) - - gamma-only: wfs1_nao.dat or wfs2_nao.dat, ...; - - non-gamma-only: wfs1k1_nao.dat or wfs1k2_nao.dat, .... - - The corresponding sequence of the orbitals can be seen in Basis Set. - - Also controled by out_freq_ion and out_app_flag. - - > Note: In the 3.10-LTS version, the file names are WFC_NAO_GAMMA1_ION1.txt and WFC_NAO_K1_ION1.txt, etc. -- **Default**: 0 - -### out_dos - -- **Type**: Integer -- **Description**: Whether to output the density of states (DOS). For more information, refer to the dos.md. - - 0: no output - - 1: output the density of states (DOS) - - nspin=1 or 4: doss1g{geom}_{basis}.txt, where geom is the geometry index when cell changes or ions move while basis is either pw or nao. - - nspin=2: doss1g{geom}_{basis}.txt and doss2g{geom}_{basis}.txt for two spin channles. - - 2: (LCAO) output the density of states (DOS) and the projected density of states (PDOS) - - 3: output the Fermi surface file (fermi.bxsf) in BXSF format that can be visualized by XCrySDen -- **Default**: 0 - -### out_ldos - -- **Type**: Integer \[Integer\](optional) -- **Description**: Whether to output the local density of states (LDOS), optionally output precision can be set by a second parameter, default is 3. - - 0: no output - - 1: output the partial charge density for given bias (controlled by stm_bias) in cube file format, which can be used to plot scanning tunneling spectroscopys to mimick STM images using the Python script plot.py. - - 2: output LDOS along a line in real space (controlled by ldos_line). Parameters used to control DOS output are also valid for LDOS. - - 3: output both two LDOS modes above. -- **Default**: 0 - -### out_band - -- **Type**: Boolean \[Integer\](optional) -- **Description**: Whether to output the eigenvalues of the Hamiltonian matrix (in eV) into the running log during electronic iterations and into a file at the end of calculations. The former can be used with the 'out_freq_elec' parameter while the latter option allows the output precision to be set via a second parameter, with a default value of 8. The output file names are: - - nspin = 1 or 4: eig.txt; - - nspin = 2: eigs1.txt and eigs2.txt; - - For more information, refer to the band.md -- **Default**: False - -### out_proj_band - -- **Type**: Boolean -- **Description**: Whether to output the projected band structure. For more information, refer to the band.md -- **Default**: False - -### out_stru - -- **Type**: Integer -- **Description**: Controls the output of structure files per ionic step in geometry relaxation calculations. The files are written to the OUT.{suffix}/ directory. Each file corresponds to the structure at RELAX STEP ${istep}, i.e., the structure for which that step's energy was computed (before the relax move), and includes a header comment with the ABACUS version, timestamp, energy, and stress tensor. When out_freq_ion is positive, the numbered files STRU{istep} (or STRU{istep}.cif) are written every out_freq_ion steps; when out_freq_ion is 0, no numbered files are output. - - 0: No structure files are output. - - 1: ABACUS STRU format files are output. The latest structure is written to STRU_NOW (overwritten each step), the numbered file STRU{istep} (e.g., STRU1, STRU2) is written every out_freq_ion steps (when out_freq_ion is positive), and the final converged structure is written to STRU_FINAL. No CIF files are output. - - 2: CIF format files are output. The latest structure is written to STRU_NOW.cif (overwritten each step), the numbered file STRU{istep}.cif (e.g., STRU1.cif, STRU2.cif) is written every out_freq_ion steps (when out_freq_ion is positive), and the final converged structure is written to STRU_FINAL.cif. No non-CIF files are output. - > Note: For backward compatibility, true/false (case insensitive) are accepted and converted to 1/0. -- **Default**: 1 - -### out_level - -- **Type**: String -- **Description**: Control the output level of information in OUT.{calculation}.log. - - ie: electronic iteration level, which prints useful information for electronic iterations; - - i: geometry relaxation level, which prints some information for geometry relaxations additionally; - - m: molecular dynamics level, which does not print some information for simplicity. -- **Default**: ie - -### out_hsk - -- **Type**: Integer \[Integer\](optional) -- **Availability**: *[`basis_type`](#basis_type)==lcao* -- **Description**: Output the upper triangular part of the Hamiltonian and overlap matrices in reciprocal space for each k-point into files in the directory OUT.${suffix}. The first integer selects the format: - - 0: disabled; - - 1: text output; the optional second integer controls precision and defaults to 8; - - 2: binary output in the native ABACUS .dat format; - - 3: NPZ output, which is not implemented for H(k)/S(k). - - The output is also controlled by out_freq_ion and out_app_flag. For more information, refer to hs_matrix.md. - - - Gamma-only, nspin = 1: hk_nao.txt for the Hamiltonian matrix and sk_nao.txt for the overlap matrix. - - Gamma-only, nspin = 2: hks1_nao.txt and hks2_nao.txt for the two spin channels of the Hamiltonian matrix, and sk_nao.txt for the overlap matrix. Only one overlap matrix is written because it is identical for both spin channels. - - Gamma-only, nspin = 4: not available with the gamma-only algorithm. - - Multi-k, nspin = 1: hk1_nao.txt for the Hamiltonian matrix and sk1_nao.txt for the overlap matrix at the first k-point. - - Multi-k, nspin = 2: hk1s1_nao.txt and hk1s2_nao.txt for the two spin channels of the Hamiltonian matrix, and sk1_nao.txt for the overlap matrix at the first k-point. Only one overlap matrix is written because it is identical for both spin channels. - - Multi-k, nspin = 4: hk1s4_nao.txt for the spinor Hamiltonian matrix and sk1_nao.txt for the spinor overlap matrix at the first k-point. - For binary output, the same names use the .dat suffix. Each native binary record contains the matrix dimension as an int followed by the row-major upper triangle. Gamma-only elements are doubles; multi-k and spinor elements are pairs of doubles containing the real and imaginary parts. Native integer representation and byte order are used. - When out_app_flag is true, the first ionic step truncates the file and later steps append complete records. - When out_app_flag is false, g followed by the one-based ionic-step index is inserted before _nao, for example hk1s1g1_nao.txt. - - > Note: In the 3.10-LTS version, the file names are data-0-H and data-0-S, etc. -- **Default**: 0 8 -- **Unit**: Ry - -### out_mat_hs - -- **Type**: Boolean \[Integer\](optional) -- **Availability**: *[`basis_type`](#basis_type)==lcao* -- **Description**: Legacy alias for out_hsk 1, which outputs Hamiltonian and overlap matrices in reciprocal space for each k-point. The optional second integer controls text precision. If both out_hsk and out_mat_hs are present, out_hsk takes precedence. -- **Default**: False 8 -- **Unit**: Ry - -### out_hsr - -- **Type**: Integer \[Integer\](optional) -- **Availability**: *[`basis_type`](#basis_type)==lcao* -- **Description**: Output Hamiltonian and overlap matrices in real space, indexed by the Bravais lattice vector R, in the directory OUT.${suffix}. The first integer selects the format: - - 0: disabled; - - 1: text CSR output; the optional second integer controls precision and defaults to 8; - - 2: native binary CSR output using .dat files; - - 3: NPZ output using hrs1_nao.npz, hrs2_nao.npz when needed, and sr_nao.npz. - - For multi-k calculations, the output contains the individual real-space blocks stored for the Bravais lattice vectors R. For gamma-only calculations, the internal real-space contributions are folded into a single R = (0, 0, 0) block. This folded result cannot recover the original R-resolved contributions or interpolate arbitrary k points. Terms added only while constructing H(k) are not guaranteed to be present. - - For binary output, each file uses the same basename as text output with a .dat suffix. Every native record contains the zero-based ionic step, matrix dimension, and number of R blocks as ints. Each R block contains three int coordinates, an int nonzero count, native double values (real/imaginary double pairs for complex matrices), int column indices, and long long row pointers. Native integer representation and byte order are used. When out_app_flag is true, the first ionic step truncates the file and later steps append complete records. - - > Note: In the 3.10-LTS version, the file names are data-HR-sparse_SPIN0.csr and data-SR-sparse_SPIN0.csr, etc. -- **Default**: 0 8 -- **Unit**: Ry - -### out_mat_hs2 - -- **Type**: Boolean \[Integer\](optional) -- **Availability**: *[`basis_type`](#basis_type)==lcao* -- **Description**: Legacy alias for out_hsr 1, which outputs Hamiltonian and overlap matrices in real space indexed by the Bravais lattice vector R. The optional second integer controls text precision. If both out_hsr and out_mat_hs2 are present, out_hsr takes precedence. -- **Default**: False 8 -- **Unit**: Ry - -### out_mat_tk - -- **Type**: Boolean \[Integer\](optional) -- **Availability**: *[`basis_type`](#basis_type)==lcao* -- **Description**: Whether to print the upper triangular part of the kinetic matrices for each k-point into OUT.${suffix}/tks1ki_nao.txt, where i is the index of k points. One may optionally provide a second parameter to specify the precision. - - > Note: In the 3.10-LTS version, the file names are data-TR-sparse_SPIN0.csr, etc. -- **Default**: False [8] -- **Unit**: Ry - -### out_mat_r - -- **Type**: Boolean \[Integer\](optional) -- **Availability**: *[`basis_type`](#basis_type)==lcao and [`gamma_only`](#gamma_only)==0* -- **Description**: Whether to print the matrix representation of the position matrix into files named rxrs1_nao.csr, ryrs1_nao.csr, rzrs1_nao.csr in the directory OUT.${suffix}. The optional second parameter controls text output precision. If calculation is set to get_s, the position matrix can be obtained without scf iterations. For more information, please refer to position_matrix.md. - - > Note: In the 3.10-LTS version, the file name is data-rR-sparse.csr. -- **Default**: False 8 -- **Unit**: Bohr - -### out_mat_t - -- **Type**: Boolean \[Integer\](optional) -- **Availability**: *[`basis_type`](#basis_type)==lcao and [`gamma_only`](#gamma_only)==0* -- **Description**: Generate files containing the kinetic energy matrix. The optional second parameter controls text output precision. The format will be the same as the Hamiltonian matrix and overlap matrix as mentioned in out_hsr. The name of the files will be trs1_nao.csr and so on. Also controled by out_freq_ion and out_app_flag. - - > Note: In the 3.10-LTS version, the file name is data-TR-sparse_SPIN0.csr. -- **Default**: False 8 -- **Unit**: Ry - -### out_mat_dh - -- **Type**: Integer -- **Availability**: *[`basis_type`](#basis_type)==lcao and [`gamma_only`](#gamma_only)==0* -- **Description**: Whether to print files containing the derivatives of the Hamiltonian matrix. The format will be the same as the Hamiltonian matrix and overlap matrix as mentioned in out_hsr. The name of the files will be dhrxs1_nao.csr, dhrys1_nao.csr, dhrzs1_nao.csr and so on. Also controled by out_freq_ion and out_app_flag. - - Format: <enable> [precision] [iat1 iat2 ...]. The first value (0/1) enables/disables output. The second optional value sets the output precision (default: 8). Starting from the third value, 1-based atom indices can be listed to restrict output to derivatives with respect to those specific atoms only; if no atom indices are given, all atoms are written. - - > Note: In the 3.10-LTS version, the file name is data-dHRx-sparse_SPIN0.csr and so on. -- **Default**: 0 8 -- **Unit**: Ry/Bohr - -### out_mat_dh_t - -- **Type**: Integer -- **Description**: Whether to print files containing the derivatives of the kinetic energy matrix dT/dR. - - See out_mat_dh for format details (enable, precision, atom indices). -- **Default**: 0 8 -- **Unit**: Ry/Bohr - -### out_mat_dh_vl - -- **Type**: Integer -- **Description**: Whether to print files containing the derivatives of the local pseudopotential matrix dV^L/dR. - - See out_mat_dh for format details. -- **Default**: 0 8 -- **Unit**: Ry/Bohr - -### out_mat_dh_vnl - -- **Type**: Integer -- **Description**: Whether to print files containing the derivatives of the nonlocal pseudopotential matrix dV^NL/dR. - - See out_mat_dh for format details. -- **Default**: 0 8 -- **Unit**: Ry/Bohr - -### out_mat_dh_vh - -- **Type**: Integer -- **Description**: Whether to print files containing the derivatives of the Hartree matrix dV^H/dR. - - See out_mat_dh for format details. -- **Default**: 0 8 -- **Unit**: Ry/Bohr - -### out_mat_dh_vxc - -- **Type**: Integer -- **Description**: Whether to print files containing the derivatives of the XC matrix dV^XC/dR. - - See out_mat_dh for format details. -- **Default**: 0 8 -- **Unit**: Ry/Bohr - -### out_mat_dh_exx - -- **Type**: Integer -- **Description**: Whether to print files containing the derivatives of the exact-exchange matrix dV^EXX/dR. - - See out_mat_dh for format details. -- **Default**: 0 8 -- **Unit**: Ry/Bohr - -### out_mat_h_t - -- **Type**: Integer -- **Description**: Whether to print files containing the kinetic energy matrix T(R) in CSR format. - - See out_hsr for format details. -- **Default**: 0 8 -- **Unit**: Ry - -### out_mat_h_vnl - -- **Type**: Integer -- **Description**: Whether to print files containing the nonlocal pseudopotential matrix Vnl(R) in CSR format. - - See out_hsr for format details. -- **Default**: 0 8 -- **Unit**: Ry - -### out_mat_h_vl - -- **Type**: Integer -- **Description**: Whether to print files containing the local pseudopotential matrix Vl(R) in CSR format. - - See out_hsr for format details. -- **Default**: 0 8 -- **Unit**: Ry - -### out_mat_h_vh - -- **Type**: Integer -- **Description**: Whether to print files containing the Hartree matrix Vh(R) in CSR format. - - See out_hsr for format details. -- **Default**: 0 8 -- **Unit**: Ry - -### out_mat_h_vxc - -- **Type**: Integer -- **Description**: Whether to print files containing the XC matrix Vxc(R) in CSR format. - - See out_hsr for format details. -- **Default**: 0 8 -- **Unit**: Ry - -### out_mat_h_exx - -- **Type**: Integer -- **Description**: Whether to print files containing the exact-exchange matrix Vexx(R) in CSR format. - - See out_hsr for format details. -- **Default**: 0 8 -- **Unit**: Ry - -### out_mat_ds - -- **Type**: Boolean \[Integer\](optional) -- **Availability**: *[`basis_type`](#basis_type)==lcao and [`gamma_only`](#gamma_only)==0* -- **Description**: Whether to print files containing the derivatives of the overlap matrix. The optional second parameter controls text output precision. The format will be the same as the overlap matrix as mentioned in out_mat_dh. The name of the files will be dsxrs1_nao.csr and so on. Also controled by out_freq_ion and out_app_flag. This feature can be used with calculation get_s. - - > Note: In the 3.10-LTS version, the file name is data-dSRx-sparse_SPIN0.csr and so on. -- **Default**: False 8 -- **Unit**: Ry/Bohr - -### out_mat_xc - -- **Type**: Boolean -- **Availability**: *[`basis_type`](#basis_type) in [lcao, lcao_in_pw]* -- **Description**: Whether to print the upper triangular part of the exchange-correlation matrices in Kohn-Sham orbital representation: for each k point into files in the directory OUT.i_nao.txt, where {suffix}/vxc_out.dat. If EXX is calculated, the local and EXX part of band energy will also be printed in OUT.{suffix}/vxc_exx_out.dat, respectively. All the vxc_out.dat files contains 3 integers (nk, nspin, nband) followed by nk*nspin*nband lines of energy Hartree and eV. - - > Note: In the 3.10-LTS version, the file name is k-$k-Vxc and so on. -- **Default**: False -- **Unit**: Ry - -### out_mat_xc2 - -- **Type**: Boolean \[Integer\](optional) -- **Availability**: *[`basis_type`](#basis_type)==lcao* -- **Description**: Whether to print the exchange-correlation matrices in numerical orbital representation: in CSR format in the directory OUT.${suffix}. The name of the files will be vxcrs1_nao.csr and so on. - - > Note: In the 3.10-LTS version, the file name is Vxc_R_spin$s and so on. -- **Default**: False 8 -- **Unit**: Ry - -### out_mat_l - -- **Type**: Boolean \[Integer\](optional) -- **Availability**: *[`basis_type`](#basis_type)==lcao* -- **Description**: Whether to print the expectation value of the angular momentum operator , , and in the basis of the localized atomic orbitals. The files are named OUT.{suffix}_Lx.dat, OUT.{suffix}_Ly.dat, and OUT.{suffix}_Lz.dat. The second integer controls the precision of the output. -- **Default**: False 8 - -### out_xc_r - -- **Type**: Integer \[Integer\](optional) -- **Description**: The first integer controls whether to output the exchange-correlation (in Bohr^-3) on real space grids using Libxc to folder OUT.${suffix}: - - 0: rho, amag, sigma, exc - - 1: vrho, vsigma - - 2: v2rho2, v2rhosigma, v2sigma2 - - 3: v3rho3, v3rho2sigma, v3rhosigma2, v3sigma3 - - 4: v4rho4, v4rho3sigma, v4rho2sigma2, v4rhosigma3, v4sigma4 The meaning of the files is presented in Libxc - - The second integer controls the precision of the charge density output, if not given, will use 3 as default. - - The circle order of the charge density on real space grids is: x is the outer loop, then y and finally z (z is moving fastest). -- **Default**: -1 3 - -### out_eband_terms - -- **Type**: Boolean -- **Availability**: *[`basis_type`](#basis_type)==lcao* -- **Description**: Whether to print the band energy terms separately in the file OUT.{term}_out.dat. The terms include the kinetic, pseudopotential (local + nonlocal), Hartree and exchange-correlation (including exact exchange if calculated). -- **Default**: False - -### out_hr_npz - -- **Type**: Boolean -- **Availability**: *[`basis_type`](#basis_type)==lcao and [`gamma_only`](#gamma_only)==0* -- **Description**: Whether to print Hamiltonian matrices H(R) in NPZ format as hrs1_nao.npz and, for nspin = 2, hrs2_nao.npz. This feature does not work for gamma-only calculations. -- **Default**: False -- **Unit**: Ry - -### out_hsr_npz - -- **Type**: Boolean -- **Availability**: *[`basis_type`](#basis_type)==lcao* -- **Description**: Legacy alias for out_hsr 3, writing hrs1_nao.npz, hrs2_nao.npz when needed, and sr_nao.npz. If both out_hsr and out_hsr_npz are present, out_hsr takes precedence. Gamma-only calculations write the folded R = (0, 0, 0) representation. -- **Default**: False -- **Unit**: Ry - -### out_dm_npz - -- **Type**: Boolean -- **Availability**: *[`basis_type`](#basis_type)==lcao and [`gamma_only`](#gamma_only)==0* -- **Description**: Whether to print density matrices DM(R) in npz format. This feature does not work for gamma-only calculations. -- **Default**: False - -### out_mul - -- **Type**: Boolean -- **Availability**: *[`basis_type`](#basis_type)==lcao* -- **Description**: Whether to print the Mulliken population analysis result into OUT.${suffix}/mulliken.txt. In molecular dynamics calculations, the output frequency is controlled by out_freq_ion. -- **Default**: False - -### out_app_flag - -- **Type**: Boolean -- **Availability**: *[`basis_type`](#basis_type)==lcao and [`gamma_only`](#gamma_only)==0* -- **Description**: Whether to output r(R), H(R), S(R), T(R), dH(R), dS(R), and wfc matrices in an append manner during molecular dynamics calculations. Check input parameters out_mat_r, out_hsr, out_mat_t, out_mat_dh, out_hsk and out_wfc_lcao for more information. -- **Default**: true - -### out_ndigits - -- **Type**: Integer -- **Availability**: *[`basis_type`](#basis_type)==lcao and [`out_hsk`](#out_hsk)==1* -- **Description**: Controls the length of decimal part of output data, such as charge density, Hamiltonian matrix, Overlap matrix and so on. -- **Default**: 8 - -### out_element_info - -- **Type**: Boolean -- **Description**: Whether to print element information into files in the directory OUT.{element_label}, including pseudopotential and orbital information of the element (in atomic Ryberg units). -- **Default**: False - -### restart_save - -- **Type**: Boolean -- **Availability**: *[`basis_type`](#basis_type)==lcao* -- **Description**: Whether to save charge density files per ionic step, which are used to restart calculations. According to the value of read_file_dir: - - auto: These files are saved in folder OUT.{read_file_dir}/restart/. - - If EXX(exact exchange) is calculated (i.e. dft_fuctional==hse/hf/pbe0/scan0 or rpa==True), the Hexx(R) files for each processor will also be saved in the above folder, which can be read in EXX calculation with restart_load==True. -- **Default**: False - -### rpa - -- **Type**: Boolean -- **Availability**: *[`basis_type`](#basis_type)==lcao* -- **Description**: Generate output files used in rpa calculations. - - > Note: If symmetry is set to 1, additional files containing the necessary information for exploiting symmetry in the subsequent rpa calculation will be output: irreducible_sector.txt, symrot_k.txt and symrot_R.txt. -- **Default**: False - -### rpa_out_vel - -- **Type**: Boolean -- **Availability**: *[`basis_type`](#basis_type)==lcao* -- **Description**: Velocity matrix in KS basis (in unit of eV *Angstrom). Loop layer: spin -> k -> direction -> KS_basis1 -> KS_basis2. -- **Default**: False -- **Unit**: eV * A - -### rpa_outdir - -- **Type**: String -- **Availability**: *[`basis_type`](#basis_type)==lcao* -- **Description**: The directory to save files for LibRPA. -- **Default**: "OUT.librpa" - -### out_pchg - -- **Type**: String -- **Availability**: *[`basis_type`](#basis_type)==pw or ([`basis_type`](#basis_type)==lcao and [`calculation`](#calculation)==get_pchg)* -- **Description**: Selects electronic states for partial (band-decomposed) charge-density output using a space-separated string of `0`s and `1`s, where `1` selects a state and `0` skips it. Repetition follows the `ocp_set` syntax, for example `1 4*0 5*1 0`; the expanded list must not exceed `nbands`. Each output represents a complete one-particle state. The spin degeneracy is 2 for `nspin=1` and 1 for `nspin=2` or `nspin=4`. For `nspin=1`, `s1` contains the charge density. For `nspin=2`, `s1` and `s2` contain the spin-up and spin-down charge densities, respectively. For `nspin=4`, `s1`, `s2`, `s3`, and `s4` respectively contain $\rho_0$, $m_x$, $m_y$, and $m_z$. With `if_separate_k=true`, files are named `pchgi[state]s[component]k[kpoint].cube`; otherwise, the weighted k-point sum is named `pchgi[state]s[component].cube`. - - For PW calculations with ultrasoft pseudopotentials (USPP), the single-state valence density includes the augmentation contribution: - - $$ - \rho_{n\boldsymbol{k}}(\boldsymbol{r})=\left\vert\tilde{\psi}_{n\boldsymbol{k}}(\boldsymbol{r})\right\vert^2+\sum_{Iij}Q_{ij}^{I}(\boldsymbol{r})\Braket{\tilde{\psi}_{n\boldsymbol{k}} | \beta_i^I}\Braket{\beta_j^I | \tilde{\psi}_{n\boldsymbol{k}}}. - $$ - - Here $\tilde{\psi}$ is the pseudo-wavefunction, $\beta_i^I$ are the atomic projectors, and $Q_{ij}^I$ are the augmentation functions. Each separate-k output has a cell integral equal to the spin degeneracy. The merged output uses k-point weights including spin degeneracy, and its integral equals their sum for the corresponding spin channel. - - > Note: Enabling symmetry may produce unintended partial charge densities because of reduced k-point weights and real-space symmetry operations. If the desired symmetry treatment is uncertain, set `symmetry = -1`. Use the same symmetry setting as in the SCF calculation. -- **Default**: none - -### out_wfc_norm - -- **Type**: String -- **Availability**: *[`basis_type`](#basis_type)==pw or ([`basis_type`](#basis_type)==lcao and [`calculation`](#calculation)==get_wf)* -- **Description**: Selects electronic states for real-space wavefunction-modulus output using the selection syntax of `out_pchg`. Each output contains single-particle wavefunction amplitudes. In PW calculations, norm-conserving pseudo-wavefunctions satisfy $\Braket{\psi_{n\boldsymbol{k}} | \psi_{n\boldsymbol{k}}}=1$, while USPP pseudo-wavefunctions satisfy $\Braket{\tilde{\psi}_{n\boldsymbol{k}} | \hat{S} | \tilde{\psi}_{n\boldsymbol{k}}}=1$, where $\hat{S}=1+\sum_{Iij}q_{ij}^I\Ket{\beta_i^I}\Bra{\beta_j^I}$ is the USPP overlap operator, $q_{ij}^I=\int Q_{ij}^I(\boldsymbol{r})\,\mathrm{d}\boldsymbol{r}$, and $\beta_i^I$ are the atomic projectors. For `nspin=1`, `s1` contains the wavefunction modulus. For `nspin=2`, `s1` and `s2` contain the spin-up and spin-down wavefunction moduli, respectively. For `nspin=4`, `s1` contains the total spinor modulus. Files are named `wfi[state]s[spin]k[kpoint].cube`. -- **Default**: none - -### out_wfc_re_im - -- **Type**: String -- **Availability**: *[`basis_type`](#basis_type)==pw or ([`basis_type`](#basis_type)==lcao and [`calculation`](#calculation)==get_wf)* -- **Description**: Selects electronic states for real-space wavefunction real- and imaginary-part output using the selection syntax of `out_pchg`. Each output contains single-particle wavefunction amplitudes. In PW calculations, norm-conserving pseudo-wavefunctions satisfy $\Braket{\psi_{n\boldsymbol{k}} | \psi_{n\boldsymbol{k}}}=1$, while USPP pseudo-wavefunctions satisfy $\Braket{\tilde{\psi}_{n\boldsymbol{k}} | \hat{S} | \tilde{\psi}_{n\boldsymbol{k}}}=1$, where $\hat{S}=1+\sum_{Iij}q_{ij}^I\Ket{\beta_i^I}\Bra{\beta_j^I}$ is the USPP overlap operator, $q_{ij}^I=\int Q_{ij}^I(\boldsymbol{r})\,\mathrm{d}\boldsymbol{r}$, and $\beta_i^I$ are the atomic projectors. For `nspin=1`, `s1` contains the wavefunction. For `nspin=2`, `s1` and `s2` contain the spin-up and spin-down wavefunctions, respectively. For `nspin=4`, `s1` and `s2` contain the upper and lower spinor components, respectively. Files are named `wfi[state]s[spin]k[kpoint][re/im].cube`. -- **Default**: none - -### if_separate_k - -- **Type**: Boolean -- **Availability**: *([`basis_type`](#basis_type)==pw and [`out_pchg`](#out_pchg)!=none) or ([`basis_type`](#basis_type)==lcao and [`calculation`](#calculation)==get_pchg and [`gamma_only`](#gamma_only)==0)* -- **Description**: Specifies whether to write partial charge densities for individual k-points or merge them. -- **Default**: false - -### out_elf - -- **Type**: Integer \[Integer\](optional) -- **Availability**: *[`esolver_type`](#esolver_type) in [ksdft, ofdft]* -- **Description**: Whether to output the electron localization function (ELF) in the folder `OUT.${suffix}`. The files are named as - - nspin = 1: - - elftot.cube: ${\rm{ELF}} = \frac{1}{1+\chi^2}$, $\chi = \frac{\frac{1}{2}\sum_{i}{f_i |\nabla\psi_{i}|^2} - \frac{|\nabla\rho|^2}{8\rho}}{\frac{3}{10}(3\pi^2)^{2/3}\rho^{5/3}}$; - - nspin = 2: - - elfs1.cube, elfs2.cube: ${\rm{ELF}}_\sigma = \frac{1}{1+\chi_\sigma^2}$, $\chi_\sigma = \frac{\frac{1}{2}\sum_{i}{f_i |\nabla\psi_{i,\sigma}|^2} - \frac{|\nabla\rho_\sigma|^2}{8\rho_\sigma}}{\frac{3}{10}(6\pi^2)^{2/3}\rho_\sigma^{5/3}}$; - - elftot.cube: ${\rm{ELF}} = \frac{1}{1+\chi^2}$, $\chi = \frac{\frac{1}{2}\sum_{i,\sigma}{f_i |\nabla\psi_{i,\sigma}|^2} - \sum_{\sigma}{\frac{|\nabla\rho_\sigma|^2}{8\rho_\sigma}}}{\sum_{\sigma}{\frac{3}{10}(6\pi^2)^{2/3}\rho_\sigma^{5/3}}}$; - - nspin = 4 (noncollinear): - - elftot.cube: ELF for total charge density, ${\rm{ELF}} = \frac{1}{1+\chi^2}$, $\chi = \frac{\frac{1}{2}\sum_{i}{f_i |\nabla\psi_{i}|^2} - \frac{|\nabla\rho|^2}{8\rho}}{\frac{3}{10}(3\pi^2)^{2/3}\rho^{5/3}}$ - - When `out_freq_ion > 0`, a geometry step suffix `g{#}` is appended to the file names (e.g., `elftotg1.cube`, `elfs1g1.cube`). - - The second integer controls the precision of the kinetic energy density output, if not given, will use 3 as default. For purpose restarting from this file and other high-precision involved calculation, recommend to use 10. - - In molecular dynamics calculations, the output frequency is controlled by out_freq_ion. -- **Default**: 0 3 - -### out_spillage - -- **Type**: Integer -- **Availability**: *[`esolver_type`](#esolver_type)==ksdft and [`basis_type`](#basis_type)==pw* -- **Description**: This output is only intentively needed by the ABACUS numerical atomic orbital generation workflow. This parameter is used to control whether to output the overlap integrals between truncated spherical Bessel functions (TSBFs) and plane-wave basis expanded wavefunctions (named as OVERLAP_Q), and between TSBFs (named as OVERLAP_Sq), also their first order derivatives. The output files are named starting with orb_matrix. A value of 2 would enable the output. -- **Default**: 0 - -### out_alllog - -- **Type**: Boolean -- **Description**: Whether to print information into individual logs from all ranks in an MPI run. - - True: Information from each rank will be written into individual files named OUT.{calculation}_{suffix}/running_${calculation}.log. -- **Default**: False - -[back to top](#full-list-of-input-keywords) - -## Density of states - -### dos_edelta_ev - -- **Type**: Real -- **Description**: The step size in writing Density of States (DOS) -- **Default**: 0.01 -- **Unit**: eV - -### dos_sigma - -- **Type**: Real -- **Description**: The width of the Gaussian factor when obtaining smeared Density of States (DOS) -- **Default**: 0.07 -- **Unit**: eV - -### dos_scale - -- **Type**: Real -- **Description**: Defines the energy range of DOS output as (emax-emin)*(1+dos_scale), centered at (emax+emin)/2. This parameter will be used when dos_emin and dos_emax are not set. -- **Default**: 0.01 -- **Unit**: eV - -### dos_emin_ev - -- **Type**: Real -- **Description**: The minimal range for Density of States (DOS) - - If set, "dos_scale" will be ignored. -- **Default**: Minimal eigenenergy of -- **Unit**: eV - -### dos_emax_ev - -- **Type**: Real -- **Description**: The maximal range for Density of States (DOS) - - If set, "dos_scale" will be ignored. -- **Default**: Maximal eigenenergy of -- **Unit**: eV - -### dos_nche - -- **Type**: Integer -- **Description**: The order of Chebyshev expansions when using Stochastic Density Functional Theory (SDFT) to calculate DOS. -- **Default**: 100 - -### stm_bias - -- **Type**: Real Real(optional) Integer(optional) -- **Description**: The bias voltage used to calculate local density of states to simulate scanning tunneling microscope, see details in out_ldos. When using three parameters: - - - The first parameter specifies the initial bias voltage value. - - The second parameter defines the voltage increment (step size between consecutive bias values). - - The third parameter determines the total number of voltage points -- **Default**: 1.0 -- **Unit**: V - -### ldos_line - -- **Type**: Real*6 Integer(optional) -- **Description**: Specify the path of the three-dimensional space and display LDOS in the form of a two-dimensional color chart, see details in out_ldos. The first three paramenters are the direct coordinates of the start point, the next three paramenters are the direct coordinates of the end point, and the final one is the number of points along the path, whose default is 100. -- **Default**: 0.0 0.0 0.0 0.0 0.0 1.0 100 - -[back to top](#full-list-of-input-keywords) - -## NAOs - -### bessel_nao_ecut - -- **Type**: String -- **Description**: "Energy cutoff" (in Ry) of spherical Bessel functions. The number of spherical Bessel functions that constitute the radial parts of NAOs is determined by sqrt(bessel_nao_ecut)*bessel_nao_rcut/. -- **Default**: ecutwfc - -### bessel_nao_tolerence - -- **Type**: Real -- **Description**: Tolerance when searching for the zeros of spherical Bessel functions. -- **Default**: 1.0e-12 - -### bessel_nao_rcut - -- **Type**: Vector of Real (N values) -- **Description**: Cutoff radius (in Bohr) and the common node of spherical Bessel functions used to construct the NAOs. -- **Default**: 6.0 - -### bessel_nao_smooth - -- **Type**: Boolean -- **Description**: If True, NAOs will be smoothed near the cutoff radius. See bessel_nao_rcut and bessel_nao_sigma for parameters. -- **Default**: True - -### bessel_nao_sigma - -- **Type**: Real -- **Description**: Smoothing range (in Bohr). See also bessel_nao_smooth. -- **Default**: 0.1 - -[back to top](#full-list-of-input-keywords) - -## DeePKS - -### deepks_out_labels - -- **Type**: Integer -- **Availability**: *[`basis_type`](#basis_type)==lcao* -- **Description**: Print labels and descriptors for DeePKS in OUT.${suffix}. The names of these files start with "deepks". - - 0 : No output. - - 1 : Output intermediate files needed during DeePKS training. - - 2 : Output target labels for label preperation. The label files are named as deepks_<property>.npy or deepks_<property>.csr, where the units and formats are the same as label files <property>.npy or <property>.csr required for training, except that the first dimension (nframes) is excluded. System structrue files are also given in deepks_atom.npy and deepks_box.npy in the unit of Bohr, which means lattice_constant should be set to 1 when training. - - > Note: When deepks_out_labels equals 1, the path of a numerical descriptor (an orb file) is needed to be specified under the NUMERICAL_DESCRIPTOR tag in the STRU file. This is not needed when deepks_out_labels equals 2. -- **Default**: 0 - -### deepks_out_freq_elec - -- **Type**: Integer -- **Availability**: *[`basis_type`](#basis_type)==lcao* -- **Description**: When deepks_out_freq_elec is greater than 0, print labels and descriptors for DeePKS in OUT.${suffix}/DeePKS_Labels_Elec per deepks_out_freq_elec electronic iterations, with suffix _e* to distinguish different steps. Often used with deepks_out_labels equals 1. -- **Default**: 0 - -### deepks_out_base - -- **Type**: String -- **Availability**: *[`basis_type`](#basis_type)==lcao and [`deepks_out_freq_elec`](#deepks_out_freq_elec)>0* -- **Description**: Print labels and descriptors calculated by base functional ( determined by deepks_out_base ) and target functional ( determined by dft_functional ) for DeePKS in per deepks_out_freq_elec electronic iterations. The SCF process, labels and descriptors output of the target functional are all consistent with those when the target functional is used alone. The only additional output under this configuration is the labels of the base functional. Often used with deepks_out_labels equals 1. -- **Default**: None - -### deepks_scf - -- **Type**: Boolean -- **Availability**: *[`basis_type`](#basis_type)==lcao* -- **Description**: perform self-consistent field iteration in DeePKS method - - > Note: A trained, traced model file is needed. -- **Default**: False - -### deepks_equiv - -- **Type**: Boolean -- **Availability**: *[`basis_type`](#basis_type)==lcao* -- **Description**: whether to use equivariant version of DeePKS - - > Note: The equivariant version of DeePKS-kit is still under development, so this feature is currently only intended for internal usage. -- **Default**: False - -### deepks_model - -- **Type**: String -- **Availability**: *[`basis_type`](#basis_type)==lcao and [`deepks_scf`](#deepks_scf)==true* -- **Description**: the path of the trained, traced neural network model file generated by deepks-kit -- **Default**: None - -### bessel_descriptor_lmax - -- **Type**: Integer -- **Availability**: *[`calculation`](#calculation)==gen_bessel* -- **Description**: the maximum angular momentum of the Bessel functions generated as the projectors in DeePKS - NOte: To generate such projectors, set calculation type to gen_bessel in ABACUS. See also calculation. -- **Default**: 2 - -### bessel_descriptor_ecut - -- **Type**: String -- **Availability**: *[`calculation`](#calculation)==gen_bessel* -- **Description**: energy cutoff of Bessel functions -- **Default**: same as ecutwfc -- **Unit**: Ry - -### bessel_descriptor_tolerence - -- **Type**: Real -- **Availability**: *[`calculation`](#calculation)==gen_bessel* -- **Description**: tolerance for searching the zeros of Bessel functions -- **Default**: 1.0e-12 - -### bessel_descriptor_rcut - -- **Type**: Real -- **Availability**: *[`calculation`](#calculation)==gen_bessel* -- **Description**: cutoff radius of Bessel functions -- **Default**: 6.0 -- **Unit**: Bohr - -### bessel_descriptor_smooth - -- **Type**: Boolean -- **Availability**: *[`calculation`](#calculation)==gen_bessel* -- **Description**: smooth the Bessel functions at radius cutoff -- **Default**: False - -### bessel_descriptor_sigma - -- **Type**: Real -- **Availability**: *[`calculation`](#calculation)==gen_bessel* -- **Description**: smooth parameter at the cutoff radius of projectors -- **Default**: 0.1 -- **Unit**: Bohr - -### deepks_bandgap - -- **Type**: Integer -- **Availability**: *[`basis_type`](#basis_type)==lcao and [`deepks_scf`](#deepks_scf)==true* -- **Description**: include bandgap label for DeePKS training - - 0: Don't include bandgap label - - 1: Include target bandgap label (see deepks_band_range for more details) - - 2: Include multiple bandgap label (see deepks_band_range for more details) - - 3: Used for systems containing H atoms. Here HOMO is defined as the max occupation except H atoms and the bandgap label is the energy between HOMO and (HOMO + 1) -- **Default**: 0 - -### deepks_band_range - -- **Type**: Integer*2 -- **Availability**: *[`basis_type`](#basis_type)==lcao and [`deepks_scf`](#deepks_scf)==true and [`deepks_bandgap`](#deepks_bandgap) in [1, 2]* -- **Description**: The first value should not be larger than the second one and the meaning differs in different cases below - - deepks_bandgap is 1: Bandgap label is the energy between LUMO + deepks_band_range[0] and LUMO + deepks_band_range[1]. If not set, it will calculate energy between HOMO and LUMO states. - - deepks_bandgap is 2: Bandgap labels are energies between HOMO and all states in range [LUMO + deepks_band_range[0], LUMO + deepks_band_range[1]] (Thus there are deepks_band_range[1] - deepks_band_range[0] + 1 bandgaps in total). If HOMO is included in the setting range, it will be ignored since it will always be zero and has no valuable messages (deepks_band_range[1] - deepks_band_range[0] bandgaps in this case). NOTICE: The set range can be greater than, less than, or include the value of HOMO. In the bandgap label, we always calculate the energy of the state in the set range minus the energy of HOMO state, so the bandgap can be negative if the state is lower than HOMO. -- **Default**: -1 0 - -### deepks_v_delta - -- **Type**: Integer -- **Availability**: *[`basis_type`](#basis_type)==lcao* -- **Description**: Include V_delta/V_delta_R (Hamiltonian in k/real space) label for DeePKS training. When deepks_out_labels is true and deepks_v_delta > 0 (k space), ABACUS will output deepks_hbase.npy, deepks_vdelta.npy and deepks_htot.npy(htot=hbase+vdelta). When deepks_out_labels is true and deepks_v_delta < 0 (real space), ABACUS will output deepks_hrtot.csr, deepks_hrdelta.csr. Some more files output for different settings. NOTICE: To match the unit Normally used in DeePKS, the unit of Hamiltonian in k space is Hartree. However, currently in R space the unit is still Ry. - - deepks_v_delta = 1: deepks_vdpre.npy, which is used to calculate V_delta during DeePKS training. - - deepks_v_delta = 2: deepks_phialpha.npy and deepks_gevdm.npy, which can be used to calculate deepks_vdpre.npy. A recommanded method for memory saving. - - deepks_v_delta = -1: deepks_vdrpre.npy, which is used to calculate V_delta_R during DeePKS training. - - deepks_v_delta = -2: deepks_phialpha_r.npy and deepks_gevdm.npy, which can be used to calculate deepks_vdrpre.npy. A recommanded method for memory saving. -- **Default**: 0 - -### deepks_out_unittest - -- **Type**: Boolean -- **Description**: generate files for constructing DeePKS unit test - - > Note: Not relevant when running actual calculations. When set to 1, ABACUS needs to be run with only 1 process. -- **Default**: False - -[back to top](#full-list-of-input-keywords) - -## OFDFT: orbital free density functional theory - -### of_kinetic - -- **Type**: String -- **Availability**: *[`esolver_type`](#esolver_type)==ofdft* -- **Description**: Kinetic energy functional type: - - tf: Thomas-Fermi (TF) functional - - vw: von Weizsacker (vW) functional - - tf+: TF + vW functional - - wt: Wang-Teter (WT) functional - - ext-wt: Extended Wang-Teter functional - - xwm: XWM functional - - lkt: Luo-Karasiev-Trickey (LKT) functional - - ml: Machine learning KEDF - - mpn: MPN KEDF (automatically sets ml parameters) - - cpn5: CPN5 KEDF (automatically sets ml parameters) -- **Default**: wt - -### of_method - -- **Type**: String -- **Availability**: *[`esolver_type`](#esolver_type)==ofdft* -- **Description**: The optimization method used in OFDFT. - - cg1: Polak-Ribiere. Standard CG algorithm. - - cg2: Hager-Zhang (generally faster than cg1). - - tn: Truncated Newton algorithm. -- **Default**: tn - -### of_conv - -- **Type**: String -- **Availability**: *[`esolver_type`](#esolver_type)==ofdft* -- **Description**: Criterion used to check the convergence of OFDFT. - - energy: Total energy changes less than of_tole. - - potential: The norm of potential is less than of_tolp. - - both: Both energy and potential must satisfy the convergence criterion. -- **Default**: energy - -### of_tole - -- **Type**: Real -- **Availability**: *[`esolver_type`](#esolver_type)==ofdft* -- **Description**: Tolerance of the energy change for determining the convergence. -- **Default**: 2e-6 -- **Unit**: Ry - -### of_tolp - -- **Type**: Real -- **Availability**: *[`esolver_type`](#esolver_type)==ofdft* -- **Description**: Tolerance of potential for determining the convergence. -- **Default**: 1e-5 -- **Unit**: Ry - -### of_tf_weight - -- **Type**: Real -- **Availability**: *[`esolver_type`](#esolver_type)==ofdft and [`of_kinetic`](#of_kinetic) in [tf, tf+, wt, ext-wt, xwm]* -- **Description**: Weight of TF KEDF (kinetic energy density functional). -- **Default**: 1.0 - -### of_vw_weight - -- **Type**: Real -- **Availability**: *[`esolver_type`](#esolver_type)==ofdft and [`of_kinetic`](#of_kinetic) in [vw, tf+, wt, ext-wt, lkt, xwm]* -- **Description**: Weight of vW KEDF (kinetic energy density functional). -- **Default**: 1.0 - -### of_wt_alpha - -- **Type**: Real -- **Availability**: *[`esolver_type`](#esolver_type)==ofdft and [`of_kinetic`](#of_kinetic) in [wt, ext-wt]* -- **Description**: Parameter alpha of WT KEDF (kinetic energy density functional). - -### of_wt_beta - -- **Type**: Real -- **Availability**: *[`esolver_type`](#esolver_type)==ofdft and [`of_kinetic`](#of_kinetic) in [wt, ext-wt]* -- **Description**: Parameter beta of WT KEDF (kinetic energy density functional). - -### of_extwt_kappa - -- **Type**: Real -- **Availability**: *[`esolver_type`](#esolver_type)==ofdft and [`of_kinetic`](#of_kinetic)==ext-wt* -- **Description**: Parameter kappa for EXT-WT KEDF. -- **Default**: 1.0 / (2.0 * std::pow(4./3., 1./3.) - 1.0) - -### of_wt_rho0 - -- **Type**: Real -- **Availability**: *[`esolver_type`](#esolver_type)==ofdft and [`of_kinetic`](#of_kinetic)==wt* -- **Description**: The average density of system. -- **Default**: 0.0 -- **Unit**: Bohr^-3 - -### of_hold_rho0 - -- **Type**: Boolean -- **Availability**: *[`esolver_type`](#esolver_type)==ofdft and [`of_kinetic`](#of_kinetic)==wt* -- **Description**: Whether to fix the average density rho0. - - True: rho0 will be fixed even if the volume of system has changed, it will be set to True automatically if of_wt_rho0 is not zero. - - False: rho0 will change if volume of system has changed. -- **Default**: False - -### of_lkt_a - -- **Type**: Real -- **Availability**: *[`esolver_type`](#esolver_type)==ofdft and [`of_kinetic`](#of_kinetic)==lkt* -- **Description**: Parameter a of LKT KEDF (kinetic energy density functional). -- **Default**: 1.3 - -### of_xwm_rho_ref - -- **Type**: Real -- **Availability**: *[`esolver_type`](#esolver_type)==ofdft and [`of_kinetic`](#of_kinetic)==xwm* -- **Description**: Reference charge density for XWM kinetic energy functional. If set to 0, the program will use average charge density. -- **Default**: 0.0 - -### of_xwm_kappa - -- **Type**: Real -- **Availability**: *[`esolver_type`](#esolver_type)==ofdft and [`of_kinetic`](#of_kinetic)==xwm* -- **Description**: Parameter for XWM kinetic energy functional. See PHYSICAL REVIEW B 100, 205132 (2019) for optimal values. -- **Default**: 0.0 - -### of_read_kernel - -- **Type**: Boolean -- **Availability**: *[`esolver_type`](#esolver_type)==ofdft and [`of_kinetic`](#of_kinetic)==wt* -- **Description**: Whether to read in the kernel file. - - True: The kernel of WT KEDF (kinetic energy density functional) will be filled from the file specified by of_kernel_file. - - False: The kernel of WT KEDF (kinetic energy density functional) will be filled from formula. -- **Default**: False - -### of_kernel_file - -- **Type**: String -- **Availability**: *[`esolver_type`](#esolver_type)==ofdft and [`of_kinetic`](#of_kinetic)==wt and [`of_read_kernel`](#of_read_kernel)==true* -- **Description**: The name of WT kernel file. -- **Default**: WTkernel.txt - -### of_full_pw - -- **Type**: Boolean -- **Availability**: *[`esolver_type`](#esolver_type)==ofdft* -- **Description**: Whether to use full planewaves. - - True: Ecut will be ignored while collecting planewaves, so that all planewaves will be used in FFT. - - False: Only use the planewaves inside ecut, the same as KSDFT. -- **Default**: True - -### of_full_pw_dim - -- **Type**: Integer -- **Availability**: *[`esolver_type`](#esolver_type)==ofdft and [`of_full_pw`](#of_full_pw)==true* -- **Description**: Specify the parity of FFT dimensions. - - 0: either odd or even. - - 1: odd only. - - 2: even only. - - Note: Even dimensions may cause slight errors in FFT. It should be ignorable in ofdft calculation, but it may make Cardinal B-spline interpolation unstable, so please set of_full_pw_dim = 1 if nbspline != -1. -- **Default**: 0 - -[back to top](#full-list-of-input-keywords) - -## ML-KEDF: machine learning based kinetic energy density functional for OFDFT - -### of_ml_gene_data - -- **Type**: Boolean -- **Availability**: *[`esolver_type`](#esolver_type)==ksdft and [`basis_type`](#basis_type)==pw* -- **Description**: Controls the generation of machine learning training data. When enabled, training data in .npy format will be saved in the directory OUT.${suffix}/. -- **Default**: False - -### of_ml_device - -- **Type**: String -- **Availability**: *[`esolver_type`](#esolver_type)==ofdft* -- **Description**: Run Neural Network on GPU or CPU. - - cpu: CPU - - gpu: GPU -- **Default**: cpu - -### of_ml_feg - -- **Type**: Integer -- **Availability**: *[`esolver_type`](#esolver_type)==ofdft* -- **Description**: The method to incorporate the Free Electron Gas (FEG) limit. - - 0: Do not incorporate the FEG limit. - - 1: Incorporate the FEG limit by translation. - - 3: Incorporate the FEG limit by nonlinear transformation using softplus function. -- **Default**: 0 - -### of_ml_nkernel - -- **Type**: Integer -- **Availability**: *[`esolver_type`](#esolver_type)==ofdft* -- **Description**: Number of kernel functions. -- **Default**: 1 - -### of_ml_kernel - -- **Type**: Vector of Integer -- **Availability**: *[`esolver_type`](#esolver_type)==ofdft* -- **Description**: Containing nkernel (see of_ml_nkernel) elements. The i-th element specifies the type of the i-th kernel function. - - 1: Wang-Teter kernel function. - - 2: Modified Yukawa function, and alpha is specified by of_ml_yukawa_alpha. - - 3: Truncated kinetic kernel (TKK), the file containing TKK is specified by of_ml_kernel_file. -- **Default**: 1 - -### of_ml_kernel_scaling - -- **Type**: Vector of Real -- **Availability**: *[`esolver_type`](#esolver_type)==ofdft* -- **Description**: Containing nkernel (see of_ml_nkernel) elements. The i-th element specifies the RECIPROCAL of scaling parameter of the i-th kernel function. -- **Default**: 1.0 - -### of_ml_yukawa_alpha - -- **Type**: Vector of Real -- **Availability**: *[`esolver_type`](#esolver_type)==ofdft* -- **Description**: Containing nkernel (see of_ml_nkernel) elements. The i-th element specifies the parameter alpha of i-th kernel function. ONLY used for Yukawa kernel function. -- **Default**: 1.0 - -### of_ml_kernel_file - -- **Type**: Vector of String -- **Availability**: *[`esolver_type`](#esolver_type)==ofdft* -- **Description**: Containing nkernel (see of_ml_nkernel) elements. The i-th element specifies the file containing the i-th kernel function. ONLY used for TKK. -- **Default**: none - -### of_ml_gamma - -- **Type**: Boolean -- **Availability**: *[`esolver_type`](#esolver_type)==ofdft* -- **Description**: Local descriptor: gamma = (rho / rho0)^(1/3). -- **Default**: False - -### of_ml_p - -- **Type**: Boolean -- **Availability**: *[`esolver_type`](#esolver_type)==ofdft* -- **Description**: Semi-local descriptor: p = |nabla rho|^2 / [2 (3 pi^2)^(1/3) rho^(4/3)]^2. -- **Default**: False - -### of_ml_q - -- **Type**: Boolean -- **Availability**: *[`esolver_type`](#esolver_type)==ofdft* -- **Description**: Semi-local descriptor: q = nabla^2 rho / [4 (3 pi^2)^(2/3) rho^(5/3)]. -- **Default**: False - -### of_ml_tanhp - -- **Type**: Boolean -- **Availability**: *[`esolver_type`](#esolver_type)==ofdft* -- **Description**: Semi-local descriptor: tanhp = tanh(chi_p * p). -- **Default**: False - -### of_ml_tanhq - -- **Type**: Boolean -- **Availability**: *[`esolver_type`](#esolver_type)==ofdft* -- **Description**: Semi-local descriptor: tanhq = tanh(chi_q * q). -- **Default**: False - -### of_ml_chi_p - -- **Type**: Real -- **Availability**: *[`esolver_type`](#esolver_type)==ofdft* -- **Description**: Hyperparameter chi_p: tanhp = tanh(chi_p * p). -- **Default**: 1.0 - -### of_ml_chi_q - -- **Type**: Real -- **Availability**: *[`esolver_type`](#esolver_type)==ofdft* -- **Description**: Hyperparameter chi_q: tanhq = tanh(chi_q * q). -- **Default**: 1.0 - -### of_ml_gammanl - -- **Type**: Vector of Integer -- **Availability**: *[`esolver_type`](#esolver_type)==ofdft* -- **Description**: Containing nkernel (see of_ml_nkernel) elements. The i-th element controls the non-local descriptor gammanl defined by the i-th kernel function. -- **Default**: 0 - -### of_ml_pnl - -- **Type**: Vector of Integer -- **Availability**: *[`esolver_type`](#esolver_type)==ofdft* -- **Description**: Containing nkernel (see of_ml_nkernel) elements. The i-th element controls the non-local descriptor pnl defined by the i-th kernel function. -- **Default**: 0 - -### of_ml_qnl - -- **Type**: Vector of Integer -- **Availability**: *[`esolver_type`](#esolver_type)==ofdft* -- **Description**: Containing nkernel (see of_ml_nkernel) elements. The i-th element controls the non-local descriptor qnl defined by the i-th kernel function. -- **Default**: 0 - -### of_ml_xi - -- **Type**: Vector of Integer -- **Availability**: *[`esolver_type`](#esolver_type)==ofdft* -- **Description**: Containing nkernel (see of_ml_nkernel) elements. The i-th element controls the non-local descriptor xi defined by the i-th kernel function. -- **Default**: 0 - -### of_ml_tanhxi - -- **Type**: Vector of Integer -- **Availability**: *[`esolver_type`](#esolver_type)==ofdft* -- **Description**: Containing nkernel (see of_ml_nkernel) elements. The i-th element controls the non-local descriptor tanhxi defined by the i-th kernel function. -- **Default**: 0 - -### of_ml_tanhxi_nl - -- **Type**: Vector of Integer -- **Availability**: *[`esolver_type`](#esolver_type)==ofdft* -- **Description**: Containing nkernel (see of_ml_nkernel) elements. The i-th element controls the non-local descriptor tanhxi_nl defined by the i-th kernel function. -- **Default**: 0 - -### of_ml_tanh_pnl - -- **Type**: Vector of Integer -- **Availability**: *[`esolver_type`](#esolver_type)==ofdft* -- **Description**: Containing nkernel (see of_ml_nkernel) elements. The i-th element controls the non-local descriptor tanh_pnl defined by the i-th kernel function. -- **Default**: 0 - -### of_ml_tanh_qnl - -- **Type**: Vector of Integer -- **Availability**: *[`esolver_type`](#esolver_type)==ofdft* -- **Description**: Containing nkernel (see of_ml_nkernel) elements. The i-th element controls the non-local descriptor tanh_qnl defined by the i-th kernel function. -- **Default**: 0 - -### of_ml_tanhp_nl - -- **Type**: Vector of Integer -- **Availability**: *[`esolver_type`](#esolver_type)==ofdft* -- **Description**: Containing nkernel (see of_ml_nkernel) elements. The i-th element controls the non-local descriptor tanhp_nl defined by the i-th kernel function. -- **Default**: 0 - -### of_ml_tanhq_nl - -- **Type**: Vector of Integer -- **Availability**: *[`esolver_type`](#esolver_type)==ofdft* -- **Description**: Containing nkernel (see of_ml_nkernel) elements. The i-th element controls the non-local descriptor tanhq_nl defined by the i-th kernel function. -- **Default**: 0 - -### of_ml_chi_xi - -- **Type**: Vector of Real -- **Availability**: *[`esolver_type`](#esolver_type)==ofdft* -- **Description**: Containing nkernel (see of_ml_nkernel) elements. The i-th element specifies the hyperparameter chi_xi of non-local descriptor tanhxi defined by the i-th kernel function. -- **Default**: 1.0 - -### of_ml_chi_pnl - -- **Type**: Vector of Real -- **Availability**: *[`esolver_type`](#esolver_type)==ofdft* -- **Description**: Containing nkernel (see of_ml_nkernel) elements. The i-th element specifies the hyperparameter chi_pnl of non-local descriptor tanh_pnl defined by the i-th kernel function. -- **Default**: 1.0 - -### of_ml_chi_qnl - -- **Type**: Vector of Real -- **Availability**: *[`esolver_type`](#esolver_type)==ofdft* -- **Description**: Containing nkernel (see of_ml_nkernel) elements. The i-th element specifies the hyperparameter chi_qnl of non-local descriptor tanh_qnl defined by the i-th kernel function. -- **Default**: 1.0 - -### of_ml_local_test - -- **Type**: Boolean -- **Availability**: *[`esolver_type`](#esolver_type)==ofdft* -- **Description**: FOR TEST. Read in the density, and output the F and Pauli potential. -- **Default**: False - -### ml_exx - -- **Type**: Boolean -- **Description**: Whether to use machine learning based exact exchange (ML-EXX). -- **Default**: False - -[back to top](#full-list-of-input-keywords) - -## TDOFDFT: time dependent orbital free density functional theory - -### of_cd - -- **Type**: Boolean -- **Availability**: *[`esolver_type`](#esolver_type)==tdofdft* -- **Description**: Added the current dependent(CD) potential. (https://doi.org/10.1103/PhysRevB.98.144302) - - True: Added the CD potential. - - False: Not added the CD potential. -- **Default**: False - -### of_mcd_alpha - -- **Type**: Real -- **Availability**: *[`esolver_type`](#esolver_type)==tdofdft* -- **Description**: The value of the parameter alpha in modified CD potential method. mCDPotential=alpha*CDPotential (proposed in paper PhysRevB.98.144302) -- **Default**: 1.0 - -[back to top](#full-list-of-input-keywords) - -## Electric field and dipole correction - -### efield_flag - -- **Type**: Boolean -- **Description**: Added the electric field. - - True: A saw-like potential simulating an electric field is added to the bare ionic potential. - - False: Not added the electric field. -- **Default**: False - -### dip_cor_flag - -- **Type**: Boolean -- **Availability**: *[`efield_flag`](#efield_flag)==true* -- **Description**: Added a dipole correction to the bare ionic potential. - - True: A dipole correction is also added to the bare ionic potential. - - False: A dipole correction is not added to the bare ionic potential. - - > Note: If you do not want any electric field, the parameter efield_amp should be set to zero. This should ONLY be used in a slab geometry for surface calculations, with the discontinuity FALLING IN THE EMPTY SPACE. -- **Default**: False - -### efield_dir - -- **Type**: Integer -- **Availability**: *[`efield_flag`](#efield_flag)==true* -- **Description**: The direction of the electric field or dipole correction is parallel to the reciprocal lattice vector, so the potential is constant in planes defined by FFT grid points, efield_dir can set to 0, 1 or 2. - - 0: parallel to the first reciprocal lattice vector - - 1: parallel to the second reciprocal lattice vector - - 2: parallel to the third reciprocal lattice vector -- **Default**: 2 - -### efield_pos_max - -- **Type**: Real -- **Availability**: *[`efield_flag`](#efield_flag)==true* -- **Description**: Position of the maximum of the saw-like potential along crystal axis efield_dir, within the unit cell, 0 <= efield_pos_max < 1. -- **Default**: Autoset to center of vacuum - width of vacuum / 20 - -### efield_pos_dec - -- **Type**: Real -- **Availability**: *[`efield_flag`](#efield_flag)==true* -- **Description**: Zone in the unit cell where the saw-like potential decreases, 0 < efield_pos_dec < 1. -- **Default**: Autoset to width of vacuum / 10 - -### efield_amp - -- **Type**: Real -- **Availability**: *[`efield_flag`](#efield_flag)==true* -- **Description**: Amplitude of the electric field. The saw-like potential increases with slope efield_amp in the region from efield_pos_max+efield_pos_dec-1) to (efield_pos_max), then decreases until (efield_pos_max+efield_pos_dec), in units of the crystal vector efield_dir. - - > Note: The change of slope of this potential must be located in the empty region, or else unphysical forces will result. -- **Default**: 0.0 -- **Unit**: a.u., 1 a.u. = 51.4220632*10^10 V/m. - -[back to top](#full-list-of-input-keywords) - -## Gate field (compensating charge) - -### gate_flag - -- **Type**: Boolean -- **Description**: Controls the addition of compensating charge by a charged plate for charged cells. - - true: A charged plate is placed at the zgate position to add compensating charge. The direction is determined by efield_dir. - - false: No compensating charge is added. -- **Default**: false - -### zgate - -- **Type**: Real -- **Description**: Position of the charged plate in the unit cell -- **Default**: 0.5 -- **Unit**: Unit cell size - -### block - -- **Type**: Boolean -- **Description**: Controls the addition of a potential barrier to prevent electron spillover. - - true: A potential barrier is added from block_down to block_up with a height of block_height. If dip_cor_flag is set to true, efield_pos_dec is used to smoothly increase and decrease the potential barrier. - - false: No potential barrier is added. -- **Default**: false - -### block_down - -- **Type**: Real -- **Description**: Lower beginning of the potential barrier -- **Default**: 0.45 -- **Unit**: Unit cell size - -### block_up - -- **Type**: Real -- **Description**: Upper beginning of the potential barrier -- **Default**: 0.55 -- **Unit**: Unit cell size - -### block_height - -- **Type**: Real -- **Description**: Height of the potential barrier -- **Default**: 0.1 -- **Unit**: Rydberg - -[back to top](#full-list-of-input-keywords) - -## Exact Exchange (Common) - -### exx_fock_alpha - -- **Type**: Real -- **Description**: Fraction of full-ranged Fock exchange $1/r$ in range-separated hybrid functionals. -- **Default**: see hybrid_func_params - -### exx_erfc_alpha - -- **Type**: Real -- **Description**: Fraction of short-ranged Fock exchange $\mathrm{erfc}(\omega r)/r$ in range-separated hybrid functionals. -- **Default**: see hybrid_func_params - -### exx_erfc_omega - -- **Type**: Real -- **Description**: Range-separation parameter $\omega$ in the short-ranged Fock term $\mathrm{erfc}(\omega r)/r$. -- **Default**: see hybrid_func_params - -### exx_separate_loop - -- **Type**: Boolean -- **Description**: There are two types of iterative approaches provided by ABACUS to evaluate Fock exchange. - - False: Start with a GGA-Loop, and then Hybrid-Loop, in which EXX Hamiltonian is updated with electronic iterations. - - True: A two-step method is employed, i.e. in the inner iterations, density matrix is updated, while in the outer iterations, is calculated based on density matrix that converges in the inner iteration. -- **Default**: True - -### exx_hybrid_step - -- **Type**: Integer -- **Availability**: *[`exx_separate_loop`](#exx_separate_loop)==1* -- **Description**: The maximal iteration number of the outer-loop, where the Fock exchange is calculated -- **Default**: 100 - -### exx_mixing_beta - -- **Type**: Real -- **Availability**: *[`exx_separate_loop`](#exx_separate_loop)==1* -- **Description**: Mixing parameter for densty matrix in each iteration of the outer-loop -- **Default**: 1.0 - -[back to top](#full-list-of-input-keywords) - -## Exact Exchange (LCAO in PW) - -### exx_fock_lambda - -- **Type**: Real -- **Availability**: *[`basis_type`](#basis_type)==lcao_in_pw* -- **Description**: It is used to compensate for divergence points at G=0 in the evaluation of Fock exchange using lcao_in_pw method. -- **Default**: 0.3 - -[back to top](#full-list-of-input-keywords) - -## Exact Exchange (LCAO) - -### exx_pca_threshold - -- **Type**: Real -- **Description**: To accelerate the evaluation of four-center integrals (), the product of atomic orbitals are expanded in the basis of auxiliary basis functions (ABF): . The size of the ABF (i.e. number of ) is reduced using principal component analysis. When a large PCA threshold is used, the number of ABF will be reduced, hence the calculation becomes faster. However, this comes at the cost of computational accuracy. A relatively safe choice of the value is 1e-4. -- **Default**: 1E-4 - -### exx_c_threshold - -- **Type**: Real -- **Description**: See also the entry exx_pca_threshold. Smaller components (less than exx_c_threshold) of the matrix are neglected to accelerate calculation. The larger the threshold is, the faster the calculation and the lower the accuracy. A relatively safe choice of the value is 1e-4. -- **Default**: 1E-4 - -### exx_cs_inv_thr - -- **Type**: Real -- **Description**: By default, the Coulomb matrix inversion required for obtaining LRI coefficients is performed using LU decomposition. However, this approach may suffer from numerical instabilities when a large set of auxiliary basis functions (ABFs) is employed. When exx_cs_inv_thr > 0, the inversion is instead carried out via matrix diagonalization. Eigenvalues smaller than exx_cs_inv_thr are discarded to improve numerical stability. A relatively safe and commonly recommended value is 1e-5. -- **Default**: -1 - -### exx_v_threshold - -- **Type**: Real -- **Description**: See also the entry exx_pca_threshold. With the approximation , the four-center integral in Fock exchange is expressed as , where is a double-center integral. Smaller values of the V matrix can be truncated to accelerate calculation. The larger the threshold is, the faster the calculation and the lower the accuracy. A relatively safe choice of the value is 0, i.e. no truncation. -- **Default**: 1E-1 - -### exx_dm_threshold - -- **Type**: Real -- **Description**: The Fock exchange can be expressed as where D is the density matrix. Smaller values of the density matrix can be truncated to accelerate calculation. The larger the threshold is, the faster the calculation and the lower the accuracy. A relatively safe choice of the value is 1e-4. -- **Default**: 1E-4 - -### exx_c_grad_threshold - -- **Type**: Real -- **Description**: See also the entry exx_pca_threshold. is used in force. Smaller components (less than exx_c_grad_threshold) of the matrix are neglected to accelerate calculation. The larger the threshold is, the faster the calculation and the lower the accuracy. A relatively safe choice of the value is 1e-4. -- **Default**: 1E-4 - -### exx_v_grad_threshold - -- **Type**: Real -- **Description**: See also the entry exx_pca_threshold. With the approximation , the four-center integral in Fock exchange is expressed as , where is a double-center integral. is used in force. Smaller values of the V matrix can be truncated to accelerate calculation. The larger the threshold is, the faster the calculation and the lower the accuracy. A relatively safe choice of the value is 0, i.e. no truncation. -- **Default**: 1E-1 - -### exx_c_grad_r_threshold - -- **Type**: Real -- **Description**: See also the entry exx_pca_threshold. is used in stress. Smaller components (less than exx_c_grad_r_threshold) of the matrix are neglected to accelerate calculation. The larger the threshold is, the faster the calculation and the lower the accuracy. A relatively safe choice of the value is 1e-4. -- **Default**: 1E-4 - -### exx_v_grad_r_threshold - -- **Type**: Real -- **Description**: See also the entry exx_pca_threshold. With the approximation , the four-center integral in Fock exchange is expressed as , where is a double-center integral. is used in force and stress. Smaller values of the V matrix can be truncated to accelerate calculation. The larger the threshold is, the faster the calculation and the lower the accuracy. A relatively safe choice of the value is 0, i.e. no truncation. -- **Default**: 1E-1 - -### exx_ccp_rmesh_times - -- **Type**: String -- **Description**: This parameter determines how many times larger the radial mesh required for calculating Columb potential is to that of atomic orbitals. The value should be larger than 0. Reducing this value can effectively increase the speed of self-consistent calculations using hybrid functionals. - -### exx_opt_orb_lmax - -- **Type**: Integer -- **Availability**: *[`calculation`](#calculation)==gen_opt_abfs* -- **Description**: The maximum l of the spherical Bessel functions, when the radial part of opt-ABFs are generated as linear combinations of spherical Bessel functions. A reasonable choice is 2. -- **Default**: 0 - -### exx_opt_orb_ecut - -- **Type**: Real -- **Availability**: *[`calculation`](#calculation)==gen_opt_abfs* -- **Description**: The cut-off of plane wave expansion, when the plane wave basis is used to optimize the radial ABFs. A reasonable choice is 60. -- **Default**: 0 -- **Unit**: Ry - -### exx_opt_orb_tolerence - -- **Type**: Real -- **Availability**: *[`calculation`](#calculation)==gen_opt_abfs* -- **Description**: The threshold when solving for the zeros of spherical Bessel functions. A reasonable choice is 1e-12. -- **Default**: 1E-12 - -### exx_real_number - -- **Type**: String -- **Description**: - True: Enforce LibRI to use double data type. - - False: Enforce LibRI to use complex data type. Setting it to True can effectively improve the speed of self-consistent calculations with hybrid functionals. -- **Default**: depends on the gamma_only option - -### exx_singularity_correction - -- **Type**: String -- **Description**: - spencer: see Phys. Rev. B 77, 193110 (2008). - - revised_spencer: see Phys. Rev. Mater. 5, 013807 (2021). Set the scheme of Coulomb singularity correction. -- **Default**: default - -### rpa_ccp_rmesh_times - -- **Type**: Real -- **Description**: How many times larger the radial mesh required is to that of atomic orbitals in the postprocess calculation of the bare Coulomb matrix for RPA, GW, etc. -- **Default**: 10 - -### exx_symmetry_realspace - -- **Type**: Boolean -- **Availability**: *[`symmetry`](#symmetry)==1 and ([`dft_functional`](#dft_functional) in [hse, hf, pbe0, scan0] or ([`basis_type`](#basis_type)==lcao and [`rpa`](#rpa)==true))* -- **Description**: - False: only rotate k-space density matrix D(k) from irreducible k-points to accelerate diagonalization - - True: rotate both D(k) and Hexx(R) to accelerate both diagonalization and EXX calculation - For multi-k calculations, D(k) is averaged over the unitary little group of each irreducible k point before star expansion, for either setting. -- **Default**: True - -### out_ri_cv - -- **Type**: Boolean -- **Description**: Whether to output the coefficient tensor C(R) and ABFs-representation Coulomb matrix V(R) for each atom pair and cell in real space. -- **Default**: false - -### out_unshrinked_v - -- **Type**: Boolean -- **Description**: Whether to output the large Vq matrix in the unshrinked auxiliary basis. -- **Default**: false - -### exx_coul_moment - -- **Type**: Boolean -- **Description**: Whether to use the moment method for Coulomb calculation. -- **Default**: false - -### exx_rotate_abfs - -- **Type**: Boolean -- **Description**: Whether to rotate the auxiliary basis for Coulomb calculation. -- **Default**: false - -### exx_multip_moments_threshold - -- **Type**: Real -- **Description**: Threshold to screen multipole moments in Coulomb calculation. -- **Default**: 1e-10 - -### shrink_abfs_pca_thr - -- **Type**: Real -- **Description**: Threshold to shrink the auxiliary basis for GW/RPA calculations. -- **Default**: -1 - -### shrink_lu_inv_thr - -- **Type**: Real -- **Description**: Threshold for obtaining the inverse of the overlap matrix by LU decomposition in the auxiliary-basis representation. -- **Default**: 1e-6 - -[back to top](#full-list-of-input-keywords) - -## Exact Exchange (PW) - -### exxace - -- **Type**: Boolean -- **Availability**: *[`exx_separate_loop`](#exx_separate_loop)==true* -- **Description**: Whether to use the ACE method (https://doi.org/10.1021/acs.jctc.6b00092) to accelerate the calculation the Fock exchange matrix. Should be set to true most of the time. - - True: Use the ACE method to calculate the Fock exchange operator. - - False: Use the traditional method to calculate the Fock exchange operator. -- **Default**: True - -### exx_gamma_extrapolation - -- **Type**: Boolean -- **Description**: Whether to use the gamma point extrapolation method to calculate the Fock exchange operator. See https://doi.org/10.1103/PhysRevB.79.205114 for details. Should be set to true most of the time. -- **Default**: True - -### ecutexx - -- **Type**: Real -- **Description**: The energy cutoff for EXX (Fock) exchange operator in plane wave basis calculations. Reducing ecutexx below ecutrho may significantly accelerate EXX computations. This speed improvement comes with a reduced numerical accuracy in the exchange energy calculation. -- **Default**: same as ecutrho -- **Unit**: Ry - -### exx_thr_type - -- **Type**: String -- **Description**: The type of threshold used to judge whether the outer loop has converged in the separate loop EXX calculation. - - energy: use the change of exact exchange energy to judge convergence. - - density: if the change of charge density difference between two successive outer loop iterations is seen as converged according to scf_thr, then the outer loop is seen as converged. -- **Default**: density - -### exx_ene_thr - -- **Type**: Real -- **Availability**: *[`exx_thr_type`](#exx_thr_type)==energy* -- **Description**: The threshold for the change of exact exchange energy to judge convergence of the outer loop in the separate loop EXX calculation. -- **Default**: 1e-5 -- **Unit**: Ry - -[back to top](#full-list-of-input-keywords) - -## Molecular dynamics - -### md_type - -- **Type**: String -- **Description**: Control the algorithm to integrate the equation of motion for molecular dynamics (MD), see md.md in detail. - - - fire: a MD-based relaxation algorithm, named fast inertial relaxation engine. - - nve: NVE ensemble with velocity Verlet algorithm. - - nvt: NVT ensemble, see md_thermostat in detail. - - npt: Nose-Hoover style NPT ensemble, see md_pmode in detail. - - langevin: NVT ensemble with Langevin thermostat, see md_damp in detail. - - msst: MSST method, see msst_direction, msst_vel, msst_qmass, msst_vis, msst_tscale in detail. -- **Default**: nvt - -### md_nstep - -- **Type**: Integer -- **Description**: The total number of molecular dynamics steps. -- **Default**: 10 - -### md_dt - -- **Type**: Real -- **Description**: The time step used in molecular dynamics calculations. -- **Default**: 1.0 -- **Unit**: fs - -### md_thermostat - -- **Type**: String -- **Description**: Specify the temperature control method used in NVT ensemble. - - - nhc: Nose-Hoover chain, see md_tfreq and md_tchain in detail. - - anderson: Anderson thermostat, see md_nraise in detail. - - berendsen: Berendsen thermostat, see md_nraise in detail. - - rescaling: velocity Rescaling method 1, see md_tolerance in detail. - - rescale_v: velocity Rescaling method 2, see md_nraise in detail. - - csvr: Canonical Sampling through Velocity Rescaling, see md_csvr_tau in detail. -- **Default**: nhc - -### md_tfirst - -- **Type**: Real -- **Description**: The temperature used in molecular dynamics calculations. - - If md_tfirst is unset or less than zero, init_vel is autoset to be true. If init_vel is true, the initial temperature will be determined by the velocities read from STRU. In this case, if velocities are unspecified in STRU, the initial temperature is set to zero. - - If md_tfirst is set to a positive value and init_vel is true simultaneously, please make sure they are consistent, otherwise abacus will exit immediately. - - Note that md_tlast is only used in NVT/NPT simulations. If md_tlast is unset or less than zero, md_tlast is set to md_tfirst. If md_tlast is set to be different from md_tfirst, ABACUS will automatically change the temperature from md_tfirst to md_tlast. -- **Default**: No default -- **Unit**: K - -### md_tlast - -- **Type**: Real -- **Description**: The temperature used in molecular dynamics calculations. - - If md_tfirst is unset or less than zero, init_vel is autoset to be true. If init_vel is true, the initial temperature will be determined by the velocities read from STRU. In this case, if velocities are unspecified in STRU, the initial temperature is set to zero. - - If md_tfirst is set to a positive value and init_vel is true simultaneously, please make sure they are consistent, otherwise abacus will exit immediately. - - Note that md_tlast is only used in NVT/NPT simulations. If md_tlast is unset or less than zero, md_tlast is set to md_tfirst. If md_tlast is set to be different from md_tfirst, ABACUS will automatically change the temperature from md_tfirst to md_tlast. -- **Default**: No default -- **Unit**: K - -### md_prec_level - -- **Type**: Integer -- **Description**: Determine the precision level of variable-cell molecular dynamics calculations. - - 0: FFT grids do not change, only G vectors and K vectors are changed due to the change of lattice vector. This level is suitable for cases where the variation of the volume and shape is not large, and the efficiency is relatively higher. - - 2: FFT grids change per step. This level is suitable for cases where the variation of the volume and shape is large, such as the MSST method. However, accuracy comes at the cost of efficiency. -- **Default**: 0 - -### md_restart - -- **Type**: Boolean -- **Description**: Control whether to restart molecular dynamics calculations and time-dependent density functional theory calculations. - - True: ABACUS will read in {md_step}, then read in the corresponding STRU_MD_suffix/STRU/ automatically. For tddft, ABACUS will also read in WFC_NAO_K${kpoint} of the last step (You need to set out_wfc_lcao=1 and out_app_flag=0 to obtain this file). - - False: ABACUS will start molecular dynamics calculations normally from the first step. -- **Default**: False - -### md_restartfreq - -- **Type**: Integer -- **Description**: The output frequency of OUT.{suffix}/STRU_MD_*, which are used to restart molecular dynamics calculations, see md_restart in detail. Set to 0 to disable MD restart output. -- **Default**: 5 - -### md_dumpfreq - -- **Type**: Integer -- **Description**: The output frequency of OUT.${suffix}/MD_dump in molecular dynamics calculations, which includes lattice and atomic information. Set to 0 to disable MD_dump output. -- **Default**: 1 - -### md_neighbor_skin - -- **Type**: Real -- **Description**: The extra neighbor-list radius in Angstrom for MDCell molecular dynamics. This parameter is only used for classical potentials or machine-learned interatomic potentials. A positive value reuses the cutoff-plus-skin candidate list until an atom has moved by half this distance; 0 rebuilds the list every force evaluation. -- **Default**: 0.0 -- **Unit**: Angstrom - -### md_out_force - -- **Type**: Boolean -- **Description**: Whether to output the TOTAL-FORCE table in OUT.${suffix}/running_md.log for MDCell molecular dynamics. This does not affect force calculation or molecular dynamics integration. -- **Default**: True - -### dump_force - -- **Type**: Boolean -- **Description**: Whether to output atomic forces into the file OUT.${suffix}/MD_dump. -- **Default**: True - -### dump_vel - -- **Type**: Boolean -- **Description**: Whether to output atomic velocities into the file OUT.${suffix}/MD_dump. -- **Default**: True - -### dump_virial - -- **Type**: Boolean -- **Description**: Whether to output lattice virials into the file OUT.${suffix}/MD_dump. -- **Default**: True - -### md_seed - -- **Type**: Integer -- **Description**: The random seed to initialize random numbers used in molecular dynamics calculations. - - < 0: Each MPI rank uses the default seed 1 plus its rank. - - >= 0: Each MPI rank uses md_seed plus its rank. -- **Default**: -1 - -### md_tfreq - -- **Type**: Real -- **Description**: Control the frequency of temperature oscillations during the simulation. If it is too large, the temperature will fluctuate violently; if it is too small, the temperature will take a very long time to equilibrate with the atomic system. - - Note: It is a system-dependent empirical parameter, ranging from 1/(40*md_dt) to 1/(100*md_dt). An improper choice might lead to the failure of jobs. -- **Default**: 1/40/md_dt - -### md_tchain - -- **Type**: Integer -- **Description**: Number of thermostats coupled with the particles in the NVT/NPT ensemble based on the Nose-Hoover style non-Hamiltonian equations of motion. -- **Default**: 1 - -### md_pmode - -- **Type**: String -- **Description**: Determine the precision level of variable-cell molecular dynamics calculations. - - 0: FFT grids do not change, only G vectors and K vectors are changed due to the change of lattice vector. This level is suitable for cases where the variation of the volume and shape is not large, and the efficiency is relatively higher. - - 2: FFT grids change per step. This level is suitable for cases where the variation of the volume and shape is large, such as the MSST method. However, accuracy comes at the cost of efficiency. -- **Default**: iso - -### ref_cell_factor - -- **Type**: Real -- **Description**: Construct a reference cell bigger than the initial cell. The reference cell has to be large enough so that the lattice vectors of the fluctuating cell do not exceed the reference lattice vectors during MD. Typically, 1.02 ~ 1.10 is sufficient. However, the cell fluctuations depend on the specific system and thermodynamic conditions. So users must test for a proper choice. This parameters should be used in conjunction with erf_ecut, erf_height, and erf_sigma. -- **Default**: 1.0 - -### md_pcouple - -- **Type**: String -- **Description**: The coupled lattice vectors will scale proportionally in NPT ensemble based on the Nose-Hoover style non-Hamiltonian equations of motion. - - none: Three lattice vectors scale independently. - - xyz: Lattice vectors x, y, and z scale proportionally. - - xy: Lattice vectors x and y scale proportionally. - - xz: Lattice vectors x and z scale proportionally. - - yz: Lattice vectors y and z scale proportionally. -- **Default**: none - -### md_pfirst - -- **Type**: Real -- **Description**: The target pressure used in NPT ensemble simulations, the default value of md_plast is md_pfirst. If md_plast is set to be different from md_pfirst, ABACUS will automatically change the target pressure from md_pfirst to md_plast. -- **Default**: -1.0 -- **Unit**: kbar - -### md_plast - -- **Type**: Real -- **Description**: The target pressure used in NPT ensemble simulations, the default value of md_plast is md_pfirst. If md_plast is set to be different from md_pfirst, ABACUS will automatically change the target pressure from md_pfirst to md_plast. -- **Default**: -1.0 -- **Unit**: kbar - -### md_pfreq - -- **Type**: Real -- **Description**: The frequency of pressure oscillations during the NPT ensemble simulation. If it is too large, the pressure will fluctuate violently; if it is too small, the pressure will take a very long time to equilibrate with the atomic system. - - Note: It is a system-dependent empirical parameter. An improper choice might lead to the failure of jobs. -- **Default**: 1/400/md_dt - -### md_pchain - -- **Type**: Integer -- **Description**: The number of thermostats coupled with the barostat in the NPT ensemble based on the Nose-Hoover style non-Hamiltonian equations of motion. -- **Default**: 1 - -### lj_rule - -- **Type**: Integer -- **Description**: The Lennard-Jones potential between two atoms equals: $\sigma_k\sigma(i,j)$ -- **Default**: 2 - -### lj_eshift - -- **Type**: Boolean -- **Description**: It True, the LJ potential is shifted by a constant such that it is zero at the cut-off distance. -- **Default**: False - -### lj_rcut - -- **Type**: Real -- **Description**: Cut-off radius for Leonard Jones potential, beyond which the interaction will be neglected. It can be a single value, which means that all pairs of atoms types share the same cut-off radius. Otherwise, it should be a multiple-component vector, containing values, see details in lj_rule. -- **Default**: No default -- **Unit**: Angstrom - -### lj_epsilon - -- **Type**: Real -- **Description**: The vector representing the matrix for Leonard Jones potential. See details in lj_rule. -- **Default**: No default -- **Unit**: eV - -### lj_sigma - -- **Type**: Real -- **Description**: The vector representing the matrix for Leonard Jones potential. See details in lj_rule. -- **Default**: No default -- **Unit**: Angstrom - -### pot_file - -- **Type**: String -- **Description**: The filename of DP/NEP potential files, see md.md in detail. -- **Default**: graph.pb - -### dp_rescaling - -- **Type**: Real -- **Availability**: *[`esolver_type`](#esolver_type)==dp* -- **Description**: Rescaling factor to use a temperature-dependent DP. Energy, stress and force calculated by DP will be multiplied by this factor. -- **Default**: 1.0 - -### dp_fparam - -- **Type**: Real -- **Availability**: *[`esolver_type`](#esolver_type)==dp* -- **Description**: The frame parameter for dp potential. The array size is dim_fparam, then all frames are assumed to be provided with the same fparam. -- **Default**: {} - -### dp_aparam - -- **Type**: Real -- **Availability**: *[`esolver_type`](#esolver_type)==dp* -- **Description**: The atomic parameter for dp potential. The array size can be (1) natoms x dim_aparam, then all frames are assumed to be provided with the same aparam; (2) dim_aparam, then all frames and atoms are assumed to be provided with the same aparam. -- **Default**: {} - -### msst_direction - -- **Type**: Integer -- **Description**: The direction of the shock wave in the MSST method. - - 0: x direction - - 1: y direction - - 2: z direction -- **Default**: 2 - -### msst_vel - -- **Type**: Real -- **Description**: The velocity of the shock wave in the MSST method. -- **Default**: 0.0 -- **Unit**: Angstrom/fs - -### msst_vis - -- **Type**: Real -- **Description**: Artificial viscosity in the MSST method. -- **Default**: 0.0 -- **Unit**: g/(mol*Angstrom*fs) - -### msst_tscale - -- **Type**: Real -- **Description**: The reduction percentage of the initial temperature used to compress volume in the MSST method. -- **Default**: 0.01 - -### msst_qmass - -- **Type**: Real -- **Description**: Inertia of the extended system variable. You should set a number larger than 0. -- **Default**: No default - -### md_damp - -- **Type**: Real -- **Description**: The damping parameter used to add fictitious force in the Langevin method. -- **Default**: 1.0 -- **Unit**: fs - -### md_csvr_tau - -- **Type**: Real -- **Availability**: *[`md_thermostat`](#md_thermostat)==csvr* -- **Description**: The characteristic time scale for the CSVR (Canonical Sampling through Velocity Rescaling) thermostat. Larger values give weaker coupling, smaller values give stronger coupling. Recommended value: 100 * md_dt. -- **Default**: 100.0 -- **Unit**: fs - -### md_tolerance - -- **Type**: Real -- **Description**: The temperature tolerance for velocity rescaling. Velocities are rescaled if the current and target temperature differ more than md_tolerance. -- **Default**: 100.0 -- **Unit**: K - -### md_nraise - -- **Type**: Integer -- **Description**: - Anderson: The "collision frequency" parameter is given as 1/md_nraise. - - Berendsen: The "rise time" parameter is given in units of the time step: tau = md_nraise*md_dt, so md_dt/tau = 1/md_nraise. - - Rescale_v: Every md_nraise steps the current temperature is rescaled to the target temperature. -- **Default**: 1 - -### cal_syns - -- **Type**: Boolean [Integer](optional) -- **Description**: Whether to calculate and output asynchronous overlap matrix for Hefei-NAMD interface. When enabled, calculates <phi(t-1)|phi(t)> by computing overlap between basis functions at atomic positions from previous time step and current time step. The overlap is calculated by shifting atom positions backward by velocity x md_dt. Output file: OUT.*/syns_nao.csr in CSR format. - - - 0 or false: disable - - 1 or true: enable with default precision (8 digits) - - 1 5: enable with custom precision (5 digits) - - > Note: Only works with LCAO basis and molecular dynamics calculations. Requires atomic velocities. Output starts from the second MD step (istep > 0). -- **Default**: False - -### dmax - -- **Type**: Real -- **Description**: The maximum displacement of all atoms in one step. This parameter is useful when cal_syns = True. -- **Default**: 0.01 -- **Unit**: bohr - -[back to top](#full-list-of-input-keywords) - -## DFT+U correction - -### dft_plus_u - -- **Type**: Integer -- **Description**: Determines whether to calculate the plus U correction, which is especially important for correlated electrons. - - 1: Calculate plus U correction with radius-adjustable localized projections (with parameter onsite_radius). - - 2: Calculate plus U correction using first zeta of NAOs as projections (this is old method for testing). - - 0: Do not calculate plus U correction. -- **Default**: 0 - -### dft_plus_dmft - -- **Type**: Boolean -- **Availability**: *[`basis_type`](#basis_type)==lcao* -- **Description**: Whether to enable DFT+DMFT calculation. True: DFT+DMFT; False: standard DFT calculation. -- **Default**: False - -### orbital_corr - -- **Type**: Vector of Integer (n values where n is the number of atomic types) -- **Description**: Specifies which orbits need plus U correction for each atom type ( for atom type 1, 2, 3, respectively). - - -1: The plus U correction will not be calculated for this atom. - - 1: For p-electron orbits, the plus U correction is needed. - - 2: For d-electron orbits, the plus U correction is needed. - - 3: For f-electron orbits, the plus U correction is needed. -- **Default**: -1 - -### hubbard_u - -- **Type**: Vector of Real (n values where n is the number of atomic types) -- **Description**: Specifies the Hubbard Coulomb interaction parameter U (eV) in plus U correction, which should be specified for each atom unless the Yukawa potential is used. - - > Note: Since only the simplified scheme by Duradev is implemented, the 'U' here is actually U-effective, which is given by Hubbard U minus Hund J. -- **Default**: 0.0 - -### yukawa_potential - -- **Type**: Boolean -- **Description**: Determines whether to use the local screen Coulomb potential method to calculate the values of U and J. - - True: hubbard_u does not need to be specified. - - False: hubbard_u does need to be specified. -- **Default**: False - -### yukawa_lambda - -- **Type**: Real -- **Availability**: *[`dft_plus_u`](#dft_plus_u)==1 and [`yukawa_potential`](#yukawa_potential)==true* -- **Description**: The screen length of Yukawa potential. If left to default, the screen length will be calculated as an average of the entire system. It's better to stick to the default setting unless there is a very good reason. -- **Default**: Calculated on the fly. - -### uramping - -- **Type**: Real -- **Availability**: *[`dft_plus_u`](#dft_plus_u)==1 and [`mixing_restart`](#mixing_restart)>0* -- **Description**: Once uramping > 0.15 eV. DFT+U calculations will start SCF with U = 0 eV, namely normal LDA/PBE calculations. Once SCF restarts when drho<mixing_restart, U value will increase by uramping eV. SCF will repeat above calcuations until U values reach target defined in hubbard_u. As for uramping=1.0 eV, the recommendations of mixing_restart is around 5e-4. -- **Default**: -1.0. -- **Unit**: eV - -### omc - -- **Type**: Integer -- **Description**: The parameter controls the form of occupation matrix control used. - - 0: No occupation matrix control is performed, and the onsite density matrix will be calculated from wavefunctions in each SCF step. - - 1: The first SCF step will use an initial density matrix read from a file named dm_onsite_ini.txt, but for later steps, the onsite density matrix will be updated. - - 2: The same onsite density matrix from dm_onsite_ini.txt will be used throughout the entire calculation. - - > Note: The easiest way to create dm_onsite_ini.txt is to run a DFT+U calculation with out_chg=1, look for a file named dm_onsite.txt in the OUT.prefix directory, copy and rename it to dm_onsite_ini.txt. The file dm_onsite_ini.txt should be placed in the directory specified by read_file_dir. The format of the file is rather straight-forward. -- **Default**: 0 - -### onsite_radius - -- **Type**: Real -- **Availability**: *[`dft_plus_u`](#dft_plus_u)==1* -- **Description**: - The onsite_radius parameter facilitates modulation of the single-zeta portion of numerical atomic orbitals used for DFT+U projections. - - The modulation algorithm applies a smooth truncation to the orbital tail followed by normalization. A representative profile is $f(r)=\frac{1}{2}\left[1+\operatorname{erf}\!\left(\frac{r_c-r}{\sigma}\right)\right]$, where $r_c$ is the cutoff radius and $\sigma=\gamma r_c$ controls smoothness. -- **Default**: 3.0 -- **Unit**: Bohr - -[back to top](#full-list-of-input-keywords) - -## Spin-Constrained DFT - -### sc_mag_switch - -- **Type**: Boolean -- **Description**: Switch to control spin-constrained DFT calculation -- **Default**: False - -### decay_grad_switch - -- **Type**: Boolean -- **Description**: Switch to control gradient break condition in spin-constrained DFT -- **Default**: False - -### sc_thr - -- **Type**: Real -- **Availability**: *[`sc_mag_switch`](#sc_mag_switch)==true* -- **Description**: Convergence criterion of spin-constrained iteration (RMS) in uB -- **Default**: 1.0e-6 -- **Unit**: uB - -### nsc - -- **Type**: Integer -- **Availability**: *[`sc_mag_switch`](#sc_mag_switch)==true* -- **Description**: Maximal number of spin-constrained iteration -- **Default**: 100 - -### nsc_min - -- **Type**: Integer -- **Availability**: *[`sc_mag_switch`](#sc_mag_switch)==true* -- **Description**: Minimum number of spin-constrained iteration -- **Default**: 2 - -### alpha_trial - -- **Type**: Real -- **Availability**: *[`sc_mag_switch`](#sc_mag_switch)==true* -- **Description**: Initial trial step size for lambda in eV/uB^2 -- **Default**: 0.01 -- **Unit**: eV/uB^2 - -### sccut - -- **Type**: Real -- **Availability**: *[`sc_mag_switch`](#sc_mag_switch)==true* -- **Description**: Maximal step size for lambda in eV/uB -- **Default**: 3.0 -- **Unit**: eV/uB - -### sc_drop_thr - -- **Type**: Real -- **Availability**: *[`sc_mag_switch`](#sc_mag_switch)==true* -- **Description**: Convergence criterion ratio of lambda iteration in Spin-constrained DFT -- **Default**: 1.0e-2 - -### sc_scf_thr - -- **Type**: Real -- **Availability**: *[`sc_mag_switch`](#sc_mag_switch)==true* -- **Description**: Density error threshold for inner loop of spin-constrained SCF -- **Default**: 1.0e-4 - -### sc_direction_only - -- **Type**: Boolean -- **Availability**: *[`sc_mag_switch`](#sc_mag_switch)==true* -- **Description**: When true, only the direction of the magnetic moment is constrained to the target direction, while the magnitude is allowed to vary freely. This is useful for studying magnetic anisotropy or when the magnitude of the moment is determined by the electronic structure rather than an external constraint. - - When false (default), both the direction and magnitude of the magnetic moment are constrained to the target values. -- **Default**: False - -### sc_lambda_strategy - -- **Type**: String -- **Availability**: *[`sc_mag_switch`](#sc_mag_switch)==true* -- **Description**: Lambda update strategy for spin-constrained DFT: - - bfgs: BFGS quasi-Newton method - - linear_response: linear response (Scheme B) - - augmented_lagrangian: augmented Lagrangian (Scheme C) - - hybrid_delayed: hybrid delayed update (Scheme D) - - linear_scan: linear sweep of lambda for testing magnetic moment response -- **Default**: bfgs - -### sc_scan_lambda_start - -- **Type**: Float -- **Availability**: *[`sc_mag_switch`](#sc_mag_switch)==true and [`sc_lambda_strategy`](#sc_lambda_strategy)==linear_scan* -- **Description**: Starting lambda value for linear_scan strategy. Only used when sc_lambda_strategy=linear_scan. -- **Default**: 0.0 -- **Unit**: eV/uB - -### sc_scan_lambda_end - -- **Type**: Float -- **Availability**: *[`sc_mag_switch`](#sc_mag_switch)==true and [`sc_lambda_strategy`](#sc_lambda_strategy)==linear_scan* -- **Description**: Ending lambda value for linear_scan strategy. Only used when sc_lambda_strategy=linear_scan. -- **Default**: 1.0 -- **Unit**: eV/uB - -### sc_scan_steps - -- **Type**: Integer -- **Availability**: *[`sc_mag_switch`](#sc_mag_switch)==true and [`sc_lambda_strategy`](#sc_lambda_strategy)==linear_scan* -- **Description**: Number of lambda values to scan. Only used when sc_lambda_strategy=linear_scan. -- **Default**: 20 - -[back to top](#full-list-of-input-keywords) - -## vdW correction - -### vdw_method - -- **Type**: String -- **Description**: Specifies the method used for Van der Waals (VdW) correction. Available options are: - - d2: Grimme's D2 dispersion correction method - - d3_0: Grimme's DFT-D3(0) dispersion correction method (zero-damping) - - d3_bj: Grimme's DFTD3(BJ) dispersion correction method (BJ-damping) - - d4: Grimme's DFT-D4 dispersion correction method using the external DFT-D4 library - - none: no vdW correction - - > Note: ABACUS automatically loads DFT-D3 parameters for supported functionals according to dft_functional setting. Individual user values overwrite the corresponding tabulated values. Setting all four of vdw_s6, vdw_s8, vdw_a1 and vdw_a2 defines a fully custom set and bypasses functional lookup. -- **Default**: none - -### vdw_d4_xc - -- **Type**: String -- **Availability**: *[`vdw_method`](#vdw_method)==d4* -- **Description**: Functional name used to load DFT-D4 damping parameters from the DFT-D4 library. - If set to default, ABACUS infers the functional name from dft_functional or pseudopotential metadata. -- **Default**: default - -### vdw_d4_model - -- **Type**: String -- **Availability**: *[`vdw_method`](#vdw_method)==d4* -- **Description**: DFT-D4 dispersion model used by the external DFT-D4 library. - Available options are: - - - d4: standard D4 model - - d4s: smooth D4S model -- **Default**: d4 - -### vdw_s6 - -- **Type**: String -- **Availability**: *[`vdw_method`](#vdw_method) in [d2, d3_0, d3_bj]* -- **Description**: Scale factor s6, which is used to optimize the interaction energy deviations in van der Waals (vdW) corrected calculations. The recommended values of this parameter are dependent on the chosen vdW correction method and the DFT functional being used. For DFT-D2, the recommended values are 0.75 (PBE), 1.2 (BLYP), 1.05 (B-P86), 1.0 (TPSS), and 1.05 (B3LYP); if not set, will use values of PBE functional by default. For DFT-D3, ABACUS will search in built-in dataset based on the dft_functional setting by default; user set value will overwrite the searched value. - -### vdw_s8 - -- **Type**: String -- **Availability**: *[`vdw_method`](#vdw_method) in [d3_0, d3_bj]* -- **Description**: Scale factor s8 for D3(0) and D3(BJ). By default, ABACUS will search in built-in dataset based on the dft_functional setting. User set value will overwrite the searched value. - -### vdw_a1 - -- **Type**: String -- **Availability**: *[`vdw_method`](#vdw_method) in [d3_0, d3_bj]* -- **Description**: Damping parameter rs6 for D3(0), or a1 for D3(BJ). If not set, ABACUS loads the s-dftd3 value for dft_functional. A user value overwrites the tabulated value. - -### vdw_a2 - -- **Type**: String -- **Availability**: *[`vdw_method`](#vdw_method) in [d3_0, d3_bj]* -- **Description**: Damping parameter rs8 for D3(0), or a2 for D3(BJ). If not set, ABACUS loads the s-dftd3 value for dft_functional. A user value overwrites the tabulated value. - -### vdw_d - -- **Type**: Real -- **Availability**: *[`vdw_method`](#vdw_method)==d2* -- **Description**: Controls the damping rate of the damping function in the DFT-D2 method. -- **Default**: 20 - -### vdw_abc - -- **Type**: Boolean -- **Availability**: *[`vdw_method`](#vdw_method) in [d3_0, d3_bj]* -- **Description**: Determines whether three-body terms are calculated for DFT-D3 methods. - - True: ABACUS will calculate the three-body term. - - False: The three-body term is not included. -- **Default**: False - -### vdw_c6_file - -- **Type**: String -- **Availability**: *[`vdw_method`](#vdw_method)==d2* -- **Description**: Specifies the name of the file containing parameters for each element when using the D2 method. If not set, ABACUS uses the default parameters (Jnm6/mol) stored in the program. To manually set the parameters, provide a file containing the parameters. An example is given by: - - H 0.1 Si 9.0 - - Namely, each line contains the element name and the corresponding parameter. -- **Default**: default - -### vdw_c6_unit - -- **Type**: String -- **Availability**: *[`vdw_method`](#vdw_method)==d2 and [`vdw_c6_file`](#vdw_c6_file)!=default* -- **Description**: Specifies the unit of the provided parameters in the D2 method. Available options are: - - Jnm6/mol (J nm^6/mol) - - eVA (eV Angstrom) -- **Default**: Jnm6/mol - -### vdw_r0_file - -- **Type**: String -- **Availability**: *[`vdw_method`](#vdw_method)==d2* -- **Description**: Specifies the name of the file containing parameters for each element when using the D2 method. If not set, ABACUS uses the default parameters (Angstrom) stored in the program. To manually set the parameters, provide a file containing the parameters. An example is given by: - - Li 1.0 Cl 2.0 - - Namely, each line contains the element name and the corresponding parameter. -- **Default**: default - -### vdw_r0_unit - -- **Type**: String -- **Availability**: *[`vdw_method`](#vdw_method)==d2 and [`vdw_r0_file`](#vdw_r0_file)!=default* -- **Description**: Specifies the unit for the parameters in the D2 method when manually set by the user. Available options are: - - A (Angstrom) - - Bohr -- **Default**: A - -### vdw_cutoff_type - -- **Type**: String -- **Description**: Determines the method used for specifying the cutoff radius in periodic systems when applying Van der Waals correction. Available options are: - - radius: The supercell is selected within a sphere centered at the origin with a radius defined by vdw_cutoff_radius. - - period: The extent of the D2 supercell is explicitly specified using the vdw_cutoff_period keyword. DFT-D3 and DFT-D4 require radius. -- **Default**: radius - -### vdw_cutoff_radius - -- **Type**: String -- **Availability**: *[`vdw_cutoff_type`](#vdw_cutoff_type)==radius* -- **Description**: Defines the radius of the cutoff sphere when vdw_cutoff_type is set to radius. The default values depend on the chosen vdw_method. -- **Unit**: defined by vdw_radius_unit (default Bohr) - -### vdw_radius_unit - -- **Type**: String -- **Availability**: *[`vdw_cutoff_type`](#vdw_cutoff_type)==radius* -- **Description**: Specify the unit of vdw_cutoff_radius. Available options are: - - A(Angstrom) - - Bohr -- **Default**: Bohr - -### vdw_cutoff_width2 - -- **Type**: Real -- **Availability**: *[`vdw_method`](#vdw_method) in [d3_0, d3_bj, d4]* -- **Description**: Width of the smooth switching region for the two-body pairwise dispersion real-space cutoff. - A value of zero disables smoothing for the two-body contribution. -- **Default**: 0.05 -- **Unit**: Bohr - -### vdw_cutoff_width3 - -- **Type**: Real -- **Availability**: *[`vdw_method`](#vdw_method) in [d3_0, d3_bj, d4]* -- **Description**: Width of the smooth switching region for the three-body Axilrod-Teller-Muto (ATM) dispersion real-space cutoff. - A value of zero disables smoothing for the three-body contribution. -- **Default**: 0.0 -- **Unit**: Bohr - -### vdw_cutoff_period - -- **Type**: Integer Integer Integer -- **Availability**: *[`vdw_cutoff_type`](#vdw_cutoff_type)==period* -- **Description**: The three integers supplied here explicitly specify the extent of the supercell in the directions of the three basis lattice vectors. -- **Default**: 3 3 3 - -### vdw_cn_thr - -- **Type**: Real -- **Availability**: *[`vdw_method`](#vdw_method) in [d3_0, d3_bj, d4]* -- **Description**: The cutoff radius when calculating coordination numbers. -- **Default**: 40 -- **Unit**: defined by vdw_cn_thr_unit (default: Bohr) - -### vdw_cn_thr_unit - -- **Type**: String -- **Description**: Unit of the coordination number cutoff (vdw_cn_thr). Available options are: - - A(Angstrom) - - Bohr -- **Default**: Bohr - -[back to top](#full-list-of-input-keywords) - -## Berry phase and wannier90 interface - -### berry_phase - -- **Type**: Boolean -- **Description**: Controls the calculation of Berry phase - - true: Calculate Berry phase. - - false: Do not calculate Berry phase. -- **Default**: false - -### gdir - -- **Type**: Integer -- **Description**: The direction of the polarization in the lattice vector for Berry phase calculation - - 1: Calculate the polarization in the direction of the lattice vector a_1 defined in the STRU file. - - 2: Calculate the polarization in the direction of the lattice vector a_2 defined in the STRU file. - - 3: Calculate the polarization in the direction of the lattice vector a_3 defined in the STRU file. -- **Default**: 3 - -### towannier90 - -- **Type**: Boolean -- **Description**: Controls the generation of files for the Wannier90 code. - - 1: Generate files for the Wannier90 code. - - 0: Do not generate files for the Wannier90 code. -- **Default**: 0 - -### nnkpfile - -- **Type**: String -- **Description**: The file name generated when running "wannier90 -pp ..." command -- **Default**: seedname.nnkp - -### wannier_method - -- **Type**: Integer -- **Description**: Only available on LCAO basis, using different methods to generate "\.mmn" file and "\.amn" file. - - 1: Calculated using the lcao_in_pw method, the calculation accuracy can be improved by increasing ecutwfc to maintain consistency with the pw basis set results. - - 2: The overlap between atomic orbitals is calculated using grid integration. The radial grid points are generated using the Gauss-Legendre method, while the spherical grid points are generated using the Lebedev-Laikov method. -- **Default**: 1 - -### wannier_spin - -- **Type**: String -- **Description**: The spin direction for the Wannier function calculation when nspin is set to 2 - - up: Calculate spin up for the Wannier function. - - down: Calculate spin down for the Wannier function. -- **Default**: up - -### out_wannier_mmn - -- **Type**: Boolean -- **Description**: Write the "*.mmn" file or not. - - 0: don't write the "*.mmn" file. - - 1: write the "*.mmn" file. -- **Default**: 1 - -### out_wannier_amn - -- **Type**: Boolean -- **Description**: Write the "*.amn" file or not. - - 0: don't write the "*.amn" file. - - 1: write the "*.amn" file. -- **Default**: 1 - -### out_wannier_eig - -- **Type**: Boolean -- **Description**: Write the "*.eig" file or not. - - 0: don't write the "*.eig" file. - - 1: write the "*.eig" file. -- **Default**: 1 - -### out_wannier_unk - -- **Type**: Boolean -- **Description**: Write the "UNK.*" file or not. - - 0: don't write the "UNK.*" file. - - 1: write the "UNK.*" file. -- **Default**: 0 - -### out_wannier_wvfn_formatted - -- **Type**: Boolean -- **Description**: Write the "UNK.*" file in ASCII format or binary format. - - 0: write the "UNK.*" file in binary format. - - 1: write the "UNK.*" file in ASCII format (text file format). -- **Default**: 1 - -[back to top](#full-list-of-input-keywords) - -## RT-TDDFT: Real-Time Time-Dependent Density Functional Theory - -### estep_per_md - -- **Type**: Integer -- **Description**: The number of electronic propagation steps between two ionic steps. -- **Default**: 1 - -### td_dt - -- **Type**: Real -- **Description**: The time step used for electronic propagation. If td_dt is not specified, it is set to md_dt / estep_per_md. If td_dt is specified explicitly, md_dt is reset to td_dt * estep_per_md. -- **Default**: md_dt / estep_per_md -- **Unit**: fs - -### td_edm - -- **Type**: Integer -- **Description**: Method used to calculate the energy-density matrix for the overlap contribution to forces in LCAO RT-TDDFT. - - 0: Use $\mathrm{EDM}_{\boldsymbol{k}}=\frac{1}{2}\left(S_{\boldsymbol{k}}^{-1}H_{\boldsymbol{k}}\rho_{\boldsymbol{k}}+\rho_{\boldsymbol{k}}H_{\boldsymbol{k}}S_{\boldsymbol{k}}^{-1}\right)$. - - 1: Use the ground-state eigenvalue-weighted expression $\mathrm{EDM}_{\mu\nu,\boldsymbol{k}}=\sum_i w_{i\boldsymbol{k}}\epsilon_{i\boldsymbol{k}}C_{\mu i,\boldsymbol{k}}C_{\nu i,\boldsymbol{k}}^*$. This expression is deprecated for RT-TDDFT and is generally not valid when the propagated wave functions are not Hamiltonian eigenstates. -- **Default**: 0 - -### td_print_eij - -- **Type**: Real -- **Description**: Controls output of the propagated-state Hamiltonian matrix elements $E_{ij}=\Braket{\psi_i | \hat{H} | \psi_j}$ to the running log. The printed band indices $i$ and $j$ are one-based global indices. Both the threshold and the printed matrix elements are in Ry. - - $\lt 0$: Disable the output. - - $\geqslant 0$: Print an element when either $\left|\operatorname{Re}E_{ij}\right|$ or $\left|\operatorname{Im}E_{ij}\right|$ is greater than or equal to td_print_eij. -- **Default**: -1 -- **Unit**: Ry - -### td_propagator - -- **Type**: Integer -- **Description**: Method used to propagate the electronic states in a nonorthogonal LCAO basis. The formulas below use Hartree atomic units, with $S$, $H$, and $\Delta t=\mathtt{td\_dt}$ evaluated as required by each approximation. - - 0: Crank-Nicolson through an explicitly constructed evolution matrix, $U=\left[S+\mathrm{i}H\Delta t/2\right]^{-1}\left[S-\mathrm{i}H\Delta t/2\right]$. - - 1: Fourth-order Taylor approximation to the exponential. With $\mathcal{A}=-\mathrm{i}S^{-1}H\Delta t$, $U=I+\mathcal{A}+\mathcal{A}^2/2+\mathcal{A}^3/6+\mathcal{A}^4/24$. - - 2: Enforced time-reversal symmetry (ETRS), $U(t+\Delta t,t)=\exp\left[-\mathrm{i}S^{-1}H(t+\Delta t)\Delta t/2\right]\exp\left[-\mathrm{i}S^{-1}H(t)\Delta t/2\right]$. In the implementation, each exponential is replaced by the fourth-order Taylor polynomial from method 1 evaluated with a half time step. - - 3: Crank-Nicolson by directly solving $\left[S+\mathrm{i}H\Delta t/2\right]\psi(t+\Delta t)=\left[S-\mathrm{i}H\Delta t/2\right]\psi(t)$. - - > Note: GPU execution currently supports only method 0 in both single-GPU and multi-GPU solver configurations. CPU execution supports methods 0 through 3. -- **Default**: 0 - -### td_vext - -- **Type**: Boolean -- **Description**: Controls whether a time-dependent external electric field is applied. - - True: Add a laser-material interaction (external electric field). - - False: No external electric field. -- **Default**: False - -### td_vext_dire - -- **Type**: Vector of Integer -- **Description**: Specifies one absolute Cartesian direction for each external electric field when td_vext is enabled. Unlike the ground-state efield_dir parameter, these directions are not defined by lattice or reciprocal-lattice vectors. The number of values must equal that of td_ttype, and repeated directions are allowed; fields assigned to the same direction are added. For example, td_vext_dire 1 2 applies one field along Cartesian x and one along Cartesian y. - - 1: The external field direction is along the x-axis. - - 2: The external field direction is along the y-axis. - - 3: The external field direction is along the z-axis. -- **Default**: 1 - -### td_stype - -- **Type**: Integer -- **Description**: Type of electric field in the space domain, i.e. the gauge of the electric field. - - 0: Length gauge. - - 1: Velocity gauge. - - 2: Hybrid gauge. See J. Chem. Theory Comput. 2025, 21, 3335-3341 for more information. -- **Default**: 0 - -### td_ttype - -- **Type**: Vector of Integer -- **Description**: Specifies one time-domain type for each external electric field. Its number of values must equal that of td_vext_dire. Parameters belonging to each type must provide exactly one value for every occurrence of that type, in occurrence order; fields with a repeated direction are added. - - The formulas below use Hartree atomic units. For every ordinary input frequency $f$, $\omega=2\pi f$; $\Delta t=\mathtt{td\_dt}$; and $E_0$ denotes the corresponding amplitude parameter. A step-valued parameter $n_q$ represents the physical time $t_q=n_q\Delta t$. - - - 0: Gaussian pulse, $E(t)=E_0\cos\left[\omega(t-t_0)+\varphi\right]\mathrm{e}^{-(t-t_0)^2/(2\sigma^2)}$, where $t_0=\mathtt{td\_gauss\_t0}\Delta t$. - - 1: Trapezoid pulse, $E(t)=E_0g(t)\cos(\omega t+\varphi)$. With $t_1=\mathtt{td\_trape\_t1}\Delta t$, $t_2=\mathtt{td\_trape\_t2}\Delta t$, and $t_3=\mathtt{td\_trape\_t3}\Delta t$, the envelope is $g(t)=t/t_1$ for $0\leqslant t\lt t_1$, $g(t)=1$ for $t_1\leqslant t\lt t_2$, $g(t)=(t_3-t)/(t_3-t_2)$ for $t_2\leqslant t\lt t_3$, and $g(t)=0$ otherwise. - - 2: Trigonometric pulse, $E(t)=E_0\cos(\omega_1t+\varphi_1)\sin^2(\omega_2t+\varphi_2)$. - - 3: Heaviside pulse defined on electronic steps. With $n_0=\mathtt{td\_heavi\_t0}$, $E(n)=E_0$ for $n\lt n_0$ and $E(n)=0$ for $n\geqslant n_0$. - - 4: Finite-support supersine pulse. For $t_{\mathrm{s}}\lt t\lt t_{\mathrm{e}}$, the envelope is $f(t)=\left\{\sin\left[\pi\frac{t-t_{\mathrm{s}}}{t_{\mathrm{e}}-t_{\mathrm{s}}}\right]\right\}^{\frac{\pi}{\sigma}\left|\frac{t-t_{\mathrm{s}}}{t_{\mathrm{e}}-t_{\mathrm{s}}}-\frac{1}{2}\right|}$ and the electric field is $E(t)=E_0\left\{f(t)\cos\left[\omega\left(t-\frac{t_{\mathrm{s}}+t_{\mathrm{e}}}{2}\right)+\varphi\right]+\frac{\dot{f}(t)}{\omega}\sin\left[\omega\left(t-\frac{t_{\mathrm{s}}+t_{\mathrm{e}}}{2}\right)+\varphi\right]\right\}$. The corresponding analytic vector potential is $\boldsymbol{A}(t)=-\frac{E_0}{\omega}f(t)\sin\left[\omega\left(t-\frac{t_{\mathrm{s}}+t_{\mathrm{e}}}{2}\right)+\varphi\right]\hat{\boldsymbol{e}}$, with $\boldsymbol{E}(t)=-\partial\boldsymbol{A}(t)/\partial t$. The envelope, electric field, and vector potential are zero at the pulse boundaries and outside the interval. - - In the velocity and hybrid gauges, ABACUS obtains the vector potential actually used in propagation by Simpson integration of the selected electric fields, including the supersine field, so a residual at the numerical-quadrature accuracy scale may remain. -- **Default**: 0 - -### td_tstart - -- **Type**: Integer -- **Description**: First electronic step at which the time-dependent electric field is active. The interval from td_tstart through td_tend includes both endpoints. On each active step $n$, the velocity and hybrid gauges integrate the field over $[n\Delta t,(n+1)\Delta t]$, where $\Delta t=\mathtt{td\_dt}$. -- **Default**: 1 - -### td_tend - -- **Type**: Integer -- **Description**: Last electronic step at which the time-dependent electric field is active. The interval from td_tstart through td_tend includes both endpoints. On each active step $n$, the velocity and hybrid gauges integrate the field over $[n\Delta t,(n+1)\Delta t]$, where $\Delta t=\mathtt{td\_dt}$. -- **Default**: 1000 - -### td_lcut1 - -- **Type**: Real -- **Description**: Lower fractional-coordinate cutoff for the periodic spatial modulation used in the length gauge. Let $c_1=\mathtt{td\_lcut1}$, $c_2=\mathtt{td\_lcut2}$, $D=c_2-c_1$, and $G=c_1+1-c_2$. For a fractional coordinate $x$, the field factor is $\eta(x)=1$ when $c_1\leqslant x\lt c_2$ and $\eta(x)=-D/G$ elsewhere. The reversed outer interval makes the potential periodic and continuous and gives the field zero cell average. -- **Default**: 0.05 - -### td_lcut2 - -- **Type**: Real -- **Description**: Upper fractional-coordinate cutoff for the periodic spatial modulation used in the length gauge. Let $c_1=\mathtt{td\_lcut1}$, $c_2=\mathtt{td\_lcut2}$, $D=c_2-c_1$, and $G=c_1+1-c_2$. For a fractional coordinate $x$, the field factor is $\eta(x)=1$ when $c_1\leqslant x\lt c_2$ and $\eta(x)=-D/G$ elsewhere. The reversed outer interval makes the potential periodic and continuous and gives the field zero cell average. -- **Default**: 0.95 - -### td_gauss_freq - -- **Type**: Vector of Real -- **Availability**: *[`td_ttype`](#td_ttype) contains 0* -- **Description**: Ordinary frequency $f$ in the Gaussian-pulse formula, with $\omega=2\pi f$. Supply exactly one value for each td_ttype 0 occurrence, in occurrence order. -- **Default**: 22.13 -- **Unit**: 1/fs - -### td_gauss_phase - -- **Type**: Vector of Real -- **Availability**: *[`td_ttype`](#td_ttype) contains 0* -- **Description**: Carrier phase $\varphi$ in the Gaussian-pulse formula. Supply exactly one value for each td_ttype 0 occurrence, in occurrence order. -- **Default**: 0.0 -- **Unit**: rad - -### td_gauss_sigma - -- **Type**: Vector of Real -- **Availability**: *[`td_ttype`](#td_ttype) contains 0* -- **Description**: Nonzero standard deviation $\sigma$ of the Gaussian envelope. Supply exactly one value for each td_ttype 0 occurrence, in occurrence order. -- **Default**: 30.0 -- **Unit**: fs - -### td_gauss_t0 - -- **Type**: Vector of Real -- **Availability**: *[`td_ttype`](#td_ttype) contains 0* -- **Description**: Electronic-step position of the Gaussian center, which defines $t_0=\mathtt{td\_gauss\_t0}\Delta t$. Supply exactly one value for each td_ttype 0 occurrence, in occurrence order. -- **Default**: 100 - -### td_gauss_amp - -- **Type**: Vector of Real -- **Availability**: *[`td_ttype`](#td_ttype) contains 0* -- **Description**: Electric-field scale $E_0$ in the Gaussian-pulse formula. Supply exactly one value for each td_ttype 0 occurrence, in occurrence order. -- **Default**: 0.25 -- **Unit**: V/Angstrom - -### td_trape_freq - -- **Type**: Vector of Real -- **Availability**: *[`td_ttype`](#td_ttype) contains 1* -- **Description**: Ordinary carrier frequency $f$ in the trapezoid-pulse formula, with $\omega=2\pi f$. Supply exactly one value for each td_ttype 1 occurrence, in occurrence order. -- **Default**: 1.60 -- **Unit**: 1/fs - -### td_trape_phase - -- **Type**: Vector of Real -- **Availability**: *[`td_ttype`](#td_ttype) contains 1* -- **Description**: Carrier phase $\varphi$ in the trapezoid-pulse formula. Supply exactly one value for each td_ttype 1 occurrence, in occurrence order. -- **Default**: 0.0 -- **Unit**: rad - -### td_trape_t1 - -- **Type**: Vector of Real -- **Availability**: *[`td_ttype`](#td_ttype) contains 1* -- **Description**: Electronic step defining the end of the linear rise, $t_1=\mathtt{td\_trape\_t1}\Delta t$. Each field must satisfy td_trape_t1 <= td_trape_t2 <= td_trape_t3. Supply exactly one value for each td_ttype 1 occurrence, in occurrence order. -- **Default**: 1875 - -### td_trape_t2 - -- **Type**: Vector of Real -- **Availability**: *[`td_ttype`](#td_ttype) contains 1* -- **Description**: Electronic step defining the end of the plateau, $t_2=\mathtt{td\_trape\_t2}\Delta t$. Each field must satisfy td_trape_t1 <= td_trape_t2 <= td_trape_t3. Supply exactly one value for each td_ttype 1 occurrence, in occurrence order. -- **Default**: 5625 - -### td_trape_t3 - -- **Type**: Vector of Real -- **Availability**: *[`td_ttype`](#td_ttype) contains 1* -- **Description**: Electronic step defining the end of the linear fall, $t_3=\mathtt{td\_trape\_t3}\Delta t$. Each field must satisfy td_trape_t1 <= td_trape_t2 <= td_trape_t3. Supply exactly one value for each td_ttype 1 occurrence, in occurrence order. -- **Default**: 7500 - -### td_trape_amp - -- **Type**: Vector of Real -- **Availability**: *[`td_ttype`](#td_ttype) contains 1* -- **Description**: Electric-field scale $E_0$ in the trapezoid-pulse formula. Supply exactly one value for each td_ttype 1 occurrence, in occurrence order. -- **Default**: 2.74 -- **Unit**: V/Angstrom - -### td_trigo_freq1 - -- **Type**: Vector of Real -- **Availability**: *[`td_ttype`](#td_ttype) contains 2* -- **Description**: First ordinary frequency $f_1$ in the trigonometric-pulse formula, with $\omega_1=2\pi f_1$. Supply exactly one value for each td_ttype 2 occurrence, in occurrence order. -- **Default**: 1.164656 -- **Unit**: 1/fs - -### td_trigo_freq2 - -- **Type**: Vector of Real -- **Availability**: *[`td_ttype`](#td_ttype) contains 2* -- **Description**: Second ordinary frequency $f_2$ in the trigonometric-pulse formula, with $\omega_2=2\pi f_2$. Supply exactly one value for each td_ttype 2 occurrence, in occurrence order. -- **Default**: 0.029116 -- **Unit**: 1/fs - -### td_trigo_phase1 - -- **Type**: Vector of Real -- **Availability**: *[`td_ttype`](#td_ttype) contains 2* -- **Description**: Carrier phase $\varphi_1$ in the cosine factor of the trigonometric-pulse formula. Supply exactly one value for each td_ttype 2 occurrence, in occurrence order. -- **Default**: 0.0 -- **Unit**: rad - -### td_trigo_phase2 - -- **Type**: Vector of Real -- **Availability**: *[`td_ttype`](#td_ttype) contains 2* -- **Description**: Envelope phase $\varphi_2$ in the sine-squared factor of the trigonometric-pulse formula. Supply exactly one value for each td_ttype 2 occurrence, in occurrence order. -- **Default**: 0.0 -- **Unit**: rad - -### td_trigo_amp - -- **Type**: Vector of Real -- **Availability**: *[`td_ttype`](#td_ttype) contains 2* -- **Description**: Electric-field scale $E_0$ in the trigonometric-pulse formula. Supply exactly one value for each td_ttype 2 occurrence, in occurrence order. -- **Default**: 2.74 -- **Unit**: V/Angstrom - -### td_heavi_t0 - -- **Type**: Vector of Real -- **Availability**: *[`td_ttype`](#td_ttype) contains 3* -- **Description**: Electronic switch step $n_0$ in the Heaviside-pulse definition. The field is $E_0$ for $n\lt n_0$ and zero for $n\geqslant n_0$. Supply exactly one value for each td_ttype 3 occurrence, in occurrence order. -- **Default**: 100 - -### td_heavi_amp - -- **Type**: Vector of Real -- **Availability**: *[`td_ttype`](#td_ttype) contains 3* -- **Description**: Electric-field scale $E_0$ in the Heaviside-pulse definition. Supply exactly one value for each td_ttype 3 occurrence, in occurrence order. -- **Default**: 1.0 -- **Unit**: V/Angstrom - -### td_supsine_amp - -- **Type**: Vector of Real -- **Availability**: *[`td_ttype`](#td_ttype) contains 4* -- **Description**: Carrier electric-field scale $E_0$ of each supersine pulse. This is not a normalization of the complete waveform maximum, because the envelope-derivative term also contributes. Supply exactly one value for each td_ttype 4 occurrence, in occurrence order. -- **Default**: 0.27 -- **Unit**: V/Angstrom - -### td_supsine_freq - -- **Type**: Vector of Real -- **Availability**: *[`td_ttype`](#td_ttype) contains 4* -- **Description**: Nonzero ordinary carrier frequency $f$ of each supersine pulse, with $\omega=2\pi f$. Supply exactly one value for each td_ttype 4 occurrence, in occurrence order. -- **Default**: 0.18737028625 -- **Unit**: 1/fs - -### td_supsine_phase - -- **Type**: Vector of Real -- **Availability**: *[`td_ttype`](#td_ttype) contains 4* -- **Description**: Electric-field carrier phase $\varphi$ at the center of each supersine envelope. A value of 0 places a cosine carrier maximum at the envelope center. Supply exactly one value for each td_ttype 4 occurrence, in occurrence order. -- **Default**: 0.0 -- **Unit**: rad - -### td_supsine_sigma - -- **Type**: Vector of Real -- **Availability**: *[`td_ttype`](#td_ttype) contains 4* -- **Description**: Dimensionless shape parameter $\sigma$ of each supersine envelope. It must satisfy $0\lt\sigma\lt\pi/2$ so that the electric field approaches zero at the pulse boundaries. Supply exactly one value for each td_ttype 4 occurrence, in occurrence order. -- **Default**: 0.75 - -### td_supsine_tstart - -- **Type**: Vector of String -- **Availability**: *[`td_ttype`](#td_ttype) contains 4* -- **Description**: Integer electronic step at the left, exactly zero boundary of each supersine pulse, defining $t_{\mathrm{s}}=\mathtt{td\_supsine\_tstart}\Delta t$. Supply exactly one integer or default token for each td_ttype 4 occurrence, in occurrence order; each default token inherits td_tstart. The complete pulse support must lie inside the inclusive global td_tstart to td_tend interval; hard truncation of a supersine pulse is rejected. -- **Default**: default - -### td_supsine_tend - -- **Type**: Vector of String -- **Availability**: *[`td_ttype`](#td_ttype) contains 4* -- **Description**: Integer electronic step at the right, exactly zero boundary of each supersine pulse, defining $t_{\mathrm{e}}=\mathtt{td\_supsine\_tend}\Delta t$. Supply exactly one integer or default token for each td_ttype 4 occurrence, in occurrence order; each default token inherits td_tend. The complete pulse support must lie inside the inclusive global td_tstart to td_tend interval; hard truncation of a supersine pulse is rejected. -- **Default**: default - -### init_vecpot_file - -- **Type**: Boolean -- **Description**: Selects the source of the Cartesian vector potential used by LCAO RT-TDDFT. - - True: Read vector_pot.txt from the calculation working directory. Each non-comment line must contain four columns: a conventionally one-based electronic-step label followed by $A_x$, $A_y$, and $A_z$ in atomic units. Rows are consumed sequentially; the first column is read as a label and is not used for lookup. If propagation continues beyond the available rows, the last row is reused. - - False: Obtain the vector potential by integrating the configured electric field. -- **Default**: False - -### ocp - -- **Type**: Boolean -- **Description**: Controls fixed band occupations. In calculations other than LCAO RT-TDDFT, fixed values are applied during electronic-state setup. In LCAO RT-TDDFT, the initial ground-state SCF determines occupations normally, and fixed values from ocp_set are applied during the subsequent real-time propagation steps. - - True: Use the fixed occupations specified by ocp_set during propagation. - - False: Keep the occupations determined by the initial SCF. -- **Default**: False - -### ocp_set - -- **Type**: String -- **Description**: Fixed occupation weights used when ocp is true. Values are assigned in band order for each k-point, following k-point order. In LCAO RT-TDDFT, the initial ground-state SCF uses its normally determined occupations, and this array is applied only during subsequent real-time propagation steps. The repetition syntax N*x expands to N copies of x. - - Example: 1 10*1 0 1 expands to 13 values, with the 12th value equal to 0 and all other values equal to 1. - - After expansion, provide one block of nbands values for each k-point. If nspin is 2, provide all k-point blocks for spin up followed by all k-point blocks for spin down; otherwise, provide one block per k-point. - - The sum of all weights must equal nelec; otherwise the calculation terminates with an error. -- **Default**: None - -### out_dipole - -- **Type**: Boolean -- **Description**: Controls electric-dipole output. In RT-TDDFT, each enabled spin channel is written to OUT.{suffix}/dipole_s[spin].txt using a one-based spin number. Every row contains the one-based electronic-step index followed by the Cartesian electronic-dipole components $P_x$, $P_y$, and $P_z$ in atomic units. The running log additionally reports the electronic, ionic, and total dipoles and the norm of the total dipole. - - True: Output the electric dipole information. - - False: Do not output the electric dipole information. -- **Default**: False - -### out_current - -- **Type**: Integer -- **Availability**: *[`basis_type`](#basis_type)==lcao and [`esolver_type`](#esolver_type)==tddft* -- **Description**: Controls the current-density output method for LCAO RT-TDDFT. Output rows contain the one-based electronic-step index followed by $J_x$, $J_y$, and $J_z$ in atomic units. - - 0: Do not output current. - - 1: Explicitly construct the velocity operator from the momentum, vector-potential, and KB nonlocal-pseudopotential terms using two-center and spherical-grid integrals: $\hat{v}_{\alpha}=-\mathrm{i}\nabla_{\alpha}+A_{\alpha}(t)+\mathrm{i}\left[\widetilde{V}_{\mathrm{NL}}^{\mathrm{KB}},r_{\alpha}\right]$, where $\widetilde{V}_{\mathrm{NL}}^{\mathrm{KB}}=\mathrm{e}^{-\mathrm{i}\boldsymbol{A}(t)\cdot\boldsymbol{r}}\hat{V}_{\mathrm{NL}}^{\mathrm{KB}}\mathrm{e}^{\mathrm{i}\boldsymbol{A}(t)\cdot\boldsymbol{r}}$. $\boldsymbol{A}(t)$ is nonzero only for the velocity gauge (td_stype=1); otherwise $\boldsymbol{A}(t)=0$. Other nonlocal Hamiltonian terms, such as EXX, are not included explicitly. The total current is written to OUT.{suffix}/current_tot.txt. - - 2: Use the full Hamiltonian to construct the generalized velocity matrix in a nonorthogonal NAO basis, $\widetilde{v}_{\alpha}=\partial_{\alpha}H+\mathrm{i}HS^{-1}\mathcal{R}_{\alpha}-\mathrm{i}\mathcal{R}_{\alpha}S^{-1}H-HS^{-1}\partial_{\alpha}S$. This includes all contributions available in the real-space Hamiltonian matrix when enabled. This method is more general but more expensive. The total current is written to OUT.{suffix}/current_tot_comm.txt. -- **Default**: 0 - -### out_current_k - -- **Type**: Boolean -- **Availability**: *[`basis_type`](#basis_type)==lcao and [`esolver_type`](#esolver_type)==tddft and [`out_current`](#out_current)>0* -- **Description**: Controls whether LCAO RT-TDDFT current density is also resolved by spin and k-point. The total-current file is always written when out_current is 1 or 2. - - True: In addition to the total, out_current=1 writes OUT.{suffix}/current_s[spin]k[kpoint].txt; out_current=2 writes OUT.{suffix}/current_s[spin]k[kpoint]_comm.txt. Both use one-based spin and k-point numbers, with k-points numbered independently within each spin channel. Each row contains the one-based electronic-step index followed by $J_x$, $J_y$, and $J_z$ in atomic units. - - False: Output only current_tot.txt for out_current=1 or current_tot_comm.txt for out_current=2. -- **Default**: False - -### out_efield - -- **Type**: Boolean -- **Availability**: *[`esolver_type`](#esolver_type)==tddft and [`td_vext`](#td_vext)==true* -- **Description**: Controls time-dependent electric-field output. For each configured field, OUT.{suffix}/efield_[index].txt contains two columns: physical time in fs and the field value in V/Angstrom. The one-based field index follows the occurrence order shared by td_ttype and td_vext_dire, so fields assigned to the same direction remain in separate files. At initialization, a fresh calculation with md_restart=False truncates the files corresponding to the currently configured fields, whereas a calculation with md_restart=True preserves them and appends new samples. - - True: Output electric-field values on active electronic steps. - - False: Do not output electric-field values. -- **Default**: False - -### out_vecpot - -- **Type**: Boolean -- **Availability**: *[`basis_type`](#basis_type)==lcao and [`esolver_type`](#esolver_type)==tddft* -- **Description**: Controls Cartesian vector-potential output for LCAO RT-TDDFT. OUT.{suffix}/vector_pot.txt contains four columns: the one-based electronic-step index followed by $A_x$, $A_y$, and $A_z$ in atomic units. At initialization, a fresh calculation with md_restart=False truncates the file and writes a new header, whereas a calculation with md_restart=True preserves a nonempty existing file and appends new samples. If the restart output file is missing or empty, a new file with a header is created. - - True: Write vector-potential samples on electronic propagation steps. - - False: Do not output the vector potential. -- **Default**: False - -[back to top](#full-list-of-input-keywords) - -## Variables useful for debugging - -### nurse - -- **Type**: Integer -- **Description**: Debugging flag for developers -- **Default**: 0 - -### t_in_h - -- **Type**: Boolean -- **Description**: Specify whether to include kinetic term in obtaining the Hamiltonian matrix. - - 0: No. - - 1: Yes. -- **Default**: 1 - -### vl_in_h - -- **Type**: Boolean -- **Description**: Specify whether to include local pseudopotential term in obtaining the Hamiltonian matrix. - - 0: No. - - 1: Yes. -- **Default**: 1 - -### vnl_in_h - -- **Type**: Boolean -- **Description**: Specify whether to include non-local pseudopotential term in obtaining the Hamiltonian matrix. - - 0: No. - - 1: Yes. -- **Default**: 1 - -### vh_in_h - -- **Type**: Boolean -- **Description**: Specify whether to include Hartree potential term in obtaining the Hamiltonian matrix. - - 0: No. - - 1: Yes. -- **Default**: 1 - -### vion_in_h - -- **Type**: Boolean -- **Description**: Specify whether to include local ionic potential term in obtaining the Hamiltonian matrix. - - 0: No. - - 1: Yes. -- **Default**: 1 - -### test_force - -- **Type**: Boolean -- **Description**: Specify whether to output the detailed components in forces. - - 0: No. - - 1: Yes. -- **Default**: 0 - -### test_stress - -- **Type**: Boolean -- **Description**: Specify whether to output the detailed components in stress. - - 0: No. - - 1: Yes. -- **Default**: 0 - -### test_skip_ewald - -- **Type**: Boolean -- **Description**: Specify whether to skip the calculation of the ewald energy. - - 0: No. - - 1: Yes. -- **Default**: 0 - -[back to top](#full-list-of-input-keywords) - -## Electronic conductivities - -### cal_cond - -- **Type**: Boolean -- **Availability**: *[`basis_type`](#basis_type)==pw* -- **Description**: Whether to calculate electronic conductivities. -- **Default**: False - -### cond_che_thr - -- **Type**: Real -- **Availability**: *[`esolver_type`](#esolver_type)==sdft* -- **Description**: Control the error of Chebyshev expansions for conductivities. -- **Default**: 1e-8 - -### cond_dw - -- **Type**: Real -- **Availability**: *[`basis_type`](#basis_type)==pw* -- **Description**: Frequency interval () for frequency-dependent conductivities. -- **Default**: 0.1 -- **Unit**: eV - -### cond_wcut - -- **Type**: Real -- **Availability**: *[`basis_type`](#basis_type)==pw* -- **Description**: Cutoff frequency for frequency-dependent conductivities. -- **Default**: 10.0 -- **Unit**: eV - -### cond_dt - -- **Type**: Real -- **Availability**: *[`basis_type`](#basis_type)==pw* -- **Description**: Time interval () to integrate Onsager coefficients. -- **Default**: 0.02 -- **Unit**: a.u. - -### cond_dtbatch - -- **Type**: Integer -- **Availability**: *[`esolver_type`](#esolver_type)==sdft* -- **Description**: exp(iH\dt\cond_dtbatch) is expanded with Chebyshev expansion to calculate conductivities. It is faster but costs more memory. - - If cond_dtbatch = 0: Autoset this parameter to make expansion orders larger than 100. -- **Default**: 0 - -### cond_smear - -- **Type**: Integer -- **Description**: Smearing method for conductivities - - 1: Gaussian smearing - - 2: Lorentzian smearing -- **Default**: 1 - -### cond_fwhm - -- **Type**: Real -- **Availability**: *[`basis_type`](#basis_type)==pw* -- **Description**: FWHM for conductivities. For Gaussian smearing, ; for Lorentzian smearing, . -- **Default**: 0.4 -- **Unit**: eV - -### cond_nonlocal - -- **Type**: Boolean -- **Availability**: *[`basis_type`](#basis_type)==pw* -- **Description**: Whether to consider nonlocal potential correction when calculating velocity matrix . - - True: . - - False: . -- **Default**: True - -[back to top](#full-list-of-input-keywords) - -## Implicit solvation model - -### imp_sol - -- **Type**: Boolean -- **Description**: Calculate implicit solvation correction -- **Default**: False - -### eb_k - -- **Type**: Real -- **Availability**: *[`imp_sol`](#imp_sol)==true* -- **Description**: The relative permittivity of the bulk solvent, 80 for water -- **Default**: 80 - -### tau - -- **Type**: Real -- **Description**: The effective surface tension parameter that describes the cavitation, the dispersion, and the repulsion interaction between the solute and the solvent which are not captured by the electrostatic terms -- **Default**: 1.0798e-05 - -### sigma_k - -- **Type**: Real -- **Description**: The width of the diffuse cavity that is implicitly determined by the electronic structure of the solute -- **Default**: 0.6 - -### nc_k - -- **Type**: Real -- **Description**: The value of the electron density at which the dielectric cavity forms -- **Default**: 0.00037 - -[back to top](#full-list-of-input-keywords) - -## Quasiatomic Orbital (QO) analysis - -### qo_switch - -- **Type**: Boolean -- **Description**: Whether to let ABACUS output QO analysis required files -- **Default**: False - -### qo_basis - -- **Type**: String -- **Description**: Type of QO basis function: - - hydrogen: hydrogen-like basis - - pswfc: read basis from pseudopotential - - szv: single-zeta valence basis -- **Default**: szv - -### qo_strategy - -- **Type**: Vector of String (1 or n values where n is the number of atomic types) -- **Description**: Strategy to generate radial orbitals for QO analysis. For hydrogen: energy-valence, for pswfc and szv: all -- **Default**: for hydrogen: energy-valence, for pswfc and szv: all - -### qo_screening_coeff - -- **Type**: Vector of Real (n values where n is the number of atomic types; 1 value allowed for qo_basis=pswfc) -- **Description**: The screening coefficient for each atom type to rescale the shape of radial orbitals -- **Default**: 0.1 -- **Unit**: Bohr^-1 - -### qo_thr - -- **Type**: Real -- **Description**: The convergence threshold determining the cutoff of generated orbital. Lower threshold will yield orbital with larger cutoff radius. -- **Default**: 1.0e-6 - -[back to top](#full-list-of-input-keywords) - -## PEXSI - -### pexsi_npole - -- **Type**: Integer -- **Description**: The number of poles used in the pole expansion method, should be a even number. -- **Default**: 40 - -### pexsi_inertia - -- **Type**: Boolean -- **Description**: Whether inertia counting is used at the very beginning. -- **Default**: True - -### pexsi_nmax - -- **Type**: Integer -- **Description**: Maximum number of PEXSI iterations after each inertia counting procedure. -- **Default**: 80 - -### pexsi_comm - -- **Type**: Boolean -- **Description**: Whether to construct PSelInv communication pattern. -- **Default**: True - -### pexsi_storage - -- **Type**: Boolean -- **Description**: Whether to use symmetric storage space used by the Selected Inversion algorithm for symmetric matrices. -- **Default**: True - -### pexsi_ordering - -- **Type**: Integer -- **Description**: Ordering strategy for factorization and selected inversion. 0: Parallel ordering using ParMETIS, 1: Sequential ordering using METIS, 2: Multiple minimum degree ordering -- **Default**: 0 - -### pexsi_row_ordering - -- **Type**: Integer -- **Description**: Row permutation strategy for factorization and selected inversion, 0: No row permutation, 1: Make the diagonal entry of the matrix larger than the off-diagonal entries. -- **Default**: 1 - -### pexsi_nproc - -- **Type**: Integer -- **Description**: Number of processors for PARMETIS. Only used if pexsi_ordering == 0. -- **Default**: 1 - -### pexsi_symm - -- **Type**: Boolean -- **Description**: Whether the matrix is symmetric. -- **Default**: True - -### pexsi_trans - -- **Type**: Boolean -- **Description**: Whether to factorize the transpose of the matrix. -- **Default**: False - -### pexsi_method - -- **Type**: Integer -- **Description**: The pole expansion method to be used. 1 for Cauchy Contour Integral method, 2 for Moussa optimized method. -- **Default**: 1 - -### pexsi_nproc_pole - -- **Type**: Integer -- **Description**: The point parallelizaion of PEXSI. Recommend two points parallelization. -- **Default**: 1 - -### pexsi_temp - -- **Type**: Real -- **Description**: Temperature in Fermi-Dirac distribution, in Ry, should have the same effect as the smearing sigma when smearing method is set to Fermi-Dirac. -- **Default**: 0.015 - -### pexsi_gap - -- **Type**: Real -- **Description**: Spectral gap, this can be set to be 0 in most cases. -- **Default**: 0 - -### pexsi_delta_e - -- **Type**: Real -- **Description**: Upper bound for the spectral radius of S^{-1}H. -- **Default**: 20 - -### pexsi_mu_lower - -- **Type**: Real -- **Description**: Initial guess of lower bound for mu. -- **Default**: -10 - -### pexsi_mu_upper - -- **Type**: Real -- **Description**: Initial guess of upper bound for mu. -- **Default**: 10 - -### pexsi_mu - -- **Type**: Real -- **Description**: Initial guess for mu (for the solver). -- **Default**: 0 - -### pexsi_mu_thr - -- **Type**: Real -- **Description**: Stopping criterion in terms of the chemical potential for the inertia counting procedure. -- **Default**: 0.05 - -### pexsi_mu_expand - -- **Type**: Real -- **Description**: If the chemical potential is not in the initial interval, the interval is expanded by this value. -- **Default**: 0.3 - -### pexsi_mu_guard - -- **Type**: Real -- **Description**: Safe guard criterion in terms of the chemical potential to reinvoke the inertia counting procedure. -- **Default**: 0.2 - -### pexsi_elec_thr - -- **Type**: Real -- **Description**: Stopping criterion of the PEXSI iteration in terms of the number of electrons compared to numElectronExact. -- **Default**: 0.001 - -### pexsi_zero_thr - -- **Type**: Real -- **Description**: if the absolute value of CCS matrix element is less than this value, it will be considered as zero. -- **Default**: 1e-10 - -[back to top](#full-list-of-input-keywords) - -## Linear Response TDDFT - -### xc_kernel - -- **Type**: String -- **Description**: The exchange-correlation kernel used in the calculation. Currently supported: RPA, LDA, PBE, HSE, HF. -- **Default**: LDA - -### lr_init_xc_kernel - -- **Type**: Vector of String (>=1 values) -- **Description**: The method to initalize the xc kernel. - - "default": Calculate xc kernel from the ground-state charge density. - - "file": Read the xc kernel on grid from the provided files. The following words should be the paths of ".cube" files, where the first 1 (nspin==1) or 3 (nspin==2, namely spin-aa, spin-ab and spin-bb) will be read in. The parameter xc_kernel will be invalid. Now only LDA-type kernel is supported as the potential will be calculated by directly multiplying the transition density. - - "from_charge_file": Calculate fxc from the charge density read from the provided files. The following words should be the paths of ".cube" files, where the first nspin files will be read in. -- **Default**: "default" - -### lr_solver - -- **Type**: String -- **Description**: The method to solve the Casida equation in LR-TDDFT under Tamm-Dancoff approximation (TDA). - - dav/dav_subspace/cg: Construct and diagonalize the Hamiltonian matrix iteratively with Davidson/Non-ortho-Davidson/CG algorithm. - - lapack: Construct the full matrix and directly diagonalize with LAPACK. - - spectrum: Calculate absorption spectrum only without solving Casida equation. -- **Default**: dav - -### lr_thr - -- **Type**: Real -- **Description**: The convergence threshold of iterative diagonalization solver for LR-TDDFT. It is a pure-math number with the same meaning as pw_diag_thr, but since the Casida equation is a one-shot eigenvalue problem, it is also the convergence threshold of LR-TDDFT. -- **Default**: 1e-2 - -### nocc - -- **Type**: Integer -- **Description**: The number of occupied orbitals (up to HOMO) used in the LR-TDDFT calculation. - - Note: If the value is illegal ( > nelec/2 or <= 0), it will be autoset to nelec/2. -- **Default**: nband - -### nvirt - -- **Type**: Integer -- **Description**: The number of virtual orbitals (starting from LUMO) used in the LR-TDDFT calculation. -- **Default**: 1 - -### lr_nstates - -- **Type**: Integer -- **Description**: The number of 2-particle states to be solved. -- **Default**: 0 - -### lr_unrestricted - -- **Type**: Boolean -- **Description**: Whether to use unrestricted construction for LR-TDDFT (the matrix size will be doubled). - - True: Always use unrestricted LR-TDDFT. - - False: Use unrestricted LR-TDDFT only when the system is open-shell. -- **Default**: False - -### abs_wavelen_range - -- **Type**: Real Real -- **Description**: The range of the wavelength for the absorption spectrum calculation. -- **Default**: 0.0 0.0 -- **Unit**: nm - -### out_wfc_lr - -- **Type**: Boolean -- **Description**: Whether to output the eigenstates (excitation energy) and eigenvectors (excitation amplitude) of the LR-TDDFT calculation. The output files are OUT.{suffix}/Excitation_Amplitude_${processor_rank}.dat. -- **Default**: False - -### abs_gauge - -- **Type**: String -- **Description**: Whether to use length or velocity gauge to calculate the absorption spectrum in LR-TDDFT. -- **Default**: velocity - -### abs_broadening - -- **Type**: Real -- **Description**: The broadening factor for the absorption spectrum calculation. -- **Default**: 0.01 - -### plot_istate - -- **Type**: Integer -- **Description**: The index of the excited state to plot, starting from 0. -- **Default**: 0 - -### exciton_plot_type - -- **Type**: String -- **Description**: Exciton density represented when lr_solver is 'plot': 'average' integrates out the other particle, while 'conditional' fixes one particle at exciton_fixed_coordinate and plots a slice of the other particle's density. -- **Default**: average - -### exciton_plot_format - -- **Type**: String -- **Availability**: *[`lr_solver`](#lr_solver)==plot* -- **Description**: The exciton-density output format. Average density supports cube, slice, and both; conditional density supports slice only. -- **Default**: cube - -### exciton_fixed_coordinate - -- **Type**: Vector of Real (6 values) -- **Description**: Cartesian coordinates in Bohr used by conditional exciton plotting, in the order hole_x hole_y hole_z electron_x electron_y electron_z. -- **Default**: 0.0 0.0 0.0 0.0 0.0 0.0 - -### exciton_slice_plane - -- **Type**: String -- **Description**: Pair of lattice-vector directions spanning the cross section: 'ab', 'bc', or 'ca'. -- **Default**: ab - -### exciton_slice_pos - -- **Type**: Real -- **Description**: Offset in Bohr along the remaining lattice-vector direction: c for an ab slice, a for bc, and b for ca. -- **Default**: 0.0 - -### exciton_slice_npoints - -- **Type**: Integer -- **Description**: Target in-plane grid resolution. The final grid uses a uniform number of points per primitive cell over `exciton_slice_range` and includes both endpoints. -- **Default**: 200 - -### exciton_slice_range - -- **Type**: Vector of Integer (4 values) -- **Availability**: *[`lr_solver`](#lr_solver)==plot and [`exciton_plot_format`](#exciton_plot_format) in [slice, both]* -- **Description**: The in-plane primitive-cell range of an exciton slice: ustart uend vstart vend. The end values are exclusive cell boundaries, while grid data include both range endpoints. -- **Default**: -1 2 -1 2 -- **Unit**: primitive cells - -### ri_hartree_benchmark - -- **Type**: String -- **Description**: Whether to use the RI approximation for the Hartree term in LR-TDDFT for benchmark (with FHI-aims/ABACUS read-in style) -- **Default**: none - -### aims_nbasis - -- **Type**: A number(ntype) of Integers -- **Availability**: *[`ri_hartree_benchmark`](#ri_hartree_benchmark)==aims* -- **Description**: Atomic basis set size for each atom type (with the same order as in STRU) in FHI-aims. -- **Default**: {} (empty list, where ABACUS use its own basis set size) - -[back to top](#full-list-of-input-keywords) - -## Bethe-Salpeter Equation - -### bse_tda - -- **Type**: String -- **Description**: Whether the Tamm-Dancoff approximation is used: 'tda', 'full', or 'both'. -- **Default**: tda - -### bse_spin_types - -- **Type**: Vector of String (>=1 values) -- **Description**: Spin types for a closed-shell calculation in one task: 'singlet', 'triplet', and the test modes 'rpa' and 'ipa'. -- **Default**: singlet triplet - -### bse_mem_save - -- **Type**: Boolean -- **Description**: Whether to save memory by adding V and W directly to the BSE matrix. When enabled, bse_ri_hartree is enabled and bse_continue is reset to 0. -- **Default**: false - -### bse_ri_hartree - -- **Type**: Boolean -- **Description**: Whether to use the RI approximation for the Hartree term in BSE. -- **Default**: true - -### bse_use_fine_kgrid - -- **Type**: Integer -- **Description**: Fine k-grid mode for BSE: 0 uses the coarse k-grid, 1 uses a uniform fine k-grid, and 2 uses a non-uniform fine k-grid. Modes 1 and 2 require band_kpath_info, band_KS_eigenvector_k_{index}.txt, KS_band_spin_{index}.txt, and GW_band_spin_{index}.txt. -- **Default**: 0 - -### bse_q_approx_mode - -- **Type**: Integer -- **Description**: q-to-k-pair mapping mode for W: 0=exact, 1=coarse q grid, 2=mixed, 3=truncate pairs with |q|>threshold (W elements dropped) -- **Default**: 0 - -### bse_q_approx_threshold - -- **Type**: Real -- **Description**: Threshold radius in unit of 2*pi/lat0 (same unit system as kvec_c) for exact q-to-k-pair mapping when bse_q_approx_mode is 2; in mode 3 pairs with larger |q| are dropped entirely. -- **Default**: 0.1 - -### out_bse_ab - -- **Type**: Boolean -- **Description**: Whether to output the AB matrix to a file. -- **Default**: false - -### bse_continue - -- **Type**: Integer -- **Description**: Step from which to continue a previous BSE calculation: 0 starts a new calculation; 1 reads A_V; 2 reads A_V and A_W; 3 reads A_V, A_W, and B_V; 4 reads A_V, A_W, B_V, and B_W. -- **Default**: 0 - -[back to top](#full-list-of-input-keywords) - -## Reduced Density Matrix Functional Theory - -### rdmft - -- **Type**: Boolean -- **Description**: Whether to perform rdmft calculation (reduced density matrix funcional theory). The physical quantities that RDMFT temporarily expects to output are the kinetic energy, total energy, and 1-RDM of the system in the ground state, etc. -- **Default**: false - -### rdmft_power_alpha - -- **Type**: Real -- **Description**: The alpha parameter of power-functional(or other exx-type/hybrid functionals) which used in RDMFT, g(occ_number) = occ_number^alpha -- **Default**: 0.656 - -[back to top](#full-list-of-input-keywords) - -## Density functional perturbation theory - -### dfpt_qmesh - -- **Type**: Vector of Int (1 or 3 values) -- **Description**: Set the Monkhorst-Pack q mesh (gamma-centered) for DFPT phonon calculations. The q mesh must be commensurate with the ground-state k mesh: k + q must be a point of the k list (modulo a reciprocal lattice vector). For example, a 4x4x4 KPT mesh is commensurate with dfpt_qmesh values of 1, 2, or 4 along each direction. This parameter is ignored when dfpt_qfile is set. -- **Default**: 1 1 1 - -### dfpt_qfile - -- **Type**: String -- **Description**: Set the file containing the q points for DFPT, in the same format as the KPT file (Q_POINTS card: Gamma/Monkhorst-Pack mesh, or an explicit Direct/Cartesian list; symmetry reduction is not applied to file q lists). When set, it overrides dfpt_qmesh. Each q point must still be commensurate with the ground-state k mesh. -- **Default**: "" - -### dfpt_compute_q0 - -- **Type**: Boolean -- **Description**: Whether to compute the macroscopic dielectric tensor (epsilon_inf) and the Born effective charges at q = 0 within the same DFPT run. Requires a q point at Gamma (the default dfpt_qmesh 1 1 1). -- **Default**: false - -### dfpt_loto - -- **Type**: Boolean -- **Description**: Whether to apply the Lyddane-Sachs-Teller non-analytic correction to the Gamma-point dynamical matrix, which splits the longitudinal and transverse optical modes. Requires dfpt_compute_q0 to be true, since the correction is built from epsilon_inf and the Born effective charges. -- **Default**: false - -### dfpt_conv_thr - -- **Type**: Real -- **Description**: Set the convergence threshold of the self-consistent DFPT cycle: the iteration stops when the relative residual of the first-order density ||drho_out - drho_in|| / ||drho_out|| drops below this value for every displacement. -- **Default**: 1.0e-8 - -### dfpt_max_iter - -- **Type**: Integer -- **Description**: Set the maximum number of self-consistent DFPT iterations for each atomic displacement. -- **Default**: 100 - -### dfpt_mix_beta - -- **Type**: Real -- **Description**: Set the plain-mixing coefficient of the first-order density in the self-consistent DFPT cycle. The response Jacobian has strongly negative eigenvalues on the smallest-G shells (Coulomb stiffness), so beta must stay below 2 / (1 + |lambda_min|); the default 0.4 keeps margin up to |lambda_min| ~ 3. A larger value accelerates convergence for weakly screened systems but may diverge. -- **Default**: 0.4 - -[back to top](#full-list-of-input-keywords) diff --git a/docs/conf.py b/docs/conf.py index e0d92d3701a..33d0d8ea398 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -108,31 +108,6 @@ import sys from pathlib import Path -try: - from sphinx.util import logging as sphinx_logging - logger = sphinx_logging.getLogger(__name__) -except Exception: - logger = None - - -def warn_input_docs(message): - if logger is not None: - logger.warning(message) - else: - print(f"Warning: {message}") - - -def input_docs_refresh_required(env=None): - env = os.environ if env is None else env - return env.get('READTHEDOCS') == 'True' - - -def handle_input_docs_failure(message, warn, fail_on_error): - if fail_on_error: - raise RuntimeError(message) - warn(message) - - def candidate_abacus_binaries(repo_root): """Return candidate ABACUS binaries for local and Read the Docs builds.""" env_binary = os.environ.get('ABACUS_BINARY') or os.environ.get('ABACUS_EXECUTABLE') @@ -157,20 +132,17 @@ def find_abacus_binary(repo_root): return None -def refresh_input_docs(docs_dir, abacus_binary=None, warn=warn_input_docs, fail_on_error=False): - """Refresh input-main.md from an ABACUS executable, if one is available.""" +def refresh_input_docs(docs_dir, abacus_binary=None): + """Refresh input-main.md from an ABACUS executable.""" docs_dir = Path(docs_dir) repo_root = docs_dir.parent binary = Path(abacus_binary) if abacus_binary else find_abacus_binary(repo_root) if binary is None or not binary.exists() or not os.access(binary, os.X_OK): - handle_input_docs_failure( + raise RuntimeError( "ABACUS executable not found; INPUT parameter documentation may not " - "be up to date. Set ABACUS_BINARY=/path/to/abacus or build the " - "reduced documentation binary first.", - warn, - fail_on_error, + "be generated. Set ABACUS_BINARY=/path/to/abacus or build the " + "reduced documentation binary first." ) - return False env = os.environ.copy() env.setdefault('OMP_NUM_THREADS', '1') @@ -183,14 +155,11 @@ def refresh_input_docs(docs_dir, abacus_binary=None, warn=warn_input_docs, fail_ ) if result.returncode != 0: detail = result.stderr.strip() or result.stdout.strip() - handle_input_docs_failure( + raise RuntimeError( "ABACUS could not generate INPUT parameter metadata; documentation " - f"may not be up to date. Command: {binary} --generate-parameters-yaml" - + (f". Output: {detail}" if detail else ""), - warn, - fail_on_error, + f"cannot be built. Command: {binary} --generate-parameters-yaml" + + (f". Output: {detail}" if detail else "") ) - return False sys.path.insert(0, str(Path(__file__).resolve().parent)) import yaml @@ -203,10 +172,7 @@ def refresh_input_docs(docs_dir, abacus_binary=None, warn=warn_input_docs, fail_ def generate_input_docs(app): - refresh_input_docs( - Path(__file__).resolve().parent, - fail_on_error=input_docs_refresh_required(), - ) + refresh_input_docs(Path(__file__).resolve().parent) def setup(app): app.connect('builder-inited', generate_input_docs) diff --git a/docs/developers_guide/agent_governance.md b/docs/developers_guide/agent_governance.md index c403149ce3d..27f95f3f804 100644 --- a/docs/developers_guide/agent_governance.md +++ b/docs/developers_guide/agent_governance.md @@ -220,24 +220,17 @@ setup workflows and should be added only through a later governance change. ## INPUT Parameter Changes Changes to parameter metadata, default values, type, availability, description, -or parsing behavior must include: - -- `docs/advanced/input_files/input-main.md` - -The parameter YAML stream is generated transiently from the ABACUS binary and -is not stored in the repository. - -If the diff touches parameter internals but does not change user-visible INPUT -behavior, the PR should state why no documentation update is required. Missing -documentation updates trigger a governance warning (not a block), but maintainers -may still request documentation updates before merging. +or parsing behavior must update the relevant C++ `Input_Item` registration. +The parameter YAML stream and `docs/advanced/input_files/input-main.md` are +generated transiently during the documentation build and are not stored in the +repository. Documentation builds fail if either artifact cannot be generated. ## PR Self-Consistency Before requesting review, check that the PR description matches the diff: -- New or changed INPUT behavior lists the changed parameters and links the - Markdown documentation update. +- New or changed INPUT behavior lists the changed parameters and confirms the + generated INPUT reference was verified. - Source changes list focused unit, case, or CLI verification commands with the observed result. - Header include growth, `.hpp` propagation, missing tests, or other warnings diff --git a/docs/developers_guide/input_availability.md b/docs/developers_guide/input_availability.md index 5435082bf08..c2269c58f85 100644 --- a/docs/developers_guide/input_availability.md +++ b/docs/developers_guide/input_availability.md @@ -84,8 +84,9 @@ item.set_availability("esolver_type==sdft and method_sto==2"); 1. Parse and require canonical spelling in `set_availability()`. 2. Finish registering all `Input_Item` objects. 3. Validate referenced parameter names, operator compatibility, literal values, and that every referenced parameter carries its own enclosing requirements on the referencing path. -4. Serialize the AST into `docs/parameters.yaml`. -5. Generate `docs/advanced/input_files/input-main.md` from that YAML. +4. Serialize the AST as a transient YAML stream from the ABACUS executable. +5. Generate `docs/advanced/input_files/input-main.md` from that stream during + the Sphinx build; neither generated artifact is stored in the repository. Runtime evaluation is outside this metadata contract. Any implementation must define evaluation timing, treatment of defaults and reset values, and warning diff --git a/docs/tests/test_conf_input_docs.py b/docs/tests/test_conf_input_docs.py index 7cce650f856..3e310828ab3 100644 --- a/docs/tests/test_conf_input_docs.py +++ b/docs/tests/test_conf_input_docs.py @@ -22,11 +22,6 @@ class InputDocsGenerationTest(unittest.TestCase): - def test_readthedocs_environment_requires_fresh_input_docs(self): - self.assertTrue(conf.input_docs_refresh_required({"READTHEDOCS": "True"})) - self.assertFalse(conf.input_docs_refresh_required({"READTHEDOCS": "False"})) - self.assertFalse(conf.input_docs_refresh_required({})) - def test_explicit_abacus_binary_path_disables_fallback_search(self): with tempfile.TemporaryDirectory() as tmpdir: repo_root = Path(tmpdir) @@ -54,11 +49,9 @@ def test_refreshes_input_docs_from_abacus_binary_without_writing_yaml_file(self) ) fake_abacus.chmod(fake_abacus.stat().st_mode | stat.S_IXUSR) - warnings = [] refreshed = conf.refresh_input_docs( docs_dir=docs_dir, abacus_binary=fake_abacus, - warn=warnings.append, ) output = docs_dir / "advanced" / "input_files" / "input-main.md" @@ -66,43 +59,22 @@ def test_refreshes_input_docs_from_abacus_binary_without_writing_yaml_file(self) self.assertTrue(output.exists()) self.assertIn("ecutwfc", output.read_text()) self.assertFalse((docs_dir / "parameters.yaml").exists()) - self.assertEqual([], warnings) - def test_warns_when_abacus_binary_is_not_available(self): + def test_refresh_raises_when_abacus_binary_is_not_available(self): with tempfile.TemporaryDirectory() as tmpdir: docs_dir = Path(tmpdir) / "docs" docs_dir.mkdir() - warnings = [] - - refreshed = conf.refresh_input_docs( - docs_dir=docs_dir, - abacus_binary=docs_dir / "missing-abacus", - warn=warnings.append, - ) - - self.assertFalse(refreshed) - self.assertEqual([], list(docs_dir.rglob("input-main.md"))) - self.assertEqual(1, len(warnings)) - self.assertIn("may not be up to date", warnings[0]) - - def test_required_refresh_raises_when_abacus_binary_is_not_available(self): - with tempfile.TemporaryDirectory() as tmpdir: - docs_dir = Path(tmpdir) / "docs" - docs_dir.mkdir() - warnings = [] with self.assertRaises(RuntimeError) as caught: conf.refresh_input_docs( docs_dir=docs_dir, abacus_binary=docs_dir / "missing-abacus", - warn=warnings.append, - fail_on_error=True, ) - self.assertIn("may not be up to date", str(caught.exception)) - self.assertEqual([], warnings) + self.assertIn("ABACUS executable not found", str(caught.exception)) + self.assertEqual([], list(docs_dir.rglob("input-main.md"))) - def test_required_refresh_raises_when_abacus_metadata_generation_fails(self): + def test_refresh_raises_when_abacus_metadata_generation_fails(self): with tempfile.TemporaryDirectory() as tmpdir: tmp_path = Path(tmpdir) docs_dir = tmp_path / "docs" @@ -114,19 +86,14 @@ def test_required_refresh_raises_when_abacus_metadata_generation_fails(self): "exit 2\n" ) fake_abacus.chmod(fake_abacus.stat().st_mode | stat.S_IXUSR) - warnings = [] - with self.assertRaises(RuntimeError) as caught: conf.refresh_input_docs( docs_dir=docs_dir, abacus_binary=fake_abacus, - warn=warnings.append, - fail_on_error=True, ) self.assertIn("could not generate INPUT parameter metadata", str(caught.exception)) self.assertIn("metadata generation failed", str(caught.exception)) - self.assertEqual([], warnings) if __name__ == "__main__": diff --git a/tools/03_code_analysis/agent_governance_check.py b/tools/03_code_analysis/agent_governance_check.py index 4d8b45ddc0e..82bbee68256 100644 --- a/tools/03_code_analysis/agent_governance_check.py +++ b/tools/03_code_analysis/agent_governance_check.py @@ -552,69 +552,6 @@ def check_cmake_linkage(findings: List[Finding], statuses: Dict[str, str], chang ) -def input_parameter_changed(paths: Sequence[str], lines: Sequence[DiffLine]) -> bool: - parameter_paths = [ - path - for path in paths - if path.startswith("source/source_io/module_parameter/") - and Path(path).suffix.lower() in {".cpp", ".h", ".hpp"} - ] - if parameter_paths: - sensitive = re.compile( - r"\b(Input_Item|add_item|default_value|description|category|availability|read_value|reset_value|check_value|type)\b" - ) - return any( - line.path in parameter_paths - and not line.content.lstrip().startswith("//") - and sensitive.search(line.content) - for line in lines - ) - return any( - line.path.startswith("source/") - and re.search(r"\bInput_Item\s+\w+|add_item\s*\(", line.content) - for line in lines - ) - - -def pr_body_allows_no_input_doc_update(body: str) -> bool: - lowered = body.lower() - needles = [ - "input parameter documentation: not needed", - "input docs: not needed", - "no input documentation update required", - "无需更新 input", - ] - return any(needle in lowered for needle in needles) - - -def check_input_parameter_docs( - findings: List[Finding], - changed: Sequence[str], - statuses: Dict[str, str], - lines: Sequence[DiffLine], - pr_body: str, -) -> None: - if not input_parameter_changed(changed, lines): - return - has_markdown = ( - "docs/advanced/input_files/input-main.md" in changed - and not statuses.get("docs/advanced/input_files/input-main.md", "").startswith("D") - ) - if has_markdown: - return - if pr_body and pr_body_allows_no_input_doc_update(pr_body): - return - add_finding( - findings, - "INPUT parameter documentation linkage", - WARN, - "source/source_io/module_parameter", - None, - "INPUT parameter behavior appears to change without an input-main.md update.", - "Regenerate docs/advanced/input_files/input-main.md from the ABACUS parameter metadata, or state why no INPUT documentation update is required in the PR.", - ) - - def read_pr_body(event_path: Optional[str]) -> Optional[str]: if not event_path: return None @@ -802,7 +739,6 @@ def collect_findings(root: Path, args: argparse.Namespace) -> List[Finding]: check_hpp_warnings(findings, statuses, lines) check_header_include_warnings(findings, lines) check_cmake_linkage(findings, statuses, changed) - check_input_parameter_docs(findings, changed, statuses, lines, body_text) check_pr_metadata(findings, body) check_test_evidence_warning(findings, changed, body_text) check_heterogeneous_test_warning(findings, changed, body_text) diff --git a/tools/03_code_analysis/test_agent_governance_check.py b/tools/03_code_analysis/test_agent_governance_check.py index adc9a01b825..480d77d4e10 100644 --- a/tools/03_code_analysis/test_agent_governance_check.py +++ b/tools/03_code_analysis/test_agent_governance_check.py @@ -216,7 +216,7 @@ def test_blocks_new_source_file_without_cmake_linkage(self): self.assert_blocked_by(result, "CMake linkage for new sources") - def test_warns_input_parameter_changes_without_docs_linkage(self): + def test_allows_input_parameter_changes_without_generated_docs(self): self.write( "source/source_io/module_parameter/read_input_item_model.cpp", 'Input_Item item("new_switch");\nitem.default_value = "0";\n', @@ -225,7 +225,8 @@ def test_warns_input_parameter_changes_without_docs_linkage(self): result = self.run_checker("--base", self.base, "--head", head) - self.assert_warns_with_success(result, "INPUT parameter documentation linkage") + self.assertEqual(result.returncode, 0, result.stdout + result.stderr) + self.assertNotIn("INPUT parameter documentation linkage", result.stdout) def test_allows_parameter_file_comment_only_change_without_docs(self): self.write( @@ -246,51 +247,6 @@ def test_allows_input_item_test_fixture_without_docs(self): self.assertEqual(result.returncode, 0, result.stdout + result.stderr) - def test_allows_input_parameter_changes_with_required_docs(self): - self.write( - "source/source_io/module_parameter/read_input_item_model.cpp", - 'Input_Item item("new_switch");\nitem.default_value = "0";\n', - ) - self.write("docs/advanced/input_files/input-main.md", "# INPUT\n") - head = self.commit_change() - - result = self.run_checker("--base", self.base, "--head", head) - - self.assertEqual(result.returncode, 0, result.stdout + result.stderr) - - def test_allows_input_parameter_changes_with_markdown_and_deleted_yaml(self): - self.write("docs/parameters.yaml", "parameters: []\n") - self.git("add", ".") - self.git("commit", "-m", "add legacy parameter yaml") - base = self.git("rev-parse", "HEAD").stdout.strip() - self.write( - "source/source_io/module_parameter/read_input_item_model.cpp", - 'Input_Item item("new_switch");\nitem.default_value = "0";\n', - ) - self.write("docs/advanced/input_files/input-main.md", "# INPUT\n") - (self.repo / "docs" / "parameters.yaml").unlink() - head = self.commit_change() - - result = self.run_checker("--base", base, "--head", head) - - self.assertEqual(result.returncode, 0, result.stdout + result.stderr) - - def test_blocks_input_parameter_change_when_required_docs_are_deleted(self): - self.write("docs/advanced/input_files/input-main.md", "# INPUT\n") - self.git("add", ".") - self.git("commit", "-m", "add input docs") - base = self.git("rev-parse", "HEAD").stdout.strip() - self.write( - "source/source_io/module_parameter/read_input_item_model.cpp", - 'Input_Item item("new_switch");\nitem.default_value = "0";\n', - ) - (self.repo / "docs" / "advanced" / "input_files" / "input-main.md").unlink() - head = self.commit_change() - - result = self.run_checker("--base", base, "--head", head) - - self.assert_warns_with_success(result, "INPUT parameter documentation linkage") - def test_warns_for_unfilled_pr_template_fields_from_event_payload(self): event = self.repo / "event.json" event.write_text(