bsym: A basic symmetry module

A large number of problems in materials science concern the configurational disorder of atoms. Examples include describing mixing of alloys (Ganose and Scanlon 2016); identifying prefferred arrangements in crystals of non-dilute point defects, dopants, or intercalated atoms (Morgan and Watson 2011, Grieshammer et al. (2014), DaltonEtAl_ChemMater2012); or predicting crystal surface structures or the arrangements of adsorbed atoms (Morgan, Carrasco, and Teobaldi 2016).

Computational modelling can provide useful insight into problems such as these. For a given atomic geometry, relative energies, or other such properties, can be directly calculated. Repeating these calculations across a range of possible structures can be used to identify which atom arrangements are more or less likely, or be used to construct a statistical description giving an ensemble average. For bulk materials with approximately random disorder (ideal mixing) special quasi-random structures can be used to model the effects of disorder in a single periodic system (Zunger et al. 1990). Where disorder is not random, however, contributions from different atomic configurations need to be explicitly considered. One approach is to model the system energy via an effective Hamiltonian (for example, parameterised using cluster expansion methods), and then to perform Monte Carlo simulations (Lerch et al. 2009, Walle and Ceder (2002), (“CASM, V0.2.1” 2017), Ludwig et al. (2011)). This approach depends on the accuracy of the effective Hamiltonian, and is particularly suited to systems where short-range interactions dominate the total energy. An alternative is to explicitly consider all possible configurations of relevant atoms within a reduced configurational space (e.g. a computationally tractable supercell) (Grau-Crespo et al. 2007, Tompsett and Islam (2013)).

In this approach, the overall computational cost can be greatly reduced by considering only symmetry inequivalent configurations. If, for each of these unique structures, the number of symmetry-equivalent configurations is known, then in addition to individual enthalpies, configurational entropies, and hence free energies, may be calculated (Grau-Crespo et al. 2007).


bsym (Morgan 2016) is a Python module for performing symmetry-based manipulations on arbitrary configuration vector spaces. The code includes an efficient implementation of the algorithm described by Grau-Crespo et al., for enumerating symmetry inequivalent configurations (Grau-Crespo et al. 2007). For treating the specific case of site-disorder in crystals, bsym includes an interface for working with pymatgen Structure objects [OngEtAl_CompMaterSci2013], which allows simple construction of sets of symmetry operations for crystal structures, and conversion to and from a range of standard file formats for recording crystal structures and for inputs for a range of atomistic modelling codes. The core classes describe objects corresponding to an abstracted matrix representation of configurational vector spaces and their symmetry properties. This means bsym can be readily used for analysis in other classes of problems, including molecular point groups, crystal surface symmetries (2D space groups), and graph theoretical colouring problems.


BJM acknowledges support from the EU FP7 program SIRBATT (contract No. 608502), from the Royal Society (UF130329), and from EPSRC grant EP/N004302/ 1.


“CASM, V0.2.1.” 2017. Available from doi:10.5281/zenodo.546148.

Ganose, Alex M., and David O. Scanlon. 2016. “Band Gap and Work Function Tailoring of SnO2 for Improved Transparent Conducting Ability in Photovoltaics.” J. Mater. Chem. A 4 (February): 1467–75.

Grau-Crespo, R., S. Hamad, C. Richard A. Catlow, and N. H. de Leeuw. 2007. “Symmetry-adapted configurational modelling of fractional site occupancy in solids.” J. Phys.-Condens. Mat. 19 (25): 256201.

Grieshammer, Steffen, Benjamin O. H. Grope, Julius Koettgen, and Manfred Martin. 2014. “A Combined DFT+U and Monte Carlo Study on Rare Earth Doped Ceria.” Phys. Chem. Chem. Phys. 16 (21): 9974–13.

Lerch, D., O. Wieckhorst, G. L. W. Hart, R. W. Forcade, and S. Müller. 2009. “UNCLE: A Code for Constructing Cluster Expansions for Arbitrary Lattices with Minimal User-Input.” Modelling Simul. Mater. Sci. Eng. 17 (5): 055003–20.

Ludwig, Christian D. R., Thomas Gruhn, Claudia Felser, and Johannes Windeln. 2011. “Defect Structures in CuInSe2: A Combination of Monte Carlo Simulations and Density Functional Theory.” Phys. Rev. B 83 (17): 622–8.

Morgan, Benjamin J. 2016. “bsym - a Basic Symmetry Module.”

Morgan, Benjamin J., and Graeme W. Watson. 2011. “The Role of Lithium Ordering in the LixTiO2 Anatase Titanate Phase Transition.” J. Phys. Chem. Lett. 2 (June): 1657—1611.

Morgan, Benjamin J., Javier Carrasco, and Gilberto Teobaldi. 2016. “Variation in Surface Energy and Reduction Drive of a Metal Oxide Lithium-Ion Anode with Stoichiometry: A DFT Study of Lithium Titanate Spinel Surfaces.” J. Mater. Chem. A 4 (43): 17180–92.

Tompsett, David A., and M. Saiful Islam. 2013. “Electrochemistry of Hollandite α-MnO2: Li-Ion and Na-Ion Insertion and Li2O Incorporation.” Chem. Mater. 25 (12): 2515–26.

Walle, A. van de, and Gerbrand Ceder. 2002. “Automating First-Principles Phase Diagram Calculations.” J. Phase Equil. 23 (4): 348–59.

Zunger, A., S.H. Wei, L. G. Ferreria, and J. E. Bernard. 1990. “Special Quasirandom Structures.” Phys. Rev. Lett. 65 (3): 353–56.