Key concepts#

On this page we list concepts and data structures, that are essential for understanding of wulfric's scope. And give some some code examples for each.

Cell#

cell is a two-dimensianal \(3\times3\) matrix, that defines three lattice vectors. The rows of the cell are vectors, while the columns are cartesian coordinates. Here is an example of a simple orthorhombic cell

>>> cell = [
... [3.553350, 0.000000, 0.000000],
... [0.000000, 4.744935, 0.000000],
... [0.000000, 0.000000, 8.760497],
... ]

The functions of wulfric assume that the cell is array-like, i. e. that it can be converted to the NumPy array.

>>> import numpy as np
>>> cell = np.array(cell, dtype=float)

There is a lot of things that one can do with cell. All functions that deal with the cell alone (i.e. do not require any atoms) are implemented in the wulfric.cell submodule. For more detailed examples of what can be done with the cell see Manipulations with cell.

Atoms#

Atoms in wulfric are stored as a plain python dictionary. Keys of the atoms are properties of atoms. Values are the lists of \(N\) elements each, where \(N\) is an amount of atoms.

>>> atoms = {
...     "names": ["Cr1", "Br1", "S1", "Cr2", "Br2", "S2"],
...     "species": ["Cr", "Br", "S", "Cr", "Br", "S"],
...     "positions": [
...         [0.500000, 0.000000, 0.882382],
...         [0.000000, 0.000000, 0.677322],
...         [0.500000, 0.500000, 0.935321],
...         [0.000000, 0.500000, 0.117618],
...         [0.500000, 0.500000, 0.322678],
...         [0.000000, 0.000000, 0.064679],
...     ],
... }

Keys recognized by wulfric:

  • "names" : list of str.

  • "species" : list of str.

  • "positions" : list of relative positions of atoms. Each element is an array-like of the length \(3\).

  • "spglib_types" : list of int. Each element is >=1.

Wulfric uses only those four keys, however, we invite you to extend the atoms to your needs and store any properties in the same dictionary. Any function of wulfric that reads atoms dictionary and returns new_atoms dictionary will transfer the values of each atom in atoms to the corresponding atom of new_atoms for every key, not only for ones that wulfric recognizes. atoms dictionary allows to use wulfric's functions on the user-extendend atoms. Functions of wulfric will only ever modify the key-values that are recognized by it and leave the user-defined ones intact.

Hint

If you want to have an attribute-like access to the atoms properties, then you can add some Syntactic sugar to any dictionary with

>>> import wulfric
>>> atoms = wulfric.add_sugar(atoms)
>>> atoms.names
['Cr1', 'Br1', 'S1', 'Cr2', 'Br2', 'S2']

See wulfric.add_sugar() and wulfric.remove_sugar() for more.

Crystal#

Crystal is simply a pair of cell and atoms. There is no dedicated data structure for crystal in wulfric (not even a tuple (cell, atoms)). If necessary the user must provide two variables: cell and atoms. atoms["positions"] are always interpreted by wulfric as relative with respect to cell. Therefore, user is responsible for providing appropriate cell for any given atoms.

For example, cell and atoms from the above two sections describe a crystal of CrSBr from materials cloud.

K-path#

Wulfric understands kpath of the format like "G-K-X|R-S".

  • K-points are identified by their names. Name can not contain "-".

  • | separates subpaths. Each subpath has to contain at least two points. Path has to have at least one subpath.

  • - separates high-symmetry points in each subpath.

Almost every function of wulfric expects k-path to be given as a string in that format.

The concept of subpaths allows to "jump" from one k-point to another, without following a path in between. For instance, in the path "G-K-X|R-S" for the band structure calculation/plots some amount of intermediate points is implied between "G" and "K", between "K" and "X" and between "R" and "S". However, there is no intermediate points between "X" and "R".

Internally the path is stored as list of list of str, i.e. as list of subpaths, where each subpath is a list of names of high-symmetry points. Functions wulfric.kpoints.get_path_as_string() and wulfric.kpoints.get_path_as_list() can be used for conversion between representations if necessary.

Here are some examples

As string

As list of list of str

G-K

[["G", "K"]]

G-K-X|R-S

[["G","K","X",],["R","S"]]

S1-K-G

[["S1", "K", "G"]]