Validation

This page explains the VQkit pre-flight calculation checker in detail.

The pre-flight checker is designed to identify common input problems before a VASP or Quantum ESPRESSO calculation is submitted.

It is available from:

[1] Pre-processing
[6] Pre-flight calculation check

The checker does not run the DFT calculation.

It examines the available input files and reports:

required files that are missing;
malformed or inconsistent input settings;
warnings that deserve manual review;
useful calculation metadata;
whether the setup is ready for submission.

The final status is reported as:

[READY]
[READY WITH WARNINGS]
[NOT READY]

Meaning of report levels

VQkit classifies each check using one of four levels.

OK

[OK]

The item passed the implemented consistency check.

Example:

[OK] ENCUT - 520 eV

WARNING

[WARNING]

The calculation may still run, but the setting should be reviewed.

Examples include:

ENCUT not explicitly defined;
MAGMOM missing for a spin-polarized VASP calculation;
QE ecutrho not explicitly defined;
non-flat or uncertain settings;
an unusual band-path specification.

A warning does not automatically mean the calculation is wrong.

ERROR

[ERROR]

A blocking problem was found.

Examples include:

missing required input file;
invalid atom count;
missing pseudopotential;
inconsistent POSCAR/POTCAR species order;
invalid QE cell;
missing K_POINTS.

A report containing at least one ERROR is classified:

[NOT READY]

INFO

[INFO]

Informational items do not block submission.

Examples include:

an optional job script is present or absent;
selective-dynamics constraints are detected;
QE outdir location;
repeated INCAR tags with the same value.

Code detection

VQkit first determines whether the working directory appears to contain:

VASP inputs;
Quantum ESPRESSO inputs;
both;
neither.

If only one code is clearly detected, VQkit uses it automatically.

If both VASP and QE files are detected, VQkit asks which code should be validated.

If neither can be determined, VQkit also asks the user to select the code.

VASP pre-flight validation

For VASP, VQkit checks the following required files:

INCAR
POSCAR
KPOINTS
POTCAR

Each file is checked for:

existence;
non-zero file size.

If any required file is missing or empty, VQkit reports an ERROR.

INCAR checks

VQkit parses active KEY = VALUE INCAR lines while ignoring normal ! and # comments.

ENCUT

If ENCUT is missing:

[WARNING] ENCUT - ENCUT is not explicitly set.

If it is present but invalid or non-positive:

[ERROR] ENCUT - ENCUT must be a positive numeric value.

If valid:

[OK] ENCUT - 520 eV

EDIFF

VQkit performs a similar check for:

EDIFF

If it is absent, a warning is issued because the electronic convergence threshold is not explicitly controlled.

Repeated INCAR tags

VQkit detects repeated INCAR keywords.

If the same keyword appears several times with exactly the same value, VQkit reports an informational message.

Example:

ENCUT = 520
ENCUT = 520

may produce:

[INFO] Repeated INCAR tag ENCUT
       Repeated with the same value: 520

If the repeated values differ:

ENCUT = 450
ENCUT = 520

VQkit reports a warning and reminds the user that VASP will use the final active value.

This is useful for detecting accidental duplicate settings copied into an INCAR.

Spin setup

VQkit checks ISPIN.

If:

ISPIN = 2

but MAGMOM is absent, VQkit reports:

[WARNING] MAGMOM
ISPIN = 2 but MAGMOM is not explicitly defined.

If both ISPIN = 2 and MAGMOM are present, the spin setup is reported as OK.

If:

ISPIN = 1

VQkit reports that the calculation is non-spin-polarized.

This check does not determine whether the chosen magnetic configuration is scientifically correct.

Ionic-relaxation consistency

VQkit checks the relationship between:

NSW
IBRION

If NSW > 0 but IBRION is not explicitly defined, VQkit issues a warning.

If:

NSW > 0
IBRION = -1

VQkit warns that ionic motion may not actually be configured as intended.

Otherwise, a normal relaxation setup is reported with the detected NSW and IBRION values.

POSCAR checks

