Set Magnetic Moments

Group: Magnetism | Class: SetMagneticMomentsCard

What the card does

Write a consistent spin:R:3 representation to each input structure. Choose the moment source—existing values, an element map, or a constant magnitude—the scalar or vector output format, a reference axis, and the elements to which it applies. This foundational card does not branch into multiple magnetic orders; it prepares a clean, uniform starting state for downstream magnetic cards. The internal ASE initial_magmoms compatibility alias is kept in sync.

How this differs from Magnetic Order: Magnetic Order branches one parent structure into FM, AFM, and paramagnetic-like states. This card only standardizes moment values and representation. Use it once at the beginning when several downstream cards would otherwise repeat the same magmom_map and axis settings.

Example workflow

Scenario: repeated `magmom_map` settings drift out of sync across magnetic cards

Your workflow contains Magnetic Order → Small-Angle Spin Tilt → Spin Spiral, and each card repeats Fe:2.2,Co:1.7. Later you change Co to 1.5 in two cards but overlook the third. Part of the generated data silently retains the old Co magnitude, introducing an avoidable inconsistency into the labeled set.

Diagnosis: Define moment magnitudes once in a magnetic workflow. Put this card first, then select Existing initial magmoms in downstream cards instead of redefining the element map repeatedly.

Input: A magnetic crystal structure without spin or initial_magmoms.

Goal: Initialize vector moments along z, using 2.2 μB for Fe and 1.7 μB for Co, then reuse them throughout the downstream workflow.

Parameters:

Source = Map/default magnitude
Format = Non-collinear (vector)
Magmom Map = Fe:2.2,Co:1.7
Apply Elements = Fe,Co

Output: One structure labeled MagSet(map,vec) with a spin:R:3 array. Atomic positions and counts are unchanged.

How to verify that training-set quality improved:

Set all downstream magnetic cards to Existing initial magmoms and verify that moment magnitudes remain consistent.
If Co requires a specific reference magnitude, enter that value explicitly in Magmom Map and document its source.
If both scalar and vector workflows are needed, create one standardized branch for each format here instead of switching representations later.

When to add this card

Add it when:

Several magnetic cards repeat the same moment magnitudes, format, and axis.
Input structures mix scalar and vector moments and must be standardized.
You need one reference FM initialization without branching into several magnetic orders.

Do not add it when:

Only one magnetic card uses the settings → configuring that card directly may be simpler.
You need FM, AFM, and paramagnetic-like branches → use Magnetic Order.

Parameters

Moment source

Source（source）

str, default: 'Map/default magnitude'. Source from which moment values are obtained.

Options	Meaning
`Map/default magnitude`	Generate moments from `magmom_map` and `default_moment`; the input does not need existing moments.
`Existing initial magmoms`	Preserve existing moment values and convert only their representation; the input must contain `initial_magmoms`.
`Constant magnitude`	Assign one constant magnitude to all target elements; useful for a quick reference-value scan.

Magmom Map（magmom_map）

str, default: ''. Element-to-moment map such as Fe:2.2,Ni:0.6. JSON vectors such as {"Cr":[0,0,1.0]} are also accepted.

Use Element Dirs（use_element_dirs）

bool, default: False. Preserve vector directions supplied in magmom_map instead of projecting all mapped magnitudes onto Axis. Relevant only for vector output.

Default Moment（default_moment）

float, default: 0.0. Default magnitude for elements absent from magmom_map. A value of zero leaves unconfigured elements nonmagnetic.

Constant Moment（constant_moment）

float, default: 2.0. Magnitude assigned to every target element when Source = Constant magnitude.

Output representation

Format（format）

str, default: 'Non-collinear (vector)'. Choose Collinear (scalar) or Non-collinear (vector). Use vectors for downstream rotation, spiral, or canting operations.

Lift Scalar（lift_scalar）

bool, default: True. When converting scalar input to vector output, lift each signed scalar along Axis. Keep enabled for the usual scalar-to-vector conversion.

Axis（axis）

list[float] | tuple[float, float, float], default: (0.0, 0.0, 1.0). Reference direction for generated vectors and for lifting scalar moments, expressed as [x, y, z].

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

Element scope

Apply Elements（apply_elements）

str, default: ''. Comma-separated element symbols such as Fe,Co. Only listed elements receive moments; others are set to zero. Leave empty to include all elements.

Recommended presets

Convert existing moments to vectors without changing their magnitudes

{
  "class": "SetMagneticMomentsCard",
  "check_state": true,
  "source": "Existing initial magmoms",
  "format": "Non-collinear (vector)",
  "axis": [0.0, 0.0, 1.0],
  "magmom_map": "",
  "use_element_dirs": false,
  "default_moment": [0.0],
  "constant_moment": [2.0],
  "lift_scalar": true,
  "apply_elements": ""
}

Initialize from one element map at the start of a magnetic workflow

{
  "class": "SetMagneticMomentsCard",
  "check_state": true,
  "source": "Map/default magnitude",
  "format": "Non-collinear (vector)",
  "axis": [0.0, 0.0, 1.0],
  "magmom_map": "Fe:2.2,Co:1.7",
  "use_element_dirs": false,
  "default_moment": [0.0],
  "constant_moment": [2.0],
  "lift_scalar": true,
  "apply_elements": "Fe,Co"
}

Quick constant-magnitude exploration over reference values

{
  "class": "SetMagneticMomentsCard",
  "check_state": true,
  "source": "Constant magnitude",
  "format": "Non-collinear (vector)",
  "axis": [1.0, 0.0, 0.0],
  "magmom_map": "",
  "use_element_dirs": false,
  "default_moment": [0.0],
  "constant_moment": [3.0],
  "lift_scalar": true,
  "apply_elements": "Fe,Co,Ni"
}

Recommended combinations

Set Magnetic Moments → Magnetic Order: standardize representation, then generate FM, AFM, and paramagnetic-like orders.
Set Magnetic Moments → Small-Angle Spin Tilt: create consistent FM vector moments, then apply canting.
Set Magnetic Moments → Spin Spiral: establish consistent magnitudes, then generate spiral starting states.

Common questions

The output has no moments. Check that Source matches the input. Existing reads spin:R:3 first and falls back to legacy initial_magmoms only when spin is absent. Map/default requires a populated magmom_map or a nonzero, appropriate default_moment.

Scalar moments were not converted to vectors. Enable lift_scalar when Format is vector and the input contains only scalar values.

Some elements were unintentionally set to zero. Check whether a nonempty apply_elements list omitted the intended species.

Output labels

MagSet(existing,sca), MagSet(map,vec), or MagSet(const,vec), recording the moment source and output representation.

All exported outputs use spin:R:3. Scalar output requires a nonzero Axis, which is used to construct three-component spins without silently assuming a direction.

Reproducibility

Deterministic. The same input, Source, and parameters produce identical output.