synkit 0.0.1__py3-none-any.whl

synkit/Graph/Feature/graph_descriptors.py

@@ -0,0 +1,325 @@
+import networkx as nx
+from joblib import Parallel, delayed
+from typing import List, Dict, Any, Union
+from collections import Counter, OrderedDict
+from synkit.IO.debug import setup_logging
+from synkit.Graph.Feature.graph_signature import GraphSignature
+
+logger = setup_logging()
+
+
+class GraphDescriptor:
+    def __init__(self) -> None:
+        pass
+
+    @staticmethod
+    def is_graph_empty(graph: Union[nx.Graph, dict, list, Any]) -> bool:
+        """
+        Determine if a graph representation is empty.
+
+        Parameters:
+        - graph (Union[nx.Graph, dict, list, Any]): A graph representation which can be
+          a NetworkX graph, a dictionary, a list, or an object with an 'is_empty' method.
+
+        Returns:
+        - bool: True if the graph is empty, False otherwise.
+
+        Raises:
+        - TypeError: If the graph representation is not supported.
+        """
+        if isinstance(graph, nx.Graph):
+            return graph.number_of_nodes() == 0
+        elif isinstance(graph, dict):
+            return len(graph) == 0
+        elif isinstance(graph, list):
+            return all(len(row) == 0 for row in graph)
+        elif hasattr(graph, "is_empty"):
+            return graph.is_empty()
+        else:
+            raise TypeError("Unsupported graph representation")
+
+    @staticmethod
+    def is_acyclic_graph(G: nx.Graph) -> bool:
+        """
+        Determines if the given graph is acyclic.
+
+        Parameters:
+        - G (nx.Graph): The graph to be checked.
+
+        Returns:
+        - bool: True if the graph is acyclic, False otherwise.
+        """
+        GraphDescriptor._validate_graph_input(G)
+        return nx.is_tree(G) if not GraphDescriptor.is_graph_empty(G) else False
+
+    @staticmethod
+    def is_single_cyclic_graph(G: nx.Graph) -> bool:
+        """
+        Determines if the given graph has exactly one cycle.
+
+        Parameters:
+        - G (nx.Graph): The graph to be checked.
+
+        Returns:
+        - bool: True if the graph is single cyclic, False otherwise.
+        """
+        GraphDescriptor._validate_graph_input(G)
+        if GraphDescriptor.is_graph_empty(G) or not nx.is_connected(G):
+            return False
+
+        cycles = nx.cycle_basis(G)
+        if cycles and set(G.nodes()) == {node for cycle in cycles for node in cycle}:
+            return G.number_of_edges() == G.number_of_nodes()
+        return False
+
+    @staticmethod
+    def is_complex_cyclic_graph(G: nx.Graph) -> bool:
+        """
+        Determines if the graph is complex cyclic with multiple cycles.
+
+        Parameters:
+        - G (nx.Graph): The graph to be checked.
+
+        Returns:
+        - bool: True if the graph is complex cyclic, False otherwise.
+        """
+        GraphDescriptor._validate_graph_input(G)
+        if GraphDescriptor.is_graph_empty(G) or not nx.is_connected(G):
+            return False
+
+        cycles = nx.minimum_cycle_basis(G)
+        nodes_in_cycles = {node for cycle in cycles for node in cycle}
+        return len(cycles) > 1 and nodes_in_cycles == set(G.nodes())
+
+    @staticmethod
+    def check_graph_type(G: nx.Graph) -> str:
+        """
+        Classifies the graph as acyclic, single cyclic, or complex cyclic.
+
+        Parameters:
+        - G (nx.Graph): The graph to be checked.
+
+        Returns:
+        - str: The classification result.
+        """
+        GraphDescriptor._validate_graph_input(G)
+        if GraphDescriptor.is_graph_empty(G):
+            return "Empty Graph"
+        elif GraphDescriptor.is_acyclic_graph(G):
+            return "Acyclic"
+        elif GraphDescriptor.is_single_cyclic_graph(G):
+            return "Single Cyclic"
+        elif GraphDescriptor.is_complex_cyclic_graph(G):
+            return "Combinatorial Cyclic"
+        else:
+            return "Complex Cyclic"
+
+    @staticmethod
+    def get_cycle_member_rings(G: nx.Graph, type="minimal") -> List[int]:
+        """
+        Identifies all cycles in the given graph using cycle bases to ensure no overlap
+        and returns a list of the sizes of these cycles (member rings),
+        sorted in ascending order.
+
+        Parameters:
+        - G (nx.Graph): The NetworkX graph to be analyzed.
+
+        Returns:
+        - List[int]: A sorted list of cycle sizes (member rings) found in the graph.
+        """
+        if not isinstance(G, nx.Graph):
+            raise TypeError("Input must be a networkx Graph object.")
+
+        if type == "minimal":
+            cycles = nx.minimum_cycle_basis(G)
+        else:
+            cycles = nx.cycle_basis(G)
+        member_rings = [len(cycle) for cycle in cycles]
+
+        member_rings.sort()
+
+        return member_rings
+
+    @staticmethod
+    def get_element_count(graph: nx.Graph) -> Dict[str, int]:
+        """
+        Counts occurrences of each element in the graph nodes.
+
+        Parameters:
+        - graph (nx.Graph): A NetworkX graph with 'element' attribute in nodes.
+
+        Returns:
+        - Dict[str, int]: An ordered dictionary with element counts.
+        """
+        element_counts = Counter(data["element"] for _, data in graph.nodes(data=True))
+        return OrderedDict(sorted(element_counts.items()))
+
+    @staticmethod
+    def get_descriptors(
+        entry: Dict,
+        reaction_centers: str = "RC",
+        its: str = "ITS",
+        condensed: bool = True,
+    ) -> Dict:
+        """
+        Enhance an entry dictionary with topology type and reaction type descriptors.
+
+        Parameters:
+        - entry (Dict): A dictionary with reaction data.
+        - reaction_centers (str): Key for accessing reaction center data.
+        - its (str): Key for accessing ITS (Intermediate Transition State) data.
+
+        Returns:
+        - Dict: The enhanced entry with additional descriptors.
+        """
+        graph = GraphDescriptor._extract_graph(entry, reaction_centers)
+        its_graph = GraphDescriptor._extract_graph(entry, its)
+
+        if not graph or not its_graph:
+            return entry  # Early exit if graphs are missing
+
+        # Set initial topology descriptor for the reaction center graph
+        entry["topo"] = GraphDescriptor.check_graph_type(graph)
+        entry["cycle"] = GraphDescriptor.get_cycle_member_rings(graph)
+        entry["atom_count"] = GraphDescriptor.get_element_count(graph)
+        entry["its_count"] = GraphDescriptor.get_element_count(its_graph)
+
+        # Determine the reaction type based on the topology type
+        entry["rtype"] = (
+            "Elementary"
+            if entry["topo"] in ["Single Cyclic", "Acyclic"]
+            else "Complicated"
+        )
+
+        GraphDescriptor._adjust_cycle_and_step(entry, "cycle", entry["topo"])
+        entry["signature_rc"] = GraphSignature(graph).create_graph_signature()
+
+        # Initialize ITS descriptors and call adjust
+        topo_its = GraphDescriptor.check_graph_type(its_graph)
+        cycle_its = GraphDescriptor.get_cycle_member_rings(its_graph)
+        entry["cycle_its"] = cycle_its  # Ensure key is initialized
+        GraphDescriptor._adjust_cycle_and_step(
+            entry, "cycle_its", topo_its, its_prefix="its"
+        )
+
+        entry["signature_its"] = GraphSignature(its_graph).create_graph_signature()
+
+        return entry
+
+    @staticmethod
+    def _extract_graph(entry: Dict, key: str) -> Union[nx.Graph, None]:
+        """
+        Extracts a graph from an entry dictionary based on the specified key.
+
+        Parameters:
+        - entry (Dict): The dictionary containing graph data.
+        - key (str): The key for accessing graph data.
+
+        Returns:
+        - Union[nx.Graph, None]: The extracted graph or None if unavailable.
+        """
+        data = entry.get(key)
+        if isinstance(data, tuple):
+            try:
+                return data[2]
+            except IndexError:
+                logger.error(f"No graph data available at index 2 for entry {entry}")
+        elif isinstance(data, nx.Graph):
+            return data
+        else:
+            logger.error(f"Unsupported data type for {key} in entry {entry}")
+        return None
+
+    @staticmethod
+    def _adjust_cycle_and_step(
+        entry: Dict, cycle_key: str, topo_type: str, its_prefix: str = ""
+    ) -> None:
+        """
+        Adjusts cycle and step descriptors based on the graph topology type.
+
+        Parameters:
+        - entry (Dict): The entry dictionary to update.
+        - cycle_key (str): The key for the cycle descriptor.
+        - topo_type (str): The topology type.
+        - its_prefix (str): Prefix for ITS-specific descriptors.
+        """
+        step_key = f"rstep_{its_prefix}" if its_prefix else "rstep"
+
+        # Initialize the step key in the dictionary to avoid KeyError
+        if cycle_key not in entry:
+            entry[cycle_key] = []
+
+        if topo_type == "Acyclic":
+            entry[cycle_key] = [0]
+        elif topo_type == "Complex Cyclic":
+            entry[cycle_key] = [0] + entry[cycle_key]
+
+        entry[step_key] = len(entry[cycle_key])
+
+    @staticmethod
+    def _validate_graph_input(G: nx.Graph) -> None:
+        """
+        Validates that the input is a NetworkX graph.
+
+        Parameters:
+        - G (nx.Graph): The graph to validate.
+
+        Raises:
+        - TypeError: If G is not a NetworkX Graph.
+        """
+        if not isinstance(G, nx.Graph):
+            raise TypeError("Input must be a NetworkX Graph object.")
+
+    @staticmethod
+    def process_entries_in_parallel(
+        entries: List[Dict],
+        reaction_centers: str = "RC",
+        its: str = "ITS",
+        condensed: bool = True,
+        n_jobs: int = 4,
+        verbose: int = 0,
+    ) -> List[Dict]:
+        """
+        Processes a list of entries in parallel to enhance each entry with descriptors.
+
+        Parameters:
+        - entries (List[Dict]): List of dictionaries containing reaction data to enhance.
+        - reaction_centers (str): Key to retrieve reaction center graph data from each
+        entry dictionary.
+        - its (str): Key to retrieve ITS (Intermediate Transition State) graph data from
+        each entry dictionary.
+        - condensed (bool): If True, condenses node signatures with counts.
+        - n_jobs (int): Number of jobs to run in parallel. -1 uses all processors.
+        - verbose (int): The verbosity level for joblib's Parallel.
+
+        Returns:
+        - List[Dict]: A list of enhanced dictionaries with added descriptors.
+        """
+        return Parallel(n_jobs=n_jobs, verbose=verbose)(
+            delayed(GraphDescriptor.get_descriptors)(
+                entry, reaction_centers, its, condensed
+            )
+            for entry in entries
+        )
+
+
+def check_graph_connectivity(graph: nx.Graph) -> str:
+    """
+    Check the connectivity of a NetworkX graph.
+
+    This function assesses whether all nodes in the graph are connected by some path,
+    applicable to undirected graphs.
+
+    Parameters:
+    - graph (nx.Graph): A NetworkX graph object.
+
+    Returns:
+    - str: Returns 'Connected' if the graph is connected, otherwise 'Disconnected'.
+
+    Raises:
+    - NetworkXNotImplemented: If graph is directed and does not support is_connected.
+    """
+    if nx.is_connected(graph):
+        return "Connected"
+    else:
+        return "Disconnected."

