Folded Helix

Group: Magnetism | Class: FoldedHelixCard

What the card does

Construct a symmetric folded-helix magnetic-moment texture on discrete atomic layers. Moments are confined to the plane normal to plane_normal. Along layer_axis, they rotate by a fixed angle from one layer to the next during the first half-period, then reverse by the same increment after the turning layer. The result is a triangular phase profile that rotates in one direction and folds back at the midpoint.

\[\begin{split}s(k)=\begin{cases}k,&0\le k\le h\\2h-k,&h\lt k\lt2h\end{cases}\end{split}\]
\[\phi(k)=\phi_0+\sigma\cdot s(k)\cdot\Delta\phi\]

With the default half_period_mode = Auto from layer count, the card derives a folded period from the detected layers so that the phase closes from the first layer to the last.

How this differs from Spin Spiral: Spin Spiral rotates continuously and in one direction along its propagation axis. This card creates a layer-discrete texture that advances and then folds back, making it better suited to two-dimensional magnets, heterostructure interfaces, and mirror-symmetric moment distributions.

Example workflow

Scenario: a layered antiferromagnetic model fails on nonuniform spin textures

Suppose you trained a model for a layered magnet such as bilayer CrI3. Its training data are ferromagnetic within each layer and antiferromagnetic between layers: perfectly uniform magnetic order. Under an applied electric field, however, the top-layer moments may tilt by 15° while the bottom-layer moments tilt by −15°. This is a nonmonotonic, layer-dependent spin texture that the model has never learned.

Diagnosis: Spin variation in the training set is monotonic: moments are either aligned or alternate between opposite directions. The model has never seen a texture whose direction rotates away and then returns. Generate layer-discrete folded helices so the model can learn the energy surface associated with nonuniform moment distributions across layers.

Input: A layered magnetic structure with initial_magmoms, or a structure for which moment magnitudes can be supplied with magnitude_source = Map/default magnitude.

Goal: Let automatic mode adapt to the detected layer count and generate three interlayer rotation angles (15°, 30°, and 45°), four global phases (0°, 30°, 60°, and 90°), and two chirality sequences, for a total of 3 × 4 × 2 = 24 folded-helix configurations.

Parameters:

  • Layer Axis = [0, 0, 1] (identify layers along z)

  • Plane Normal = [0, 0, 1] (rotate moments in the xy plane)

  • Half-Period Mode = Auto from layer count

  • Angle Step Range = [15, 45, 15]

  • Phase Range = [0, 90, 30]

  • Sequence = Both

Output: 24 structures whose moments fold back layer by layer in the xy plane, labeled FoldedHelix(h=...,da=...,ph=...,seq=...,ax=...,pn=...).

How to verify that training-set quality improved:

  • After retraining, evaluate several test configurations with different interlayer angles. Their energy ordering should be physically reasonable for the target system—for example, angles near its preferred FM alignment should be lower than strongly misaligned states.

  • Inspect several outputs: layer 0 should start at the global phase, the middle layer should reach the largest rotation, and the top layer should return close to the global phase.

  • If automatic mode chooses an unsuitable half-period—for example, h=4 for a ten-layer structure—switch to manual mode and set half_period_layers explicitly.

When to add this card

Add it when:

  • A layered magnet, such as a van der Waals magnet, heterostructure, or superlattice, needs a nonmonotonic layer-dependent moment texture.

  • You want a mirror-symmetric spin distribution whose two half-periods reflect one another.

  • Atoms in the same layer should share one moment direction; layer locking is built in.

Do not add it when:

  • You need a conventional one-way propagating spiral → use Spin Spiral.

  • You need a phase that varies continuously with position rather than by layer → use the continuous mode of Spin Spiral.

  • The structure is not layered, so a layer-based texture has no physical meaning.

Parameters

Layer definition

Layer Axis（layer_axis）

list[float] | tuple[float, float, float], default: (0.0, 0.0, 1.0). Direction onto which atomic positions are projected to identify layers, expressed as [x, y, z].

Plane Normal（plane_normal）

list[float] | tuple[float, float, float], default: (0.0, 0.0, 1.0). Normal vector of the plane in which moments rotate. For example, [0, 0, 1] constrains them to the xy plane.

Layer Tolerance（layer_tolerance）

float, default: 0.05. Atoms whose projected coordinates differ by no more than this tolerance are assigned to the same layer. Unit: Å.

  • Conservative: 0.01 (strict layer separation)

  • Balanced: 0.03–0.10 (allows modest intralayer rumpling)

  • Increase the tolerance if atoms within a layer show appreciable rumpling.

Half-period control

Half Period Mode（half_period_mode）

str, default: 'Auto from layer count'. Auto from layer count derives a half-period from the detected layers and closes the phase between the first and last layers; this is recommended in most cases. Manual scans the range set by half_period_layers and is useful for comparing different folded periods.

Half Period Layers（half_period_layers）

list[int] | tuple[int, int, int], default: (2, 4, 1). Used only in manual mode. Expressed as [minimum, maximum, step], it scans the number of layer intervals in one half-period.

  • Conservative: [2, 2, 1] (shortest fold)

  • Balanced: [2, 6, 1]

  • Exploratory: [4, 12, 2]

Rotation parameters

Angle Step Range（angle_step_range）

list[float] | tuple[float, float, float], default: (15.0, 45.0, 15.0). In-plane rotation between adjacent layers, in degrees, expressed as [minimum, maximum, step].

  • Conservative: [5, 15, 5] (small rotations)

  • Balanced: [15, 45, 15] (moderate rotations)

  • Exploratory: [30, 90, 15] (large rotations)

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]

  • Balanced: [0, 90, 30]

  • Exploratory: [-180, 180, 30]

Sequence Mode（sequence_mode）

str, default: 'Clockwise then counterclockwise'. Clockwise then counterclockwise uses clockwise rotation in the first half-period and counterclockwise rotation in the second. Counterclockwise then clockwise reverses that order. Both generates both sequences.

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 folded texture to selected elements. Leave empty to include all elements.

Output budget

Max Outputs（max_outputs）

int, default: 100. Half-periods, angles, phases, and chirality sequences multiply the output count. Start with a few dozen structures to verify layer detection and phase conventions before scaling up to a research scan.

Recommended presets

Single-fold automatic-mode check (~2 outputs; verify layers and directions first)

{
  "class": "FoldedHelixCard",
  "check_state": true,
  "layer_axis": [0.0, 0.0, 1.0],
  "plane_normal": [0.0, 0.0, 1.0],
  "layer_tolerance": [0.03],
  "half_period_mode": "Auto from layer count",
  "half_period_layers": [2, 2, 1],
  "angle_step_range": [10.0, 10.0, 5.0],
  "phase_range": [0.0, 0.0, 15.0],
  "sequence_mode": "Clockwise then counterclockwise",
  "magnitude_source": "Existing initial magmoms",
  "magmom_map": "",
  "default_moment": [0.0],
  "apply_elements": "",
  "max_outputs": [16]
}

Routine coverage of several rotations and phases (~24 outputs; suitable for layered-magnet training)

{
  "class": "FoldedHelixCard",
  "check_state": true,
  "layer_axis": [0.0, 0.0, 1.0],
  "plane_normal": [0.0, 0.0, 1.0],
  "layer_tolerance": [0.05],
  "half_period_mode": "Auto from layer count",
  "half_period_layers": [2, 6, 1],
  "angle_step_range": [15.0, 45.0, 15.0],
  "phase_range": [0.0, 90.0, 30.0],
  "sequence_mode": "Both",
  "magnitude_source": "Existing initial magmoms",
  "magmom_map": "",
  "default_moment": [0.0],
  "apply_elements": "",
  "max_outputs": [100]
}

Manual multiple-period, full-phase exploration (~500 outputs; research scale)

{
  "class": "FoldedHelixCard",
  "check_state": true,
  "layer_axis": [0.0, 0.0, 1.0],
  "plane_normal": [0.0, 0.0, 1.0],
  "layer_tolerance": [0.10],
  "half_period_mode": "Manual",
  "half_period_layers": [4, 12, 2],
  "angle_step_range": [30.0, 90.0, 15.0],
  "phase_range": [-180.0, 180.0, 30.0],
  "sequence_mode": "Both",
  "magnitude_source": "Map/default magnitude",
  "magmom_map": "Fe:2.2",
  "default_moment": [0.0],
  "apply_elements": "",
  "max_outputs": [500]
}

Recommended combinations

  • Magnetic Order → Folded Helix: establish local FM/AFM moment magnitudes, then rotate them in a folded layer pattern.

  • Set Magnetic Moments → Folded Helix: assign element-specific magnitudes manually, then generate the folded texture.

  • Group Label → Folded Helix: label groups first, then apply the fold to a selected sublattice.

Common questions

Only the original input is returned. All moment magnitudes are zero. Check magnitude_source and magmom_map. A fold is undefined for a one-layer structure; at least two layers are required.

Layer detection is incorrect. Check the direction of layer_axis, then adjust layer_tolerance: a value that is too small splits one physical layer, while a value that is too large merges neighboring layers.

The automatic half-period is too short or too long. Automatic mode uses (number of layers - 1) // 2. For an even number of layers, if you need a particular layer to be the turning peak, switch to manual mode and set half_period_layers.

The output phase does not appear to fold. With very few layers, such as three, the triangular profile is difficult to see. A structure with at least six layers makes the fold clearer.

Output labels

  • FoldedHelix(h=...,da=...,ph=...,seq=...,ax=...,pn=...)

    • h: number of layer intervals in one half-period

    • da: interlayer rotation angle

    • ph: global phase

    • seq: chirality sequence (cw-ccw or ccw-cw)

    • ax: layer-axis label

    • pn: rotation-plane-normal label

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

Reproducibility

Deterministic. Identical input structures and parameters produce identical output. The layer origin is fixed at the smallest projected coordinate along layer_axis.