valyte 0.17.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

---

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.

---

License

This project is licensed under the MIT License.