vasp.recipes module

vasp.recipes module#

VASP calculation recipes for workflow integration.

Provides pre-configured calculation workflows compatible with: - Prefect - Dask - Parsl - Covalent - Jobflow

Recipes follow the quacc pattern with @job and @flow decorators.

vasp.recipes.static_job(atoms, runner=None, preset=None, copy_files=None, **calc_kwargs)[source]#

Run a static (single-point) VASP calculation.

Parameters:

atoms (Atoms) – Input atomic structure.
runner (Runner | None) – Job runner (LocalRunner, SlurmRunner, etc.).
preset (str | None) – Parameter preset name.
copy_files (list[str] | None) – Files to copy from previous calculation.
**calc_kwargs – Additional VASP parameters.

Returns:

VaspResult with energy, forces, stress.

Return type:

VaspResult

Example

>>> from ase.build import bulk
>>> si = bulk('Si')
>>> result = static_job(si, encut=400, kpts=(4,4,4))
>>> print(result.energy)

vasp.recipes.relax_job(atoms, runner=None, relax_cell=False, fmax=0.02, steps=100, preset=None, **calc_kwargs)[source]#

Run a VASP relaxation calculation.

Uses VASP’s internal optimizer (IBRION=2 conjugate gradient).

Parameters:

atoms (Atoms) – Input atomic structure.
runner (Runner | None) – Job runner.
relax_cell (bool) – If True, also relax cell shape/volume (ISIF=3).
fmax (float) – Force convergence criterion in eV/Å.
steps (int) – Maximum ionic steps.
preset (str | None) – Parameter preset name.
**calc_kwargs – Additional VASP parameters.

Returns:

VaspResult with relaxed structure.

Return type:

VaspResult

Example

>>> result = relax_job(atoms, relax_cell=True, fmax=0.01)
>>> relaxed_atoms = result.atoms

vasp.recipes.double_relax_flow(atoms, runner=None, relax_cell=True, fmax=0.02, **calc_kwargs)[source]#

Two-step relaxation for better convergence.

First relaxation uses coarse settings, second uses fine settings.

Parameters:

atoms (Atoms) – Input atomic structure.
runner (Runner | None) – Job runner.
relax_cell (bool) – If True, also relax cell.
fmax (float) – Final force convergence criterion.
**calc_kwargs – Additional VASP parameters.

Returns:

VaspResult from final relaxation.

Return type:

VaspResult

vasp.recipes.slab_static_job(slab, runner=None, dipole_correction=True, **calc_kwargs)[source]#

Static calculation for a slab.

Includes dipole correction by default for accurate surface properties.

Parameters:

slab (Atoms) – Slab atomic structure.
runner (Runner | None) – Job runner.
dipole_correction (bool) – Apply dipole correction (LDIPOL).
**calc_kwargs – Additional VASP parameters.

Returns:

SlabResult with energies.

Return type:

SlabResult

vasp.recipes.slab_relax_job(slab, runner=None, fix_bottom_layers=2, relax_cell=False, fmax=0.02, dipole_correction=True, **calc_kwargs)[source]#

Relaxation for a slab with fixed bottom layers.

Parameters:

slab (Atoms) – Slab atomic structure.
runner (Runner | None) – Job runner.
fix_bottom_layers (int) – Number of bottom layers to fix.
relax_cell (bool) – If True, relax in-plane cell parameters.
fmax (float) – Force convergence in eV/Å.
dipole_correction (bool) – Apply dipole correction.
**calc_kwargs – Additional VASP parameters.

Returns:

SlabResult with relaxed structure.

Return type:

SlabResult

vasp.recipes.bulk_to_slabs_flow(bulk_atoms, runner=None, miller_indices=None, relax_bulk=True, **calc_kwargs)[source]#

Complete workflow: relax bulk, then generate and relax slabs.

Parameters:

bulk_atoms (Atoms) – Bulk atomic structure.
runner (Runner | None) – Job runner.
miller_indices (list[tuple[int, int, int]] | None) – Miller indices to generate.
relax_bulk (bool) – If True, relax bulk first.
**calc_kwargs – Additional VASP parameters.

Returns:

Dict with ‘bulk’ and ‘slabs’ results.

Return type:

dict[str, Any]

vasp.recipes.phonon_flow(atoms, runner=None, supercell_matrix=(2, 2, 2), displacement=0.01, calculate_band_structure=True, calculate_dos=True, calculate_thermal=True, temperature_range=(0, 1000, 10), **calc_kwargs)[source]#

Complete phonon calculation workflow.

Uses Phonopy for displacement generation and post-processing.

Parameters:

atoms (Atoms) – Unit cell structure.
runner (Runner | None) – Job runner.
supercell_matrix (tuple[int, int, int]) – Supercell dimensions (e.g., (2, 2, 2)).
displacement (float) – Displacement distance in Å.
calculate_band_structure (bool) – Calculate phonon bands.
calculate_dos (bool) – Calculate phonon DOS.
calculate_thermal (bool) – Calculate thermal properties.
temperature_range (tuple[float, float, float]) – (T_min, T_max, T_step) in K.
**calc_kwargs – Additional VASP parameters.

Returns:

PhononResult with frequencies and properties.

Return type:

PhononResult

Example

>>> result = phonon_flow(atoms, supercell_matrix=(3, 3, 3))
>>> print(result.frequencies)

vasp.recipes.job(func=None, *, name=None, retries=0, retry_delay_seconds=0, **kwargs)[source]#

Decorate a function as a workflow job.

This decorator adapts to the configured workflow engine: - none: Direct function execution - prefect: Wraps with @prefect.task - dask: Wraps with @dask.delayed - parsl: Wraps with @parsl.python_app - covalent: Wraps with @covalent.electron

Parameters:

func (F | None) – Function to decorate.
name (str | None) – Job name (for workflow UIs).
retries (int) – Number of retry attempts.
retry_delay_seconds (float) – Delay between retries.
**kwargs – Additional backend-specific arguments.

Returns:

Decorated function.

Return type:

F | Callable[[F], F]

Example

>>> @job
... def my_calculation(atoms):
...     calc = Vasp(...)
...     return calc.get_potential_energy()

vasp.recipes.flow(func=None, *, name=None, **kwargs)[source]#

Decorate a function as a workflow flow.

A flow orchestrates multiple jobs together.

Parameters:

func (F | None) – Function to decorate.
name (str | None) – Flow name.
**kwargs – Backend-specific arguments.

Returns:

Decorated function.

Return type:

F | Callable[[F], F]

Example

>>> @flow
... def relax_then_static(atoms):
...     relaxed = relax_job(atoms)
...     return static_job(relaxed.atoms)

vasp.recipes.subflow(func=None, *, name=None, **kwargs)[source]#

Decorate a function as a subflow (nested flow).

Parameters:

func (F | None) – Function to decorate.
name (str | None) – Subflow name.
**kwargs – Backend-specific arguments.

Returns:

Decorated function.

Return type:

F | Callable[[F], F]

Core Recipes#

Core VASP calculation recipes.

Provides basic jobs for static and relaxation calculations.

class vasp.recipes.core.VaspResult(atoms=None, energy=None, forces=None, stress=None, fermi_level=None, band_gap=None, parameters=<factory>, directory='', converged=True, nsteps=0)[source]#

Bases: object

Result container for VASP calculations.

Parameters:

atoms (Atoms | None)
energy (float | None)
forces (Any | None)
stress (Any | None)
fermi_level (float | None)
band_gap (float | None)
parameters (dict)
directory (str)
converged (bool)
nsteps (int)

atoms#

Final atomic structure.

Type:: Atoms | None

energy#

Total energy in eV.

Type:: float | None

forces#

Forces array (N, 3) in eV/Å.

Type:: Any | None

stress#

Stress tensor in Voigt notation.

Type:: Any | None

fermi_level#

Fermi energy in eV.

Type:: float | None

band_gap#

Band gap in eV (if calculated).

Type:: float | None

parameters#

VASP parameters used.

Type:: dict

directory#

Calculation directory.

Type:: str

atoms: Atoms | None = None#

energy: float | None = None#

forces: Any | None = None#

stress: Any | None = None#

fermi_level: float | None = None#

band_gap: float | None = None#

parameters: dict#

directory: str = ''#

converged: bool = True#

nsteps: int = 0#

vasp.recipes.core.static_job(atoms, runner=None, preset=None, copy_files=None, **calc_kwargs)[source]#

Run a static (single-point) VASP calculation.

Parameters:

atoms (Atoms) – Input atomic structure.
runner (Runner | None) – Job runner (LocalRunner, SlurmRunner, etc.).
preset (str | None) – Parameter preset name.
copy_files (list[str] | None) – Files to copy from previous calculation.
**calc_kwargs – Additional VASP parameters.

Returns:

VaspResult with energy, forces, stress.

Return type:

VaspResult

Example

>>> from ase.build import bulk
>>> si = bulk('Si')
>>> result = static_job(si, encut=400, kpts=(4,4,4))
>>> print(result.energy)

vasp.recipes.core.relax_job(atoms, runner=None, relax_cell=False, fmax=0.02, steps=100, preset=None, **calc_kwargs)[source]#

Run a VASP relaxation calculation.

Uses VASP’s internal optimizer (IBRION=2 conjugate gradient).

Parameters:

atoms (Atoms) – Input atomic structure.
runner (Runner | None) – Job runner.
relax_cell (bool) – If True, also relax cell shape/volume (ISIF=3).
fmax (float) – Force convergence criterion in eV/Å.
steps (int) – Maximum ionic steps.
preset (str | None) – Parameter preset name.
**calc_kwargs – Additional VASP parameters.

Returns:

VaspResult with relaxed structure.

Return type:

VaspResult

Example

>>> result = relax_job(atoms, relax_cell=True, fmax=0.01)
>>> relaxed_atoms = result.atoms

vasp.recipes.core.double_relax_flow(atoms, runner=None, relax_cell=True, fmax=0.02, **calc_kwargs)[source]#

Two-step relaxation for better convergence.

First relaxation uses coarse settings, second uses fine settings.

Parameters:

atoms (Atoms) – Input atomic structure.
runner (Runner | None) – Job runner.
relax_cell (bool) – If True, also relax cell.
fmax (float) – Final force convergence criterion.
**calc_kwargs – Additional VASP parameters.

Returns:

VaspResult from final relaxation.

Return type:

VaspResult

vasp.recipes.core.static_from_relax_job(relax_result, runner=None, **calc_kwargs)[source]#

Run static calculation on relaxed structure.

Parameters:

relax_result (VaspResult) – Result from relax_job.
runner (Runner | None) – Job runner.
**calc_kwargs – Additional VASP parameters.

Returns:

VaspResult from static calculation.

Return type:

VaspResult

vasp.recipes.core.relax_and_static_flow(atoms, runner=None, relax_cell=False, fmax=0.02, **calc_kwargs)[source]#

Relaxation followed by static calculation.

Parameters:

atoms (Atoms) – Input atomic structure.
runner (Runner | None) – Job runner.
relax_cell (bool) – If True, also relax cell.
fmax (float) – Force convergence criterion.
**calc_kwargs – Additional VASP parameters.

Returns:

Tuple of (relax_result, static_result).

Return type:

tuple[VaspResult, VaspResult]

Slab Recipes#

Slab and surface calculation recipes.

Provides workflows for surface calculations including: - Slab generation from bulk - Surface relaxation - Adsorption calculations

class vasp.recipes.slabs.SlabResult(atoms=None, energy=None, forces=None, stress=None, fermi_level=None, band_gap=None, parameters=<factory>, directory='', converged=True, nsteps=0, miller_indices=None, surface_energy=None, work_function=None, layers=0)[source]#

Bases: VaspResult

Result container for slab calculations.

Additional attributes:: miller_indices: Miller indices of the surface. surface_energy: Surface energy in J/m². work_function: Work function in eV. layers: Number of atomic layers.

Parameters:

atoms (Atoms | None)
energy (float | None)
forces (Any | None)
stress (Any | None)
fermi_level (float | None)
band_gap (float | None)
parameters (dict)
directory (str)
converged (bool)
nsteps (int)
miller_indices (tuple[int, int, int] | None)
surface_energy (float | None)
work_function (float | None)
layers (int)

miller_indices: tuple[int, int, int] | None = None#

surface_energy: float | None = None#

work_function: float | None = None#

layers: int = 0#

vasp.recipes.slabs.make_slabs_from_bulk(bulk_atoms, miller_indices=None, min_slab_size=10.0, min_vacuum_size=15.0, max_normal_search=1, center_slab=True, symmetrize=False)[source]#

Generate slabs from bulk structure.

Parameters:

bulk_atoms (Atoms) – Bulk atomic structure.
miller_indices (list[tuple[int, int, int]] | None) – List of Miller indices. If None, uses common surfaces.
min_slab_size (float) – Minimum slab thickness in Å.
min_vacuum_size (float) – Vacuum thickness in Å.
max_normal_search (int) – Max search depth for surface normals.
center_slab (bool) – Center slab in cell.
symmetrize (bool) – Make symmetric slabs.

Returns:

List of slab Atoms objects.

Return type:

list[Atoms]

vasp.recipes.slabs.slab_static_job(slab, runner=None, dipole_correction=True, **calc_kwargs)[source]#

Static calculation for a slab.

Includes dipole correction by default for accurate surface properties.

Parameters:

slab (Atoms) – Slab atomic structure.
runner (Runner | None) – Job runner.
dipole_correction (bool) – Apply dipole correction (LDIPOL).
**calc_kwargs – Additional VASP parameters.

Returns:

SlabResult with energies.

Return type:

SlabResult

vasp.recipes.slabs.slab_relax_job(slab, runner=None, fix_bottom_layers=2, relax_cell=False, fmax=0.02, dipole_correction=True, **calc_kwargs)[source]#

Relaxation for a slab with fixed bottom layers.

Parameters:

slab (Atoms) – Slab atomic structure.
runner (Runner | None) – Job runner.
fix_bottom_layers (int) – Number of bottom layers to fix.
relax_cell (bool) – If True, relax in-plane cell parameters.
fmax (float) – Force convergence in eV/Å.
dipole_correction (bool) – Apply dipole correction.
**calc_kwargs – Additional VASP parameters.

Returns:

SlabResult with relaxed structure.

Return type:

SlabResult

vasp.recipes.slabs.bulk_to_slabs_subflow(bulk_atoms, runner=None, miller_indices=None, min_slab_size=10.0, vacuum=15.0, relax=True, **calc_kwargs)[source]#

Generate and calculate multiple slabs from bulk.

Parameters:

bulk_atoms (Atoms) – Bulk atomic structure.
runner (Runner | None) – Job runner.
miller_indices (list[tuple[int, int, int]] | None) – Miller indices to generate.
min_slab_size (float) – Minimum slab thickness in Å.
vacuum (float) – Vacuum thickness in Å.
relax (bool) – If True, relax slabs; else static only.
**calc_kwargs – Additional VASP parameters.

Returns:

List of SlabResults.

Return type:

list[SlabResult]

vasp.recipes.slabs.bulk_to_slabs_flow(bulk_atoms, runner=None, miller_indices=None, relax_bulk=True, **calc_kwargs)[source]#

Complete workflow: relax bulk, then generate and relax slabs.

Parameters:

bulk_atoms (Atoms) – Bulk atomic structure.
runner (Runner | None) – Job runner.
miller_indices (list[tuple[int, int, int]] | None) – Miller indices to generate.
relax_bulk (bool) – If True, relax bulk first.
**calc_kwargs – Additional VASP parameters.

Returns:

Dict with ‘bulk’ and ‘slabs’ results.

Return type:

dict[str, Any]

vasp.recipes.slabs.calculate_surface_energy(slab_result, bulk_energy_per_atom)[source]#

Calculate surface energy from slab and bulk energies.

Parameters:

slab_result (SlabResult) – Result from slab calculation.
bulk_energy_per_atom (float) – Energy per atom in bulk.

Returns:

Surface energy in J/m².

Return type:

float

Phonon Recipes#

Phonon calculation recipes with Phonopy integration.

Provides workflows for: - Force constants calculation - Phonon band structure - Phonon DOS - Thermodynamic properties

class vasp.recipes.phonons.PhononResult(atoms=None, supercell_matrix=None, force_constants=None, frequencies=None, band_structure=None, dos=None, thermal=None, phonopy=None, directory='')[source]#

