Vibrational-Mode Perturbation (Vib Mode Perturb)

Group: Perturbation | Class: VibrationModePerturbCard

What the card does

Displace atoms along phonon eigenvectors so the sampled directions follow dynamical degrees of freedom rather than arbitrary coordinate noise. Each output combines a random subset of modes. Optional frequency scaling reduces the contribution of high-frequency modes, and a near-zero-frequency filter removes translational or rotational artifacts.

\[\mathbf{r}'=\mathbf{r}+A\sum_{k\in\mathcal{K}} c_k\mathbf{u}_k,\quad c_k\sim\mathcal{N}(0,1)\ \text{or}\ \mathcal{U}(-1,1)\]

Required input: Every input structure must carry vibrational-mode data. An EXTXYZ file may provide mode_N_x/y/z and frequency_N columns, or block arrays named modes / vibration_modes and frequencies / vibration_frequencies. A structure without recognized mode data is skipped, so an all-missing input produces no output.

Example workflow

Scenario: Atomic Perturb improves force MAE only modestly and low-frequency phonon branches remain inaccurate

You trained an NEP model for Si. Adding 0.2 Å Atomic Perturb samples reduces force MAE from 150 to 80 meV/Å, yet the low-frequency acoustic branches of the predicted phonon dispersion remain inaccurate. Independent random displacements sample generic directions, whereas low-frequency phonons involve collective, long-wavelength motion that random noise is unlikely to align with efficiently.

Diagnosis: The energy response differs greatly among normal-mode directions. Low-frequency acoustic modes involve coordinated motion across many atoms while changing local bond lengths only slightly. Independent random perturbations emphasize local bond distortions and therefore cover those collective directions poorly. Displacements along trusted eigenvectors place training samples directly on the relevant normal-mode coordinates.

Input: A Si supercell whose EXTXYZ data include phonopy-derived modes (mode_1_x/y/z through mode_N_x/y/z) and frequencies (frequency_1 through frequency_N).

Goal: Generate 32 perturbed structures by combining three randomly selected modes per structure at amplitude 0.05. Choose a frequency threshold appropriate to the system; for example, retain only modes above 10 THz when intentionally targeting that range.

Parameters:

• amplitude = 0.05

• modes_per_sample = 3

• max_num = 32

• min_frequency = 0.0, or a physically justified filtering threshold

• distribution = 0 (Gaussian)

• scale_by_frequency = true (automatically attenuate high-frequency modes)

Output: 32 structures displaced along combinations of three randomly selected vibrational modes, with contributions scaled by frequency.

How to verify that training-set quality improved:

• After DFT labeling and retraining, recalculate the phonon dispersion and compare the low-frequency acoustic branches with DFT.

• Inspect which modes were selected. If relevant low-frequency modes are excluded by min_frequency, lower the threshold.

• If high-frequency optical branches remain inaccurate, increase modes_per_sample to 4–5 or raise max_num, then verify that the added samples cover the intended modes.

• If scale_by_frequency makes high-frequency displacements negligibly small, generate a controlled comparison with scaling disabled and a correspondingly reduced amplitude.

When to add this card

Add it when:

• Trusted vibrational-mode data are available and the training set needs samples along those directions.

• Random perturbations have provided limited improvement and phonon or vibrational properties remain inaccurate.

• The model needs potential-energy curvature information along normal-mode coordinates.

Do not add it when:

• The input has no mode data. Generate modes with phonopy or DFPT before using this card.

• The modes come from an insufficiently accurate method. Sampling along incorrect eigenvectors may add noise rather than useful coverage.

• Only generic high-frequency local distortions are needed → Atomic Perturb is simpler.

Input format: vibrational-mode data

The input structure must contain one of the following array layouts. EXTXYZ is recommended.

Layout 1: one set of columns per mode (recommended and easiest to write manually)

2
Properties=species:S:1:pos:R:3:mode_1_x:R:1:mode_1_y:R:1:mode_1_z:R:1:frequency_1:R:1 pbc="F F F"
H 0.000 0.000 0.000 0.10 0.00 0.00 1500.0
H 0.740 0.000 0.000 -0.10 0.00 0.00 1500.0

mode_N_x/y/z stores the displacement components of mode N for each atom. frequency_N stores that mode’s frequency, repeated on every atomic row.

Layout 2: block arrays (convenient for many modes)

2
Properties=species:S:1:pos:R:3:modes:R:3N:frequencies:R:N pbc="F F F"

modes:R:3N stores the displacement components of N modes in mode1_xyz + mode2_xyz + ... order. frequencies:R:N stores the N frequency values, with the same set repeated on each row.

Accepted mode keys are vibration_modes, normal_modes, and modes; accepted frequency keys are vibration_frequencies, normal_mode_frequencies, frequencies, and freqs. A structure with unrecognized names or incompatible shapes is treated as having no usable modes and is skipped.

Parameters

Distribution（distribution）

int, default: 0. Distribution used to sample mode coefficients. 0 is a zero-mean Gaussian, which makes extreme amplitudes less likely; 1 is uniform. Gaussian sampling is usually the safer thermal-like default.

Amplitude（amplitude）

float, default: 0.05. Overall coefficient in displacement = amplitude * sum(coefficient * mode_vector). The actual atomic displacement also depends on how the upstream mode vectors were normalized, including whether they are mass weighted. Use 0.01–0.03 for small-displacement checks and 0.05–0.08 for routine augmentation. Above 0.1, validate nearest-neighbor distances carefully.

Modes Per Sample（modes_per_sample）

int, default: 2. Number of randomly selected modes combined in each output. Use 1–2 to inspect individual-mode behavior and 3–4 for mixed-mode coverage. Above 5, each mode’s contribution becomes harder to interpret and the combinatorial space grows rapidly; 2–4 is usually sufficient.

Min Frequency（min_frequency）

float, default: 10.0. Modes below this frequency are excluded when exclude_near_zero=true; use 0 to disable thresholding. A 0.1–1.0 THz threshold can remove translational or rotational artifacts, while 1–10 THz also removes soft modes. Choose the value from the calculated spectrum and the physics you intend to retain.

Max Num（max_num）

int, default: 32. Number of perturbed samples generated per input structure. Use 20–40 for routine coverage and 50–100 for denser sampling. Follow large batches with FPS Filter to reduce redundancy.

Scale BY Frequency（scale_by_frequency）

bool, default: true. Divides each mode coefficient by sqrt(frequency), attenuating high-frequency contributions. This is a useful thermal-like default because high-frequency modes are energetically expensive at equal displacement. When intentionally studying large-amplitude anharmonicity, you may disable it, but reduce amplitude to avoid over-sampling high-frequency directions.

Exclude Near Zero（exclude_near_zero）

bool, default: true. Applies min_frequency to remove near-zero modes. Keep it enabled in most workflows because translational and rotational artifacts lie near zero frequency and can produce large rigid-body drift.

Use Seed（use_seed）

bool, default: false. Enable it to reproduce exactly the same perturbations from the same input, parameters, and seed. Use it for controlled comparisons; leave it off during exploratory sampling.

Seed（seed）

int, default: 0. Random seed used only when use_seed is enabled.

Active only when use_seed=True.

Recommended presets

Small-displacement check (amplitude 0.02, 2 modes, 20 Gaussian samples)

{
  "class": "VibrationModePerturbCard",
  "check_state": true,
  "params": {
    "distribution": 0,
    "amplitude": 0.02,
    "modes_per_sample": 2,
    "min_frequency": 0.1,
    "max_num": 20,
    "scale_by_frequency": true,
    "exclude_near_zero": true,
    "use_seed": true,
    "seed": 42
  }
}

Routine phonon coverage (amplitude 0.05, 3 modes, 32 Gaussian samples)

{
  "class": "VibrationModePerturbCard",
  "check_state": true,
  "params": {
    "distribution": 0,
    "amplitude": 0.05,
    "modes_per_sample": 3,
    "min_frequency": 0.1,
    "max_num": 32,
    "scale_by_frequency": true,
    "exclude_near_zero": true,
    "use_seed": true,
    "seed": 42
  }
}

Large-displacement anharmonic exploration (amplitude 0.1, 5 modes, 50 samples, no frequency scaling)

{
  "class": "VibrationModePerturbCard",
  "check_state": true,
  "params": {
    "distribution": 1,
    "amplitude": 0.1,
    "modes_per_sample": 5,
    "min_frequency": 0.0,
    "max_num": 50,
    "scale_by_frequency": false,
    "exclude_near_zero": false,
    "use_seed": true,
    "seed": 42
  }
}

Recommended combinations

• Vib Mode Perturb → Atomic Perturb: sample normal-mode directions, then add generic random directions.

• phonopy/DFPT modes → Vib Mode Perturb: calculate trusted modes, attach them to the structures, then generate training candidates.

• Vib Mode Perturb → FPS Filter: reduce redundancy after large-scale generation.

Common questions

No structures are produced. The input contains no recognized mode data. Check that columns use names such as mode_1_x, not mode1_x; verify the frequency columns and ensure every array shape matches the atom count. Reading the EXTXYZ with ASE and inspecting arrays is a direct way to confirm the keys.

Some modes are never selected. This is expected in finite random sampling. With modes_per_sample of 1–2, the sample count may be too small to cover the full pool. Increase max_num or modes_per_sample and inspect the resulting coverage.

High-frequency displacements become too large after disabling scale_by_frequency. This is expected because 1/sqrt(frequency) normally attenuates them. Disable scaling only for a deliberate high-frequency anharmonic study, and compensate by lowering amplitude while validating geometry.

Too few modes remain after min_frequency filtering. A system with many soft modes can be left with a very small pool. First determine whether the soft modes are physical or indicate incomplete relaxation, then lower min_frequency or disable exclude_near_zero only when justified.

Output labels

Vib(a={amplitude},m={modes_per_sample})

Reproducibility

Enable use_seed and fix seed to reproduce the same result for the same input. The seed controls both mode selection and coefficient sampling.