Spin Spiral

Group: Magnetism | Class: SpinSpiralCard

What the card does

Write noncollinear initial_magmoms from a one-dimensional phase field, generating spin-spiral, planar-helix, and conical-spiral initial states over periods, phases, chiralities, and axial components. Control the spiral either by scanning its period L_D or by scanning the rotation gradient in degrees per Å.

\[\mathbf{m}(u)=\sqrt{1-m_z^2}\left[\cos\phi(u)\,\mathbf{e}_1+\sin\phi(u)\,\mathbf{e}_2\right] + m_z\,\hat{\mathbf{n}}\]
\[\phi(u)=s\cdot \frac{2\pi u}{L_D}+\phi_0,\qquad s\in\{-1,+1\}\]

Here m_z = m_parallel / |m| is the dimensionless component along the propagation axis. m_z = 0 gives a planar helix; nonzero m_z gives a conical spiral.

Important limitation: This card changes only the initial moment texture. If the target period is incompatible with the current periodic cell, enlarge the structure first.

Example workflow

Scenario: the predicted energy curve is wrong for spiral magnetic structures

You trained an NEP model with FM and AFM configurations. It performs acceptably for collinear orders, but for spiral states such as chiral helices in CrNb3S6 or MnSi, the shape of the energy curve is wrong and the period-dependent minimum differs from DFT by more than 30%.

Diagnosis: The model has never seen moments rotate continuously through space. FM and AFM examples cover only a few discrete directional patterns. Add spiral textures over several wave vectors so the model can learn the energy response E(q) across the relevant region of reciprocal space.

Input: A magnetic structure with known moment magnitudes, such as an MnSi cell with approximately 2.0 μB on Mn and propagation along [111].

Goal: Along [111], scan three periods (20, 30, and 40 Å), three global phases (0°, 30°, and 60°), a planar helix (mz=0), and both chiralities: 3 × 3 × 2 = 18 structures.

Parameters:

  • Propagation Axis = [1, 1, 1]

  • Spiral Parameter = Period (L_D)

  • Period Range = [20, 40, 10]

  • Phase Range = [0, 60, 30]

  • m_parallel Range = [0, 0, 0.1]

  • Chirality = Both

Output: 18 structures whose moments rotate along [111], labeled Helix(L=...,ph=...,mz=0,chi=...,ax=...).

How to verify that training-set quality improved:

  • After DFT labeling and retraining, compare the predicted E(q) curve with DFT energies for held-out spiral configurations.

  • If the position of the minimum remains inaccurate, densify period_range, for example to [10, 40, 5].

  • If conical spirals with mz != 0 are lower in energy than the planar helix, add mz = [0, 0.5, 0.1] to cover axial components.

  • Enable Period Filter when only periods commensurate with the current cell should be retained.

When to add this card

Add it when:

  • The system has a spiral or noncollinear magnetic state, as in a chiral magnet or skyrmion-host material.

  • The model fails to generalize to noncollinear magnetic order.

  • You need systematic coverage of magnetic excitations over wave vector q.

Do not add it when:

  • Only collinear order is relevant → Magnetic Order is sufficient.

  • You need local small-angle canting rather than a long-range spiral → use Small-Angle Spin Tilt.

  • The target period does not fit the current cell → build a suitable supercell first.

Parameters

Propagation axis and period

Axis（axis）

list[float] | tuple[float, float, float], default: (0.0, 0.0, 1.0). Direction along which the phase propagates. Each atom’s projected coordinate on this axis determines its phase. Format: [x, y, z].

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

Spiral Parameter Mode（spiral_parameter_mode）

str, default: 'Period (L_D)'. Use Period (L_D) when scanning known spiral periods or an E(q) curve. Use Angle gradient (deg/A) to control rotation directly in degrees per Å.

Period Range（period_range）

list[float] | tuple[float, float, float], default: (20.0, 40.0, 10.0). Period range in Å, expressed as [minimum, maximum, step].

  • Conservative: [20, 20, 5] (one period)

  • Balanced: [10, 40, 10] (four periods)

  • Exploratory: [4, 80, 4] (broad range)

Angle Gradient Range（angle_gradient_range）

list[float] | tuple[float, float, float], default: (18.0, 18.0, 1.0). Rotation-gradient range in degrees per Å, expressed as [minimum, maximum, step]. The gradient is 360 / L_D, so larger values correspond to shorter periods.

Layer Tolerance（layer_tolerance）

float, default: 0.05. Atoms whose projected coordinates differ by less than this tolerance are assigned to the same layer. Used only in Layer-locked mode.

Only Commensurate Periods（only_commensurate_periods）

bool, default: False. Retain only periods commensurate with the current periodic cell. The card searches the requested range and, if none fit, reports a suggested supercell multiplier.

Phase and spiral shape

Phase Range（phase_range）

list[float] | tuple[float, float, float], default (0.0, 0.0, 15.0). Global phase offsets as [min, max, step] in degrees.

  • Conservative: [0, 0, 15] (one phase)

  • Balanced: [0, 90, 30] (four phases)

  • Exploratory: [-180, 180, 30] (full phase range)

Mz（mz）

list[float] | tuple[float, float, float], default: (0.0, 0.0, 0.1). Normalized component along the propagation axis, in [-1, 1]. Zero gives a planar helix; a nonzero value gives a conical spiral.

  • Conservative: [0, 0, 0.1] (planar helix)

  • Balanced: [0, 0.5, 0.1] (moderate conical component)

  • Exploratory: [-0.9, 0.9, 0.1] (broad conical range)

