Fix: doc of soc (#6856)

dyzheng · root · web-flow · commit 48bfcaa33b69 · 2026-01-15T21:46:15.000+08:00
Co-authored-by: root &lt;root@LAPTOP-C2B3O75T.localdomain&gt;
diff --git a/docs/advanced/input_files/input-main.md b/docs/advanced/input_files/input-main.md
@@ -1369,28 +1369,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
diff --git a/docs/advanced/pp_orb.md b/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).
diff --git a/docs/advanced/scf/spin.md b/docs/advanced/scf/spin.md
@@ -29,36 +29,37 @@ If **"ocp=1"** and **"ocp_set"** is set in INPUT file, the occupations of states
 If **"nupdown"** is set to non-zero, number of spin-up and spin-down electrons will be fixed, and Fermi energy level will split to E_Fermi_up and E_Fermi_down. By the way, total magnetization will also be fixed, and will be the value of **"nupdown"**.
 
 ## 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. 
+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.
-The weight of each band will not change, but the number of occupied states will be double. 
+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"** in INPUT file, "nspin" is also automatically set to 4.
+
 Note: different settings for "noncolin" and "lspinorb" correspond to different calculations:
- - noncolin=0 lspinorb=0 nspin<4 : 
-Non-collinear magnetic moments and SOC effects are not considered.
- - noncolin=0 lspinorb=0 nspin=4 : 
-Actualy same as the above setting, but the calculation will be larger. So the setting is not recommended.
- - noncolin=1 lspinorb=0 : 
-Non-collinear magnetic moments are considered but SOC effects are not considered
- - noncolin=0 lspinorb=1 : 
-The SOC effect is considered but the magnetic moment is limited to the Z direction
- - noncolin=1 lspinorb=1 : 
-The SOC effect and non-collinear magnetic moment are both calculated.
+
+| noncolin | lspinorb | nspin | Effect | When to Use |
+|----------|----------|-------|--------|-------------|
+| 0 | 0 | <4 | No non-collinear magnetism, no SOC | Standard collinear spin-polarized or non-spin-polarized calculations |
+| 0 | 0 | 4 | Same as above, but larger calculation | **Not recommended** - wastes computational resources |
+| 1 | 0 | 4 | Non-collinear magnetism WITHOUT SOC | Systems with complex magnetic structures (e.g., spin spirals, frustrated magnets) where SOC is negligible |
+| 0 | 1 | 4 | SOC WITH z-axis magnetism only | Non-magnetic materials with SOC (e.g., semiconductors with band splitting), or magnetic materials where magnetism is along z-axis |
+| 1 | 1 | 4 | Both SOC AND non-collinear magnetism | Heavy-element magnetic materials where both SOC and non-collinear magnetism are important (e.g., magnetic anisotropy, Dzyaloshinskii-Moriya interaction) |
+
+**Special case**: `noncolin=0, lspinorb=1` is commonly used for non-magnetic materials with SOC effects (e.g., topological insulators, semiconductors with spin-orbit splitting). In this case, the magnetization is NOT automatically set, implying no magnetic moments in the system.
 
 ## For the continuation job
 - Continuation job for "nspin 1" need file "SPIN1_CHG.cube" which is generated by setting "out_chg=1" in task before. By setting "init_chg file" in new job's INPUT file, charge density will start from file but not atomic. 
 - Continuation job for "nspin 2" need files "SPIN1_CHG.cube" and "SPIN2_CHG.cube" which are generated by "out_chg 1" with "nspin 2", and refer to spin-up and spin-down charge densities respectively. It should be note that reading "SPIN1_CHG.cube" only for the continuation target magnetic moment job is not supported now.
 - Continuation job for "nspin 4" need files "SPIN%s_CHG.cube", where %s in {1,2,3,4}, which are generated by "out_chg 1" with any variable setting leading to 'nspin'=4, and refer to charge densities in Pauli spin matrixes. It should be note that reading charge density files printing by 'nspin'=2 case is supported, which means only $\sigma_{tot}$ and $\sigma_{z}$ are read.
 
 # SOC Effects
