Fix(input): validate contradictory final parameters

docs/advanced/input_files/input-main.md

@@ -651,7 +651,7 @@
 ### bndpar
 
 - **Type**: Integer
-- **Description**: Divide all processors into bndpar groups, and bands (only stochastic orbitals now) will be distributed among each group. It should be larger than 0.
+- **Description**: Divide all processors into bndpar groups for SDFT or the BPCG solver. bndpar must be positive, no greater than the number of MPI processes, and kpar * bndpar must divide the number of MPI processes exactly.
 - **Default**: 1
 
 ### latname
@@ -1263,7 +1263,7 @@
 - **Description**: The number of spin components of wave functions.
   - 1: Spin degeneracy
   - 2: Collinear spin polarized.
-  - 4: For the case of noncollinear polarized, nspin will be automatically set to 4 without being specified by the user.
+  - 4: Noncollinear or spin-orbit calculations. Set nspin to 4 explicitly when noncolin or lspinorb is enabled.
 - **Default**: 1
 
 ### smearing_method
@@ -1467,7 +1467,7 @@
 - **Type**: Boolean
 - **Description**: Whether to consider spin-orbit coupling (SOC) effect in the calculation.
   - True: Consider spin-orbit coupling effect. When enabled:
-  - nspin is automatically set to 4 (noncollinear spin representation)
+  - nspin must be explicitly set to 4 (noncollinear spin representation)
   - Symmetry is automatically disabled (SOC breaks inversion symmetry)
   - Requires full-relativistic pseudopotentials with has_so=true in the UPF header
   - False: Do not consider spin-orbit coupling effect.
@@ -1479,7 +1479,7 @@
 - **Type**: Boolean
 - **Description**: Whether to allow non-collinear magnetic moments, where magnetization can point in arbitrary directions (x, y, z components) rather than being constrained to the z-axis.
   - True: Allow non-collinear polarization. When enabled:
-  - nspin is automatically set to 4
+  - nspin must be explicitly set to 4
   - Wave function dimension is doubled (npol=2), and the number of occupied states is doubled
   - Charge density has 4 components (Pauli spin matrices)
   - Cannot be used with gamma_only=true
@@ -1533,8 +1533,8 @@
 - **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 Kohn-Sham DFT.
+  - 1-1000000: Perform stochastic DFT. Increasing the number of bands improves accuracy and reduces stochastic errors; To perform mixed stochastic-deterministic DFT, you should set nbands, which represents the number of KS orbitals.
+  - 0: Invalid. Use all for the complete-basis SDFT mode.
   - all: All complete basis sets are used to replace stochastic orbitals with the Chebyshev method (CT), resulting in the same results as KSDFT without stochastic errors.
 - **Default**: 256
 

docs/advanced/scf/spin.md

@@ -30,11 +30,11 @@ If **"nupdown"** is set to non-zero, number of spin-up and spin-down electrons w
 
 ## Noncollinear Spin Polarized Calculations
 The spin non-collinear polarization calculation corresponds to setting **"noncolin 1"**, in which case the coupling between spin up and spin down will be taken into account.
-In this case, nspin is automatically set to 4, which is usually not required to be specified manually.
+In this case, **"nspin 4"** must also be specified. ABACUS reports an input error instead of silently changing an incompatible or omitted nspin value.
 The weight of each band will not change, but the number of occupied states will be double.
 If the nbands parameter is set manually, it is generally set to twice what it would be when nspin<4.
 
-In general, non-collinear magnetic moment settings are often used in calculations considering [SOC effects](#soc-effects). When **"lspinorb 1"** in INPUT file, "nspin" is also automatically set to 4.
+In general, non-collinear magnetic moment settings are often used in calculations considering [SOC effects](#soc-effects). When **"lspinorb 1"** is set in INPUT, **"nspin 4"** is also required.
 
 Note: different settings for "noncolin" and "lspinorb" correspond to different calculations:
 
@@ -119,22 +119,22 @@ Example from a full-relativistic UPF file:
 - **PseudoDOJO**: Provides both scalar and full-relativistic versions
 - **ABACUS official**: [abacus.ustc.edu.cn](http://abacus.ustc.edu.cn/pseudo/list.htm)
 
-## Automatic Parameter Settings
+## Parameter Requirements and Automatic Settings
 
-When using SOC or non-collinear calculations, ABACUS automatically adjusts several parameters:
+When using SOC or non-collinear calculations, set the required spin representation explicitly. ABACUS still derives internal spin state and some related settings after validating the input:
 
 ### When `lspinorb=true`:
-1. **nspin**: Automatically set to 4 (noncollinear spin representation)
+1. **nspin**: Must be explicitly set to 4 (noncollinear spin representation)
 2. **Symmetry**: Automatically disabled (`symm_flag=-1`) because SOC breaks inversion symmetry
 3. **Magnetization**: NOT automatically set when `noncolin=0` (implies non-magnetic material with SOC)
 
 ### When `noncolin=true`:
-1. **nspin**: Automatically set to 4
+1. **nspin**: Must be explicitly set to 4
 2. **npol**: Set to 2 (wave function has two spinor components)
 3. **Magnetization**: Automatically set if user provides zero values (unless `lspinorb=1` and `noncolin=0`)
 
 ### Important Notes:
-- You do NOT need to manually set `nspin=4` when using `lspinorb=1` or `noncolin=1`
+- You must set `nspin=4` when using `lspinorb=1` or `noncolin=1`; missing or incompatible values are rejected during input validation
 - Symmetry operations are incompatible with SOC, so they are automatically turned off
 - For `lspinorb=1, noncolin=0`: This is a special case for non-magnetic materials with SOC, where magnetization is not initialized
 
@@ -172,7 +172,7 @@ basis_type          pw
 ecutwfc             50
 lspinorb            1        # Enable SOC
 noncolin            0        # No non-collinear magnetism
-# nspin will be automatically set to 4
+nspin               4        # Required spinor representation
 # symmetry will be automatically disabled
 ```
 
@@ -185,7 +185,7 @@ calculation         scf
 basis_type          lcao
 lspinorb            0        # No SOC
 noncolin            1        # Enable non-collinear magnetism
-# nspin will be automatically set to 4
+nspin               4        # Required spinor representation
 # Magnetization directions should be specified in STRU file
 ```
 
@@ -199,7 +199,7 @@ basis_type          pw
 ecutwfc             60
 lspinorb            1        # Enable SOC
 noncolin            1        # Enable non-collinear magnetism
-# nspin will be automatically set to 4
+nspin               4        # Required spinor representation
 # symmetry will be automatically disabled
 # Magnetization directions should be specified in STRU file
 ```
@@ -213,6 +213,7 @@ calculation         scf
 basis_type          pw
 ecutwfc             50
 lspinorb            1        # Enable SOC
+nspin               4        # Required spinor representation
 soc_lambda          0.5      # 50% SOC strength
 # Useful when full SOC overestimates or underestimates experimental results
 ```

docs/community/faq.md

@@ -50,7 +50,7 @@ To perform SOC calculations in ABACUS, follow these steps:
 2. **Use full-relativistic pseudopotentials**: SOC calculations require pseudopotentials with `has_so=true` in the UPF header
    - Download full-relativistic versions of SG15_ONCV pseudopotentials from [quantum-simulation.org](http://quantum-simulation.org/potentials/sg15_oncv/upf/)
    - Check the UPF file header for `relativistic="full"` and `has_so="T"`
-3. **Verify automatic settings**: When `lspinorb=1` is set, `nspin` is automatically set to 4 and symmetry is automatically disabled
+3. **Set the spin representation**: When `lspinorb=1` is set, explicitly set `nspin=4`; symmetry is automatically disabled
 
 **Basis set support**: Both `basis_type=pw` (plane wave) and `basis_type=lcao` (numerical atomic orbitals) support SOC calculations for both SCF and NSCF.
 

docs/parameters.yaml

@@ -108,7 +108,7 @@ parameters:
     category: System variables
     type: Integer
     description: |
-      Divide all processors into bndpar groups, and bands (only stochastic orbitals now) will be distributed among each group. It should be larger than 0.
+      Divide all processors into bndpar groups for SDFT or the BPCG solver. bndpar must be positive, no greater than the number of MPI processes, and kpar * bndpar must divide the number of MPI processes exactly.
     default_value: "1"
     unit: ""
     availability: ""
@@ -661,7 +661,7 @@ parameters:
       The number of spin components of wave functions.
       * 1: Spin degeneracy
       * 2: Collinear spin polarized.
-      * 4: For the case of noncollinear polarized, nspin will be automatically set to 4 without being specified by the user.
+      * 4: Noncollinear or spin-orbit calculations. Set nspin to 4 explicitly when noncolin or lspinorb is enabled.
     default_value: "1"
     unit: ""
     availability: ""
@@ -906,7 +906,7 @@ parameters:
     description: |
       Whether to consider spin-orbit coupling (SOC) effect in the calculation.
       * True: Consider spin-orbit coupling effect. When enabled:
-        * nspin is automatically set to 4 (noncollinear spin representation)
+        * nspin must be explicitly set to 4 (noncollinear spin representation)
         * Symmetry is automatically disabled (SOC breaks inversion symmetry)
         * Requires full-relativistic pseudopotentials with has_so=true in the UPF header
       * False: Do not consider spin-orbit coupling effect.
@@ -920,7 +920,7 @@ parameters:
     description: |
       Whether to allow non-collinear magnetic moments, where magnetization can point in arbitrary directions (x, y, z components) rather than being constrained to the z-axis.
       * True: Allow non-collinear polarization. When enabled:
-        * nspin is automatically set to 4
+        * nspin must be explicitly set to 4
         * Wave function dimension is doubled (npol=2), and the number of occupied states is doubled
         * Charge density has 4 components (Pauli spin matrices)
         * Cannot be used with gamma_only=true
@@ -2198,8 +2198,8 @@ parameters:
     type: Integer or string
     description: |
       The number of stochastic orbitals
-      * > 0: Perform stochastic DFT. Increasing the number of bands improves accuracy and reduces stochastic errors; To perform mixed stochastic-deterministic DFT, you should set nbands, which represents the number of KS orbitals.
-      * 0: Perform Kohn-Sham DFT.
+      * 1-1000000: Perform stochastic DFT. Increasing the number of bands improves accuracy and reduces stochastic errors; To perform mixed stochastic-deterministic DFT, you should set nbands, which represents the number of KS orbitals.
+      * 0: Invalid. Use all for the complete-basis SDFT mode.
       * all: All complete basis sets are used to replace stochastic orbitals with the Chebyshev method (CT), resulting in the same results as KSDFT without stochastic errors.
     default_value: "256"
     unit: ""

examples/21_deepks/03_lcao_CsPbI3/INPUT

@@ -29,6 +29,7 @@ deepks_model         model.ptg
 
 #Parameters (7.SOC)
 lspinorb             1
+nspin                4
 
 
 

source/source_io/module_parameter/read_input_item_elec_stru.cpp

@@ -482,22 +482,20 @@ The other way is only available when compiling with LIBXC, and it allows for sup
         item.description = R"(The number of spin components of wave functions.
 * 1: Spin degeneracy
 * 2: Collinear spin polarized.
-* 4: For the case of noncollinear polarized, nspin will be automatically set to 4 without being specified by the user.)";
+* 4: Noncollinear or spin-orbit calculations. Set nspin to 4 explicitly when noncolin or lspinorb is enabled.)";
         item.default_value = "1";
         item.unit = "";
         item.availability = "";
         read_sync_int(input.nspin);
-        item.reset_value = [](const Input_Item& item, Parameter& para) {
-            if (para.input.noncolin || para.input.lspinorb)
-            {
-                para.input.nspin = 4;
-            }
-        };
         item.check_value = [](const Input_Item& item, const Parameter& para) {
             if (para.input.nspin != 1 && para.input.nspin != 2 && para.input.nspin != 4)
             {
                 ModuleBase::WARNING_QUIT("ReadInput", "nspin should be 1, 2 or 4.");
             }
+            if ((para.input.noncolin || para.input.lspinorb) && para.input.nspin != 4)
+            {
+                ModuleBase::WARNING_QUIT("ReadInput", "nspin must be 4 when noncolin or lspinorb is enabled.");
+            }
         };
         this->add_item(item);
     }
@@ -986,7 +984,7 @@ Note: If gamma_only is set to 1, the KPT file will be overwritten. So make sure
         item.type = "Boolean";
         item.description = R"(Whether to consider spin-orbit coupling (SOC) effect in the calculation.
 * True: Consider spin-orbit coupling effect. When enabled:
-  * nspin is automatically set to 4 (noncollinear spin representation)
+  * nspin must be explicitly set to 4 (noncollinear spin representation)
   * Symmetry is automatically disabled (SOC breaks inversion symmetry)
   * Requires full-relativistic pseudopotentials with has_so=true in the UPF header
 * False: Do not consider spin-orbit coupling effect.
@@ -1004,7 +1002,7 @@ Note: If gamma_only is set to 1, the KPT file will be overwritten. So make sure
         item.type = "Boolean";
         item.description = R"(Whether to allow non-collinear magnetic moments, where magnetization can point in arbitrary directions (x, y, z components) rather than being constrained to the z-axis.
 * True: Allow non-collinear polarization. When enabled:
-  * nspin is automatically set to 4
+  * nspin must be explicitly set to 4
   * Wave function dimension is doubled (npol=2), and the number of occupied states is doubled
   * Charge density has 4 components (Pauli spin matrices)
   * Cannot be used with gamma_only=true

source/source_io/module_parameter/read_input_item_sdft.cpp

@@ -1,8 +1,9 @@
-#include "source_base/global_function.h"
 #include "source_base/tool_quit.h"
 #include "read_input.h"
 #include "read_input_tool.h"
 
+#include <exception>
+
 namespace ModuleIO
 {
 void ReadInput::item_sdft()
@@ -37,8 +38,8 @@ void ReadInput::item_sdft()
         item.category = "Electronic structure (SDFT)";
         item.type = "Integer or string";
         item.description = R"(The number of stochastic orbitals
-* > 0: Perform stochastic DFT. Increasing the number of bands improves accuracy and reduces stochastic errors; To perform mixed stochastic-deterministic DFT, you should set nbands, which represents the number of KS orbitals.
-* 0: Perform Kohn-Sham DFT.
+* 1-1000000: Perform stochastic DFT. Increasing the number of bands improves accuracy and reduces stochastic errors; To perform mixed stochastic-deterministic DFT, you should set nbands, which represents the number of KS orbitals.
+* 0: Invalid. Use all for the complete-basis SDFT mode.
 * all: All complete basis sets are used to replace stochastic orbitals with the Chebyshev method (CT), resulting in the same results as KSDFT without stochastic errors.)";
         item.default_value = "256";
         item.unit = "";
@@ -47,28 +48,32 @@ void ReadInput::item_sdft()
             std::string nbandsto_str = strvalue;
             if (nbandsto_str != "all")
             {
-                para.input.nbands_sto = std::stoi(nbandsto_str);
+                std::size_t parsed_chars = 0;
+                try
+                {
+                    para.input.nbands_sto = std::stoi(nbandsto_str, &parsed_chars);
+                }
+                catch (const std::exception&)
+                {
+                    ModuleBase::WARNING_QUIT("ReadInput",
+                                             "nbands_sto should be in the range of 1 to 1000000 or be all");
+                }
+                if (parsed_chars != nbandsto_str.size())
+                {
+                    ModuleBase::WARNING_QUIT("ReadInput",
+                                             "nbands_sto should be in the range of 1 to 1000000 or be all");
+                }
             }
             else
             {
                 para.input.nbands_sto = 0;
             }
         };
-        item.reset_value = [](const Input_Item& item, Parameter& para) {
-            // only do it when nbands_sto is set in INPUT
-            if (item.is_read())
-            {
-                if (strvalue == "0" && para.input.esolver_type == "sdft")
-                {
-                    para.input.esolver_type = "ksdft";
-                    ModuleBase::GlobalFunc::AUTO_SET("esolver_type", para.input.esolver_type);
-                }
-            }
-        };
         item.check_value = [](const Input_Item& item, const Parameter& para) {
-            if (para.input.nbands_sto < 0 || para.input.nbands_sto > 100000)
+            const bool use_complete_basis = item.is_read() && strvalue == "all";
+            if ((!use_complete_basis && para.input.nbands_sto < 1) || para.input.nbands_sto > 1000000)
             {
-                ModuleBase::WARNING_QUIT("ReadInput", "nbands_sto should be in the range of 0 to 100000");
+                ModuleBase::WARNING_QUIT("ReadInput", "nbands_sto should be in the range of 1 to 1000000 or be all");
             }
         };
         item.get_final_value = [](Input_Item& item, const Parameter& para) {

source/source_io/module_parameter/read_input_item_system.cpp

@@ -313,7 +313,7 @@ void ReadInput::item_system()
             // GPU + PW: validate kpar against total processors
             // Moved from base_device::information::get_device_kpar()
 #if defined(__CUDA) || defined(__ROCM)
-            if (para.input.device == "gpu" && para.input.basis_type == "pw")
+            if (para.input.device == "gpu" && para.input.basis_type == "pw" && para.input.bndpar > 0)
             {
                 if (GlobalV::NPROC != para.input.kpar * para.input.bndpar)
                 {
@@ -339,25 +339,34 @@ void ReadInput::item_system()
                           "will be distributed among each group";
         item.category = "System variables";
         item.type = "Integer";
-        item.description = "Divide all processors into bndpar groups, and bands (only stochastic orbitals now) "
-                          "will be distributed among each group. It should be larger than 0.";
+        item.description = "Divide all processors into bndpar groups for SDFT or the BPCG solver. bndpar must be "
+                           "positive, no greater than the number of MPI processes, and kpar * bndpar must divide "
+                           "the number of MPI processes exactly.";
         item.default_value = "1";
         read_sync_int(input.bndpar);
-        item.reset_value = [](const Input_Item& item, Parameter& para) {
-            if (para.input.esolver_type != "sdft" && para.input.ks_solver != "bpcg")
+        item.check_value = [](const Input_Item& item, const Parameter& para) {
+            if (para.input.bndpar <= 0)
             {
-                para.input.bndpar = 1;
+                ModuleBase::WARNING_QUIT("ReadInput", "bndpar must be greater than 0");
             }
             if (para.input.bndpar > GlobalV::NPROC)
             {
-                para.input.bndpar = GlobalV::NPROC;
+                ModuleBase::WARNING_QUIT("ReadInput", "bndpar can not exceed the number of MPI processes");
+            }
+            if (para.input.bndpar > 1 && para.input.esolver_type != "sdft" && para.input.ks_solver != "bpcg")
+            {
+                ModuleBase::WARNING_QUIT("ReadInput", "bndpar > 1 requires esolver_type=sdft or ks_solver=bpcg");
             }
-        };
-        item.check_value = [](const Input_Item& item, const Parameter& para) {
             if (GlobalV::NPROC % para.input.bndpar != 0)
             {
                 ModuleBase::WARNING_QUIT("ReadInput", "The number of processors can not be divided by bndpar");
             }
+            if (para.input.bndpar > 1
+                && (para.input.kpar <= 0 || (GlobalV::NPROC / para.input.bndpar) % para.input.kpar != 0))
+            {
+                ModuleBase::WARNING_QUIT("ReadInput",
+                                         "The number of processors can not be divided by kpar * bndpar");
+            }
         };
         this->add_item(item);
     }