sumo-kgen — sumo 2.3.8 documentation (2024)

Basic Options¶

As the path depends on the symmetry of the lattice, it is important that the symmetry is determinedcorrectly. The tolerance used for symmetry detection can be controlled using the --symprec option.The default is 0.01 Angstrom.

By default, the paths used are those from Bradley and Cracknell [brad]. To use the k-point paths providedSeeK-path [seek] or pymatgen [curt]. The options --seekpath or --pymatgen can be used.

sumo-kgen automatically looks for a POSCAR file in the current directory. A different structurefile can be specified using the --poscar option.

The density of the k-points along the path can be controlled using the --density option. The default is60.

Hybrid Band Structures¶

By default, sumo-kgen generates KPOINTS files for use in non-self-consistent band structure calculations(e.g. for use with generalised-gradient approximation functionals). To perform hybrid band structures, thezero-weighted k-point scheme should be used. To generate KPOINTS files for use in hybrid band structures, anIBZKPT file must be located in the current directory (the generated k-points will be appended to those inthis file). Then simply run the following:

sumo-kgen --hybrid

When generating hybrid k-points, the script will ask if you wish to split the k-points among multiple files,due to the cost of hybrid band structures which often cannot finish under standard cluster walltimes.Bear in mind that the total number of k-points per file you choose will not include the addition k-pointsincluded in the IBZKPT file. To skip this prompt, the number of k-points per file can be specifiedvia the --split option.

Folder Generation¶

Often it is desirable to generate a new folder in which to run the band structure. sumo-kgen can automatethis procedure using the --folders (or -f) option. The script will also copy in the required VASPfiles from the current directory. Which files are copied depends on the mode of k-point generation.For example, for non-self-consistent band structures, POSCAR, INCAR, POTCAR, and CHGCARwill be copied. For hybrid band structures, only the POSCAR, INCAR, and POTCAR files will be copied.

If you choose to split the hybrid k-points among a number of KPOINTS files, a separate folder will begenerated for each file. These will be named split-01, split-02, etc…

The sumo-bandplot command can automatically detect the presence of these folders and willreconstruct the full band structure from the individual splits.

Custom k-Point Paths¶

sumo-kgen also supports generating k-points along custom k-point paths. This is controlled using the--kpoints option. The custom k-point path is specified as a string with commas separating the k-points.For example, to generate the k-points along 0. 0. 0. -> 0.5 0.5 0.5, the usage is:

sumo-kgen --kpoints "0 0 0, 0.5 0.5 0.5"

Breaks in the band structure can be indicated using the pipe character.For example, the path 0. 0. 0. -> 0.5 0.5 0.5 | 0. 0. 0. -> 0.5 0. 0., is specified as:

sumo-kgen --kpoints "0 0 0, 0.5 0.5 0.5 | 0 0 0, 0.5 0 0"

Custom labels can also be provided using the --labels option. The syntax is the same as for the--kpoints option. For example, the labels for the above path are written as:

sumo-kgen --kpoints "0 0 0, 0.5 0.5 0.5 | 0 0 0, 0.5 0 0" --labels "\Gamma, M | \Gamma, X"

Note: in all cases the arguments are surrounded in parentheses.

CASTEP¶

In CASTEP, band structure calculations also include SCF convergence sotwo sets of k-points are set: a mesh for the SCF and a path for theband structure. It is safe to provide kgen with a .cell file thatalready contains e.g. a KPOINTS_MP_GRID tag:

sumo-kgen --code castep -p seedname.cell

This will write a copy of the cell file to band.cell, including aBS_KPOINT_LIST block with the high-symmetry path and with thespecial-point labels included as comments. (These comments will helpbandplot prettify the x-axis).

Most kgen features will work as expected for CASTEP, but the--hybrid and --cartesian options are not relevant.An extra feature is provided to aid phonon calculations with CASTEP: the--phonon option will write a PHONON_FINE_KPOINT_LIST block instead.

Questaal¶

To perform LMTO band structure calculations the lmf program can begiven a file defining the band structure path. The crystal structureis defined with an init.ext file (where ext is an identifier foryour system) or a site.ext file.Questaal band structures will use the scale factor ALAT set insite.ext which may have been modified from the initial setting,so it is usually best to read from site.ext.To read the crystal structure and create a band path:

sumo-kgen --code questaal -p site.ext

will write a file named syml.ext (“symmetry lines”); by default thiswill use lattice coordinates. To perform the band structurecalculation, specify this file with e.g.:

lmf -vnit=1 --rs=1,0 --band~mq~fn=syml ext

where the ~mq switch indicates that syml.ext is in fractionalcoordinates. We recommend avoiding Cartesian coordinates for Questaalband structures; it is tested and should work but between ALAT scalingand Bohr units it can get a bit confusing.

Named Arguments¶

-p, --poscar

input structure file (default: POSCAR)

Default: “POSCAR”

-c, --code

Electronic structure code (default: vasp).”questaal” also supported.

Default: “vasp”

-d, --directory

output directory for files

-s, --split

number of k-points to include per file

-f, --folders

create folders and copy in necessary files

Default: False

-y, --hybrid

append k-points to IBZKPT file with zero weight

Default: False

--symprec

tolerance for finding symmetry (default: 0.01)

Default: 0.01

--spg

space group number or symbol

--density

k-point density along high-symmetry path

Default: 60

--seekpath

use seekpath to generate the high-symmetry path

Default: False

--pymatgen

use pymatgen to generate the high-symmetry path

Default: False

--latimer-munro

use Latimer & Munro method to generate the high-symmetry path

Default: False

--cartesian

use cartesian k-point coordinates

Default: False

--kpoints

specify a list of kpoints (e.g. “0 0 0, 0.5 0 0”)

--labels

specify the labels for kpoints (e.g. “Gamma,X”)

--phonon

Write k-points as phonon band structure path

Default: False