VARNEB — variable-cell nudged elastic band

VARNEB is a calculator-agnostic Python toolkit for variable-cell NEB (VC-NEB) paths between periodic crystal structures. The public project name is varneb; the import package remains vcneb for compatibility with the original research scripts.

python -m pip install -e .
varneb --version
varneb backends
varneb optimizers
varneb init varneb.json
# after editing the endpoint paths:
varneb validate-config varneb.json
varneb prepare varneb.json
python examples/run_toy_vcneb.py
python -m pytest -q

varneb backends --json prints the machine-readable backend capability table. varneb optimizers --json prints the calculator-independent path strategy table. The backend and optimizer fields in varneb.json are deliberately orthogonal: changing FIRE/BlockFIRE/SplitFIRE/StagedFIRE/BFGS does not alter the calculator profile, and changing the calculator does not silently alter the path optimizer. varneb doctor checks optional ASE adapters and executables visible in the current shell; it does not launch a DFT calculation. The generated varneb.json is a deliberately small starting point, not a calculator parameter guess.

• vcneb/ — the stable Python API, VC-NEB core, optimizers, provenance, modal/phonon analysis, and thin calculator adapters.
• examples/ — calculator-free quickstarts and compact material fixtures.
• docs/ — theory, backend contracts, validation plans, and the detailed user manual.
• cluster/ — scheduler templates. Production jobs run on HF through Slurm; endpoints are cached and only interior images are dispatched.
• outputs/, validation/, benchmarks/ — auditable result and benchmark artifacts, never required for installing the library.

The old README_VCNEB.md, run_NEB/, and run_VCNEB/ names remain as compatibility entry points for existing research scripts. New work should use the public CLI, vcneb API, and the layout documented in docs/REPOSITORY_LAYOUT.md.

from vcneb import interpolate_vcneb, run_vcneb

images = interpolate_vcneb(initial, final, n_images=7, mic=True)
# Attach one static calculator with energy, forces, and stress to each image.
result = run_vcneb(images, fmax=0.10, climb_after=None)

The default NEB force threshold is 0.10 eV/Å. In a variable-cell run the calculator must provide stress; cell updates remain owned by VARNEB, so QE images must use scf, not relax or vc-relax. Endpoints are fixed and may be reused from audited static calculations.

VASP and ABACUS have the repository's strongest production validation. QE, LAMMPS, CP2K, and ABINIT are supported through optional ASE adapters with explicit per-image directories and static force/stress preflight. The adapter status is intentionally reported as validated, adapter, or planned rather than claiming a material result that has not been run and audited.

For HF module environments, inspect first and load only what the job needs:

ssh hf "module avail 2>&1 | grep -Ei 'lammps|quantum-espresso|cp2k|abinit|abacus|vasp'"

varneb prepare is calculator-free: it writes initial-vcneb.traj and a varneb_preflight.json report before any DFT executable is called. See docs/USER_MANUAL.md for calculator-specific factories, Slurm isolation, provenance, restarts, and modal analysis.

For any ASE calculator exposing energy, forces, and stress, use examples/run_vcneb_ase.py; specialized factories remain available when a code needs a profile or legacy file protocol.