RoboCryS

0.2.13 · active · verified Thu Apr 16

RoboCryS (robocrys) is a Python library for the automatic generation of human-readable descriptions of crystal structures. It is currently at version 0.2.13 and sees active development with minor releases every few months, often including dependency updates and compatibility fixes.

Common errors

```
robocrys.descriptor.CrystalDescriptorError: Could not convert structure to primitive cell with spglib. This often indicates an issue with spglib installation or a highly distorted structure.
```
cause Issues with `spglib` installation (a core dependency via `pymatgen`) or a highly distorted, amorphous, or chemically ambiguous structure that `spglib` cannot process.

fix Verify your `spglib` installation by running `python -c "import spglib"`. If the structure is highly distorted or chemically non-stoichiometric, `robocrys` might not be suitable; try cleaning or relaxing the structure first.
```
AttributeError: 'Structure' object has no attribute 'ntypesp'
```
cause You are likely using an older version of `robocrys` (before 0.2.10) with a newer `pymatgen` version. `pymatgen` deprecated `ntypesp` in favor of `n_elems`.

fix Upgrade `robocrys` to version 0.2.10 or newer: `pip install --upgrade robocrys`.
```
ValueError: Could not determine oxidation states for all species.
```
cause RoboCryS attempted to infer oxidation states but failed due to insufficient information, complex chemistry, or the presence of species for which default oxidation states are ambiguous.

fix Provide explicit oxidation states to the `CrystalDescriptor` constructor or the `describe` method. For example: `descriptor = CrystalDescriptor(oxidation_states={'ElementA': X, 'ElementB': Y})`.

Warnings

breaking RoboCryS is highly dependent on `pymatgen`, and breaking changes in `pymatgen` can cause compatibility issues. Older `robocrys` versions may fail with newer `pymatgen` versions, and vice-versa.
Fix: Always check the `install_requires` in `robocrys`'s `pyproject.toml` or `setup.py` for compatible `pymatgen` version ranges. Upgrade both `robocrys` and `pymatgen` together (`pip install --upgrade robocrys pymatgen`) to ensure compatibility.
gotcha For complex compounds, especially those with transition metals or mixed valences, RoboCryS may struggle to infer accurate oxidation states automatically. This can lead to less precise or incorrect descriptions.
Fix: Provide explicit oxidation states to the `CrystalDescriptor` constructor or the `describe` method. For example: `descriptor = CrystalDescriptor(oxidation_states={'Fe': 2, 'O': -2})`.
deprecated Older versions of `robocrys` (prior to 0.2.10) used the `ntypesp` attribute from `pymatgen.Structure`, which has since been deprecated and replaced with `n_elems` in `pymatgen`.
Fix: Upgrade `robocrys` to version 0.2.10 or newer (`pip install --upgrade robocrys`) to ensure compatibility with recent `pymatgen` versions that use `n_elems`.

Install

pip install robocrys Install latest version

Imports

CrystalDescriptor

from robocrys.descriptor import CrystalDescriptor

Structure
```
from pymatgen.core import Structure
```

Quickstart

This example demonstrates how to create a `pymatgen.core.Structure` object and use `robocrys.descriptor.CrystalDescriptor` to generate a textual description of the crystal structure.

from pymatgen.core import Structure
from robocrys.descriptor import CrystalDescriptor

# Example structure (SrTiO3 perovskite, from space group and lattice parameters)
structure = Structure.from_spacegroup(221, 5.5, ['Sr', 'Ti', 'O'], [[0,0,0], [0.5,0.5,0.5], [0.5,0,0]])

descriptor = CrystalDescriptor()
description = descriptor.describe(structure)
print(description)

view raw JSON →