<p align="center">
<img alt="robocrystallographer logo" src="https://raw.githubusercontent.com/hackingmaterials/robocrystallographer/master/docs/src/_static/logo-01.png" height="200px">
</p>
<p align="center">
<a href="https://pypi.org/project/robocrys/"><img alt="PyPI version" src="https://img.shields.io/pypi/v/robocrys.svg?colorB=blue"> </a>
<a href="https://github.com/hackingmaterials/robocrystallographer/actions?query=workflow%3A%22Run+tests%22"><img alt="CircleCI" src="https://img.shields.io/github/actions/workflow/status/hackingmaterials/robocrystallographer/tests.yml?branch=main"> </a>
</p>
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</sub>
([mp-856](https://materialsproject.org/materials/mp-856/)), one
can simply run:
```bash
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](http://pymatgen.org), 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](https://hackingmaterials.github.io/robocrystallographer/cli.html).
### 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:
```python
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](https://hackingmaterials.github.io/robocrystallographer/modules).
### Intermediate JSON format
The format of the intermediate JSON representation is detailed on the
[condensed structure format page](https://hackingmaterials.github.io/robocrystallographer/format.html).
### Example output
An example of the output generated by robocrystallographer for SnO<sub>2</sub> ([mp-856](https://materialsproject.org/materials/mp-856/)) is given below:
<p align="center">
<img alt="SnO2 crystal structure" src="https://raw.githubusercontent.com/hackingmaterials/robocrystallographer/master/docs/src//_static/rutile.jpg" height=
"200px">
</p>
> 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:
```bash
pip install robocrys
```
Robocrystallographer requires Python 3.7+. 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:
```bash
conda install -c conda-forge openbabel
```
## What’s new?
Track changes to robocrystallographer through the
[Changelog](https://hackingmaterials.github.io/robocrystallographer/changelog.html).
## Contributing
Robocrystallographer is in early development but we still welcome your
contributions. Please read our [contribution guidelines](https://hackingmaterials.github.io/robocrystallographer/contributing.html)
for more information. We maintain a list of all
contributors [here](https://hackingmaterials.github.io/robocrystallographer/contributors.html).
## License
Robocrystallographer is released under a modified BSD license;
the full text can be found
[here](https://hackingmaterials.github.io/robocrystallographer/license.html).
## Acknowledgements
Logo by Somewan from the Noun Project.
Raw data
{
"_id": null,
"home_page": "https://github.com/hackingmaterials/robocrystallographer",
"name": "robocrys",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "crystal-structure crystallography materials-science",
"author": "Alex Ganose",
"author_email": "aganose@lbl.gov",
"download_url": "https://files.pythonhosted.org/packages/45/bd/171fa60f3cbe6bb3b61a88e5f2912ca16c06c78bf0a90feb3f55ae25a2d3/robocrys-0.2.9.tar.gz",
"platform": null,
"description": "<p align=\"center\">\n <img alt=\"robocrystallographer logo\" src=\"https://raw.githubusercontent.com/hackingmaterials/robocrystallographer/master/docs/src/_static/logo-01.png\" height=\"200px\">\n</p>\n\n<p align=\"center\">\n <a href=\"https://pypi.org/project/robocrys/\"><img alt=\"PyPI version\" src=\"https://img.shields.io/pypi/v/robocrys.svg?colorB=blue\"> </a>\n <a href=\"https://github.com/hackingmaterials/robocrystallographer/actions?query=workflow%3A%22Run+tests%22\"><img alt=\"CircleCI\" src=\"https://img.shields.io/github/actions/workflow/status/hackingmaterials/robocrystallographer/tests.yml?branch=main\"> </a>\n</p>\n\n\n\n\nRobocrystallographer is a tool to generate text descriptions of crystal\nstructures. Similar to how a real-life crystallographer would analyse a\nstructure, robocrystallographer looks at the symmetry, local environment, and\nextended connectivity when generating a description. The package includes\nutilities for identifying molecule names, component orientations,\nheterostructure information, and more...\n\n## Usage\n\nRobocrystallographer can be used from the command-line or from a python API.\nThe package integrates with the [Materials Project](https://materialsproject.org)\nto for allow generation of structure descriptions directly from Materials Project\nids. For example, to generate the description of SnO<sub>2</sub>\n([mp-856](https://materialsproject.org/materials/mp-856/)), one\ncan simply run:\n\n```bash\nrobocrys mp-856\n```\n\nAlternatively, a structure file can be specified in place of a Materials Project id.\nRobocrystallographer supports the same file formats as\n[pymatgen](http://pymatgen.org), including the Crystallographic Information\nFormat (CIF), and common electronic structure package formats such as POSCAR files.\nMore information can be found on the\n[command-line interface page](https://hackingmaterials.github.io/robocrystallographer/cli.html).\n\n### Python interface\n\nThe two core classes in robocrystallographer are:\n\n- `StructureCondenser`: to condense the structure into an descriptive JSON\n representation.\n- `StructureDescriber`: to turn the condensed structure into a text description.\n\nA minimal working example for generating text descriptions is simply:\n\n```python\nfrom pymatgen import Structure\nfrom robocrys import StructureCondenser, StructureDescriber\n\nstructure = Structure.from_file(\"my_structure.cif\") # other file formats also supported\n\n# alternatively, uncomment the lines below to use the MPRester object\n#\u00a0to fetch structures from the Materials Project database\n# from mp_api.client import MPRester\n# structure = MPRester(api_key=None).get_structure_by_material_id(\"mp-856\")\n\ncondenser = StructureCondenser()\ndescriber = StructureDescriber()\n\ncondensed_structure = condenser.condense_structure(structure)\ndescription = describer.describe(condensed_structure)\n```\n\nWhere `structure` is a pymatgen Structure object. Both classes have many\noptions for customising the output of the structure\ndescriptions. More information is provided in the\n[module documentation](https://hackingmaterials.github.io/robocrystallographer/modules).\n\n### Intermediate JSON format\n\nThe format of the intermediate JSON representation is detailed on the\n[condensed structure format page](https://hackingmaterials.github.io/robocrystallographer/format.html).\n\n\n### Example output\n\nAn example of the output generated by robocrystallographer for SnO<sub>2</sub> ([mp-856](https://materialsproject.org/materials/mp-856/)) is given below:\n\n<p align=\"center\">\n<img alt=\"SnO2 crystal structure\" src=\"https://raw.githubusercontent.com/hackingmaterials/robocrystallographer/master/docs/src//_static/rutile.jpg\" height=\n\"200px\">\n</p>\n\n> SnO2 is Rutile structured and crystallizes in the tetragonal P4_2/mnm space\n> group. The structure is three-dimensional. Sn(1) is bonded to six equivalent\n> O(1) atoms to form a mixture of edge and corner-sharing SnO6 octahedra. The\n> corner-sharing octahedral tilt angles are 51\u00b0. All Sn(1)\u2013O(1) bond lengths\n> are 2.09 \u00c5. O(1) is bonded in a trigonal planar geometry to three equivalent\n> Sn(1) atoms.\n\n## How to cite robocrystallographer\n\nPlease considering citing the following publication if using robocrystallographer in your work:\n\n> 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\n\n## Installation\n\nRobocrystallographer can be installed using pip:\n\n```bash\npip install robocrys\n```\n\nRobocrystallographer requires Python 3.7+. The\n[OpenBabel](http://openbabel.org/wiki/Python)\npackage is required to determine molecule names. This is an optional\nrequirement but its use is recommended for best\nresults. If you are using the [Conda](https://conda.io/) package management\nsystem, OpenBabel can be installed using:\n\n```bash\nconda install -c conda-forge openbabel\n```\n\n## What\u2019s new?\n\nTrack changes to robocrystallographer through the\n[Changelog](https://hackingmaterials.github.io/robocrystallographer/changelog.html).\n\n## Contributing\n\nRobocrystallographer is in early development but we still welcome your\ncontributions. Please read our [contribution guidelines](https://hackingmaterials.github.io/robocrystallographer/contributing.html)\nfor more information. We maintain a list of all\ncontributors [here](https://hackingmaterials.github.io/robocrystallographer/contributors.html).\n\n## License\n\nRobocrystallographer is released under a modified BSD license;\nthe full text can be found\n[here](https://hackingmaterials.github.io/robocrystallographer/license.html).\n\n## Acknowledgements\n\nLogo by Somewan from the Noun Project.\n\n\n",
"bugtrack_url": null,
"license": "modified BSD",
"summary": "Automatic generation of crystal structure descriptions",
"version": "0.2.9",
"project_urls": {
"Homepage": "https://github.com/hackingmaterials/robocrystallographer"
},
"split_keywords": [
"crystal-structure",
"crystallography",
"materials-science"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e14844f505fb07a91c4ba81a334dcb322d6ad69976e04821c015b63dc449ef48",
"md5": "debc7ebf386b3289e7bec91e8940d239",
"sha256": "6c40b5ae53184c9aa55f34688a023f5fd813ae447bdad004cfe9d377b6cb7df8"
},
"downloads": -1,
"filename": "robocrys-0.2.9-py3-none-any.whl",
"has_sig": false,
"md5_digest": "debc7ebf386b3289e7bec91e8940d239",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 3829561,
"upload_time": "2024-04-25T09:51:51",
"upload_time_iso_8601": "2024-04-25T09:51:51.790230Z",
"url": "https://files.pythonhosted.org/packages/e1/48/44f505fb07a91c4ba81a334dcb322d6ad69976e04821c015b63dc449ef48/robocrys-0.2.9-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "45bd171fa60f3cbe6bb3b61a88e5f2912ca16c06c78bf0a90feb3f55ae25a2d3",
"md5": "fdee59da355c2263f95018e2aa812116",
"sha256": "f41a27b0fc91064a3711e0faec5d310959e646e974ae79eb6f09ad146b8ccef2"
},
"downloads": -1,
"filename": "robocrys-0.2.9.tar.gz",
"has_sig": false,
"md5_digest": "fdee59da355c2263f95018e2aa812116",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 3823836,
"upload_time": "2024-04-25T09:51:54",
"upload_time_iso_8601": "2024-04-25T09:51:54.256700Z",
"url": "https://files.pythonhosted.org/packages/45/bd/171fa60f3cbe6bb3b61a88e5f2912ca16c06c78bf0a90feb3f55ae25a2d3/robocrys-0.2.9.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-25 09:51:54",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "hackingmaterials",
"github_project": "robocrystallographer",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"requirements": [
{
"name": "spglib",
"specs": [
[
"==",
"2.4.0"
]
]
},
{
"name": "numpy",
"specs": [
[
"==",
"1.26.4"
]
]
},
{
"name": "scipy",
"specs": [
[
"==",
"1.13.0"
]
]
},
{
"name": "pymatgen",
"specs": [
[
"==",
"2024.4.13"
]
]
},
{
"name": "inflect",
"specs": [
[
"==",
"7.2.1"
]
]
},
{
"name": "networkx",
"specs": [
[
"==",
"3.3"
]
]
},
{
"name": "matminer",
"specs": [
[
"==",
"0.9.2"
]
]
},
{
"name": "monty",
"specs": [
[
"==",
"2024.4.17"
]
]
},
{
"name": "pubchempy",
"specs": [
[
"==",
"1.0.4"
]
]
},
{
"name": "pybtex",
"specs": [
[
"==",
"0.24.0"
]
]
},
{
"name": "mp-api",
"specs": [
[
"==",
"0.41.2"
]
]
},
{
"name": "boto3",
"specs": []
}
],
"lcname": "robocrys"
}
JSON
