Module 02 · VASP practical starting point

Getting Started with VASP: Four Files to Reliable Results

Use a two-atom silicon primitive cell to complete input understanding, convergence experiments, structure optimization and output checking.

The input examples in this manual have been checked against the data and have not yet been verified by VASP actual calculations case by case. When using, it must be combined with software version, pseudopotential and specific system verification.

01

Understand What You Are Running

01 · Environment and task boundaries

This chapter takes "a silicon unit cell" from a structure on paper to a traceable computational task. The goal is not to memorize a long list of parameters, but to know what each input determines, what each output answers, and when to stop and check. It is recommended to read it first Fundamentals of Quantum Chemistry Periodicity, plane waves and self-consistent fields in the chapter, and then proceed in the order of this chapter.

Scope of application: Common VASP 6 series, PAW-PBE, SOC-free periodic crystals are used as the main line. The values given are the starting point for teaching. You must perform a convergence check on the potential file and target physical quantities you actually use. This website does not run VASP and does not provide calculated energies, lattice constants or band gaps.

VASP is licensed software, web pages and input templates do not provide programs or POTCAR. First confirm that you belong to the authorized user group, and then obtain the installed modules, potential file location, queue name and job submission method from the research group or computing center. The school's Linux cluster usually has already compiled VASP; it is not recommended to deal with the three issues of compilation, MPI and material model at the same time when you are just getting started.

program Common uses How to choose in this tutorial
vasp_std General k-point sampling and collinear spin calculations The 8×8×8 grid in this chapter uses it
vasp_gam Dedicated implementation of only Γ point "Γ center grid" does not equal "Γ point only"; this chapter cannot use it instead
vasp_ncl Non-collinear spin and spin–orbit coupling Change the executable program when entering the SOC section

You can edit files, view existing output and do light pre-checking on the login node; formal calculations should be submitted to the computing node. The more CPU cores you have, the better: the two-atom exercise is only suitable for small-scale resource testing. The parallel settings of different compilation versions, MPI, and CPU/GPU backends are not universal. First, use the startup method that has been verified by the computing center. Record the exact version number and compilation environment. This information is more useful when encountering errors than "I used VASP".

Self-examination before starting: Can I see a normal text file in a text editor? Do you know the directory you are currently in? Can I check the job status? Which release version of PBE does the potential file belong to? If these questions are still unclear, complete this chapter "Cluster Operations" before submitting the task.

Check basis: Official installation instructions · VASP license

Back to top ↑
02

Four Input Files: From Model to Calculation

02 · Document Map

Putting each calculation into a separate directory makes it easier to locate problems than overwriting files in the same folder repeatedly. A common calculation requires at least the following four files, and the names are case-sensitive. They are mutually constrained: whatever elements are written in the structure, the potential files must be provided in the same order; whatever functional is selected, it must also be checked whether the potential used is compatible with the calculation settings.

File Answered questions Check before submitting
POSCAR What kind of structure is it? Lattice, element order, atomic number, coordinate type and nearest neighbor distance
POTCAR How to deal with ion real and valence electrons? PAW data set, ranking order, number of valence electrons, ENMAX for each element
KPOINTS How to integrate in reciprocal space? Mesh density, Γ centers/offsets, compatibility with lattice symmetry
INCAR What approximation and solution conditions are used? functional, cutoff energy, electron/ion convergence, occupation, magnetism and output

POSCAR's scaling factor multiplies the three lattice vectors; use Direct , the three numbers are fractional coordinates relative to the lattice vector, not Å. If using Cartesian , the coordinates are also affected by the scaling factor. The element row is a human-readable label. The actual ion type also depends on the POTCAR and atomic number grouping, so only changing the element name without changing the potential file does not actually change the element.

POTCAR is obtained from the authorized potential library, and its parameters do not need to be rewritten manually. A structure containing two elements A and B A B When arranging, POTCAR should also be A first and then B; and MAGMOM Usually arranged per atom, LDAUU etc. are arranged according to each element. This distinction between "by atoms" and "by species" will appear again in the chapter on magnetism.

INCAR recommends one parameter per line, and uniformly use English half-width symbols. Comments are used to explain the reasons for selection. Do not put Chinese descriptions directly after the values without comments. Don’t leave multiple contradictory statements in the same document ENCUT or ISPIN ;The value actually read by the program should be checked in OUTCAR.

Output Purpose It cannot be independently concluded based on this
OUTCAR Actual parameters, energies, forces, stresses and detailed diagnostics The presence of files does not mean the operation was successful.
OSZICAR Concise electron and ion iteration records Small changes in energy do not mean that the structure has been fully optimized
CONTCAR Structure at the end of the run It will also be written when the maximum number of steps is reached, which may not be a convergent structure.
CHGCAR / WAVECAR charge density / wavefunction , available for compatible subsequent calculations It is not a universal cache that can be reused across structural, functional, and magnetic states at will.
vasprun.xml / vaspout.h5 Structured output suitable for post-processing; HDF5 files depend on compilation settings Parsing out the numbers does not mean that the physical assumptions are correct

Check basis: POSCAR · POTCAR · INCAR · OUTCAR

Back to top ↑
03

Your First Task: SCF Calculation of Primitive Silicon

03 · Complete input

Question: Fixing the ion position, find the ground state electron density of this periodic silicon structure under the PBE approximation. "Static" here means that the atoms are not moving, not turning off electronic iterations. Begin by familiarizing yourself with a nonmagnetic, two-atom system before moving on to transition metals and surfaces.

The following POSCAR uses a two-atom primitive cell with a diamond structure. The lattice parameter 5.43 Å is the initial value for learning, not the optimization result obtained in this tutorial. The three primitive cell vectors are not perpendicular to each other, and the volume is one-quarter of that of a conventional cubic unit cell. Do not use the subsequent primitive cell k path directly to a regular unit cell containing eight atoms.

Diamond Si primitive cell; a=5.43 A
5.4300000000
0.0000000000 0.5000000000 0.5000000000
0.5000000000 0.0000000000 0.5000000000
0.5000000000 0.5000000000 0.0000000000
Si
2
Direct
0.0000000000 0.0000000000 0.0000000000
0.2500000000 0.2500000000 0.2500000000

Create si-scf directory, save the KPOINTS below. Gamma in the third line indicates that the grid is centered on Γ; 8 8 8 in the fourth line indicates the number of divisions in the three reciprocal lattice vector directions. This is an automatically generated uniform grid, the second line 0 means generated by grid rules, not "compute zero k-points". Symmetry reduces the grid to irreducible k points.

Si uniform Gamma-centered mesh
0
Gamma
8 8 8
0 0 0
One step you must take before submitting: View each of your own POTCAR ENMAX . below ENCUT=520 Values for instruction only, must first be no less than the maximum ENMAX among them, and must pass convergence experiments. If your potential requires higher cutoff energy, increase the ENCUT uniformly for all relevant tasks in this lesson.
SYSTEM = Si PBE SCF learning example
GGA = PE
ENCUT = 520
PREC = Accurate
LREAL = .FALSE.
ISPIN = 1
ISTART = 0
ICHARG = 2
ALGO = Normal
EDIFF = 1E-6
NELM = 120
ISMEAR = 0
SIGMA = 0.05
IBRION = -1
NSW = 0
LCHARG = .TRUE.
LWAVE = .TRUE.
parameters The meaning this time How to migrate to other systems
GGA=PE Choose PBE GGA Companion check PAW-PBE potential; functional selection belongs to the physical model
ENCUT=520 Upper limit of plane wave energy, unit eV The potential file converges with the target accuracy, not "all material standard values"
PREC=Accurate Use finer internal grid settings Not a replacement for ENCUT and k-grid testing
LREAL=.FALSE. Handling projection operators in reciprocal space Suitable for this small primitive cell; large system can test the accuracy and speed of Auto
ISPIN=1 In this case, non-spin polarization If it contains magnetic elements or free radicals, it must be re-judged.
ISTART=0; ICHARG=2 Start from scratch and construct a first guess using the superposition of atomic charges. To facilitate independent reproduction of experiments; subsequent reading of CHGCAR must clearly change ICHARG
ALGO=Normal Use commonly used electronic solving algorithms When the calculation does not converge, diagnose first and then convert the algorithm
EDIFF=1E-6 Energy stopping threshold for electronic iterations, eV/calculated unit cell Not a per-atom error, nor absolute accuracy of the final energy
NELM=120 Maximum number of electronic iterations steps Running it full usually indicates that the stopping condition has not been met
ISMEAR=0; SIGMA=0.05 Gaussian smearing, width 0.05 eV Good for this introductory semiconductor example; also check for smearing sensitivity
IBRION=-1; NSW=0 Does not update ion position Distinguished from structurally optimized ion cycles
LCHARG/LWAVE=.TRUE. Preserve charge density and wavefunction Will increase disk usage; save SCF evidence before performing subsequent tasks

POTCAR: Only one Si PAW-PBE data set is required. The specific version is determined by your authorization environment. The download package does not include this file. After the run is completed, use OUTCAR to check that the ion number is 2, the element and valence electron settings are correct, and the final electron cycle reaches EDIFF. Success cannot be judged by "the total energy decimal is exactly the same as others', because different potential versions and numerical settings will change the total energy baseline.

