crystals : data structure for crystallography

PyPI Package latest release Conda-forge Version

crystals is a library of data structure and algorithms to manipulate abstract crystals. crystals helps with reading crystallographic files (like .cif and .pdb), provides access to atomic positions, and allows for space-group determination. Although crystals can be used on its own, it was made to be integrated into larger projects (like scikit-ued).

Table of content

Usage example

crystals is all about constructing crystals and getting information about the resulting object. Crystals can be built from a variety of sources:

Here’s a quick example of building a crystal from the internal database:

>>> from crystals import Crystal
>>> vo2 = Crystal.from_database('vo2-m1')
>>> print(vo2)         # Short string representation
< Crystal object with following unit cell:
    Atom O  @ (0.10, 0.21, 0.20)
    Atom O  @ (0.10, 0.29, 0.70)
    Atom O  @ (0.39, 0.69, 0.29)
    Atom O  @ (0.39, 0.81, 0.79)
    Atom O  @ (0.61, 0.19, 0.21)
    Atom O  @ (0.61, 0.31, 0.71)
    Atom O  @ (0.90, 0.71, 0.30)
    Atom O  @ (0.90, 0.79, 0.80)
    Atom V  @ (0.24, 0.53, 0.53)
    Atom V  @ (0.24, 0.97, 0.03)
      ... omitting 2 atoms ...
      ... use repr() to show the full cell ...
Lattice parameters:
    a=5.743Å, b=4.517Å, c=5.375Å
    α=90.000°, β=122.600°, γ=90.000°
Chemical composition:
     O: 66.667%
     V: 33.333% >

Symmetry information is also readily available:

>>> from crystals import Crystal
>>> from pprint import pprint # pretty printing
>>> vo2 = Crystal.from_database('vo2-m1')
>>> pprint(vo2.symmetry())
{'centering': <CenteringType.primitive: 'P'>,
 'hall_number': 81,
 'hall_symbol': '-P 2ybc',
 'hm_symbol': 'P121/c1',
 'international_full': 'P 1 2_1/c 1',
 'international_number': 14,
 'international_symbol': 'P2_1/c',
 'pointgroup': '2/m'}


This package depends on the work of some amazing people. Of note are the spglib contributors


As this package is a spinoff from scikit-ued, please consider citing the following publication if you find crystals useful:

L. P. René de Cotret, M. R. Otto, M. J. Stern. and B. J. Siwick, An open-source software ecosystem for the interactive exploration of ultrafast electron scattering data, Advanced Structural and Chemical Imaging 4:11 (2018)

Underlying algorithms provided by spglib are described in the following publication:

A. Togo and I. Tanaka, spglib: a software library for crystal symmetry search. arxiv/1808.01590 (written at version 1.10.4).

Structure parsing from CIF files has been tested for correctness against CIF2CELL, detailed here:

Torbjorn Bjorkman, CIF2Cell: Generating geometries for electronic structure programs, Computer Physics Communications 182, 1183-1186 (2011)

Structure parsing from PDB files has been tested for correctness against Bio.PDB, detailed here:

Hamelryck, T., Manderick, B. PDB parser and structure class implemented in Python. Bioinformatics 19: 2308–2310 (2003)

Support / Report Issues

All support requests and issue reports should be filed on Github as an issue.


crystals is made available under the GPLv3 license. For more details, see LICENSE.