sumo.symmetry package¶
Module contents¶
Package containing functions for symmetry and k-point paths.
Submodules¶
sumo.symmetry.kpoints module¶
Module providing helper functions for generating k-points along a path.
- sumo.symmetry.kpoints.get_path_data(structure, mode='bradcrack', symprec=0.01, spg=None, line_density=60, cart_coords=False, kpt_list=None, labels=None, phonopy=False)[source]¶
Get the k-point path, coordinates and symmetry labels for a structure.
If a manual
list
of kpoints is supplied using thekpt_list
variable, themode
option will be ignored.The format of the returned data will be different if phonopy is
True
orFalse
. This is because phonopy requires the labels and kpoints to be provided in a different format than kgen.- Parameters:
structure (
Structure
) – The structure.mode (
str
, optional) –Method used for calculating the high-symmetry path. The options are:
symprec (
float
, optional) – The tolerance for determining the crystal symmetry.spg (
SpaceGroup
, optional) – Space group used to override the symmetry determined by spglib. This is not recommended and only provided for testing purposes. This option will only take effect whenmode = 'bradcrack'
.line_density (
int
, optional) – Density of k-points along the path.cart_coords (
bool
, optional) – Whether the k-points are returned in cartesian or reciprocal coordinates. Defaults toFalse
(fractional coordinates).kpt_list (
list
, optional) –List of k-points to use, formatted as a list of subpaths, each containing a list of fractional k-points. For example:
[ [[0., 0., 0.], [0., 0., 0.5]], [[0.5, 0., 0.], [0.5, 0.5, 0.]] ]
Will return points along
0 0 0 -> 0 0 1/2 | 1/2 0 0 -> 1/2 1/2 0
path_labels (
list
, optional) –The k-point labels. These should be provided as a
list
ofstr
for each subpath of the overall path. For example:[ ['Gamma', 'Z'], ['X', 'M'] ]
combined with the above example for
kpt_list
would indicate the path: Gamma -> Z | X -> M. If no labels are provided, letters from A -> Z will be used instead.phonopy (
bool
, optional) – Format the k-points and labels for use with phonopy. Defaults toFalse
.
- Returns:
A tuple of a
kpath
object, the k-points along the high-symmetry path, and the k-point labels. Returned as(kpath, kpoints, labels)
.The type of
kpath
object will depend on the value ofmode
and whetherkpt_list
is set.If
phonopy == False
, then:kpoints
is anumpy.ndarray
of the k-pointcoordinates along the high-symmetry path. For example:
[[0, 0, 0], [0.25, 0, 0], [0.5, 0, 0], [0.5, 0, 0.25], [0.5, 0, 0.5]]
If
phonopy == True
, then:kpoints
is alist
ofnumpy.ndarray
containing the k-points for each branch of the band structure. This means that the first and last k-points of a particular branch may be repeated. For example:
[[[0, 0, 0], [0.25, 0, 0], [0.5, 0, 0]], [[0.5, 0, 0], [0.5, 0, 0.25], [0.5, 0, 0.5]]]
labels
is alist
of the high symmetry labels.For example:
['\Gamma', 'X', 'Y']
- Return type:
sumo.symmetry.kpath module¶
Module containing the base class for high-symmetry k-point path determination.
- class sumo.symmetry.kpath.Kpath(structure, symprec=0.001)[source]¶
Bases:
object
Base class providing helper functions for generating k-point paths.
This class should not be used directly. Instead, one of the
BradCrackKpath
,SeekpathKpath
, orCustomKpath
, subclasses should be used.The main use of this parent object is for standardisation across the differing k-point path generation classes.
- Parameters:
- correct_structure(atol=1e-08)[source]¶
Determine if the structure matches the standard primitive structure.
The standard primitive will be different between seekpath and pymatgen high-symmetry paths, but this is handled by the specific subclasses.
- get_kpoints(line_density=20, cart_coords=False, phonopy=False)[source]¶
Return a list of k-points and labels along the high-symmetry path.
The format of the returned data will be different if phonopy is
True
orFalse
. This is because phonopy requires the labels and kpoints to be provided in a different format than kgen.Adapted from
pymatgen.symmetry.bandstructure.HighSymmKpath.get_kpoints
.- Parameters:
line_density (
int
, optional) – Density of k-points along the path.cart_coords (
bool
, optional) – Whether the k-points are returned in cartesian or reciprocal coordinates. Defaults toFalse
(fractional coordinates).phonopy (
bool
, optional) – Format the k-points and labels for use with phonopy. Defaults toFalse
.
- Returns:
A
tuple
of the k-points along the high-symmetry path, and k-point labels. Returned as(kpoints, labels)
.If
phonopy == False
, then:kpoints
is anumpy.ndarray
of the k-point coordinates along the high-symmetry path. For example:[[0, 0, 0], [0.25, 0, 0], [0.5, 0, 0], [0.5, 0, 0.25], [0.5, 0, 0.5]]
labels
is alist
of the high symmetry labels for each k-point (will be an emptystr
if the k-point has no label). For example:['\Gamma', '', 'X', '', 'Y']
If
phonopy == True
, then:kpoints
is alist
ofnumpy.ndarray
containing the k-points for each branch of the band structure. This means that the first and last k-points of a particular branch may be repeated. For example:[[[0, 0, 0], [0.25, 0, 0], [0.5, 0, 0]], [[0.5, 0, 0], [0.5, 0, 0.25], [0.5, 0, 0.5]]]
labels
is alist
of the high symmetry labels. For example:['\Gamma', 'X', 'Y']
- Return type:
- static get_lattice_type(number)[source]¶
Return the lattice crystal system.
Hexagonal cells are differentiated into rhombohedral and hexagonal lattices.
- property kpoints¶
The high-symmetry k-point labels and their fractional coordinates. Formatted as
{label: coords}
. For example:{'\Gamma': [0., 0., 0.], 'X': [0.5, 0. 0.]}
- Type:
- property lattice_type¶
The Bravais lattice system. Hexagonal cells are separated into rhombohedral and hexagonal lattices.
- Type:
- property path¶
The high-symmetry k-point path. Each subpath is provided as a list. For example, the following covers the path
\Gamma -> X -> C | \Gamma -> Y
:[['\Gamma', 'X', 'C'], ['\Gamma', 'Y']].
- Type:
- property path_string¶
The high-symmetry k-point path formatted with arrows and showing disconnections between subpaths. For example:
"X -> Gamma | Y -> Z"
- Type:
sumo.symmetry.brad_crack_kpath module¶
Module containing class for generating Bradley and Cracknell k-point paths.
- class sumo.symmetry.brad_crack_kpath.BradCrackKpath(structure, symprec=0.001, spg=None)[source]¶
Bases:
Kpath
Class to generate k-points along paths from Bradley and Cracknell.
The paths used are based on Brillouin zones depicted in reference [brad].
These paths represent only one particular route through the Brillouin zone and do not cover every possible path (though they do visit every high-symmetry k-point at least once).
These paths should be used with the correct primitive structure. This structure can be accessed using the
prim
attribute. Compliance between the provided structure and standardised structure checked using thecorrect_structure()
method.- Parameters:
structure (
Structure
) – The structure.symprec (
float
, optional) – The tolerance for determining the crystal symmetry.spg (
SpaceGroup
, optional) – Space group used to override the symmetry determined by spglib. This is not recommended and only provided for testing purposes.
- correct_structure(atol=1e-08)¶
Determine if the structure matches the standard primitive structure.
The standard primitive will be different between seekpath and pymatgen high-symmetry paths, but this is handled by the specific subclasses.
- get_kpoints(line_density=20, cart_coords=False, phonopy=False)¶
Return a list of k-points and labels along the high-symmetry path.
The format of the returned data will be different if phonopy is
True
orFalse
. This is because phonopy requires the labels and kpoints to be provided in a different format than kgen.Adapted from
pymatgen.symmetry.bandstructure.HighSymmKpath.get_kpoints
.- Parameters:
line_density (
int
, optional) – Density of k-points along the path.cart_coords (
bool
, optional) – Whether the k-points are returned in cartesian or reciprocal coordinates. Defaults toFalse
(fractional coordinates).phonopy (
bool
, optional) – Format the k-points and labels for use with phonopy. Defaults toFalse
.
- Returns:
A
tuple
of the k-points along the high-symmetry path, and k-point labels. Returned as(kpoints, labels)
.If
phonopy == False
, then:kpoints
is anumpy.ndarray
of the k-point coordinates along the high-symmetry path. For example:[[0, 0, 0], [0.25, 0, 0], [0.5, 0, 0], [0.5, 0, 0.25], [0.5, 0, 0.5]]
labels
is alist
of the high symmetry labels for each k-point (will be an emptystr
if the k-point has no label). For example:['\Gamma', '', 'X', '', 'Y']
If
phonopy == True
, then:kpoints
is alist
ofnumpy.ndarray
containing the k-points for each branch of the band structure. This means that the first and last k-points of a particular branch may be repeated. For example:[[[0, 0, 0], [0.25, 0, 0], [0.5, 0, 0]], [[0.5, 0, 0], [0.5, 0, 0.25], [0.5, 0, 0.5]]]
labels
is alist
of the high symmetry labels. For example:['\Gamma', 'X', 'Y']
- Return type:
- static get_lattice_type(number)¶
Return the lattice crystal system.
Hexagonal cells are differentiated into rhombohedral and hexagonal lattices.
- property kpoints¶
The high-symmetry k-point labels and their fractional coordinates. Formatted as
{label: coords}
. For example:{'\Gamma': [0., 0., 0.], 'X': [0.5, 0. 0.]}
- Type:
- property lattice_type¶
The Bravais lattice system. Hexagonal cells are separated into rhombohedral and hexagonal lattices.
- Type:
- property path¶
The high-symmetry k-point path. Each subpath is provided as a list. For example, the following covers the path
\Gamma -> X -> C | \Gamma -> Y
:[['\Gamma', 'X', 'C'], ['\Gamma', 'Y']].
- Type:
- property path_string¶
The high-symmetry k-point path formatted with arrows and showing disconnections between subpaths. For example:
"X -> Gamma | Y -> Z"
- Type:
sumo.symmetry.pymatgen_kpath module¶
Module containing class for generating k-points along paths from pymatgen.
- class sumo.symmetry.pymatgen_kpath.PymatgenKpath(structure, symprec=0.001)[source]¶
Bases:
Kpath
Class to generate k-points along paths from pymatgen.
More detail on the paths generated by can be found in the pymatgen documentation. These paths are based on the work described in reference [curt].
These paths should be used with primitive structures that comply with the definition from the paper. This structure can be accessed using the
prim
attribute and compliance between the provided structure and standardised structure checked using thecorrect_structure()
method.- Parameters:
- correct_structure(atol=1e-08)¶
Determine if the structure matches the standard primitive structure.
The standard primitive will be different between seekpath and pymatgen high-symmetry paths, but this is handled by the specific subclasses.
- get_kpoints(line_density=20, cart_coords=False, phonopy=False)¶
Return a list of k-points and labels along the high-symmetry path.
The format of the returned data will be different if phonopy is
True
orFalse
. This is because phonopy requires the labels and kpoints to be provided in a different format than kgen.Adapted from
pymatgen.symmetry.bandstructure.HighSymmKpath.get_kpoints
.- Parameters:
line_density (
int
, optional) – Density of k-points along the path.cart_coords (
bool
, optional) – Whether the k-points are returned in cartesian or reciprocal coordinates. Defaults toFalse
(fractional coordinates).phonopy (
bool
, optional) – Format the k-points and labels for use with phonopy. Defaults toFalse
.
- Returns:
A
tuple
of the k-points along the high-symmetry path, and k-point labels. Returned as(kpoints, labels)
.If
phonopy == False
, then:kpoints
is anumpy.ndarray
of the k-point coordinates along the high-symmetry path. For example:[[0, 0, 0], [0.25, 0, 0], [0.5, 0, 0], [0.5, 0, 0.25], [0.5, 0, 0.5]]
labels
is alist
of the high symmetry labels for each k-point (will be an emptystr
if the k-point has no label). For example:['\Gamma', '', 'X', '', 'Y']
If
phonopy == True
, then:kpoints
is alist
ofnumpy.ndarray
containing the k-points for each branch of the band structure. This means that the first and last k-points of a particular branch may be repeated. For example:[[[0, 0, 0], [0.25, 0, 0], [0.5, 0, 0]], [[0.5, 0, 0], [0.5, 0, 0.25], [0.5, 0, 0.5]]]
labels
is alist
of the high symmetry labels. For example:['\Gamma', 'X', 'Y']
- Return type:
- static get_lattice_type(number)¶
Return the lattice crystal system.
Hexagonal cells are differentiated into rhombohedral and hexagonal lattices.
- property kpoints¶
The high-symmetry k-point labels and their fractional coordinates. Formatted as
{label: coords}
. For example:{'\Gamma': [0., 0., 0.], 'X': [0.5, 0. 0.]}
- Type:
- property lattice_type¶
The Bravais lattice system. Hexagonal cells are separated into rhombohedral and hexagonal lattices.
- Type:
- property path¶
The high-symmetry k-point path. Each subpath is provided as a list. For example, the following covers the path
\Gamma -> X -> C | \Gamma -> Y
:[['\Gamma', 'X', 'C'], ['\Gamma', 'Y']].
- Type:
- property path_string¶
The high-symmetry k-point path formatted with arrows and showing disconnections between subpaths. For example:
"X -> Gamma | Y -> Z"
- Type:
sumo.symmetry.seekpath_kpath module¶
Module containing class for generating k-points along paths from SeeK-path.
- class sumo.symmetry.seekpath_kpath.SeekpathKpath(structure, symprec=0.001)[source]¶
Bases:
Kpath
Class to generate k-points along paths from SeeK-path.
More detail on the paths generated by SeeK-path can be found in reference [seek].
These paths should be used with primitive structures that comply with the definition from the paper. This structure can be accessed using the
prim
attribute and compliance between the provided structure and standardised structure checked using thecorrect_structure()
method.- Parameters:
- correct_structure(atol=1e-08)¶
Determine if the structure matches the standard primitive structure.
The standard primitive will be different between seekpath and pymatgen high-symmetry paths, but this is handled by the specific subclasses.
- get_kpoints(line_density=20, cart_coords=False, phonopy=False)¶
Return a list of k-points and labels along the high-symmetry path.
The format of the returned data will be different if phonopy is
True
orFalse
. This is because phonopy requires the labels and kpoints to be provided in a different format than kgen.Adapted from
pymatgen.symmetry.bandstructure.HighSymmKpath.get_kpoints
.- Parameters:
line_density (
int
, optional) – Density of k-points along the path.cart_coords (
bool
, optional) – Whether the k-points are returned in cartesian or reciprocal coordinates. Defaults toFalse
(fractional coordinates).phonopy (
bool
, optional) – Format the k-points and labels for use with phonopy. Defaults toFalse
.
- Returns:
A
tuple
of the k-points along the high-symmetry path, and k-point labels. Returned as(kpoints, labels)
.If
phonopy == False
, then:kpoints
is anumpy.ndarray
of the k-point coordinates along the high-symmetry path. For example:[[0, 0, 0], [0.25, 0, 0], [0.5, 0, 0], [0.5, 0, 0.25], [0.5, 0, 0.5]]
labels
is alist
of the high symmetry labels for each k-point (will be an emptystr
if the k-point has no label). For example:['\Gamma', '', 'X', '', 'Y']
If
phonopy == True
, then:kpoints
is alist
ofnumpy.ndarray
containing the k-points for each branch of the band structure. This means that the first and last k-points of a particular branch may be repeated. For example:[[[0, 0, 0], [0.25, 0, 0], [0.5, 0, 0]], [[0.5, 0, 0], [0.5, 0, 0.25], [0.5, 0, 0.5]]]
labels
is alist
of the high symmetry labels. For example:['\Gamma', 'X', 'Y']
- Return type:
- static get_lattice_type(number)¶
Return the lattice crystal system.
Hexagonal cells are differentiated into rhombohedral and hexagonal lattices.
- classmethod kpath_from_seekpath(seekpath, point_coords)[source]¶
Convert seekpath-formatted kpoints path to sumo-preferred format.
If ‘GAMMA’ is used as a label this will be replaced by ‘Gamma’.
- Parameters:
seekpath (list) –
A
list
of 2-tuples containing the labels at each side of each segment of the k-point path:[(A, B), (B, C), (C, D), ...]
where a break in the sequence is indicated by a non-repeating label. E.g.:
[(A, B), (B, C), (D, E), ...]
for a break between C and D.
point_coords (dict) –
Dict of coordinates corresponding to k-point labels:
{'GAMMA': [0., 0., 0.], ...}
- Returns:
The path and k-points as:
{ 'path', [[l1, l2, l3], [l4, l5], ...], 'kpoints', {l1: [a1, b1, c1], l2: [a2, b2, c2], ...} }
- Return type:
- property kpoints¶
The high-symmetry k-point labels and their fractional coordinates. Formatted as
{label: coords}
. For example:{'\Gamma': [0., 0., 0.], 'X': [0.5, 0. 0.]}
- Type:
- property lattice_type¶
The Bravais lattice system. Hexagonal cells are separated into rhombohedral and hexagonal lattices.
- Type:
- property path¶
The high-symmetry k-point path. Each subpath is provided as a list. For example, the following covers the path
\Gamma -> X -> C | \Gamma -> Y
:[['\Gamma', 'X', 'C'], ['\Gamma', 'Y']].
- Type:
- property path_string¶
The high-symmetry k-point path formatted with arrows and showing disconnections between subpaths. For example:
"X -> Gamma | Y -> Z"
- Type:
sumo.symmetry.custom_kpath module¶
Module containing class for generating custom k-point paths.
- class sumo.symmetry.custom_kpath.CustomKpath(structure, kpt_list, path_labels=None, symprec=0.001)[source]¶
Bases:
Kpath
Class to generate k-points along custom k-point paths.
- Parameters:
structure (
Structure
) – The structure.symprec (
float
, optional) – The tolerance for determining the crystal symmetry.kpt_list (list) –
List of k-points to use, formatted as a list of subpaths, each containing a list of fractional k-points. For example:
[ [[0., 0., 0.], [0., 0., 0.5]], [[0.5, 0., 0.], [0.5, 0.5, 0.]] ]
Will return points along
0 0 0 -> 0 0 1/2 | 1/2 0 0 -> 1/2 1/2 0
path_labels (
list
) –The k-point labels. These should be provided as a
list
ofstr
for each subpath of the overall path. For example:[ ['Gamma', 'Z'], ['X', 'M'] ]
combined with the above example for
kpt_list
would indicate the path: Gamma -> Z | X -> M. If no labels are provided, letters from A -> Z will be used instead.
- correct_structure(atol=1e-08)¶
Determine if the structure matches the standard primitive structure.
The standard primitive will be different between seekpath and pymatgen high-symmetry paths, but this is handled by the specific subclasses.
- get_kpoints(line_density=20, cart_coords=False, phonopy=False)¶
Return a list of k-points and labels along the high-symmetry path.
The format of the returned data will be different if phonopy is
True
orFalse
. This is because phonopy requires the labels and kpoints to be provided in a different format than kgen.Adapted from
pymatgen.symmetry.bandstructure.HighSymmKpath.get_kpoints
.- Parameters:
line_density (
int
, optional) – Density of k-points along the path.cart_coords (
bool
, optional) – Whether the k-points are returned in cartesian or reciprocal coordinates. Defaults toFalse
(fractional coordinates).phonopy (
bool
, optional) – Format the k-points and labels for use with phonopy. Defaults toFalse
.
- Returns:
A
tuple
of the k-points along the high-symmetry path, and k-point labels. Returned as(kpoints, labels)
.If
phonopy == False
, then:kpoints
is anumpy.ndarray
of the k-point coordinates along the high-symmetry path. For example:[[0, 0, 0], [0.25, 0, 0], [0.5, 0, 0], [0.5, 0, 0.25], [0.5, 0, 0.5]]
labels
is alist
of the high symmetry labels for each k-point (will be an emptystr
if the k-point has no label). For example:['\Gamma', '', 'X', '', 'Y']
If
phonopy == True
, then:kpoints
is alist
ofnumpy.ndarray
containing the k-points for each branch of the band structure. This means that the first and last k-points of a particular branch may be repeated. For example:[[[0, 0, 0], [0.25, 0, 0], [0.5, 0, 0]], [[0.5, 0, 0], [0.5, 0, 0.25], [0.5, 0, 0.5]]]
labels
is alist
of the high symmetry labels. For example:['\Gamma', 'X', 'Y']
- Return type:
- static get_lattice_type(number)¶
Return the lattice crystal system.
Hexagonal cells are differentiated into rhombohedral and hexagonal lattices.
- property kpoints¶
The high-symmetry k-point labels and their fractional coordinates. Formatted as
{label: coords}
. For example:{'\Gamma': [0., 0., 0.], 'X': [0.5, 0. 0.]}
- Type:
- property lattice_type¶
The Bravais lattice system. Hexagonal cells are separated into rhombohedral and hexagonal lattices.
- Type:
- property path¶
The high-symmetry k-point path. Each subpath is provided as a list. For example, the following covers the path
\Gamma -> X -> C | \Gamma -> Y
:[['\Gamma', 'X', 'C'], ['\Gamma', 'Y']].
- Type:
- property path_string¶
The high-symmetry k-point path formatted with arrows and showing disconnections between subpaths. For example:
"X -> Gamma | Y -> Z"
- Type: