bsym - A basic symmetry module

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

API documentation is here.

Examples are provided in a Jupyter notebook here

Source code is available as a git repository at https://github.com/bjmorgan/bsym.

Tests

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.

bsym

bsym.configuration

class bsym.configuration.Configuration(vector)

Bases: object

A Configuration describes a specific arrangement of objects in the vector space of possible positions. Objects are represented by integers, with indistinguishable objects denoted by identical integers. This class subclasses numpy.matrix. Each configuration in the vector space of positions is represented as a column vector.

count

If symmetry-inequivalent configurations have been generated for a configuration space, this records the number of configurations equivalent to this one. Value at initialisation is None.

Type:int

lowest_numeric_representation

If the numeric representations for the set of equivalent configurations are calculated, this can be used to store the lowest valued numeric representation, for use as a simple hash.

Type:int

Example

>>> Configuration( [1, 1, 0] )
Configuration([1, 1, 0])

as_number

A numeric representation of this configuration.

Examples

>>> c = Configuration( [ 1, 2, 0 ] )
>>> c.as_number
120

classmethod from_tuple(this_tuple)

Construct a Configuration from a tuple, e.g.:

Configuration.from_tuple( ( 1, 1, 0 ) )

Parameters:this_tuple (tuple) – The tuple used to construct this Configuration. Returns:The new Configuration. Return type:(Configuration)

has_equivalent_in_list(the_list, symmetry_operations)

Test whether this configuration is equivalent by symmetry to one or more in a list of configurations.

Parameters:

• list (list(bsym.Configuration)) – A list of Configuration instances.
• symmetry_operations (list(bsym.SymmetryOperation)) – A list of SymmetryOperation objects.

Returns:

True | False

Return type:

(bool)

is_equivalent_to(test_configuration, symmetry_operations)

Test whether this configuration is equivalent to another configuration under one or more of a set of symmetry operations.

Parameters:

• test_configuration (Configuration) – The configuration to compare against.
• symmetry_operations (list(SymmetryOperation) – A list of SymmetryOperation objects.

Returns:

True | False

Return type:

(bool)

is_in_list(the_list)

Test whether this configuration is in a list of configurations.

Parameters:list (list(bsym.Comfiguration)) – A list of Configuration instances. Returns:True | False Return type:(bool)

map_objects(objects)

Returns a dict of objects sorted according to this configuration.

Parameters:[list] (objects) – A list of objects. Returns:A dictionary of sorted objects. Return type:sorted_objects [dict]

matches(test_configuration)

Test whether this configuration is equal to another configuration.

Parameters:test_configuration (Configuration) – The configuration to compare against. Returns:True | False. Return type:(bool)

numeric_equivalents(symmetry_operations)

Returns a list of all symmetry equivalent configurations generated by a set of symmetry operations with each configuration given in numeric representation.

Parameters:symmetry_operations (list) – A list of SymmetryOperation instances. Returns:A list of numbers representing each equivalent configuration. Return type:(list(int))

position(label)

Returns the vector indices where elements are equal to label.

Parameters:label (int) – The label used to select the vector positions. Returns:A list of all positions that match label. Return type:(list)

pprint()

set_lowest_numeric_representation(symmetry_operations)

Sets self.lowest_numeric_representation to the lowest value numeric representation of this configuration when permutated under a set of symmetry operations.

Parameters:symmetry_operations (list) – A list of SymmetryOperation instances. Returns:None

tolist()

Returns the configuration data as a list.

Parameters:None – Returns:(List)

bsym.configuration.as_number(a)

bsym.configuration_space

class bsym.configuration_space.ConfigurationSpace(objects, symmetry_group=None)

Bases: object

enumerate_configurations(generator, verbose=False)

Find all symmetry inequivalent configurations within the set produced by generator.

Parameters:

• generator (generator) – Generator object, that yields the configurations to search through.
• (opt (verbose) – default=False): Print verbose output.

Returns:

A list of Configuration objects, for each symmetry

inequivalent configuration.

Return type:

unique_configurations (list)

unique_colourings(colours, verbose=False)

Find the symmetry inequivalent colourings for a given number of ‘colours’.

Parameters:

• colours (list) – A list of each object that may be arranged zero or more times in this system.
• (opt (verbose) – default=False): Print verbose output.

Returns:

A list of Configuration objects, for each symmetry

inequivalent colouring.

Return type:

unique_colours (list)

unique_configurations(site_distribution, verbose=False, show_progress=False)

Find the symmetry inequivalent configurations for a given population of objects.

Parameters:

• site_distribution (dict) –

  A dictionary that defines the number of each object to be arranged in this system.

  e.g. for a system with four sites, with two occupied (denoted 1) and two unoccupied (denoted 0):

  { 1: 2, 0: 2 }
  

• (opt (show_progress) – default=False): Print verbose output.
• (opt – default=False): Show a progress bar. Setting to True gives a simple progress bar. Setting to “notebook” gives a Jupyter notebook compatible progress bar.

Returns:

A list of Configuration objects, for each symmetry

inequivalent configuration.

Return type:

unique_configurations (list)

bsym.configuration_space.colourings_generator(colours, dim)

bsym.configuration_space.permutation_as_config_number(p)

A numeric representation of a numeric list.

Example

>>> permutation_as_config_number( [ 1, 1, 0, 0, 1 ] )
11001

bsym.coordinate_config_space

class bsym.coordinate_config_space.CoordinateConfigSpace(coordinates, symmetry_group=None, objects=None)

Bases: bsym.configuration_space.ConfigurationSpace

A CoordinateConfigSpace object is a :any`ConfigurationSpace` that has an associated set of coordinates. Each vector in the configuration vector space has a corresponding coordinate.

unique_coordinates(site_distribution, verbose=False)

Find the symmetry inequivalent coordinates for a given site occupation.

Parameters:

• site_distribution (dict) –

  A dictionary that defines the number of each object to be arranged in this system.

  e.g. for a structure with four sites, with two occupied (denoted 1) and two unoccupied (denoted 0):

  { 1: 2, 0: 2 }
  

• (opt (verbose) – default=False): Print verbose output.

Returns:

A list of dicts. Each dict describes the set of coordinates for each site type.

Return type:

unique_coordinates (list[dict])

bsym.permutations

bsym.permutations.flatten_list(this_list)

bsym.permutations.number_of_unique_permutations(seq)

Calculate the number of unique permutations of a sequence seq.

Parameters:seq (list) – list of items. Returns:The number of unique permutations of seq Return type:int

bsym.permutations.unique_permutations(seq)

Yield only unique permutations of seq in an efficient way.

A python implementation of Knuth’s “Algorithm L”, also known from the std::next_permutation function of C++, and as the permutation algorithm of Narayana Pandita.

see http://stackoverflow.com/questions/12836385/how-can-i-interleave-or-create-unique-permutations-of-two-stings-without-recurs/12837695

bsym.point_group

class bsym.point_group.PointGroup(symmetry_operations=[])

Bases: bsym.symmetry_group.SymmetryGroup

class_str = 'PointGroup'

bsym.space_group

class bsym.space_group.SpaceGroup(symmetry_operations=[])

Bases: bsym.symmetry_group.SymmetryGroup

class_str = 'SymmetryGroup'

bsym.symmetry_group

class bsym.symmetry_group.SymmetryGroup(symmetry_operations=[])

Bases: object

SymmetryGroup class.

A SymmetryGroup object contains a set of SymmetryOperation objects.

e.g.:

SymmetryGroup( symmetry_operations=[ s1, s2, s3 ] )

where s1, s2, and s3 are SymmetryOperation objects.

SymmetryGroup objects can also be created from files using the class methods:

SymmetryGroup.read_from_file( filename )

and:

SymmetryGroup.read_from_file_with_labels( filename )

append(symmetry_operation)

Append a SymmetryOperation to this SymmetryGroup.

Parameters:symmetry_operation (SymmetryOperation) – The SymmetryOperation to add. Returns:self (SymmetryGroup)

by_label(label)

Returns the SymmetryOperation with a matching label.

Parameters:label (str) – The label identifying the chosen symmetry operation. Returns:The symmetry operation that matches this label. Return type:(SymmetryOperation)

class_str = 'SymmetryGroup'

extend(symmetry_operations_list)

Extend the list of symmetry operations in this SymmetryGroup.

Parameters:symmetry_operations_list (list) – A list of SymmetryOperation objects. Returns:self (SymmetryGroup)

labels

A list of labels for each SymmetryOperation in this spacegroup.

Parameters:None – Returns:A list of label strings. Return type:(list)

classmethod read_from_file(filename)

Create a SymmetryGroup object from a file.

The file format should be a series of numerical mappings representing each symmetry operation.

e.g. for a pair of equivalent sites:

# example input file to define the spacegroup for a pair of equivalent sites
1 2
2 1

Parameters:filename (str) – Name of the file to be read in. Returns:spacegroup (SymmetryGroup)

classmethod read_from_file_with_labels(filename)

Create a SymmetryGroup object from a file, with labelled symmetry operations.

The file format should be a series of numerical mappings representing each symmetry operation, prepended with a string that will be used as a label.

e.g. for a pair of equivalent sites:

# example input file to define the spacegroup for a pair of equivalent sites
E  1 2
C2 2 1

Parameters:filename (str) – Name of the file to be read in. Returns:spacegroup (SymmetryGroup)

save_symmetry_operation_vectors_to(filename)

Save the set of vectors describing each symmetry operation in this SymmetryGroup to a file.

Parameters:filename (str) – Name of the file to save to. Returns:None

size

bsym.symmetry_operation

class bsym.symmetry_operation.SymmetryOperation(matrix, label=None)

Bases: object

SymmetryOperation class.

as_vector(count_from_zero=False)

Return a vector representation of this symmetry operation

Parameters:count_from_zero (default = False) (bool) – set to True if the vector representation counts from zero Returns:a vector representation of this symmetry operation (as a list)

character()

Return the character of this symmetry operation (the trace of self.matrix).

Parameters:none – Returns:np.trace( self.matrix )

classmethod from_vector(vector, count_from_zero=False, label=None)

Initialise a SymmetryOperation object from a vector of site mappings.

Parameters:

• vector (list) – vector of integers defining a symmetry operation mapping.
• count_from_zero (default = False) (bool) – set to True if the site index counts from zero.
• label (default=None) (str) – optional string label for this SymmetryOperation object.

Returns:

a new SymmetryOperation object

invert(label=None)

Invert this SymmetryOperation object.

Parameters:None – Returns:A new SymmetryOperation object corresponding to the inverse matrix operation.

operate_on(configuration)

Return the Configuration generated by appliying this symmetry operation

Parameters:configuration (Configuration) – the configuration / occupation vector to operate on Returns:the new configuration obtained by operating on configuration with this symmetry operation. Return type:(Configuration)

pprint()

Pretty print for this symmetry operation

Parameters:None – Returns:None

set_label(label)

Set the label for this symmetry operation.

Parameters:label – label to set for this symmetry operation Returns:self

similarity_transform(s, label=None)

Generate the SymmetryOperation produced by a similarity transform S^{-1}.M.S

Parameters:

• s – the symmetry operation or matrix S.
• label (str, optional) – the label to assign to the new SymmetryOperation. Defaults to None.

Returns:

the SymmetryOperation produced by the similarity transform

bsym.symmetry_operation.is_permutation_matrix(m)

Test whether a numpy array is a `permutation matrix`_.

Parameters:m (mp.matrix) – The matrix. Returns:True | False. Return type:(bool)

bsym.symmetry_operation.is_square(m)

Test whether a numpy matrix is square.

Parameters:m (np.matrix) – The matrix. Returns:True | False. Return type:(bool)

interface

bsym.interface.pymatgen

bsym.interface.pymatgen.configuration_space_from_molecule(molecule, subset=None, atol=1e-05)

Generate a ConfigurationSpace object from a pymatgen Molecule.

Parameters:

• molecule (pymatgen Molecule) – molecule to be used to define the ConfigurationSpace.
• subset (Optional [list]) – list of atom indices to be used for generating the configuration space.
• atol (Optional [float]) – tolerance factor for the pymatgen `coordinate mapping`_ under each symmetry operation.

Returns:

a new ConfigurationSpace instance.

bsym.interface.pymatgen.configuration_space_from_structure(structure, subset=None, atol=1e-05)

Generate a ConfigurationSpace object from a pymatgen Structure.

Parameters:

• structure (pymatgen Structure) – structure to be used to define the ConfigurationSpace.
• subset (Optional [list]) – list of atom indices to be used for generating the configuration space.
• atol (Optional [float]) – tolerance factor for the pymatgen `coordinate mapping`_ under each symmetry operation.

Returns:

a new ConfigurationSpace instance.

bsym.interface.pymatgen.molecule_cartesian_coordinates_mapping(molecule, symmop)

Maps the coordinates of pymatgen Molecule according to a SymmOp symmetry operation.

Parameters:

• molecule (Structure) – The pymatgen Molecule.
• symmop (SymmOp) – The pymatgen symmetry operation object.

Returns

(np.array): The mapped Cartesian coordinates.

bsym.interface.pymatgen.molecule_mapping_list(new_molecule, mapping_molecule, atol)

Gives the index mapping between two pymatgen Molecule objects.

Parameters:

• new_structure (Molecule) –
• mapping_structure (Molecule) –

Returns:

list of indices such that mapping_molecule.sites[indices] == new_molecule.sites

bsym.interface.pymatgen.new_structure_from_substitution(parent_structure, site_substitution_index, new_species_list)

Generate a new pymatgen Structure from site substitution parameters.

Parameters:

• parent_structure (Structure) – The parent pymatgen Struture object.
• site_substitution_index (list[int]) – The list of site indices to be substituted.
• new_species_list (list[str]) – A list of the replacement atomic species.

Returns:

The new pymatgen Structure.

Return type:

(Structure)

Notes

pymatgen Structure and Molecule classes both subclass SiteCollection. This function will also accept a parent Molecule object, and return a new Molecule.

bsym.interface.pymatgen.parse_site_distribution(site_distribution)

Converts a site distribution using species labels into one using integer labels.

Parameters:site_distribution (dict) – e.g. { ‘Mg’: 1, ‘Li’: 3 } Returns:e.g. { 1:1, 0:3 } numeric_site_mapping (dict): e.g. { 0:’Mg’, 1:’Li’ } Return type:numeric_site_distribution ( dict)

bsym.interface.pymatgen.point_group_from_molecule(molecule, subset=None, atol=1e-05)

Generates a PointGroup object from a pymatgen Molecule.

Parameters:

• molecule (pymatgen Molecule) – molecule to be used to define the PointGroup.
• subset (Optional [list]) – list of atom indices to be used for generating the symmetry operations.
• atol (Optional [float]) – tolerance factor for the pymatgen `coordinate mapping`_ under each symmetry operation.

Returns:

a new PointGroup instance

bsym.interface.pymatgen.space_group_from_structure(structure, subset=None, atol=1e-05)

Generates a SpaceGroup object from a pymatgen Structure.

Parameters:

• structure (pymatgen Structure) – structure to be used to define the SpaceGroup.
• subset (Optional [list]) – list of atom indices to be used for generating the symmetry operations.
• atol (Optional [float]) – tolerance factor for the pymatgen `coordinate mapping`_ under each symmetry operation.

Returns:

a new SpaceGroup instance

bsym.interface.pymatgen.space_group_symbol_from_structure(structure)

Returns the symbol for the space group defined by this structure.

Parameters:structure (pymatgen Structure) – The input structure. Returns:The space group symbol. Return type:(str)

bsym.interface.pymatgen.structure_cartesian_coordinates_mapping(structure, symmop)

Maps the coordinates of pymatgen Structure according to a SymmOp symmetry operation.

Parameters:

• structure (Structure) – The pymatgen Structure.
• symmop (SymmOp) – The pymatgen symmetry operation object.

Returns

(np.array): The mapped Cartesian coordinates.

bsym.interface.pymatgen.structure_mapping_list(new_structure, mapping_structure, atol)

Gives the index mapping between two pymatgen Structure objects.

Parameters:

• new_structure (Structure) –
• mapping_structure (Structure) –

Returns:

list of indices such that mapping_structure.sites[indices] == new_structure.sites

bsym.interface.pymatgen.unique_structure_substitutions(structure, to_substitute, site_distribution, verbose=False, atol=1e-05, show_progress=False)

Generate all symmetry-unique structures formed by substituting a set of sites in a pymatgen structure.

Parameters:

• structure (pymatgen.Structure) – The parent structure.
• to_substitute (str) – atom label for the sites to be substituted.
• site_distribution (dict) – A dictionary that defines the number of each substituting element.
• verbose (bool) – verbose output.
• atol (Optional [float]) – tolerance factor for the pymatgen `coordinate mapping`_ under each symmetry operation. Default=1e-5.
• (opt (show_progress) – default=False): Show a progress bar. Setting to True gives a simple progress bar. Setting to “notebook” gives a Jupyter notebook compatible progress bar.

Returns:

A list of Structure objects for each unique substitution.

Return type:

(list[Structure])

Notes

The number of symmetry-equivalent configurations for each structure is stored in the number_of_equivalent_configurations attribute.

If the parent structure was previously generated using this function (as part of a sequence of substitutions) the full configuration degeneracy of each symmetry inequivalent configuration is stored in the full_configuration_degeneracy attribute. If the parent structure is a standard Pymatgen Structure object, number_of_equivalent_configurations and full_configuration_degeneracy will be equal.

bsym.interface.pymatgen.unique_symmetry_operations_as_vectors_from_structure(structure, verbose=False, subset=None, atol=1e-05)

Uses pymatgen symmetry analysis to find the minimum complete set of symmetry operations for the space group of a structure.

Parameters:

• structure (pymatgen Structure) – structure to be analysed.
• subset (Optional [list]) – list of atom indices to be used for generating the symmetry operations.
• atol (Optional [float]) – tolerance factor for the pymatgen `coordinate mapping`_ under each symmetry operation.

Returns:

a list of lists, containing the symmetry operations as vector mappings.

Return type:

(list[list])

Indices and tables

• Index
• Module Index
• Search Page