synkit/Graph/Feature/graph_fps.py

@@ -0,0 +1,97 @@
+import networkx as nx
+import hashlib
+import numpy as np
+
+
+class GraphFP:
+    def __init__(
+        self, graph: nx.Graph, nBits: int = 1024, hash_alg: str = "sha256"
+    ) -> None:
+        """
+        Initialize the GraphFP class to create binary fingerprints based on various graph
+        characteristics.
+
+        Parameters:
+        - graph (nx.Graph): Graph on which to perform analysis.
+        - nBits (int): Size of the binary fingerprint in bits.
+        - hash_alg (str): Cryptographic hash function used for hashing.
+        """
+        self.graph = graph
+        self.nBits = nBits
+        self.hash_alg = hash_alg
+        self.hash_function = getattr(hashlib, self.hash_alg)
+
+    def fingerprint(self, method: str) -> str:
+        """
+        Generate a binary string fingerprint of the graph using the specified method.
+
+        Parameters:
+        - method (str): The method to use for fingerprinting
+        ('spectrum', 'adjacency', 'degree', 'motif')
+
+        Returns:
+        - str: A binary string of length `nBits` that represents the fingerprint of
+        the graph.
+        """
+        if method == "spectrum":
+            fp = self._spectrum_fp()
+        elif method == "adjacency":
+            fp = self._adjacency_fp()
+        elif method == "degree":
+            fp = self._degree_sequence_fp()
+        elif method == "motif":
+            fp = self._motif_count_fp()
+        else:
+            raise ValueError("Unsupported fingerprinting method.")
+
+        # If the fingerprint is shorter than nBits, use iterative deepening
+        if len(fp) < self.nBits:
+            fp += self.iterative_deepening(self.nBits - len(fp))
+
+        return fp[: self.nBits]
+
+    def _spectrum_fp(self) -> str:
+        # Graph spectrum (eigenvalues of the adjacency matrix)
+        eigenvalues = np.linalg.eigvals(nx.adjacency_matrix(self.graph).todense())
+        sorted_eigenvalues = np.sort(eigenvalues)[: self.nBits]
+        eigen_str = "".join(
+            bin(int(abs(eig)))[2:].zfill(8) for eig in sorted_eigenvalues
+        )
+        return eigen_str[: self.nBits]
+
+    def _adjacency_fp(self) -> str:
+        # Adjacency matrix flattened
+        adj_matrix = nx.adjacency_matrix(self.graph).todense().flatten()
+        adj_str = "".join(str(int(x)) for x in adj_matrix)
+        return adj_str[: self.nBits]
+
+    def _degree_sequence_fp(self) -> str:
+        # Degree sequence
+        degrees = sorted([d for n, d in self.graph.degree()], reverse=True)
+        degree_str = "".join(bin(d)[2:].zfill(8) for d in degrees)
+        return degree_str[: self.nBits]
+
+    def _motif_count_fp(self) -> str:
+        # Motif counts (e.g., number of triangles)
+        triangles = sum(nx.triangles(self.graph).values()) // 3
+        triangle_str = bin(triangles)[2:].zfill(self.nBits)
+        return triangle_str[: self.nBits]
+
+    def iterative_deepening(self, remaining_bits: int) -> str:
+        """
+        Extend the hash length using iterative hashing until the desired bit length is
+        achieved.
+
+        Parameters:
+        - remaining_bits (int): Number of bits needed to complete the fingerprint
+        to `nBits`.
+
+        Returns:
+        - str: Additional binary data to achieve the desired hash length.
+        """
+        additional_data = ""
+        hash_obj = self.hash_function()
+        while len(additional_data) * 4 < remaining_bits:
+            hash_obj.update(additional_data.encode())
+            additional_data += hash_obj.hexdigest()
+        return bin(int(additional_data, 16))[2:][:remaining_bits]

