GSFE Path）

Group: Defect | Class: StrictGSFEPathCard

What the card does

按显式晶面 hkl 和滑移方向 uvw 生成层错结构或未弛豫的广义层错（GSF）位移路径。卡片先在原子层之间放置切面，再把切面上方的原子作为一个整体沿面内方向移动；它只生成结构，不计算能量，也不做原子弛豫。

它不限定 fcc、(111) 面或某一种 Burgers 矢量，但输入必须已经按目标晶面定向：第三晶胞矢量要垂直于 plane_hkl，否则程序会直接报错。hkl 和 uvw 都是相对于当前晶胞基矢的指数，不会自动识别或重定向原始体相晶胞里的 (111)、[11-2] 等晶向。

滑移方向必须本来就在层错面内；若含有面外分量，卡片会报错，不会静默投影成另一个方向。若只是为了补充训练集，可以直接使用输出结构；若要从能量差换算 GSFE，还必须自行确认周期边界中有一个还是两个层错界面，并使用正确的界面面积和界面数。

Example workflow

Scenario: The GSFE peak is too low for a specified slip system

An fcc Ni NEP has good bulk and elastic response but strongly underestimates the (111)<112> GSFE peak. Random perturbations and surfaces do not replace systematic half-crystal displacement along that slip system.

Input: A periodic fcc111 slab-oriented cell, such as the fcc111 prototype from Crystal Prototype Builder.

目标： 沿当前 slab cell 的 (001) 面和面内 [100] 周期方向生成 0 到 1 个滑移向量的路径，步长 0.1；在这个特定定向晶胞里，(001) 对应原始 fcc 的 (111) 面。

Parameters:

plane_hkl = [0, 0, 1]
slip_uvw = [1, 0, 0]
displacement_range = [0.0, 1.0, 0.1]
displacement_unit = "fraction_of_vector"
cut_mode = "middle"

Output: Eleven unrelaxed fault structures labeled GSFE(hkl=001,uvw=100,d=...).

How to verify the improvement: Obtain DFT single points or consistently defined short relaxations, retrain, and rescan the same path. Compare peak height, local minima, and curve symmetry with DFT. If the peak improves but the curve remains jagged, refine the displacement step from 0.1 to 0.05.

Parameters

Fault plane (h k l)（plane_hkl）

Sequence[int]，默认 (0, 0, 1)。当前晶胞基矢下的 Miller 指数，定义层错面的法向；该法向必须平行于第三晶胞矢量。

Low-index planes are typical. In an fcc111-oriented slab cell, (001) denotes the original fcc (111) plane. (0,0,0) is invalid. A conventional cubic fcc cell with (111) does not satisfy the required slab orientation without reorientation.

Slip direction [u v w]（slip_uvw）

Sequence[int]，默认 (1, 0, 0)。当前晶胞基矢下的方向指数，真实滑移向量为 u*a + v*b + w*c。

方向必须位于 plane_hkl 面内；在晶格指数下等价于 h*u + k*v + l*w = 0。不满足时程序会报错，避免用户填写 [u v w]，实际却得到另一个投影方向。对于 fcc111 slab cell，可以用 [100]、[010] 或另一个面内方向；如果要扫特定 partial 位移，需要让当前晶胞的面内基矢或 Å 位移范围对应目标 Burgers 矢量。

Displacement range（displacement_range）

Sequence[float], default (0.0,1.0,0.5). Slip displacement scan as [start,stop,step].

如果 displacement_unit = "fraction_of_vector"，1.0 表示完整 slip_uvw 向量；如果单位是 angstrom，数值就是沿该方向的实际距离。起点和终点都包含在输出中，步长必须为正。GSFE 曲线通常需要至少 0.05–0.1 的分辨率；只做 smoke 时可以用 0、0.5、1.0 三个点快速确认几何没错。

Displacement unit（displacement_unit）

str, default "fraction_of_vector". Converts displacement_range values to physical displacements.

Options	Meaning	When to choose it
`fraction_of_vector`	位移 = 数值乘以 `slip_uvw` 向量	扫完整周期或按滑移向量分数描述路径
`angstrom`	位移 = 数值 Å，方向为 `slip_uvw` 的单位向量	Use a known physical displacement or a small interlayer probe

Cut position（cut_mode）

str, default "middle". Selects the cut that separates stationary and shifted atoms.

Options	Meaning	When to choose it
`middle`	在最接近结构中部的两个离散原子层之间切开	普通超胞快速生成上下两部分
`fractional`	按最低与最高投影原子层之间的厚度分数切开	Control the relative cut height inside the cell
`layer_index`	在指定离散层和下一层之间切开	Choose the exact layer above which a slab or layered structure moves

无论选择哪种模式，切面两侧都必须至少有一个原子；卡片不会接受“所有原子一起移动”或“没有原子移动”的伪层错。

Thickness fraction（cut_fraction）