Bases: object

Result container for phonon calculations.

Parameters:

atoms (Atoms | None)
supercell_matrix (tuple | None)
force_constants (Any | None)
frequencies (Any | None)
band_structure (dict | None)
dos (dict | None)
thermal (dict | None)
phonopy (Any | None)
directory (str)

atoms#

Unit cell atoms.

Type:: Atoms | None

force_constants#

Force constant matrix.

Type:: Any | None

frequencies#

Phonon frequencies at gamma.

Type:: Any | None

band_structure#

Band structure data.

Type:: dict | None

dos#

Phonon DOS data.

Type:: dict | None

thermal#

Thermodynamic properties.

Type:: dict | None

phonopy#

Phonopy object (if available).

Type:: Any | None

atoms: Atoms | None = None#

supercell_matrix: tuple | None = None#

force_constants: Any | None = None#

frequencies: Any | None = None#

band_structure: dict | None = None#

dos: dict | None = None#

thermal: dict | None = None#

phonopy: Any | None = None#

directory: str = ''#

vasp.recipes.phonons.get_phonopy_supercells(atoms, supercell_matrix=(2, 2, 2), displacement=0.01)[source]#

Generate displaced supercells using Phonopy.

Parameters:

atoms (Atoms) – Unit cell structure.
supercell_matrix (tuple[int, int, int]) – Supercell dimensions.
displacement (float) – Displacement distance in Å.

Returns:

Tuple of (Phonopy object, list of displaced supercells).

Raises:

ImportError – If phonopy is not installed.

Return type:

tuple[Any, list[Atoms]]

vasp.recipes.phonons.phonon_displacement_job(atoms, runner=None, **calc_kwargs)[source]#

Calculate forces for a displaced supercell.

Parameters:

atoms (Atoms) – Displaced supercell structure.
runner (Runner | None) – Job runner.
**calc_kwargs – Additional VASP parameters.

Returns:

VaspResult with forces.

Return type:

VaspResult

vasp.recipes.phonons.phonon_forces_subflow(displaced_cells, runner=None, **calc_kwargs)[source]#

Calculate forces for all displaced supercells.

Parameters:

displaced_cells (list[Atoms]) – List of displaced supercell structures.
runner (Runner | None) – Job runner.
**calc_kwargs – Additional VASP parameters.

Returns:

List of VaspResults with forces.

Return type:

list[VaspResult]

vasp.recipes.phonons.phonon_flow(atoms, runner=None, supercell_matrix=(2, 2, 2), displacement=0.01, calculate_band_structure=True, calculate_dos=True, calculate_thermal=True, temperature_range=(0, 1000, 10), **calc_kwargs)[source]#

Complete phonon calculation workflow.

Uses Phonopy for displacement generation and post-processing.

Parameters:

atoms (Atoms) – Unit cell structure.
runner (Runner | None) – Job runner.
supercell_matrix (tuple[int, int, int]) – Supercell dimensions (e.g., (2, 2, 2)).
displacement (float) – Displacement distance in Å.
calculate_band_structure (bool) – Calculate phonon bands.
calculate_dos (bool) – Calculate phonon DOS.
calculate_thermal (bool) – Calculate thermal properties.
temperature_range (tuple[float, float, float]) – (T_min, T_max, T_step) in K.
**calc_kwargs – Additional VASP parameters.

Returns:

PhononResult with frequencies and properties.

Return type:

PhononResult

Example

>>> result = phonon_flow(atoms, supercell_matrix=(3, 3, 3))
>>> print(result.frequencies)

vasp.recipes.phonons.dfpt_phonon_job(atoms, runner=None, **calc_kwargs)[source]#

DFPT phonon calculation using VASP’s internal routines.

Uses IBRION=8 for symmetry-reduced DFPT. Only calculates gamma-point phonons (q=0).

Parameters:

atoms (Atoms) – Unit cell structure.
runner (Runner | None) – Job runner.
**calc_kwargs – Additional VASP parameters.

Returns:

PhononResult with gamma frequencies.

Return type:

PhononResult

vasp.recipes module

Contents

vasp.recipes module#

Core Recipes#

Slab Recipes#

Phonon Recipes#