Small exercise: Open POSCAR in a visualization software, explain why the fractional coordinates of the second Si are (¼,¼,¼), and convert it to Cartesian coordinates based on the lattice vector. Read the unit cell volume of OUTCAR and compare it to your hand calculation of a³/4. This is a better way to rule out structural errors than staring at a pretty band structure diagram first.

Check basis: ENCUT · KPOINTS · EDIFF · LREAL · PREC · ALGO

Back to top ↑
04

Convergence Tests: Establish Numerical Accuracy

04 · ENCUT and k-grid

Electron circulation reaching EDIFF simply indicates that the solution is complete with the current basis set, current mesh, and current approximation. It doesn't tell you whether there are enough plane waves or whether the Brillouin zone is sufficiently sampled. A true convergence test compares whether the target quantity is stable as the value is set and encrypted. You can think of it as adjusting the resolution of a microscope: only when the picture no longer changes significantly can you discuss the details in the picture.

  1. First fix the geometry and all physics settings. This exercise always uses the same si-scf/POSCAR, the same POTCAR, and does not optimize the structure separately at each cutoff energy.
  2. Test ENCUT. Fix a temporarily denser uniform mesh, changing only the cutoff energy. You can choose 5-6 consecutively increasing values from above max(ENMAX); 400, 450, 500, 550, 600 eV can be used as an example sequence only if they are not lower than your max(ENMAX).
  3. Test k-grid. Using the cutoff energy that has become stable in the first round, compare 4³, 6³, 8³, 10³, 12³ and other Γ center grids of the same family; if 12³ is still unstable, continue to refine.
  4. Do cross-checks. Raise ENCUT one more time on the final selected k grid to confirm that the first round conclusions are not obscured by the coarse grid.

Each group generates charge densities from scratch and uses independent catalogs. The download script below only builds the input, does not run VASP, and does not automatically submit dozens of jobs. It requires the use of static INCAR of "one parameter per line" on this page, ignores comments after #/!, rejects duplicate parameters and semicolon multi-parameter lines; NSW > It will stop when 0 or IBRION is not −1 to prevent mistakenly treating the structural optimization source as a fixed geometry test. The k-grid test also checks that the source ENCUT is not lower than the potential file maximum ENMAX. If the target directory already exists, it will also stop to avoid overwriting the previous results. The script only copies the authorized POTCAR within your own computing environment and should not upload the entire generated directory to a public repository.

# Run in the common parent of the examples directory; check the actual ENMAX first
python3 prepare_convergence.py encut si-scf conv-encut 400 450 500 550 600
# First update the ENCUT in si-scf/INCAR to the tested selected value, and then do this group
python3 prepare_convergence.py kmesh si-scf conv-kmesh 4 6 8 10 12
Expand to view the directory generation script
#!/usr/bin/env python3
"""Prepare independent input directories only. Does not submit jobs or run VASP."""
import argparse
import csv
import math
from pathlib import Path
import re
import shutil

p = argparse.ArgumentParser()
p.add_argument("mode", choices=["encut", "kmesh"])
p.add_argument("source", type=Path)
p.add_argument("destination", type=Path)
p.add_argument("values", nargs="+", type=float)
a = p.parse_args()
source = a.source.resolve()
destination = a.destination.resolve()
for name in ["INCAR", "POSCAR", "KPOINTS", "POTCAR"]:
    if not (source / name).is_file():
        raise SystemExit(f"Missing source input: {name}")
if destination.exists():
    raise SystemExit("Destination exists; choose a NEW directory to avoid overwriting")
incar = (source / "INCAR").read_text(encoding="utf-8")
potcar = (source / "POTCAR").read_text(encoding="utf-8", errors="replace")
limits = re.findall(r"ENMAX\s*=\s*([0-9.]+)", potcar)
if not limits:
    raise SystemExit("ENMAX not found; inspect POTCAR before proceeding")
max_enmax = max(map(float, limits))
# Restrict this educational generator to an unambiguous static source INCAR.
settings = {}
for number, raw in enumerate(incar.splitlines(), start=1):
    clean = re.split(r"[!#]", raw, maxsplit=1)[0].strip()
    if not clean:
        continue
    if ";" in clean or clean.count("=") != 1:
        raise SystemExit(f"Use one unambiguous tag per line (INCAR line {number})")
    key, value = (part.strip() for part in clean.split("=", 1))
    key = key.upper()
    if key in settings:
        raise SystemExit(f"Duplicate INCAR tag: {key}")
    settings[key] = value
try:
    nsw = int(settings.get("NSW", "0"))
    ibrion = int(settings.get("IBRION", "-1"))
