Lattice Perturb

Group: Lattice | Class: CellScalingCard

What the card does

Apply small random changes to cell lengths and, optionally, cell angles to sample geometry near equilibrium. Every output receives an independent perturbation of the original lattice.

\[f_k\in[1-m,1+m],\quad a_i'=f_i a_i,\quad \theta_j'=g_j\theta_j\]

Example workflow

Scenario: Thermal expansion is wrong by more than 30%

A Si NEP has acceptable energy and force errors at relaxed structures, yet a quasiharmonic calculation overestimates thermal expansion by 30%. Every training structure has the same equilibrium volume, so energy gradients under small volume changes are extrapolated.

Diagnosis: Thermal expansion depends on volume derivatives of phonon frequencies, which requires adequate volume-energy sampling around equilibrium. A single relaxed volume is insufficient. Add modest random contractions and expansions around the equilibrium lattice to cover the nearby cell space.

Input: A relaxed Si unit cell.

Objective: Generate 30 random lattice variants around equilibrium with a 4% scaling amplitude.

Parameters:

max_scaling = 0.04 (4% scaling amplitude)
max_num = 30
perturb_angle = false (isolate length changes first)

Output: Thirty structures whose lattice lengths are sampled between 96% and 104% of the input values, with atoms following the cell at fixed fractional coordinates.

How to verify that training-set quality improved:

After retraining, repeat the quasiharmonic calculation; thermal expansion should move closer to experiment.
Inspect the output volume histogram. It should cover the intended neighborhood without strong endpoint clustering.
If coverage remains insufficient, increase max_scaling toward 0.06-0.08 and consider the Sobol engine for a more even small-sample design.
Spot-check nearest-neighbor distances. If a 4% perturbation shortens a bond by more than 0.2 Å relative to the DFT reference, reduce max_scaling.

When to add this card

Add it when:

Volume-sensitive predictions, the volume-energy curve, or thermal-expansion properties are inaccurate
Training volumes are concentrated at one value with no near-equilibrium spread
The model needs interpolation coverage over modest volume changes

Do not add it when:

A specific direction and strain magnitude are required; use Lattice Strain for controlled scanning
Volume changes are outside the intended physical regime, for example a tightly constrained high-pressure phase
The input contains molecules but identify_organic is disabled, which would distort intramolecular bonds

Parameters

Engine Type（engine_type）

int, default 1. 0 selects a Sobol low-discrepancy sequence and 1 uniform random sampling. Sobol gives more even coverage for fewer than about 20 samples; uniform sampling is simpler and differences diminish around 50 samples. Prefer Sobol for a small design.

Max Scaling（max_scaling）

float, default 0.04. Lattice lengths are sampled with factors in [1-m, 1+m]. With perturb_angle, angles receive the same relative scaling. Values around 0.01-0.03 target near-equilibrium phonon sampling, while 0.04-0.06 broadens thermal-expansion coverage. Above 0.08, inspect nearest-neighbor distances for nonphysical bonds.

Max Num（max_num）

int, default 50. Number of perturbed outputs per input, not the number of lattice directions. Roughly 20-30 samples can cover three length degrees of freedom at modest amplitude; 50-100 are more appropriate when angles expand the space to six dimensions. Increasing the count raises density, not range.

Perturb Angle（perturb_angle）

bool, default true. Randomly scale alpha, beta, and gamma as well as lengths. This is multiplicative, not an additive angular offset. It is useful for monoclinic or triclinic cells; for orthogonal or higher-symmetry cells, begin with it disabled and add angle coverage only when needed.

Identify Organic（identify_organic）

bool, default false. Detect molecular clusters and move each approximately as a rigid body so intramolecular bonds are not scaled. Enable for molecular crystals, MOFs, and organic semiconductors; leave disabled for purely inorganic systems.

Use Seed（use_seed）

bool, default false. Enable to reproduce perturbations from the same input, parameters, and seed. Use it for controlled comparisons; exploratory generation may leave it disabled.

Seed（seed）

int, default 0. Random seed used only when use_seed is enabled. Different seeds produce different perturbation designs.

Active only when use_seed=True.

Recommended presets

Near-equilibrium phonon coverage (2% length-only scaling with Sobol)

{
  "class": "CellScalingCard",
  "check_state": true,
  "params": {
    "engine_type": 0,
    "max_scaling": 0.02,
    "max_num": 30,
    "perturb_angle": false,
    "identify_organic": false,
    "use_seed": true,
    "seed": 42
  }
}

Thermal expansion plus angle coverage (5%, lengths and angles, 50 samples)

{
  "class": "CellScalingCard",
  "check_state": true,
  "params": {
    "engine_type": 1,
    "max_scaling": 0.05,
    "max_num": 50,
    "perturb_angle": true,
    "identify_organic": false,
    "use_seed": true,
    "seed": 42
  }
}

Broad exploration (8%, 100 samples, molecular protection enabled)

{
  "class": "CellScalingCard",
  "check_state": true,
  "params": {
    "engine_type": 0,
    "max_scaling": 0.08,
    "max_num": 100,
    "perturb_angle": true,
    "identify_organic": true,
    "use_seed": true,
    "seed": 42
  }
}

Recommended combinations

Lattice Strain -> Lattice Perturb: scan controlled directional strains, then add random local coverage
Lattice Perturb -> Atomic Perturb: perturb the cell before adding atom-level coordinate noise
Super Cell -> Lattice Perturb: expand the structure before perturbing its cell

Common questions

Outputs are identical or cover an extremely narrow range. Check whether max_scaling or max_num is too small. As a diagnostic, try max_scaling of at least 0.02 and max_num of at least 20.

Bonds break in a molecular crystal. Enable identify_organic; otherwise cell scaling directly distorts intramolecular geometry.

Angle changes differ from expectation. The card multiplies each angle by a random factor rather than adding an offset. At 90 degrees with max_scaling=0.04, the range is 86.4-93.6 degrees.

Sobol and uniform outputs differ strongly. This is expected for fewer than about 20 samples, where Sobol is more even. Differences shrink around 50 samples. For reproducibility, fix both engine_type and the seed.

Output labels

LSc(max={max_scaling},{U|S}), where U means uniform and S means Sobol.

Reproducibility

Enable use_seed and fix seed to reproduce an input. The seed is combined with each structure’s content, so frames with different geometry or cells do not reuse the same scale factors, and reordering the dataset does not change a frame’s result. Exactly duplicated frames still receive identical results. The derived seed also controls Sobol scrambling.