VQkit parses the POSCAR structure and checks:

total atom count;
lattice vectors;
cell volume;
element symbols where available;
selective-dynamics constraints.

Cell volume

The lattice volume must be finite and positive.

If the cell has zero or invalid volume:

[ERROR] POSCAR lattice

Otherwise, VQkit reports the number of atoms and the cell volume.

Example:

[OK] POSCAR structure - 24 atoms; volume = 312.456789 Ang^3

Species information

For a VASP 5-style POSCAR containing element symbols, VQkit records the species order.

Example:

Fe O

For an old VASP 4-style POSCAR without element symbols, VQkit cannot automatically verify the POTCAR species order and therefore reports a warning.

Selective dynamics

If selective dynamics is enabled, VQkit counts how many atoms have at least one constrained coordinate.

Example:

[INFO] Selective dynamics
       Enabled; 8 atom(s) have at least one constrained direction.

POTCAR checks

VQkit inspects POTCAR metadata including:

TITEL entries;
element/dataset order;
ENMAX values.

POSCAR versus POTCAR species order

For a VASP 5-style POSCAR, VQkit compares the expected element order with the POTCAR dataset order.

Example POSCAR:

Fe O

Correct POTCAR order:

Fe -> O

If the number of POTCAR datasets differs from the number of POSCAR species, VQkit reports an ERROR.

If the order differs, VQkit reports an ERROR such as:

POSCAR: Fe O
POTCAR: O Fe

This is a blocking input inconsistency.

POTCAR variants

When comparing labels such as:

Fe_pv
Ti_sv

VQkit compares the base element symbol to the POSCAR species.

Therefore:

Ti_sv

is recognized as belonging to element Ti for the purpose of species-order validation.

ENCUT versus ENMAX

VQkit extracts all available POTCAR ENMAX values and calculates:

\[E_{\mathrm{NMAX,max}} = \max(E_{\mathrm{NMAX},i})\]

It then compares the INCAR cutoff:

\[E_{\mathrm{cut}}\]

with the maximum POTCAR recommendation.

If:

\[E_{\mathrm{cut}} < E_{\mathrm{NMAX,max}}\]

VQkit reports a warning.

Example:

ENCUT = 400 eV
max POTCAR ENMAX = 520 eV

may produce:

[WARNING] ENCUT vs POTCAR
ENCUT = 400 eV is below max POTCAR ENMAX = 520 eV.

If ENCUT is equal to or greater than the maximum ENMAX, the consistency check passes.

This is only a minimum sanity check.

A proper production calculation should still use a converged plane-wave cutoff.

KPOINTS validation

VQkit reads the KPOINTS file and recognizes several common forms.

Automatic mesh

For Gamma or Monkhorst-Pack automatic meshes, VQkit checks that:

three mesh dimensions are present;
each mesh value is a positive integer.

Example:

6 6 1

is reported as valid if parsed correctly.

Line mode

If line-mode syntax is detected, VQkit reports:

Line-mode/high-symmetry path detected.

This is useful for band-structure calculations.

Explicit k points

Other valid non-automatic definitions are reported as:

Explicit/non-automatic k-point definition detected.

HPC job script

VQkit checks whether:

job.sh

exists.

Its presence or absence is informational only.

A missing job.sh does not make the VASP input invalid.

VASP example report

A typical report may look like:

VQkit pre-flight calculation check

Directory    : /path/to/calc
DFT code     : VASP
Calculation  : relax

[OK]      INCAR - Present.
[OK]      POSCAR - Present.
[OK]      KPOINTS - Present.
[OK]      POTCAR - Present.
[OK]      ENCUT - 520 eV
[OK]      EDIFF - 1e-06
[OK]      Spin setup - ISPIN = 2 and MAGMOM is present.
[OK]      POSCAR structure - 24 atoms; volume = ...
[OK]      POTCAR species order - Matches POSCAR: Fe O
[OK]      ENCUT vs POTCAR - ENCUT = 520 eV; max ENMAX = ...
[OK]      KPOINTS mesh - 6 6 1 (Gamma)

