Metadata-Version: 2.1
Name: robocrys
Version: 0.1.0
Summary: Automatic generation of crystal structure descriptions
Home-page: https://github.com/hackingmaterials/robocrystallographer
Author: Alex Ganose
Author-email: aganose@lbl.gov
License: modified BSD
Keywords: crystal-structure crystallography materials-science
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Other/Nonlisted Topic
Classifier: Operating System :: OS Independent
Requires-Dist: spglib
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: pymatgen (>=2017.12.30)
Requires-Dist: inflect
Requires-Dist: networkx
Requires-Dist: matminer
Requires-Dist: monty
Requires-Dist: pubchempy
Provides-Extra: dev
Requires-Dist: tqdm; extra == 'dev'
Requires-Dist: pybel; extra == 'dev'
Requires-Dist: pebble; extra == 'dev'
Requires-Dist: maggma; extra == 'dev'
Provides-Extra: docs
Requires-Dist: sphinx; extra == 'docs'
Requires-Dist: sphinx-argparse; extra == 'docs'
Requires-Dist: sphinx-autodoc-types (>=2.1.1); extra == 'docs'

Robocrystallographer
====================

.. image:: https://badge.fury.io/py/robocrystallographer.svg
    :target: https://badge.fury.io/py/robocrystallographeer
    :alt: Pypi Repository

.. image:: https://travis-ci.org/hackingmaterials/robocrystallographer.svg?branch=master
    :target: https://travis-ci.org/hackingmaterials/robocrystallographer
    :alt: 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...

Usage
-----

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

.. code-block:: bash

    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 <https://google.com>`_ page.
A minimal working example for generating text descriptions is simply:

.. code-block:: python

    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
<http://google.com>`_.

Example Output
^^^^^^^^^^^^^^

An example of the output generated by robocrystallographer for SnO :sub:`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.

Installation
------------

Robocrystallographer can be installed using pip:

.. code-block:: bash

    pip install robocrystallographer

Robocrystallographer requires Python 3.5+. The `OpenBabel
<http://openbabel.org/wiki/Python>`_ 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 <https://conda.io/>`_ package management
system, OpenBabel can be installed using:

.. code-block:: bash

    conda install -c openbabel openbabel

More information is available `here <https://anaconda.org/openbabel/openbabel>`__.

License
-------

Robocrystallographer is released under a modified BSD license;
the full text can be found `here
<https://github.com/hackingmaterials/robocrystallographer/blob/master/LICENSE>`__.

Contributing
------------

Robocrystallographer is in early development and we therefore welcome your
contributions. Please read our `contribution guidelines
<https://github.com/hackingmaterials/robocrystallographer/blob/master/CONTRIBUTING.rst>`_
for more information.

.. _pymatgen: http://pymatgen.org
.. _mp-856: https://materialsproject.org/materials/mp-856/