except ValueError:
    raise SystemExit("NSW and IBRION must be plain integers")
if nsw > 0 or ibrion != -1:
    raise SystemExit("Source must be STATIC: NSW <= 0 and IBRION = -1; do not use a relaxation INCAR")
if a.mode == "kmesh":
    try:
        cutoff = float(settings["ENCUT"].replace("D", "E").replace("d", "e"))
    except (KeyError, ValueError):
        raise SystemExit("kmesh source must set an explicit numeric ENCUT")
    if not math.isfinite(cutoff) or cutoff < max_enmax:
        raise SystemExit(f"Source ENCUT must be >= max ENMAX ({max_enmax} eV)")
values = a.values
if any(not math.isfinite(x) or x <= 0 for x in values):
    raise SystemExit("Values must be positive finite numbers")
if len(set(values)) != len(values):
    raise SystemExit("Duplicate values")
if a.mode == "encut" and min(values) < max_enmax:
    raise SystemExit(f"All ENCUT values must be >= max ENMAX ({max_enmax} eV)")
if a.mode == "kmesh" and any(x != int(x) for x in values):
    raise SystemExit("k mesh values must be positive integers")
# This generator expects the distributed one-tag-per-line INCAR, not an arbitrary INCAR.
base = []
for line in incar.splitlines():
    key = line.split("=", 1)[0].strip().upper()
    if key not in {"ISTART", "ICHARG", "LWAVE", "LCHARG"} and not (a.mode == "encut" and key == "ENCUT"):
        base.append(line)
base += ["ISTART = 0", "ICHARG = 2", "LWAVE = .FALSE.", "LCHARG = .FALSE."]
destination.mkdir(parents=True)
rows = []
for value in values:
    label = f"{value:g}"
    run = destination / (("e" if a.mode == "encut" else "k") + label)
    run.mkdir()
    for name in ["POSCAR", "POTCAR"]:
        shutil.copy2(source / name, run / name)
    text = "\n".join(base) + "\n"
    if a.mode == "encut":
        text += f"ENCUT = {value:g}\n"
        shutil.copy2(source / "KPOINTS", run / "KPOINTS")
    else:
        n = int(value)
        (run / "KPOINTS").write_text(f"Gamma mesh convergence\n0\nGamma\n{n} {n} {n}\n0 0 0\n", encoding="utf-8")
    (run / "INCAR").write_text(text, encoding="utf-8")
    rows.append([run.name, a.mode, label, "prepared_not_run"])
with (destination / "manifest.csv").open("w", newline="", encoding="utf-8") as f:
    writer = csv.writer(f)
    writer.writerow(["directory", "variable", "value", "status"])
    writer.writerows(rows)
print(f"Prepared {len(rows)} independent folders; submit manually after review")

Compare using a unified energy definition, such as the same smearing energy(sigma→0) , and record both the free energy and entropy terms; do not mix one set of TOTEN with another set of E0 in one table. For this two-atom primitive cell, the unit cell energy difference is divided by 2 to obtain eV/atom. For phase stability, adsorption energy or potential barriers, the corresponding energy difference itself must ultimately be examined, not just the total energy in isolation.

record column What to fill in Judgment method
ENCUT/k grid The actual read value of each group Check from OUTCAR, don't just trust the directory name
E / atom Unified energy divided by the number of atoms Draw relative to the finest reference value
Maximum residual force/stress Forces and stresses on the same structure Energy stability does not guarantee that derivatives are also stable
Computation time and memory Scheduling output and OUTCAR logging Compare costs only after accuracy is met
Whether electronic convergence Yes/No and reason for failure Failure points should not be treated as normal trend data

In class, "less than 1 meV/atom compared with the two finer groups" can be temporarily taken as the energy convergence practice target, but this is not a unified standard for all topics. If you want to discuss a magnetic anisotropy of 0.5 meV/atom, this threshold is obviously not enough. At least the last few points are required to form a stable trend, and it cannot be declared completed when just two points are close.

Research habits: Save the convergence curve as part of the result. Writing "ENCUT=520 eV" only reports the setting; writing "After increasing to 600 eV, the target energy difference changes less than the predefined threshold" reports the evidence. The latter sentence can only be used after actually completing the corresponding test.

Check basis: cutoff energy and comparability · k-point grid rules · Volume and numerical convergence

Back to top ↑
05

Structure Optimization: Atoms, Cells, and Stationary Points

05 · Forces, stresses and degrees of freedom

SCF aligns electrons on a fixed structure; structural optimization moves atoms between multiple SCFs and changes the unit cell if necessary. The negative derivative of energy with respect to atomic displacement is force, and the response of energy to strain determines stress. What optimization wants is for the electrons to converge enough to make the forces credible, and then use these forces to update the structure. Too loose electron convergence can introduce numerical noise into the ion optimizer.

