valyte 0.22.0

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

Valyte

Valyte is a CLI tool for VASP workflows — pre-processing and post-processing — built for clean, publication-quality output.

Full Documentation → valyte-project.readthedocs.io

---

Features

Pre-processing

Command	Description
valyte supercell	Generate supercells from POSCAR files
valyte kpt	Interactive KPOINTS generation (Monkhorst-Pack / Gamma)
valyte band kpt-gen	Automatic high-symmetry k-path (Bradley-Cracknell by default)
valyte potcar	Generate POTCAR from POSCAR species

Post-processing

Command	Description
valyte dos	Total and projected DOS with orbital resolution and gradient fills
valyte band	Color-coded band structure with VBM aligned to 0 eV
valyte band --tricolor	Orbital-resolved tricolor band structure
valyte band --spin-resolved	Spin-polarized band structure — spin-up (blue) and spin-down (red) channels
valyte band --spin-texture	Non-collinear spin texture — bands colored by Sₓ, S_y, or S_z expectation value
valyte ipr	Inverse Participation Ratio from PROCAR
valyte effmass	Carrier effective masses at VBM/CBM from parabolic fitting
valyte converge	Ionic and SCF convergence monitor with multi-panel plots

---

Installation

pip install valyte

To update:

pip install --upgrade valyte

Or from source:

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

---

Gallery

---

Usage

Run valyte --help or valyte <command> --help at any time.

Supercell

valyte supercell nx ny nz [options]

Option	Default	Description
-i, --input	POSCAR	Input POSCAR file
-o, --output	POSCAR_supercell	Output filename

valyte supercell 2 2 2
valyte supercell 3 3 1 -i POSCAR_primitive -o POSCAR_3x3x1

Band Structure — KPOINTS generation

Automatically generate a line-mode KPOINTS file with high-symmetry paths.

valyte band kpt-gen [options]

Option	Default	Description
-i, --input	POSCAR	Input POSCAR file
-n, --npoints	40	Points per segment
-o, --output	KPOINTS	Output filename
--mode	bradcrack	Path convention: bradcrack, seekpath, latimer_munro, setyawan_curtarolo

valyte band kpt-gen -n 60
valyte band kpt-gen --mode seekpath

Important: A POSCAR_standard file is also written. You must use this standardized structure for the band calculation (cp POSCAR_standard POSCAR) — the k-path corresponds to this specific cell orientation.

Band Structure — Standard plot

Bands are colored purple (valence) and teal (conduction), with the VBM set to 0 eV.

valyte band [options]

Option	Default	Description
--vasprun	.	Path to vasprun.xml or directory
--kpoints	auto-detected	Path to KPOINTS file for labels
--ylim	-4 4	Energy window
-o, --output	valyte_band.png	Output filename
--font	Arial	Font: Arial, Helvetica, Times New Roman
--save-data	off	Save band data to valyte_band.dat

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

Band Structure — Tricolor orbital-resolved plot

Each band segment is colored by blending three base colors weighted by the relative orbital/element projection at each k-point. A ternary triangle legend is drawn in the corner.

valyte band --tricolor SPEC1 SPEC2 SPEC3 [options]

Spec formats:

Format	Example	Selects
Orbital	s, p, d, f	That orbital across all atoms
Element	Fe, O	All orbitals for that element
Element + orbital	Fe:d, O(p)	Specific orbital for that element

Option	Default	Description
--tricolor	—	3 specs (required)
--tricolors	#e74c3c #2ecc71 #3498db	3 colors (red, green, blue)
--tri-labels	spec strings	3 labels for the triangle legend
--lw	2.0	Line width
--save-data	off	Save band data to valyte_band.dat

Requirement: VASP must be run with LORBIT = 11 (or ≥ 10) to write projected eigenvalues into vasprun.xml.

# s / p / d — default red, green, blue
valyte band --tricolor s p d --ylim -4 4

# Element-resolved (e.g. MoSSe)
valyte band --tricolor Mo S Se \
  --tricolors "#e74c3c" "#2ecc71" "#3498db" \
  --tri-labels Mo S Se --ylim -3 3

# Element + orbital resolved
valyte band --tricolor Fe:d O:p s --ylim -5 5 -o orbital_band.png

Band Structure — Spin-resolved plot (collinear)

For spin-polarized calculations, plot spin-up and spin-down channels in distinct colors on the same axes. Spin-up bands are drawn as solid blue lines, spin-down as dashed red lines, with an automatic legend.

valyte band --spin-resolved [options]

Option	Default	Description
--spin-resolved	off	Enable spin-resolved mode
--ylim	-4 4	Energy window
-o, --output	valyte_band.png	Output filename

Silently falls back to the standard plot if the calculation has only one spin channel (non-magnetic).

valyte band --spin-resolved
valyte band --spin-resolved --ylim -3 3 -o spin_band.png

Band Structure — Non-collinear spin texture

For non-collinear (SOC / LSORBIT) calculations, color each band segment by the expectation value of a chosen spin component (Sₓ, S_y, or S_z), summed over all atoms and orbitals. A diverging colormap centered at zero reveals the spin polarization direction along the k-path.

valyte band --spin-texture {sx,sy,sz} [options]

