Metadata-Version: 2.4
Name: bandplot
Version: 0.2.1
Summary: Band structure, DOS or phonon band structure plot from VASP, vaspkit or phonopy results.
Author: Kan
License-Expression: MIT
Project-URL: Homepage, https://github.com/lkccrr/bandplot
Keywords: DFT,VASP,DOS,band,plot,Phonon
Platform: Unix
Platform: Windows
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.22.0
Requires-Dist: matplotlib>=3.6.0
Dynamic: license-file

[![bandplot](https://img.shields.io/pypi/v/bandplot?style=flat-square)](https://pypi.org/project/bandplot/)
[![bandplot](https://img.shields.io/pypi/pyversions/bandplot?style=flat-square)](https://pypi.org/project/bandplot/)
[![bandplot](https://img.shields.io/pypi/l/bandplot?style=flat-square)](https://pypi.org/project/bandplot/)
[![bandplot](https://img.shields.io/pypi/dm/bandplot?style=flat-square)](https://pypi.org/project/bandplot/)
[![bandplot](https://img.shields.io/pypi/wheel/bandplot?style=flat-square)](https://pypi.org/project/bandplot/)
[![bandplot](https://img.shields.io/github/last-commit/lkccrr/bandplot?style=flat-square)](https://github.com/lkccrr/bandplot)
[![bandplot](https://img.shields.io/github/release-date/lkccrr/bandplot?style=flat-square)](https://github.com/lkccrr/bandplot)

### bandplot

The <b style="color:green;"><i>bandplot</b></i> 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, <b style="color:blue;"><i>bandplot</b></i> for band structure or DOS plotting, either directly from the ***VASP*** output files or from ***vaspkit*** <b style="color:darkred;"><i>\*.dat</b></i> files, <b style="color:blue;"><i>pbandplot</b></i> for phonon band structure or DOS plotting from ***phonopy*** <b style="color:darkred;"><i>\*.dat</b></i> files, and <b style="color:blue;"><i>pband</b></i> for generating the phonopy setting files (<b style="color:darkred;"><i>band.conf</i></b>, <b style="color:darkred;"><i>mesh.conf</i></b>) and running the phonopy workflow step by step.

* Install (packaged with `pyproject.toml`, Python &ge; 3.9):
```bash
pip install bandplot          # from PyPI
pip install -e .              # development install from this directory
python -m build               # build sdist + wheel into dist/
```
***
<b style="color:blue;"><i>bandplot</b></i> — 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.
```bash

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):

| File | Used for | Note |
|---|---|---|
| `EIGENVAL` | eigenvalues, k-points, occupations | required for bands / effective mass |
| `PROCAR` | projected bands | needs `LORBIT = 11` |
| `DOSCAR` | total and partial DOS | needs `LORBIT = 11` |
| `OUTCAR` | `E-fermi`, `ISPIN`, element names | Fermi level fallback: `DOSCAR` |
| `KPOINTS` | high-symmetry labels (line mode) | `KLABELS` in the same directory takes priority |
| `POSCAR` / `CONTCAR` | lattice, elements, formula legend | `POSCAR-unitcell` also accepted |

* 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.
***
<b style="color:blue;"><i>pbandplot</i></b>
* To execute <b style="color:blue;"><i>pbandplot</b></i> <b style="color:red;"><i>\-h</b></i> for the parameters to use.
* The broken axis option is <b style="color:red;"><i>\-B</i></b> (`--broken start end`).
* Example:
```bash
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
```
***
<b style="color:blue;"><i>pband</i></b> — phonopy workflow helper
* `pband -b` writes <b style="color:darkred;"><i>band.conf</i></b>, `pband -d` writes <b style="color:darkred;"><i>mesh.conf</i></b> (`pband -b -d` writes both; names via `-B` / `-D`). The other steps prompt and run the phonopy commands one by one (supercell &rarr; force constants &rarr; band path &rarr; `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 style="color:red;"><i>B</i></b>/<b style="color:red;"><i>b</i></b> + Enter goes back one level (re-asks the previous question / redoes the step) and <b style="color:red;"><i>Q</i></b>/<b style="color:red;"><i>q</i></b> + Enter quits &mdash; the prompt shows this hint.
* The supercell <b style="color:darkred;"><i>DIM</i></b> 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 &mdash; e.g. `-s 2 2 1` (quotes optional), `-s 2x2x1`, `-s (2,2,1)`, `-s 2` are all valid.
* By default pband uses the <b style="color:blue;">new (phonopy v4+)</b> commands: the setup steps (supercell / `--fc` / `-f`) go through <b style="color:blue;">phonopy-init</b>, band and DOS read <b style="color:darkred;"><i>phonopy_params.yaml</i></b> with `--config`. Add <b style="color:red;"><i>-O</i></b>/`--old` to use the legacy (v3) commands instead &mdash; no version detection is performed:

| Step | v4+ (default) | &le; v3 (`-O`) |
|---|---|---|
| supercell | `phonopy-init -d --dim="2 2 1" -c CELL` | `phonopy -d --dim="2 2 1" -c CELL` |
| force constants | `phonopy-init --fc vasprun.xml` | `phonopy --fc vasprun.xml` |
| FORCE_SETS | `phonopy-init -f {001..020}/vasprun.xml` | `phonopy -f {001..020}/vasprun.xml` |
| band | `phonopy --config band.conf phonopy_params.yaml` | `phonopy --dim=... -c CELL band.conf` |
| `BAND.dat` | `phonopy-bandplot --gnuplot > BAND.dat` | `phonopy-bandplot --legacy --gnuplot > BAND.dat` |
| DOS | `phonopy --config mesh.conf phonopy_params.yaml` | `phonopy -p mesh.conf` |
| total DOS | `phonopy --dos --config mesh.conf phonopy_params.yaml` | `phonopy -t mesh.conf` |

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 &mdash; the command keeps the compact brace form and bash expands it:

```bash
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: <b style="color:darkred;"><i>POSCAR-unitcell</i></b> &rarr; <b style="color:darkred;"><i>CONTCAR</i></b> &rarr; <b style="color:darkred;"><i>POSCAR</i></b>. When one of them exists it is used silently &mdash; 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):

| Option | Meaning | Default |
|---|---|---|
| `-c FILE` | unit cell file (`POSCAR-unitcell` / `CONTCAR` / `POSCAR`) | auto-detected |
| `-s N [N ...]` | supercell dimension `DIM`, 1-3 integers, quotes optional | `1 1 1` |
| `-r [FILE]` / `--xname` | forces source, default `vasprun.xml`; alone (no `-n`) it runs `pband fc` &mdash; a file, or a directory holding `vasprun.xml` (only that exact name); with `-n` it runs `pband f` and is the forces file name inside each displaced directory | `vasprun.xml` |
| `-n NAME [NAME ...]` | for `pband f` (implied by `-n`): directories, `vasprun.xml` suffixes or ranges, e.g. `001-003`, `dir-{001..003}` | &mdash; |
| `-O` / `--old` | use the legacy (phonopy v3) commands instead of the v4+ default | &mdash; |
| `-Y` / `--yes` | run without asking | &mdash; |
| `-y` / `--dry-run` | only print the commands | &mdash; |
| `-b` | write **`band.conf`** (name from `-B`); `-b -d` writes both files; cannot be combined with `-n` / `-r`; with `-y` the content is printed instead of written | `band.conf` |
| `-d` | write **`mesh.conf`** (name from `-D`); `-b -d` writes both files; cannot be combined with `-n` / `-r`; with `-y` the content is printed instead of written | `mesh.conf` |
| `-B FILE` | file name written by `-b`; also the `band.conf` read by `pband band` | `band.conf` |
| `-D FILE` | file name written by `-d`; also the `mesh.conf` read by `pband dos` | `mesh.conf` |
| `--band` / `--labels` / `--points` | `BAND` path, `BAND_LABELS`, `BAND_POINTS` used with `-b` | built-in path, `101` |
| `--mp` | `MP` mesh used with `-d` | `20 20 20` |

* Subcommands:

| Command | What it runs |
|---|---|
| `pband -b` / `pband -d` | write `band.conf` / `mesh.conf` only &mdash; interactive for `DIM`, `BAND`, `BAND_LABELS`, `BAND_POINTS` and `MP` (all skippable with `-s`/`--band`/`--labels`/`--points`/`--mp`, or `-Y`); `-b -d` writes both; names come from `-B`/`-D`; the v4+ form writes `PDOS = 1 2 3`, `-O` writes `PDOS = .TRUE.` |
| `pband supercell` | `phonopy-init -d --dim="2 2 1" -c POSCAR-unitcell` (`-O`: `phonopy -d ...`) |
| `pband fc` | `phonopy-init --fc vasprun.xml` — `-r FILE` / `--xname FILE` takes a forces file or a directory holding `vasprun.xml` (only `vasprun.xml` is looked for, not `vasprun.xml-N`); running `pband -r ...` alone (no `-n`) does the same; `-O`: `phonopy --fc ...` |
| `pband f` | `phonopy-init -f {001..003}/vasprun.xml` — FORCE_SETS from `-n` values (running `pband -n ...` alone is enough); each value is tried as `vasprun.xml-NAME` / `vasprun.xml_NAME` first, then as a directory that contains the forces file (`dir-{001..003}` &rarr; `dir-001..003`), and only then an error is shown; `-r NAME` sets the file name looked for inside each directory (`vasprun.xml` or `vasprun.xml-N` by default, no prompt); commands are printed in brace form (expansion left to bash) |
| `pband band` | compute `band.yaml` from `band.conf` (`-B FILE` to read another name; see version table above), then export `BAND.dat` via `phonopy-bandplot` |
| `pband dos` | `projected_dos.dat` from `mesh.conf` (`-D FILE` to read another name; optional `total_dos.dat`) |
| `pband` (no subcommand) | the supercell step (same as `pband supercell`); with `-n` it runs the `pband f` step; with `-r` only it runs `pband fc`; with `-b` / `-d` it only writes `band.conf` / `mesh.conf` (names from `-B` / `-D`) |

* Example session:
```bash
# 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)
```

