valyte 0.1.11

A comprehensive CLI tool for VASP pre-processing (Supercells, K-points) and post-processing (DOS, Band Structure plotting)

Valyte

Valyte is a comprehensive CLI tool for VASP workflows, providing both pre-processing and post-processing capabilities with a focus on clean, publication-quality outputs and modern aesthetics.

Features

Pre-processing

• Supercell Creation: Generate supercells from POSCAR files.
• Interactive K-Point Generation: Create KPOINTS files with automatic grid calculation based on K-spacing.
• Band KPOINTS Generation: Automatic high-symmetry path detection for band structure calculations.

Post-processing

• DOS Plotting:
  • Smart Plotting: Automatically handles total DOS and Projected DOS (PDOS).
  • Orbital-Resolved: Plots individual orbitals (s, p, d, f) by default.
  • Adaptive Legend: Intelligently hides the legend if PDOS contributions are low.
  • Gradient Fill: Aesthetically pleasing gradient fills for DOS peaks.
• Band Structure Plotting:
  • VBM alignment to 0 eV.
  • Color-coded bands (Purple for VB, Teal for CB).
  • High-symmetry path labels from KPOINTS.
• IPR Analysis: Compute Inverse Participation Ratio from PROCAR to analyze wavefunction localization.
• Publication Quality: Clean aesthetics, custom fonts (Arial, Helvetica, Times New Roman), high DPI output.

Installation

Install Valyte directly from PyPI:

pip install valyte

Or install from source:

git clone https://github.com/nikyadav002/Valyte-Project
cd Valyte-Project
pip install -e .

Examples

Updating Valyte

To update to the latest version:

pip install --upgrade valyte

Usage

The main command is valyte.

Click to view detailed usage instructions

🧊 Create Supercell

Generate a supercell from a POSCAR file:

valyte supercell nx ny nz [options]

Example:

# Create a 2×2×2 supercell
valyte supercell 2 2 2

# Specify input and output files
valyte supercell 3 3 1 -i POSCAR_primitive -o POSCAR_3x3x1

Options:

• -i, --input: Input POSCAR file (default: POSCAR).
• -o, --output: Output filename (default: POSCAR_supercell).

---

📉 Band Structure

1. Generate KPOINTS

Automatically generate a KPOINTS file with high-symmetry paths for band structure calculations.

[!TIP] Smart K-Path Generation (New in v0.1.7+): Valyte now automatically determines the standard path (e.g., \Gamma - Y - V for Monoclinic cells) using the Bradley-Cracknell convention by default. This ensures clean, publication-ready labels without external dependencies.

valyte band kpt-gen [options]

Options:

• -i, --input: Input POSCAR file (default: POSCAR).
• -n, --npoints: Points per segment (default: 40).
• -o, --output: Output filename (default: KPOINTS).
• --mode: Path convention. Options: bradcrack (Default), seekpath, latimer_munro, setyawan_curtarolo.

Example:

# Default (Smart/BradCrack)
valyte band kpt-gen -n 60

# Explicitly use Seekpath convention
valyte band kpt-gen --mode seekpath

[!IMPORTANT] The command will generate a POSCAR_standard file. You MUST use this structure for your band structure calculation (i.e., cp POSCAR_standard POSCAR) because the K-path corresponds to this specific orientation. Using your original POSCAR may result in incorrect paths.

🕸️ Generate K-Points (Interactive)

Generate a KPOINTS file for SCF calculations interactively.

valyte kpt

This command will prompt you for:

1. K-Mesh Scheme: Monkhorst-Pack or Gamma.
2. K-Spacing: Value in $2\pi/\AA$ (e.g., 0.04).

It automatically calculates the optimal grid based on your POSCAR structure.

---

🧪 Generate POTCAR

Generate a POTCAR file based on the species in your POSCAR.

valyte potcar [options]

Options:

• -i, --input: Input POSCAR file (default: POSCAR).
• -o, --output: Output filename (default: POTCAR).
• --functional: Functional to use (default: PBE). Options include PBE, PBE_52, PBE_54, LDA, etc.

Example:

# Generate POTCAR using default PBE functional
valyte potcar

# Use a specific functional
valyte potcar --functional PBE_54

# Specify input and output files
valyte potcar -i POSCAR_relaxed -o POTCAR_new

[!IMPORTANT] Pymatgen Configuration Required: This command requires Pymatgen to be configured with your VASP pseudopotential directory. Set PMG_VASP_PSP_DIR in your ~/.pmgrc.yaml file. See the Pymatgen documentation for setup instructions.

---

2. Plot Band Structure

Plot the electronic band structure from vasprun.xml.

valyte band [options]

Options:

• --vasprun: Path to vasprun.xml (default: current directory).
• --kpoints: Path to KPOINTS file for path labels (default: looks for KPOINTS in same dir).
• --ylim: Energy range, e.g., --ylim -4 4.
• -o, --output: Output filename (default: valyte_band.png).

Example:

valyte band --ylim -3 3 -o my_bands.png

---

📊 Plot DOS

valyte dos [path/to/vasprun.xml] [options]

You can provide the path as a positional argument, use the --vasprun flag, or omit it to use the current directory.

Examples:

# Plot all orbitals for all elements (Default)
valyte dos

# Plot specific elements (Total PDOS)
valyte dos -e Fe O

# Plot specific orbitals
valyte dos -e "Fe(d)" "O(p)"

# Plot mixed (Fe Total and Fe d-orbital)
valyte dos -e Fe "Fe(d)"

Options:

• -e, --elements: Specific elements or orbitals to plot.
  • Example: -e Fe O (Plots Total PDOS for Fe and O).
  • Example: -e Fe(d) O(p) (Plots Fe d-orbital and O p-orbital).
  • Example: -e Fe Fe(d) (Plots Fe Total and Fe d-orbital).
• --xlim: Energy range (default: -6 6).
• --ylim: DOS range (e.g., --ylim 0 10).
• --scale: Scaling factor for Y-axis (e.g., --scale 3 divides DOS by 3).
• --fermi: Draw a dashed line at the Fermi level (E=0). Default is OFF.
• --pdos: Plot only Projected DOS (hide Total DOS).
• --legend-cutoff: Threshold for legend visibility (default: 0.10 = 10%).
• -o, --output: Output filename (default: valyte_dos.png).
• --font: Font family (default: Arial).

Example:

valyte dos ./vasp_data --xlim -5 5 -o my_dos.png

---

📐 Compute IPR (Inverse Participation Ratio)

Compute the Inverse Participation Ratio (IPR) from VASP PROCAR to analyze wavefunction localization.

valyte ipr

This interactive command will:

1. Read the PROCAR file from the current directory.
2. Display the number of k-points, bands, and atoms.
3. Prompt you for band indices to analyze (e.g., 5 6 7 or 5-7).
4. Optionally show per-k-point IPR values.
5. Save results to ipr_procar.dat.

Output Columns:

• Band: Band index.
• Energy: Average energy (eV) across k-points.
• IPR: Inverse Participation Ratio (higher = more localized).
• N_eff: Effective number of atoms (1/IPR).

[!TIP] Use IPR to identify localized defect states. A state localized on a single atom has IPR ≈ 1.0 and N_eff ≈ 1. Delocalized band states have small IPR and large N_eff.