Small-Angle Spin Tilt

Group: Magnetism | Class: SmallAngleSpinTiltCard

What the card does

Apply deterministic small-angle canting to selected atoms, an entire magnetic order, explicit atom pairs, or two labeled groups. Pair modes generate opposite-chirality partners with positive and negative S_i × S_j, which is useful for DMI training. Global tilt scans collective rotation, for example along an approximate field-driven path.

\[\hat{\mathbf{m}}(\theta)=\cos\theta\,\hat{\mathbf{m}}_0+\sin\theta\,\hat{\mathbf{t}}\]

\[\theta_L=+\theta/2,\qquad \theta_R=-\theta/2\]

关键限制： 这是一张确定性卡片——没有随机采样。每个角度和每个目标都会生成确定性的输出。需要随机方向扰动时用 Magmom Rotation。缺少磁矩、目标原子、有效 pair 或 group 时会明确报错，不会返回原结构或只返回 reference 冒充完成。

Example workflow

Scenario: a model predicts the wrong sign for chirality-dependent energy differences in a DMI system

You trained an NEP model for a noncentrosymmetric magnet using only collinear FM and AFM configurations. Its symmetric exchange behavior is reasonable, but it predicts the wrong sign for the energy difference between left- and right-handed spirals because the training data contain no information about DMI chirality.

Diagnosis: DMI depends on S_i × S_j. When every training pair is exactly parallel or antiparallel, that cross product is zero and its handedness cannot be learned. Add neighboring-spin pairs with small relative angles and include both signs as matched partners so the data expose the antisymmetric response.

Input: A bcc Fe structure with initial_magmoms, or an FM reference initialized with magnitude_source = Map/default magnitude.

Goal: For every first-neighbor Fe–Fe pair, generate paired chiralities at ±1°, 2°, 5°, and 10° to probe the small-angle DMI response.

Parameters:

Canting Mode = Atom pair canting
Pair Source = Auto by neighbor shell
Pair Shell = [1]
Angle List = 1,2,5,10
Tilt Signs = Both (+/- pair)
Magnitude Source = Map/default magnitude，Magmom Map = Fe:2.2

Output: Eight canted configurations per first-neighbor Fe–Fe pair: four angles times two chiralities. If four pairs are selected automatically, this gives about 32 outputs, or 33 with the reference state.

How to verify that training-set quality improved:

After DFT labeling and retraining, compare left- and right-handed spiral energy differences with DFT; both sign and trend should agree.
Inspect a paired output: the left moment should rotate by +theta/2 and the right by -theta/2, with the opposite sample reversing the chirality.
If DMI remains inaccurate, expand Angle List to 1,2,3,5,7,10,15 and evaluate a separate second-neighbor branch with Pair Shell = 2.
To study a particular bond, use Manual indices and specify the pair explicitly.

When to add this card

Add it when:

You are training a model for DMI or other chirality-dependent magnetic behavior.
You need deterministic, directly comparable small-angle samples rather than random rotations.
You need collective tilt states near a field-driven or metamagnetic pathway.
A simulation shows unphysical relative-angle oscillations for specific moment pairs.

Do not add it when:

You need random directional coverage → use Magmom Rotation.
You need fractional sign flips or an ordered-to-disordered gradient → use Spin Disorder.
You need a full magnetic-order reversal rather than local canting → use the AFM branch of Magnetic Order.
You need a continuous spatial spiral → use Spin Spiral.

Parameters

Tilt target

Canting Mode（canting_mode）

str, default: 'Single-spin tilt'.

Mode	Meaning	Best used for
`Single-spin tilt`	Tilt one selected atomic moment	Workflow validation or a specific site
`Global tilt`	Tilt all eligible moments by the same angle	Collective field-driven rotation or an approximate spin-flop path
`Atom pair canting`	Tilt the two atoms by `+θ/2` and `−θ/2`	Preferred for DMI training pairs
`Group pair canting`	Tilt two entire groups by `+θ/2` and `−θ/2`	Sublattice-level canting

Target Mode（target_mode）

str, default: 'First eligible atom'. Use the first eligible atom or a manual index for a focused check. Use All eligible for systematic site coverage, noting that it multiplies the output count by the number of targets.

Target Indices（target_indices）

str, default: ''. One-based atom indices to tilt, with ranges such as 1,3-5.

Used when target_mode selects manual indices.

Atom-pair targets

Pair Left Indices（pair_left_indices）

str, default: ''. In manual mode, one-based indices for the left atoms, paired position by position with the right list.

Used when pair_source selects manual indices.

Pair Right Indices（pair_right_indices）

str, default: ''. In manual mode, one-based indices for the right atoms, paired position by position with the left list.

Used when pair_source selects manual indices.

Pair Source（pair_source）

str, default: 'Manual indices'. Manual indices give controlled, auditable pairs. Automatic neighbor shells generate DMI or exchange-path samples in bulk, but their element and bond-direction filters must be checked.

Pair Shell（pair_shell）

int, default: 1. Neighbor shell in automatic mode: 1 for first neighbors, 2 for second neighbors.

Used when pair_source selects automatic neighbor search.

Pair Shell Tolerance（pair_shell_tolerance）

float, default: 0.05. Distance tolerance in Å used to cluster automatically detected neighbor shells.

Used when pair_source selects automatic neighbor search.

Pair Element Filter（pair_element_filter）

str, default: ''. Element-pair filter for automatic neighbors, such as Fe-Fe or Fe-Co. Match it to the interaction channel being studied.

Use when automatically generated pairs must be filtered by element.

Pair Group Filter（pair_group_filter）

str, default: ''. Group-pair filter for automatic neighbors, useful for layered AFM states, interfaces, or labeled sublattices. Do not use it without upstream group labels.

Use when automatically generated pairs must be filtered by group.

Bond Filter Mode（bond_filter_mode）

str, default: 'Any'. Any retains all candidate bonds. Near axis selects bonds close to a direction; Near plane selects bonds close to a plane, enabling in-plane and out-of-plane interaction channels to be separated.

Bond Filter Axis（bond_filter_axis）

list[float] | tuple[float, float, float], default: (0.0, 0.0, 1.0). Reference axis or plane normal for bond filtering. It must match the actual crystal orientation in an in-plane/out-of-plane DMI study.

Used when bond_filter_mode is not Any.

Bond Filter Tolerance（bond_filter_tolerance）

float, default: 20.0. Angular tolerance for bond-direction filtering. Too small may select no pairs; too large may mix distinct exchange paths.

Used when bond_filter_mode is not Any.

Group-pair mode

Group A（group_a）

str, default: 'A'. Label in arrays['group'] for the first group. The input must already contain group labels.

Used by group-pair, manual-group, or AFM-group modes.

Group B（group_b）

str, default: 'B'. Label in arrays['group'] for the second group. The input must already contain group labels.

Used by group-pair, manual-group, or AFM-group modes.

Angles and chirality

Angle List（angle_list）

str, default: '1,2,5,10'. Comma-separated tilt angles in degrees. The default is a practical small-angle starting set.

Tilt Signs（tilt_signs）

str, default: 'Positive only'. A +θ sample is enough for a local-response check. Matched ±θ samples are required to isolate chirality-odd contributions and are recommended for DMI data.

Include Reference（include_reference）

bool，默认 True。额外输出一帧未偏转的参考磁态，方便做 energy difference 对比。打开后 max_outputs 至少为 2，确保预算中还留有一帧真正的 canting 输出。

Moments and reference state

Magnitude Source（magnitude_source）

str, default 'Existing initial magmoms'. Reusing existing initial_magmoms is safest. Without moment input, construct magnitudes from magmom_map and default_moment; never replace known element moments with a generic default.

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.

Lift Scalar（lift_scalar）

bool, default True. Enable when scalar moments must be promoted to noncollinear vectors. Do not promote again when the input already contains directional information.

Axis（axis）

list[float] | tuple[float, float, float], default (0.0, 0.0, 1.0). This is a directional reference, not an ordinary scalar setting: changing it changes a layering direction, surface normal, or moment direction. Confirm the cell orientation and intended physical direction first.

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

Reference Direction（reference_direction）

list[float] | tuple[float, float, float], default: (1.0, 0.0, 0.0). Preferred transverse reference direction used to define the canting plane.

Apply Elements（apply_elements）

str, default: ''. Restricts target selection to specified elements. Leave empty to include all.

Output budget

Max Outputs（max_outputs）

int，默认 100。自动 pair、角度列表和正负手性会相乘放大输出数量。这个上限包含 reference；开启 include_reference 时至少设为 2。先用 20-100 检查 pair 选择是否合理，确认后再扩大到完整 DMI 扫描。

Recommended presets

Single-spin check (~5 outputs; validate the convention first)

{
  "class": "SmallAngleSpinTiltCard",
  "check_state": true,
  "canting_mode": "Single-spin tilt",
  "target_mode": "First eligible atom",
  "target_indices": "",
  "pair_left_indices": "",
  "pair_right_indices": "",
  "pair_source": "Manual indices",
  "pair_shell": [1],
  "pair_shell_tolerance": [0.05],
  "pair_element_filter": "",
  "pair_group_filter": "",
  "bond_filter_mode": "Any",
  "bond_filter_axis": [0.0, 0.0, 1.0],
  "bond_filter_tolerance": [20.0],
  "group_a": "A",
  "group_b": "B",
  "angle_list": "1,2,5,10",
  "tilt_signs": "Positive only",
  "include_reference": true,
  "magnitude_source": "Existing initial magmoms",
  "magmom_map": "",
  "default_moment": [0.0],
  "lift_scalar": true,
  "axis": [0.0, 0.0, 1.0],
  "reference_direction": [1.0, 0.0, 0.0],
  "apply_elements": "",
  "max_outputs": [16]
}

Neighbor-pair DMI set (~100 outputs; routine use)

{
  "class": "SmallAngleSpinTiltCard",
  "check_state": true,
  "canting_mode": "Atom pair canting",
  "target_mode": "First eligible atom",
  "target_indices": "",
  "pair_left_indices": "",
  "pair_right_indices": "",
  "pair_source": "Auto by neighbor shell",
  "pair_shell": [1],
  "pair_shell_tolerance": [0.05],
  "pair_element_filter": "",
  "pair_group_filter": "",
  "bond_filter_mode": "Any",
  "bond_filter_axis": [0.0, 0.0, 1.0],
  "bond_filter_tolerance": [20.0],
  "group_a": "A",
  "group_b": "B",
  "angle_list": "1,2,5,10",
  "tilt_signs": "Both (+/- pair)",
  "include_reference": true,
  "magnitude_source": "Existing initial magmoms",
  "magmom_map": "",
  "default_moment": [0.0],
  "lift_scalar": true,
  "axis": [0.0, 0.0, 1.0],
  "reference_direction": [1.0, 0.0, 0.0],
  "apply_elements": "",
  "max_outputs": [100]
}

Bond-direction and element-pair-resolved DMI scan (~500 outputs; research scale)

{
  "class": "SmallAngleSpinTiltCard",
  "check_state": true,
  "canting_mode": "Group pair canting",
  "target_mode": "First eligible atom",
  "target_indices": "",
  "pair_left_indices": "",
  "pair_right_indices": "",
  "pair_source": "Auto by neighbor shell",
  "pair_shell": [2],
  "pair_shell_tolerance": [0.1],
  "pair_element_filter": "Fe-Co",
  "pair_group_filter": "A-B",
  "bond_filter_mode": "In plane (normal)",
  "bond_filter_axis": [0.0, 0.0, 1.0],
  "bond_filter_tolerance": [15.0],
  "group_a": "A",
  "group_b": "B",
  "angle_list": "1,2,5,10,15",
  "tilt_signs": "Both (+/- pair)",
  "include_reference": false,
  "magnitude_source": "Map/default magnitude",
  "magmom_map": "Fe:2.2,Co:1.7",
  "default_moment": [0.5],
  "lift_scalar": true,
  "axis": [0.0, 0.0, 1.0],
  "reference_direction": [1.0, 0.0, 0.0],
  "apply_elements": "Fe,Co",
  "max_outputs": [500]
}

Recommended combinations

Set Magnetic Moments → Small-Angle Spin Tilt: standardize vector moments, then generate paired canting samples.
Magnetic Order → Small-Angle Spin Tilt: construct a reference magnetic order, then apply local canting.
Group Label → Magnetic Order → Small-Angle Spin Tilt: label sublattices, initialize their order, then use Group pair canting.

Common questions

提示没有可倾斜磁矩或目标原子。 Existing initial magmoms 要求输入已有非零磁矩；否则切换到 Map/default magnitude 并填写真实幅值。再检查 apply_elements、手动索引和目标模式是否把所有原子过滤掉了。卡片不会再用原结构代替 canting 输出。

提示没有有效 pair。 手动模式检查左右索引数量和磁矩是否非零；自动模式调整 pair_shell_tolerance——太大把不同壳层并到一起，太小把同一壳层拆开。再检查 pair_element_filter、pair_group_filter 和键方向筛选是否过紧。

group pair canting 报错。 输入需要 arrays['group']，而且 group_a 和 group_b 中都要有至少一个非零磁矩原子。可以用 Group Label 先生成坐标分组，但它不会自动识别化学子晶格。

The output count is larger than expected. Target Mode = All eligible atoms combined with Both (+/- pair) multiplies targets and signs. Set max_outputs or use First eligible atom for an initial check.

Output labels

SpinTiltRef: reference state when include_reference=true
SpinTilt(i=...,a=...,sg=...): single-spin tilt
SpinPair(i=...,j=...,a=...,sg=...): atom-pair canting
SpinPairG(A=...,B=...,a=...,sg=...)：group pair canting

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

Reproducibility

Deterministic. Identical inputs and parameters produce identical output. reference_direction is orthogonalized against the baseline moment direction in a deterministic way.