Super Cell

Group: Lattice | Class: SuperCellCard

What the card does

Expand a structure by fixed replication, target cell lengths, or an atom-count limit so downstream defect, surface, and magnetic operations have enough space. Choose one strategy: scale, cell, or max_atoms. Individual axes can be locked, which is useful for preserving the normal direction of a slab.

\[\mathbf{T}=\mathrm{diag}(n_a,n_b,n_c),\quad \mathbf{C}'=\mathbf{C}\mathbf{T},\quad N'=N\cdot n_a n_b n_c\]

Example workflow

Scenario: Periodic images raise the vacancy formation energy by 0.5 eV

A bcc Fe NEP is trained on 2x2x2 cells with 16 atoms and overestimates a single-vacancy formation energy by 0.5 eV. The vacancy is only about 5 Å from its periodic images, so the training environment represents interacting vacancy images rather than an isolated defect.

Diagnosis: Defect cells must be large enough that interactions between periodic defect images are negligible for the target accuracy. Add vacancy labels in larger cells, for example 3x3x3 or 4x4x4, and use such cells as parents for downstream defect generation.

Input: A two-atom bcc Fe primitive cell.

Objective: Build a 4x4x4, 128-atom parent for vacancy generation.

Parameters:

mode = scale
super_scale = [4, 4, 4]

Output: One 4x4x4 supercell with 128 atoms.

How to verify the result:

Check atom count: 2 × 4 × 4 × 4 = 128.
Check lattice vectors: each is four times longer and volume is 64 times larger.
If the vacancy formation energy remains size dependent, repeat at larger cells until the chosen DFT and NEP comparisons are converged.
If larger cells exceed the labeling budget, use max_atoms to impose a hard size limit.

When to add this card

Add it when:

Downstream vacancies, interstitials, surfaces, or magnetic patterns need a larger parent cell
Periodic-image interactions are not negligible in current cells
A specified minimum defect-image separation is required

Do not add it when:

The task is a bulk property already converged in the primitive or small cell
The DFT budget cannot support the expanded cell and the remaining finite-size error is explicitly accepted
Cell deformation rather than replication is needed; use Lattice Strain or Lattice Perturb

Parameters

Expansion strategy

Behavior Type（behavior_type）

int, default 0. Selects outputs. 0 returns one requested/selected cell; 1 enumerates intermediate replication combinations from 1x1x1 through the target; 2 uses the smallest replication that meets a target, including ceiling behavior for target lengths. Estimate enumeration size before using mode 1.

Mode（mode）

SuperCellMode, default 'scale'. scale uses explicit super_scale; cell derives per-axis replication from target_cell in Å using floor or ceiling according to behavior_type; max_atoms searches replication combinations under an atom-count cap. Use explicit scale when the required cell is known, target lengths for separation constraints, and max atoms for a budget-limited design.

Super Scale（super_scale）

tuple[int, int, int], default (3, 3, 3); scale only. Replication along a, b, and c, with minimum 1. Total atom count is multiplied by their product.

Target Cell（target_cell）

tuple[float, float, float], default (20.0, 20.0, 20.0) Å; cell only. Target lengths by axis. Replication is derived from target/original length and the selected floor/ceiling behavior.

Max Atoms（max_atoms）

int, default 100; max-atoms only. Upper bound on total atoms. Enumeration behavior may emit several replication combinations below it.

Axis locking

Fixed Axis Flags（fixed_axis_flags）

tuple[bool, bool, bool], default (false, false, false). Lock replication along a, b, or c. For a slab, lock the normal and expand only in plane. Locked axes use fixed_axis_scale; others follow the selected strategy.

Fixed Axis Scale（fixed_axis_scale）

tuple[int, int, int], default (1, 1, 1). Replication values for axes enabled in fixed_axis_flags. Use 1 to preserve an axis or another fixed integer when required.

Recommended presets

Direct 3x3x3 expansion (one output)

{
  "class": "SuperCellCard",
  "check_state": true,
  "mode": "scale",
  "behavior_type": 0,
  "super_scale": [3, 3, 3],
  "target_cell": [20, 20, 20],
  "max_atoms": 100,
  "fixed_axis_flags": [false, false, false],
  "fixed_axis_scale": [1, 1, 1]
}

Slab expansion (20 Å in plane, normal locked at 1x, enumerate combinations)

{
  "class": "SuperCellCard",
  "check_state": true,
  "mode": "cell",
  "behavior_type": 1,
  "super_scale": [3, 3, 3],
  "target_cell": [20, 20, 20],
  "max_atoms": 100,
  "fixed_axis_flags": [false, false, true],
  "fixed_axis_scale": [1, 1, 1]
}

Largest supercell under a 300-atom budget

{
  "class": "SuperCellCard",
  "check_state": true,
  "mode": "max_atoms",
  "behavior_type": 0,
  "super_scale": [3, 3, 3],
  "target_cell": [20, 20, 20],
  "max_atoms": 300,
  "fixed_axis_flags": [false, false, false],
  "fixed_axis_scale": [1, 1, 1]
}

Recommended combinations

Super Cell -> Vacancy Defect: establish defect-image separation before removing atoms
Super Cell -> Lattice Strain: strain the target-size cell
Super Cell -> Surface Warp: create surface variation after in-plane expansion
Super Cell -> FPS Filter: reduce redundant outputs from an intentionally broad enumeration

Common questions

Only 1x1x1 is returned. The input may already meet target_cell, or its atom count may already exceed max_atoms. Compare target lengths and budget with the input cell.

A slab expands unevenly in plane. Unlocked axes choose replication independently. Use equal a/b targets or explicit scale when a square in-plane cell is required.

Atom count exceeds the budget. Compute n_input × na × nb × nc first. Enumeration mode also emits multiple sizes, not just the largest.

Enumeration produces too many cells. Mode 1 emits all allowed intermediate combinations. Use behavior 0 when only the largest selected cell is needed.

Output labels

SC({na}x{nb}x{nc}), for example SC(4x4x4).

Reproducibility

Deterministic: identical inputs and parameters produce identical outputs.