Skip to content

[3/6] Add TSPIN and Spin lattice integration support - #1853

Draft
aboys-cb wants to merge 6 commits into
brucefan1983:masterfrom
MagTheoryLab:codex/spin-3-tspin
Draft

aboys-cb wants to merge 6 commits into
brucefan1983:masterfrom
MagTheoryLab:codex/spin-3-tspin

Conversation

@aboys-cb

@aboys-cb aboys-cb commented Oct 26, 2026 •

Copy link
Copy Markdown
Contributor

Add Cartesian TSPIN dynamics with fixed-lattice and coupled NVT/NPT modes, element-wise spin masses, spin-velocity IO and lifecycle validation. Introduce the shared Spin integration hooks and Spin-specific NHC/MTTK lattice checkpoint classes.

Ordinary NHC/MTTK implementations remain byte-identical to upstream. The initial-temperature cache retains its upstream meaning while the per-step target is passed to Spin. No SIB or GLSD commands are accepted yet. Lattice checkpoints do not imply full TSPIN extended-state restart reproducibility.

Series and review scope

Part 3 of six, split from #1849. Depends on #1852.

Incremental diff for this part: parent → this commit.

This draft currently targets upstream master, so GitHub's Files changed also includes the preceding parts. After this part's prerequisites merge, rebase it onto the updated master to expose only this part in GitHub.

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

Validation

Validated production/test inputs for 6f657e7dd1c41492823833458a4be547f2be5643 on four NVIDIA V100 GPUs with CUDA 12.9.1; 1/2/4 GPUs where specified. Final documentation/ignore-only cleanup was checked separately. The publication base is c7e6340; its only change from the GPU-tested upstream base 04bd535 is doc/publications.bib, and documentation was rebuilt after adopting it. No numerical tolerance or oracle values were changed.

  • Fresh CUDA Make builds of gpumd and nep; 22 model-format tests.
  • Full upstream regression: 255/255 cases passed, 0 failed; 25/25 relations passed.
  • 28 integrator/lifecycle pytest cases; standalone TSPIN analytic one-step, NPT, parser, mask and restart checks; 35 runtime cases on 1/2/4 GPUs. A separately linked production-object probe passed the initial-temperature-cache and per-step Spin-target checks.
  • Strict Sphinx HTML build (-W --keep-going), Markdown links and git diff --check passed.

These are implementation/regression checks, not scientific fit-quality or performance claims. HIP, WPE and Windows execution are not covered by this validation.

Train and predict a spin-dependent NEP using the existing SNES lifecycle. Add shared Spin3 descriptors and derivatives, magnetic-force parallel/perpendicular supervision, torque and grouped-response losses, input validation, reference scaling, prediction, restart and versioned model IO.

The shared descriptor headers are introduced here for both consumers. GPUMD force dispatch and spin dynamics are not enabled in this PR.
Load exported NEP-spin models and evaluate energy, atomic forces, magnetic forces and the full virial in GPUMD. Add single-process multi-GPU evaluation, per-atom spin input/output and replication, fixed-spin restart output, and group/region magnetic fields.

The spin coordinates remain fixed under ordinary supported lattice integration. No spin integrator, spin velocity, or lattice-thermostat checkpoint state is introduced. Runtime and training reuse the descriptor kernels from part 1.
Add Cartesian TSPIN dynamics with fixed-lattice and coupled NVT/NPT modes, element-wise spin masses, spin-velocity IO and lifecycle validation. Introduce the shared Spin integration hooks and Spin-specific NHC/MTTK lattice checkpoint classes.

Ordinary NHC/MTTK implementations remain byte-identical to upstream. The initial-temperature cache retains its upstream meaning while the per-step target is passed to Spin. No SIB or GLSD commands are accepted yet. Lattice checkpoints do not imply full TSPIN extended-state restart reproducibility.
Reject flexible ZBL before parameter loading, retain universal ZBL,
and remove C++17-only syntax from the magnetic kernels and probes.
Consolidate overlapping training checks while retaining numerical,
restart, JIT and multi-GPU coverage.
Preserve the existing PR history while carrying prerequisite Spin fixes
and the reduced regression suites into this stage.
Preserve the existing PR history while carrying prerequisite Spin fixes
and the reduced regression suites into this stage.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant