vasp-band

name	vasp-band
description	VASP band structure calculation. Two-step workflow with SCF charge density followed by non-SCF band calculation along high-symmetry k-path.

VASP Band Structure Calculation

Compute electronic band structure along high-symmetry k-point paths. Requires a two-step process: self-consistent charge density, then non-SCF calculation along the k-path.

Why Two Steps?

1. Single point (SCF) — compute self-consistent charge density with a uniform k-mesh
2. Band calculation (non-SCF) — read the converged CHGCAR and compute eigenvalues along the high-symmetry k-path without updating the charge density

This separation is necessary because the high-symmetry k-path does not provide uniform Brillouin zone sampling needed for SCF convergence.

Full Band Structure Workflow

from catgo.workflow import Workflow
from catgo.workflow.builtins import geo_opt, single_point

wf = Workflow("TiO2 band structure")
struct = wf.add_task("structure_input", structure=structure_json)

# Step 1: Optimize (skip if already relaxed)
opt = wf.add_task(geo_opt, structure=struct.output.structure,
                  ISIF=3, system_name="relax")

# Step 2: SCF single point to generate CHGCAR
scf = wf.add_task(single_point, structure=opt.output.structure,
                  LCHARG=True,     # Write CHGCAR
                  EDIFF=1e-6,      # Tight convergence
                  system_name="SCF")

# Step 3: Non-SCF band calculation
band = wf.add_task(single_point, structure=opt.output.structure,
                   ICHARG=11,       # Read CHGCAR, do not update
                   LORBIT=11,       # Projected band character
                   LCHARG=False,
                   LWAVE=False,
                   kpath_mode="auto",  # Auto-detect high-symmetry path
                   kpath_density=40,   # Points per segment
                   system_name="bands")

wf.submit()

MCP Workflow

catgo_workflow_engine(action="create", params={"name": "Band structure"})

# Input structure
catgo_workflow_engine(action="add_task", params={
  "workflow_id": "wf_xxx",
  "task_type": "structure_input",
  "structure": "<json>"
})

# SCF single point
catgo_workflow_engine(action="add_task", params={
  "workflow_id": "wf_xxx",
  "task_type": "single_point",
  "software": "vasp",
  "structure": "{{t_001.output.structure}}",
  "LCHARG": true,
  "EDIFF": 1e-6,
  "system_name": "SCF"
})

# Non-SCF band calculation
catgo_workflow_engine(action="add_task", params={
  "workflow_id": "wf_xxx",
  "task_type": "single_point",
  "software": "vasp",
  "structure": "{{t_001.output.structure}}",
  "ICHARG": 11,
  "LORBIT": 11,
  "kpath_mode": "auto",
  "kpath_density": 40,
  "system_name": "bands"
})

catgo_workflow_engine(action="submit", params={"workflow_id": "wf_xxx"})

High-Symmetry K-Path

Automatic Path Detection

Set kpath_mode="auto" to let the engine detect the Bravais lattice and generate the standard k-path. This works for most crystal systems.

Manual K-Path

For custom paths, specify k-points explicitly:

band = wf.add_task(single_point, structure=opt.output.structure,
                   ICHARG=11,
                   kpath_mode="manual",
                   kpath_points={
                       "G": [0.0, 0.0, 0.0],
                       "X": [0.5, 0.0, 0.0],
                       "M": [0.5, 0.5, 0.0],
                       "G2": [0.0, 0.0, 0.0],
                       "R": [0.5, 0.5, 0.5],
                   },
                   kpath_segments=["G-X", "X-M", "M-G2", "G2-R"],
                   kpath_density=40,
                   system_name="bands")

Common K-Paths by Crystal System

System	Path	Example
FCC	G-X-W-K-G-L-U-W-L-K	Cu, Al, Pt
BCC	G-H-N-G-P-H	Fe, W, Cr
HCP	G-M-K-G-A-L-H-A	Ti, Ru, Co
Tetragonal	G-X-M-G-Z-R-A-Z	TiO2 rutile
Simple cubic	G-X-M-G-R-X	SrTiO3

Key Parameters

Parameter	Value	Purpose
ICHARG	11	Read CHGCAR, non-self-consistent
LORBIT	11	Atom- and orbital-projected bands
NBANDS	auto	Number of bands (increase for unoccupied states)
LCHARG	False	Do not overwrite CHGCAR from SCF step
LWAVE	False	Do not write WAVECAR (saves disk)
kpath_density	40	K-points per segment (more = smoother bands)

Spin-Polarized Band Structure

For magnetic systems:

scf = wf.add_task(single_point, structure=s,
                  LCHARG=True, ISPIN=2,
                  MAGMOM="2*5.0 4*0.6",
                  system_name="SCF_spin")

band = wf.add_task(single_point, structure=s,
                   ICHARG=11, ISPIN=2, LORBIT=11,
                   kpath_mode="auto", kpath_density=40,
                   system_name="bands_spin")

Hybrid Functional Band Structure (HSE06)

HSE06 band structure is expensive but more accurate for band gaps:

scf = wf.add_task(single_point, structure=s,
                  LCHARG=True, LHFCALC=True, HFSCREEN=0.2,
                  AEXX=0.25, ALGO="Damped", TIME=0.4,
                  system_name="SCF_HSE")

band = wf.add_task(single_point, structure=s,
                   ICHARG=11, LHFCALC=True, HFSCREEN=0.2,
                   AEXX=0.25, ALGO="Damped", TIME=0.4,
                   kpath_mode="auto", kpath_density=20,
                   system_name="bands_HSE")

Note: HSE band calculations are 10-100x more expensive than PBE. Use a lower kpath_density (20) and fewer NBANDS.

Combined DOS + Band Structure

Run both from the same SCF calculation:

scf = wf.add_task(single_point, structure=opt.output.structure,
                  LCHARG=True, EDIFF=1e-6, system_name="SCF")

# DOS branch
dos_sp = wf.add_task(single_point, structure=opt.output.structure,
                     ISMEAR=-5, NEDOS=3001, LORBIT=11,
                     system_name="DOS")

# Band branch
band = wf.add_task(single_point, structure=opt.output.structure,
                   ICHARG=11, LORBIT=11,
                   kpath_mode="auto", kpath_density=40,
                   system_name="bands")

Troubleshooting

Problem	Fix
Bands look wrong / discontinuous	CHGCAR from SCF may be on different k-mesh. Ensure SCF used uniform mesh
Band gap too small (PBE)	Expected — PBE underestimates gaps. Use HSE06 for accurate gaps
Missing unoccupied bands	Increase NBANDS (default may cut off conduction bands)
ICHARG=11 error	CHGCAR must exist from SCF step. Check SCF completed with LCHARG=True
Very slow HSE	Normal — reduce kpath_density, reduce NBANDS, use more nodes