From 34bfa7f886ac087553e94407f17428234ddd26d2 Mon Sep 17 00:00:00 2001 From: Bonan Zhu Date: Wed, 25 Feb 2026 11:39:55 +0800 Subject: [PATCH 1/4] Fix formatting issue for input-main and update type info - Update the type field of parameter item field where multiple values are expected. - Fixed formatting issue in input-main.md where > and < are not escaped correctly. --- docs/advanced/input_files/input-main.md | 120 ++++++++++++++---- docs/generate_input_main.py | 8 ++ .../read_input_item_elec_stru.cpp | 2 +- .../read_input_item_exx_dftu.cpp | 4 +- .../read_input_item_other.cpp | 6 +- .../read_input_item_system.cpp | 2 +- .../read_input_item_tddft.cpp | 2 +- 7 files changed, 110 insertions(+), 34 deletions(-) diff --git a/docs/advanced/input_files/input-main.md b/docs/advanced/input_files/input-main.md index e91215c1ff..9ac09ef507 100644 --- a/docs/advanced/input_files/input-main.md +++ b/docs/advanced/input_files/input-main.md @@ -708,7 +708,7 @@ - **Type**: Integer - **Availability**: *Used only for plane wave basis set.* - **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. + - >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 @@ -720,7 +720,7 @@ ### kspacing - **Type**: Real -- **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. +- **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 @@ -792,6 +792,8 @@ - **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 @@ -838,6 +840,8 @@ - **Description**: The directory to save the spillage files. - **Default**: "./" +[back to top](#full-list-of-input-keywords) + ## Plane wave related variables ### ecutwfc @@ -953,7 +957,7 @@ ### 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. +- **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 @@ -987,6 +991,8 @@ - **Description**: Preconditioner type for conjugate gradient diagonalization method. - **Default**: 1 +[back to top](#full-list-of-input-keywords) + ## Numerical atomic orbitals related variables ### lmaxmax @@ -1061,6 +1067,8 @@ - **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 @@ -1108,7 +1116,7 @@ - **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. + - >0.0: this denotes the total number of electrons in the system. Must be less than 2*nbands. - **Default**: 0.0 ### nelec_delta @@ -1121,7 +1129,7 @@ - **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. + - >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 @@ -1233,7 +1241,7 @@ - 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. + - 0.1 or less: if convergence of SCF calculation is difficult to reach, please try 0 < mixing_beta < 0.1. Note: For low-dimensional large systems, the setup of mixing_beta=0.1, mixing_ndim=20, and mixing_gg0=1.0 usually works well. - **Default**: 0.8 for nspin=1, 0.4 for nspin=2 and nspin=4. @@ -1262,14 +1270,14 @@ - **Type**: Boolean - **Availability**: *Only for mixing_restart>=0.0* -- **Description**: At n-th iteration which is calculated by drho0: 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: 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. @@ -1292,8 +1300,8 @@ - **Type**: Real - **Availability**: *Only relevant for non-colinear calculations 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 + - <=0: Normal broyden mixing + - >0: Angle mixing for the modulus with mixing_angle=1.0 - **Default**: -10.0 ### mixing_tau @@ -1432,6 +1440,8 @@ - 1: Shell DFT-1/2 method is used. - **Default**: 0 +[back to top](#full-list-of-input-keywords) + ## Electronic structure (SDFT) ### method_sto @@ -1449,7 +1459,7 @@ - **Type**: Integer or string - **Availability**: *esolver_type = sdft* - **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 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**: 256 @@ -1482,9 +1492,9 @@ - **Type**: Integer - **Availability**: *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: 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: Stochastic orbitals have the form of +1 or -1 with equal probability. - -1: the seed is decided by time(NULL). - **Default**: 0 @@ -1512,6 +1522,8 @@ - **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 @@ -1711,6 +1723,8 @@ - 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 @@ -2114,6 +2128,8 @@ - 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 @@ -2176,6 +2192,8 @@ - **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 @@ -2208,6 +2226,8 @@ - **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 @@ -2217,7 +2237,7 @@ - **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. + - 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 @@ -2330,7 +2350,7 @@ - **Type**: Integer - **Availability**: *Numerical atomic orbital basis* -- **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. +- **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. @@ -2345,6 +2365,8 @@ > 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 @@ -2500,6 +2522,8 @@ 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 @@ -2719,6 +2743,8 @@ - **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 @@ -2737,6 +2763,8 @@ - **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 @@ -2772,14 +2800,14 @@ - **Type**: Real - **Availability**: *with 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. +- **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**: *with efield_flag = True.* -- **Description**: Zone in the unit cell where the saw-like potential decreases, 0 < efield_pos_dec < 1. +- **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 @@ -2792,6 +2820,8 @@ - **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 @@ -2838,6 +2868,8 @@ - **Default**: 0.1 - **Unit**: Rydberg +[back to top](#full-list-of-input-keywords) + ## Exact Exchange (Common) ### exx_fock_alpha @@ -2880,6 +2912,8 @@ - **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 @@ -2889,6 +2923,8 @@ - **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 @@ -2906,7 +2942,7 @@ ### 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. +- **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 @@ -3006,6 +3042,8 @@ - **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 +[back to top](#full-list-of-input-keywords) + ## Exact Exchange (PW) ### exxace @@ -3046,6 +3084,8 @@ - **Default**: 1e-5 - **Unit**: Ry +[back to top](#full-list-of-input-keywords) + ## Molecular dynamics ### md_type @@ -3162,8 +3202,8 @@ - **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. + - < 0: No srand() function is called. + - >= 0: The function srand(md_seed) is called. - **Default**: -1 ### md_tfreq @@ -3353,9 +3393,9 @@ ### cal_syns - **Type**: Boolean -- **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. +- **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. - > Note: Only works with LCAO basis and molecular dynamics calculations. Requires atomic velocities. Output starts from the second MD step (istep > 0). + > 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 @@ -3365,6 +3405,8 @@ - **Default**: 0.01 - **Unit**: bohr +[back to top](#full-list-of-input-keywords) + ## DFT+U correction ### dft_plus_u @@ -3420,7 +3462,7 @@ - **Type**: Real - **Availability**: *DFT+U calculations with 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= 0: Print only elements with either i or j exceeding td_print_eij. + - < 0: Suppress all output. + - >= 0: Print only elements with either i or j exceeding td_print_eij. - **Default**: -1 - **Unit**: Ry @@ -4028,6 +4078,8 @@ - False: Do not output vector potential. - **Default**: False +[back to top](#full-list-of-input-keywords) + ## Variables useful for debugging ### nurse @@ -4100,6 +4152,8 @@ - 1: Yes. - **Default**: 0 +[back to top](#full-list-of-input-keywords) + ## Electronic conductivities ### cal_cond @@ -4173,6 +4227,8 @@ - False: . - **Default**: True +[back to top](#full-list-of-input-keywords) + ## Implicit solvation model ### imp_sol @@ -4206,6 +4262,8 @@ - **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 @@ -4242,6 +4300,8 @@ - **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 @@ -4382,6 +4442,8 @@ - **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 ### ri_hartree_benchmark @@ -4397,6 +4459,8 @@ - **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) + ## Linear Response TDDFT (Under Development Feature) ### xc_kernel @@ -4433,7 +4497,7 @@ - **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. + - Note: If the value is illegal ( > nelec/2 or <= 0), it will be autoset to nelec/2. - **Default**: nband ### nvirt @@ -4481,6 +4545,8 @@ - **Description**: The broadening factor for the absorption spectrum calculation. - **Default**: 0.01 +[back to top](#full-list-of-input-keywords) + ## Reduced Density Matrix Functional Theory ### rdmft @@ -4494,3 +4560,5 @@ - **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) diff --git a/docs/generate_input_main.py b/docs/generate_input_main.py index 36bcd02c9d..073c3dba77 100644 --- a/docs/generate_input_main.py +++ b/docs/generate_input_main.py @@ -79,6 +79,10 @@ def format_description(desc: str) -> str: if not desc: return '' + # Prevent placeholder tokens like from being parsed as raw HTML + # and breaking list/heading structure in rendered docs. + desc = desc.replace('<', '<').replace('>', '>') + lines = desc.split('\n') result_lines = [] @@ -156,6 +160,10 @@ def generate_category_markdown(category: str, params: List[Dict[str, str]]) -> s for param in params: lines.append(generate_parameter_markdown(param)) + # Keep legacy navigation aid used by downstream tooling/rendering. + lines.append("[back to top](#full-list-of-input-keywords)") + lines.append("") + return '\n'.join(lines) diff --git a/source/source_io/module_parameter/read_input_item_elec_stru.cpp b/source/source_io/module_parameter/read_input_item_elec_stru.cpp index b5a84574d6..45d033f79a 100644 --- a/source/source_io/module_parameter/read_input_item_elec_stru.cpp +++ b/source/source_io/module_parameter/read_input_item_elec_stru.cpp @@ -1350,7 +1350,7 @@ Use case: When experimental or high-level theoretical results suggest that the S Input_Item item("bessel_nao_rcut"); item.annotation = "radial cutoff for spherical bessel functions(a.u.)"; item.category = "NAOs"; - item.type = "Real"; + item.type = "Vector of Real (N values)"; item.description = "Cutoff radius (in Bohr) and the common node of spherical Bessel functions used to construct the NAOs."; item.default_value = "6.0"; item.unit = ""; 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 684546c78d..201bbca490 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 @@ -638,7 +638,7 @@ void ReadInput::item_dftu() item.annotation = "which correlated orbitals need corrected ; d:2 " ",f:3, do not need correction:-1"; item.category = "DFT+U correction"; - item.type = "Integer"; + item.type = "Vector of Integer (ntype values)"; item.description = R"(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. @@ -681,7 +681,7 @@ void ReadInput::item_dftu() Input_Item item("hubbard_u"); item.annotation = "Hubbard Coulomb interaction parameter U(ev)"; item.category = "DFT+U correction"; - item.type = "Real"; + item.type = "Vector of Real (ntype values)"; item.description = R"(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.)"; diff --git a/source/source_io/module_parameter/read_input_item_other.cpp b/source/source_io/module_parameter/read_input_item_other.cpp index a9535b5873..5e0bc3db16 100644 --- a/source/source_io/module_parameter/read_input_item_other.cpp +++ b/source/source_io/module_parameter/read_input_item_other.cpp @@ -236,7 +236,7 @@ void ReadInput::item_others() Input_Item item("qo_strategy"); item.annotation = "strategy to generate generate radial orbitals"; item.category = "Quasiatomic Orbital (QO) analysis"; - item.type = "String"; + item.type = "Vector of String (1 or n values where n is the number of atomic types)"; item.description = "Strategy to generate radial orbitals for QO analysis. For hydrogen: energy-valence, for pswfc and szv: all"; item.default_value = "for hydrogen: energy-valence, for pswfc and szv: all"; item.unit = ""; @@ -284,7 +284,7 @@ void ReadInput::item_others() Input_Item item("qo_screening_coeff"); item.annotation = "rescale the shape of radial orbitals"; item.category = "Quasiatomic Orbital (QO) analysis"; - item.type = "Real"; + item.type = "Vector of Real (ntype values; 1 value allowed for qo_basis=pswfc)"; item.description = "The screening coefficient for each atom type to rescale the shape of radial orbitals"; item.default_value = "0.1"; item.unit = "Bohr^-1"; @@ -953,4 +953,4 @@ void ReadInput::item_others() this->add_item(item); } } -} // namespace ModuleIO \ No newline at end of file +} // namespace ModuleIO diff --git a/source/source_io/module_parameter/read_input_item_system.cpp b/source/source_io/module_parameter/read_input_item_system.cpp index cdb71ae1cf..2bb18f9898 100644 --- a/source/source_io/module_parameter/read_input_item_system.cpp +++ b/source/source_io/module_parameter/read_input_item_system.cpp @@ -564,7 +564,7 @@ Available options are: item.annotation = "unit in 1/bohr, should be > 0, default is 0 which " "means read KPT file"; item.category = "System variables"; - item.type = "Real"; + item.type = "Vector of Real (1 or 3 values)"; item.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." diff --git a/source/source_io/module_parameter/read_input_item_tddft.cpp b/source/source_io/module_parameter/read_input_item_tddft.cpp index b6fb1287d6..18e8ad3c00 100644 --- a/source/source_io/module_parameter/read_input_item_tddft.cpp +++ b/source/source_io/module_parameter/read_input_item_tddft.cpp @@ -593,7 +593,7 @@ void ReadInput::item_lr_tddft() Input_Item item("lr_init_xc_kernel"); item.annotation = "The method to initalize the xc kernel"; item.category = "Linear Response TDDFT (Under Development Feature)"; - item.type = "String"; + item.type = "Vector of String (>=1 values)"; item.description = R"(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 344c00710288291472d41dd31d0e7c12bb635118 Mon Sep 17 00:00:00 2001 From: Bonan Zhu Date: Wed, 25 Feb 2026 12:47:41 +0800 Subject: [PATCH 2/4] Fix more formating issues Fixed some LaTeX issue and unify the description of types. --- docs/advanced/input_files/input-main.md | 46 +++++++++---------- docs/generate_input_main.py | 21 ++++++++- docs/parameters.yaml | 36 +++++++-------- .../read_input_item_deepks.cpp | 2 +- .../read_input_item_elec_stru.cpp | 4 +- .../read_input_item_exx_dftu.cpp | 20 ++++---- .../read_input_item_postprocess.cpp | 10 ++-- 7 files changed, 79 insertions(+), 60 deletions(-) diff --git a/docs/advanced/input_files/input-main.md b/docs/advanced/input_files/input-main.md index 9ac09ef507..b610f1d70b 100644 --- a/docs/advanced/input_files/input-main.md +++ b/docs/advanced/input_files/input-main.md @@ -596,7 +596,7 @@ - **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. + > 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 @@ -1160,7 +1160,7 @@ ### xc_exch_ext -- **Type**: Integer Real ... +- **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. @@ -1168,7 +1168,7 @@ ### xc_corr_ext -- **Type**: Integer Real ... +- **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. @@ -1713,7 +1713,7 @@ - **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. + > 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 @@ -2339,7 +2339,7 @@ ### deepks_band_range -- **Type**: Int*2 +- **Type**: Integer*2 - **Availability**: *Numerical atomic orbital basis, deepks_scf is true, and deepks_bandgap is 1 or 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. @@ -2783,7 +2783,7 @@ - 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. + > 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 @@ -2816,7 +2816,7 @@ - **Availability**: *with 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: Note: The change of slope of this potential must be located in the empty region, or else unphysical forces will result. + > 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. @@ -2874,20 +2874,20 @@ ### exx_fock_alpha -- **Type**: Real \Real...\ -- **Description**: Fraction of full-ranged Fock exchange 1/r () in range-separated hybrid funtionals, so that . +- **Type**: Vector of Real +- **Description**: Fraction $\alpha$ of full-ranged Fock exchange $1/r$ in range-separated hybrid functionals. - **Default**: see hybrid_func_params ### exx_erfc_alpha -- **Type**: Real \Real...\ -- **Description**: Fraction of short-ranged Fock exchange erfc(wr)/r () in range-separated hybrid funtionals, so that . +- **Type**: Vector of Real +- **Description**: Fraction $\beta$ 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 \Real...\ -- **Description**: Range-separation parameter in exchange, such that +- **Type**: Vector of 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 @@ -2918,7 +2918,7 @@ ### exx_fock_lambda -- **Type**: Real \Real...\ +- **Type**: Vector of Real - **Availability**: *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 @@ -3440,7 +3440,7 @@ - **Type**: Real - **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. + > 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 @@ -3474,15 +3474,15 @@ - 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: 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. + > 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**: 0 ### onsite_radius - **Type**: Real - **Availability**: *dft_plus_u is set to 1* -- **Description**: - The Onsite-radius parameter facilitates modulation of the single-zeta portion of numerical atomic orbitals for projections for DFT+U. - - The modulation algorithm includes a smooth truncation applied directly to the tail of the original orbital, followed by normalization. Consider the function: $\sigmar_c\sigmaf'(r)\equiv \mathrm{d}f(r)/\mathrm{d}r\gamma$ is a parameter that adjusts the relative weight of the error function to the derivative error function. +- **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 @@ -3757,7 +3757,7 @@ ### out_wannier_mmn -- **Type**: Bool +- **Type**: Boolean - **Description**: Write the "*.mmn" file or not. - 0: don't write the "*.mmn" file. - 1: write the "*.mmn" file. @@ -3765,7 +3765,7 @@ ### out_wannier_amn -- **Type**: Bool +- **Type**: Boolean - **Description**: Write the "*.amn" file or not. - 0: don't write the "*.amn" file. - 1: write the "*.amn" file. @@ -3773,7 +3773,7 @@ ### out_wannier_eig -- **Type**: Bool +- **Type**: Boolean - **Description**: Write the "*.eig" file or not. - 0: don't write the "*.eig" file. - 1: write the "*.eig" file. @@ -3781,7 +3781,7 @@ ### out_wannier_unk -- **Type**: Bool +- **Type**: Boolean - **Description**: Write the "UNK.*" file or not. - 0: don't write the "UNK.*" file. - 1: write the "UNK.*" file. @@ -3789,7 +3789,7 @@ ### out_wannier_wvfn_formatted -- **Type**: Bool +- **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). diff --git a/docs/generate_input_main.py b/docs/generate_input_main.py index 073c3dba77..30d3ea80e4 100644 --- a/docs/generate_input_main.py +++ b/docs/generate_input_main.py @@ -69,6 +69,21 @@ ] +def normalize_type(type_text: str) -> str: + """ + Normalize legacy type labels for cleaner generated docs. + """ + if not type_text: + return '' + + normalized = type_text.strip() + aliases = { + "Bool": "Boolean", + "Int*2": "Integer*2", + } + return aliases.get(normalized, normalized) + + def format_description(desc: str) -> str: """ Format description text for markdown output. @@ -98,6 +113,10 @@ def format_description(desc: str) -> str: if '[WARNING]' in line: line = line.replace('[WARNING]', '> Warning:') + # Normalize doubled note/warning prefixes from legacy content + line = re.sub(r'>\s*Note:\s*Note\s*:?\s*', '> Note: ', line) + line = re.sub(r'>\s*Warning:\s*Warning\s*:?\s*', '> Warning: ', line) + result_lines.append(line) # Join and clean up @@ -119,7 +138,7 @@ def generate_parameter_markdown(param: Dict[str, str]) -> str: # Type if param.get('type', '') != '': - lines.append(f"- **Type**: {param['type']}") + lines.append(f"- **Type**: {normalize_type(str(param['type']))}") # Availability (before description, as in original format) if param.get('availability', '') != '': diff --git a/docs/parameters.yaml b/docs/parameters.yaml index 8cb30ffb40..9fd94f9b7c 100644 --- a/docs/parameters.yaml +++ b/docs/parameters.yaml @@ -577,7 +577,7 @@ parameters: availability: "" - name: xc_exch_ext category: Electronic structure - type: Integer Real ... + 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. @@ -587,7 +587,7 @@ parameters: availability: "" - name: xc_corr_ext category: Electronic structure - type: Integer Real ... + 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. @@ -2316,7 +2316,7 @@ parameters: availability: Numerical atomic orbital basis and deepks_scf is true - name: deepks_band_range category: DeePKS - type: "Int*2" + 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. @@ -3477,7 +3477,7 @@ parameters: availability: "" - name: out_wannier_mmn category: Berry phase and wannier90 interface - type: Bool + type: Boolean description: | Write the "*.mmn" file or not. * 0: don't write the "*.mmn" file. @@ -3487,7 +3487,7 @@ parameters: availability: "" - name: out_wannier_amn category: Berry phase and wannier90 interface - type: Bool + type: Boolean description: | Write the "*.amn" file or not. * 0: don't write the "*.amn" file. @@ -3497,7 +3497,7 @@ parameters: availability: "" - name: out_wannier_eig category: Berry phase and wannier90 interface - type: Bool + type: Boolean description: | Write the "*.eig" file or not. * 0: don't write the "*.eig" file. @@ -3507,7 +3507,7 @@ parameters: availability: "" - name: out_wannier_unk category: Berry phase and wannier90 interface - type: Bool + type: Boolean description: | Write the "UNK.*" file or not. * 0: don't write the "UNK.*" file. @@ -3517,7 +3517,7 @@ parameters: availability: "" - name: out_wannier_wvfn_formatted category: Berry phase and wannier90 interface - type: Bool + type: Boolean description: | Write the "UNK.*" file in ASCII format or binary format. * 0: write the "UNK.*" file in binary format. @@ -3840,25 +3840,25 @@ parameters: availability: "" - name: exx_fock_alpha category: Exact Exchange (Common) - type: "Real \\Real...\\" + type: Vector of Real description: | - Fraction of full-ranged Fock exchange 1/r () in range-separated hybrid funtionals, so that . + Fraction $\alpha$ 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 \\Real...\\" + type: Vector of Real description: | - Fraction of short-ranged Fock exchange erfc(wr)/r () in range-separated hybrid funtionals, so that . + Fraction $\beta$ 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 \\Real...\\" + type: Vector of Real description: | - Range-separation parameter in exchange, such that + Range-separation parameter $\omega$ in the short-ranged Fock term $\mathrm{erfc}(\omega r)/r$. default_value: see hybrid_func_params unit: "" availability: "" @@ -3890,7 +3890,7 @@ parameters: availability: exx_separate_loop==1 - name: exx_fock_lambda category: Exact Exchange (LCAO in PW) - type: "Real \\Real...\\" + type: Vector of 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" @@ -4119,7 +4119,7 @@ parameters: * 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] 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. + [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: "" @@ -4127,8 +4127,8 @@ parameters: category: DFT+U correction type: Real description: | - * The Onsite-radius parameter facilitates modulation of the single-zeta portion of numerical atomic orbitals for projections for DFT+U. - * The modulation algorithm includes a smooth truncation applied directly to the tail of the original orbital, followed by normalization. Consider the function: $\sigmar_c\sigmaf'(r)\equiv \mathrm{d}f(r)/\mathrm{d}r\gamma$ is a parameter that adjusts the relative weight of the error function to the derivative error function. + * 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 diff --git a/source/source_io/module_parameter/read_input_item_deepks.cpp b/source/source_io/module_parameter/read_input_item_deepks.cpp index e27e011cfd..7f69b58dd5 100644 --- a/source/source_io/module_parameter/read_input_item_deepks.cpp +++ b/source/source_io/module_parameter/read_input_item_deepks.cpp @@ -247,7 +247,7 @@ void ReadInput::item_deepks() Input_Item item("deepks_band_range"); item.annotation = "(int, int) range of bands for bandgap label"; item.category = "DeePKS"; - item.type = "Int*2"; + item.type = "Integer*2"; item.description = R"(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.)"; diff --git a/source/source_io/module_parameter/read_input_item_elec_stru.cpp b/source/source_io/module_parameter/read_input_item_elec_stru.cpp index 45d033f79a..16822aca8b 100644 --- a/source/source_io/module_parameter/read_input_item_elec_stru.cpp +++ b/source/source_io/module_parameter/read_input_item_elec_stru.cpp @@ -350,7 +350,7 @@ The other way is only available when compiling with LIBXC, and it allows for sup Input_Item item("xc_exch_ext"); item.annotation = "placeholder for xcpnet exchange functional"; item.category = "Electronic structure"; - item.type = "Integer Real ..."; + item.type = "Integer followed by Real values"; item.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." "\n\n[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. " @@ -393,7 +393,7 @@ The other way is only available when compiling with LIBXC, and it allows for sup Input_Item item("xc_corr_ext"); item.annotation = "placeholder for xcpnet exchange functional"; item.category = "Electronic structure"; - item.type = "Integer Real ..."; + item.type = "Integer followed by Real values"; item.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." "\n\n[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. " 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 201bbca490..60a96c6d3c 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 @@ -14,8 +14,8 @@ void ReadInput::item_exx() Input_Item item("exx_fock_alpha"); item.annotation = "fraction of Fock exchange 1/r in hybrid functionals"; item.category = "Exact Exchange (Common)"; - item.type = "Real \\Real...\\"; - item.description = "Fraction of full-ranged Fock exchange 1/r () in range-separated hybrid funtionals, so that ."; + item.type = "Real"; + item.description = R"(Fraction of full-ranged Fock exchange $1/r$ in range-separated hybrid functionals.)"; item.default_value = "see hybrid_func_params"; item.unit = ""; item.availability = ""; @@ -63,8 +63,8 @@ void ReadInput::item_exx() Input_Item item("exx_erfc_alpha"); item.annotation = "fraction of exchange erfc(wr)/r in hybrid functionals"; item.category = "Exact Exchange (Common)"; - item.type = "Real \\Real...\\"; - item.description = "Fraction of short-ranged Fock exchange erfc(wr)/r () in range-separated hybrid funtionals, so that ."; + item.type = "Real"; + item.description = R"(Fraction $\beta$ of short-ranged Fock exchange $\mathrm{erfc}(\omega r)/r$ in range-separated hybrid functionals.)"; item.default_value = "see hybrid_func_params"; item.unit = ""; item.availability = ""; @@ -113,8 +113,8 @@ void ReadInput::item_exx() Input_Item item("exx_erfc_omega"); item.annotation = "range-separation parameter erfc(wr)/r in hybrid functionals"; item.category = "Exact Exchange (Common)"; - item.type = "Real \\Real...\\"; - item.description = "Range-separation parameter in exchange, such that"; + item.type = "Real"; + item.description = R"(Range-separation parameter $\omega$ in the short-ranged Fock term $\mathrm{erfc}(\omega r)/r$.)"; item.default_value = "see hybrid_func_params"; item.unit = ""; item.availability = ""; @@ -222,7 +222,7 @@ void ReadInput::item_exx() "the evaluation of Fock exchange using " "lcao_in_pw method"; item.category = "Exact Exchange (LCAO in PW)"; - item.type = "Real \\Real...\\"; + item.type = "Real"; item.description = "It is used to compensate for divergence points at G=0 in the evaluation of Fock exchange using lcao_in_pw method."; item.default_value = "0.3"; item.unit = ""; @@ -791,7 +791,7 @@ void ReadInput::item_dftu() * 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] 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.)"; +[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.)"; item.default_value = "0"; item.unit = ""; item.availability = ""; @@ -803,8 +803,8 @@ void ReadInput::item_dftu() item.annotation = "radius of the sphere for onsite projection (Bohr)"; item.category = "DFT+U correction"; item.type = "Real"; - item.description = R"(* The Onsite-radius parameter facilitates modulation of the single-zeta portion of numerical atomic orbitals for projections for DFT+U. -* The modulation algorithm includes a smooth truncation applied directly to the tail of the original orbital, followed by normalization. Consider the function: $\sigmar_c\sigmaf'(r)\equiv \mathrm{d}f(r)/\mathrm{d}r\gamma$ is a parameter that adjusts the relative weight of the error function to the derivative error function.)"; + item.description = R"(* 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.)"; item.default_value = "3.0"; item.unit = "Bohr"; item.availability = "dft_plus_u is set to 1"; diff --git a/source/source_io/module_parameter/read_input_item_postprocess.cpp b/source/source_io/module_parameter/read_input_item_postprocess.cpp index 2a47061826..b9a6e8f6ba 100644 --- a/source/source_io/module_parameter/read_input_item_postprocess.cpp +++ b/source/source_io/module_parameter/read_input_item_postprocess.cpp @@ -426,7 +426,7 @@ void ReadInput::item_postprocess() Input_Item item("out_wannier_mmn"); item.annotation = "output .mmn file or not"; item.category = "Berry phase and wannier90 interface"; - item.type = "Bool"; + item.type = "Boolean"; item.description = R"(Write the "*.mmn" file or not. * 0: don't write the "*.mmn" file. * 1: write the "*.mmn" file.)"; @@ -440,7 +440,7 @@ void ReadInput::item_postprocess() Input_Item item("out_wannier_amn"); item.annotation = "output .amn file or not"; item.category = "Berry phase and wannier90 interface"; - item.type = "Bool"; + item.type = "Boolean"; item.description = R"(Write the "*.amn" file or not. * 0: don't write the "*.amn" file. * 1: write the "*.amn" file.)"; @@ -454,7 +454,7 @@ void ReadInput::item_postprocess() Input_Item item("out_wannier_eig"); item.annotation = "output .eig file or not"; item.category = "Berry phase and wannier90 interface"; - item.type = "Bool"; + item.type = "Boolean"; item.description = R"(Write the "*.eig" file or not. * 0: don't write the "*.eig" file. * 1: write the "*.eig" file.)"; @@ -468,7 +468,7 @@ void ReadInput::item_postprocess() Input_Item item("out_wannier_unk"); item.annotation = "output UNK. file or not"; item.category = "Berry phase and wannier90 interface"; - item.type = "Bool"; + item.type = "Boolean"; item.description = R"(Write the "UNK.*" file or not. * 0: don't write the "UNK.*" file. * 1: write the "UNK.*" file.)"; @@ -482,7 +482,7 @@ void ReadInput::item_postprocess() Input_Item item("out_wannier_wvfn_formatted"); item.annotation = "output UNK. file in text format or in binary format"; item.category = "Berry phase and wannier90 interface"; - item.type = "Bool"; + item.type = "Boolean"; item.description = R"(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).)"; From 7659769a9cc33dbab954409c6a6200dbee125bfa Mon Sep 17 00:00:00 2001 From: Bonan Zhu Date: Wed, 25 Feb 2026 22:00:10 +0800 Subject: [PATCH 3/4] Add automatic escaping for < and > Escaping is performed when the md file is generated. --- docs/advanced/input_files/input-main.md | 30 +++++----- docs/generate_input_main.py | 25 +++++++-- docs/parameters.yaml | 56 +++++++++---------- .../read_input_item_elec_stru.cpp | 2 +- .../read_input_item_exx_dftu.cpp | 2 +- .../module_parameter/read_input_item_sdft.cpp | 2 +- 6 files changed, 66 insertions(+), 51 deletions(-) diff --git a/docs/advanced/input_files/input-main.md b/docs/advanced/input_files/input-main.md index b610f1d70b..0678dab310 100644 --- a/docs/advanced/input_files/input-main.md +++ b/docs/advanced/input_files/input-main.md @@ -719,7 +719,7 @@ ### kspacing -- **Type**: Real +- **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. @@ -1269,7 +1269,7 @@ ### mixing_dmr - **Type**: Boolean -- **Availability**: *Only for mixing_restart>=0.0* +- **Availability**: *Only for mixing_restart >= 0.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 @@ -2210,7 +2210,7 @@ ### bessel_nao_rcut -- **Type**: Real +- **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 @@ -2874,19 +2874,19 @@ ### exx_fock_alpha -- **Type**: Vector of Real -- **Description**: Fraction $\alpha$ of full-ranged Fock exchange $1/r$ in range-separated hybrid functionals. +- **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**: Vector of Real -- **Description**: Fraction $\beta$ of short-ranged Fock exchange $\mathrm{erfc}(\omega r)/r$ in range-separated hybrid functionals. +- **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**: Vector of Real +- **Type**: Real - **Description**: Range-separation parameter $\omega$ in the short-ranged Fock term $\mathrm{erfc}(\omega r)/r$. - **Default**: see hybrid_func_params @@ -2918,7 +2918,7 @@ ### exx_fock_lambda -- **Type**: Vector of Real +- **Type**: Real - **Availability**: *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 @@ -3427,7 +3427,7 @@ ### orbital_corr -- **Type**: Integer +- **Type**: Vector of Integer (ntype values) - **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. @@ -3437,7 +3437,7 @@ ### hubbard_u -- **Type**: Real +- **Type**: Vector of Real (ntype values) - **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. @@ -3461,7 +3461,7 @@ ### uramping - **Type**: Real -- **Availability**: *DFT+U calculations with mixing_restart > 0.* +- **Availability**: *DFT+U calculations with 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 @@ -4283,13 +4283,13 @@ ### qo_strategy -- **Type**: String +- **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**: Real +- **Type**: Vector of Real (ntype values; 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 @@ -4471,7 +4471,7 @@ ### lr_init_xc_kernel -- **Type**: String +- **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. diff --git a/docs/generate_input_main.py b/docs/generate_input_main.py index 30d3ea80e4..16a9e398bb 100644 --- a/docs/generate_input_main.py +++ b/docs/generate_input_main.py @@ -15,6 +15,7 @@ """ import argparse +import html import re import sys from pathlib import Path @@ -84,6 +85,16 @@ def normalize_type(type_text: str) -> str: return aliases.get(normalized, normalized) +def escape_md_text(text: str) -> str: + """ + Escape markdown-sensitive angle brackets while avoiding double escaping. + """ + if text is None: + return '' + normalized = html.unescape(str(text)) + return normalized.replace('<', '<').replace('>', '>') + + def format_description(desc: str) -> str: """ Format description text for markdown output. @@ -96,7 +107,7 @@ def format_description(desc: str) -> str: # Prevent placeholder tokens like from being parsed as raw HTML # and breaking list/heading structure in rendered docs. - desc = desc.replace('<', '<').replace('>', '>') + desc = escape_md_text(desc) lines = desc.split('\n') result_lines = [] @@ -138,11 +149,13 @@ def generate_parameter_markdown(param: Dict[str, str]) -> str: # Type if param.get('type', '') != '': - lines.append(f"- **Type**: {normalize_type(str(param['type']))}") + type_text = escape_md_text(normalize_type(str(param['type']))) + lines.append(f"- **Type**: {type_text}") # Availability (before description, as in original format) if param.get('availability', '') != '': - lines.append(f"- **Availability**: *{param['availability']}*") + availability_text = escape_md_text(str(param['availability'])) + lines.append(f"- **Availability**: *{availability_text}*") # Description if param.get('description', '') != '': @@ -160,11 +173,13 @@ def generate_parameter_markdown(param: Dict[str, str]) -> str: # Default if param.get('default_value', '') != '': - lines.append(f"- **Default**: {param['default_value']}") + default_text = escape_md_text(str(param['default_value'])) + lines.append(f"- **Default**: {default_text}") # Unit if param.get('unit', '') != '': - lines.append(f"- **Unit**: {param['unit']}") + unit_text = escape_md_text(str(param['unit'])) + lines.append(f"- **Unit**: {unit_text}") lines.append("") return '\n'.join(lines) diff --git a/docs/parameters.yaml b/docs/parameters.yaml index 9fd94f9b7c..fde25b1cd5 100644 --- a/docs/parameters.yaml +++ b/docs/parameters.yaml @@ -216,7 +216,7 @@ parameters: availability: "" - name: kspacing category: System variables - type: Real + 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. @@ -674,7 +674,7 @@ parameters: * 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. + * 0.1 or less: if convergence of SCF calculation is difficult to reach, please try 0 < mixing_beta < 0.1. Note: For low-dimensional large systems, the setup of mixing_beta=0.1, mixing_ndim=20, and mixing_gg0=1.0 usually works well. default_value: "0.8 for nspin=1, 0.4 for nspin=2 and nspin=4." @@ -710,16 +710,16 @@ parameters: category: Electronic structure type: Boolean description: | - At n-th iteration which is calculated by drho=0.0" + availability: "Only for mixing_restart >= 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: 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. @@ -747,8 +747,8 @@ parameters: 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 + * <=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. @@ -915,7 +915,7 @@ parameters: 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. + 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: "" @@ -1075,7 +1075,7 @@ parameters: availability: "" - name: bessel_nao_rcut category: NAOs - type: Real + 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" @@ -1683,7 +1683,7 @@ parameters: 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. - [NOTE] Only works with LCAO basis and molecular dynamics calculations. Requires atomic velocities. Output starts from the second MD step (istep > 0). + [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: "" @@ -2316,7 +2316,7 @@ parameters: availability: Numerical atomic orbital basis and deepks_scf is true - name: deepks_band_range category: DeePKS - type: Integer*2 + 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. @@ -2672,7 +2672,7 @@ parameters: availability: "" - name: lr_init_xc_kernel category: Linear Response TDDFT (Under Development Feature) - type: String + type: "Vector of String (>=1 values)" description: | The method to initalize the xc kernel. * "default": Calculate xc kernel from the ground-state charge density. @@ -2705,7 +2705,7 @@ parameters: 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. + * Note: If the value is illegal ( > nelec/2 or <= 0), it will be autoset to nelec/2. default_value: nband unit: "" availability: "" @@ -3562,7 +3562,7 @@ parameters: 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. + 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. @@ -3570,7 +3570,7 @@ parameters: 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. + 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. @@ -3840,23 +3840,23 @@ parameters: availability: "" - name: exx_fock_alpha category: Exact Exchange (Common) - type: Vector of Real + type: Real description: | - Fraction $\alpha$ of full-ranged Fock exchange $1/r$ in range-separated hybrid functionals. + 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: Vector of Real + type: Real description: | - Fraction $\beta$ of short-ranged Fock exchange $\mathrm{erfc}(\omega r)/r$ in range-separated hybrid functionals. + 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: Vector of Real + type: Real description: | Range-separation parameter $\omega$ in the short-ranged Fock term $\mathrm{erfc}(\omega r)/r$. default_value: see hybrid_func_params @@ -3890,7 +3890,7 @@ parameters: availability: exx_separate_loop==1 - name: exx_fock_lambda category: Exact Exchange (LCAO in PW) - type: Vector of Real + 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" @@ -3916,7 +3916,7 @@ parameters: 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. + 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: "" @@ -4064,7 +4064,7 @@ parameters: availability: basis_type==lcao - name: orbital_corr category: DFT+U correction - type: Integer + type: Vector of Integer (ntype values) 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. @@ -4076,7 +4076,7 @@ parameters: availability: "" - name: hubbard_u category: DFT+U correction - type: Real + type: Vector of Real (ntype values) 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. @@ -4106,10 +4106,10 @@ parameters: 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." + availability: "DFT+U calculations with mixing_restart > 0." - name: omc category: DFT+U correction type: Integer @@ -4233,7 +4233,7 @@ parameters: availability: "" - name: qo_strategy category: Quasiatomic Orbital (QO) analysis - type: String + 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" @@ -4241,7 +4241,7 @@ parameters: availability: "" - name: qo_screening_coeff category: Quasiatomic Orbital (QO) analysis - type: Real + type: Vector of Real (ntype values; 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" diff --git a/source/source_io/module_parameter/read_input_item_elec_stru.cpp b/source/source_io/module_parameter/read_input_item_elec_stru.cpp index 16822aca8b..1a16db5577 100644 --- a/source/source_io/module_parameter/read_input_item_elec_stru.cpp +++ b/source/source_io/module_parameter/read_input_item_elec_stru.cpp @@ -675,7 +675,7 @@ For systems that are difficult to converge, one could try increasing the value o item.description = "At n-th iteration which is calculated by drhoadd_item(item); } 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 60a96c6d3c..9cfb72193d 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 @@ -64,7 +64,7 @@ void ReadInput::item_exx() item.annotation = "fraction of exchange erfc(wr)/r in hybrid functionals"; item.category = "Exact Exchange (Common)"; item.type = "Real"; - item.description = R"(Fraction $\beta$ of short-ranged Fock exchange $\mathrm{erfc}(\omega r)/r$ in range-separated hybrid functionals.)"; + item.description = R"(Fraction of short-ranged Fock exchange $\mathrm{erfc}(\omega r)/r$ in range-separated hybrid functionals.)"; item.default_value = "see hybrid_func_params"; item.unit = ""; item.availability = ""; diff --git a/source/source_io/module_parameter/read_input_item_sdft.cpp b/source/source_io/module_parameter/read_input_item_sdft.cpp index 3aec5aa9eb..b57a2ce797 100644 --- a/source/source_io/module_parameter/read_input_item_sdft.cpp +++ b/source/source_io/module_parameter/read_input_item_sdft.cpp @@ -177,4 +177,4 @@ void ReadInput::item_sdft() this->add_item(item); } } -} // namespace ModuleIO \ No newline at end of file +} // namespace ModuleIO From cb4d18dc9ee166fe6612ad92f9b0b67bfcfe3c72 Mon Sep 17 00:00:00 2001 From: Bonan Zhu Date: Thu, 26 Feb 2026 09:30:18 +0800 Subject: [PATCH 4/4] Minor wording updates --- docs/CONTRIBUTING.md | 6 ++-- docs/advanced/input_files/input-main.md | 6 ++-- docs/parameters.yaml | 34 +++++++++---------- .../read_input_item_exx_dftu.cpp | 4 +-- .../read_input_item_other.cpp | 2 +- 5 files changed, 26 insertions(+), 26 deletions(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 4f93b2e6cf..071e47df17 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -173,10 +173,10 @@ You **must** regenerate `docs/parameters.yaml` whenever you: ### How to Regenerate -After building ABACUS, run: +After building and installing ABACUS, run: ```bash -./build/abacus --generate-parameters-yaml > docs/parameters.yaml +abacus --generate-parameters-yaml > docs/parameters.yaml ``` Then verify the YAML is valid: @@ -191,7 +191,7 @@ You can also regenerate the markdown documentation locally: python3 docs/generate_input_main.py docs/parameters.yaml --output docs/advanced/input_files/input-main.md ``` -**Important:** Include the updated `docs/parameters.yaml` in your commit when submitting a PR that modifies INPUT parameters. Reviewers should verify the YAML changes match the C++ source changes. +**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. ### Parameter Documentation Format diff --git a/docs/advanced/input_files/input-main.md b/docs/advanced/input_files/input-main.md index 0678dab310..ca5041be81 100644 --- a/docs/advanced/input_files/input-main.md +++ b/docs/advanced/input_files/input-main.md @@ -3427,7 +3427,7 @@ ### orbital_corr -- **Type**: Vector of Integer (ntype values) +- **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. @@ -3437,7 +3437,7 @@ ### hubbard_u -- **Type**: Vector of Real (ntype values) +- **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. @@ -4289,7 +4289,7 @@ ### qo_screening_coeff -- **Type**: Vector of Real (ntype values; 1 value allowed for qo_basis=pswfc) +- **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 diff --git a/docs/parameters.yaml b/docs/parameters.yaml index fde25b1cd5..73726df8b3 100644 --- a/docs/parameters.yaml +++ b/docs/parameters.yaml @@ -674,7 +674,7 @@ parameters: * 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. + * 0.1 or less: if convergence of SCF calculation is difficult to reach, please try 0 < mixing_beta < 0.1. Note: For low-dimensional large systems, the setup of mixing_beta=0.1, mixing_ndim=20, and mixing_gg0=1.0 usually works well. default_value: "0.8 for nspin=1, 0.4 for nspin=2 and nspin=4." @@ -710,16 +710,16 @@ parameters: category: Electronic structure type: Boolean 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. + 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: 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. @@ -747,8 +747,8 @@ parameters: 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 + * <=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. @@ -915,7 +915,7 @@ parameters: 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. + 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: "" @@ -1683,7 +1683,7 @@ parameters: 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. - [NOTE] Only works with LCAO basis and molecular dynamics calculations. Requires atomic velocities. Output starts from the second MD step (istep > 0). + [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: "" @@ -2705,7 +2705,7 @@ parameters: 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. + * Note: If the value is illegal ( > nelec/2 or <= 0), it will be autoset to nelec/2. default_value: nband unit: "" availability: "" @@ -3562,7 +3562,7 @@ parameters: 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. + 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. @@ -3570,7 +3570,7 @@ parameters: 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. + 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. @@ -3916,7 +3916,7 @@ parameters: 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. + 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: "" @@ -4064,7 +4064,7 @@ parameters: availability: basis_type==lcao - name: orbital_corr category: DFT+U correction - type: Vector of Integer (ntype values) + 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. @@ -4076,7 +4076,7 @@ parameters: availability: "" - name: hubbard_u category: DFT+U correction - type: Vector of Real (ntype values) + 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. @@ -4106,10 +4106,10 @@ parameters: 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<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. + 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 @@ -4241,7 +4241,7 @@ parameters: availability: "" - name: qo_screening_coeff category: Quasiatomic Orbital (QO) analysis - type: Vector of Real (ntype values; 1 value allowed for qo_basis=pswfc) + 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" 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 9cfb72193d..123cbd1805 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 @@ -638,7 +638,7 @@ void ReadInput::item_dftu() item.annotation = "which correlated orbitals need corrected ; d:2 " ",f:3, do not need correction:-1"; item.category = "DFT+U correction"; - item.type = "Vector of Integer (ntype values)"; + item.type = "Vector of Integer (n values where n is the number of atomic types)"; item.description = R"(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. @@ -681,7 +681,7 @@ void ReadInput::item_dftu() Input_Item item("hubbard_u"); item.annotation = "Hubbard Coulomb interaction parameter U(ev)"; item.category = "DFT+U correction"; - item.type = "Vector of Real (ntype values)"; + item.type = "Vector of Real (n values where n is the number of atomic types)"; item.description = R"(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.)"; diff --git a/source/source_io/module_parameter/read_input_item_other.cpp b/source/source_io/module_parameter/read_input_item_other.cpp index 5e0bc3db16..1ec1bf255a 100644 --- a/source/source_io/module_parameter/read_input_item_other.cpp +++ b/source/source_io/module_parameter/read_input_item_other.cpp @@ -284,7 +284,7 @@ void ReadInput::item_others() Input_Item item("qo_screening_coeff"); item.annotation = "rescale the shape of radial orbitals"; item.category = "Quasiatomic Orbital (QO) analysis"; - item.type = "Vector of Real (ntype values; 1 value allowed for qo_basis=pswfc)"; + item.type = "Vector of Real (n values where n is the number of atomic types; 1 value allowed for qo_basis=pswfc)"; item.description = "The screening coefficient for each atom type to rescale the shape of radial orbitals"; item.default_value = "0.1"; item.unit = "Bohr^-1";