[aboys-cb]

This complete-branch draft has been split into six smaller draft PRs:

1. [1/6] Add NEP-spin training and model IO
2. [2/6] Add the NEP-spin potential to GPUMD
3. [3/6] Add TSPIN and Spin lattice integration support
4. [4/6] Add fixed-magnitude SIB spin dynamics
5. [5/6] Add variable-magnitude GLSD spin dynamics
6. [6/6] Add coupled Spin FIRE relaxation

The original spin3-refactor branch remains at b7d58c136fa63203bf74a2b5959b892593553d05. Please use the six drafts for current scope, dependencies, incremental diffs and validation results. Closing this umbrella draft keeps the review in the split series.

Previous complete-branch description (historical)

Summary

Add spin-dependent NEP training and spin–lattice dynamics to GPUMD. A single learned energy supplies atomic forces, magnetic forces and virials, so magnetic reference data can be fitted and the exported potential used for spin and coupled spin–lattice simulations.

This is a draft for upstream review of the model interface, shared-code changes and validation coverage. Head: MagTheoryLab:spin3-refactor (076511ffbf2f979a9663341d3f2c36ac812960fa); base: master (30a6db02e36494b8bba71c9fa1d1a68627604961). The diff contains 171 files, +34,109/−490 lines, including documentation, tests and frozen numerical references.

Local follow-up reviewed on 2026-10-26 — not pushed

The GitHub PR head is still 076511ffbf2f979a9663341d3f2c36ac812960fa. The following review and validation apply to local candidate b7d58c136fa63203bf74a2b5959b892593553d05, which includes upstream 04bd53510707415dee2a07f839b04262808834dc through merge 988893fc8993ef1815519d36587e9fd676027fb1. These local changes are not yet present in the PR diff. The PR remains a draft.

The candidate moves Spin force implementations and magnetic fields into src/force/nep_spin/, and isolates Spin input parsing, endpoint refresh, lattice restart and serialization in src/integrate/spin/. Ordinary NHC/MTTK implementation/header files, their ensemble documentation and the ordinary NEP small-box header are byte-identical to the incorporated upstream commit. Spin lattice subclasses reuse the upstream mechanical integration and own their continuation state. The public drivers retain model selection, validation and lifecycle hooks.

The final cleanup preserves the initial-temperature cache, including ordinary MTTK, while continuing to pass the per-step lattice target to Spin. Spin parsing and force-delta kernels were moved without algorithm changes; SIB/GLSD endpoint refresh remains after the second integration phase and before measurements, preserving the already-sampled mechanical-force increment. Spin MD, endpoint refresh and FIRE use the explicit Force::compute_spin entry point.

A focused final diff review found no new blocking issue in these entry points or the Spin isolation. Shared-code changes still include neighbor capacity/invalidation handling, reusable GPU allocation capacity, partition/region helper extraction and numerical helper templates; this is not a claim that all non-Spin files are unchanged. Make, HIP/WPE source lists and CMake include the new directories; only the CUDA builds below were executed.

Validation of local candidate b7d58c1

Sai job 1947761, V100-SXM2-32GB (up to four GPUs), CUDA 12.9.1, sm_70; final status COMPLETED / 0:0. Source/test/build input hashes (922 files) were unchanged through the run and have been checked against the local candidate. Existing regression manifests, tolerances and comparison rules were retained.

Check	Result
Full tests_regression/ suite against incorporated upstream	255 passed, 0 failed
Regression relations	25 passed, 0 failed, 0 skipped
Spin pytest: format, FIRE, SIB, TSPIN and lattice checkpoint lifecycle	78 passed
NHC / MTTK lattice restart, 1/4 GPUs	21 / 20 report groups passed
GLSD runtime	60 report groups passed
Block-format MD, 1/2/4 GPUs	41 cases passed
Independent runtime oracle, legacy / block format	24 / 24 cases passed
Production temperature-cache probe	Passed; the same probe linked against pre-fix production objects failed as expected
Make	Fresh gpumd and nep builds passed
Separate CMake build	gpumd passed
Final static checks	Upstream file equality, source provenance, relocated-path checks and git diff --check passed

Candidate Make gpumd SHA256: d33738c91cf9c092c83e27dd1e858f5deaed9c9439ed3b8111cc9aa3667133e7.

The earlier training/JIT/magnetic-loss validations below retain their original commit attribution; they were not rerun on this candidate. Lattice restart coverage does not imply complete SIB random-stream or TSPIN extended-state checkpoint reproducibility. HIP/WPE/Windows execution, CMake nep, and the earlier strict ordinary-NEP multi-GPU discrepancy remain outside this validation result. This final review rechecked the collected evidence; it did not launch another GPU run.

Changes in the currently pushed PR

