bandplot 0.2.1

bandplot

The bandplot is used for electron band structure, DOS or phonon band structure, DOS plotting from VASP, vaspkit or phonopy results. The code will provide three scripts, bandplot for band structure or DOS plotting, either directly from the VASP output files or from vaspkit *.dat files, pbandplot for phonon band structure or DOS plotting from phonopy *.dat files, and pband for generating the phonopy setting files (band.conf, mesh.conf) and running the phonopy workflow step by step.

• Install (packaged with pyproject.toml, Python ≥ 3.9):

pip install bandplot          # from PyPI
pip install -e .              # development install from this directory
python -m build               # build sdist + wheel into dist/

bandplot — VASP output is the default data source, vaspkit is optional

• -i takes a directory (default: the current directory). The directory is scanned automatically: VASP output (EIGENVAL / DOSCAR / PROCAR) is preferred, otherwise BAND.dat / PBAND*.dat / PDOS*.dat are used.
• -i alone plots the band structure; -d alone plots the DOS; -i together with -d plots the band structure and the DOS side by side.

bandplot                                     # band structure of the current directory
bandplot -i calc_PBE -l g m k g              # given directory, VASP or .dat auto-detected
bandplot -i calc_PBE -d -z                   # bands + DOS (DOSCAR or PDOS*.dat)
bandplot -d                                  # DOS only
bandplot -i calc_PBE -r -p Mo-d              # projected bands from PROCAR
bandplot -i calc_PBE -D -d                   # spin polarized: up/down panels + spin resolved DOS
bandplot -i calc_PBE -m 0.15                 # effective masses from EIGENVAL
bandplot -i calc_PBE calc_HSE                # compare two or three directories
bandplot -i BAND.dat -d PDOS*.dat            # vaspkit .dat route, unchanged
bandplot --vasp calc_PBE                     # legacy spelling of -i
bandplot -i calc_PBE --no-shift              # keep absolute energies
bandplot -i calc_PBE --export-dat dat        # also dump vaspkit-style .dat files
bandplot -i calc_PBE -d --no-mirror          # keep spin-down DOS positive

• Compared with an older release, bandplot --vasp DIR still works but is just an alias of -i DIR; a bare bandplot no longer insists on BAND.dat in the current directory.
• Spin resolved DOS is drawn as a mirror plot: spin-up on the positive axis, spin-down on the negative axis. The curve is flipped whenever its label contains up/down (also dw, _DW, $dw$), so the same rule applies to the DOSCAR route and to -d PDOS_*_UP.dat PDOS_*_DW.dat; use --no-mirror to keep both positive. When -x gives a one sided DOS range, it is expanded symmetrically so that both spin channels stay visible.
• Files used (all optional except one data source):

• Energies are shifted so that the Fermi level is 0 eV; use --no-shift to keep the raw values.
• k-path distances are computed from the EIGENVAL k-points and the reciprocal lattice (units of 1/Å), so no KLABELS file is needed.
• The .dat reader is untouched: the old workflow bandplot -i BAND.dat --klabels KLABELS still works, and --export-dat can generate those files from VASP output for reuse.

pbandplot

• To execute pbandplot -h for the parameters to use.
• The broken axis option is -B (--broken start end).
• Example:

pbandplot -h
pbandplot -i BAND.dat -o BAND.png -l g m k g -d projected_dos.dat -z
pbandplot -B 23 100 -l g m k g -y -2 110
pbandplot -i BAND1.dat BAND2.dat -B 20 100

pband — phonopy workflow helper

• pband -b writes band.conf, pband -d writes mesh.conf (pband -b -d writes both; names via -B / -D). The other steps prompt and run the phonopy commands one by one (supercell → force constants → band path → BAND.dat / DOS data). Every command is printed and confirmed before execution; -Y/--yes runs without asking and -y/--dry-run only prints them. In any interactive prompt, B/b + Enter goes back one level (re-asks the previous question / redoes the step) and Q/q + Enter quits — the prompt shows this hint.
• The supercell DIM accepts 1-3 integers; missing ones default to 1 (overall default 1 1 1). Separators can be spaces or common punctuation (, ; / x X × *), brackets and extra characters are ignored — e.g. -s 2 2 1 (quotes optional), -s 2x2x1, -s (2,2,1), -s 2 are all valid.
• By default pband uses the new (phonopy v4+) commands: the setup steps (supercell / --fc / -f) go through phonopy-init, band and DOS read phonopy_params.yaml with --config. Add -O/--old to use the legacy (v3) commands instead — no version detection is performed:

The values given via -n may be directories, vasprun.xml suffixes, or ranges, and giving -n alone already runs the pband f step (no subcommand needed). Each name is checked in this order: first a file vasprun.xml-<name> / vasprun.xml_<name> in the current directory (e.g. vasprun.xml-001), then a directory with that name that actually holds the forces file (001/vasprun.xml, dir-001/vasprun.xml-1). Only when neither is found does pband report an error. dir-{001..003} means dir-001, dir-002, dir-003. Nothing is expanded one by one — the command keeps the compact brace form and bash expands it:

pband -n 001-003                # -n alone runs f; vasprun.xml-001..003 present
                                #   -> phonopy-init -f vasprun.xml-{001..003}
pband f -n 001-003              # otherwise dirs 001..003
                                #   -> phonopy-init -f {001..003}/vasprun.xml
pband f -n dir-{001..003}       # dir-001..003 -> -f dir-{001..003}/vasprun.xml
pband f -n 001-003 005-007      # several groups -> -f vasprun.xml-{001..003} {005..007}/vasprun.xml
pband f -n 001-003 -r vasprun.xml-1   # forces file name inside each directory

Because /bin/sh (dash) does not expand braces, commands containing {a..b} are run through bash -c when bash is available.

• The unit cell file defaults to an auto-detected one: POSCAR-unitcell → CONTCAR → POSCAR. When one of them exists it is used silently — pband only asks for it if none is found (or give it explicitly with -c FILE).
• Shortcut options (usable before or after the subcommand; in the guided flow they skip the matching prompt):

• Subcommands:

• Example session:

# contains POSCAR-unitcell
pband                                             # supercell step (default; same as pband supercell)
pband -b -d --dim "3 2 1" --band "0 0 0 0.5 0 0 0.5 0.5 0.5 0 0 0" --labels "G X M G" --mp "20 20 20"
pband supercell --dim "2 2 1" -c POSCAR-unitcell
pband fc                                          # phonopy-init --fc vasprun.xml
pband -r                                          # -r alone runs fc with ./vasprun.xml
pband fc -r calc/                                 # or a directory containing vasprun.xml
pband -n 001-003                                  # -n alone runs f -> vasprun.xml-{001..003}
pband -n dir-{001..003}                           # dir-001..003        -> -f dir-{001..003}/vasprun.xml
pband band                                        # phonopy --config band.conf phonopy_params.yaml
pband -O band --dim "3 2 1" -c POSCAR-unitcell    # legacy v3 form
pband dos --total
pband -O -y supercell -s 2 2 1                    # preview the legacy command only
pbandplot                                         # plot BAND.dat (+ projected_dos.dat if present)