Atomic Perturb

Group: Perturbation | Class: PerturbCard

What the card does

Apply random displacements to atomic positions to sample the local neighborhood of an equilibrium configuration. The length of each atom’s displacement vector is at most max_distance; the cell remains unchanged.

\[\Delta\mathbf{r}_i=r_i\hat{\mathbf{u}}_i,\quad 0\le r_i\le d_i,\quad \|\hat{\mathbf{u}}_i\|=1,\quad \mathbf{r}_i'=\mathbf{r}_i+\Delta\mathbf{r}_i\]

When identify_organic is enabled, detected organic molecules move as rigid clusters so their internal bonds are not stretched.

Example workflow

Scenario: force MAE is 50 meV/Å on static tests but rises to 200 meV/Å on an MD trajectory

You trained an NEP model for Si and obtained a force MAE of only 50 meV/Å on static DFT validation structures. During a 300 K NVT trajectory, however, the force error rises to 200 meV/Å because every training atom lies near an equilibrium position and the model has not seen thermally displaced configurations.

Diagnosis: Relaxed structures sit near minima of the potential-energy surface, whereas an MD trajectory samples the surrounding neighborhood. The model needs force responses to displacements away from equilibrium. If the training set contains only minima, those gradients are extrapolations. Small random displacements supply local curvature information around each minimum.

Input: A relaxed 64-atom Si supercell.

Goal: Generate 50 perturbed variants with each atomic displacement no larger than 0.15 Å, roughly two to three times a typical room-temperature Si vibration amplitude.

Parameters:

max_distance = 0.15 Å
max_num = 50
engine_type = 0 (Sobol, for more even directional coverage with a small sample)

Output: 50 structures in which every atom is displaced by 0–0.15 Å from its original position.

How to verify that training-set quality improved:

After DFT labeling and retraining, evaluate a held-out MD trajectory. Its force MAE should decrease substantially toward the static-test error.
Inspect the shortest bond lengths. With 0.15 Å per-atom displacements, a Si–Si bond can change by up to about ±0.3 Å when neighboring atoms move in opposite directions. If contacts shorter than 1.8 Å appear, reduce max_distance.
If the improvement is insufficient, try increasing max_num to 100 and max_distance to 0.25 Å.
For a multielement system with a large mass contrast, such as H plus heavy atoms, consider use_element_scaling so light elements can receive larger displacements.

When to add this card

Add it when:

The training set consists mainly of relaxed static structures and lacks off-equilibrium force directions.
Force predictions are inaccurate in MD or other nonequilibrium configurations.
You need local potential-energy curvature, or force-constant, information near equilibrium.

Do not add it when:

The training set already contains extensive MD trajectories; thermal displacements are already covered, so random perturbations would be redundant.
The input has not been relaxed. Relax it before using this card if the goal is to sample a neighborhood around a minimum.
The displacement is larger than about 0.5 Å and produces many unphysical structures. Use MD, rather than independent random displacements, to explore such large excursions.

Parameters

Engine Type（engine_type）

int, default 1. 0 selects a Sobol low-discrepancy sequence; 1 selects uniform random sampling.

Uniform is the general-purpose default: it is fast and has no Sobol dimensionality limit. Sobol gives more even and isotropic displacement directions for small designs (< 100), but 3 × atom count must not exceed SciPy’s 21,201-dimensional limit, so it supports at most 7,067 atoms. Larger structures must use Uniform. Choose Sobol for 20–50 structures when better directional coverage matters; prefer Uniform for batches or large systems.

Max Distance（max_distance）

float, default: 0.3. Maximum displacement of each atom, in Å.

This is neither a strain percentage nor a separate bound on each Cartesian component; it is the maximum distance an atom may move. Room-temperature vibrational amplitudes are often around 0.05–0.1 Å, so 0.15–0.3 Å is usually sufficient. For light elements such as H, enable use_element_scaling. At 0.3–0.5 Å or above, always inspect nearest-neighbor distances because bonds may be severely distorted or broken.

Max Num（max_num）

int, default: 50. Number of perturbed variants generated for each input structure.

This is the number of output structures, not an atom-count limit. Use 20–50 for lightweight augmentation and 50–100 for routine coverage. For more than 100, follow with FPS Filter, because many perturbations can be nearly redundant in descriptor space.

Identify Organic（identify_organic）

bool, default: false. When enabled, detected organic molecules are treated as rigid clusters and translated as units, preserving all intramolecular bond lengths.

For purely inorganic metals, oxides, or semiconductors, leave this disabled to avoid unnecessary cluster detection. Enable it for systems containing organic molecules; otherwise independent atomic displacements can distort or tear the molecules apart.

Use Element Scaling（use_element_scaling）

bool, default: false. Enables element-specific displacement limits that override the global max_distance.

Enable this for systems with strongly different atomic masses, such as H plus heavy elements. A single max_distance may otherwise under-sample H or over-displace the heavy atoms.

Element Scalings（element_scalings）

dict[str, float] | None, default: None. Mapping from element symbols to maximum displacements.

For example, {"H": 0.5, "O": 0.15, "Si": 0.1}. Listed elements use their mapped limits; all others continue to use the global max_distance.

Used only when use_element_scaling is true.

Use Seed（use_seed）

bool, default: false. When enabled, the same input, parameters, and seed reproduce exactly the same perturbations.

Enable it for controlled comparisons or reproducibility; leave it off for unconstrained exploration. The seed is combined with each structure’s content, so geometrically different frames do not reuse the same displacements, and reordering the dataset does not change a frame’s result. Exactly duplicated frames still receive identical perturbations; deduplicate them or process batches with different seeds when distinct augmentation is wanted.

Seed（seed）

int, default: 0. Random seed, used only when use_seed is enabled. Different seeds produce different displacement sets.

Recommended presets

Room-temperature perturbations (0.1 Å, Sobol, 30 samples)

{
  "class": "PerturbCard",
  "check_state": true,
  "params": {
    "engine_type": 0,
    "max_distance": 0.1,
    "max_num": 30,
    "identify_organic": false,
    "use_element_scaling": false,
    "element_scalings": {},
    "use_seed": true,
    "seed": 42
  }
}

Routine force-field augmentation (0.2 Å, Uniform, 50 samples)

{
  "class": "PerturbCard",
  "check_state": true,
  "params": {
    "engine_type": 1,
    "max_distance": 0.2,
    "max_num": 50,
    "identify_organic": false,
    "use_element_scaling": false,
    "element_scalings": {},
    "use_seed": true,
    "seed": 42
  }
}

Element-specific perturbations (H: 0.5 Å; heavy elements: 0.15 Å; 100 samples)

{
  "class": "PerturbCard",
  "check_state": true,
  "params": {
    "engine_type": 0,
    "max_distance": 0.15,
    "max_num": 100,
    "identify_organic": false,
    "use_element_scaling": true,
    "element_scalings": {"H": 0.5, "C": 0.2, "O": 0.15},
    "use_seed": true,
    "seed": 42
  }
}

Recommended combinations

Lattice Strain → Atomic Perturb: apply a global deformation, then add local displacements.
Shear Matrix Strain -> Atomic Perturb: add coordinate noise after a shear deformation
Atomic Perturb → FPS Filter: remove redundancy after large-scale perturbation.

Common questions

Perturbation creates an abnormally short contact below 1.0 Å. Two neighboring atoms happened to move toward each other. Reduce max_distance, or generate a larger pool and remove invalid structures before representative selection. This card does not perform collision detection, so geometry validation remains necessary.

Molecules in a molecular crystal are distorted or broken. Enable identify_organic so each molecular cluster is translated rigidly and its internal bond lengths are preserved.

Force MAE does not improve after adding perturbed data. max_distance may be too small, leaving samples inside an already learned linear region; test 0.3–0.5 Å while validating geometry. If the potential-energy surface is strongly anharmonic, arbitrary directions may be inefficient. Use Vib Mode Perturb to displace along physically meaningful vibrational modes instead.

Sobol output differs between runs. The Sobol scramble depends on the seed. When use_seed=false, repeated runs may therefore use different sequences. Set use_seed=true for reproducible output.

Sobol reports more than 7,067 atoms. Each atom consumes three Sobol dimensions, so the input exceeds SciPy’s maximum dimensionality. Use the default Uniform engine. This keeps each atom’s displacement limit unchanged and only changes how random points are sampled.

Output labels

Pert(d={max_distance},{U|S}), where U means Uniform and S means Sobol.

Reproducibility

Enable use_seed and fix seed to reproduce the same input; geometrically different frames use distinct but stable derived random streams.