SiteAnalyzer

class emmet.core.featurization.robocrys.condense.site.SiteAnalyzer(bonded_structure, use_symmetry_equivalent_sites=False, symprec=0.01, minimum_geometry_op=0.4, use_iupac_formula=True)

Bases: object

Class to extract information on site geometry and bonding.

Attributes:

symmetry_labels: A dict mapping the site indices to the symmetry: label for that site. If two sites are symmetrically equivalent they share the same symmetry label. The numbering begins at 1 for each element in the structure.
equivalent_sites: A list of indices mapping each site in: the structure to a symmetrically or structurally equivalent site, depending on the value of use_symmetry_equivalent_sites.

Args:

bonded_structure: A bonded structure with nearest neighbor data: included. For example generated using pymatgen.analysis.local_env.CrystalNN or pymatgen.analysis.local_env.VoronoiNN.
use_symmetry_equivalent_sites: Whether to use symmetry to determine if: sites are inequivalent. If False, the site geometry and (next) nearest neighbor information will be used.
symprec: The tolerance used when determining the symmetry of: the structure. The symmetry can used both to determine if multiple sites are symmetrically equivalent and to obtain the symmetry labels for each site.
minimum_geometry_op: The minimum geometrical order parameter for a: geometry match to be returned.
use_iupac_formula (bool, optional): Whether to order formulas: by the iupac “electronegativity” series, defined in Table VI of “Nomenclature of Inorganic Chemistry (IUPAC Recommendations 2005)”. This ordering effectively follows the groups and rows of the periodic table, except the Lanthanides, Actanides and hydrogen. If set to False, the elements will be ordered according to the electronegativity values.

Parameters:

bonded_structure (StructureGraph)
use_symmetry_equivalent_sites (bool)
symprec (float)
minimum_geometry_op (float)
use_iupac_formula (bool)

get_site_geometry(site_index)

Gets the bonding geometry of a site.

For example, “octahedral” or “square-planar”.

Return type:: dict[str, str | float]
Parameters:: site_index (int)

Args:

site_index: The site index (zero based).

Returns:

The site geometry information formatted at as:

{'type': geometry_type, 'likeness': order_parameter}

Where geometry_type is a str corresponding to the geometry type (e.g. octahedral) and order_parameter is a float indicating whether how close the geometry is to the perfect geometry. If the largest geometrical order parameter falls beneath robocrys.site.SiteAnalyzer.minimum_geometry_op, the geometry type will be returned as “X-coordinate”, where X is the coordination number.

get_nearest_neighbors(site_index, inc_inequivalent_site_index=True)

Gets information about the bonded nearest neighbors.

Return type:

list[dict[str, Any]]

Parameters:

site_index (int)
inc_inequivalent_site_index (bool)

Args:

site_index: The site index (zero based). inc_inequivalent_site_index: Whether to include the inequivalent

site indices in the nearest neighbor information.

Returns:

For each site bonded to site_index, returns a dict with the format:

{'element': el, 'dist': distance}

If inc_inequivalent_site_index=True, the data will have an additional key 'inequiv_index' corresponding to the inequivalent site index. E.g. if two sites are structurally/symmetrically equivalent (depending on the value of self.use_symmetry_equivalent_sites then they will have the same inequiv_index.

get_next_nearest_neighbors(site_index, inc_inequivalent_site_index=True)

Gets information about the bonded next nearest neighbors.

Return type:

list[dict[str, Any]]

Parameters:

site_index (int)
inc_inequivalent_site_index (bool)

Args:

site_index: The site index (zero based). inc_inequivalent_site_index: Whether to include the inequivalent

site indices.

Returns:

A list of the next nearest neighbor information. For each next nearest neighbor site, returns a dict with the format:

{'element': el, 'connectivity': con, 'geometry': geom,
 'angles': angles, 'distance': distance}

The connectivity property is the connectivity type to the next nearest neighbor, e.g. “face”, “corner”, or “edge”. The geometry property gives the geometry of the next nearest neighbor site. See the get_site_geometry method for the format of this data. The angles property gives the bond angles between the site and the next nearest neighbour. Returned as a list of int. Multiple bond angles are given when the two sites share more than nearest neighbor (e.g. if they are face-sharing or edge-sharing). The distance property gives the distance between the site and the next nearest neighbor. If inc_inequivalent_site_index=True, the data will have an additional key 'inequiv_index' corresponding to the inequivalent site index. E.g. if two sites are structurally/symmetrically equivalent (depending on the value of self.use_symmetry_equivalent_sites then they will have the same inequiv_index.

get_site_summary(site_index)

Gets a summary of the site information.

Return type:: dict[str, Any]
Parameters:: site_index (int)

Args:

site_index: The site index (zero based).

Returns:

A summary of the site information, formatted as:

{
    'element': 'Mo4+',
    'geometry': {
        'likesness': 0.5544,
        'type': 'pentagonal pyramidal'
    },
    'nn': [2, 2, 2, 2, 2, 2],
    'nnn': {'edge': [0, 0, 0, 0, 0, 0]},
    'poly_formula': 'S6',
    'sym_labels': (1,)
}

Where element is the species string (if the species has oxidation states, these will be included in the string). The geometry key is the geometry information as produced by SiteAnalyzer.get_site_geometry(). The nn key lists the site indices of the nearest neighbor bonding sites. Note the inequivalent site index is given for each site. The nnn key gives the next nearest neighbor information, broken up by the connectivity to that neighbor. The poly_formula key gives the formula of the bonded nearest neighbors. poly_formula will be None if the site geometry is not in robocrys.util.connected_geometries. The sym_labels key gives the symmetry labels of the site. If two sites are symmetrically equivalent they share the same symmetry label. The numbering begins at 1 for each element in the structure. If SiteAnalyzer.use_symmetry_inequivalnt_sites is False, each site may have more than one symmetry label, as structural features have instead been used to determine the site equivalences, i.e. two sites are symmetrically distinct but share the same geometry, nearest neighbor and next nearest neighbor properties.

get_bond_distance_summary(site_index)

Gets the bond distance summary for a site.

Return type:: dict[int, list[float]]
Parameters:: site_index (int)

Args:

site_index: The site index (zero based).

Returns:

The bonding data for the site, formatted as:

{to_site: [dist_1, dist_2, dist_3, ...]}

Where to_site is the index of a nearest neighbor site and dist_1 etc are the bond distances as float.

get_connectivity_angle_summary(site_index)

Gets the connectivity angle summary for a site.

The connectivity angles are the angles between a site and its next nearest neighbors.

Return type:: dict[int, dict[str, list[float]]]
Parameters:: site_index (int)

Args:

site_index: The site index (zero based).

Returns:

The connectivity angle data for the site, formatted as:

{
    to_site: {
        connectivity_a: [angle_1, angle_2, ...]
        connectivity_b: [angle_1, angle_2, ...]
    }
}

Where to_site is the index of a next nearest neighbor site, connectivity_a etc are the bonding connectivity type, e.g. 'edge' or 'corner' (for edge-sharing and corner-sharing connectivity), and angle_1 etc are the bond angles as float.

get_nnn_distance_summary(site_index)

Gets the next nearest neighbor distance summary for a site.

Return type:: dict[int, dict[str, list[float]]]
Parameters:: site_index (int)

Args:

site_index: The site index (zero based).

Returns:

The connectivity distance data for the site, formatted as:

{
    to_site: {
        connectivity_a: [distance_1, distance_2, ...]
        connectivity_b: [distance_1, distance_2, ...]
    }
}

Where to_site is the index of a next nearest neighbor site, connectivity_a etc are the bonding connectivity type, e.g. 'edge' or 'corner' (for edge-sharing and corner-sharing connectivity), and distance_1 etc are the bond angles as float.

get_all_site_summaries()

Gets the site summaries for all sites.

Returns:

The site summaries for all sites, formatted as:

{
    site_index: site_summary
}

Where site_summary has the same format as produced by SiteAnalyzer.get_site_summary().

get_all_bond_distance_summaries()

Gets the bond distance summaries for all sites.

Return type:: dict[int, dict[int, list[float]]]

Returns:

The bond distance summaries for all sites, formatted as:

{
    from_site: {
        to_site: distances
    }
}

Where from_site and to_site are site indices and distances is a list of float of bond distances.

get_all_connectivity_angle_summaries()

Gets the connectivity angle summaries for all sites.

The connectivity angles are the angles between a site and its next nearest neighbors.

Return type:: dict[int, dict[int, dict[str, list[float]]]]

Returns:

The connectivity angle summaries for all sites, formatted as:

{
    from_site: {
        to_site: {
            connectivity: angles
        }
    }
}

Where from_site and to_site are the site indices of two sites, connectivity is the connectivity type (e.g. 'edge' or 'face') and angles is a list of float of connectivity angles.

get_all_nnn_distance_summaries()

Gets the next nearest neighbor distance summaries for all sites.

Return type:: dict[int, dict[int, dict[str, list[float]]]]

Returns:

The next nearest neighbor distance summaries for all sites, formatted as:

{
    from_site: {
        to_site: {
            connectivity: distances
        }
    }
}

Where from_site and to_site are the site indices of two sites, connectivity is the connectivity type (e.g. 'edge' or 'face') and distances is a list of float of distances.

get_inequivalent_site_indices(site_indices)

Gets the inequivalent site indices from a list of site indices.

Return type:: list[int]
Parameters:: site_indices (list[int])

Args:

site_indices: The site indices.

Returns:

The inequivalent site indices. For example, if a structure has 4 sites where the first two are equivalent and the last two are inequivalent. If site_indices=[0, 1, 2, 3] the output will be:

[0, 0, 2, 3]