Key concepts#

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

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. 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 are implemented under wulfric.cell.

For the given cell one can compute a set of lattice parameters: lengths of the lattice vectors and pair-wise angles between them as

>>> import wulfric as wulf
>>> wulf.cell.get_params(cell)
(3.55335, 4.744935, 8.760497, 90.0, 90.0, 90.0)

This function returns six numbers (a, b, c, alpha, beta, gamma).

Another typical task is to find a reciprocal cell

>>> wulf.cell.get_reciprocal(cell)
array([[1.76824273, 0.        , 0.        ],
       [0.        , 1.32418786, 0.        ],
       [0.        , 0.        , 0.71721791]])

For more examples of what can be done with cell see Manipulations with cell.

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],
...     ],
... }

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.

Keys recognized by wulfric:

  • "names" : list of str

  • "species" : list of str.

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

Wulfric recognizes only a few keys, however, we invite you to extend the atoms to your needs. Here is a list a few of the potential keys that are not used by any of wulfric's functions, but may be useful or be used by wulfric in the future.

  • "spin_vectors"

  • "g_factors"

  • "charges"

  • ...

atoms dictionary allows to use wulfric's functions on the user-extendend atoms. Functions of wulfric will only 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

>>> atoms = wulf.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. We do not introduce any new structure for the crystal (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.

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.

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.

Below we give a table with 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"]]