DFT Calculator

Overview

The calculator.py module sets up DFT calculators as ASE calculator objects from the dft_calculator section of input.yaml. Six engines are supported:

engine key	Backend	Notes
VASP	ase.calculators.vasp.Vasp	All parameters read from INCAR template; requires POTCAR files (VASP_PP_PATH)
CP2K	ase.calculators.cp2k.CP2K	Requires cp2k_template.inp
ORCA	ase.calculators.orca.ORCA	Molecular (non-periodic); periodicity auto-removed from structure
xTB	ase.calculators.xtb.XTB	Semi-empirical tight-binding; reads key = value template file; non-periodic — NPT ensemble not supported
QE	ase.calculators.espresso.Espresso	Quantum ESPRESSO pw.x; k-points default to Gamma-only sampling
Gaussian	ase.calculators.gaussian.Gaussian	Molecular (non-periodic); periodicity auto-removed from structure

Configuration (input.yaml)

dft_calculator:
  engine: "VASP"                       # Engine name (required)
  template_file: "INCAR"               # Engine-specific input template (required)
  exe_command: "mpirun -np 4 vasp_std" # Executable command (optional; auto-detected if omitted)

Each engine reads its template file differently:

Engine	Template file	Notes
VASP	INCAR	Standard VASP INCAR format
CP2K	cp2k_template.inp	CP2K input file (comments stripped)
ORCA	orca_template.inp	ORCA simple input format
xTB	xtb_template.inp	key = value file
QE	qe_template.in	Quantum ESPRESSO pw.x input
Gaussian	gaussian_template.inp	key = value file; always non-periodic

Note

For ORCA and Gaussian, any periodic boundary conditions on the input structure are automatically removed before the calculator is attached.

Note

Ensure that the VASP executable and VASP_PP_PATH are correctly set before running. See SPARC Installation Guide for environment setup.

Template File Reference

Each engine reads its template_file in a different format. Minimal working examples are shown below.

1. VASP (INCAR)

Standard VASP INCAR format. All keys are passed directly to the ASE Vasp calculator.

ISTART = 0
ICHARG = 2
ENCUT  = 520
EDIFF  = 1E-6
NSW    = 0
IBRION = -1
ISMEAR = 0
SIGMA  = 0.05
LWAVE  = .FALSE.
LCHARG = .FALSE.
NPAR   = 4

2. CP2K (cp2k_template.inp)

Full CP2K input format. Lines starting with # or ! are stripped. ASE injects the &COORD and &CELL sections automatically from the Atoms object.

! This is a comment
# This is a comment
&GLOBAL
  ECHO_INPUT
&END GLOBAL
&FORCE_EVAL
  &DFT
    CHARGE 0
    MULTIPLICITY 1
    &MGRID
      REL_CUTOFF 50
      NGRIDS 3
    &END MGRID
    &QS
      METHOD GPW
      EPS_DEFAULT 1.0E-10
      EPS_PGF_ORB 1.0E-12
      EXTRAPOLATION ASPC
      EXTRAPOLATION_ORDER 3
    &END QS
    &SCF
      EPS_SCF 1.0E-4
      SCF_GUESS RESTART
      &OT
        PRECONDITIONER FULL_ALL
      &END OT
      &OUTER_SCF
        EPS_SCF 1.0E-4
        MAX_SCF 3
      &END OUTER_SCF
    &END SCF
  &END DFT
  &SUBSYS
    &KIND B
      ELEMENT B
    &END KIND
    &KIND N
      ELEMENT N
    &END KIND
    &KIND H
      ELEMENT H
    &END KIND
  &END SUBSYS
&END FORCE_EVAL

CP2K parameters (cp2k: section in input.yaml)

Top-level ASE CP2K() parameters are supplied in a separate cp2k: section of input.yaml — not inside dft_calculator:.

Parameter precedence: values in cp2k: override the defaults listed below. Parameters not present in cp2k: take their default values. Settings controlled entirely by the template (cutoff, pseudo_potential) default to null so that ASE does not inject conflicting values.

dft_calculator:
  engine: "CP2K"
  template_file: "cp2k_template.inp"
  exe_command: "mpirun -np 4 cp2k.psmp"  # optional

cp2k:
  xc: "PBE"                        # XC functional
  max_scf: 500                      # Max SCF iterations
  basis_set_file: "BASIS_MOLOPT"    # Basis set library file
  potential_file: "GTH_POTENTIALS"  # Pseudopotential library file

cp2k: parameters and defaults

Key	Default	Description
xc	PBE	Exchange-correlation functional
max_scf	500	Maximum number of outer SCF cycles
basis_set_file	BASIS_MOLOPT	Filename of the basis set library (BASIS_SET_FILE_NAME in &DFT)
basis_set	null	Global basis set. When null, specify BASIS_SET per species inside each &KIND block of the template
potential_file	GTH_POTENTIALS	Filename of the pseudopotential library (POTENTIAL_FILE_NAME in &DFT)
pseudo_potential	null	Global pseudopotential. When null, specify POTENTIAL per species inside each &KIND block of the template
label	cp2k/job	Output file prefix and working subdirectory

Note

basis_set and pseudo_potential default to null. Define BASIS_SET and POTENTIAL inside each &KIND block of the template to assign different basis sets and pseudopotentials per species.

3. ORCA (orca_template.inp)

Requires one ! keyword line. Charge and multiplicity are read from the *xyz line. The %pal block sets parallelism.

Note

