bsym is a basic Python symmetry module. It consists of core classes that describe configuration vector spaces, their symmetry operations, and specific configurations of objects within these spaces. The module also contains an interface for working with pymatgen Structure objects, to allow simple generation of disordered symmetry-inequivalent structures from a symmetric parent crystal structure.

Usage examples are provided in the documentation. API documentation is here. Source code is available at https://github.com/bjmorgan/bsym.

bsym requires Python 3.10 or later.

Install from PyPI:

pip install bsym

Download the latest release from GitHub, and install:

cd bsym
pip install .

Or clone the latest development version:

git clone git@github.com:bjmorgan/bsym.git
cd bsym
pip install .

To install with development dependencies (for running tests, type checking, building docs, etc.):

git clone git@github.com:bjmorgan/bsym.git
cd bsym
pip install -e ".[dev]"

This installs bsym in editable mode with additional tools for development.

Tests use pytest. After installing with development dependencies, run:

pytest

For verbose output:

pytest -v

To run specific test files:

pytest tests/unit_tests/test_symmetry_group.py

bsym can enumerate symmetry-inequivalent structures for disordered materials. Here's an example using a pymatgen Structure as input:

from bsym.interface.pymatgen import unique_structure_substitutions
unique_structures = unique_structure_substitutions(
    parent_structure, 
    'X',  # Sites to substitute
    {'O': 8, 'F': 16}  # 8 oxygen, 16 fluorine
)
print(f"Found {len(unique_structures)} unique structures")

An overview of the capabilities of bsym along with example code is provided in the documentation.

This code can be cited as:

Morgan, Benjamin J. (2017). bsym - a Basic Symmetry Module. The Journal of Open Source Software. http://doi.org/10.21105/joss.00370

@article{Morgan_JOSS2017b,
  doi = {10.21105/joss.00370},
  url = {https://doi.org/10.21105/joss.00370},
  year  = {2017},
  month = {aug},
  publisher = {The Open Journal},
  volume = {2},
  number = {16},
  author = {Benjamin J. Morgan},
  title = {bsym: A basic symmetry module},
  journal = {The Journal of Open Source Software}
}