Pre-flight summary
Passed   : ...
Warnings : ...
Errors   : ...

[READY]

Quantum ESPRESSO pre-flight validation

For QE, VQkit searches for pw.x input files.

Recognized files are *.in files containing at least:

&CONTROL
&SYSTEM

If exactly one suitable input exists, VQkit selects it automatically.

If multiple QE inputs exist, VQkit displays a menu so the user can choose the file to validate.

Examples may include:

scf.in
relax.in
vc-relax.in
nscf.in
bands.in

Quantum ESPRESSO pre-flight calculation check

Required QE namelists

VQkit checks for:

&CONTROL
&SYSTEM

Both are required for the current pw.x validation workflow.

If either is missing, VQkit reports an ERROR.

ELECTRONS namelist

&ELECTRONS is checked separately.

If present:

[OK] &ELECTRONS

If absent, VQkit reports an informational message because QE defaults may be valid in some cases.

nat and ntyp

VQkit reads:

nat
ntyp

Both must be positive integers.

For example:

nat = 8
ntyp = 2

If either is missing or non-positive, an ERROR is reported.

ATOMIC_SPECIES

VQkit parses the:

ATOMIC_SPECIES

block.

It checks:

whether the block exists;
how many species entries are present;
whether that count matches ntyp.

Example:

ntyp = 2

ATOMIC_SPECIES
  Fe  55.845  Fe.UPF
  O   15.999  O.UPF

passes the count consistency check.

If ntyp = 2 but three species entries are present, VQkit reports an ERROR.

ATOMIC_POSITIONS

VQkit checks that:

ATOMIC_POSITIONS

exists and contains numerical coordinate rows.

The number of coordinate rows is compared with nat.

If:

nat = 8

but only seven positions are found, VQkit reports an ERROR.

Lattice validation

VQkit reads:

ibrav

If:

ibrav = 0

the input must contain exactly three valid:

CELL_PARAMETERS

vectors.

VQkit calculates the cell volume and rejects a zero or invalid lattice.

If ibrav is not explicitly specified, VQkit reports a warning asking the user to verify the lattice definition.

Plane-wave cutoffs

VQkit checks:

ecutwfc
ecutrho

For each value:

missing -> WARNING;
non-positive -> ERROR;
positive -> OK.

Example:

ecutwfc = 60
ecutrho = 480

may produce:

[OK] ecutwfc - 60 Ry
[OK] ecutrho - 480 Ry

VQkit does not determine whether these values are scientifically converged.

K_POINTS validation

The QE input must contain:

K_POINTS

If the card is missing, VQkit reports an ERROR.

Automatic mesh

For:

K_POINTS automatic

VQkit expects a following mesh/shift line with six integers:

nk1 nk2 nk3 sk1 sk2 sk3

The first three values must be at least 1.

The shift values must be:

0
1

Example:

K_POINTS automatic
6 6 1 0 0 0

is valid.

Band-structure path

If the QE calculation type is:

calculation = 'bands'

VQkit checks whether the K_POINTS card uses a band-path format such as:

crystal_b
tpiba_b

If not, a warning is issued asking the user to verify the high-symmetry path.

Relaxation-specific checks

For:

calculation = 'relax'

VQkit requires:

&IONS

If missing, an ERROR is reported.

For:

calculation = 'vc-relax'

VQkit requires both:

&IONS
&CELL

Missing either required namelist results in an ERROR.

Smearing consistency

If:

occupations = 'smearing'

VQkit checks whether:

smearing
degauss

are explicitly defined.

Missing smearing produces a warning.

Missing or non-positive degauss also produces a warning.

A complete setup such as:

occupations = 'smearing'
smearing = 'mv'
degauss = 0.02

is reported as valid.

Calculation identity

VQkit reports the detected:

prefix
calculation

as informational metadata.

For example:

prefix = graphene
calculation = scf

pseudo_dir validation

VQkit resolves:

pseudo_dir

relative to the QE input directory when necessary.

The directory must exist.

If it does not:

[ERROR] pseudo_dir