in brand new si-relax Put the POSCAR, the same POTCAR and the converged uniform KPOINTS of Si in the previous section into the directory, and then use the following INCAR. 520 eV should only be retained if it meets your volume optimization accuracy requirements. First check the commonly used starting point of approximately 1.3×max(ENMAX) for an increased cutoff, then choose the actual value through residual-stress checks and tests at still higher cutoffs.

SYSTEM = Si PBE cell relaxation learning example
GGA = PE
ENCUT = 520
PREC = Accurate
LREAL = .FALSE.
ISPIN = 1
ISTART = 0
ICHARG = 2
ALGO = Normal
EDIFF = 1E-7
NELM = 120
ISMEAR = 0
SIGMA = 0.05
IBRION = 2
ISIF = 3
NSW = 100
POTIM = 0.5
EDIFFG = -0.01
LCHARG = .FALSE.
LWAVE = .FALSE.
parameters function Reason for selection in this case
IBRION=2 Conjugated Gradient Ion Optimization A common and robust solution suitable for entry-level; large systems close to the minimum value can also be tested IBRION=1
ISIF=2 Relax the atomic positions and fix the unit cell Common to surface, fixed strain, and determined lattice; not used for finding complete equilibrium lattice
ISIF=3 Relax atomic positions, unit cell shape, and volume This example is three-dimensional bulk silicon, allowing lattice optimization
NSW=100 Maximum number of ion steps The upper limit is not a goal, and completing the number of steps is not proof of convergence.
POTIM=0.5 Step size related parameters of this optimization algorithm does not mean that 0.5 fs of molecular dynamics was performed at this time
EDIFFG=-0.01 Stop based on force subject to optimized degrees of freedom, eV/Å The negative sign is very important; the positive value changes to the adjacent ion step energy change condition
EDIFF=1E-7 Tighter electronic stopping conditions Make residual force inspection less affected by electronic noise

The fractional coordinates of two atoms in an ideal silicon structure may have zero net force from the start, but the initial unit cell volume is still not necessarily optimal. Therefore, in this example we cannot just look at whether the atomic coordinates have changed, but also compare the lattice, volume and final stress. For surfaces with fixed partial atoms, the optimization conditions only apply to the degrees of freedom allowed for motion, and the forces retained by the fixed atoms are still worth checking and reporting.

Why does Pulay stress occur? The finite plane wave basis set changes with the unit cell, and its incompleteness errors can appear as additional stresses. Therefore, "external pressure is close to zero" does not necessarily mean reliable equilibrium volume at very low cutoff energy. Using a higher cutoff energy, a sufficiently fine mesh, and starting over from an optimized structure is a practical way to check the stability of the lattice; don't just add a PSTRESS number to "zero" the stress.

Completion conditions: It is seen that the ion optimization stop conditions are indeed met, and the last few electron cycles have converged; check the forces on the final optimized degrees of freedom, the stresses related to the lattice degrees of freedom, and the structural rationality. Check CONTCAR for unreasonably short bonds or unexpected collapse. Finally, a more refined static calculation review is needed. What geometric optimization finds is a local stationary point, whether it is a stable minimum, whether there is a lower energy structure, and also involves phonon and structure search.

When can't you just copy ISIF=3?

Two-dimensional materials or surfaces containing a vacuum layer cannot allow the algorithm to treat the vacuum as a lattice contraction to be optimized; first determine the in-plane lattice and vacuum settings, usually only relax the internal atoms, and then handle the in-plane strain according to the research purpose. External strains, defective supercells, interfaces and molecular boxes also need to be explicitly fixed which boundary conditions are fixed. Don’t think just because 3 is bigger than 2 it’s more “advanced”.

Check basis: ISIF degrees of freedom · ion optimization algorithm · EDIFFG symbol · Pulay stress and volume

Back to top ↑
06

Static Calculations and Reading the Outputs

06 · The result is not an energy number

Structural optimization and final property calculations are usually done separately. The focus of the former is to find the structure, while the latter uses uniform and strict numerical settings to generate comparable energy, charge and electronic states without moving ions. Especially after the last ion update, any old CHGCAR should not be taken as being a converged density corresponding to the final structure without checking.

in new si-static In the directory, put the ones that have been verified for convergence si-relax/CONTCAR Copy as POSCAR, using the same POTCAR. The 12³ grid and 520 eV below are also examples, the actual chosen values must come from your convergence experiments. To reduce restart confusion for beginners, the choice here is to make electron self-consistent from scratch; it may be slower than properly reusing wavefunctions, but the path is clear.