ORCA uses MPI for parallel execution (%pal nprocs N end). Ensure that MPI binaries (mpirun / mpiexec) are on your PATH and that the correct MPI libraries are loaded before running, otherwise ORCA will fall back to serial execution or fail to start.

! B3LYP 6-31G(d,p) Engrad
%scf Convergence tight
 maxiter 300 end
%pal nprocs 4 end
*xyz 0 1

4. xTB (xtb_template.inp)

Simple key = value file. Comments start with #. Supported keys:

# xTB template for SPARC
method               = GFN2-xTB
charge               = 0
multiplicity         = 1
accuracy             = 1.0
electronic_temperature = 300.0
max_iterations       = 250
solvent              = none
solvent_method       = none
directory            = xtb_run
label                = xtb

5. Quantum ESPRESSO (qe_template.in)

Standard pw.x input. ASE injects atomic positions and cell parameters. The ATOMIC_SPECIES card maps elements to pseudopotential files. K-points default to Gamma-only if the K_POINTS gamma card is used or the card is omitted.

Note

calculation, tprnfor, and tstress are always overridden by SPARC to scf, .true., and .true. respectively — they may be included in the template for clarity but have no effect.

&CONTROL
  calculation  = 'scf'
  tprnfor      = .true.
  tstress      = .true.
  pseudo_dir   = '/path/to/pseudo'
  outdir       = './qe_out'
  verbosity    = 'low'
/

&SYSTEM
  ibrav            = 0
  ecutwfc          = 40
  ecutrho          = 320
  occupations      = 'fixed'
/

&ELECTRONS
  conv_thr         = 1.0d-5
  mixing_beta      = 0.3
  electron_maxstep = 100
/

ATOMIC_SPECIES
  B   10.811  b_pbe_v1.4.uspp.F.UPF
  N   14.007  N.pbe-n-radius_5.UPF
  H    1.008  H.pbe-rrkjus_psl.1.0.0.UPF

K_POINTS gamma

6. Gaussian (gaussian_template.inp)

Simple key = value file. Comments start with # or !. method and basis are required. ASE always runs a force calculation.

# Gaussian template for SPARC
method       = HF
basis        = STO-3G
charge       = 0
multiplicity = 1
mem          = 2GB
nproc        = 2
scf          = qc,maxcycle=200

Module Contents

Unified interface for setting up DFT calculators as ASE calculator objects.

Supports VASP, CP2K, ORCA, xTB, Quantum ESPRESSO, and Gaussian. Each engine reads its parameters from an engine-specific template file defined in the dft_calculator section of input.yaml.

exception sparc.src.calculator.CalculatorError

Bases: Exception

Exception raised when calculator setup or execution fails.

This exception is raised for issues such as: - Missing required configuration parameters - Invalid template files - Calculator initialization failures - Unsupported calculator engines

class sparc.src.calculator.SetupDFTCalculator(input_config, print_screen=False)

Bases: object

Class to set up DFT calculators for VASP, CP2K, ORCA, and xTB using ASE.

This class provides a unified interface for configuring different DFT engines based on template files and configuration dictionaries. It handles parsing of engine-specific input files and creates appropriate ASE calculator objects.

Parameters:

• input_config (dict or SparcConfig) – Configuration dictionary or SparcConfig object containing calculator settings. Must include a ‘dft_calculator’ key with engine-specific parameters.

• print_screen (bool, optional) – Whether to print calculator configuration details to log. Default is False.

input_config

Processed configuration dictionary

Type:

dict

dft_config

DFT calculator specific configuration

Type:

dict

print_screen

Flag for verbose output

Type:

bool

Raises:

• ConfigurationError – If input_config is invalid or missing required keys

• CalculatorError – If calculator setup fails

Examples

>>> config = {'dft_calculator': {'engine': 'VASP', 'template_file': 'INCAR', ...}}
>>> calc_setup = SetupDFTCalculator(config, print_screen=True)
>>> calculator = calc_setup.vasp()

cp2k()

Set up the CP2K calculator from template file.

espresso()

Set up the Quantum ESPRESSO calculator from a pw.x template file.

The template file should be a standard pw.x input containing namelists (&CONTROL, &SYSTEM, &ELECTRONS, …), ATOMIC_SPECIES, and K_POINTS cards. Coordinates are provided by ASE, so ATOMIC_POSITIONS and CELL_PARAMETERS in the template are ignored.

gaussian()

Set up the Gaussian calculator from a template file.

All keywords from the template are passed directly to ASE’s Gaussian(). ASE handles Link0 vs route section sorting internally. force=None is always added so ASE drives single-point force calculations.

orca()

Set up the ORCA calculator from template file.

vasp()

Set up the VASP calculator from INCAR template.

xtb()

Set up the xTB (extended tight-binding) calculator from template.

sparc.src.calculator.dft_calculator(config, print_screen=False)

Helper function to set up a DFT calculator based on configuration.

This is the main entry point for creating DFT calculators. It automatically determines the calculator engine from the configuration and creates the appropriate ASE calculator object.

Parameters:

• config (dict or SparcConfig) – Configuration dictionary or SparcConfig object containing calculator settings. Must include ‘dft_calculator’ section with ‘engine’ key.

• print_screen (bool, optional) – Whether to print calculator configuration details to log. Default is False.

Returns:

The configured ASE calculator instance (Vasp, CP2K, ORCA, or XTB)

Return type:

ASE Calculator

Raises:

CalculatorError – If engine is unsupported or calculator setup fails

Examples

>>> config = load_config('input.yaml')
>>> calc = dft_calculator(config, print_screen=True)
>>> atoms.calc = calc
>>> energy = atoms.get_potential_energy()