pymatgen.analysis.chemenv.connectivity package — pymatgen 2026.3.9 documentation

# pymatgen.analysis.chemenv.connectivity package

Package for analyzing connectivity.

## Submodules

## pymatgen.analysis.chemenv.connectivity.connected_components module

Connected components.

class ConnectedComponent(environments=None, links=None, environments_data=None, links_data=None, graph=None)

  Bases: `MSONable`

  Describe the connected components in a structure in terms of coordination environments.

  Constructor for the ConnectedComponent object.

  Parameters:

    - environments – Environments in the connected component.

    - links – Links between environments in the connected component.

    - environments_data – Data of environment nodes.

    - links_data – Data of links between environment nodes.

    - graph – Graph of the connected component.

  as_dict()

    Bson-serializable dict representation of the ConnectedComponent object.

    Returns:

      Bson-serializable dict representation of the ConnectedComponent object.

    Return type:

      dict

  compute_periodicity(algorithm='all_simple_paths') → None
    Parameters:

      algorithm (str) – Algorithm to use to compute the periodicity vectors. Can be either “all_simple_paths” or “cycle_basis”.

  compute_periodicity_all_simple_paths_algorithm()

    Get the periodicity vectors of the connected component.

  compute_periodicity_cycle_basis() → None

    Compute periodicity vectors of the connected component.

  coordination_sequence(source_node, path_size=5, coordination='number', include_source=False)

    Get the coordination sequence for a given node.

    Parameters:

      - source_node – Node for which the coordination sequence is computed.

      - path_size – Maximum length of the path for the coordination sequence.

      - coordination – Type of coordination sequence. The default (“number”) corresponds to the number of environment nodes that are reachable by following paths of sizes between 1 and path_size. For coordination “env:number”, this resulting coordination sequence is a sequence of dictionaries mapping the type of environment to the number of such environment reachable by following paths of sizes between 1 and path_size.

      - include_source – Whether to include the source_node in the coordination sequence.

    Returns:

      Mapping between the nth “layer” of the connected component with the corresponding coordination.

    Return type:

      dict

    Examples

    The corner-sharing octahedral framework (as in perovskites) have the following coordination sequence (up to a path of size 6) : {1: 6, 2: 18, 3: 38, 4: 66, 5: 102, 6: 146} Considering both the octahedrons and the cuboctahedrons of the typical BaTiO3 perovskite, the “env:number” coordination sequence (up to a path of size 6) starting on the Ti octahedron and Ba cuboctahedron are the following : Starting on the Ti octahedron : {1: {‘O:6’: 6, ‘C:12’: 8}, 2: {‘O:6’: 26, ‘C:12’: 48},

    > 3: {‘O:6’: 90, ‘C:12’: 128}, 4: {‘O:6’: 194, ‘C:12’: 248}, 5: {‘O:6’: 338, ‘C:12’: 408}, 6: {‘O:6’: 522, ‘C:12’: 608}}

    Starting on the Ba cuboctahedron{1: {‘O:6’: 8, ‘C:12’: 18}, 2: {‘O:6’: 48, ‘C:12’: 74},

      3: {‘O:6’: 128, ‘C:12’: 170}, 4: {‘O:6’: 248, ‘C:12’: 306}, 5: {‘O:6’: 408, ‘C:12’: 482}, 6: {‘O:6’: 608, ‘C:12’: 698}}

    If include_source is set to True, the source node is included in the sequence, e.g. for the corner-sharing octahedral framework : {0: 1, 1: 6, 2: 18, 3: 38, 4: 66, 5: 102, 6: 146}. For the “env:number” coordination starting on a Ba cuboctahedron (as shown above), the coordination sequence is then : {0: {‘C:12’: 1}, 1: {‘O:6’: 8, ‘C:12’: 18}, 2: {‘O:6’: 48, ‘C:12’: 74}, 3: {‘O:6’: 128, ‘C:12’: 170},

    > 4: {‘O:6’: 248, ‘C:12’: 306}, 5: {‘O:6’: 408, ‘C:12’: 482}, 6: {‘O:6’: 608, ‘C:12’: 698}}

  description(full=False)
    Parameters:

      full (bool) – Whether to return a short or full description.

    Returns:

      A description of the connected component.

    Return type:

      str

  elastic_centered_graph(start_node=None)
    Parameters:

      start_node (Node, optional) – Node to start the elastic centering from. If not provided, the first node in the graph is used.

    Returns:

      Elastic centered subgraph.

    Return type:

      nx.MultiGraph

  classmethod from_dict(dct: dict) → Self

    Reconstructs the ConnectedComponent object from a dict representation of the ConnectedComponent object created using the as_dict method.

    Parameters:

      dct (dict) – dict representation of the ConnectedComponent object

    Returns:

      The connected component representing the links of a given set of environments.

    Return type:

      ConnectedComponent

  classmethod from_graph(g) → Self

    Constructor for the ConnectedComponent object from a graph of the connected component.

    Parameters:

      g (MultiGraph) – Graph of the connected component.

    Returns:

      The connected component representing the links of a given set of environments.

    Return type:

      ConnectedComponent

  property graph

    The Networkx MultiGraph object of this connected component with environment as nodes and links between these nodes as edges with information about the image cell difference if any.

  property is_0d: bool

    Whether this connected component is 0-dimensional.

  property is_1d: bool

    Whether this connected component is 1-dimensional.

  property is_2d: bool

    Whether this connected component is 2-dimensional.

  property is_3d: bool

    Whether this connected component is 3-dimensional.

  property is_periodic: bool

    Whether this connected component is periodic.

  make_supergraph(multiplicity)
    Parameters:

      multiplicity (int) – Multiplicity of the super graph.

    Returns:

      Super graph of the connected component.

    Return type:

      nx.MultiGraph

  property periodicity

    Periodicity of this connected component.

  property periodicity_vectors

    Periodicity vectors of this connected component.

  show_graph(graph: MultiGraph | None = None, save_file: str | None = None, drawing_type: str = 'internal') → None

    Displays the graph using the specified drawing type.

    Parameters:

      - graph (Graph, optional) – The graph to display. If not provided, the current graph is used.

      - save_file (str, optional) – The file path to save the graph image to. If not provided, the graph is not saved.

      - drawing_type (str) – The type of drawing to use. Can be “internal” or “external”.

draw_network(env_graph, pos, ax, sg=None, periodicity_vectors=None)

  Draw network of environments in a matplotlib figure axes.

  Parameters:

    - env_graph – Graph of environments.

    - pos – Positions of the nodes of the environments in the 2D figure.

    - ax – Axes object in which the network should be drawn.

    - sg – Not used currently (drawing of supergraphs).

    - periodicity_vectors – List of periodicity vectors that should be drawn.

make_supergraph(graph, multiplicity, periodicity_vectors)

  Make super graph from a graph of environments.

  Parameters:

    - graph – Graph of environments.

    - multiplicity – Multiplicity of the super graph.

    - periodicity_vectors – Periodicity vectors needed to make the super graph.

  Returns:

    Super graph of the environments.

  Return type:

    nx.MultiGraph

## pymatgen.analysis.chemenv.connectivity.connectivity_finder module

Module implementing connectivity finding.

class ConnectivityFinder(multiple_environments_choice=None)

  Bases: `object`

  Main class used to find the structure connectivity of a structure.

  Constructor for the ConnectivityFinder.

  Parameters:

    - multiple_environments_choice – defines the procedure to apply when

    - one (the environment of a given site is described as a "mix" of more than)

    - environments. (coordination)

  get_structure_connectivity(light_structure_environments)

    Get the structure connectivity from the coordination environments provided as an input.

    Parameters:

      - light_structure_environments – LightStructureEnvironments with the

      - structure (relevant coordination environments in the)

    Returns:

      a StructureConnectivity object describing the connectivity of

    the environments in the structure

  setup_parameters(multiple_environments_choice)

    Setup of the parameters for the connectivity finder.

## pymatgen.analysis.chemenv.connectivity.environment_nodes module

Environment nodes module.

class AbstractEnvironmentNode(central_site, i_central_site)

  Bases: `MSONable`

  Abstract class used to define an environment as a node in a graph.

  Constructor for the AbstractEnvironmentNode object.

  Parameters:

    - central_site (Site or subclass of Site) – central site as a pymatgen Site or subclass of Site (e.g. PeriodicSite, …).

    - i_central_site (int) – Index of the central site in the structure.

  ATOM = 6
  CE_NNBCES_NBCES_LIGANDS = -1
  COORDINATION_ENVIRONMENT = 0
  DEFAULT_EXTENSIONS = (6, 0)
  LIGANDS_ARRANGEMENT = 4
  NEIGHBORING_CES = 2
  NEIGHBORING_COORDINATION_ENVIRONMENTS = 2
  NEIGHBORS_LIGANDS_ARRANGEMENT = 5
  NUMBER_OF_LIGANDS_FOR_EACH_NEIGHBORING_CE = 3
  NUMBER_OF_LIGANDS_FOR_EACH_NEIGHBORING_COORDINATION_ENVIRONMENT = 3
  NUMBER_OF_NEIGHBORING_CES = 1
  NUMBER_OF_NEIGHBORING_COORDINATION_ENVIRONMENTS = 1
  property atom_symbol

    Symbol of the atom on the central site.

  property ce

    Coordination environment of this node.

  property ce_symbol

    Coordination environment of this node.

  abstract property coordination_environment

    Coordination environment of this node.

  everything_equal(other)

    Check equality with respect to another AbstractEnvironmentNode using the index of the central site as well as the central site itself.

  property isite

    Index of the central site.

  property mp_symbol

    Coordination environment of this node.

class EnvironmentNode(central_site, i_central_site, ce_symbol)

  Bases: `AbstractEnvironmentNode`

  Define an environment as a node in a graph.

  Constructor for the EnvironmentNode object.

  Parameters:

    - central_site (Site or subclass of Site) – central site as a pymatgen Site or subclass of Site (e.g. PeriodicSite, …).

    - i_central_site (int) – Index of the central site in the structure.

    - ce_symbol (str) – Symbol of the identified environment.

  property coordination_environment

    Coordination environment of this node.

  everything_equal(other)

    Compare with another environment node.

    Returns:

      True if it is equal to the other node.

    Return type:

      bool

get_environment_node(central_site, i_central_site, ce_symbol)

  Get the EnvironmentNode class or subclass for the given site and symbol.

  Parameters:

    - central_site (Site or subclass of Site) – Central site of the environment.

    - i_central_site (int) – Index of the central site in the structure.

    - ce_symbol – Symbol of the environment.

  Returns:

    An EnvironmentNode object.

## pymatgen.analysis.chemenv.connectivity.structure_connectivity module

Structure connectivity class.

class StructureConnectivity(light_structure_environment, connectivity_graph=None, environment_subgraphs=None)

  Bases: `MSONable`

  Main class containing the connectivity of a structure.

  Constructor for the StructureConnectivity object.

  Parameters:

    - light_structure_environment – a LightStructureEnvironments object containing the relevant local environments for the sites in the structure.

    - connectivity_graph – the networkx MultiGraph if it has already been computed, e.g. stored in a file or dict and StructureConnectivity is reconstructed from that file or dict.

    - environment_subgraphs – the different subgraphs of environments that have been computed if any (as for connectivity_graph, only if it is reconstructed from a file or dict).

  add_bonds(isite, site_neighbors_set)

    Add the bonds for a given site index to the structure connectivity graph.

    Parameters:

      - isite – Index of the site for which the bonds have to be added.

      - site_neighbors_set – site_neighbors_set: Neighbors set of the site

  add_sites()

    Add the sites in the structure connectivity graph.

  as_dict()

    Convert to MSONable dict.

  environment_subgraph(environments_symbols=None, only_atoms=None)
    Parameters:

      - environments_symbols (list[str]) – symbols of the environments to consider.

      - only_atoms (list[str]) – atoms to consider.

    Returns:

      The subgraph of the structure connectivity graph

    Return type:

      nx.MultiGraph

  classmethod from_dict(dct: dict) → Self
    Parameters:

      dct (dict)

    Returns:

      StructureConnectivity

  get_connected_components(environments_symbols=None, only_atoms=None)
  print_links() → None

    Print all links in the graph.

  setup_atom_environment_subgraph(atom_environment)
  setup_atom_environments_subgraph(atoms_environments)
  setup_connectivity_description()
  setup_environment_subgraph(environments_symbols, only_atoms=None)

    Set up the graph for predefined environments and optionally atoms.

    Parameters:

      - environments_symbols – Symbols of the environments for the environment subgraph.

      - only_atoms – Atoms to be considered.

  setup_environments_subgraph(environments_symbols)

get_delta_image(isite1, isite2, data1, data2)

  Helper method to get the delta image between one environment and another from the ligand’s delta images.