{"id":9268,"library":"pyxtal","title":"PyXtal: Crystal Structure Generation","description":"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.","status":"active","version":"1.1.3","language":"en","source_language":"en","source_url":"https://github.com/MaterSim/PyXtal","tags":["material-science","crystallography","simulation","chemistry","structure-generation"],"install":[{"cmd":"pip install pyxtal","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Fundamental package for scientific computing.","package":"numpy","optional":false},{"reason":"Core library for scientific and technical computing.","package":"scipy","optional":false},{"reason":"Data structures and data analysis tools.","package":"pandas","optional":false},{"reason":"Materials science library for structure objects, I/O (CIF, POSCAR), and symmetry analysis.","package":"pymatgen","optional":false},{"reason":"Space group symmetry library for crystal structures.","package":"spglib","optional":false},{"reason":"Graph theory functions, used internally for some operations.","package":"networkx","optional":false},{"reason":"Provides support for additional molecular file formats. Requires C++ OpenBabel library and SWIG to be pre-installed.","package":"openbabel","optional":true}],"imports":[{"symbol":"pyxtal","correct":"from pyxtal import pyxtal"},{"symbol":"Group","correct":"from pyxtal.symmetry import Group"},{"symbol":"pyxtal_molecule","correct":"from pyxtal.molecule import pyxtal_molecule"}],"quickstart":{"code":"from pyxtal import pyxtal\n\n# Create a new structure instance\nstruc = pyxtal()\n\n# Generate a random 3D atomic crystal\n# dim=3 (3D), group=227 (Fd-3m, diamond space group), species=['C'], numIons=[8] (8 Carbon atoms per conventional cell)\nstruc.from_random(dim=3, group=227, species=['C'], numIons=[8])\n\nif struc.valid:\n    print(\"Crystal generated successfully:\")\n    print(struc)\n    # To save the structure to a CIF file\n    struc.to_file(\"diamond.cif\")\nelse:\n    print(\"Failed to generate crystal.\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","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.","error":"pyxtal.msg.Symm_CompatibilityError: Cannot find a valid combination of Wyckoff positions."},{"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`.","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.","error":"ImportError: No module named 'openbabel.openbabel' when attempting to load or save molecular structures."}]}