Welcome to kristal’s documentation!

Kristal is an user friendly package for matching crystallographic structures.

Installation

Currently you can only install Kristal locally:

  1. Clone repository

  2. From top level directory run:

    pip install .

You can also use pip install -e . to install in editable (development mode).

Modules

kristal.io

Main file of kristal.io package.

kristal.io.read_cif(cif_path, transformer=None)

Read content of given CIF file.

Parameters:
  • cif_path (str or pathlib.Path) – path of the CIF file to be read. Can be given as a str object or pathlib.Path object.
  • transformer (a subclass of lark.Transformer.) – an optional transformer object that will be used to transformer the parsed tree. It not given, a default transformer will be used.
Returns:

a mapping name -> datablock holding information read from all datablocks present in CIF file.
Return type:

A mapping str -> kristal.io.transform.DataBlock. The DataBlock objects have the following attributes: - name: name of the datablock - entries: non-loop dataitems - loop: list of all loops

The non-loop dataitems are stored as pandas.Series (can be accessed like a dictionary). The loops are stored as pandas.DataFrame.

kristal.geometry

Various utilities for working with atoms’ equivalence positions.

class kristal.geometry.equiv.FractionalCoordinateSystem(a, b, c, alpha, beta, gamma)

Class representing fractional coordinates system.

Variables:
  • a (float) – length of first periodic vector.
  • b (float) – length of second periodic vector.
  • c (float) – length of second periodic vector.
  • alpha (float) – an angle between second and third periodic vector.
  • beta (float) – an angle between first and third periodic vector.
  • gamma (float) – an angle between first and second periodic vector.
Parameters:
  • a (float) – length of first periodic vector.
  • b (float) – length of second periodic vector.
  • c (float) – length of second periodic vector.
  • alpha (float) – an angle between second and third periodic vector.
  • beta (float) – an angle between first and third periodic vector.
  • gamma (float) – an angle between first and second periodic vector.
change_of_basis_matrix()

Change of basis matrix from fractional to Cartesian coordinates.

Let \((u, v, w)\) be components of arbitrary vector in fractional coordinates. Components of this vector in Cartesian coordinates are given by

\[\begin{split}\begin{bmatrix} x \\ y \\ z \end{bmatrix} = M \cdot \begin{bmatrix} u \\ v \\ w \end{bmatrix}\end{split}\]

where \(M\) is given by

\[\begin{split}M = \begin{bmatrix} a & b \cos(\gamma) & c \cos(\beta) \\ 0 & b \sin(\gamma) & c \frac{\cos(\alpha) - \cos(\beta)\cos(\gamma)}{\sin(\gamma)} \\ 0 & 0 & \frac{V}{ab \sin(\gamma)} \end{bmatrix}\end{split}\]

This method returns \(M\) from the above equation.

inv_change_of_basis_matrix()

“Matrix changing basis from this system to Cartesian.

This is an inverse of a matrix \(M\) returned by change_of_basis_matrix().

unit_cell_volume

Volume of the cell in this coordinates system.

Volume of the unit cell is defined as a volume of parallelepiped determined by periodic vectors and is given by:

\[V = abc \sqrt{1 - \cos^2(\alpha) - \cos^2(\beta) - \cos^2(\gamma) + 2\cos(\alpha)\cos(\beta) \cos(\gamma)}\]
kristal.geometry.equiv.cos2(x)

Shortcut for computing np.cos(x) ** 2.

kristal.geometry.equiv.sin2(x)

Shortcut for computing np.sin(x) ** 2.

Indices and tables