Topology and response functions directly from VASP wavefunctions.
VASPBERRY reads WAVECAR and evaluates wavefunction overlaps and interband
matrix elements in Fortran. Use the Fukui–Hatsugai–Suzuki (FHS) link-variable
method, also called the Fukui method, for Chern numbers. The separate
Fukui–Hatsugai (FH) n-field method gives the 2D Z₂ invariant. Kubo-formula
calculations provide Berry-curvature maps, symmetry-path curves and intrinsic
charge Hall response. Projected-spin Chern
numbers and spin-sector Kubo-formula Berry curvature use a matching OUTCAR
to establish the Cartesian spin frame.
VASP calculation → WAVECAR → VASPBERRY → numerical output → analysis / plots
VASP supplies the material's electronic structure. VASPBERRY postprocesses it; band plots provide context for the calculated topology and response.
Technical report (PDF) · Hands-on commands · Feature examples · Build guide · Postprocessing guide · Output formats
VASPBERRY 1.6.3.
Native Kubo band selection is simpler: --bands N calculates one band,
and a multi-band range calculates its subspace trace. Use --per-band 1
for separate bands. Byte and legacy four-byte-word WAVECAR record lengths
are detected automatically. New curvature exports check finite results and
complete row coverage before reporting success.
The native --bundle and -kubo_bundle flags have been removed. See the
short migration guide,
release notes, validation scope,
changelog and version policy.
The VASPBERRY executable requires a Fortran compiler, GNU Make, POSIX shell/tools
and LP64 BLAS/LAPACK libraries. An MPI build additionally needs the matching
MPI development package/compiler wrapper and runtime launcher. These
native dependencies are sufficient to compile and run VASPBERRY on an existing
compatible WAVECAR. Python is used by the optional numerical postprocessing
and plotting tools.
| Environment | Required native development environment | Build and executable |
|---|---|---|
| Linux, Intel serial | Intel oneAPI ifx + oneMKL |
make ifx → build/vaspberry-ifx |
| Linux, Intel MPI (main walkthrough) | ifx + Intel MPI SDK (mpiifx) + oneMKL |
make ifx-mpi → build/vaspberry-ifx-mpi |
| Linux, GNU serial | GNU Fortran + LP64 BLAS/LAPACK | make serial → build/vaspberry |
| Linux, GNU MPI | GNU Fortran + Open MPI or MPICH development libraries + LP64 BLAS/LAPACK | make mpi → build/vaspberry-mpi |
| macOS, GNU | Compatible GNU Fortran/MPI libraries and LP64 BLAS/LAPACK | See the architecture-specific build guide for paths and available packages |
Retained Intel Classic installations use make ifort or make ifort-mpi.
On Windows use a Linux environment such as WSL2 and its Linux compiler stack;
there is no native Windows build. The build guide distinguishes
CI-validated environments from installation guidance and covers cluster modules,
macOS, MPICH, runtime libraries and common errors.
Clone the repository's default branch (master):
git clone https://github.com/Infant83/VASPBERRY.git
cd VASPBERRY
make helpFor a fixed release, download and extract the source archive from
v1.6.3, then run the
same build commands from the extracted directory containing Makefile.
Archive builds do not require Git or Python. No precompiled executable or
system-wide installation is needed; the build creates local files in build/.
Update an existing default-branch checkout with git pull --ff-only, then
rebuild. Release tags stay fixed. Large example inputs may separately need
the input-fetch procedure.
Install/load the Fortran compiler, Intel MPI SDK and oneMKL development components; having only runtime libraries is insufficient. In Bash, activate the installed environment or use the site's equivalent modules:
source /opt/intel/oneapi/setvars.sh
make ifx-mpi
make check-ifx-mpi
mpiexec -n 4 ./build/vaspberry-ifx-mpi --helpReplace the setup path with the site's actual oneAPI installation. Use the
mpiexec from the same Intel MPI environment as mpiifx, and run within an
allocation that permits the requested rank count. check-ifx-mpi builds and
checks two-rank startup/communication/help. Intel Classic uses
make check-ifort-mpi. For a machine without MPI, use make ifx,
make check-ifx, and run ./build/vaspberry-ifx --help directly.
The serial executable needs no MPI package:
sudo apt-get update
sudo apt-get install make gfortran libblas-dev liblapack-dev
make serial
make check-serial-help
./build/vaspberry --helpFor Open MPI, add the development/runtime packages and build the MPI version:
sudo apt-get install openmpi-bin libopenmpi-dev
make mpi
make check-gnu
mpiexec -n 4 ./build/vaspberry-mpi --helpOn a cluster, use its installed modules/libraries instead of these administrator commands. Compiler, wrapper and library paths can be supplied to Make; see build overrides and platform recipes. The supplied builds use byte-based WAVECAR records and LP64, not ILP64, numerical libraries. Serial executables run directly; MPI executables run with their matching launcher. Keep the compiler/MPI/library environment loaded when running.
Use your usual Python environment for the optional tools/ commands. Their
full dependency versions are in requirements-transport.txt;
Matplotlib is used by the supplied postprocessing and plotting tools.
Environment creation and package installation follow your site's usual practice.
| Task | Native command | Actual VASP example and results |
|---|---|---|
| Berry flux and Chern number of an isolated band or bundle using the Fukui method | --task chern |
MoS₂ BZ map, Bi occupied bundle |
| Projected-spin sector Chern numbers | --task spin-chern |
Graphene with intrinsic SOC; SPIN_CHERN.csv, plaquette flux and spin spectra |
| Spin-sector Kubo-formula Berry curvature | --task spin-kubo |
Path and mesh guide; native sector curvature CSVs and explicitly approximate mesh integrals |
| 2D Z₂ invariant and n-field using the FH method | --task z2 |
MoS₂ (Z₂ = 0) and Bi (Z₂ = 1) |
| Kubo-formula Berry curvature on a BZ mesh or symmetry path | --task kubo |
MoS₂ occupied bundle and isolated-band maps, paths and bands |
| Intrinsic charge Hall response versus chemical potential and temperature | --task kubo-pairs, then occupation-weighted postprocessing |
MoS₂ Hall and valley-region curves |
| Circular optical selectivity and transition spectra | --task optical / --task spectrum |
MoS₂ circular dichroism |
| Real-space wavefunction at Γ | --task wavefunction |
MoS₂ wavefunction |
Plaquette flux from the Fukui method and Kubo-formula point Berry curvature
are different finite-grid quantities. A Chern number computed with the Fukui method needs band
isolation and mesh checks. A Kubo-formula curvature integral is not rounded to
an integer; its k mesh and intermediate band window must be converged. Native
Kubo-formula calculations use canonical momentum of the stored pseudo-wavefunctions.
Optional full-velocity comparisons assess the missing
PAW/nonlocal/SOC terms; see operator choices.
For spin-sector convergence, use --sum-bands N
to vary the intermediate sum on unchanged wavefunctions. The
Bi comparisons
separate this from mesh and source-state changes; the
graphene controls
resolve a local SOC peak without claiming a converged full-BZ Kubo-formula curvature integral.
For layer, atom, orbital and spin character, combine a matching SOC
PROCAR with the WAVECAR and actual spin frame from OUTCAR using
the optional [projection] and [group NAME] sections in the
postprocessing settings. Named atom/orbital groups and a Cartesian spin
axis define the projections. The same saved native pair data support
chemical-potential/temperature scans of selected-band projected charge-Hall
contributions. Follow the projection tutorial
for commands and an explicitly synthetic reproducibility fixture. These
projections explain state character; conventional spin-current Hall uses the
separate operator route described in the spin guide.
VASPBERRY provides a short overview and help for individual tasks and options. After building, list the tasks, inspect a calculation, then run the first example below:
mpiexec -n 4 ./build/vaspberry-ifx-mpi --help
mpiexec -n 4 ./build/vaspberry-ifx-mpi --help task
mpiexec -n 4 ./build/vaspberry-ifx-mpi --help kubo
mpiexec -n 4 ./build/vaspberry-ifx-mpi --help bandsHelp runs in the native Fortran executable; it needs neither Python nor a
WAVECAR. Use --help spin-chern for that task, --help options to find option
names, and --help all (also --help legacy) for the complete flag reference.
-h is the short form of --help. See the
native help guide.
Run from the repository root. This small example uses the actual SOC band-path WAVECAR already in the repository, and writes the curvature of the occupied bands 1–18 at its supplied k points:
mkdir -p results/mos2-path
mpiexec -n 4 ./build/vaspberry-ifx-mpi --task kubo \
--wavecar examples/1H-MoS2/KPATH/2.band/WAVECAR --bands 1:18 \
--curvature-csv results/mos2-path/KUBO.csvKUBO.csv contains one row per k point/spin channel, with fractional
k coordinates, omega_z_A2 (Ωxy in Ų) and min_external_gap_eV.
VASPBERRY has already evaluated the occupied-bundle sum: plot omega_z_A2
against the ordered k_index for this path. For a mesh map, convert the
fractional coordinates with the reciprocal lattice. The
MoS₂ tutorial separately provides a
matching full-BZ/path dataset and commands for the reference panels. A line
path alone cannot supply a BZ integral. Use a fresh output
path for each run.
A multi-band trace defaults to KUBO.csv if --curvature-csv is omitted.
For separate bands, use --bands 18:19 --per-band 1; each selected band must
be separated from every other stored band by more than 1e-5 eV. The trace
requires this gap only between the selected subspace and excluded bands.
Choose the mesh and band range from your VASP calculation. VASPBERRY detects
one- or two-component wavefunctions from WAVECAR automatically; an optional
--spinor 1 or --spinor 2 checks that the file matches your expectation.
These illustrative commands assume the appropriate WAVECAR in the working
directory; the band indices are examples, not universal occupied counts.
# Berry flux and Chern number from the Fukui method: full 12 × 12 mesh, bands 1–18.
mpiexec -n 4 ./build/vaspberry-ifx-mpi --task chern --wavecar WAVECAR \
--mesh 12,12 --bands 1:18 --output BERRYCURV
# Bi example: full even mesh, occupied spinor bands 1–10.
mpiexec -n 4 ./build/vaspberry-ifx-mpi --task z2 --wavecar WAVECAR \
--mesh 12,12 --bands 1:10 --output NFIELD
# Occupied-bundle point curvature, excluding internal transitions.
mpiexec -n 4 ./build/vaspberry-ifx-mpi --task kubo --wavecar WAVECAR \
--bands 1:18 --curvature-csv KUBO_BUNDLE.csv
# Reusable all-band pair numerators for charge Hall postprocessing.
mpiexec -n 4 ./build/vaspberry-ifx-mpi --task kubo-pairs --wavecar WAVECAR \
--pairs-csv PAIRS.csvThe native syntax groups a mesh as NX,NY and a band range as FIRST:LAST.
Specialized legacy options can still be used. A named Kubo task uses the
new band-range semantics even when its endpoints are given by -ii/-if.
Pure legacy -kubo commands retain separate-band output with the same
isolation checks. --task kubo-integral additionally evaluates the mesh integral.
Use mpiexec -n 4 ./build/vaspberry-ifx-mpi --help all or the native command reference for the full list. For example:
mpiexec -n 4 ./build/vaspberry-ifx-mpi --task chern --wavecar WAVECAR \
--mesh 12,12 --bands 1:18 --output BERRYCURVFor Z₂, use a nonmagnetic time-reversal-symmetric insulator and a full,
unshifted, even Nx × Ny × 1 mesh with Nx,Ny >= 4, generated with
ISYM=-1. Report only a final Z2_FIELD.csv with result_status=PASS,
reportable_invariant=1 and matching half-zone parities. See the
Z₂ guide for input and convergence checks.
Start with the public Bi walkthrough.
Its bi.ini needs only [run]
(input, native executable, mesh and output) and [hall] (μ, reference and
temperature). After its build/input step, run from the repository root:
python3 tools/vaspberry_post.py run examples/features/simple-postprocess/bi.ini
python3 tools/vaspberry_post.py plot results/simple-biThe first command executes VASPBERRY with the configured MPI launcher and rank count, then uses Python for numerical Hall integration. The second command draws the completed table. You edit one INI file, and the tool records the underlying commands. The files remain usable in Python, Origin, gnuplot or other software:
| Stage | File under results/simple-bi/ |
Contents and use |
|---|---|---|
VASPBERRY execution: WAVECAR → pair data |
native/PAIRS.csv |
Energies, k coordinates and three interband pair numerators in eV² Ų; reusable matrix data before occupations and Hall integration. |
| Numerical postprocessing | hall/conductivity.csv and .dat |
Sheet σ and reference-subtracted Δσ in e²/h, as functions of μ, temperature and region, plus represented carrier counts. |
| Plotting | figures/charge-hall/hall.png, .pdf, .svg |
Total charge-Hall conductivity versus μ−reference. |
Use the beginner guide to add one feature at a time: change the μ/T scan, reuse saved pairs, select a k-space region, then add PROCAR groups when needed. The Bi rescan and region examples are runnable extensions of the first calculation. The PROCAR tutorial explains the matching extra inputs and has a separate analytic fixture; it is not part of the Bi input. Consult the settings reference for all keys and defaults, or the output specification for columns and units.
For a curvature map or symmetry-path curve, native --task kubo already
writes gap-divided omega_z_A2 in KUBO.csv; that result can be plotted
directly in your preferred plotting tool. The direct VASPBERRY commands above
require no Python script; the INI run command additionally automates cache
validation and numerical Hall integration. See the MoS₂ curvature example.
The hands-on commands and
individual Kubo-formula transport stages
remain available for users who need direct control of each stage.
The main tutorials above use ordinary VASP wavefunctions. Separate guides cover extra operators and independent checks:
- PAW optical and full-velocity comparisons, including matched MoS₂ charge Hall data.
- Conventional spin Hall response with explicitly supplied spin and velocity matrices; Bi results complement its directly calculated Z₂ invariant.
- Advanced geometric transport, matrix interfaces and developer model checks.
The technical report connects these capabilities to reference figures. The material catalog records input preparation and sampling. The Chern-number calculation follows Fukui, Hatsugai and Suzuki, JPSJ 74, 1674 (2005). The separate Z₂ n-field calculation follows Fukui and Hatsugai, JPSJ 76, 053702 (2007). Method-specific references are given in each guide.
- Hyun-Jung Kim: Main developer and maintainer; responsible for subsequent development and ongoing updates of the Kubo implementation.
- Sun-Woo Kim: Contributions to circular dichroism and the initial Kubo implementation.
@software{Kim_VASPBERRY_2018,author = {Kim, Hyun-Jung},doi = {10.5281/zenodo.1402593},month = {8},title = {{VASPBERRY}},url = {https://github.com/Infant83/VASPBERRY},version = {1.0},year = {2018}}
@article{PhysRevLett.128.046401,
title = {Circular Dichroism of Emergent Chiral Stacking Orders in Quasi-One-Dimensional Charge Density Waves},
author = {Kim, Sun-Woo and Kim, Hyun-Jung and Cheon, Sangmo and Kim, Tae-Hwan},
journal = {Phys. Rev. Lett.},
volume = {128},
issue = {4},
pages = {046401},
numpages = {6},
year = {2022},
month = {Jan},
publisher = {American Physical Society},
doi = {10.1103/PhysRevLett.128.046401},
url = {https://link.aps.org/doi/10.1103/PhysRevLett.128.046401}
}