bsym.interface.pymatgen

bsym.interface.pymatgen.configuration_space_from_molecule(molecule: Molecule, subset: list[int] | None = None, atol: float = 1e-05) → ConfigurationSpace[source]

Generate a ConfigurationSpace object from a pymatgen Molecule.

Parameters:

  • molecule – Molecule to be used to define the ConfigurationSpace.

  • subset – List of atom indices to be used for generating the configuration space.

  • atol – Tolerance factor for the pymatgen `coordinate mapping`_ under each symmetry operation.

Returns:

A new ConfigurationSpace instance.

bsym.interface.pymatgen.configuration_space_from_structure(structure: Structure, subset: list[int] | None = None, atol: float = 1e-05) → ConfigurationSpace[source]

Generate a ConfigurationSpace object from a pymatgen Structure.

Parameters:

  • structure – Structure to be used to define the ConfigurationSpace.

  • subset – List of atom indices to be used for generating the configuration space.

  • atol – Tolerance factor for the pymatgen `coordinate mapping`_ under each symmetry operation.

Returns:

A new ConfigurationSpace instance.

bsym.interface.pymatgen.molecule_cartesian_coordinates_mapping(molecule: Molecule, symmop: SymmOp) → ndarray[source]

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

Parameters:

  • molecule – The pymatgen Molecule.

  • symmop – The pymatgen symmetry operation object.

Returns:

The mapped Cartesian coordinates.

bsym.interface.pymatgen.molecule_mapping_list(new_molecule: Molecule, mapping_molecule: Molecule, atol: float) → list[int][source]

Gives the index mapping between two pymatgen Molecule objects.

Parameters:

  • new_molecule – The new molecule.

  • mapping_molecule – The molecule to map to.

  • atol – Absolute tolerance for coordinate matching.

Returns:

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

bsym.interface.pymatgen.new_structure_from_substitution(parent_structure: Structure | Molecule, site_substitution_index: list[int], new_species_list: list[str]) → Any[source]

Generate a new pymatgen Structure from site substitution parameters.

Parameters:

  • parent_structure – The parent pymatgen Structure or Molecule object.

  • site_substitution_index – The list of site indices to be substituted.

  • new_species_list – A list of the replacement atomic species.

Returns:

The new pymatgen Structure or Molecule.

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: dict[str, int]) → tuple[dict[int, int], dict[int, str]][source]

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

Parameters:

site_distribution – e.g. {‘Mg’: 1, ‘Li’: 3}

Returns:

Tuple of (numeric_site_distribution, numeric_site_mapping) e.g. ({0: 3, 1: 1}, {0: ‘Li’, 1: ‘Mg’})

bsym.interface.pymatgen.point_group_from_molecule(molecule: Molecule, subset: list[int] | None = None, atol: float = 1e-05) → PointGroup[source]

Generates a PointGroup object from a pymatgen Molecule.

Parameters:

  • molecule – Molecule to be used to define the PointGroup.

  • subset – List of atom indices to be used for generating the symmetry operations.

  • atol – Tolerance factor for the pymatgen `coordinate mapping`_ under each symmetry operation.

Returns:

A new PointGroup instance

bsym.interface.pymatgen.random_unique_structure_substitutions(structure, to_substitute, site_distribution, n, sampling='degeneracy_weighted', seed=None, atol=1e-05, exclude_file=None, output_file=None)[source]

Generate n random symmetry-unique structures by substituting 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) – Dictionary mapping species to counts, e.g. {‘O’: 8, ‘F’: 8}.

  • n (int) – Number of unique structures to generate.

  • sampling (str) – Sampling method. Either ‘degeneracy_weighted’ (default) or ‘uniform’. ‘degeneracy_weighted’ samples configurations with probability proportional to their degeneracy. ‘uniform’ samples uniformly over equivalence classes.

  • seed (int, optional) – Random seed for reproducibility.

  • atol (float) – Tolerance factor for coordinate mapping. Default=1e-5.

  • exclude_file (str or list[str], optional) – Path(s) to JSON file(s) of configurations to exclude.

  • output_file (str, optional) – Path to save generated configurations.

