Skip to content

Add VASP and Quantum ESPRESSO plane-wave DFT calculators - #162

Open
reowszer wants to merge 1 commit into
argonne-lcf:mainfrom
reowszer:feature/dft-calculators
Open

Add VASP and Quantum ESPRESSO plane-wave DFT calculators#162
reowszer wants to merge 1 commit into
argonne-lcf:mainfrom
reowszer:feature/dft-calculators

Conversation

@reowszer

@reowszer reowszer commented Jul 31, 2026

Copy link
Copy Markdown
Contributor

Summary

Adds two subprocess-based DFT calculators to ChemGraph, VASP and Quantum ESPRESSO, so the agent can run plane-wave DFT through the same run_ase path already used for EMT, MACE, and other calculators. These are the primary target engines for long-running calculations.

The calculators are periodicity-aware, which is the core correctness feature of this PR:

  • PBC-aware k-point mesh. A non-periodic molecule, with all pbc values set to False, no longer receives a spurious Monkhorst-Pack mesh. QE emits K_POINTS gamma; VASP pins the mesh to [1, 1, 1], enables gamma, and removes kspacing. Otherwise, a stray KSPACING entry in the INCAR could override the gamma point specified by KPOINTS. Periodic systems retain their configured meshes. Constructing a calculator without atoms also preserves the configured mesh for backward compatibility. Slabs and wires use a per-axis mesh: periodic axes retain their configured subdivisions, while non-periodic vacuum axes are forced to a single point.
  • Non-periodic cell handling. A molecule without a cell is centered inside a finite vacuum box, controlled by the vacuum field, before it reaches the input writer. Plane-wave QE and VASP calculations cannot run with a zero cell. The molecule's pbc values remain False, so it still follows the gamma-point branch.
  • QE command sanitization. A legacy full ASE_ESPRESSO_COMMAND, such as mpirun -np 4 pw.x -in PREFIX.pwi > PREFIX.pwo, is reduced to only the launcher and executable before being passed to EspressoProfile. This prevents ASE's own -in handling from being duplicated and ensures that no > token leaks into the argument vector. Runtime flags such as -npool and -ndiag are preserved.
  • VASP INCAR escape hatch. An input_data field passes advanced INCAR parameters, including ISMEAR, SIGMA, ALGO, LREAL, MAGMOM, and others, through to ASE. Keys are converted to lowercase during the merge, with documented last-value-wins precedence. VASP also gains a gamma field. Molecular calculations default to Gaussian smearing with ismear=0, which is appropriate for isolated systems.

The get_calculator(self, atoms=None) signature is gated in ase_core.py using an isinstance(calc_model, (EspressoCalc, VaspCalc)) check because every other calculator exposes a zero-argument get_calculator method.

Part of a 3-PR series

This is the first of three PRs that together add long-running-calculation support for subprocess DFT. They are intended to land in the following order:

  1. feature/dft-calculators (this PR): adds the VASP and Quantum ESPRESSO calculators.
  2. feature/longrun-cap-resume: adds the wall-clock cap, run manifest, and chemgraph resume. It overlaps with this PR at the file level but is functionally independent, and the branches have been verified to merge cleanly.
  3. feature/aurora-qe-example: adds a runnable Aurora example that validates the full seam using real QE DFT. It depends on both earlier PRs.

The example PR will remain in Draft until the calculators and cap PRs merge.

Related issues

None

Type of change

  • Bug fix
  • New feature
  • Docs
  • Chore / refactor / CI

How was this tested?

  • Hermetic unit tests in tests/test_calculators.py assert against both the parameter dictionaries of the constructed ASE calculators and the actual input files written to disk. These checks cover QE's K_POINTS gamma and finite CELL_PARAMETERS, as well as VASP's kpts, gamma, and INCAR parameters. The tests therefore validate the generated inputs, not only the schema. No DFT calculations run in CI.
  • The QE calculator is additionally validated against real pw.x DFT on ALCF Aurora, using bulk Si and a centered H2O molecule, in the companion example PR. VASP is covered only by hermetic tests in this PR and is explicitly labeled as not yet validated against a real VASP installation.
  • ruff check . passes.
  • pytest tests/ -k "not tblite" passes with 354 passed, 28 skipped, and 2 deselected.

Checklist

  • Branched off the latest main and targets main
  • PR is focused on a single logical change and was split where necessary
  • ruff check . passes
  • pytest tests/ -k "not tblite" passes, including additional tests if Academy or backend code was touched
  • Added or updated tests for the change
  • Updated docs or README for any user-facing change

Add EspressoCalc and VaspCalc so ChemGraph can drive subprocess
plane-wave DFT through ASE, alongside a shared _plane_wave helper that
makes both engines physically correct across molecules, slabs, wires,
and solids.

Calculator schemas:
- EspressoCalc: ecutwfc/ecutrho, pseudopotentials, an input_data escape
  hatch for arbitrary QE namelist tags, a vacuum field for non-periodic
  systems, and tprnfor=True so pw.x prints forces every SCF step (ASE
  reads them each optimizer step).
- VaspCalc: kpts/kspacing, an input_data escape hatch for arbitrary
  INCAR tags merged with lowercased keys, a gamma flag, molecule
  smearing defaults, and a vacuum field.

Plane-wave correctness (_plane_wave.py):
- A fully non-periodic system is run Gamma-only with no k-mesh and no
  KSPACING, so a molecule is never given a meaningless Monkhorst-Pack
  mesh. VASP pins a Gamma-centered [1,1,1] KPOINTS file since real VASP
  requires one.
- A slab or wire keeps a mesh only along its periodic axes and drops it
  along vacuum axes.
- A solid keeps the configured mesh verbatim.

Cell handling and command safety:
- A cell-less molecule is centered with vacuum padding in ase_core so
  the writer emits a finite cell, which plane-wave DFT requires.
- ASE_ESPRESSO_COMMAND is sanitized before it reaches EspressoProfile,
  so a legacy full-command value does not duplicate the input flag or
  leak a redirection token.

The pbc-aware k-mesh is applied by rebuilding the DFT calculator with the
read atoms in ase_core, guarded so every other calculator type is left
untouched. Covered by hermetic tests in tests/test_calculators.py that
assert on ASE parameter dicts and on the generated input files.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant