synkit 1.6.5__py3-none-win_amd64.whl

synkit/Graph/Matcher/automorphism.py

@@ -0,0 +1,314 @@
+"""automorphism.py
+~~~~~~~~~~~~~~~~~~
+Utility for computing graph automorphisms and pruning redundant sub-graph
+mappings equivalent under those symmetries.
+
+This module provides the :class:`Automorphism` helper, which computes the
+node-orbits of a graph and uses them to deduplicate subgraph-match mappings.
+
+Key idea
+--------
+Group host nodes into **orbits** under the automorphism group of the host
+graph: two nodes are in the same orbit if there exists an automorphism
+:math:`\\sigma` such that :math:`\\sigma(u) = v`.
+
+Mappings are considered equivalent if they hit the same **multiset of orbits**
+on the host side, and a single representative is kept.
+
+Disconnected graphs
+-------------------
+If the host graph is disconnected, we choose one connected component as an
+**anchor** (by default the *largest* component) to suppress automorphisms that
+swap isomorphic components. We then compute automorphisms **within each
+component** independently and combine component orbits. The total number of
+automorphisms is the product of component automorphism counts (excluding
+component-permutation symmetries by design due to anchoring).
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from typing import (
+    Dict,
+    Iterable,
+    List,
+    Mapping,
+    Optional,
+    Sequence,
+    Tuple,
+    Union,
+)
+
+import networkx as nx
+from networkx.algorithms.isomorphism import (
+    GraphMatcher,
+    categorical_edge_match,
+    categorical_multiedge_match,
+    categorical_node_match,
+)
+
+# ---------------------------------------------------------------------------
+# Typing aliases
+# ---------------------------------------------------------------------------
+NodeId = Union[int, str, Tuple, object]
+MappingDict = Mapping[NodeId, NodeId]
+
+__all__ = ["Automorphism", "NodeId", "MappingDict"]
+
+
+class Automorphism:
+    """Analyze the automorphism group of a graph and prune sub-graph mappings
+    that are equivalent under those symmetries.
+
+    Two nodes are in the same orbit if there exists an automorphism
+    :math:`\\sigma` such that :math:`\\sigma(u) = v`.
+
+    :param graph: The host graph for which to compute automorphisms.
+    :type graph: nx.Graph
+    :param node_attr_keys: Sequence of node attribute keys to respect in the automorphism
+                           computation (i.e., nodes must match on these attributes). Defaults to
+                           ``("element", "charge")``.
+    :type node_attr_keys: Sequence[str] | None, optional
+    :param edge_attr_keys: Sequence of edge attribute keys to respect in the automorphism
+                           computation. Defaults to ``("order",)``.
+    :type edge_attr_keys: Sequence[str] | None, optional
+    :param anchor_largest_component: If ``True`` and the graph is disconnected, chooses the largest connected
+                                     component as an "anchor" to suppress automorphisms that swap isomorphic
+                                     components. Defaults to ``True``.
+    :type anchor_largest_component: bool, optional
+    """
+
+    _DEF_NODE_ATTRS: Tuple[str, ...] = ("element", "charge")
+    _DEF_EDGE_ATTRS: Tuple[str, ...] = ("order",)
+
+    def __init__(
+        self,
+        graph: nx.Graph,
+        node_attr_keys: Optional[Sequence[str]] = None,
+        edge_attr_keys: Optional[Sequence[str]] = None,
+        *,
+        anchor_largest_component: bool = True,
+    ) -> None:
+        self._graph: nx.Graph = graph
+        self._nkeys: Tuple[str, ...] = (
+            tuple(node_attr_keys)
+            if node_attr_keys is not None
+            else self._DEF_NODE_ATTRS
+        )
+        self._ekeys: Tuple[str, ...] = (
+            tuple(edge_attr_keys)
+            if edge_attr_keys is not None
+            else self._DEF_EDGE_ATTRS
+        )
+        self._anchor_largest: bool = bool(anchor_largest_component)
+
+        self._orbits: Optional[List[frozenset[NodeId]]] = None
+        self._n_automorphisms: Optional[int] = None
+        self._orbit_index: Optional[Dict[NodeId, int]] = None
+        self._components: Optional[List[frozenset[NodeId]]] = None
+        self._anchor_component: Optional[frozenset[NodeId]] = None
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+    @property
+    def orbits(self) -> List[frozenset[NodeId]]:
+        """Node-orbits of the graph under its automorphism group.
+
+        :return: Orbits, computed lazily and cached.
+        :rtype: list[frozenset[NodeId]]
+        """
+        if self._orbits is None:
+            self._analyze()
+        return self._orbits  # type: ignore[return-value]
+
+    @property
+    def n_automorphisms(self) -> int:
+        """Number of automorphisms of the host graph.
+
+        :return: Group order (at least 1).
+        :rtype: int
+        """
+        if self._n_automorphisms is None:
+            self._analyze()
+        return int(self._n_automorphisms)  # type: ignore[return-value]
+
+    # ------------------------------------------------------------------
+    # Connected / disconnected handling
+    # ------------------------------------------------------------------
+    @property
+    def is_connected(self) -> bool:
+        """Whether the host graph is connected (weakly for directed graphs).
+
+        :return: ``True`` if connected or has 0/1 nodes, else ``False``.
+        :rtype: bool
+        """
+        n = self._graph.number_of_nodes()
+        if n <= 1:
+            return True
+        return len(self.components) == 1
+
+    @property
+    def components(self) -> List[frozenset[NodeId]]:
+        """Connected components (weakly for directed graphs).
+
+        :return: Components as frozensets of node IDs.
+        :rtype: list[frozenset[NodeId]]
+        """
+        if self._components is None:
+            self._components = self._compute_components()
+        return self._components
+
+    @property
+    def anchor_component(self) -> Optional[frozenset[NodeId]]:
+        """Anchor component used for disconnected graphs.
+
+        :return: Anchor component node-set, or ``None`` if graph is connected.
+        :rtype: frozenset[NodeId] | None
+        """
+        if self._orbits is None:
+            self._analyze()
+        return self._anchor_component
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+    def _compute_components(self) -> List[frozenset[NodeId]]:
+        if self._graph.number_of_nodes() == 0:
+            return []
+        if self._graph.is_directed():
+            comps: Iterable[Iterable[NodeId]] = nx.weakly_connected_components(self._graph)  # type: ignore[arg-type]
+        else:
+            comps = nx.connected_components(self._graph)  # type: ignore[arg-type]
+        return [frozenset(c) for c in comps]
+
+    def _node_defaults(self) -> List[object]:
+        defaults: List[object] = []
+        for k in self._nkeys:
+            defaults.append(0 if k == "charge" else "*")
+        return defaults
+
+    def _edge_defaults(self) -> List[object]:
+        return [1.0 for _ in self._ekeys]
+
+    def _make_matcher(self, g: nx.Graph) -> GraphMatcher:
+        if g.is_multigraph():
+            matcher_cls = (
+                nx.algorithms.isomorphism.MultiDiGraphMatcher
+                if g.is_directed()
+                else nx.algorithms.isomorphism.MultiGraphMatcher
+            )
+            edge_match = categorical_multiedge_match(
+                self._ekeys,
+                self._edge_defaults(),
+            )
+        else:
+            matcher_cls = (
+                nx.algorithms.isomorphism.DiGraphMatcher
+                if g.is_directed()
+                else GraphMatcher
+            )
+            edge_match = categorical_edge_match(
+                self._ekeys,
+                self._edge_defaults(),
+            )
+        return matcher_cls(
+            g,
+            g,
+            node_match=categorical_node_match(self._nkeys, self._node_defaults()),
+            edge_match=edge_match,
+        )
+
+    def _analyze_component(self, g: nx.Graph) -> Tuple[List[frozenset[NodeId]], int]:
+        if g.number_of_nodes() == 0:
+            return ([], 1)
+        if g.number_of_nodes() == 1:
+            node = next(iter(g.nodes))
+            return ([frozenset({node})], 1)
+
+        gm = self._make_matcher(g)
+
+        orbit_sets: Dict[NodeId, set[NodeId]] = defaultdict(set)
+        n_aut = 0
+
+        for auto in gm.isomorphisms_iter():
+            n_aut += 1
+            for u, v in auto.items():
+                orbit_sets[u].add(v)
+                orbit_sets[v].add(u)
+
+        if not orbit_sets:
+            return ([frozenset({n}) for n in g.nodes], 1)
+
+        unique_orbits = {frozenset(nodes) for nodes in orbit_sets.values()}
+        return (list(unique_orbits), n_aut if n_aut > 0 else 1)
+
+    def _choose_anchor(
+        self, comps: List[frozenset[NodeId]]
+    ) -> Optional[frozenset[NodeId]]:
+        if len(comps) <= 1 or not self._anchor_largest:
+            return None
+        return max(comps, key=len)
+
+    def _sorted_orbits(
+        self, orbits: List[frozenset[NodeId]]
+    ) -> List[frozenset[NodeId]]:
+        def _key(o: frozenset[NodeId]) -> Tuple[int, str]:
+            return (len(o), "|".join(sorted((repr(x) for x in o))))
+
+        return sorted(orbits, key=_key)
+
+    def _analyze(self) -> None:
+        comps = self.components
+
+        if self._graph.number_of_nodes() == 0:
+            self._orbits = []
+            self._n_automorphisms = 1
+            self._anchor_component = None
+            return
+
+        if len(comps) <= 1:
+            orbits, n_aut = self._analyze_component(self._graph)
+            self._orbits = self._sorted_orbits(orbits)
+            self._n_automorphisms = n_aut
+            self._anchor_component = None
+            return
+
+        # Disconnected: anchor largest component; compute per-component autos
+        self._anchor_component = self._choose_anchor(comps)
+
+        all_orbits: List[frozenset[NodeId]] = []
+        total_aut = 1
+
+        for comp in comps:
+            sub = self._graph.subgraph(comp).copy()
+            orbits, n_aut = self._analyze_component(sub)
+            all_orbits.extend(orbits)
+            total_aut *= int(n_aut)
+
+        self._orbits = self._sorted_orbits(list({frozenset(o) for o in all_orbits}))
+        self._n_automorphisms = int(total_aut) if total_aut > 0 else 1
+
+    def _get_orbit_index(self) -> Dict[NodeId, int]:
+        if self._orbit_index is None:
+            self._orbit_index = {
+                node: idx for idx, orb in enumerate(self.orbits) for node in orb
+            }
+        return self._orbit_index
+
+    # ------------------------------------------------------------------
+    # Dunder methods
+    # ------------------------------------------------------------------
+    def __len__(self) -> int:
+        return len(self.orbits)
+
+    def __repr__(self) -> str:
+        n_nodes = self._graph.number_of_nodes()
+        conn = "connected" if self.is_connected else "disconnected"
+        n_comp = len(self.components)
+        n_orb = len(self.orbits) if self._orbits is not None else "?"
+        n_aut = self._n_automorphisms if self._n_automorphisms is not None else "?"
+        return (
+            f"<Automorphism | {conn} nodes={n_nodes} comps={n_comp} "
+            f"orbits={n_orb} automorphisms={n_aut}>"
+        )

synkit/Graph/Matcher/batch_cluster.py

@@ -0,0 +1,224 @@
+from operator import eq
+from typing import List, Dict, Any, Tuple, Optional, Callable
+from networkx.algorithms.isomorphism import generic_node_match, generic_edge_match
+from synkit.Utils.utils import stratified_random_sample
+from synkit.Rule.Modify.rule_utils import strip_context
+from synkit.Graph.Matcher.graph_cluster import GraphCluster, _as_native_graph
+from synkit.Graph.Matcher.graph_morphism import graph_isomorphism
+
+
+class BatchCluster:
+    def __init__(
+        self,
+        node_label_names: List[str] = ["element", "charge"],
+        node_label_default: List[Any] = ["*", 0],
+        edge_attribute: str = "order",
+        backend: str = "nx",
+    ):
+        """Initializes an AutoCat instance which uses isomorphism checks for
+        categorizing new graphs or rules.
+
+        :param node_label_names: Names of the node attributes to use in
+                                 isomorphism checks.
+        :type node_label_names: List[str]
+        :param node_label_default: Default values for node attributes if they are
+                                   missing in the graph data.
+        :type node_label_default: List[Any]
+        :param edge_attribute: The edge attribute to consider when checking isomorphism
+                               between graphs.
+        :type edge_attribute: str
+
+        :raises ValueError: If the lengths of `node_label_names` and `node_label_default` do not match.
+        """
+        self.backend = backend.lower()
+        if self.backend != "nx":
+            raise ValueError(f"Unsupported backend: {backend!r}")
+        if len(node_label_names) != len(node_label_default):
+            raise ValueError(
+                "The lengths of `node_label_names` and `node_label_default` must match."
+            )
+        if backend == "nx":
+            self.nodeLabelNames = node_label_names
+            self.nodeLabelDefault = node_label_default
+            self.edgeAttribute = edge_attribute
+            self.nodeMatch = generic_node_match(
+                self.nodeLabelNames, self.nodeLabelDefault, [eq] * len(node_label_names)
+            )
+            self.edgeMatch = generic_edge_match(edge_attribute, 1, eq)
+
+    def available_backends(self) -> List[str]:
+        """Return the native matching backend."""
+        return ["nx"]
+
+    def lib_check(
+        self,
+        data: Dict,
+        templates: List[Dict],
+        rule_key: str = "gml",
+        attribute_key: str = "signature",
+        nodeMatch: Optional[Callable] = None,
+        edgeMatch: Optional[Callable] = None,
+    ) -> Dict:
+        """Checks and classifies a graph or rule based on existing templates
+        using either graph or rule isomorphism.
+
+        :param data: A dictionary representing a graph or rule with its attributes and
+                     classification.
+        :type data: Dict
+        :param templates: Dynamic templates used for categorization. If None, initializes to an empty list.
+        :type templates: List[Dict]
+        :param rule_key: Key to access the graph or rule data within the dictionary.
+        :type rule_key: str
+        :param attribute_key: An attribute used to filter templates before isomorphism check.
+        :type attribute_key: str
+        :param nodeMatch: A function to match nodes, defaults to a predefined generic_node_match.
+        :type nodeMatch: Optional[Callable]
+        :param edgeMatch: A function to match edges, defaults to a predefined generic_edge_match.
+        :type edgeMatch: Optional[Callable]
+
+        :return: The updated dictionary with its classification.
+        :rtype: Dict
+        """
+        # Ensure that templates are not None
+        if templates is None:
+            templates = []
+
+        att = data.get(attribute_key)
+        sub_temp = [temp for temp in templates if temp.get(attribute_key) == att]
+
+        for template in sub_temp:
+            template_data = (
+                strip_context(template[rule_key])
+                if isinstance(template[rule_key], str)
+                else template[rule_key]
+            )
+            data_rule = (
+                strip_context(data[rule_key])
+                if isinstance(data[rule_key], str)
+                else data[rule_key]
+            )
+
+            if graph_isomorphism(
+                _as_native_graph(template_data),
+                _as_native_graph(data_rule),
+                nodeMatch or self.nodeMatch,
+                edgeMatch or self.edgeMatch,
+            ):
+                data["class"] = template["class"]
+                break
+        else:
+            new_class = max((temp["class"] for temp in templates), default=-1) + 1
+            data["class"] = new_class
+            templates.append(data.copy())  # Append a copy to avoid reference issues
+
+        return data, templates
+
+    @staticmethod
+    def batch_dicts(input_list, batch_size):
+        """Splits a list of dictionaries into batches of a specified size.
+
+        :param input_list: The list of dictionaries to be batched.
+        :type input_list: list of dict
+        :param batch_size: The size of each batch.
+        :type batch_size: int
+
+        :return: A list where each element is a batch (sublist) of dictionaries.
+        :rtype: list of list of dict
+
+        :raises ValueError: If batch_size is less than 1.
+        """
+
+        # Validate batch_size to ensure it's a positive integer
+        if batch_size < 1:
+            raise ValueError("batch_size must be at least 1")
+
+        # Initialize an empty list to hold the batches
+        batches = []
+
+        # Iterate over the input list in steps of batch_size
+        for i in range(0, len(input_list), batch_size):
+            # Append a batch slice to the batches list
+            # fmt: off
+            batches.append(input_list[i: i + batch_size])
+            # fmt: on
+
+        return batches
+
+    def cluster(
+        self,
+        data: List[Dict],
+        templates: List[Dict],
+        rule_key: str = "gml",
+        attribute_key: str = "WLHash",
+    ) -> Tuple[List[Dict], List[Dict]]:
+        """Processes a list of graph data entries, classifying each based on
+        existing templates.
+
+        :param data: A list of dictionaries, each representing a graph or rule
+                     to be classified.
+        :type data: List[Dict]
+        :param templates: Dynamic templates used for categorization.
+        :type templates: List[Dict]
+
+        :return: A tuple containing the list of classified data and the updated templates.
+        :rtype: Tuple[List[Dict], List[Dict]]
+        """
+        for entry in data:
+            _, templates = self.lib_check(entry, templates, rule_key, attribute_key)
+        return data, templates
+
+    def fit(
+        self,
+        data: List[Dict],
+        templates: List[Dict],
+        rule_key: str = "gml",
+        attribute_key: str = "WLHash",
+        batch_size: Optional[int] = None,
+    ) -> Tuple[List[Dict], List[Dict]]:
+        """Processes and classifies data in batches. Uses GraphCluster for
+        initial processing and a stratified sampling technique to update
+        templates if there is only one batch and no initial templates are
+        provided.
+
+        :param data: Data to process.
+        :type data: List[Dict]
+        :param templates: Templates for categorization.
+        :type templates: List[Dict]
+        :param rule_key: Key to access rule or graph data.
+        :type rule_key: str
+        :param attribute_key: Key to access attributes used for filtering.
+        :type attribute_key: str
+        :param batch_size: Size of batches for processing, if not provided, processes all data at once.
+        :type batch_size: Optional[int]
+
+        :return: The processed data and the potentially updated templates.
+        :rtype: Tuple[List[Dict], List[Dict]]
+        """
+        if batch_size is not None:
+            batches = self.batch_dicts(data, batch_size)
+        else:
+            batches = [data]  # Process all at once if no batch size provided
+
+        output_data, output_templates = [], templates if templates is not None else []
+        graph_cluster = GraphCluster()
+
+        if len(batches) == 1:
+            batch = batches[0]
+            if not templates:
+                output_data = graph_cluster.fit(batch, rule_key, attribute_key)
+                output_templates = stratified_random_sample(
+                    output_data, property_key="class", samples_per_class=1, seed=1
+                )
+            else:
+                output_data, output_templates = self.cluster(
+                    batch, output_templates, rule_key, attribute_key
+                )
+        else:
+            for batch in batches:
+                processed_data, new_templates = self.cluster(
+                    batch, output_templates, rule_key, attribute_key
+                )
+                output_data.extend(processed_data)
+                output_templates = new_templates
+
+        return output_data, output_templates