Merge branch 'develop' into Charge_template

Conflicts:
	source/source_pw/module_ofdft/evolve_ofdft.cpp
	source/source_pw/module_ofdft/evolve_ofdft.h

Author: PeizeLin

docs/advanced/input_files/input-main.md

@@ -557,6 +557,7 @@ These variables are used to control general system parameters.
     - If ([dft_fuctional](#dft_functional)==hse/hf/pbe0/scan0 or [rpa](#rpa)==True).
     - If [efield_flag](#efield_flag)==1
   - 1: else
+- **Note**: When symmetry is enabled (value 1), k-points are reduced to the irreducible Brillouin zone (IBZ). For explicit k-point lists with custom weights (see [KPT file](./kpt.md#k-point-weights-and-symmetry)), the custom weights are preserved during symmetry reduction. For Monkhorst-Pack grids, uniform weights are used.
 
 ### symmetry_prec
 
@@ -1369,28 +1370,46 @@ Note: In new angle mixing, you should set `mixing_beta_mag >> mixing_beta`. The
 ### lspinorb
 
 - **Type**: Boolean
-- **Description**: Whether to consider spin-orbital coupling effect in the calculation.
-  - True: Consider spin-orbital coupling effect, and `nspin` is also automatically set to 4.
-  - False: Do not consider spin-orbital coupling effect.
+- **Description**: Whether to consider spin-orbit coupling (SOC) effect in the calculation.
+  - **True**: Consider spin-orbit coupling effect. When enabled:
+    - `nspin` is automatically set to 4 (noncollinear spin representation)
+    - Symmetry is automatically disabled (SOC breaks inversion symmetry)
+    - **Requires** full-relativistic pseudopotentials with `has_so=true` in the UPF header
+  - **False**: Do not consider spin-orbit coupling effect.
+  - **Common Error**: "no soc upf used for lspinorb calculation" - ensure you are using full-relativistic pseudopotentials
+  - See [Spin-polarization and SOC](../scf/spin.md#soc-effects) for detailed usage and examples
 - **Default**: False
 
 ### noncolin
 
 - **Type**: Boolean
-- **Description**: Whether to allow non-collinear polarization, in which case the coupling between spin up and spin down will be taken into account.
-  - True: Allow non-collinear polarization, and `nspin` is also automatically set to 4.
-  - False: Do not allow non-collinear polarization.
+- **Description**: Whether to allow non-collinear magnetic moments, where magnetization can point in arbitrary directions (x, y, z components) rather than being constrained to the z-axis.
+  - **True**: Allow non-collinear polarization. When enabled:
+    - `nspin` is automatically set to 4
+    - Wave function dimension is doubled (`npol=2`), and the number of occupied states is doubled
+    - Charge density has 4 components (Pauli spin matrices: ρ_total, ρ_x, ρ_y, ρ_z)
+    - **Constraint**: Cannot be used with `gamma_only=true`
+    - Can be combined with `lspinorb=true` for SOC effects with non-collinear magnetism
+  - **False**: Do not allow non-collinear polarization (magnetization constrained to z-axis).
+  - **Relationship with lspinorb**:
+    - `noncolin=0, lspinorb=1`: SOC with z-axis magnetism only (for non-magnetic materials with SOC)
+    - `noncolin=1, lspinorb=0`: Non-collinear magnetism without SOC
+    - `noncolin=1, lspinorb=1`: Both non-collinear magnetism and SOC
+  - See [Noncollinear Spin Polarized Calculations](../scf/spin.md#noncollinear-spin-polarized-calculations) for usage examples
 - **Default**: False
 
 ### soc_lambda
 
 - **Type**: Real
-- **Availability**: Relevant for soc calculations.
-- **Description**: Sometimes, for some real materials, both scalar-relativistic and full-relativistic can not describe the exact spin-orbit coupling. Artificial modulation may help in such cases.
+- **Availability**: Only works when `lspinorb=true`
+- **Description**: Modulates the strength of spin-orbit coupling effect. Sometimes, for some real materials, both scalar-relativistic and full-relativistic pseudopotentials cannot describe the exact spin-orbit coupling. Artificial modulation may help in such cases.
 
-  `soc_lambda`, which has value range [0.0, 1.0] , is used for modulate SOC effect.
+  `soc_lambda`, which has value range [0.0, 1.0], is used to modulate SOC effect:
+  - `soc_lambda 0.0`: Scalar-relativistic case (no SOC)
+  - `soc_lambda 1.0`: Full-relativistic case (full SOC)
+  - Intermediate values: Partial-relativistic SOC (interpolation between scalar and full)
 
-  In particular, `soc_lambda 0.0` refers to scalar-relativistic case and `soc_lambda 1.0` refers to full-relativistic case.
+  **Use case**: When experimental or high-level theoretical results suggest that the SOC effect is weaker or stronger than what full-relativistic pseudopotentials predict, you can adjust this parameter to match the target behavior.
 - **Default**: 1.0
 
 ### dfthalf_type

docs/advanced/input_files/kpt.md

@@ -58,6 +58,40 @@ Direct //`Direct' or `Cartesian' coordinate
 0.5 0.5 0.5 0.125
 ```
 
+### K-point Weights and Symmetry
+
+When explicitly setting k-points, you can specify custom weights for each k-point. These weights determine the contribution of each k-point to the total energy and density calculations.
+
+**Important notes about k-point weights:**
+
+1. **Custom weights are preserved**: When using explicit k-point lists (non-Monkhorst-Pack), ABACUS preserves the custom weights you specify, even when symmetry operations are applied to reduce the k-points to the irreducible Brillouin zone (IBZ).
+
+2. **Symmetry reduction**: When [`symmetry`](./input-main.md#symmetry) is set to 1, ABACUS will analyze the crystal symmetry and reduce the k-point set to the irreducible Brillouin zone. During this reduction:
+   - For **Monkhorst-Pack grids** (automatically generated): All k-points have uniform weights (1/N where N is the total number of k-points)
+   - For **explicit k-point lists**: Custom weights are preserved and properly combined when symmetry-equivalent k-points are merged
+
+3. **Weight normalization**: After symmetry reduction, k-point weights are normalized so that their sum equals `degspin` (2 for non-spin-polarized calculations, 1 for spin-polarized calculations).
+
+**Example with custom weights:**
+
+```
+K_POINTS
+5
+Direct
+0.0 0.0 0.0   0.1   // Gamma point with weight 0.1
+0.5 0.0 0.0   0.2   // X point with weight 0.2
+0.0 0.5 0.0   0.3   // Y point with weight 0.3
+0.5 0.5 0.0   0.2   // M point with weight 0.2
+0.0 0.0 0.5   0.2   // Z point with weight 0.2
+```
+
+In this example, different k-points have different weights, which might be useful for:
+- Special sampling schemes
+- Convergence testing with specific k-point importance
+- Custom integration methods
+
+> **Note**: When using custom weights with symmetry, ensure that your weight distribution is consistent with the crystal symmetry. ABACUS will preserve your weights during IBZ reduction, but inconsistent weights may lead to unexpected results.
+
 [back to top](#the-kpt-file)
 
 ## Band structure calculations

docs/advanced/pp_orb.md

@@ -65,7 +65,57 @@ $$
 
 ## Pseudopotentials
 ### Supported formats
-ABACUS supports both norm-conserving and ultrasoft pseudopotentials. For norm-conserving pseudopotentials, UPF, UPF2, VWR, and BLPS formats are supported. For ultrasoft pseudopotentials, UPF and UPF2 formats are supported. 
+ABACUS supports both norm-conserving and ultrasoft pseudopotentials. For norm-conserving pseudopotentials, UPF, UPF2, VWR, and BLPS formats are supported. For ultrasoft pseudopotentials, UPF and UPF2 formats are supported.
+
+### Pseudopotentials for SOC Calculations
+
+When performing spin-orbit coupling (SOC) calculations with `lspinorb=1`, specific pseudopotential requirements must be met:
+
+#### Identifying SOC Pseudopotentials
+
+Full-relativistic pseudopotentials suitable for SOC calculations can be identified by checking the UPF file header (`PP_HEADER` section):
+
+```xml
+<PP_HEADER
+   ...
+   relativistic="full"
+   has_so="T"
+   ...
+/>
+```
+
+- **`relativistic="full"`**: Indicates a full-relativistic pseudopotential
+- **`has_so="T"` or `has_so="1"`**: Indicates SOC information is included in the pseudopotential
+
+#### Usage Rules
+
+1. **SOC calculations** (`lspinorb=1`):
+   - **Required**: Full-relativistic pseudopotentials with `has_so=true`
+   - **Error if not met**: "no soc upf used for lspinorb calculation"
+
+2. **Non-SOC calculations** (`lspinorb=0`):
+   - **Flexible**: Can use either scalar-relativistic (`relativistic="scalar"`) or full-relativistic pseudopotentials
+   - **Automatic conversion**: If full-relativistic PP is used, ABACUS automatically transforms it to scalar-relativistic version
+
+3. **Ultrasoft pseudopotentials (USPP)**:
+   - **Constraint**: Full-relativistic USPP must be used with `lspinorb=true`
+   - **Warning if violated**: "FR-USPP please use lspinorb=.true."
+
+#### Validation by ABACUS
+
+ABACUS performs automatic validation when reading pseudopotentials:
+- Checks if `lspinorb=1` but pseudopotential has `has_so=false` → terminates with error
+- Checks if full-relativistic USPP is used without `lspinorb=1` → shows warning
+- Automatically averages SOC-related beta functions when `lspinorb=0`
+
+#### Where to Find SOC Pseudopotentials
+
+For SOC calculations, download full-relativistic pseudopotentials from:
+- **SG15_ONCV**: [quantum-simulation.org](http://quantum-simulation.org/potentials/sg15_oncv/upf/) - widely used in ABACUS
+- **PseudoDOJO**: [pseudo-dojo.org](http://www.pseudo-dojo.org/) - provides both scalar and full-relativistic versions
+- **ABACUS official**: [abacus.ustc.edu.cn](http://abacus.ustc.edu.cn/pseudo/list.htm) - includes both pseudopotentials and numerical atomic orbitals
+
+For more details on SOC calculations, see [Spin-polarization and SOC](./scf/spin.md#soc-effects).
 
 ### Usage
 For more information about pseudopotential usage, check the `ATOMIC_SPECIES` section in the specification of the [STRU file](./input_files/stru.md).