VQkit Documentation

Unified VASP + Quantum ESPRESSO Toolkit

VQkit is a unified, file-based command-line toolkit designed to simplify the pre-processing and post-processing of density functional theory calculations performed with VASP and Quantum ESPRESSO.

The toolkit provides a consistent interface for preparing input files, organizing calculation workflows, checking convergence, analyzing electronic structure, processing charge-density data, evaluating trajectories, preparing reaction pathways, and extracting application-oriented materials properties.

Lead Developer: Rajkamal Anand, Ph.D.

Contributors: Dr. Prakash Govindaraj, Seunghwan Kwon, Prof. Gun Jin Yun, Prof. Hern Kim

License: MIT

Documentation

Getting Started

• Overview
  • Design concept
  • Unified interface
  • File-based architecture
  • Modular workflow design
  • User control
  • Local and HPC workflows
  • Extensibility
  • Scope
• Features
  • Pre-processing
  • Post-processing
  • Application-oriented analysis
  • VASP and Quantum ESPRESSO support
  • Output and visualization
• Installation
  • Requirements
  • Recommended installation
  • Windows
  • Linux
  • Linux / HPC
  • Verify installation
  • Install from source
  • Development installation
  • Updating VQkit
  • Uninstalling VQkit
  • Troubleshooting

Tutorials

• Tutorials
  • Start here
  • Electronic-structure tutorials
  • Charge and bonding tutorials
  • Dynamics and reaction-path tutorials
  • Tutorial index

Pre-processing

• Pre-processing
  • Calculation Setup
    • Main setup workflows
    • Create a new calculation
    • CIF to input
    • Output to input
    • VASP setup checks
    • Quantum ESPRESSO setup checks
    • Pre-flight validation
    • Related pages
  • Structure Editing
    • Height and layer analysis
    • Layer detection
    • Supported input structures
    • [4] Freeze / fix atoms
    • Choose fixed direction
    • How VQkit represents constraints
    • Selecting atoms to fix
    • Selection by height
    • Selection by layers
    • Selection by atom index
    • Output file for freeze/fix workflow
    • Existing output protection
    • QE atom ordering and mapping
    • Example: freeze bottom two VASP layers
    • Example: fix only z motion in QE
    • [5] Delete atoms
    • Selecting atoms to delete
    • Selection by atom label/type
    • Selection by layers
    • Selection by height
    • Deletion summary
    • Delete-atoms output files
    • VASP deletion behavior
    • Quantum ESPRESSO deletion behavior
    • Example: remove an adsorbate
    • Example: remove the top slab layer
    • Important scientific checks after editing
    • Height-based selection cautions
    • Layer tolerance
    • Recommended workflow
  • Validation
    • Meaning of report levels
    • Code detection
    • VASP pre-flight validation
    • INCAR checks
    • Repeated INCAR tags
    • Spin setup
    • Ionic-relaxation consistency
    • POSCAR checks
    • POTCAR checks
    • ENCUT versus ENMAX
    • KPOINTS validation
    • HPC job script
    • VASP example report
    • Quantum ESPRESSO pre-flight validation
    • Required QE namelists
    • nat and ntyp
    • ATOMIC_SPECIES
    • ATOMIC_POSITIONS
    • Lattice validation
    • Plane-wave cutoffs
    • K_POINTS validation
    • Relaxation-specific checks
    • Smearing consistency
    • Calculation identity
    • pseudo_dir validation
    • Pseudopotential file validation
    • outdir
    • QE example report
    • READY logic
    • What the checker does not validate
    • Recommended workflow
    • Scientific responsibility
  • Pseudopotentials
    • Why pseudopotential configuration matters
    • [8] Pseudopotential library setup
    • 1. Configure VASP POTCAR library
    • 2. Configure Quantum ESPRESSO UPF library
    • 3. Show configured pseudopotential libraries
    • 4. VQkit private pseudopotential folders
    • VASP licensing note
    • [7] Create POTCAR from POSCAR
    • POTCAR assembly
    • Missing potential
    • Existing POTCAR
    • Automatic POTCAR creation during calculation setup
    • Example: VASP Fe-O calculation
    • POTCAR and ENCUT
    • Example: Quantum ESPRESSO library setup
    • Scientific selection of pseudopotentials
    • Common problems
    • Licensing and redistribution
    • Recommended workflow
  • Reciprocal Space and Convergence
    • [9] Generate band-structure K-path
    • Symmetry tolerance scan
    • Symmetry-standardized path
    • Interpolation density
    • VASP path output
    • Quantum ESPRESSO path output
    • Built-in fallback path library
    • Band-path cautions
    • [10] K-points
    • Supported structures
    • Reciprocal lattice
    • Automatic k-spacing
    • Mesh formula
    • System dimensionality
    • Vacuum-gap estimation
    • Automatic dimensionality
    • 2D systems
    • 1D systems
    • 3D systems
    • Monkhorst-Pack mesh
    • Gamma-centered mesh
    • QE Monkhorst-Pack shifts
    • Irreducible k-points
    • Manual k-point mesh
    • K-point scientific cautions
    • [11] Convergence tests
    • VASP cutoff preparation
    • Quantum ESPRESSO cutoff preparation
    • Execution modes
    • Analyze completed cutoff calculations
    • Energy extraction
    • Reference energy
    • Recommended cutoff logic
    • Generated convergence outputs
    • Example: VASP cutoff convergence
    • Example: QE cutoff convergence
    • Convergence-test cautions
    • Recommended workflow
  • NEB Pre-processing
    • NEB concept
    • Open the NEB image generator
    • VASP NEB preparation
    • VASP endpoint requirements
    • VASP interpolation cautions
    • Recommended VASP workflow
    • Quantum ESPRESSO NEB preparation
    • QE NEB output file
    • QE CIF inspection images
    • Visual validation
    • What to inspect in every image
    • QE execution
    • Review before running QE NEB
    • Climbing-image NEB
    • Number of images
    • Cell consistency
    • Periodic boundary conditions
    • Atom ordering
    • Endpoint optimization
    • VASP preparation after interpolation
    • Quantum ESPRESSO preparation after interpolation
    • NEB convergence
    • Transition-state interpretation
    • Recommended VASP example
    • Recommended QE example
    • Connection to NEB post-processing
    • Scientific cautions
    • Recommended workflow

Post-processing

• Post-processing
  • General Calculation Analysis
    • Example
    • Basic workflow
    • Information reported
    • Code detection
    • Calculation-type detection
    • VASP status detection
    • Quantum ESPRESSO status detection
    • Input/output association
    • VASP total-energy extraction
    • Quantum ESPRESSO total-energy extraction
    • VASP Fermi-level extraction
    • Quantum ESPRESSO Fermi-level extraction
    • Example: completed VASP SCF
    • Example: completed QE SCF
    • Example: incomplete calculation
    • Interpreting the status correctly
    • Mixed directories
    • Why the summary is useful
    • Recommended post-processing sequence
    • Scientific cautions
    • Summary limitations
    • Recommended practice
  • Structural Analysis
    • Overview
    • VASP example
    • Quantum ESPRESSO example
    • Final-structure detection
    • Optimized structure / lattice / volume
    • Converting the final structure to a new input
    • Bond-length analysis
    • Choosing a bond cutoff
    • Bond-angle analysis
    • Atomic-height analysis
    • Layer analysis
    • Using layer analysis for slab systems
    • Choosing the layer tolerance
    • Example: analyze a relaxed VASP slab
    • Example: analyze a relaxed QE structure
    • Minimum-image convention
    • Scientific cautions
    • Recommended workflow
    • Generated files
  • Electronic Structure
    • General workflow
    • DOS - VASP
    • DOS - Quantum ESPRESSO
    • Projected DOS (PDOS)
    • Band structure - VASP
    • Band structure - Quantum ESPRESSO
    • Band outputs
    • Spin-polarized bands
    • Band-gap analysis
    • Band-gap cautions
    • Fermi energy
    • Work function
    • Quantum ESPRESSO work function
    • Work-function outputs
    • Relationship between the six menu items
    • Recommended analysis sequence
    • Common cautions
    • Generated files summary
  • Charge Density, Bader Charge, and ELF
    • Charge-density difference
    • CDD cube parsing
    • CDD plotting menu
    • CDD color convention
    • CDD outputs
    • Three-dimensional visualization
    • CDD interpretation cautions
    • Bader charge analysis
    • External dependency
    • Bader file-status check
    • Reference-density preparation
    • Running Bader analysis
    • Analyzing an existing ACF.dat
    • POTCAR ZVAL and net charge
    • Bader output
    • Additional ACF information
    • Bader interpretation cautions
    • Electron localization function
    • ELF range
    • ELF plotting menu
    • ELF contours
    • QE ELF preparation
    • ELF outputs
    • Three-dimensional ELF
    • Relationship between CDD, Bader, and ELF
    • Recommended combined workflow
    • Tutorial links
  • Energetics and Thermodynamics
    • Detected calculation and status
    • [1] Atom / molecule adsorption energy
    • [2] Doping formation energy
    • [3] NEB / transition-state analysis and plot
    • [4] Surface energy
    • [5] Single-atom vacancy formation energy
    • Common requirements for energetic comparisons
    • Energy versus free energy
    • Recommended workflow
    • Generated files summary
  • AIMD / Trajectory Analysis
    • General AIMD requirements
    • Time-step detection
    • Time convention
    • Variable-cell / NPT trajectories
    • Common XDATCAR prompt
    • Coordinate handling
    • Periodic unwrapping
    • [1] Trajectory summary
    • [2] Atomic position coordinates vs time
    • [3] Energy vs time
    • [4] Volume / lattice parameters vs time
    • [5] Bond distance vs time
    • [6] Mean-square displacement (MSD)
    • [7] Diffusion coefficient
    • [8] Radial distribution function (RDF)
    • [9] Coordination number vs time
    • Atom and group selection
    • Example: Li-ion diffusion
    • Example: bond-breaking trajectory
    • Example: liquid structure
    • Output directory summary
    • Plot generation
    • Important scientific cautions
    • Recommended AIMD analysis sequence
  • Batteries
    • Cathode material analysis
    • Anode material analysis
    • Chemical-formula mass parser
    • Reference consistency
    • Li metal reference
    • Formula-unit normalization
    • 0 K approximation
    • Cathode stability versus full phase stability
    • Diffusion caution
    • Recommended cathode workflow
    • Recommended anode workflow
    • Connection to other VQkit modules
    • Current scope
    • Summary
  • Catalysis
    • Computational hydrogen electrode
    • [1] ORR free-energy analysis (CHE)
    • [2] OER free-energy analysis (CHE)
    • ORR/OER free-energy diagrams
    • [3] HER analysis
    • [4] CO2RR analysis
    • [5] NRR analysis (CHE)
    • [6] CO reduction (CORR) analysis
    • [7] Vibrational frequency analysis
    • [8] Orbital center (s/p/d)
    • Catalysis workflow relationships
    • Recommended ORR/OER workflow
    • Recommended HER workflow
    • Recommended CO2RR workflow
    • Recommended NRR/CORR workflow
    • Thermochemistry consistency
    • Scientific limitations
    • Summary
  • Mechanical / Structural Properties
    • Elastic tensor
    • Voigt strain convention
    • Default strain grid
    • [1] Prepare elastic calculations
    • Source structures
    • Metric lattice-family detection
    • General elastic mode
    • Symmetry-reduced mode
    • Energy-strain method
    • VASP preparation
    • Quantum ESPRESSO preparation
    • Output directories
    • Manifest file
    • Stress-strain method
    • Stress-strain accuracy
    • [2] Analyze completed elastic calculations
    • Energy-strain fitting
    • Stress-strain fitting
    • Raw stress stiffness tensor
    • Elastic stiffness tensor
    • Compliance tensor
    • Voigt-Reuss-Hill properties
    • Elastic anisotropy
    • Mechanical stability
    • Mechanical output summary
    • [3] Directional elasticity: high-accuracy 3D plots
    • Positive-definite requirement
    • Young’s modulus
    • Linear compressibility
    • Shear modulus
    • Poisson ratio
    • High-resolution grid
    • ELATE-compatible optimization
    • Automatic directional extrema
    • Directional output directory
    • Directional summary
    • Recommended elastic workflow
    • Energy-strain versus stress-strain
    • Scientific cautions
    • Summary
  • Phonon-Derived Transport Properties
    • [1] Phonon group velocity
    • Supported dispersion-table formats
    • Source-unit selection
    • Group-velocity conversion
    • Segment-aware differentiation
    • Branch-resolved velocities
    • Acoustic-mode estimate near Gamma
    • Acoustic RMS velocity
    • Group-velocity cautions
    • [2] Gruneisen parameter
    • [1] gruneisen_band.dat
    • Acoustic RMS Gruneisen parameter
    • Two-volume Gruneisen calculation
    • Non-positive frequencies
    • Folder-based workflow
    • Volume-span warning
    • Gruneisen outputs
    • Scientific interpretation
    • [3] Debye temperature
    • Automatic Debye workflow
    • Velocity-based Debye temperature
    • Automatic Debye output
    • Maximum-frequency estimate
    • Manual acoustic-velocity mode
    • Relationship among the three descriptors
    • Recommended workflow
    • Scientific cautions
    • Generated files summary
    • Summary
  • Supercapacitor
    • [1] Quantum capacitance from DOS
    • DOS source
    • Spin-polarized DOS
    • Fermi-Dirac derivative
    • Effective DOS
    • Area conversion
    • Electrode-area input
    • Temperature
    • Potential modes
    • Potential-dependent output
    • Quantum-capacitance summary
    • Plots
    • Low-temperature limit
    • Example quantum-capacitance workflow
    • [2] Total interfacial capacitance
    • Input
    • Physical interpretation
    • [3] Show equations / conventions
    • Quantum capacitance versus double-layer capacitance
    • DOS convergence
    • Energy window
    • Electrode area
    • One-sided versus two-sided electrodes
    • Potential convention
    • Temperature dependence
    • Supercapacitor limitations
    • Pseudocapacitive materials
    • Recommended workflow
    • Connection to other VQkit modules
    • Generated files summary
    • Summary

Reference

• Gallery
  • Pre-processing examples
  • Post-processing examples
  • Electronic structure
  • Additional gallery topics
• Resources
  • Electronic-structure software
  • Scientific Python ecosystem
  • Related tools
  • Pseudopotential resources
  • Documentation resources
  • Licensing and citation
• Citation
• Downloads
  • Current release
  • Package selection
  • Official download location
  • Verification
• Release Notes
  • VQkit 1.0
• Acknowledgments
  • Electronic-structure software
  • Scientific Python ecosystem
  • Development and testing
  • Community
  • Citation and third-party software