Skip to main content

A Basic Symmetry Module

Project description

PyPI version DOI status Build Status Test Coverage Documentation Status

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.

Examples are provided in a Jupyter notebook here.
API documentation is here.
Source code is available as a git repository at


pip install bsym

Or download the latest release from GitHub, and install

cd bsym
python install

Or clone the latest development version

git clone

and install the same way.

cd bsym
python install 


Automated testing of the latest commit happens here.

Manual tests can be run using

python -m unittest discover

The code has been tested with Python versions 3.5 and above.


An overview of the capabilities of bsym along with example code is contained in a Jupyter notebook in the repository examples directory examples/bsym_examples.ipynb.

API documentation is available here.

I want to generate a set of symmetry-inequivalent crystal structures

bsym can enumerate symmetry-inequivalent crystal structures generated by partial substitutions, starting from a parent structure described by a pymatgen Structure object.
Example code is in the example notebook.
Also refer to the bsym.interface.pymatgen.unique_structure_substitutions documentation.

Citing bsym

This code can be cited as:

Morgan, Benjamin J. (2017). bsym - a Basic Symmetry Module. The Journal of Open Source Software.


  doi = {10.21105/joss.00370},
  url = {},
  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}

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for bsym, version 1.1.1
Filename, size File type Python version Upload date Hashes
Filename, size bsym-1.1.1-py3-none-any.whl (18.6 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size bsym-1.1.1.tar.gz (15.3 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page