hpc-vasp
Build, review, debug, and automate VASP first-principles workflows. Use when working with VASP input sets such as INCAR, POSCAR, KPOINTS, and POTCAR; when choosing SCF, relaxation, static, DOS, or ban
SKILL.mdskills/hpc-vasp/SKILL.md
GitHubHPC VASP Skill
Treat VASP as a staged workflow built around a coherent four-file input set.
Quick Start
Typical Workflow
- Acquire or prepare structure (CIF, POSCAR) — see references/10-structure-preparation.md
- Generate four-file input set (INCAR, POSCAR, KPOINTS, POTCAR) — see references/01-input-set-manual.md
- Select workflow stage (relax, static, DOS, bands) — see references/02-stage-and-parameter-matrix.md
- Configure INCAR tags for the stage — see references/07-incar-tag-matrix.md
- Set pseudopotential, k-points, and convergence controls — see references/03-pseudopotential-kpoints-and-convergence.md
- For DOS or band-structure workflows — see references/06-dos-and-band-workflows.md
- Configure restart and handoff between stages — see references/09-restarts-spin-and-wavefunction-files.md and references/12-workflow-handoff-matrix.md
- Submit to HPC cluster — see references/04-cluster-execution-playbook.md
- Handle errors — see references/05-error-recovery.md and references/error-pattern-dictionary.md
Skill Map
User Requirements
├─ Input Set Authoring
│ ├─ Four-file model (INCAR, POSCAR, KPOINTS, POTCAR) → 01-input-set-manual.md
│ ├─ Species order discipline, coordinate modes → 08-poscar-species-and-structure.md
│ └─ INCAR tag selection per stage → 07-incar-tag-matrix.md
├─ Workflow Stage Selection
│ ├─ Stage map (relax, static, DOS, bands) → 02-stage-and-parameter-matrix.md
│ ├─ INCAR controls per stage (IBRION, NSW, ISMEAR, SIGMA) → 07-incar-tag-matrix.md
│ └─ DOS / band-structure workflows → 06-dos-and-band-workflows.md
├─ Convergence & Cutoffs
│ ├─ POTCAR coherence and ENCUT selection → 03-pseudopotential-kpoints-and-convergence.md
│ ├─ K-point strategy (Gamma, Monkhorst-Pack, line-mode) → 03-pseudopotential-kpoints-and-convergence.md
│ ├─ Metallic vs insulating smearing → 03-pseudopotential-kpoints-and-convergence.md
│ └─ Material-specific parameters (DFT+U, magnetism) → 11-material-specific-parameters.md
├─ Structure Preparation
│ ├─ Download from Materials Project → 10-structure-preparation.md
│ ├─ Build with ASE (bulk, surface, molecule) → 10-structure-preparation.md
│ ├─ Format conversion (CIF → POSCAR) → 10-structure-preparation.md
│ └─ Generate VASP inputs with qvasp → 10-structure-preparation.md
├─ Restart & Handoff
│ ├─ ISTART/ICHARG logic, CONTCAR → POSCAR handoff → 09-restarts-spin-and-wavefunction-files.md
│ └─ Stage artifact and restart-file matrix → 12-workflow-handoff-matrix.md
└─ HPC Cluster Execution
├─ SLURM/PBS job scripts → 04-cluster-execution-playbook.md
├─ Stage-aware execution and artifact discipline → 04-cluster-execution-playbook.md
└─ Restart and continuation → 04-cluster-execution-playbook.md
Reference Documents
| Document | Content |
|---|---|
| references/01-input-set-manual.md | Four-file model (INCAR, POSCAR, KPOINTS, POTCAR), file responsibility matrix, stage-to-directory workflow |
| references/02-stage-and-parameter-matrix.md | Stage map (relax, static, DOS, bands), INCAR matrix, KPOINTS strategy |
| references/03-pseudopotential-kpoints-and-convergence.md | POTCAR coherence, metallic vs insulating logic, convergence troubleshooting |
| references/04-cluster-execution-playbook.md | SLURM/PBS scripts, preflight checks, stage-aware execution, srun vasp_std, restart/continuation |
| references/05-error-recovery.md | Input-set mismatches, SCF failures, ionic relaxation failures, workflow handoff failures |
| references/06-dos-and-band-workflows.md | DOS workflow, band-structure workflow, k-point mode differences, stage ordering |
| references/07-incar-tag-matrix.md | Stage-to-INCAR matrix, electronic-class-to-smearing (ISMEAR/SIGMA), relaxation controls (IBRION, NSW, ISIF) |
| references/08-poscar-species-and-structure.md | POSCAR structure, species order discipline, coordinate modes (direct/Cartesian), ISIF implications |
| references/09-restarts-spin-and-wavefunction-files.md | WAVECAR/CHGCAR/CONTCAR, ISTART/ICHARG logic, ISPIN/MAGMOM, practical continuation rules |
| references/10-structure-preparation.md | Materials Project download, ASE structure building, format conversion, qvasp toolkit |
| references/11-material-specific-parameters.md | Magnetic materials (ISPIN/MAGMOM), DFT+U (LDAUU/LDAUL), metals (ISMEAR/SIGMA), KSPACING |
| references/12-workflow-handoff-matrix.md | Stage-artifact matrix, restart-file matrix, KPOINTS handoff matrix |
| references/error-pattern-dictionary.md | Structured failure signatures: VASP_SPECIES_ORDER_MISMATCH, VASP_METAL_SMEARING_MISMATCH, VASP_RELAXATION_TOO_AGGRESSIVE, etc. |
Key Decision Points
| Question | Guide | Summary |
|---|---|---|
| Which workflow stage? | 02-stage-and-parameter-matrix.md | ionic relaxation (IBRION=2), static SCF (IBRION=-1, NSW=0), DOS, bands |
| What INCAR tags for this stage? | 07-incar-tag-matrix.md | Per-stage INCAR tag lookup |
| Metal or insulator? | 03-pseudopotential-kpoints-and-convergence.md | ISMEAR=0 (insulator), ISMEAR=1-2 (metal) |
| ENCUT value? | 10-structure-preparation.md | 1.2–1.3× max ENMAX in POTCAR |
| K-point mode? | 03-pseudopotential-kpoints-and-convergence.md | Gamma (supercells), Monkhorst-Pack (bulk), line-mode (bands) |
| Material magnetic? | 11-material-specific-parameters.md | ISPIN=2, MAGMOM initial values per element |
| DFT+U needed? | 11-material-specific-parameters.md | For transition metal oxides, LDA+U with appropriate U values |
| Running on HPC cluster? | 04-cluster-execution-playbook.md | srun vasp_std, preflight checks, stage directory discipline |
Guardrails
- Do not invent INCAR tags from other DFT codes — consult references/07-incar-tag-matrix.md
- Do not set
ENCUTbelow 1.2× maximumENMAXin POTCAR — insufficient cutoff causes convergence instability - Do not use
ISPIN=1for potentially magnetic materials without checking spin polarization - Do not leave
ISMEAR=1(metal smearing) for an insulator or semiconductor — see references/07-incar-tag-matrix.md - Do not run DOS or bands before geometry and ground-state SCF are trustworthy — see references/06-dos-and-band-workflows.md
- Do not change
prefixoroutdirbetween related stages (QE analog; VASP equivalent: CONTCAR, CHGCAR, WAVECAR discipline) — see references/09-restarts-spin-and-wavefunction-files.md and references/12-workflow-handoff-matrix.md
Outputs
Summarize:
- workflow stage (relax, static, DOS, bands)
- INCAR intent and key tags
- KPOINTS strategy and mode
- POTCAR and species assumptions
- expected key outputs (CONTCAR, OUTCAR, DOSCAR, etc.)
- next stage handoff plan
Template Files
Template files in assets/templates/ are ready-to-use starting scaffolds that can be copied and modified:
| Template | Type | Use Case | Reference |
|---|---|---|---|
| assets/templates/INCAR_relax | INCAR | Ionic relaxation (IBRION=2, NSW=100, ISIF=3) | 07-incar-tag-matrix.md, 02-stage-and-parameter-matrix.md |
| assets/templates/INCAR_static | INCAR | Static SCF (IBRION=-1, NSW=0, ISMEAR=-5) | 07-incar-tag-matrix.md, 06-dos-and-band-workflows.md |
| assets/templates/INCAR_bands | INCAR | Band structure (ICHARG=11, line-mode KPOINTS follow-on) | 06-dos-and-band-workflows.md, 09-restarts-spin-and-wavefunction-files.md |
| assets/templates/KPOINTS_gamma | KPOINTS | Gamma-only mesh for large supercells | 03-pseudopotential-kpoints-and-convergence.md |
| assets/templates/KPOINTS_mp_6x6x6 | KPOINTS | Monkhorst-Pack 6×6×6 mesh | 03-pseudopotential-kpoints-and-convergence.md |
| assets/templates/POSCAR_si | POSCAR | Si diamond structure (conventional cell) | 08-poscar-species-and-structure.md |
| assets/templates/vasp-standard-slurm.sh | Batch script | SLURM submission for VASP jobs | 04-cluster-execution-playbook.md |
Utility Scripts
Scripts in scripts/ assist with structure acquisition and VASP input generation:
| Script | Use Case | Reference |
|---|---|---|
| scripts/download_from_mp.py | Download CIF from Materials Project by material ID or formula | 10-structure-preparation.md |
| scripts/build_structure_ase.py | Build bulk crystals, surfaces, molecules with ASE | 10-structure-preparation.md |
| scripts/convert_structure.py | Convert structure files (CIF, XYZ, POSCAR, etc.) using pymatgen | 10-structure-preparation.md |
| scripts/read_with_ase.py | Read and convert structure files using ASE | 10-structure-preparation.md |
| scripts/generate_vasp_inputs.sh | Generate INCAR, KPOINTS from existing POSCAR/POTCAR using qvasp | 10-structure-preparation.md |
Error Recovery
Consult these documents for structured diagnosis:
- references/05-error-recovery.md — Input-set mismatches, SCF failures, ionic relaxation failures, workflow handoff failures
- references/error-pattern-dictionary.md — Structured failure signatures: VASP_SPECIES_ORDER_MISMATCH, VASP_STAGE_TAG_MISMATCH, VASP_METAL_SMEARING_MISMATCH, VASP_CUTOFF_OR_KMESH_TOO_WEAK, VASP_RELAXATION_TOO_AGGRESSIVE, VASP_WRONG_RELAXATION_SCOPE, VASP_DOS_WITH_WRONG_KPOINT_MODE, VASP_BANDS_WITH_WRONG_HANDOFF