English | 简体中文

SpinMDKit

SpinMDKit is a format-extensible magnetic-moment post-processing framework for spin molecular dynamics. It streams large trajectories, calculates magnetic observables, exports analysis-ready time series, and renders three-dimensional spin-vector views. Extended XYZ trajectories are supported out of the box.

The project is intentionally small at its foundation: one explicit frame model, one schema-driven streaming reader, a tested Python API/CLI, and optional C++17 kernels. Version 1.0.0 establishes the stable base for a downloadable toolkit; future simulation formats can be added without changing the data, analysis, or visualization layers.

Install

Download a wheel from the Releases page and install it with pip:

python -m pip install spinmdkit-1.0.0-...whl

The base installation has one runtime dependency: NumPy. Plotting is a separate optional feature:

python -m pip install "spinmdkit[plot]"

Or build the C++17 extension from source:

git clone https://github.com/LYKD/spinmdkit.git
cd spinmdkit
python -m pip install ".[test]"
python -m pytest

The source build needs a C++17 compiler. A NumPy-only installation can be built without the native module when necessary:

SPINMDKIT_DISABLE_NATIVE=1 python -m pip install .

In PowerShell, set the option with $env:SPINMDKIT_DISABLE_NATIVE='1' before running pip. The native extension is optional; failure to compile it does not prevent the NumPy implementation from being installed.

Quick start

Inspect a GPUMD trajectory without loading it all into memory:

spinmdkit inspect trajectory.xyz --species U

Format selection is automatic by file suffix or explicit when needed:

spinmdkit formats
spinmdkit inspect trajectory.xyz --format extxyz --species U

Export net magnetization, local-moment magnitudes, magnetic-force norms, and the derived spin x mforce torque norm:

spinmdkit timeseries trajectory.xyz -o magnetic-timeseries.csv --species U

Export the numerical data and render the net Mx/My/Mz/|M| plus mean/minimum/maximum local-moment evolution in one command:

spinmdkit plot-moments trajectory.xyz --species U \
  --timestep 0.001 --sample-every 100 --time-offset 0.2 \
  --time-unit ps --moment-unit "μB" -o moment_time_evolution.png

This writes moment_time_evolution.csv beside the two-panel horizontal PNG. Here --sample-every is the number of MD steps between stored frames; --frame-stride is available when post-processing downsampling is also wanted. Use --time-source metadata --time-key Time when frame metadata already carries time values.

For an antiferromagnet, supply the sublattice signs explicitly. The pattern is repeated across the selected atoms only when its length divides their count:

spinmdkit timeseries trajectory.xyz -o afm.csv \
  --species U --sublattice-pattern "+--+"

Render one frame as three-dimensional colored arrows:

spinmdkit plot-frame trajectory.xyz -o frame-0.png \
  --frame 0 --species U --normalize

Select the complete upper U layer from the last frame and draw a 3D moment view beside its in-plane projection, with magnitude-scaled arrows and a numerical color range on the right:

spinmdkit plot-layer examples/top_layer_moments/trajectory.xyz \
  --frame -1 --species U --axis z --layer top \
  --arrow-scale 1.0 --position-unit "Å" --moment-unit "μB" \
  -o top_layer_moments.svg

Automatic edge-layer detection groups a plane from coordinate gaps rather than keeping only the atom at the exact maximum. A known plane can instead be selected with --coordinate Z --tolerance DZ. The projection follows the layer normal: an x layer uses the yz positions and (my, mz), a y layer uses xz and (mx, mz), and a z layer uses xy and (mx, my). See the complete bilingual top_layer_moments example.

Self-contained examples are stored one per directory. The complete time-axis, CSV, and two-panel workflow is documented in examples/moment_time_evolution. The eight-atom AFM example can be inspected with:

spinmdkit inspect examples/afm_frame/trajectory.xyz --species U \
  --sublattice-pattern "+--+" --json

Python API

from spinmdkit import iter_extxyz, summarize_frame

for frame in iter_extxyz("trajectory.xyz"):
    result = summarize_frame(frame, species="U")
    print(result["magnetization"], result["mean_moment_norm"])

Each Frame has species, positions, an optional cell, unmodified frame metadata, and named per-atom properties. The reader supports arbitrary Extended XYZ property schemas, including spin, mforce, and spin_velocity. It also accepts .xyz.gz streams.

Module boundaries

spinmdkit.data           validated frame objects; no file or plot logic
spinmdkit.io             reader contracts, format registry, and trajectory access
spinmdkit.io.readers     isolated input-format adapters, including Extended XYZ
spinmdkit.analysis       physical observables, spatial selections, and summaries
spinmdkit.kernels        NumPy/native compute backend boundary
spinmdkit.export         dependency-light CSV serializers
spinmdkit.visualization  optional plotting; imports Matplotlib on demand
spinmdkit.cli            thin command composition only

Dependencies point in one direction. In particular, io never imports analysis or plotting, and analysis never imports the CLI or Matplotlib. This keeps each layer independently testable and makes format, physics, or rendering bugs easier to isolate.

New formats implement the small TrajectoryReader contract and register a name plus file extensions. Every adapter yields the same format-neutral Frame, keeping downstream analysis and plotting independent of input syntax.

Scientific contract

• spin is the local magnetic-moment vector read from the trajectory.
• mforce remains a separately named magnetic-force-like output.
• torque is a derived quantity calculated as spin x mforce; it is not treated as an independent label.
• the Néel vector is calculated only from explicit +1/-1 sublattice signs.
• stress, virial, units, and sign conventions are preserved as source metadata. SpinMDKit does not silently convert them.
• values retain their source provenance and are not relabeled as reference data.

See Data model, Architecture, and Adding a reader for the design details.

License

SpinMDKit is distributed under the GNU General Public License version 3. Distributed modified or derivative works must remain under GPLv3, and object-code distributions must make the corresponding source available under the license terms. Proprietary relicensing requires separate permission from the relevant copyright holders.

This change does not retroactively revoke rights already granted for copies obtained under an earlier license.

Version policy

Versions change only after an explicit maintainer instruction. Commits, debugging sessions, CI runs, and feature additions never bump the version automatically. See VERSIONING.md.

Initial command surface

Command	Purpose
spinmdkit formats	List currently registered input adapters
spinmdkit inspect	Stream and summarize trajectory structure and ranges
spinmdkit timeseries	Export per-frame magnetic observables to CSV
spinmdkit plot-moments	Export CSV and render a horizontal two-panel moment history
spinmdkit plot-frame	Render a static 3D spin-vector image
spinmdkit plot-layer	Select one atomic layer and render magnitude-scaled moment arrows

Roadmap

1. Additional simulation formats and trajectory writers through isolated adapters.
2. Additional spatial, sublattice, and temperature-resolved magnetic observables.
3. Interactive and batch visualization pipelines.
4. Stable plugin interfaces for domain-specific analyses.
5. Benchmarks and scalable parallel readers for production trajectories.

Contributions and reproducible test cases are welcome. See CONTRIBUTING.md.