-## SOC 
+## SOC
 `lspinorb` is used for control whether or not SOC(spin-orbit coupling) effects should be considered.
 
 Both `basis_type=pw` and `basis_type=lcao` support `scf` and `nscf` calculation with SOC effects.
 
-Atomic forces and cell stresses can not be calculated with SOC effects yet. 
+Atomic forces and cell stresses can be calculated with SOC effects (supported since ABACUS v3.9.0). 
 
 ## Pseudopotentials and Numerical Atomic Orbitals
 For Norm-Conserving pseudopotentials, there are differences between SOC version and non-SOC version.
@@ -72,9 +73,146 @@ When full-relativistic pseudopotential is used for non-SOC calculation, ABACUS w
 Numerical atomic orbitals in ABACUS are unrelated with spin, and same orbital file can be used for SOC and non-SOC calculation.
 
 ## Partial-relativistic SOC Effect
-Sometimes, for some real materials, both scalar-relativistic and full-relativistic can not describe the exact spin-orbit coupling. 
+Sometimes, for some real materials, both scalar-relativistic and full-relativistic can not describe the exact spin-orbit coupling.
 Artificial modulation can help for these cases.
 
 `soc_lambda`, which has value range [0.0, 1.0] , is used for modulate SOC effect.
 In particular, `soc_lambda 0.0` refers to scalar-relativistic case and `soc_lambda 1.0` refers to full-relativistic case.
 