is reported.

Pseudopotential file validation

VQkit reads the UPF filename associated with every ATOMIC_SPECIES entry.

It then verifies that each referenced file exists in pseudo_dir or at the specified absolute path.

Example:

ATOMIC_SPECIES
  C  12.011  C.UPF
  O  15.999  O.UPF

If C.UPF exists but O.UPF does not, VQkit reports an ERROR listing the missing species/file pair.

Example:

[ERROR] Pseudopotential files
Missing: O:O.UPF

This is a blocking issue.

outdir

VQkit also resolves:

outdir

If the directory already exists, it is reported as informational.

If it does not yet exist, VQkit reports that it will need to be created and writable at run time.

A missing outdir directory is not automatically treated as a blocking error because QE can create suitable directories during execution depending on the environment.

QE example report

A typical report may look like:

VQkit pre-flight calculation check

Directory    : /path/to/qe
DFT code     : Quantum ESPRESSO
Calculation  : scf
Input file   : scf.in

[OK]      Input file - scf.in
[OK]      &CONTROL - Namelist present.
[OK]      &SYSTEM - Namelist present.
[OK]      &ELECTRONS - Namelist present.
[OK]      nat - 2 atoms declared.
[OK]      ntyp - 1 species declared.
[OK]      ATOMIC_SPECIES - 1 species entries: C.
[OK]      ntyp vs ATOMIC_SPECIES - Counts match.
[OK]      ATOMIC_POSITIONS - 2 coordinate rows.
[OK]      CELL_PARAMETERS - Three lattice vectors found.
[OK]      ecutwfc - 60 Ry
[OK]      ecutrho - 480 Ry
[OK]      K_POINTS mesh - 12 12 1; shift 0 0 0.
[OK]      pseudo_dir - /path/to/qe/pseudo
[OK]      Pseudopotential files - All referenced UPF files are present.

[READY]

READY logic

VQkit determines final readiness from the number of ERROR items.

READY

If there are:

0 errors
0 warnings

the report ends with:

[READY] No blocking errors or warnings were found.

READY WITH WARNINGS

If there are:

0 errors
1 or more warnings

the report ends with:

[READY WITH WARNINGS]

This means VQkit found no blocking syntax or consistency problem, but manual review is still required.

NOT READY

If there is at least one ERROR:

[NOT READY]

The ERROR items should be corrected before submitting the calculation.

What the checker does not validate

The pre-flight checker is intentionally conservative.

A READY result does not prove that the calculation is scientifically correct.

VQkit does not automatically determine whether:

the chosen exchange-correlation functional is appropriate;
a Hubbard U value is justified;
a magnetic ordering is physically correct;
a k-point mesh is converged;
a plane-wave cutoff is converged;
a vacuum region is sufficiently thick;
a slab requires dipole correction;
an NEB pathway is physically meaningful;
a smearing width is optimal;
the structure represents the intended phase;
the chosen pseudopotential variant is the best one.

These remain scientific decisions.

Recommended workflow

Before submitting a VASP calculation:

Generate or prepare the input files.
Verify the structure.
Verify POTCAR species order.
Verify pseudopotential variants.
Check ENCUT.
Check KPOINTS.
Check spin settings.
Run the pre-flight check.
Resolve all ERROR items.
Review all WARNING items.
Submit the calculation.

Before submitting a QE calculation:

Verify &CONTROL and &SYSTEM.
Check nat and ntyp.
Verify ATOMIC_SPECIES.
Verify all UPF files.
Check ATOMIC_POSITIONS.
Check the lattice definition.
Review ecutwfc and ecutrho.
Check K_POINTS.
Check relaxation-specific namelists where required.
Run the pre-flight check.
Resolve all ERROR items.
Review all WARNING items.

Scientific responsibility

The purpose of the pre-flight checker is to reduce avoidable setup mistakes.

It should be treated as a technical and consistency check, not as an automatic scientific approval system.

As emphasized in the original VQkit guide:

VQkit does not replace scientific judgment.

Users must still verify all system-specific settings before production calculations.