float，默认 0.5。当 cut_mode = "fractional" 时使用，界面范围是 0 到 0.9999；核心参数必须满足 0 <= cut_fraction <= 1，但 1 会因为上方没有原子而报错。

0.5 is near the middle. 0.25 shifts more atoms and 0.75 only the upper region. Values near 0 or 1 create unbalanced halves and are more appropriate for slabs or nonuniform layering than a first bulk scan.

Active only when cut_mode is fractional.

Lower layer index（layer_index）

int，默认 0。当 cut_mode = "layer_index" 时使用。索引指定切面下方的原子层，切面实际放在该层和下一层的中间。

Indices start at 0 and must select an interface below the top layer. Choosing the final layer fails because no upper atoms remain. This mode is clearest when the interface between discrete layers is known.

Active only when cut_mode is layer_index.

Wrap displaced atoms into the cell（wrap）

bool, default true. Wrap shifted atoms back into the periodic cell. Disable to retain unwrapped Cartesian displacements for geometry inspection.

训练集导出通常建议打开，避免原子跑出可视化盒子导致后续工具误判。做几何调试或想直接看上半部分移动了多远时可以关闭；关闭后输出仍然是同一个周期 cell，但坐标可能超过原胞边界。

Recommended presets

对应 Atomsk 的 fcc (111) 半晶体滑移

参考脚本先把原始 fcc 晶体定向为 x=[1-10]、y=[11-2]、z=[111]，再移动 z > 0.5*box 的上半部分，位移沿当前 y 方向。把同一已定向结构送入本卡片时，对应参数是：

plane_hkl = [0, 0, 1]
slip_uvw = [0, 1, 0]
displacement_range = [0.0, 1.47786, 0.073893]
displacement_unit = "angstrom"
cut_mode = "fractional"，cut_fraction = 0.5

对晶格常数 (a=3.62) Å，终点 (1.47786 \approx a/\sqrt{6}) Å，正好扫描一个 fcc Shockley partial 位移。参考脚本随后增加真空层；本卡片不自动改晶胞，因此若目标是含真空的单内部层错 slab，应在上游先准备好真空和定向。

Complete fractional path in an fcc111 slab

Suitable for an initial GSFE curve; produces 11 structures.

{
  "class": "StrictGSFEPathCard",
  "check_state": true,
  "params": {
    "plane_hkl": [0, 0, 1],
    "slip_uvw": [1, 0, 0],
    "displacement_range": [0.0, 1.0, 0.1],
    "displacement_unit": "fraction_of_vector",
    "cut_mode": "middle",
    "cut_fraction": 0.5,
    "layer_index": 0,
    "wrap": true
  }
}

Small-displacement Å probe

Use for small interlayer offsets without a complete period.

{
  "class": "StrictGSFEPathCard",
  "check_state": true,
  "params": {
    "plane_hkl": [0, 0, 1],
    "slip_uvw": [1, 0, 0],
    "displacement_range": [0.0, 0.5, 0.1],
    "displacement_unit": "angstrom",
    "cut_mode": "middle",
    "cut_fraction": 0.5,
    "layer_index": 0,
    "wrap": true
  }
}

Explicit interlayer cut

Use for a slab or layered material when motion should begin above a known layer.

{
  "class": "StrictGSFEPathCard",
  "check_state": true,
  "params": {
    "plane_hkl": [0, 0, 1],
    "slip_uvw": [1, 0, 0],
    "displacement_range": [0.0, 1.0, 0.25],
    "displacement_unit": "angstrom",
    "cut_mode": "layer_index",
    "cut_fraction": 0.5,
    "layer_index": 1,
    "wrap": false
  }
}

Recommended combinations

Super Cell → Stacking Fault / GSFE Path：先扩胞，再切面滑移，降低小胞周期重复带来的假相互作用。
Stacking Fault / GSFE Path → Atomic Perturb：在每个位移点附近加入小扰动，让模型不仅见过理想路径，也见过热扰动后的层错环境。
Bain Path → Stacking Fault / GSFE Path：先改变晶胞形状，再扫层错路径，用于相变或应变下的 GSFE 数据。

Common questions

程序提示 slip_uvw 不在层错面内。 检查 h*u + k*v + l*w 是否为 0。卡片不会把面外分量静默投影掉，请填写真实的面内晶向。

The wrong layers move. Use layer_index to select an explicit interface. middle suits a uniform bulk-like cell but may not suit a slab.

Coordinates exceed cell bounds. Enable wrap. If it was intentionally disabled, treat output as unwrapped in later export and visualization.

能量差除以面积后为什么和参考 GSFE 差一倍。 先检查周期方向上有几个层错界面。纯周期体相超胞把上半部分整体平移时，胞内切面和周期边界都可能形成错配；若两处界面等价，换算单界面 GSFE 时还要除以 2。含真空 slab 通常只有一个内部切面，但仍应检查几何而不是按卡片名称直接假设。

Output labels

GSFE(hkl={hkl},uvw={uvw},d={displacement})

Reproducibility

Deterministic: the same input structure and parameters produce exactly the same structure list.