VaspInteractive: a stream-based calculator for VASP

VaspInteractive is a faster yet fully-compatible replacement for the original Vasp calculator from the Atomic Simulation Environment (ase), leveraging the interactive mode of the Vienna Ab Initio Package (VASP) to reduce the number of DFT electronic self-consistent cycles. It can be used both as a file I/O calculator and to communicate with an external server via the socket interface.

Installation

pip install git+https://github.com/SMTG-Bham/vasp-interactive.git

Requires the usual VASP environment variables ($VASP_COMMAND, $VASP_PP_PATH, etc.) to be set.

Usage

Existing code written with ase's Vasp calculator can be easily replaced by VaspInteractive. The calculator should be wrapped in a with-clause to ensure the VASP process exits gracefully:

from ase.optimize import BFGS
from vasp_interactive import VaspInteractive

# atoms: an ase.atoms.Atoms object
# parameters: parameters compatible with ase.calculators.vasp.Vasp
with VaspInteractive(**parameters) as calc:
    atoms.calc = calc
    dyn = BFGS(atoms)
    dyn.run()

If you are using VaspInteractive without the with-clause, call calc.finalize() to manually stop the VASP process.

Pausing the MPI processes

Between ionic steps the VASP ranks sit idle waiting on stdin, but still occupy their cores. If you need to do expensive work in Python between steps (training a surrogate model, running an external optimizer), wrap it in calc.pause() to send SIGTSTP to the MPI ranks and SIGCONT afterwards:

with VaspInteractive(**parameters) as calc:
    atoms.calc = calc
    atoms.get_potential_energy()
    with calc.pause():
        # VASP is suspended here and is not consuming CPU
        expensive_python_work()

Pausing works with both mpirun-style launchers and slurm job steps. Set allow_mpi_pause=False to disable it.

Socket-I/O mode

VaspInteractive also speaks the i-PI protocol, so it can act as a client to any ase socket server. Driven from Python via SocketIOCalculator:

from ase.calculators.socketio import SocketIOCalculator
from vasp_interactive import VaspInteractive

vpi = VaspInteractive(**parameters)
with SocketIOCalculator(calc=vpi, unixsocket="vpi") as calc:
    atoms.calc = calc
    BFGS(atoms).run(fmax=0.05)

Or launched standalone from a directory that already contains VASP inputs:

python -m vasp_interactive.socketio --unixsocket vpi

The standalone client resolves its parameters in this order, with later sources overriding earlier ones:

1. the existing VASP input files (INCAR, KPOINTS, POSCAR) in the working directory
2. .vpi_params.pkl, which the calculator writes into its directory on construction
3. json passed via --params

You do not need to set use_socket=True when going through SocketIOCalculator — only when calling calc.run(atoms) or calc.irun(atoms) directly.

Parameters

Beyond every parameter accepted by ase.calculators.vasp.Vasp:

Parameter	Default	Description
allow_restart_process	True	Restart the VASP process if it exits before the user program ends
allow_mpi_pause	True	Whether calc.pause() may suspend the MPI ranks
allow_default_param_overwrite	True	Overwrite conflicting mandatory INCAR tags with a warning instead of raising
cell_tolerance	1e-8	Threshold below which a cell change is not treated as a system change
kill_timeout	60	Seconds to wait for a clean shutdown before force-killing VASP
parse_vaspout	True	Fall back to parsing vasp.out for energy/forces. Only relevant for VASP 5.x
use_socket	False	Attach a socket client, enabling calc.run() / calc.irun()
host, port, unixsocket, timeout, log	—	Socket client settings, used when use_socket=True

Caveats

• Some INCAR tags are forced. ibrion=-1, potim=0.0, iwavpr=11, interactive=True, ediffg=0 and isif=3 are mandatory for the interactive protocol and will be overwritten (with a warning) if you set them differently. nsw=2000 and isym=0 are applied as defaults if you don't set them.
• Changing the chemical formula is not supported on a running calculator — create a new instance instead.
• Two stdin protocols exist and VASP picks one. VASP 6.4.1 changed INPOS so that with ISIF >= 3 it prompts POSITIONS AND LATTICE: reading from stdin and expects a complete POSCAR (comment, scale, three lattice vectors, ion counts, coordinate mode, positions) rather than just the position block. VaspInteractive reads the prompt and answers in the matching format, so cell relaxation works out of the box on VASP >= 6.4.1. Sending the wrong format deadlocks — VASP waits on stdin while the calculator waits on stdout — so if you patch this area, keep the two in sync. See issue #48.
• Cell relaxation on VASP < 6.4.1 requires a patched build that adds a separate LATTICE: reading from stdin prompt; without it you get a RuntimeError explaining as much.
• A .vpi_params.pkl file is written into the calculation directory on construction, so the standalone socket client can recover the calculator settings.
• calc.converged refers to the ionic step that just finished. Results are parsed from a rolling window of the OUTCAR rather than the whole file, which grows all run long. As a side effect calc.converged now tracks the latest step; reading the full file makes ase stop at the first aborting loop line, so it reported ionic step 1 for the rest of the run.
• MLFF (ML_LMLFF) support is experimental. Output is parsed from a pre-filtered OUTCAR, and shutdown uses SIGINT rather than STOPCAR, which can leave OUTCAR incomplete.

Development

conda env create -f build_tools/environment.yml -y
conda activate vasp-interactive
pip install -e .

The tests in tests/test_parse.py and tests/test_utils.py cover the parsing helpers and need no VASP binary:

pytest tests/test_parse.py tests/test_utils.py

tests/test_vasp_interactive.py runs real relaxations and requires a working VASP installation, POTCARs, and the local environment set up by prep_local_env.

Linting and formatting use ruff, configured in pyproject.toml:

ruff format . && ruff check .