pyxtal

library1.1.4pypypi✓ verified 87d ago

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.

data

pip install pyxtal

github ↗package ↗

INSTALL

IMPORT

SIG · PYXTAL

pyxtal

datapythonv1.1.4

Install

30.8s avg

Import

3351ms

Disk

663MB

Pass rate

5/ 10

Env Coverage5 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.1.4 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.910 runs

build_error

glibc

py 3.10–3.910 runs

installs and imports cleanly · install 30.8s · import 3.351s · 629MB

663MB installed

● package 663MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

pyxtal

✓ from pyxtal import pyxtal

Group

✓ from pyxtal.symmetry import Group

pyxtal_molecule

✓ from pyxtal.molecule import pyxtal_molecule

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

Debug

Known issues

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

affects: All versions

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

affects: All versions

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

affects: All versions

Errors

Common errors & fixes

pyxtal.msg.Symm_CompatibilityError: Cannot find a valid combination of Wyckoff positions.

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.

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

Upgrade

Version history

1.1.4latest on PyPI · released May 26, 2026

Audit

Dependencies

numpyrequiredFundamental package for scientific computing.

scipyrequiredCore library for scientific and technical computing.

pandasrequiredData structures and data analysis tools.

pymatgenrequiredMaterials science library for structure objects, I/O (CIF, POSCAR), and symmetry analysis.

spglibrequiredSpace group symmetry library for crystal structures.

networkxrequiredGraph theory functions, used internally for some operations.

openbabeloptionalProvides support for additional molecular file formats. Requires C++ OpenBabel library and SWIG to be pre-installed.

Agent activity

8 hits · last 30 days

node

Resources

githubhttps://github.com/MaterSim/PyXtal ↗

packagehttps://pypi.org/project/pyxtal/ ↗