neb-prepare

name: neb-prepare description: "Use this skill for NEB and dimer preparation work: validate endpoint pairs, choose image counts, build image trees, prepare VASP NEB roots, and prepare dimer-ready inputs or raw mode guesses."

Overview

Use this skill when the job is to prepare a pathway calculation rather than execute or analyze it. It covers endpoint validation, interpolation count selection, NEB input-tree assembly, and dimer-ready setup. For the actual run strategy, use neb-calculation. For post-run interpretation and pitfalls, use neb-analysis.

Quick Start

Confirm the endpoint pair is one local elementary step and preserve frozen-atom identity.
If same-species atoms may be permuted, run remap_neb_endpoint_atoms before interpolation.
Estimate n_images with estimate_neb_image_count before interpolating.
Keep the image count tied to a stated displacement rationale, not a guessed constant.
Build the image tree with make_neb_geometry.
Prepare the VASP NEB root with vasp_neb_prepare.
If a dimer refinement branch is needed, prepare the raw mode with make_dimer_mode_from_neb or make_dimer_mode_from_mace, then build the dimer input with vasp_dimer_prepare.
If you need the detailed run protocol for plain-NEB -> CI-NEB or NEB/frequency/dimer, switch to neb-calculation.

Allowed tools

estimate_neb_image_count
remap_neb_endpoint_atoms
make_neb_geometry
vasp_neb_prepare
vasp_dimer_prepare
make_dimer_mode_from_neb
make_dimer_mode_from_mace

Workflow

1. Validate the endpoint contract before interpolation

Do not skip endpoint validation because a downstream NEB execution tool exists. A managed pathway run is only useful if this preparation contract is already satisfied.
The initial and final structures must keep the same atom ordering. Do not interpolate reordered atoms.
If same-species atoms may have been permuted, use remap_neb_endpoint_atoms to reorder the final endpoint onto the initial order before estimating distances or building images.
The remapping step should normally exclude frozen atoms and preserve selective dynamics. For slab pathways, keep bulk-like frozen layers fixed in identity and only remap the mobile subset.
By default, remap_neb_endpoint_atoms also locks mobile atoms whose current-order displacement is already below 0.5 Å; only the remaining mobile atoms are candidates for remapping.
A single NEB should describe one local elementary event, not a long migration across several equivalent sites.
If the displacement is really a long hop, remodel the final state onto the nearest equivalent site and prepare that primitive hop first.

2. Choose the image count from the periodic displacement, not by feel

Prefer estimate_neb_image_count before choosing n_images.
Under periodic boundary conditions, use the same minimum-image convention (mic=true) for the estimate that you intend to use for interpolation.
When no better prior exists, use n_images ≈ ceil(sqrt(sum_i ||Δr_i||^2) / 0.8 Å).
For routine local events, prefer about 4-8 intermediate images.
If the periodic root-sum-squared displacement exceeds about 6 Å, or if the estimate asks for more than about 8 intermediate images, treat that as a warning that the path is probably too long for one primitive NEB.

3. Build the shared image tree

Use make_neb_geometry to generate the flat numbered image tree (00.vasp, 01.vasp, ...).
Prefer this flat image-tree layout as the common handoff format.
Inspect make_neb_geometry warnings before handing the tree to execution. A minimum interatomic distance below about 0.8 Å in any image is strong evidence that abnormal interpolation or atom overlap may be present; recheck endpoint atom mapping, use remap_neb_endpoint_atoms for same-species permutations, try interp_method="idpp", or remodel the event as a shorter primitive hop.
Endpoint atom count, element sequence, and lattice mismatches are hard errors. Do not bypass them by manually copying image files into a later execution stage.
If the output directory already exists, require overwrite=true rather than silently mixing trees.

4. Prepare the NEB-ready VASP root

Use vasp_neb_prepare only to assemble the VASP NEB root and protected NEB INCAR settings.
In image-tree mode, the tool will warn that endpoint OUTCAR files still need to be copied in later for barrier analysis. That reminder is expected; preparation should still continue.
Keep patch_policy="safe" unless you intentionally need to override NEB-critical keys.
iopt must stay one of 7, 2, or 1.

5. Prepare the dimer branch when needed

vasp_dimer_prepare is for the official VASP improved dimer method (IBRION=44).
Use make_dimer_mode_from_neb when a NEB path already localizes the TS region well enough to extract a reaction-direction guess.
Use make_dimer_mode_from_mace when you need a finite-difference mode guess instead.
vasp_dimer_prepare applies the required per-atom 1/sqrt(mass) transformation internally. Pass it the raw mode, not an already mass-divided mode.
If you copy a vibrational mode from a VASP OUTCAR, use the ordinary raw dx dy dz block, not the Eigenvectors after division by SQRT(mass) block.

6. Keep the execution branches conceptually separate

The common robust NEB route is plain-NEB -> CI-NEB.
A common TS-refinement route is plain-NEB or TS guess -> frequency/mode guess -> dimer.
This skill only prepares those branches. Use neb-calculation if you need the detailed execution sequence.

Method-critical defaults

Keep endpoint preparation, image generation, and later execution settings scientifically aligned.
Do not treat image-count choice as cosmetic; it is part of the pathway model.
Treat short_distance_count > 0 or an overlap warning from make_neb_geometry/vasp_neb_prepare as strong evidence of a potentially abnormal interpolation until the endpoint mapping or path model has been checked.
Prefer odd intermediate-image counts for CI-NEB refinement so there is a natural central climbing image.
Prefer even intermediate-image counts for plain NEB only when the path is otherwise symmetric and no unique climbing image is needed yet.
For dimer preparation, never skip the mass weighting performed by vasp_dimer_prepare.
If several imaginary modes exist, the correct dimer direction is the chemically meaningful one, not automatically the largest-magnitude imaginary mode.

Output Contract

Return:

validated endpoint pair or the reason it is not NEB-ready
chosen image-count rationale
image-tree root
prepared NEB root plus INCAR and neb_incar_patch.json
if dimer preparation was requested, the raw mode path and dimer-ready POSCAR path

References

Use neb-calculation for the detailed execution protocol after preparation is complete.
Use neb-analysis once images have been collected and you need barrier interpretation or QC.