Returns:

A list of n unique Structure objects. Each has a

number_of_equivalent_configurations attribute.

Return type:

list[Structure]

bsym.interface.pymatgen.space_group_from_structure(structure: Structure, subset: list[int] | None = None, atol: float = 1e-05) → SpaceGroup[source]

Generates a SpaceGroup object from a pymatgen Structure.

Parameters:

  • structure – Structure to be used to define the SpaceGroup.

  • subset – List of atom indices to be used for generating the symmetry operations.

  • atol – 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: Structure) → str[source]

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

Parameters:

structure – The input structure.

Returns:

The space group symbol.

bsym.interface.pymatgen.structure_cartesian_coordinates_mapping(structure: Structure, symmop: SymmOp) → ndarray[source]

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

Parameters:

  • structure – The pymatgen Structure.

  • symmop – The pymatgen symmetry operation object.

Returns:

The mapped Cartesian coordinates.

bsym.interface.pymatgen.structure_mapping_list(new_structure: Structure, mapping_structure: Structure, atol: float) → list[int][source]

Gives the index mapping between two pymatgen Structure objects.

Parameters:

  • new_structure – The new structure.

  • mapping_structure – The structure to map to.

  • atol – Absolute tolerance for coordinate matching.

Returns:

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

bsym.interface.pymatgen.unique_structure_substitutions(structure: Structure | Molecule, to_substitute: str, site_distribution: dict[str, int], verbose: bool = False, atol: float = 1e-05, show_progress: bool | str = False) → list[Any][source]

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

Parameters:

  • structure – The parent structure.

  • to_substitute – Atom label for the sites to be substituted.

  • site_distribution – A dictionary that defines the number of each substituting element.

  • verbose – Verbose output.

  • atol – Tolerance factor for the pymatgen `coordinate mapping`_ under each symmetry operation. Default=1e-5.

  • show_progress – 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.

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_structure_substitutions_by_composition(structure: Structure | Molecule, to_substitute: str, species_list: list[str], bounds: dict[str, tuple[int | None, int | None]] | None = None, verbose: bool = False, atol: float = 1e-05, show_progress: bool | str = False) → dict[tuple[int, ...], list[Any]][source]

Generate all symmetry-unique structures for all compositions of substituting species.

Parameters:

  • structure – The parent structure.

  • to_substitute – Atom label for the sites to be substituted.

  • species_list – List of species to substitute, e.g., [‘Li’, ‘Na’, ‘Mg’]. Order determines composition tuple indices.

  • bounds – Occupancy bounds for each species. Keys are species names, values are (min, max) tuples. e.g., {‘Li’: (1, 3), ‘Na’: (0, 2)}

  • verbose – Verbose output.

  • atol – Tolerance factor for coordinate mapping. Default=1e-5.

  • show_progress – Show progress bars. Can be True, False, or “notebook”.

Returns:

Mapping from composition tuples to lists of Structure objects. Keys are tuples like (2, 1, 1) corresponding to species_list order. Each Structure has a number_of_equivalent_configurations attribute.

Example

>>> results = unique_structure_substitutions_by_composition(
...     structure, 'X', ['Li', 'Na'])
>>> # results[(2, 2)] gives structures with 2 Li and 2 Na
bsym.interface.pymatgen.unique_symmetry_operations_as_vectors_from_structure(structure: Structure | Molecule, verbose: bool = False, subset: list[int] | None = None, atol: float = 1e-05) → list[list[int]][source]

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

Parameters:

  • structure – Structure or Molecule to be analysed.

  • verbose – Print verbose output including space/point group information.

  • subset – List of atom indices to be used for generating the symmetry operations.

  • atol – Tolerance factor for the pymatgen `coordinate mapping`_ under each symmetry operation.

Returns:

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