Feature: fully utilized magnetic space group (MSG) enabling SOC

[maki49]

What's implemented

• SOC double group operation $T \otimes U$: construction, charge density symmetrization, and (for EXX) the rotation of D(k) and Hexx(R)
• Time reversal symmetry $\Theta=-i\sigma_y K$
• Megnetic (Shubnikov) group analysis (enable anti-unitary operations)

What's fixed by the way

• Disable autoset_magnetization at symmetry==1 (The meaning of symmetry==1 is to analyze and preserve the symmetry of the initial magnetic structure, which is documented.)
• Enable mixing_restart for EXX 2nd loop (Fix the segfault at the charge mixer pointer)

Correctness and Efficiency: HSE, SOC (lspinorb=1)

#	Sys	SG/MSG	IBZ/BZ	nosym E (eV)	ΔE(symk)	ΔE(sym)	EXX conv steps n/k/s	Wall time n/k/s (s)
01	GaAs	T_d	4/27	−4788.307939	−0.2 μeV	−0.2 μeV	11/11/11	721/711/586
02	Bi	D_3d	6/27	−4276.312290	+0.1 μeV	+0.1 μeV	11/11/11	521/509/392
03	Zn	D_6h	8/48	−11328.542825	+0.0 μeV	+0.0 μeV	11/11/11	2125/2113/1547
04	Fe	O_h/C_4h	13/64	−3378.065090	−0.1 μeV	−0.2 μeV	69/62/59	2413/2191/1222
05	Co	D_6h/C_6h	8/48	−8150.565738	+0.2 μeV	−0.3 μeV	69/95/119	7745/9951/4233
06	FePt	D_4h/C_4h	12/48	−6858.995196	+0.0 μeV	+0.4 μeV	44/50/50	5526/5962/3300
07	NiO	D_3d/S_2	6/8	−9959.557188	−1.7 μeV	−7.6 μeV	24/24/24	356/343/328
08	Mn₃Sn	D_6h/D_6	9/36	(PBE not conv.)	symk vs sym −0.1 μeV		—/27/27	—/47633/28493
09	Mn₃Ir	O_h/S_6	6/27	−11822.6847	+0.0 meV*	+0.1 meV*	32/33/41	9630/9451/6084

• nosym/n: symmetry==-1
• symk/k (Reduce k points): symmetry==1, exx_symmetry_realspace==0
• sym/s (Reduce both k points and Hexx(R)): symmetry==1, exx_symmetry_realspace==1

A detailed test report:
2026-07-SOC对称性测试-最终.pdf

[Copilot]

Pull request overview

This PR extends ABACUS symmetry support to nspin=4 (SOC / non-collinear) by adding time-reversal handling, double-group (spinor) rotation machinery, and Shubnikov (magnetic) group analysis so that k-reduction, density symmetrization, and EXX (including real-space EXX symmetry) can preserve the symmetry of the initial magnetic structure.

Changes:

• Add SU(2) spin-rotation utilities and apply them to SOC density symmetrization and SOC EXX symmetry rotations (including antiunitary/Shubnikov handling).
• Extend EXX symmetry rotation/restoration paths to handle nspin=4 (including coupled 4-channel spinor real-space H(R) restoration).
• Add/extend tests and an integration EXX case to validate SOC symmetry behavior; update symmetry input documentation.

Reviewed changes

Copilot reviewed 34 out of 34 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
tests/integrate/tools/catch_properties.sh	Adjust symmetry property extraction to avoid magnetic-group lines interfering; optionally capture magnetic point group for nspin=4.
tests/08_EXX/CASES_CPU.txt	Register a new CPU EXX test case.
tests/08_EXX/15_KP_HSE_SOC_symm/threshold	Thresholds for the new SOC+EXX symmetry integration case.
tests/08_EXX/15_KP_HSE_SOC_symm/STRU	Structure for the new SOC+EXX symmetry integration case.
tests/08_EXX/15_KP_HSE_SOC_symm/result.ref	Reference outputs for symmetry assertions and energies.
tests/08_EXX/15_KP_HSE_SOC_symm/KPT	K-point grid for the new integration case.
tests/08_EXX/15_KP_HSE_SOC_symm/INPUT	Input enabling nspin=4 + SOC + symmetry + HSE/EXX settings for the test.
source/source_lcao/module_ri/module_exx_symmetry/test/symmetry_rotation_test.cpp	Add unit tests for SOC time-reversal spin-flip helpers.
source/source_lcao/module_ri/module_exx_symmetry/symmetry_rotation.h	Extend EXX symmetry rotation interfaces for SOC and antiunitary operations.
source/source_lcao/module_ri/module_exx_symmetry/symmetry_rotation.cpp	Implement SOC spinor AO rotation, TRS handling via Sigma_y, and antiunitary-aware rotation logic.
source/source_lcao/module_ri/module_exx_symmetry/symmetry_rotation_R.hpp	Add SOC coupled 4-channel real-space H(R) restoration including antiunitary channel remap.
source/source_lcao/module_ri/module_exx_symmetry/irreducible_sector.cpp	Extend sector rotation bookkeeping to support antiunitary spatial parts with a unified raw index.
source/source_lcao/module_ri/module_exx_symmetry/irreducible_sector_bvk.cpp	Map BvK symmetry ops to both unitary and antiunitary spatial operations where applicable.
source/source_lcao/module_ri/Exx_LRI.hpp	Route SOC (nspin=4) EXX symmetry to a coupled-channel implementation.
source/source_lcao/module_ri/Exx_LRI.h	Declare SOC-specific coupled EXX symmetry entry point.
source/source_lcao/module_ri/Exx_LRI_interface.hpp	Enable EXX space-group symmetry for SOC and fix mixing_restart pointer reuse/restart behavior.
source/source_lcao/module_ri/Exx_LRI_interface.h	Store charge-mixing pointer identity to safely re-borrow after restart.
source/source_io/module_parameter/input_conv.cpp	Stop forcibly disabling symmetry for LCAO EXX SOC; update symmetry reset logic.
source/source_estate/module_charge/symmetry_rhog.cpp	Pass an explicit symmetry-op list to rhog symmetrization, aligned with SOC magnetic group rules.
source/source_estate/module_charge/symmetry_rho.h	Add SOC spin-density symmetrization API to Symmetry_rho.
source/source_estate/module_charge/symmetry_rho.cpp	Implement SOC path: symmetrize charge and coupled (x,y,z) spin density separately.
source/source_cell/read_atoms_helper.cpp	Disable autoset_magmom under symmetry=1 to preserve symmetric nonmagnetic initial states.
source/source_cell/module_symmetry/test/symmetry_rotation_spin_test.cpp	Add unit tests for SU(2) / Pauli-vector rotation consistency.
source/source_cell/module_symmetry/test/symmetry_rho_soc_test.cpp	Add unit test for rhog_symmetry_nspin4 invariance/idempotence.
source/source_cell/module_symmetry/test/CMakeLists.txt	Register the new symmetry spin-rotation and SOC rho tests.
source/source_cell/module_symmetry/symmetry.h	Add Shubnikov-group storage, SOC density-symmetry op enumeration, and SOC rhog symmetrization API.
source/source_cell/module_symmetry/symmetry_rotation_spin.h	New SU(2) / spin-vector rotation utility header for SOC symmetry.
source/source_cell/module_symmetry/symmetry_rotation_spin.cpp	Implement SU(2) construction and spin-vector rotation helpers.
source/source_cell/module_symmetry/symm_rho.cpp	Refactor FFT-grid grouping and add rhog_symmetry_nspin4 implementation for SOC spin density.
source/source_cell/module_symmetry/symm_magnetic.cpp	Implement SOC magnetic group restriction and antiunitary coset extraction; add density op enumeration.
source/source_cell/module_symmetry/symm_analysis.cpp	Invoke SOC magnetic-group restriction during symmetry analysis when nspin=4.
source/source_cell/module_symmetry/CMakeLists.txt	Build the new spin-rotation utility into the symmetry library.
source/source_cell/k_vector_utils.cpp	For magnetic nspin=4, fold k-points using explicit Shubnikov antiunitary elements instead of generic -k doubling.
docs/advanced/input_files/input-main.md	Clarify symmetry=1 behavior for magnetic initial structures.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[mohanchen]

LGTM

[mohanchen]

This is an important PR to improve the quality of ABACUS code. Thanks for your contribution.

[Growl1234]

Unfortunately the test 15_KP_HSE_SOC_symm introduced here is failing in my PR #7712 due to deviation:

338: [ RUN      ] 15_KP_HSE_SOC_symm
338: [      OK  ]  etotref
338: [      OK  ]  etotperatomref
338: [      OK  ]  totalforceref
338: [WARNING   ]  totalstressref cal=20909.52018600 ref=20903.56145800 deviation=-5.95872800
338: [      OK  ]  pointgroupref
338: [      OK  ]  spacegroupref
338: [      OK  ]  nksibzref
338: [      OK  ]  magpointgroupref
338: [----------] Time elapsed: 82.419 seconds

I can confirm this failure has nothing to do with my changes, so it most likely indicates that the implementation in this PR has numerical stability issues.

[Growl1234]

Moreover it introduced many Global dependencies which should be cleaned up.

[maki49]

Unfortunately the test 15_KP_HSE_SOC_symm introduced here is failing in my PR #7712 due to deviation:
...
I can confirm this failure has nothing to do with my changes, so it most likely indicates that the implementation in this PR has numerical stability issues.

Sorry for interrupting your work. You can cherry-pick my commit 20700fb in #7715.

[Growl1234]

No worries. I can simply rebase my branch once #7715 is merged.