设置磁矩（Set Magnetic Moments）

Group: Magnetism | Class: SetMagneticMomentsCard

功能说明

把输入结构写成统一的 initial_magmoms 表示。选择磁矩来源（已有磁矩 / 元素映射 / 常数幅值）、输出格式（标量 / 向量）、参考轴方向和生效元素范围。这是一张基础层卡片——不生成多磁序分支，只为后续磁性卡片提供干净、统一的初始磁矩。

和 Magnetic Order 的区别： Magnetic Order 从一个母相出发生成 FM+AFM+PM 多分支。本卡只标准化磁矩格式，不创建新磁序。如果你的流程里多张磁性卡都在重复配 magmom_map 和 axis，用本卡统一初始化一次可以消除重复。

操作示例

场景：多张磁性卡各自配 magmom_map，配错了一处

你的训练流水线里有 Magnetic Order → Small-Angle Spin Tilt → Spin Spiral 三张磁性卡。每张卡都有一个 magmom_map 输入框，你填了三遍 Fe:2.2,Co:1.7。两周后改 Co 的磁矩为 1.5，只改了两张卡，第三张忘了——生成的数据里 Co 的磁矩默默用了旧值。训练出来的模型在含 Co 的构型上能量系统性偏高。

诊断思路： 磁性流水线里，磁矩幅值的定义应该只在一处。用本卡在最前面做一次统一初始化，后续磁性卡全部选 “Existing initial magmoms” 模式，不再各自定义 magmom_map。

输入： 一个磁性晶体结构，还没写 initial_magmoms

目标： 统一写入向量格式的初始磁矩，Fe 取 2.2 μB，Co 取 1.7 μB，沿 z 轴，后续卡片全部复用

参数设置：

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

输出： 1 个结构，带 MagSet(map,vec) 标签和 initial_magmoms 数组。原子位置和数量不变。

怎么验证训练集质量改善：

后续磁性卡全部切到 “Existing initial magmoms”，检查输出磁矩幅值是否一致
如果 Co 的磁矩需要精确到实验值，直接用 Magmom Map 的精确定义
如果后续要同时跑标量和向量流程，分别用本卡输出两种格式的版本，而不是在后面卡片里切换

什么时候加这张卡、什么时候不加

加：

流水线里多张磁性卡都在重复配置磁矩幅值、格式、axis
输入结构的磁矩格式不统一（有的标量有的向量），需要标准化
只想初始化参考 FM 磁矩，不想生成多磁序分支

不加：

只有一张磁性卡且不共享磁矩配置 → 直接在目标卡上配也可以
需要一次性生成 FM/AFM/PM 多磁序 → 用 Magnetic Order 一步完成

参数说明

磁矩来源

Source（source）

str，默认 'Map/default magnitude'。磁矩从哪里来。

选项	含义
`Map/default magnitude`	用 `magmom_map` / `default_moment` 生成。输入不需要已有磁矩
`Existing initial magmoms`	保留输入已有的磁矩，只做格式转换。输入需要已有 `initial_magmoms`
`Constant magnitude`	所有目标元素统一用一个常数幅值，适合快速扫参考值

Magmom Map（magmom_map）

str，默认 ''。元素到磁矩的映射，格式如 Fe:2.2,Ni:0.6，也可用 JSON 向量如 {"Cr":[0,0,1.0]}。

Use Element Dirs（use_element_dirs）

bool，默认 False。勾选后 magmom_map 中提供的向量方向会被保留，而不是统一投到 Axis。仅向量格式下有意义。

Default Moment（default_moment）

float，默认 0.0。magmom_map 未命中元素的默认幅值。设 0 则不给未配置元素写磁矩。

Constant Moment（constant_moment）

float，默认 2.0。Source = Constant magnitude 时所有目标元素的统一幅值。

输出格式

Format（format）

str，默认 'Non-collinear (vector)'。Collinear (scalar) 或 Non-collinear (vector)。后续要做旋转、螺旋、canting 时优先选向量格式。

Lift Scalar（lift_scalar）

bool，默认 True。输入是标量且目标格式是向量时，是否沿 Axis 抬升。通常保持开启。

Axis（axis）

list[float] | tuple[float, float, float]，默认 (0.0, 0.0, 1.0)。向量输出的参考方向、标量抬升的方向，格式为 [x, y, z]。

生效条件：涉及方向、分层、表面或向量初始化的模式都会使用。

元素范围

Apply Elements（apply_elements）

str，默认 ''。逗号分隔如 Fe,Co，只对列出的元素写磁矩，其余写 0。留空则全部生效。

常见问题

输出没有磁矩。 检查 Source 模式是否匹配输入。Existing 模式要求输入已有 initial_magmoms。Map/default 需要填写 magmom_map 或合理的 default_moment。

标量磁矩没变成向量。 Lift Scalar 没开，且 Format 选了向量但输入只有标量。开启 lift_scalar。

某些元素磁矩被意外清零。 检查 apply_elements 是否为非空且遗漏了目标元素。

输出标签

MagSet(existing,sca) / MagSet(map,vec) / MagSet(const,vec) 等：标记磁矩来源和输出格式

所有输出写入 initial_magmoms 数组。

可复现性

无随机性。相同输入、相同 Source 和相同参数 → 严格一致输出。