synkit/Graph/Feature/graph_signature.py

@@ -0,0 +1,236 @@
+import hashlib
+import networkx as nx
+
+
+class GraphSignature:
+    """
+    Provides methods to generate canonical signatures for graph edges (with flexible 'order' and 'state' attributes,
+    and node degrees/neighbor information), various spectral invariants, adjacency matrix, and complete graphs.
+    Aims for high uniqueness without relying solely on isomorphism checks.
+    """
+
+    def __init__(self, graph: nx.Graph):
+        """
+        Initializes the GraphSignature class with a specified graph.
+
+        Parameters:
+        - graph (nx.Graph): A NetworkX graph instance.
+        """
+        self.graph = graph
+        self._validate_graph()
+
+    def _validate_graph(self):
+        """
+        Validates that all nodes have the required attributes ('element' and 'charge'),
+        and all edges have the required 'order' attribute as int, float, or tuple of two floats,
+        and optionally the 'state' attribute.
+
+        Raises:
+        - ValueError: If any node is missing the 'element' or 'charge' attribute,
+                      or if any edge is missing the 'order' attribute or has an invalid type.
+        """
+        for node, data in self.graph.nodes(data=True):
+            if "element" not in data:
+                raise ValueError(f"Node {node} is missing the 'element' attribute.")
+            if "charge" not in data:
+                raise ValueError(f"Node {node} is missing the 'charge' attribute.")
+
+        for u, v, data in self.graph.edges(data=True):
+            if "order" not in data:
+                raise ValueError(f"Edge ({u}, {v}) is missing the 'order' attribute.")
+            order = data["order"]
+            if isinstance(order, tuple):
+                if len(order) != 2 or not all(
+                    isinstance(o, (int, float)) for o in order
+                ):
+                    raise ValueError(
+                        f"Edge ({u}, {v}) has an invalid 'order'. It must be a tuple of two ints/floats."
+                    )
+            elif not isinstance(order, (int, float)):
+                raise ValueError(
+                    f"Edge ({u}, {v}) has an invalid 'order'. It must be an int, float, or a tuple of two ints/floats."
+                )
+
+            # Optional: Validate 'state' attribute if present
+            state = data.get("state", "steady")  # Default to 'steady' if missing
+            if state not in {"break", "form", "steady"}:
+                raise ValueError(
+                    f"Edge ({u}, {v}) has an invalid 'state'. It must be 'break', 'form', or 'steady'."
+                )
+
+    def create_edge_signature(
+        self, include_neighbors: bool = False, max_hop: int = 2
+    ) -> str:
+        """
+        Generates a canonical edge signature by formatting each edge with sorted node elements (including charge),
+        node degrees, bond order, bond state, and optionally including neighbor information and topological context.
+
+        Parameters:
+        - include_neighbors (bool): Whether to include neighbors' details in the edge signature.
+        - max_hop (int): Maximum number of hops to include for neighbor-level structural information.
+
+        Returns:
+        - str: A concatenated and sorted string of edge representations.
+        """
+        edge_signature_parts = []
+
+        for u, v, data in self.graph.edges(data=True):
+            # Retrieve bond order (default to (1.0, 1.0) if missing)
+            order = data.get("order", (1.0, 1.0))
+
+            # Format order as a tuple (default or actual value)
+            if isinstance(order, tuple):
+                order_str = f"{{{order[0]:.1f},{order[1]:.1f}}}"
+            else:
+                order_str = f"{float(order):.1f}"
+
+            # Get node elements and charges for both nodes
+            node1_element = self.graph.nodes[u].get(
+                "element", "X"
+            )  # Default to 'X' if missing
+            node1_charge = self.graph.nodes[u].get(
+                "charge", 0
+            )  # Default to 0 if missing
+            node2_element = self.graph.nodes[v].get("element", "X")
+            node2_charge = self.graph.nodes[v].get("charge", 0)
+
+            # Construct node representation with element and charge
+            node1 = f"{node1_element}{node1_charge}"
+            node2 = f"{node2_element}{node2_charge}"
+
+            # Optionally include neighbors in the signature
+            if include_neighbors:
+                neighbors_u = sorted(
+                    [
+                        f"{self.graph.nodes[neighbor].get('element', 'X')}{self.graph.nodes[neighbor].get('charge', 0)}"
+                        + f"d{self.graph.degree(neighbor)}"
+                        for neighbor in self.graph.neighbors(u)
+                    ]
+                )
+                neighbors_v = sorted(
+                    [
+                        f"{self.graph.nodes[neighbor].get('element', 'X')}{self.graph.nodes[neighbor].get('charge', 0)}"
+                        + f"d{self.graph.degree(neighbor)}"
+                        for neighbor in self.graph.neighbors(v)
+                    ]
+                )
+
+                # Represent neighbors within square brackets
+                node1_neighbors = "".join(neighbors_u)
+                node2_neighbors = "".join(neighbors_v)
+                node1 = f"{node1}[{node1_neighbors}]"
+                node2 = f"{node2}[{node2_neighbors}]"
+
+            # Include k-hop neighborhood information
+            if max_hop > 1:
+                node1_neighbors_khop = self._get_khop_neighbors(u, max_hop)
+                node2_neighbors_khop = self._get_khop_neighbors(v, max_hop)
+                node1 += f"[{node1_neighbors_khop}]"
+                node2 += f"[{node2_neighbors_khop}]"
+
+            # Sort nodes to ensure consistency in edge signature (avoid direction dependency)
+            node1, node2 = sorted([node1, node2])
+
+            # Format the edge signature and append it
+            edge_part = f"{node1}{order_str}{node2}"
+            edge_signature_parts.append(edge_part)
+
+        # Sort all edge signatures to ensure consistency in the final representation
+        return "/".join(sorted(edge_signature_parts))
+
+    def _get_khop_neighbors(self, node, max_hop):
+        """
+        Retrieves the k-hop neighborhood information for a given node.
+
+        Parameters:
+        - node (int): The node for which to get neighborhood information.
+        - max_hop (int): Maximum number of hops for neighborhood exploration.
+
+        Returns:
+        - str: A concatenated string representing the k-hop neighborhood information.
+        """
+        k_hop_neighbors = []
+        current_hop_neighbors = [node]
+        for _ in range(max_hop):
+            next_hop_neighbors = []
+            for n in current_hop_neighbors:
+                next_hop_neighbors.extend(list(self.graph.neighbors(n)))
+            # Filter out already seen nodes to avoid loops
+            next_hop_neighbors = set(next_hop_neighbors) - set(k_hop_neighbors)
+            k_hop_neighbors.extend(next_hop_neighbors)
+            current_hop_neighbors = next_hop_neighbors
+
+        # Return sorted k-hop neighborhood info
+        return "".join(
+            sorted(
+                [
+                    f"{self.graph.nodes[neighbor].get('element', 'X')}{self.graph.nodes[neighbor].get('charge', 0)}"
+                    for neighbor in k_hop_neighbors
+                ]
+            )
+        )
+
+    def create_wl_hash(self, iterations: int = 3) -> str:
+        """
+        Generates a Weisfeiler-Lehman (WL) hash for the graph to capture its structural features.
+
+        Parameters:
+        - iterations (int): Number of WL iterations to perform.
+
+        Returns:
+        - str: A hexadecimal hash representing the WL feature.
+        """
+        # Initialize labels with both 'element' and 'charge'
+        labels = {
+            node: f"{data['element']}{data.get('charge', 0)}"
+            for node, data in self.graph.nodes(data=True)
+        }
+        for _ in range(iterations):
+            new_labels = {}
+            for node in self.graph.nodes():
+                # Gather sorted labels of neighbors
+                neighbor_labels = sorted(
+                    labels[neighbor] for neighbor in self.graph.neighbors(node)
+                )
+                # Concatenate current label with neighbor labels
+                concatenated = labels[node] + "".join(neighbor_labels)
+                # Hash the concatenated string to obtain a new label
+                new_label = hashlib.sha256(concatenated.encode()).hexdigest()
+                new_labels[node] = new_label
+            labels = new_labels
+        # Aggregate all node labels into a sorted string and hash it
+        sorted_labels = sorted(labels.values())
+        aggregated = "".join(sorted_labels)
+        graph_hash = hashlib.sha256(aggregated.encode()).hexdigest()
+        return graph_hash
+
+    def create_graph_signature(
+        self,
+        include_wl_hash: bool = True,
+        include_neighbors: bool = True,
+        max_hop: int = 1,
+    ) -> str:
+        """
+        Combines edge, various spectral invariants, and WL hash into a single comprehensive graph signature.
+
+        Parameters:
+        - include_wl_hash (bool): Whether to include the Weisfeiler-Lehman hash.
+        - include_spectral (bool): Whether to include spectral invariants.
+        - include_combined_hash (bool): Whether to include the combined hash.
+        - include_neighbors (bool): Whether to include neighbor information in edge signatures.
+
+        Returns:
+        - str: A concatenated string representing the complete graph signature.
+        """
+        signatures = []
+
+        if include_wl_hash:
+            wl_signature = self.create_wl_hash()
+            signatures.append(f"{wl_signature}")
+
+        edge_signature = self.create_edge_signature(
+            include_neighbors=include_neighbors, max_hop=max_hop
+        )
+        signatures.append(f"{edge_signature}")
+
+        return "|".join(signatures)