Skip to main content

Automatic generation of crystal structure descriptions

Project description

Pypi Repository Build Status

Robocrystallographer is a tool to generate text descriptions of crystal structures. Similar to how a real-life crystallographer would analyse a structure, robocrystallographer looks at the symmetry, local environment, and extended connectivity when generating a description. The package includes utilities for identifying molecule names, component orientations, heterostructure information, and more…


Robocrystallographer can be used from the command-line or from a python API. The package integrates with the Materials Project to for allow generation of structure descriptions directly from materials project ids. For example, to generate the description of SnO 2 (mp-856), one can simply run:

robocrystallographer mp-856

Alternatively, a structure file can be specified in place of an mp-id. Robocrystallographer supports the same file formats as pymatgen, including the Crystallographic Information Format (CIF), and common electronic structure package formats such as POSCAR.

Python Interface

The two core classes in robocrystallographer are:

  • StructureCondenser: to condense the structure into an intermediate JSON representation.

  • StructureDescriber: to turn the condensed structure into a text description.

The format of the intermediate JSON representation is detailed on the Condensed Structure Format page page. A minimal working example for generating text descriptions is simply:

from robocrys import StructureCondenser, StructureDescriber

condenser = StructureCondenser()
describer = StructureDescriber()
condensed_structure = condenser.condense_structure(structure)
description = describer.describe(condensed_structure)

Both classes have many options for customising the output of the structure descriptions. More information is provided in the Module Documentation page.

Example Output

An example of the output generated by robocrystallographer for SnO 2 (mp-856) is given below:

SnO2 is Rutile structured and crystallizes in the tetragonal P4_2/mnm space group. The structure is three-dimensional. Sn(1) is bonded to six equivalent O(1) atoms to form a mixture of edge and corner-sharing SnO6 octahedra. The corner-sharing octahedral tilt angles are 51°. All Sn(1)–O(1) bond lengths are 2.09 Å. O(1) is bonded in a trigonal planar geometry to three equivalent Sn(1) atoms.


Robocrystallographer can be installed using pip:

pip install robocrystallographer

Robocrystallographer requires Python 3.5+. The OpenBabel package is required to determine molecule names. This is an optional requirement but its use is recommended for best results. If you are using the Conda package management system, OpenBabel can be installed using:

conda install -c openbabel openbabel

More information is available here.


Robocrystallographer is released under a modified BSD license; the full text can be found here.


Robocrystallographer is in early development and we therefore welcome your contributions. Please read our contribution guidelines for more information.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

robocrys-0.1.0.tar.gz (3.8 MB view hashes)

Uploaded source

Built Distribution

robocrys-0.1.0-py3-none-any.whl (3.8 MB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page