• Add the Spin3 order/compression descriptor with shared training/runtime layout and production kernels, magnetic-environment and response masks, and optional ZBL. The default O3/C2/L2/SOC1 configuration has 55 magnetic descriptors and 97 total descriptors with the structural defaults.
• Select training with spin_version 1. Export the upstream named-block container using format_version 1, model nep_spin and a separate spin_version 1; reuse elemental energy_reference and restart IO. Retain compatible legacy readers and reject unknown versions or conflicting selectors.
• Fit magnetic forces, optional torques and grouped response data. Support separate parallel/perpendicular magnetic-force loss weights with explicit zero-moment handling. Check actual exported-model energy errors independently of centered mini-batch loss.
• Use deterministic reference descriptors for scaling. initial_para scales reference radial coefficients, defaults to 1 and accepts finite values in [0.1, 1]; it does not change the SNES initial search distribution. Prediction, restart and explicit scaler import preserve saved scalers.
• Add single-process multi-GPU training and Spin force evaluation with spatial ownership/halo environments and owner-only output collection.
• Add TSPIN, fixed-magnitude stochastic SIB and variable-magnitude GLSD integration; coupled atom/cell/spin FIRE relaxation; external fields with group/region selection; spin and magnetic-force output; GLSD noise-state and NHC/MTTK lattice-driver restart support.
• Reuse structural training evaluation and shared utilities, retain an independent frozen numerical oracle, and document current inputs, model format and supported combinations. Ordinary NEP remains the default without a Spin selector. spin_dof_type selects public response/supervision and does not freeze integrated spin coordinates.

Earlier validation of the pushed PR

CUDA checks used V100-SXM2-32GB GPUs, CUDA 12.9.1 and sm_70, with up to four GPUs. Original numerical tolerances were retained. Reproduction entry points and oracle policy are documented in developer/spin_validation.md which includes the GLSD/NHC/MTTK test entry points and their external prerequisites. Historical experiment reports are kept outside the source tree; user-facing units and continuation contracts are in the main documentation.

The following suites ran directly on c4dc508faccf417ca226b3516ed4f80391a6bb61, with source/test hashes checked against that commit. The current head only consolidates documentation; source code, tests and fixtures are unchanged. This documentation update passed a complete strict Sphinx HTML build (warnings treated as errors), stale-reference/local-link checks and git diff --check; GPU tests were not rerun for it:

Check	Result
Block-format MD, 1/2/4 GPUs	41/41 comparisons passed: format compatibility, reference-energy shifts, geometry/cutoff/partition variants, TSPIN/SIB/NPT trajectories, fields and migration; no componentwise tolerance exceedances
Magnetic-force loss split, 1/2/4 GPUs	Independent projection oracle and weighted objectives passed; 20 invalid inputs rejected; restart/reference/loss/energy/magnetic-force differences were zero across GPU counts
Training restart/scalers	Spin and ordinary NEP search-mean/elite restoration and scaler import passed
Integrators and FIRE	GLSD: 17 analytic/statistical cases and 60 runtime records, including 35 invalid-input checks; TSPIN/SIB standalone checks; FIRE in 1/4-GPU-visible configurations; 49 integrator pytest cases passed without skips
Native/JIT training, 1/2/4 GPUs	12/12 fixed-checkpoint comparisons passed for O1/C9 and O3/C1/C2/C3; specialized compilation confirmed without fallback; maximum exported energy difference 2.484e-8 eV/atom and force/magnetic-force/virial differences about 1e-6
MTTK/NHC restart	19 MTTK and 12 NHC step-by-step continuation comparisons passed on 1/4 GPUs, with 10/13 invalid-input checks and missing-state controls; NHC also passed six cross-GPU comparisons

Additional checks ran on 13bbe23ec1bd5f5e5fe4604bfc112d866027ce32. The only subsequent source-code changes are verified license comments in five shared files; all bytes after those headers are unchanged:

• CPU production model-format tests: 22 passed; complete Sphinx HTML build with warnings treated as errors: zero warnings.
• CUDA build of gpumd/nep and training-policy probe passed.
• Independent FP64 runtime oracle: 24 cases for each legacy/block format; maximum absolute error 3.978e-6 against the existing 2e-4 gate.
• Training/lifecycle checks passed for C1/C2/C3, masks, typewise cutoff, small cells, ZBL, response data, model IO, restart and energy differences. Ordinary NEP training/restart/prediction smoke checks passed.
• initial_para checks passed on 1/2/4 GPUs: default/explicit 1 agree, 0.5/0.1 affect scalers as expected, saved scalers persist and invalid values are rejected.
• Multi-structure training matched restart, reference energies, losses and predictions across 1/2/4 GPUs. Independently calculated energy RMSE was 0.04610498 eV/atom, consistent with logged 0.04610.

Known limits and open validation item

• A later fixed-state YIG inference check on c4dc508 passed strict 1-versus-4-GPU comparisons for Spin C2/C3 at 14,400 and 80,000 atoms. Ordinary NEP did not pass the same strict componentwise gates: at 80,000 atoms, maximum per-atom energy/force/virial differences were 1.43e-5 eV, 1.98e-4 eV/Å and 1.55e-4 eV. The cause and whether this is upstream behavior or a regression are not established. This remains an open validation item; ordinary-NEP multi-GPU equivalence is not claimed from that experiment.
• The Fe historical-binary integrator comparisons use legacy models; the separate block-format MD matrix covers the current container. This is not the full format × integrator cross-product.
• SIB random-stream continuation and arbitrary stateful modifiers are outside the documented GLSD/NHC/MTTK checkpoint guarantee. Unsupported species fine-tuning, charge/vdW combinations and versions are rejected.
• HIP and Windows were not validated. The earlier acceptance run below did not include a separate CMake build or the full repository regression suite; the local candidate section above now records those checks, with CMake limited to gpumd.
• No general speedup, improved fit accuracy, extrapolative magnetic behavior or transition-temperature result is claimed. The earlier fixed-budget YIG merge comparison did not show consistent energy-error improvement. The experimental magnetic-density/force JIT specialization was reverted after no end-to-end gain and is not included here; the native/JIT checks above concern the retained training JIT path.