CONVERGE_KPOINTS(1)

🌸 CONVERGE_KPOINTS 🌸

okay bestie, so this is a page from the custodian manual — that's the manual name, CONVERGE_KPOINTS(1), filed under User Commands — and it's about a little script called converge_kpoints that runs VASP jobs over and over until your k-points stop changing the answer. yes, really. it just keeps going until things converge. main character energy, honestly.

✨ NAME ✨

converge_kpoints — repeat VASP jobs until kpoint convergence 💅

💖 DESCRIPTION 💖

the usage, verbatim, no notes:

converge_kpoints [-h] [-c [COMMAND]] [-i [{linear,inc}]]

       [-m [MAX_STEPS]] [-t [TARGET]]

so. converge_kpoints performs a KPOINTS convergence. what that actually means: it takes a particular VASP run and keeps re-running it with increasing multiples of the initial KPOINT grid, and it does that over and over until it hits a target convergence in energy per atom. 🎯

example time, because this is the part that makes it click. say you have vasp input files with a k-point grid of 1x1x1. this script will run a sequence of jobs with k-point grids of 1x1x1, 2x2x2, 3x3x3, 4x4x4, ... until convergence is achieved. it's giving "keep going until it stops mattering". 👑

the default convergence criteria is 1meV/atom, but you can set it yourself with the --target option. periodt.

🎀 options: 🎀

• -h, --help — show this help message and exit. the classic. the icon.
• -c [COMMAND], --command [COMMAND] — the VASP command. defaults to pvasp. if you're using mpirun, set this to something like 'mpirun pvasp'. that's it, that's the flag.
• -i [{linear,inc}], --increment_mode [{linear,inc}] — the mode for increasing kpoints, bestie, and there are two whole vibes here:
  • linear mode does multiples of the existing kpoints. e.g., 2x4x2 -> 4x8x4 -> 6x12x6.
  • inc mode increments all KPOINTS by 1 at each stage, i.e., 2x4x2 -> 3x5x3 ->4x6x4. ⚠️ note that the latter mode does not preserve KPOINTS symmetry, though it is probably less expensive.
• -m [MAX_STEPS], --max_steps [MAX_STEPS] — the maximum number of KPOINTS increment steps. this puts an upper bound on the largest KPOINT converge grid attempted. your safety net, your limit, your "okay we're done here". 🛑
• -t [TARGET], --target [TARGET] — the target converge in energy per atom to achieve convergence. e.g., 1e-3 means the KPOINTS will be increased until a converged of 1meV is reached. 🔥

Author: Shyue Ping Ong

okay that's the whole page, no cap 🫶 shoutout to custodian, and this little slice of the docs is dated January 2024 — take care of yourselves, converge responsibly, and remember: when in doubt, bump the grid. 💖✨🎀🦋🌸