Magnetic-Moment Rotation (Magmom Rotation)

Group: Perturbation | Class: MagneticMomentRotationCard

What the card does

Apply random small-angle rotations to existing moments and optionally perturb their magnitudes. Multiple variants per input provide continuous local coverage around a reference spin direction.

\[\mathbf{m}'=\lambda\,\mathbf{R}(\hat{\mathbf{n}},\theta)\,\mathbf{m},\quad \lambda\in[f_{\min},f_{\max}]\]

Scope: This card only rotates and rescales moments. It neither changes atomic geometry nor defines a new magnetic order, and it requires existing initial_magmoms.

Example workflow

Scenario: model errors rise sharply when spin directions fluctuate during MD

You trained a magnetic NEP model using only perfectly aligned moments: parallel in FM states and exactly reversed in AFM states. Static predictions are accurate, but in finite-temperature MD a 5–10° thermal deflection of local moments doubles the force error.

Diagnosis: The training set covers only isolated points in moment-direction space, forcing interpolation gaps to behave like extrapolation. Add small-angle samples around each reference state so the model learns a continuous neighborhood of spin orientations.

Input: A magnetic structure with initial_magmoms, typically produced by Magnetic Order or Set Magnetic Moments.

Goal: Generate five variants per input with rotations up to 10° and magnitude scaling of ±5%, covering a local neighborhood around each reference direction.

Parameters:

  • Max Angle = 10.0

  • Num Structures = 5

  • Enable Disturb Magnitude and set Magnitude Factor to [0.95, 1.05].

Output: Five structures per input. Moment directions are randomly deflected by 0–10°, magnitudes are scaled to 95–105%, and atomic positions are unchanged.

How to verify that training-set quality improved:

  • After DFT labeling and retraining, rerun the finite-temperature validation and check whether force MAE remains stable under directional fluctuations.

  • If directional sensitivity remains, increase Max Angle to 15–20° or increase Num Structures, then re-evaluate held-out angular slices.

  • If perturbing a particular species produces implausible moments, use Elements to restrict the operation to the intended magnetic sublattice.

When to add this card

Add it when:

  • The training set contains only fixed magnetic directions and the model is sensitive to directional fluctuations.

  • Finite-temperature MD or spin dynamics requires continuous directional coverage.

  • The upstream moments are trusted and only local sampling around them is needed.

Do not add it when:

  • The input has no moments → use Set Magnetic Moments or Magnetic Order first.

  • You need broad angular coverage of 40° or more → use a deterministic Small-Angle Spin Tilt scan.

  • Only magnitude variation is needed → choose a workflow that does not introduce unnecessary rotations.

Parameters

Elements（elements）

str, default: ''. Comma-separated symbols such as Fe,Co. Only listed elements are rotated and rescaled; leave empty to include all atoms with nonzero moments.

Max Angle（max_angle）

float, default: 10.0. Maximum rotation angle in degrees. Each rotation angle is sampled uniformly from [0, max_angle].

  • Conservative: 2–5° (verify that directional augmentation is useful)

  • Balanced: 8–15° (routine finite-temperature coverage)

  • Exploratory: 20° or more (broad angular coverage; inspect carefully)

Num Structures（num_structures）

int, default: 5. Number of rotated variants per input frame. Use 5–10 for lightweight augmentation and 10–30 for routine coverage. For more than 30, follow with representative filtering.

Lift Scalar（lift_scalar）

bool, default: True. Lift collinear scalar moments to vectors along Axis before rotation. This must be enabled when scalar input is to be rotated.

Axis（axis）

list[float] | tuple[float, float, float], default: (0.0, 0.0, 1.0). Reference direction used by lift_scalar. It does not alter the initial direction of vector-valued input moments.

Used by modes that depend on a direction, layering, a surface, or vector initialization.

Disturb Magnitude（disturb_magnitude）

bool, default: True. Randomly rescale moment magnitudes while rotating them.

Magnitude Factor（magnitude_factor）

list[float] | tuple[float, float], default: (0.95, 1.05). Magnitude scale-factor range expressed as [minimum, maximum].

  • Conservative: [0.98, 1.02]

  • Balanced: [0.95, 1.05]

  • Exploratory: [0.85, 1.15]

Use Seed（use_seed）

bool, default: False. Enable with a fixed seed for reproducibility. Use it for controlled comparisons; leave it off during exploration.

Seed（seed）

int, default: 0. Random seed.

Active only when use_seed=True.

Recommended presets

Directional-perturbation check (5 outputs per frame)

{
  "class": "MagneticMomentRotationCard",
  "check_state": true,
  "elements": "",
  "max_angle": [5.0],
  "num_structures": [5],
  "lift_scalar": true,
  "axis": [0.0, 0.0, 1.0],
  "disturb_magnitude": false,
  "magnitude_factor": [0.95, 1.05],
  "use_seed": false,
  "seed": [0]
}

Routine direction-and-magnitude coverage (10 outputs per frame; suitable for finite-temperature MD)

{
  "class": "MagneticMomentRotationCard",
  "check_state": true,
  "elements": "",
  "max_angle": [10.0],
  "num_structures": [10],
  "lift_scalar": true,
  "axis": [0.0, 0.0, 1.0],
  "disturb_magnitude": true,
  "magnitude_factor": [0.95, 1.05],
  "use_seed": true,
  "seed": [42]
}

Broad angular exploration (30 reproducible outputs per frame)

{
  "class": "MagneticMomentRotationCard",
  "check_state": true,
  "elements": "Fe,Co",
  "max_angle": [25.0],
  "num_structures": [30],
  "lift_scalar": true,
  "axis": [0.0, 0.0, 1.0],
  "disturb_magnitude": true,
  "magnitude_factor": [0.85, 1.15],
  "use_seed": true,
  "seed": [42]
}

Recommended combinations

  • Magnetic Order → Magmom Rotation: generate FM/AFM reference states, then sample their directional neighborhoods.

  • Set Magnetic Moments → Magmom Rotation: standardize the moment representation, then rotate.

  • Magmom Rotation → FPS Filter: select representative samples after generating many variants.

Common questions

The output is unchanged. Confirm that the input has initial_magmoms, enable Lift Scalar for scalar moments, and ensure Max Angle is nonzero.

All output moments are zero. Elements may exclude every magnetic species, or the magnitude-factor range may include zero. Correct the element scope and scaling interval.

Results differ between runs. Enable Use Seed and fix Seed for reproducibility.

Output labels

  • MMR(a=10.0,s=0.95-1.05): vector rotation with magnitude perturbation

  • MMS(s=0.95-1.05): magnitude scaling only, when the rotation angle is zero or vector input is unavailable

All exported outputs use spin:R:3. Existing moments are read from spin first, with legacy initial_magmoms accepted only when spin is absent.

Reproducibility

Enable use_seed and fix seed to reproduce the same result for the same input. Each random axis and angle is determined jointly by the seed and structure index.