synkit 1.6.5__py3-none-win_amd64.whl

synkit/Graph/Matcher/dedup_matches.py

@@ -0,0 +1,247 @@
+from __future__ import annotations
+
+from typing import Callable, Dict, FrozenSet, Iterable, List, Optional, Tuple
+
+Sig = Tuple[Tuple, Tuple]
+
+
+def _build_host_orbit_index(
+    host_orbits: Iterable[FrozenSet[int]],
+) -> Dict[int, int]:
+    """Build host node -> host orbit index.
+
+    :param host_orbits:
+        Iterable of host orbits.
+    :return:
+        Dict mapping host node to orbit index.
+    """
+    host_orbit_index: Dict[int, int] = {}
+    for idx, orb in enumerate(host_orbits):
+        for h in orb:
+            host_orbit_index[h] = idx
+    return host_orbit_index
+
+
+def _make_host_repr(
+    host_orbits: Optional[Iterable[FrozenSet[int]]],
+) -> Callable[[int], int]:
+    """Create a function that maps host node to its representative.
+
+    If host orbits are provided, the representative is the host-orbit index.
+    This is sound only for a one-node mapping; callers with joint mappings
+    must supply the identity representation instead.
+
+    :param host_orbits:
+        Host orbits or None.
+    :return:
+        Callable mapping host node -> representative integer.
+    :raises ValueError:
+        If host orbits are provided but a host node is not covered.
+    """
+    if host_orbits is None:
+        return lambda h: h
+
+    host_orbit_index = _build_host_orbit_index(host_orbits)
+
+    def _repr(h: int) -> int:
+        try:
+            return host_orbit_index[h]
+        except KeyError as exc:
+            raise ValueError(
+                f"Host node {h} not present in host_orbits; cannot canonicalize."
+            ) from exc
+
+    return _repr
+
+
+def _prepare_pattern_orbits(
+    pattern_orbits: Optional[Iterable[FrozenSet[int]]],
+    pattern_anchor: FrozenSet[int],
+) -> Tuple[List[Tuple[int, ...]], Tuple[int, ...]]:
+    """Prepare free pattern orbits and anchored nodes.
+
+    :param pattern_orbits:
+        Pattern orbits or None.
+    :param pattern_anchor:
+        Anchor nodes of the pattern.
+    :return:
+        (free_pattern_orbits, anchored_pattern_nodes)
+    """
+    if pattern_orbits is None:
+        return ([], ())
+
+    orbits_sorted = [tuple(sorted(o, key=repr)) for o in pattern_orbits]
+    free_orbits = [o for o in orbits_sorted if not set(o) & pattern_anchor]
+    anchored_nodes = tuple(sorted(pattern_anchor, key=repr))
+    return (free_orbits, anchored_nodes)
+
+
+def _free_sig_from_pattern_orbits(
+    mapping: Dict[int, int],
+    free_pattern_orbits: List[Tuple[int, ...]],
+    host_repr: Callable[[int], int],
+) -> Tuple:
+    """Compute free signature using pattern orbits (partial-match safe).
+
+    Each orbit contributes a pair:
+        (present_pattern_nodes_sorted, sorted(host_repr(images)))
+
+    :param mapping:
+        Pattern -> host mapping.
+    :param free_pattern_orbits:
+        Pattern orbits disjoint from anchor.
+    :param host_repr:
+        Host representative function.
+    :return:
+        Free signature tuple.
+    """
+    if not free_pattern_orbits:
+        return ()
+
+    m_keys = set(mapping.keys())
+    parts: List[Tuple[Tuple[int, ...], Tuple[int, ...]]] = []
+
+    for orbit in free_pattern_orbits:
+        present = [p for p in orbit if p in m_keys]
+        if not present:
+            continue
+
+        present_sorted = tuple(sorted(present, key=repr))
+        image = tuple(sorted((host_repr(mapping[p]) for p in present_sorted), key=repr))
+        parts.append((present_sorted, image))
+
+    return tuple(parts)
+
+
+def _free_sig_host_only(
+    mapping: Dict[int, int],
+    host_repr: Callable[[int], int],
+) -> Tuple:
+    """Compute free signature using host-only symmetry (mapping values only).
+
+    :param mapping:
+        Pattern -> host mapping.
+    :param host_repr:
+        Host representative function.
+    :return:
+        Free signature tuple.
+    """
+    return (tuple(sorted((host_repr(h) for h in mapping.values()), key=repr)),)
+
+
+def _anchor_sig(
+    mapping: Dict[int, int],
+    anchored_pattern_nodes: Tuple[int, ...],
+) -> Tuple:
+    """Compute anchor signature: exact placement for anchored pattern nodes
+    that are present in the mapping.
+
+    Returned as (pattern_node, host_node) pairs for stability.
+
+    :param mapping:
+        Pattern -> host mapping.
+    :param anchored_pattern_nodes:
+        Sorted anchored pattern nodes.
+    :return:
+        Anchor signature tuple.
+    """
+    if not anchored_pattern_nodes:
+        return ()
+
+    present = [p for p in anchored_pattern_nodes if p in mapping]
+    return tuple((p, mapping[p]) for p in present)
+
+
+def deduplicate_matches_with_anchor(
+    matches: Iterable[Dict[int, int]],
+    *,
+    pattern_orbits: Optional[Iterable[FrozenSet[int]]] = None,
+    pattern_anchor: Optional[FrozenSet[int]] = None,
+    host_orbits: Optional[Iterable[FrozenSet[int]]] = None,
+    host_anchor: Optional[FrozenSet[int]] = None,
+) -> List[Dict[int, int]]:
+    """Deduplicate pattern→host matches with optional anchor-aware symmetry
+    breaking on both pattern and host sides.
+
+    This function supports *partial* mappings. Orbit partitions are sufficient
+    to quotient singleton mappings only; joint mappings are returned unchanged
+    because their equivalence requires complete automorphism group elements.
+
+    Rules
+    -----
+    - Matches are always interpreted as **pattern → host** mappings.
+    - For singleton mappings, if ``pattern_orbits`` is provided:
+        * Pattern nodes inside ``pattern_anchor`` are fixed when present.
+        * Pattern orbits disjoint from the anchor are deduplicated up to
+          permutation.
+    - If ``pattern_orbits`` is None and ``host_orbits`` is provided:
+        * A one-node mapping may be deduplicated by its host vertex orbit.
+        * Joint mappings remain distinct because vertex orbits do not encode
+          the simultaneous action of the host automorphism group.
+    - Joint mappings, or mappings with both orbit arguments absent, are
+      returned unchanged.
+
+    :param matches:
+        Iterable of pattern → host mapping dictionaries.
+    :param pattern_orbits:
+        Automorphism orbits of the pattern graph (optional).
+    :param pattern_anchor:
+        Anchor component of the pattern graph (optional).
+    :param host_orbits:
+        Automorphism orbits of the host graph (optional).
+    :param host_anchor:
+        Anchor component of the host graph (optional). Kept for API symmetry;
+        host anchoring is handled indirectly by orbit collapsing.
+    :return:
+        Deduplicated list of pattern → host mappings, preserving input order.
+    :raises ValueError:
+        If ``host_orbits`` is provided but a mapping contains a host node not
+        covered by any host orbit.
+    """
+    # Reserved for API compatibility.
+    _ = host_anchor
+
+    if pattern_orbits is None and host_orbits is None:
+        return list(matches)
+
+    pattern_anchor = pattern_anchor or frozenset()
+    mappings = list(matches)
+    joint_mapping = any(len(mapping) > 1 for mapping in mappings)
+    if joint_mapping:
+        # Vertex orbits describe where one vertex may move. They do not encode
+        # which simultaneous permutations across one or several orbits belong
+        # to the same group element. A joint quotient needs the complete group
+        # action, not only its orbit partition.
+        return mappings
+    host_repr = _make_host_repr(None if joint_mapping else host_orbits)
+
+    free_pattern_orbits, anchored_pattern_nodes = _prepare_pattern_orbits(
+        pattern_orbits,
+        pattern_anchor,
+    )
+
+    use_pattern = bool(free_pattern_orbits) or bool(anchored_pattern_nodes)
+    seen: set[Sig] = set()
+    unique: List[Dict[int, int]] = []
+
+    for m in mappings:
+        if use_pattern:
+            free_sig = _free_sig_from_pattern_orbits(
+                m,
+                free_pattern_orbits,
+                host_repr,
+            )
+        else:
+            # host-only symmetry case
+            free_sig = _free_sig_host_only(m, host_repr)
+
+        anchor_part = _anchor_sig(m, anchored_pattern_nodes)
+        sig: Sig = (free_sig, anchor_part)
+
+        if sig in seen:
+            continue
+
+        seen.add(sig)
+        unique.append(m)
+
+    return unique