SYSTEM = Si final static learning example
GGA = PE
ENCUT = 520
PREC = Accurate
LREAL = .FALSE.
ISPIN = 1
ISTART = 0
ICHARG = 2
ALGO = Normal
EDIFF = 1E-7
NELM = 120
ISMEAR = 0
SIGMA = 0.05
IBRION = -1
NSW = 0
LCHARG = .TRUE.
LWAVE = .TRUE.
Si final uniform Gamma-centered mesh
0
Gamma
12 12 12
0 0 0

This INCAR with IBRION=-1, NSW=0 leaves the structure fixed; the electron threshold is tighter and the mesh is denser than in the first task. The CHGCAR it saves can be used as input for the PBE band structure calculation in the next chapter. Its corresponding POSCAR must be recorded at the same time, rather than just saving CHGCAR in isolation.

where to look What to see why
OUTCAR beginning and parameter area VASP version, element, ENCUT, k-point, functional, spin Prevent actual input from being different than expected
OSZICAR's electronic iterations line dE, d eps, rms(c) changes with the number of steps Distinguish between stable convergence, oscillation, and stopping at maximum number of steps
OUTCAR'S ENERGY ZONE Free energy TOTEN, entropy-free energy, sigma→0 extrapolation energy They are not always the same number; definitions must be stated when comparing
OUTCAR final force and stress Force vector, maximum optimized force, pressure and stress components Static recalculation can expose residual errors from the previous step of optimization
Scheduling log ends with OUTCAR Exit code, truncate file, normal end information The normal end should also be judged together with the electronic convergence information.

Electronic EDIFF compares energy changes between adjacent iterations, not "DFT vs. experiment error less than 10⁻⁷ eV". Even if the numerical convergence is excellent, the functional approximation, temperature, defect concentration, and model boundary conditions can still lead to larger deviations from the band structure. Writing down numerical errors and model errors clearly is an important step in learning computational chemistry.

The absolute value of the total energy is usually large and dependent on the reference base of the potential, and studies more often compare the energy difference under controlled conditions. The stability of structures composed of different elements cannot be directly ranked according to the total energy. Appropriate definitions such as formation energy, chemical potential or phase diagram are needed. When comparing different atomic numbers, you should first clarify whether it is per atom, per chemical formula, or the entire supercell.

Data delivered to the next step: POSCAR to confirm convergence, four-input hash and parameter record, CHGCAR, necessary WAVECAR, OUTCAR, OSZICAR, structured output and job log. Don’t just leave a screenshot or handwritten energy; if you find a setting is wrong later, a complete record will allow you to determine which results need to be redone.

Check basis: OSZICAR field · CHGCAR content and restart · Electronic convergence conditions

Back to top ↑
07

Linux and Clusters: Submitting a Calculation

07 · Safe, changeable job templates

The following commands are for Linux cluster terminal use and are not Windows PowerShell commands. Use first pwd Confirm the location and then look at the directory contents. Use the new directory for all official calculations; make sure there are no files on the target that need to be retained before copying. Do not perform recursive deletion when the path is unclear, and do not interpret "run again" as directly erasing the evidence of the last failure.

pwd
ls -lh
head -n 12 POSCAR
cat INCAR
cat KPOINTS
grep -E 'TITEL|ZVAL|ENMAX' POTCAR
sha256sum INCAR POSCAR KPOINTS POTCAR
# The following is executed from the common upper-level directory; mkdir is only executed when creating a new directory from scratch.
# If the supporting package already has si-static, first confirm that the old results are not mixed in, and skip the following line
mkdir si-static
# Verify that si-relax has indeed converged before copying; -i avoids silent coverage
cp -i si-relax/CONTCAR si-static/POSCAR
cp -i si-relax/POTCAR si-static/POTCAR

Slurm below Template to be configured , the file name starts with .template The end. Must put YOUR_PARTITION with YOUR_VASP_MODULE Replace it with the real value given by the computing center, check the number of cores, time limit, memory requirements and launcher, and then save as submit.slurm . Some machines use mpirun or a specific srun plug-in. The method given by the administrator should be used. The example cannot be used as a general configuration for the cluster.

Templates in companion packages are located in a common parent directory. After completing the configuration, save it as the submit.slurm , for example si-scf/submit.slurm . Before submitting, enter the actual directory where the four input files are saved; execute in the parent directory sbatch si-scf/submit.slurm It will not automatically change the submission directory into si-scf . Subsequent tasks also save their own scripts respectively and submit them from the corresponding directory.