Chirality（chirality）

str, default: 'Both'. Choose Clockwise, Counterclockwise, or Both. Both generates a pair of opposite chiralities for every other parameter combination.

Phase Mode（phase_mode）

str, default: 'Continuous by position'. In Continuous by position, each atom’s phase follows its own projected coordinate. In Layer-locked, projected positions are clustered into layers and all atoms in one layer share a phase.

Moment magnitudes

Magnitude Source（magnitude_source）

str, default 'Existing initial magmoms'. Choose Existing initial magmoms to reuse stored moments or Map/default magnitude to create magnitudes from an element map.

Magmom Map / Default Moment: used only in Map/default magnitude mode.

Magmom Map（magmom_map）

str, default ''. Provide known element-resolved local moments explicitly, for example Fe:2.2,Ni:0.6. Do not invent a prior for an unknown element through a default value.

Default Moment（default_moment）

float, default 0.0. Used only when an element is absent from magmom_map. List important magnetic elements explicitly; nonmagnetic elements should normally remain at 0.

Apply Elements（apply_elements）

str, default: ''. Restricts the spiral texture to selected elements. Leave empty to include all elements.

Output budget

Max Outputs（max_outputs）

int, default: 100. Periods, phases, chiralities, and axial components form a Cartesian product. Keep an initial E(q) scan to a few dozen points, then raise the cap only for a deliberate full-space study.

Recommended presets

Single-period planar-helix check (2 outputs; verify propagation and chirality)

{
  "class": "SpinSpiralCard",
  "check_state": true,
  "axis": [0.0, 0.0, 1.0],
  "spiral_parameter_mode": "Period (L_D)",
  "period_range": [20.0, 20.0, 10.0],
  "angle_gradient_range": [18.0, 18.0, 1.0],
  "phase_range": [0.0, 0.0, 15.0],
  "mz": [0.0, 0.0, 0.1],
  "chirality": "Both",
  "phase_mode": "Continuous by position",
  "layer_tolerance": [0.05],
  "only_commensurate_periods": false,
  "magnitude_source": "Existing initial magmoms",
  "magmom_map": "",
  "default_moment": [0.0],
  "apply_elements": "",
  "max_outputs": [16]
}

Multiple-period, multiple-phase spirals (~30 outputs for routine E(q) fitting)

{
  "class": "SpinSpiralCard",
  "check_state": true,
  "axis": [0.0, 0.0, 1.0],
  "spiral_parameter_mode": "Period (L_D)",
  "period_range": [10.0, 40.0, 10.0],
  "angle_gradient_range": [18.0, 18.0, 1.0],
  "phase_range": [0.0, 90.0, 30.0],
  "mz": [0.0, 0.3, 0.1],
  "chirality": "Both",
  "phase_mode": "Layer-locked",
  "layer_tolerance": [0.05],
  "only_commensurate_periods": false,
  "magnitude_source": "Existing initial magmoms",
  "magmom_map": "",
  "default_moment": [0.0],
  "apply_elements": "",
  "max_outputs": [100]
}

Full parameter-space scan (~500 outputs; conical states with commensurability filtering)

{
  "class": "SpinSpiralCard",
  "check_state": true,
  "axis": [0.0, 0.0, 1.0],
  "spiral_parameter_mode": "Angle gradient (deg/A)",
  "period_range": [20.0, 40.0, 10.0],
  "angle_gradient_range": [4.5, 90.0, 4.5],
  "phase_range": [-180.0, 180.0, 30.0],
  "mz": [0.0, 0.8, 0.2],
  "chirality": "Both",
  "phase_mode": "Layer-locked",
  "layer_tolerance": [0.08],
  "only_commensurate_periods": true,
  "magnitude_source": "Map/default magnitude",
  "magmom_map": "Fe:2.2",
  "default_moment": [0.0],
  "apply_elements": "",
  "max_outputs": [500]
}

Recommended combinations

  • Magnetic Order → Spin Spiral: establish local moment magnitudes, then scan spiral period and mz.

  • Set Magnetic Moments → Spin Spiral: standardize moment magnitudes, then impose the spiral.

  • Super Cell → Spin Spiral: enlarge the cell to accommodate longer periods, then enforce commensurability.

Common questions

No output is produced, or only the original input remains. All moment magnitudes may be zero; check magnitude_source and magmom_map. Alternatively, Period Filter found no commensurate period in the requested range; use the reported supercell suggestion.

Phase progression between layers is incorrect. Check Propagation Axis. In Phase Mode = Layer-locked, also tune layer_tolerance so physical layers are neither split nor merged.

Far more structures are produced than expected. period_range may use a fine step or mz may span too many values. Set max_outputs and validate a small scan before expanding it.

The meaning of conical-spiral mz is unclear. It is the dimensionless ratio m_parallel / |m|, not an absolute moment in μB, and must lie in [-1, 1].

Output labels

  • Helix(L=...,ph=...,mz=0,chi=...,ax=...): planar helix

  • Spiral(L=...,ph=...,mz=...,chi=...,ax=...)：conical spiral

  • Additional pm=layer,ltol=...: present only in layer-locked mode

All exported outputs use spin:R:3; an ASE initial_magmoms three-component vector alias is kept in sync internally.

Reproducibility

Deterministic. The same input structure and parameters produce identical output. The phase origin is fixed at the minimum projection along the propagation axis.