synkit/Graph/Matcher/graph_cluster.py

@@ -0,0 +1,191 @@
+import networkx as nx
+from operator import eq
+from collections import OrderedDict
+from typing import List, Set, Dict, Any, Tuple, Optional, Callable, Mapping
+from networkx.algorithms.isomorphism import generic_node_match, generic_edge_match
+
+from synkit.Rule.Modify.rule_utils import strip_context
+from synkit.Graph.Stereo.matching import stereo_isomorphic
+from synkit.IO.gml_to_nx import GMLToNX
+
+
+def _match_all(_left: Mapping[str, Any], _right: Mapping[str, Any]) -> bool:
+    """Implement NetworkX's no-attribute-matcher semantics explicitly."""
+    return True
+
+
+def _as_native_graph(rule: Any) -> nx.Graph:
+    """Return a native ITS graph from a graph or serialized GML rule."""
+    if isinstance(rule, nx.Graph):
+        return rule
+    if isinstance(rule, str):
+        return GMLToNX(rule).transform()[2]
+    raise TypeError("Rules must be NetworkX graphs or GML strings.")
+
+
+class GraphCluster:
+    def __init__(
+        self,
+        node_label_names: List[str] = ["element", "charge"],
+        node_label_default: List[Any] = ["*", 0],
+        edge_attribute: str = "order",
+        backend: str = "nx",
+    ):
+        """Initializes the GraphCluster with customization options for node and
+        edge matching functions. This class is designed to facilitate
+        clustering of graph nodes and edges based on specified attributes and
+        their matching criteria.
+
+        :param node_label_names: A list of node attribute names to be considered
+                                 for matching. Each attribute name corresponds to a property of the nodes in the
+                                 graph. Default values provided.
+        :type node_label_names: List[str]
+        :param node_label_default: Default values for each of the node attributes
+                                   specified in `node_label_names`. These are used where node attributes are missing.
+                                   The length and order of this list should match `node_label_names`.
+        :type node_label_default: List[Any]
+        :param edge_attribute: The name of the edge attribute to consider for matching
+                               edges. This attribute is used to assess edge similarity.
+        :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."
+            )
+        self.nodeLabelNames = node_label_names
+        self.nodeLabelDefault = node_label_default
+        self.edgeAttribute = edge_attribute
+        self.nodeMatch = generic_node_match(
+            self.nodeLabelNames,
+            self.nodeLabelDefault,
+            [eq for _ in node_label_names],
+        )
+        self.edgeMatch = generic_edge_match(self.edgeAttribute, 1, eq)
+
+    def available_backends(self) -> List[str]:
+        """Return the native matching backend."""
+        return ["nx"]
+
+    def iterative_cluster(
+        self,
+        rules: List[Any],
+        attributes: Optional[List[Any]] = None,
+        nodeMatch: Optional[Callable] = None,
+        edgeMatch: Optional[Callable] = None,
+    ) -> Tuple[List[Set[int]], Dict[int, int]]:
+        """Clusters rules based on their similarities, which could include
+        structural or attribute-based similarities depending on the given
+        attributes.
+
+        :param rules: List of rules, potentially serialized strings of rule
+                      representations.
+        :type rules: List[str]
+        :param attributes: Attributes associated with each rule for
+                           preliminary comparison, e.g., labels or properties.
+        :type attributes: Optional[List[Any]]
+
+        :return: Rule-index clusters and a mapping from each rule index to its
+                 cluster index.
+        :rtype: Tuple[List[Set[int]], Dict[int, int]]
+        """
+        native_rules = [_as_native_graph(rule) for rule in rules]
+
+        if attributes is None:
+            attributes_sorted = [1] * len(rules)
+        else:
+            if len(attributes) != len(rules):
+                raise ValueError("attributes must have the same length as rules")
+            attributes_sorted = []
+            for value in attributes:
+                if isinstance(value, OrderedDict):
+                    value = OrderedDict(sorted(value.items(), key=repr))
+                elif isinstance(value, (list, tuple, set, frozenset)):
+                    value = tuple(sorted(value, key=repr))
+                attributes_sorted.append(value)
+
+        visited = set()
+        clusters = []
+        rule_to_cluster = {}
+
+        for i, rule_i in enumerate(native_rules):
+            if i in visited:
+                continue
+            cluster = {i}
+            visited.add(i)
+            rule_to_cluster[i] = len(clusters)
+            # fmt: off
+            for j, rule_j in enumerate(native_rules[i + 1:], start=i + 1):
+                # fmt: on
+                if attributes_sorted[i] == attributes_sorted[j] and j not in visited:
+                    # ``stereo_isomorphic`` has chemistry-aware defaults,
+                    # whereas this API defines ``None`` as matching every node
+                    # or edge attribute. Preserve that contract while layering
+                    # exact stereo-registry comparison over each candidate.
+                    is_isomorphic = stereo_isomorphic(
+                        rule_i,
+                        rule_j,
+                        node_match=nodeMatch or _match_all,
+                        edge_match=edgeMatch or _match_all,
+                    )
+
+                    if is_isomorphic:
+                        cluster.add(j)
+                        visited.add(j)
+                        rule_to_cluster[j] = len(clusters)
+
+            clusters.append(cluster)
+
+        return clusters, rule_to_cluster
+
+    def fit(
+        self,
+        data: List[Dict],
+        rule_key: str = "gml",
+        attribute_key: str = "WLHash",
+        strip: bool = False,
+    ) -> List[Dict]:
+        """Automatically clusters the rules and assigns them cluster indices
+        based on the similarity, potentially using provided templates for
+        clustering, or generating new templates.
+
+        :param data: A list containing dictionaries, each representing a
+                     rule along with metadata.
+        :type data: List[Dict]
+        :param rule_key: The key in the dictionaries under `data` where the rule data
+                         is stored.
+        :type rule_key: str
+        :param attribute_key: The key in the dictionaries under `data` where rule
+                              attributes are stored.
+        :type attribute_key: str
+
+        :return: Updated list of dictionaries with an added 'class' key for cluster identification.
+        :rtype: List[Dict]
+        """
+        if not data:
+            return data
+        if isinstance(data[0][rule_key], str):
+            if strip:
+                rules = [strip_context(entry[rule_key]) for entry in data]
+            else:
+                rules = [entry[rule_key] for entry in data]
+
+        else:
+            rules = [entry[rule_key] for entry in data]
+
+        attributes = (
+            [entry.get(attribute_key) for entry in data] if attribute_key else None
+        )
+        _, rule_to_cluster_dict = self.iterative_cluster(
+            rules, attributes, self.nodeMatch, self.edgeMatch
+        )
+
+        for index, entry in enumerate(data):
+            entry["class"] = rule_to_cluster_dict.get(index, None)
+
+        return data