#!/bin/bash
#SBATCH --job-name=si-scf
#SBATCH --partition=YOUR_PARTITION
#SBATCH --nodes=1
#SBATCH --ntasks=8
#SBATCH --cpus-per-task=1
#SBATCH --time=00:30:00
#SBATCH --output=slurm-%j.out
#SBATCH --error=slurm-%j.err

# Save the configured script as submit.slurm INSIDE the calculation directory.
# Submit after cd into that directory, where all four input files are present.
# For SOC/noncollinear tasks, replace BOTH vasp_std commands below with vasp_ncl.
set -euo pipefail
: "${SLURM_SUBMIT_DIR:?Submit through sbatch after editing placeholders}"
cd "$SLURM_SUBMIT_DIR"
module load YOUR_VASP_MODULE
export OMP_NUM_THREADS=1
for f in INCAR POSCAR KPOINTS POTCAR; do
  test -s "$f" || { printf 'Missing or empty input: %s\n' "$f" >&2; exit 1; }
done
command -v vasp_std >/dev/null
sha256sum INCAR POSCAR KPOINTS POTCAR > inputs.sha256
srun vasp_std > vasp.out 2>&1

#SBATCH lines are instructions for Slurm to request resources, not VASP parameters. The 8 MPI processes and 1 thread here demonstrate CPU work only; it is not a performance recommendation and does not apply to all GPU environments. set -euo pipefail Expose common script errors and failed commands earlier, and check input files to prevent accidental startup in the wrong directory. The input hash is recorded in the job directory and does not contain the potential file text.

# The configuration is completed and saved as si-scf/submit.slurm; the following starts from the common parent directory
# If you are already in si-scf, skip the cd line
cd si-scf
sbatch submit.slurm
squeue -u "$USER"
# Replaced with the numeric job number returned by sbatch
sacct -j YOUR_JOB_ID --format=JobID,State,Elapsed,ExitCode
# Observe the text in the actual calculation directory, do not change it while running INCAR
tail -n 30 OSZICAR
tail -n 40 vasp.out

It is normal for a job to not generate OUTCAR while waiting to be queued; if it stops suddenly after running, check for timeouts, memory limits, and node errors. When canceling a job, only cancel the specific job number you confirmed to avoid batch operations affecting other tasks. The input file should not be modified during calculation operation; when parameters need to be changed, create a new task directory and note the reason for the modification.

After submission, three corresponding relationships must be established: which structure the directory corresponds to; which run the job number corresponds to; and which set of actual parameters the result corresponds to. It is recommended to record “what hypothesis you want to test today” in your research notes instead of just “I ran 12 assignments today”. The time limit of 30 minutes in the template is not a guarantee by the software that the task will take time. The actual time taken depends on the hardware and compilation environment.

Check basis: Slurm sbatch official documentation · VASP environment and installation

Back to top ↑
08

Troubleshooting Convergence and Recording Your Work

08 · From successful operation to credible results

The easiest way to waste computing power is to increase both NELM and NSW to a very large value when you see failure. First determine which layer the failure occurs: whether the program can be started, whether the structure is reasonable, whether the electrons converge, whether the ions converge, and whether the target properties are stable with the numerical settings. Only by finding the right level and modifying parameters does it make sense.

phenomenon Check first Next step
Program not found/MPI error Modules, paths, starters and allocated resources Verify the environment with a small example approved by the Computing Center
An element or file error is reported just after startup. File name, text format, POSCAR/POTCAR order Correct the input and try again in the new directory
Electron energy oscillates violently Atomic overlap, occupation patterns, magnetism, wrong charges, old restart files Back to structures and models first; consider algorithms or mixing parameters later
Every ion step is completed with NELM Electronic convergence is not resolved and forces may be unreliable Pause optimization, fix the structure and solve SCF first
After the force decreases, it suddenly increases Step size, structural distance, electronic error, constraints View structure traces, not just the last line
Job ended but target threshold not reached Whether to timeout, exhaust NSW, read failure output Keep logs and mark non-convergence, not as normal data points
Different initial magnetic states give different results Are the local magnetic moments and structures the same? When comparing multiple candidate solutions, "unsightly" solutions cannot be directly deleted.

If the energy continues to oscillate, you can re-initialize it to exclude incompatible WAVECAR/CHGCAR, confirm that ISMEAR is suitable for the system, and then adjust ALGO or mixing parameters one by one according to the official electronic minimization instructions. Change only one justified option at a time and keep controls. Increasing NELM is only appropriate if convergence is indeed slowly approaching; extending the run without a downward trend is often just a matter of repeated failure.

As the number of atoms increases, the surface vacuum becomes thicker, and the system changes from an insulator to a metal, the original effective mesh and mixing parameters may need to be re-examined. Do not copy a line of parameters found based on an error report into all tasks without understanding it. When a program crashes, the error context, software version, minimum input, and operating environment should be saved, and sensitive files should only be shared through licensed channels.

