PyXtal: Crystal Structure Generation

1.1.3 · active · verified Thu Apr 16

PyXtal is an open-source Python library designed for the ab-initio generation of crystal structures based on symmetry constraints. It supports the generation of atomic and molecular systems across 0D to 3D dimensions, facilitates symmetry analysis, and offers structural manipulation capabilities. The library is currently at version 1.1.3 and is actively maintained with regular updates and contributions from the materials science community.

Common errors

```
pyxtal.msg.Symm_CompatibilityError: Cannot find a valid combination of Wyckoff positions.
```
cause The input stoichiometry (number of atoms/molecules) is fundamentally incompatible with the Wyckoff positions available for the specified space group and dimension, or the chosen volume factor leads to unavoidable atomic overlaps, preventing the generation of a valid crystal.

fix Revise your input parameters: try a different space group, adjust the `numIons` or `numMols` list, or increase the `factor` parameter to provide more volume for atom placement. If generating molecular crystals, ensure molecular symmetry is compatible with Wyckoff site symmetry.
```
ImportError: No module named 'openbabel.openbabel' when attempting to load or save molecular structures.
```
cause The Python bindings for OpenBabel (`openbabel-python`) are not correctly installed or accessible. This typically happens because the required C++ OpenBabel library or SWIG dependency was missing during the `openbabel` pip installation.

fix Ensure the C++ `openbabel` library and `swig` (a tool for generating Python bindings) are installed on your system. For example, on Debian/Ubuntu, run `sudo apt-get install openbabel swig`. After these are installed, reinstall the Python `openbabel` package: `pip install openbabel`.

Warnings

gotcha Structure generation failures can occur due to incompatible input parameters (e.g., stoichiometry and space group, or unphysical atomic distances from volume factors). The library's randomized generation within symmetry constraints means some attempts might fail.
Fix: Carefully review the chosen `dim`, `group`, `species`/`molecules`, `numIons`/`numMols`, and `factor` parameters. Increase the `factor` (volume expansion) or `max_attempts` for more challenging structures. Consider using pre-defined `sites` for more control over Wyckoff positions.
gotcha Installing PyXtal with `openbabel` support (for extended molecular file format handling) is complex. The Python bindings for OpenBabel (`openbabel-python`) require the underlying C++ OpenBabel library and the `swig` tool to be installed on your system *before* installing the Python package.
Fix: First, install the C++ OpenBabel library and SWIG (version >= 2.0) via your system's package manager (e.g., `sudo apt-get install openbabel swig` on Debian/Ubuntu). Then, install the Python bindings: `pip install openbabel`.
gotcha By default, PyXtal avoids generating molecular crystals that include mirror copies of chiral molecules. This is a deliberate choice for many chemical and pharmaceutical applications but might not be desired for all use cases.
Fix: If you require crystals containing mirror images of chiral molecules, you will need to explicitly configure PyXtal to allow inversion. Consult the molecular crystal generation documentation for specific parameters.

Install

pip install pyxtal Install stable version

Imports

pyxtal
```
from pyxtal import pyxtal
```
Group
```
from pyxtal.symmetry import Group
```

pyxtal_molecule

from pyxtal.molecule import pyxtal_molecule

Quickstart

This quickstart demonstrates how to generate a 3D atomic crystal, specifically a diamond-like carbon structure, using the `pyxtal` class's `from_random` method. It initializes a crystal instance, attempts to generate a structure based on dimension, space group, element, and stoichiometry, and then prints the structure details or saves it to a CIF file if successful.

from pyxtal import pyxtal

# Create a new structure instance
struc = pyxtal()

# Generate a random 3D atomic crystal
# dim=3 (3D), group=227 (Fd-3m, diamond space group), species=['C'], numIons=[8] (8 Carbon atoms per conventional cell)
struc.from_random(dim=3, group=227, species=['C'], numIons=[8])

if struc.valid:
    print("Crystal generated successfully:")
    print(struc)
    # To save the structure to a CIF file
    struc.to_file("diamond.cif")
else:
    print("Failed to generate crystal.")

view raw JSON →