synkit 1.6.5__py3-none-win_amd64.whl

synkit/Chem/Mapper/graph/automorphism.py

@@ -0,0 +1,395 @@
+"""
+Automorphism orbits of a labeled graph (thin wrapper over synkit).
+
+Two atoms are *symmetry-equivalent* when some automorphism of the molecular graph
+maps one to the other; the set of atoms reachable from a given atom under the
+automorphism group is its *orbit*. Branching the exact search over one
+representative per orbit (orbital branching, :mod:`mapper.exact.branching`) avoids
+exploring assignments that are equivalent by symmetry, and orbits also drive
+symmetry-distinct optimum enumeration (:mod:`mapper.exact.enumerate`).
+
+This module converts a :class:`~mapper.graph.labeled_graph.LabeledGraph` into a
+``networkx`` graph (node attribute ``element`` = atomic number, edge attribute
+``order`` = bond order) and asks
+:class:`synkit.Graph.Matcher.automorphism.Automorphism` for the orbits over the
+*whole* graph (all connected components). If automorphism analysis fails,
+:func:`node_orbits` falls back to the discrete partition, which simply disables
+symmetry pruning without affecting correctness.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import time
+
+import networkx as nx
+import numpy as np
+from typing import Dict, List, FrozenSet
+
+from synkit.Graph.Canon import ExactCanonicalResult, ExactColoredGraphCanonicalizer
+from synkit.Graph.Matcher.automorphism import Automorphism
+
+from .synkit_adapter import graph_to_nx
+
+_MAX_ORBIT_NODES = 48
+
+
+def _atomic_numbers(lg):
+    nums = lg.props.get("atomic numbers")
+    if nums is None:
+        nums = list(lg.labels)
+    return list(nums)
+
+
+def _objective_graph_data(lg, binary=False, node_properties=()):
+    """Return the exact matrix/element data used by chemical distance."""
+    n = len(lg.labels)
+    matrix = []
+    for source in range(n):
+        neighbours = lg.graph.get(source, {})
+        row = []
+        for target in range(n):
+            if source == target or target not in neighbours:
+                row.append(0.0)
+            else:
+                row.append(1.0 if binary else float(neighbours[target]))
+        matrix.append(tuple(row))
+    colors = []
+    atomic_numbers = _atomic_numbers(lg)
+    for index, atomic_number in enumerate(atomic_numbers):
+        extras = []
+        for name in node_properties:
+            values = lg.props.get(name)
+            if values is None or len(values) != n:
+                raise ValueError(
+                    f"symmetry node property {name!r} requires one value per atom"
+                )
+            extras.append(values[index])
+        colors.append((atomic_number, *extras) if extras else atomic_number)
+    return tuple(matrix), tuple(colors)
+
+
+def _objective_graph_digest(lg, binary=False, node_properties=()) -> str:
+    matrix, elements = _objective_graph_data(lg, binary, node_properties)
+    payload = repr(
+        (
+            tuple((type(value).__module__, type(value).__qualname__, repr(value)) for value in elements),
+            matrix,
+        )
+    ).encode("utf-8", "surrogatepass")
+    return hashlib.sha256(payload).hexdigest()
+
+
+def _is_exact_automorphism(permutation, matrix, elements) -> bool:
+    """Check a permutation against the exact chemical-distance input."""
+    n = len(elements)
+    if len(permutation) != n or sorted(permutation) != list(range(n)):
+        return False
+    if any(elements[index] != elements[permutation[index]] for index in range(n)):
+        return False
+    array = np.asarray(matrix)
+    return bool(np.array_equal(array, array[np.ix_(permutation, permutation)]))
+
+
+def to_nx(lg, binary=False, node_properties=()):
+    """Build a ``networkx.Graph`` from a labeled graph for automorphism analysis.
+
+    Nodes carry ``element`` (atomic number); edges carry ``order`` (bond order,
+    or ``1`` when ``binary``).
+    """
+    g = graph_to_nx(lg, binary=binary, include_label=False)
+    _, elements = _objective_graph_data(lg, binary, node_properties)
+    for i in range(len(lg.labels)):
+        g.nodes[i]["element"] = elements[i] if i < len(elements) else 0
+    return g
+
+
+def _discrete_orbits(n: int) -> List[FrozenSet[int]]:
+    return [frozenset({i}) for i in range(n)]
+
+
+def node_orbits(lg, binary=False) -> List[FrozenSet[int]]:
+    """Automorphism orbits of a labeled graph's atoms.
+
+    :param lg:
+    :type lg: LabeledGraph
+    :param binary: Whether bond orders are binarised.
+    :type binary: bool, optional
+
+    :return: The orbits (a partition of the atom indices). Without synkit, the
+              discrete partition (one atom per orbit) is returned.
+    :rtype: list[frozenset[int]]
+    """
+    n = len(lg.labels)
+    if n > _MAX_ORBIT_NODES:
+        return _discrete_orbits(n)
+    try:
+        g = to_nx(lg, binary=binary)
+        auto = Automorphism(
+            g,
+            node_attr_keys=["element"],
+            edge_attr_keys=["order"],
+            anchor_largest_component=False,
+        )
+        orbits = [frozenset(o) for o in auto.orbits]
+    except Exception:
+        return _discrete_orbits(n)
+    seen = set().union(*orbits) if orbits else set()
+    # Isolated atoms may be omitted by the backend; add them as singletons.
+    for i in range(n):
+        if i not in seen:
+            orbits.append(frozenset({i}))
+    return orbits
+
+
+def orbit_id_map(orbits) -> Dict[int, int]:
+    """Map each atom index to an integer orbit id."""
+    out = {}
+    for oid, orb in enumerate(orbits):
+        for i in orb:
+            out[i] = oid
+    return out
+
+
+def n_automorphisms(lg, binary=False) -> int:
+    """Size of the automorphism group."""
+    try:
+        g = to_nx(lg, binary=binary)
+        auto = Automorphism(
+            g,
+            node_attr_keys=["element"],
+            edge_attr_keys=["order"],
+            anchor_largest_component=False,
+        )
+        return int(auto.n_automorphisms)
+    except Exception:
+        return 1
+
+
+def _verified_twin_permutations(matrix, elements, limit):
+    """Recover a bounded subgroup from equal incoming and outgoing rows.
+
+    Adjacent transpositions within each nonadjacent-twin class generate its
+    full symmetric group. Check each witness against the complete objective.
+    """
+    n = len(elements)
+    identity = tuple(range(n))
+    classes = {}
+    for atom in range(n):
+        signature = (matrix[atom], tuple(row[atom] for row in matrix))
+        classes.setdefault(signature, []).append(atom)
+    permutations = [identity]
+    for atoms in classes.values():
+        # Colors may be comparable but not hashable.
+        color_classes = []
+        for atom in atoms:
+            for group in color_classes:
+                if elements[atom] == elements[group[0]]:
+                    group.append(atom)
+                    break
+            else:
+                color_classes.append([atom])
+        for group in color_classes:
+            for first, second in zip(group, group[1:]):
+                permutation = list(identity)
+                permutation[first], permutation[second] = second, first
+                permutation = tuple(permutation)
+                if _is_exact_automorphism(permutation, matrix, elements):
+                    permutations.append(permutation)
+                    if len(permutations) >= limit:
+                        return tuple(sorted(permutations))
+    return tuple(sorted(permutations))
+
+
+def _component_automorphism_permutations(  # noqa: C901
+    graph, matrix, elements, limit, timeout_seconds, max_search_nodes
+):
+    """Find component generators and equal-component swaps under shared budgets.
+
+    Equal canonical codes propose transports; full matrix verification is the
+    authority for every lifted witness. Retain compact generators instead of
+    expanding their often enormous direct-product group.
+    """
+    components = sorted(
+        (tuple(sorted(c)) for c in nx.connected_components(graph)),
+        key=lambda c: (len(c), c),
+    )
+    if len(components) <= 1:
+        return None
+    started = time.perf_counter()
+    identity = tuple(range(len(elements)))
+    permutations = {identity}
+    verification_matrix = np.asarray(matrix)
+    matches = {}
+    remaining_nodes = max_search_nodes
+    complete = True
+
+    def accept(permutation):
+        nonlocal complete
+        permutation = tuple(permutation)
+        if permutation in permutations:
+            return
+        if len(permutations) >= limit:
+            complete = False
+            return
+        if _is_exact_automorphism(permutation, verification_matrix, elements):
+            permutations.add(permutation)
+        else:
+            complete = False
+
+    for atoms in components:
+        remaining = timeout_seconds - (time.perf_counter() - started)
+        if remaining <= 0 or remaining_nodes <= 0 or len(permutations) >= limit:
+            complete = False
+            break
+        try:
+            result = ExactColoredGraphCanonicalizer(
+                graph.subgraph(atoms).copy(),
+                node_color="element",
+                edge_color="order",
+                prune_automorphisms=True,
+                enumerate_automorphism_group=False,
+            ).search(timeout_seconds=remaining, max_search_nodes=remaining_nodes)
+        except Exception:
+            complete = False
+            break
+        remaining_nodes -= result.statistics.visited_nodes
+        for witness in result.automorphisms:
+            permutation = list(identity)
+            for source, target in witness.as_dict().items():
+                permutation[source] = target
+            accept(permutation)
+        if not isinstance(result, ExactCanonicalResult):
+            complete = False
+            continue
+        previous = matches.get(result.canonical_code)
+        if previous is not None:
+            permutation = list(identity)
+            for first, second in zip(previous, result.canonical_order):
+                permutation[first], permutation[second] = second, first
+            accept(permutation)
+        # Adjacent component swaps generate all permutations of equal components.
+        matches[result.canonical_code] = result.canonical_order
+    if not complete:
+        for permutation in _verified_twin_permutations(matrix, elements, limit):
+            accept(permutation)
+    return tuple(sorted(permutations)), complete
+
+
+def bounded_automorphism_permutations(  # noqa: C901
+    lg,
+    binary=False,
+    *,
+    limit=256,
+    timeout_seconds=0.25,
+    max_search_nodes=10000,
+    node_properties=(),
+):
+    """Return bounded, exactly verified product-graph symmetries.
+
+    Disconnected graphs use component canonicalization under shared time/node
+    budgets, retaining compact internal generators and equal-component swaps.
+    Connected graphs use SynKit's bounded exact canonicalizer and a bounded
+    expansion of its generators. If a canonical search does not complete,
+    verified nonadjacent-twin transpositions recover a safe subgroup; absent
+    such witnesses the identity disables pruning. Every returned permutation
+    is a concrete automorphism; group completeness is not required for safety.
+
+    :param lg: Mapper labeled graph.
+    :param binary: Whether edge orders are binarized.
+    :param limit: Maximum number of returned permutations.
+    :param timeout_seconds: Canonical-search wall-time budget.
+    :param max_search_nodes: Canonical-search node budget.
+    :return: ``(permutations, canonical_search_complete)``.
+    """
+    if isinstance(limit, bool) or not isinstance(limit, int) or limit < 1:
+        raise ValueError("limit must be a positive integer")
+    node_properties = tuple(str(name) for name in node_properties)
+    n = len(lg.labels)
+    identity = tuple(range(n))
+    if n <= 1 or limit == 1:
+        return (identity,), n <= 1
+
+    cache_key = (
+        _objective_graph_digest(lg, binary, node_properties),
+        bool(binary),
+        node_properties,
+        int(limit),
+        float(timeout_seconds),
+        int(max_search_nodes),
+    )
+    cache = lg.props.setdefault("_bounded_automorphism_permutations", {})
+    if cache_key in cache:
+        return cache[cache_key]
+
+    graph = to_nx(lg, binary=binary, node_properties=node_properties)
+    matrix, elements = _objective_graph_data(lg, binary, node_properties)
+
+    def fallback():
+        outcome = (_verified_twin_permutations(matrix, elements, limit), False)
+        cache[cache_key] = outcome
+        return outcome
+
+    component_outcome = _component_automorphism_permutations(
+        graph, matrix, elements, limit, timeout_seconds, max_search_nodes
+    )
+    if component_outcome is not None:
+        cache[cache_key] = component_outcome
+        return component_outcome
+
+    try:
+        canonicalizer = ExactColoredGraphCanonicalizer(
+            graph,
+            node_color="element",
+            edge_color="order",
+            prune_automorphisms=True,
+            enumerate_automorphism_group=False,
+        )
+        result = canonicalizer.search(
+            timeout_seconds=timeout_seconds,
+            max_search_nodes=max_search_nodes,
+        )
+    except Exception:
+        return fallback()
+    if not isinstance(result, ExactCanonicalResult):
+        partial = set(_verified_twin_permutations(matrix, elements, limit))
+        for witness in result.automorphisms:
+            permutation = tuple(witness.as_dict()[index] for index in range(n))
+            if len(partial) >= limit:
+                break
+            if _is_exact_automorphism(permutation, matrix, elements):
+                partial.add(permutation)
+        outcome = (tuple(sorted(partial)), False)
+        cache[cache_key] = outcome
+        return outcome
+
+    generators = {
+        tuple(witness.as_dict()[index] for index in range(n))
+        for witness in result.automorphisms
+    }
+    generators.add(identity)
+    generators = {
+        permutation
+        for permutation in generators
+        if _is_exact_automorphism(permutation, matrix, elements)
+    }
+    permutations = set(generators)
+    frontier = list(sorted(generators))
+    while frontier and len(permutations) < limit:
+        right = frontier.pop(0)
+        for left in tuple(sorted(permutations)):
+            for composed in (
+                tuple(left[right[index]] for index in range(n)),
+                tuple(right[left[index]] for index in range(n)),
+            ):
+                if composed in permutations:
+                    continue
+                permutations.add(composed)
+                frontier.append(composed)
+                if len(permutations) >= limit:
+                    break
+            if len(permutations) >= limit:
+                break
+    outcome = (tuple(sorted(permutations)[:limit]), True)
+    cache[cache_key] = outcome
+    return outcome

synkit/Chem/Mapper/graph/blockcut.py

@@ -0,0 +1,98 @@
+"""
+Block-cut-tree decomposition of a labeled graph.
+
+A connected graph decomposes into *biconnected components* (blocks) joined at
+*articulation points* (cut vertices). Contracting each block to a node and
+linking it to its cut vertices yields the *block-cut tree*. Removing an
+articulation point disconnects the graph, so any matching/automorphism question
+factorises over this tree: the pieces interact only through the shared cut
+vertices.
+
+This module exposes the decomposition (:func:`block_cut_tree`) and a helper to
+locate which block(s) each atom belongs to (:func:`node_block_map`). The exact
+kernel solver uses them to split an uncertainty region that spans several
+independent blocks into per-block sub-problems, turning one ``O(k!)`` search into
+a sum of much smaller ones (see ``solve_kernel_blockwise`` in
+:mod:`mapper.exact.branching`).
+
+Built on :func:`networkx.biconnected_components` /
+:func:`networkx.articulation_points`.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Dict, FrozenSet, List, Set
+
+try:
+    import networkx as nx
+
+    HAS_NX = True
+except Exception:  # pragma: no cover
+    HAS_NX = False
+
+
+def _to_nx(graph, n):
+    g = nx.Graph()
+    g.add_nodes_from(range(n))
+    for i, nbrs in graph.items():
+        for j in nbrs:
+            if i != j:
+                g.add_edge(i, j)
+    return g
+
+
+@dataclass
+class BlockCutTree:
+    """Block-cut-tree decomposition.
+
+    :ivar blocks: Biconnected components (node sets). A bridge edge is a block of size 2.
+    :vartype blocks: list[frozenset[int]]
+    :ivar articulation_points: Cut vertices shared between blocks.
+    :vartype articulation_points: set[int]
+    :ivar tree: Bipartite block-cut tree with nodes ``("B", block_index)`` and
+                ``("C", cut_vertex)``.
+    :vartype tree: networkx.Graph
+    """
+
+    blocks: List[FrozenSet[int]]
+    articulation_points: Set[int]
+    tree: "nx.Graph"
+
+
+def block_cut_tree(graph, n):
+    """Compute the block-cut-tree decomposition of a labeled-graph adjacency dict.
+
+    :param graph: Adjacency (edge weights ignored).
+    :type graph: dict[int, dict[int, number]]
+    :param n: Number of nodes.
+    :type n: int
+
+    :rtype: BlockCutTree
+    """
+    if not HAS_NX:
+        raise ImportError("networkx is required for block-cut-tree decomposition")
+    g = _to_nx(graph, n)
+    blocks = [frozenset(b) for b in nx.biconnected_components(g)]
+    arts = set(nx.articulation_points(g))
+
+    tree = nx.Graph()
+    for bi, block in enumerate(blocks):
+        tree.add_node(("B", bi))
+        for v in block:
+            if v in arts:
+                tree.add_node(("C", v))
+                tree.add_edge(("B", bi), ("C", v))
+    return BlockCutTree(blocks=blocks, articulation_points=arts, tree=tree)
+
+
+def node_block_map(bct) -> Dict[int, List[int]]:
+    """Map each atom index to the list of block indices containing it.
+
+    Articulation points belong to several blocks; ordinary atoms to exactly one.
+    """
+    out: Dict[int, List[int]] = {}
+    for bi, block in enumerate(bct.blocks):
+        for v in block:
+            out.setdefault(v, []).append(bi)
+    return out

synkit/Chem/Mapper/graph/labeled_graph.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+from collections import defaultdict
+
+from .synkit_adapter import stable_int_token, synkit_wl_node_labels
+
+
+class LabeledGraph:
+    """Indexed graph with labels and metadata."""
+
+    SYNKIT_WL_NODE_LIMIT = 256
+
+    def __init__(self, graph, labels):
+        self.graph = self._normalise_graph(graph, len(labels))
+        self.labels = list(labels)
+        self.label2idxs = defaultdict(list)
+        self.props = {}
+        self.reindex_labels()
+
+        self._ini_labels = list(self.labels)
+        self._ini_wl_labels = None
+        self._irred_labels = {}
+
+    @staticmethod
+    def _normalise_graph(graph, n_nodes):
+        normalised = {idx: dict(graph.get(idx, {})) for idx in range(n_nodes)}
+        for src, nbrs in graph.items():
+            normalised.setdefault(src, {}).update(nbrs)
+        return normalised
+
+    def reindex_labels(self):
+        """Rebuild label -> indices."""
+        label_index = defaultdict(list)
+        for idx, label in enumerate(self.labels):
+            label_index[label].append(idx)
+        self.label2idxs = label_index
+
+    def build_label2idxs(self):
+        """Alias for reindex_labels."""
+        self.reindex_labels()
+
+    def copy(self):
+        """Copy graph state."""
+        clone = type(self).__new__(type(self))
+        clone.graph = {idx: dict(nbrs) for idx, nbrs in self.graph.items()}
+        clone.labels = list(self.labels)
+        clone.label2idxs = defaultdict(
+            list,
+            {label: list(idxs) for label, idxs in self.label2idxs.items()},
+        )
+        clone.props = self.props
+        clone._ini_labels = self._ini_labels
+        clone._ini_wl_labels = self._ini_wl_labels
+        clone._irred_labels = dict(self._irred_labels)
+        return clone
+
+    def set_prop(self, name, prop):
+        """Set metadata."""
+        self.props[name] = prop
+
+    def binarize_graph(self):
+        """Set all edge weights to 1."""
+        for nbrs in self.graph.values():
+            for nbr in list(nbrs):
+                nbrs[nbr] = 1
+
+    def neighborhood_signature(self, idx, labels=None, binary=False):
+        """WL neighborhood signature."""
+        labels = self.labels if labels is None else labels
+        grouped = defaultdict(list)
+        for nbr, weight in self.graph.get(idx, {}).items():
+            grouped[labels[nbr]].append(1 if binary else weight)
+        return (
+            labels[idx],
+            tuple(
+                sorted(
+                    (label, tuple(sorted(weights, reverse=True)))
+                    for label, weights in grouped.items()
+                )
+            ),
+        )
+
+    def one_wl_round(self, labels=None, binary=False):
+        """One deterministic WL round."""
+        labels = self.labels if labels is None else labels
+        return [
+            stable_int_token(self.neighborhood_signature(idx, labels, binary))
+            for idx in range(len(labels))
+        ]
+
+    def get_WL_labels(self):
+        """Stabilized WL colors."""
+        if len(self.labels) <= self.SYNKIT_WL_NODE_LIMIT:
+            synkit_labels = synkit_wl_node_labels(self)
+            if synkit_labels is not None:
+                return synkit_labels
+
+        colors = list(self.labels)
+        for _ in range(max(1, 2 * len(colors))):
+            refined = self.one_wl_round(colors)
+            if len(set(refined)) == len(set(colors)):
+                return colors
+            colors = refined
+        return colors