Skip to main content

Automatic generation of crystal structure descriptions

Project description

robocrystallographer logo

PyPI version CircleCI

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...

Usage

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 SnO2 (mp-856), one can simply run:

robocrys mp-856

Alternatively, a structure file can be specified in place of a Materials Project id. Robocrystallographer supports the same file formats as pymatgen, including the Crystallographic Information Format (CIF), and common electronic structure package formats such as POSCAR files. More information can be found on the command-line interface page.

Python interface

The two core classes in robocrystallographer are:

  • StructureCondenser: to condense the structure into an descriptive JSON representation.
  • StructureDescriber: to turn the condensed structure into a text description.

A minimal working example for generating text descriptions is simply:

from pymatgen import Structure
from robocrys import StructureCondenser, StructureDescriber

structure = Structure.from_file("my_structure.cif") # other file formats also supported

# alternatively, uncomment the lines below to use the MPRester object
# to fetch structures from the Materials Project database
# from mp_api.client import MPRester
# structure = MPRester(api_key=None).get_structure_by_material_id("mp-856")

condenser = StructureCondenser()
describer = StructureDescriber()

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

Where structure is a pymatgen Structure object. Both classes have many options for customising the output of the structure descriptions. More information is provided in the module documentation.

Intermediate JSON format

The format of the intermediate JSON representation is detailed on the condensed structure format page.

Example output

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

SnO2 crystal structure

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.

How to cite robocrystallographer

Please considering citing the following publication if using robocrystallographer in your work:

Ganose, A., & Jain, A. (2019). Robocrystallographer: Automated crystal structure text descriptions and analysis. MRS Communications, 9(3), 874-881. https://doi.org/10.1557/mrc.2019.94

Installation

Robocrystallographer can be installed using pip:

pip install robocrys

Robocrystallographer requires Python 3.7+. 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 conda-forge openbabel

What’s new?

Track changes to robocrystallographer through the Changelog.

Contributing

Robocrystallographer is in early development but we still welcome your contributions. Please read our contribution guidelines for more information. We maintain a list of all contributors here.

License

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

Acknowledgements

Logo by Somewan from the Noun Project.

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.2.10.tar.gz (3.8 MB view details)

Uploaded Source

Built Distribution

robocrys-0.2.10-py3-none-any.whl (3.8 MB view details)

Uploaded Python 3

File details

Details for the file robocrys-0.2.10.tar.gz.

File metadata

  • Download URL: robocrys-0.2.10.tar.gz
  • Upload date:
  • Size: 3.8 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.1 CPython/3.9.20

File hashes

Hashes for robocrys-0.2.10.tar.gz
Algorithm Hash digest
SHA256 6ca56df390dc312e4cb8fafcc1d9a5e132bcefd2b62cb2bbe007c13e7206d2bc
MD5 8370dd0f1ec99908c0daa4f679b86e32
BLAKE2b-256 161c9802111f02cf77ea90c8a597de94dd903a0d0edede12ac1ce3b8e61ec75c

See more details on using hashes here.

File details

Details for the file robocrys-0.2.10-py3-none-any.whl.

File metadata

  • Download URL: robocrys-0.2.10-py3-none-any.whl
  • Upload date:
  • Size: 3.8 MB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.1 CPython/3.9.20

File hashes

Hashes for robocrys-0.2.10-py3-none-any.whl
Algorithm Hash digest
SHA256 0a9a9bf9940d50620c3bdc999d2a8ccfe923eee9ab32619eab1550889985c3be
MD5 c5878f4757e33478e1f8a61de5763be6
BLAKE2b-256 6303cb8b23234d8b50c0d93a069f0890d17aea7d0219892a16a2ae86e9829c45

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page