This module contains tools for [TODO]

get_nearest_neighbour_indices(structure: pymatgen.core.structure.Structure, ref_structure: pymatgen.core.structure.Structure, vertex_species: List[str], n_coord: int) → List[List[int]][source]

Returns the atom indices for the N nearest neighbours to each site in a reference structure.

  • structure (pymatgen.Structure) – A pymatgen Structure object, used to select the nearest neighbour indices.
  • ref_structure (pymatgen.Structure) – A pymatgen Structure object. Each site is used to find the set of N nearest neighbours (of the specified atomic species) in structure.
  • vertex_species (list(str)) – List of strings specifying the atomic species of the vertex atoms, e.g. [ 'S', 'I' ].
  • n_coord (int) – Number of matching nearest neighbours to return for each site in ref_structure.

N_sites x N_neighbours nested list of vertex atom indices.

Return type:


get_vertex_indices(structure: pymatgen.core.structure.Structure, centre_species: str, vertex_species: Union[str, List[str]], cutoff: float = 4.5, n_vertices: Union[int, List[int]] = 6) → List[List[int]][source]

Find the atom indices for atoms defining the vertices of coordination polyhedra, from a pymatgen Structure object.

Given the elemental species of a set of central atoms, A, and of the polyhedral vertices, B, this function finds: for each A, then N closest neighbours B (within some cutoff). The number of neighbours found per central atom can be a single value for all A, or can be provided as a list of values for each A.

  • structure (pymatgen.Structure) – A pymatgen Structure object, used to find the coordination polyhedra vertices..
  • centre_species (str) – Species string identifying the atoms at the centres of each coordination environment, e.g. “Na”.
  • vertex_species (str or list(str)) – Species string identifying the atoms at the vertices of each coordination environment, e.g. “S”., or a list of strings, e.g. ["S", "I"].
  • cutoff (float) – Distance cutoff for neighbour search.
  • n_vertices (int or list(int)) – Number(s) of nearest neighbours to return for each set of vertices. If a list is passed, this should be the same length as the number of atoms of centre species A.

Nested list of integers, giving the atom indices for each

coordination environment.

Return type:


site_index_mapping(structure1: pymatgen.core.structure.Structure, structure2: pymatgen.core.structure.Structure, species1: Union[str, List[str], None] = None, species2: Union[str, List[str], None] = None, one_to_one_mapping: Optional[bool] = True, return_mapping_distances: Optional[bool] = False) → Union[numpy.ndarray, Tuple[numpy.ndarray, numpy.ndarray]][source]

Compute the site index mapping between two structures based on the closest corresponding site in structure2 to each selected site in structure1.

  • structure1 (pymatgen.Structure) – The structure to map from.
  • structure2 (pymatgen.Structure) – The structure to map to.
  • species1 (optional, str or list(str)) – Optional argument to select a subset of atomic species to map site indices from.
  • species2 (optional, str of list(str)) – Optional argument to specify a subset of atomic species to map site indices to.
  • one_to_one_mapping (optional, bool) – Optional argument to check that a one-to-one mapping is found between the relevant subsets of sites in structure1 and structure2. Default is True.



ValueError – if one_to_one_mapping = True and a one-to-one mapping is not found.

species_string_from_site(site: pymatgen.core.sites.Site)[source]
x_pbc(x: numpy.ndarray)[source]

Return an array of fractional coordinates mapped into all positive neighbouring periodic cells.

Parameters:x (np.array) – Input fractional coordinates.
(9,3) numpy array of all mapped fractional coordinates, including the
original coordinates in the origin calculation cell.
Return type:np.array


>>> x = np.array([0.1, 0.2, 0.3])
>>> x_pbc(x)
array([[0.1, 0.2, 0.3],
       [1.1, 0.2, 0.3],
       [0.1, 1.2, 0.3],
       [0.1, 0.2, 1.3],
       [1.1, 1.2, 0.3],
       [1.1, 0.2, 1.3],
       [0.1, 1.2, 1.3],
       [1.1, 1.2, 1.3]])