Scientific issues also require independent investigation. For example, "the calculated lattice is larger than the experiment" may involve functional, temperature and zero-point vibration; "the band gap is too small" may come from the semi-local functional itself, which cannot be corrected by increasing SIGMA; "negative defect formation energy" may refer to errors in chemical potential or metrology relationships, which cannot be explained simply by increasing ENCUT.

# Calculation records: please fill in item by item
Scientific questions and hypotheses to be tested:
Structure source / primitive cell or supercell / number of atoms / charge state:
VASP version/compilation environment/executable program:
POTCAR RELEASE / TITEL / ZVAL / ENMAX / SHA-256:
functional/U and J/SOC/spin initial state:
ENCUT / PREC / k-grid / smearing:
Electron and ion stopping threshold/fixed degrees of freedom:
Convergence test target quantity/threshold/control directory:
Job ID/Date/Resource/Exit Status:
Whether electrons converge/maximum force/final stress:
Energy definition/unit/normalization used:
Post-processing tool version/script/graph data source:
Known limitations and next steps to verify:

Exercises to complete this chapter: Draw the ENCUT vs. k-grid convergence graph; compare the initial structure and the optimized structure; write a real "calculation method" with the final static OUTCAR; explain what your evidence can and cannot support. If you do not have cluster permissions for the time being, you can complete file reading, structure visualization, and experimental design first, but do not fill in the hypothetical energy as the running result.

Next step to enter Electronic structure: DOS, band structure, magnetism and charge analysis ;Use when you need to quickly locate parameters according to tasks Parameters and troubleshooting index . For tasks such as catalysis, phonon, and molecular dynamics, please first make sure you understand the convergence and recording methods in this chapter.

Check basis: ALGO and electronic iterations · NELM meaning · electron minimization method

Back to top ↑

Example Files for This Module

DOWNLOAD & CHECK

Read the file description and corresponding chapters first, and then complete the model, POTCAR and pre-calculation. Files with the suffix .template contain parameters to be changed and cannot be submitted as they are.

Silicone SCF · POSCAR ↓ si-scf/POSCAR

Teaching input; need to bring your own authorized Si POTCAR and check ENMAX and convergence.

Silicon SCF · KPOINTS ↓ si-scf/KPOINTS

Teaching input; need to bring your own authorized Si POTCAR and check ENMAX and convergence.

Silicone SCF · INCAR ↓ si-scf/INCAR

Teaching input; need to bring your own authorized Si POTCAR and check ENMAX and convergence.

Silicon SCF · README.txt ↓ si-scf/README.txt

Teaching input; need to bring your own authorized Si POTCAR and check ENMAX and convergence.

Silicon unit cell optimization · INCAR ↓ si-relax/INCAR

Paired with same silicon POSCAR/POTCAR with converged mesh; 520 eV volumetric optimization accuracy must be verified.

Silicon unit cell optimization · Operation instructions ↓ si-relax/README.txt

Optimization is not a completed calculation; please verify final forces and stresses.

Silicon Ultimate Static · INCAR ↓ si-static/INCAR

Copying POSCAR from si-relax/CONTCAR where convergence has been verified, the potential file remains consistent.

Silicon Final Static · KPOINTS ↓ si-static/KPOINTS

Copying POSCAR from si-relax/CONTCAR where convergence has been verified, the potential file remains consistent.

Silicon Final Static · Operating Instructions ↓ si-static/README.txt

The downloaded package does not create an optimized structure, you need to complete your own optimization first.

Standalone Convergence Catalog Generator ↓ prepare_convergence.py

Only generate the directory and input, do not submit or run VASP; will refuse to overwrite the target directory.

Slurm submission template ↓ submit.slurm.template

Queue and module placeholders must be replaced and the launcher adjusted as per Compute Center instructions.

Reproducible calculation records ↓ calculation-record.md.template

Fill in after each actual calculation, do not use hypothetical results.

Primary Sources & Further Reading

READ THE PRIMARY SOURCES

The main text is an independently organized study instruction. For label meanings and version differences, refer to the official documentation corresponding to your program version.

  1. VASP license
  2. Installation and executable programs
  3. POSCAR
  4. POTCAR
  5. INCAR
  6. KPOINTS
  7. ENCUT
  8. PREC
  9. LREAL
  10. EDIFF
  11. ALGO
  12. NELM
  13. ISIF
  14. IBRION
  15. EDIFFG
  16. Volume relaxation
  17. OUTCAR
  18. OSZICAR
  19. CHGCAR
  20. Slurm sbatch
  21. Electronic minimization
↑