Option	Default	Description
--spin-texture	—	Component to visualize: sx, sy, or sz
--spin-cmap	seismic	Diverging colormap (any matplotlib name)
--ylim	-4 4	Energy window
-o, --output	valyte_band_sz.png	Output filename (auto-named by component)

Requirement: VASP must be run with LSORBIT = .TRUE. (or LNONCOLLINEAR = .TRUE.) and LORBIT >= 11.

# Out-of-plane spin texture (most common)
valyte band --spin-texture sz

# In-plane components
valyte band --spin-texture sx
valyte band --spin-texture sy

# Custom colormap and energy window
valyte band --spin-texture sz --spin-cmap RdBu_r --ylim -2 2

DOS — Density of States

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

Option	Default	Description
-e, --elements	all	Elements/orbitals to plot
--xlim	-6 6	Energy range
--ylim	auto	DOS range
--scale	1.0	Divide DOS by this factor
--fermi	off	Draw dashed line at E = 0
--pdos	off	Show only projected DOS
--legend-cutoff	0.10	Hide legend if PDOS fraction < threshold
-o, --output	valyte_dos.png	Output filename
--font	Arial	Font family
--save-data	off	Save DOS data to valyte_dos.dat

valyte dos                            # All orbitals, all elements
valyte dos -e Fe O                    # Total PDOS for Fe and O
valyte dos -e "Fe(d)" "O(p)"          # Specific orbitals
valyte dos -e Fe "Fe(d)"              # Fe total + Fe d-orbital
valyte dos ./run --xlim -5 5 --fermi -o my_dos.png
valyte dos -e Fe O --save-data        # Save data to valyte_dos.dat

K-Points — Interactive SCF grid

valyte kpt

Prompts for K-mesh scheme (Monkhorst-Pack or Gamma) and K-spacing in 2π/Å, then calculates the optimal grid from your POSCAR.

POTCAR

valyte potcar [options]

Option	Default	Description
-i, --input	POSCAR	Input POSCAR file
-o, --output	POTCAR	Output filename
--functional	PBE	PBE, PBE_52, PBE_54, LDA, etc.

valyte potcar
valyte potcar --functional PBE_54
valyte potcar -i POSCAR_relaxed -o POTCAR_new

Pymatgen configuration required: Set PMG_VASP_PSP_DIR in ~/.pmgrc.yaml. See the Pymatgen docs.

IPR — Inverse Participation Ratio

Compute the Inverse Participation Ratio from PROCAR to quantify wavefunction localization.

valyte ipr

Interactive — reads PROCAR, shows system info, prompts for band indices, saves results to ipr_procar.dat.

Output columns: Band | Energy (eV) | IPR | N_eff (= 1/IPR)

A state localized on a single atom has IPR ≈ 1 and N_eff ≈ 1. Delocalized band states have small IPR and large N_eff. Use IPR to identify defect states in supercell calculations.

Effective Mass

Compute carrier effective masses (m*/m₀) at the VBM and CBM by fitting a parabola to the band dispersion along each high-symmetry direction. Works from vasprun.xml alone — no extra input needed.

valyte effmass [options]

Option	Default	Description
--vasprun	.	Path to vasprun.xml or directory
--kpoints	auto-detected	Path to KPOINTS file for labels
--npoints	3	K-points on each side of extremum used for fitting
--band-index	auto	Manual 1-indexed band indices to fit
--tol	1e-3	Degeneracy tolerance in eV
--plot	off	Save parabolic fit plot
-o, --output	valyte_effmass.png	Output plot filename (with --plot)
--save-data	off	Save results to valyte_effmass.dat

valyte effmass                         # Auto-detect VBM/CBM
valyte effmass --npoints 5             # Wider fitting window
valyte effmass --plot -o effmass.png   # Save parabolic fit figure
valyte effmass --save-data             # Export to valyte_effmass.dat

Requirement: Line-mode band structure calculation (IBRION = -1, line-mode KPOINTS). A self-consistent calculation will raise an error.

Convergence Monitor

Monitor and visualize the convergence of VASP relaxation, single-point, or MD calculations by parsing OSZICAR (always) and optionally OUTCAR (for forces and pressure).

valyte converge [path] [options]

Option	Default	Description
path	.	Directory or direct path to OSZICAR
--electronic	off	Show SCF convergence instead of ionic
--forces	off	Include max-force panel (requires OUTCAR)
--stress	off	Include pressure panel (requires OUTCAR)
--mag	off	Include magnetization subplot
--ethresh	from OUTCAR / 1e-4	Energy convergence reference line (eV)
--fthresh	0.02	Force convergence reference line (eV/Å)
--start	1	First ionic step to include
--end	last	Last ionic step to include
--no-plot	off	Print terminal summary only (fast SSH check)
-o, --output	valyte_converge.png	Output plot filename
--save-data	off	Save parsed data to valyte_converge.dat

valyte converge                        # 2-panel ionic plot from OSZICAR
valyte converge --forces               # Add max-force panel (needs OUTCAR)
valyte converge --forces --stress      # Add force + pressure panels
valyte converge --electronic           # SCF convergence across all ionic steps
valyte converge --no-plot              # Terminal summary only
valyte converge /path/to/run --start 5 --end 30

---

License

This project is licensed under the MIT License.