+## Pseudopotential Requirements for SOC
+
+When performing SOC calculations (`lspinorb=1`), specific pseudopotential requirements must be met:
+
+### Checking Pseudopotential Files
+
+In the UPF (Unified Pseudopotential Format) file header (`PP_HEADER` section), look for:
+- `has_so="T"` or `has_so="1"`: Indicates SOC information is included
+- `relativistic="full"`: Indicates full-relativistic pseudopotential
+
+Example from a full-relativistic UPF file:
+```
+<PP_HEADER
+   ...
+   relativistic="full"
+   has_so="T"
+   ...
+/>
+```
+
+### Pseudopotential Usage Rules
+
+1. **For SOC calculations** (`lspinorb=1`):
+   - **MUST** use full-relativistic pseudopotentials with `has_so=true`
+   - Code will terminate with error: "no soc upf used for lspinorb calculation" if scalar-relativistic PP is used
+
+2. **For non-SOC calculations** (`lspinorb=0`):
+   - Can use either scalar-relativistic or full-relativistic pseudopotentials
+   - If full-relativistic PP is used, ABACUS automatically transforms it to scalar-relativistic version
+
+3. **For ultrasoft pseudopotentials (USPP)**:
+   - Full-relativistic USPP **requires** `lspinorb=true`
+   - Code will show warning: "FR-USPP please use lspinorb=.true." if this requirement is not met
+
+### Where to Find SOC Pseudopotentials
+
+- **SG15_ONCV**: Full-relativistic versions available at [quantum-simulation.org](http://quantum-simulation.org/potentials/sg15_oncv/upf/)
+- **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
+
+When using SOC or non-collinear calculations, ABACUS automatically adjusts several parameters:
+
+### When `lspinorb=true`:
+1. **nspin**: Automatically 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
+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`
+- 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
+
+## Common Errors and Solutions
+
+### Error: "no soc upf used for lspinorb calculation"
+**Cause**: Using scalar-relativistic pseudopotentials with `lspinorb=1`
+
+**Solution**: Download and use full-relativistic pseudopotentials with `has_so=true`. Check the UPF file header to verify `relativistic="full"` and `has_so="T"`.
+
+### Error: "nspin=4(soc or noncollinear-spin) does not support gamma only calculation"
+**Cause**: Trying to use `gamma_only=true` with `lspinorb=1` or `noncolin=1`
+
+**Solution**: Set `gamma_only=false` or `gamma_only=0` in your INPUT file. SOC and non-collinear calculations require k-point sampling beyond the gamma point.
+
+### Warning: "FR-USPP please use lspinorb=.true."
+**Cause**: Using full-relativistic ultrasoft pseudopotentials without enabling SOC
+
+**Solution**: Set `lspinorb=true` in your INPUT file, or switch to scalar-relativistic USPP if SOC is not needed.
+
+### Issue: Forces or stresses not calculated
+**Note**: This issue has been resolved. Atomic forces and cell stresses can now be calculated with SOC effects (supported since ABACUS v3.9.0).
+
+If you are using an older version of ABACUS (before v3.9.0), force and stress calculations with SOC were not supported. Please upgrade to the latest version to use this feature.
+
+## INPUT File Examples
+
+### Example 1: SOC without Non-collinear Magnetism
+For non-magnetic materials with SOC (e.g., GaAs, topological insulators):
+
+```
+INPUT_PARAMETERS
+calculation         scf
+basis_type          pw
+ecutwfc             50
+lspinorb            1        # Enable SOC
+noncolin            0        # No non-collinear magnetism
+# nspin will be automatically set to 4
+# symmetry will be automatically disabled
+```
+
+### Example 2: Non-collinear Magnetism without SOC
+For systems with complex magnetic structures but negligible SOC:
+
+```
+INPUT_PARAMETERS
+calculation         scf
+basis_type          lcao
+lspinorb            0        # No SOC
+noncolin            1        # Enable non-collinear magnetism
+# nspin will be automatically set to 4
+# Magnetization directions should be specified in STRU file
+```
+
+### Example 3: Both SOC and Non-collinear Magnetism
+For heavy-element magnetic materials (e.g., Fe with SOC, materials with DMI):
+
+```
+INPUT_PARAMETERS
+calculation         scf
+basis_type          pw
+ecutwfc             60
+lspinorb            1        # Enable SOC
+noncolin            1        # Enable non-collinear magnetism
+# nspin will be automatically set to 4
+# symmetry will be automatically disabled
+# Magnetization directions should be specified in STRU file
+```
+
+### Example 4: Partial-relativistic SOC
+For fine-tuning SOC strength:
+
+```
+INPUT_PARAMETERS
+calculation         scf
+basis_type          pw
+ecutwfc             50
+lspinorb            1        # Enable SOC
+soc_lambda          0.5      # 50% SOC strength
+# Useful when full SOC overestimates or underestimates experimental results
+```
diff --git a/docs/community/faq.md b/docs/community/faq.md
@@ -44,7 +44,23 @@ Non-periodic systems such as liquid systems can be calculated by using supercell
 
 **6. How to perform spin-orbital coupling (SOC) calculations in ABACUS?**
 
-Apart from setting relavant keys (`lspinorb` to 1) in the `INPUT` file, SOC calculations can only be performed with fully-relativistic pseudopotentials. Users are suggested to download fully-relativistic versions of SG15_ONCV pseudopotential files from a [website](http://quantum-simulation.org/potentials/sg15_oncv/upf/). The numerical orbital files generated from the corresponding scalar-relativistic pseudoptential files by ABACUS ([here](http://abacus.ustc.edu.cn/pseudo/list.htm)) can be used in collaboration with the fully-relativistic pseudopotentials.
+To perform SOC calculations in ABACUS, follow these steps:
+
+1. **Set `lspinorb=1` in the INPUT file**: This enables spin-orbit coupling effects
+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
+
+**Basis set support**: Both `basis_type=pw` (plane wave) and `basis_type=lcao` (numerical atomic orbitals) support SOC calculations for both SCF and NSCF.
+
+**Force and stress calculations**: Atomic forces and cell stresses can be calculated with SOC (supported since ABACUS v3.9.0).
+
+**Numerical atomic orbitals**: The numerical orbital files generated from scalar-relativistic pseudopotentials (available at [abacus.ustc.edu.cn](http://abacus.ustc.edu.cn/pseudo/list.htm)) can be used with full-relativistic pseudopotentials, as orbitals are spin-independent.
+
+**Common error**: If you see "no soc upf used for lspinorb calculation", ensure you are using full-relativistic pseudopotentials with `has_so=true`.
+
+For detailed information, examples, and troubleshooting, see [Spin-polarization and SOC](../advanced/scf/spin.md#soc-effects).
 
 **7. How to restart jobs in abacus?**
 
