GASM-or 0.1.0__py3-none-any.whl

gasm/__init__.py

@@ -0,0 +1,36 @@
+"""GASM -- Graph Attributes and Structure Matching.
+
+A fast graph matching library implementing the GASM algorithm of Candelier,
+*Graph Matching Based on Similarities in Structure and Attributes*,
+Journal of Graph Algorithms and Applications 29(1), 289-320 (2025),
+with GPU (OpenCL) and CPU back-ends.
+
+Typical usage::
+
+    import gasm
+    M = gasm.match(G1, G2)
+    pairs = M.matchups
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .api import match
+from .attributes import Attribute
+from .matching import Matching
+from .metrics import accuracy, structural_quality
+
+try:
+    __version__ = version("GASM-or")
+except PackageNotFoundError:  # pragma: no cover - source checkout without install
+    __version__ = "0.1.0"
+
+__all__ = [
+    "match",
+    "Matching",
+    "Attribute",
+    "accuracy",
+    "structural_quality",
+    "__version__",
+]

gasm/api.py

@@ -0,0 +1,152 @@
+"""Public entry point: :func:`match`."""
+
+from __future__ import annotations
+
+import networkx as nx
+
+from . import attributes as attr_mod
+from . import lap as lap_registry
+from .cpu import core as cpu_core
+from .matching import Matching
+from .graph import from_networkx
+from .utils import AttributeWarning, PlatformWarning, warn
+
+
+def match(
+    G1,
+    G2,
+    *,
+    platform: str = "GPU",
+    attributes=None,
+    structure: bool = True,
+    complement: bool = True,
+    lap: str = "auto",
+    noise: float = 1e-10,
+    convergence: str = "adaptive",
+    tol: float = 1e-6,
+    patience: int = 2,
+    max_iterations: int | None = None,
+    normalize: bool = True,
+    match_on: str = "vertices",
+    return_scores: bool = False,
+    seed: int | None = None,
+) -> Matching:
+    """Match two graphs with the GASM algorithm.
+
+    Parameters
+    ----------
+    G1, G2:
+        The two graphs to match, as :class:`networkx.Graph` or
+        :class:`networkx.DiGraph`. Both must share the same directedness.
+    platform:
+        ``'GPU'`` (default) runs on OpenCL, falling back to the CPU with a
+        warning when no device is available; ``'CPU'`` forces the reference
+        implementation.
+    attributes:
+        ``None`` for a purely structural matching, or a list of
+        :class:`gasm.Attribute` (or equivalent dicts) describing the vertex and
+        edge attributes to use, each with its uncertainty ``rho``.
+    structure:
+        When ``False``, ignore the graph structure and match on attributes only.
+    complement:
+        Allow the complement procedure (eq. 18 / 26) for dense graphs. ``False``
+        always uses the original incidence matrices.
+    lap:
+        Linear assignment solver: ``'auto'``, ``'jv'`` (Jonker-Volgenant) or
+        ``'auction'``.
+    noise:
+        Amplitude ``eta`` of the symmetry-lifting noise (eq. 11). ``0`` disables
+        it.
+    convergence:
+        ``'adaptive'`` (early stopping) or ``'diameter'`` (fixed number of
+        iterations, eq. 30).
+    tol, patience:
+        Parameters of the adaptive convergence criterion.
+    max_iterations:
+        Hard cap on the number of iterations; defaults to ``min(diam_A, diam_B)``
+        (eq. 30).
+    normalize:
+        Apply the approximate normalization ``fx = 4 dA dB + 1`` (eq. S2).
+    match_on:
+        ``'vertices'`` (match on the vertex score matrix ``X``) or ``'edges'``
+        (match on the edge score matrix ``Y``).
+    return_scores:
+        For the GPU platform, transfer the score matrix immediately instead of
+        lazily. Ignored on the CPU, where scores are always available.
+    seed:
+        Seed for the noise generator, for reproducible matchings.
+
+    Returns
+    -------
+    Matching
+        The matching result.
+    """
+    if match_on not in ("vertices", "edges"):
+        raise ValueError("match_on must be 'vertices' or 'edges'.")
+    if platform not in ("GPU", "CPU"):
+        raise ValueError("platform must be 'GPU' or 'CPU'.")
+
+    if G1.is_directed() != G2.is_directed():
+        raise ValueError(
+            "Both graphs must share the same directedness "
+            "(both directed or both undirected)."
+        )
+    if G1.number_of_nodes() == 0 or G2.number_of_nodes() == 0:
+        raise ValueError("Both graphs must have at least one vertex.")
+
+    if not structure and not attributes:
+        warn(
+            "structure=False with no attributes: the matching has no information "
+            "to rely on and will be arbitrary.",
+            AttributeWarning,
+        )
+
+    ga = from_networkx(G1)
+    gb = from_networkx(G2)
+    V, E = attr_mod.build_matrices(attributes, ga, gb)
+
+    options = dict(
+        structure=structure,
+        complement=complement,
+        noise=noise,
+        convergence=convergence,
+        tol=tol,
+        patience=patience,
+        max_iterations=max_iterations,
+        normalize=normalize,
+        match_on=match_on,
+        seed=seed,
+    )
+
+    score_matrix = None
+    labels_a = labels_b = None
+    used_platform = platform
+
+    if platform == "GPU":
+        try:
+            from .gpu import core as gpu_core
+
+            score_matrix, labels_a, labels_b, _iters, _loader = gpu_core.run(
+                ga, gb, V, E, lap=lap, return_scores=return_scores, **options
+            )
+        except Exception as exc:  # pragma: no cover - depends on host OpenCL
+            warn(
+                "GPU platform unavailable "
+                f"({type(exc).__name__}: {exc}); falling back to the CPU.",
+                PlatformWarning,
+            )
+            used_platform = "CPU"
+
+    if used_platform == "CPU":
+        score_matrix, labels_a, labels_b, _iters = cpu_core.run(ga, gb, V, E, **options)
+
+    solver = lap_registry.get_cpu_solver(lap)
+    rows, cols = solver(score_matrix)
+    return Matching(
+        labels_a,
+        labels_b,
+        rows,
+        cols,
+        match_on=match_on,
+        score_matrix=score_matrix,
+    )

gasm/attributes.py

@@ -0,0 +1,176 @@
+"""Attribute handling for GASM (Section 3.2 of the reference article).
+
+Builds the vertex distance matrix ``V`` (eq. 9) and edge distance matrix ``E``
+(eq. 10) from user-specified attributes, each with an uncertainty parameter
+``rho``. Categorical attributes use eq. (6)-(7); measurable attributes use
+eq. (8).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+import numpy as np
+
+from .graph import Graph
+from .utils import AttributeWarning, warn
+
+
+@dataclass
+class Attribute:
+    """Specification of a graph attribute used for matching.
+
+    Parameters
+    ----------
+    name:
+        Key under which the attribute is stored in the networkx node or edge
+        data dictionaries.
+    on:
+        ``'vertex'`` or ``'edge'``.
+    kind:
+        ``'measurable'`` (a distance can be defined, eq. 8) or ``'categorical'``
+        (only equality is meaningful, eq. 6-7).
+    rho:
+        Uncertainty over the attribute values. A non-negative float, or
+        ``'auto'`` to use the standard deviation of all pairwise comparisons as
+        a safe upper bound.
+    """
+
+    name: str
+    on: Literal["vertex", "edge"]
+    kind: Literal["measurable", "categorical"] = "measurable"
+    rho: float | str = "auto"
+
+    def __post_init__(self):
+        if self.on not in ("vertex", "edge"):
+            raise ValueError("Attribute.on must be 'vertex' or 'edge'.")
+        if self.kind not in ("measurable", "categorical"):
+            raise ValueError(
+                "Attribute.kind must be 'measurable' or 'categorical'."
+            )
+        if not (self.rho == "auto" or (isinstance(self.rho, (int, float)) and self.rho >= 0)):
+            raise ValueError("Attribute.rho must be a non-negative float or 'auto'.")
+
+
+def _coerce(spec) -> Attribute:
+    if isinstance(spec, Attribute):
+        return spec
+    if isinstance(spec, dict):
+        return Attribute(**spec)
+    raise TypeError(
+        "Each attribute must be a gasm.Attribute or a dict, got "
+        f"{type(spec).__name__}."
+    )
+
+
+def _vertex_values(g: Graph, name: str):
+    missing = [v for v in g.nodes if name not in g._raw_node_data[v]]
+    if missing:
+        warn(
+            f"Vertex attribute '{name}' is missing on {len(missing)} vertices; "
+            "those comparisons are treated as dissimilar.",
+            AttributeWarning,
+        )
+    return [g._raw_node_data[v].get(name, _MISSING) for v in g.nodes]
+
+
+def _edge_values(g: Graph, name: str):
+    missing = [e for e in g.edges if name not in g._raw_edge_data[e]]
+    if missing:
+        warn(
+            f"Edge attribute '{name}' is missing on {len(missing)} edges; "
+            "those comparisons are treated as dissimilar.",
+            AttributeWarning,
+        )
+    return [g._raw_edge_data[e].get(name, _MISSING) for e in g.edges]
+
+
+class _Missing:
+    def __repr__(self):
+        return "<missing>"
+
+
+_MISSING = _Missing()
+
+
+def _measurable_matrix(va, vb, rho):
+    a = np.asarray(va, dtype=np.float64)[:, None]
+    b = np.asarray(vb, dtype=np.float64)[None, :]
+    diff = a - b
+    if rho == 0:
+        return (diff == 0).astype(np.float64)
+    return np.exp(-(diff ** 2) / (2.0 * rho ** 2))
+
+
+def _categorical_matrix(va, vb, rho):
+    a = np.asarray(va, dtype=object)[:, None]
+    b = np.asarray(vb, dtype=object)[None, :]
+    equal = a == b
+    if rho == 0:
+        return equal.astype(np.float64)
+    out = np.full(equal.shape, np.exp(-1.0 / (2.0 * rho ** 2)), dtype=np.float64)
+    out[equal] = 1.0
+    return out
+
+
+def _auto_rho(va, vb, kind):
+    a = np.asarray(va, dtype=np.float64) if kind == "measurable" else None
+    if kind == "measurable":
+        diff = a[:, None] - np.asarray(vb, dtype=np.float64)[None, :]
+        sigma = float(np.std(diff))
+    else:
+        eq = (np.asarray(va, dtype=object)[:, None] == np.asarray(vb, dtype=object)[None, :])
+        sigma = float(np.std(eq.astype(np.float64)))
+    # Guard against a degenerate zero std (all values identical).
+    return sigma if sigma > 0 else 0.0
+
+
+def _attribute_matrix(spec: Attribute, ga: Graph, gb: Graph):
+    if spec.on == "vertex":
+        va = _vertex_values(ga, spec.name)
+        vb = _vertex_values(gb, spec.name)
+    else:
+        va = _edge_values(ga, spec.name)
+        vb = _edge_values(gb, spec.name)
+
+    rho = _auto_rho(va, vb, spec.kind) if spec.rho == "auto" else float(spec.rho)
+
+    if spec.kind == "measurable":
+        return _measurable_matrix(va, vb, rho)
+    return _categorical_matrix(va, vb, rho)
+
+
+def build_matrices(specs, ga: Graph, gb: Graph):
+    """Build the vertex (``V``) and edge (``E``) distance matrices.
+
+    Parameters
+    ----------
+    specs:
+        Iterable of :class:`Attribute` or dict specifications, or ``None``.
+    ga, gb:
+        The two graphs being matched.
+
+    Returns
+    -------
+    V:
+        Vertex distance matrix of shape ``(nA, nB)`` (eq. 9). All-ones when no
+        vertex attribute is specified.
+    E:
+        Edge distance matrix of shape ``(mA, mB)`` (eq. 10). All-ones when no
+        edge attribute is specified.
+    """
+    V = np.ones((ga.n, gb.n), dtype=np.float64)
+    E = np.ones((ga.m, gb.m), dtype=np.float64)
+
+    if not specs:
+        return V, E
+
+    for spec in specs:
+        spec = _coerce(spec)
+        A = _attribute_matrix(spec, ga, gb)
+        if spec.on == "vertex":
+            V *= A
+        else:
+            E *= A
+    return V, E

gasm/convergence.py

@@ -0,0 +1,100 @@
+"""Convergence criteria for the GASM iterative procedure.
+
+The reference article (eq. 30) fixes the number of iterations to
+``k_tilde = min(diam_A, diam_B)``. Supp. Fig. S3 shows the accuracy usually
+plateaus well before that bound, so this module also provides an adaptive
+early-stop criterion that monitors the stabilisation of the row-wise argmax
+assignment -- a cheap surrogate for the final LAP that avoids running the LAP at
+every iteration -- capped by the diameter for safety.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+
+class ConvergenceMonitor:
+    """Track convergence of the vertex score matrix across iterations.
+
+    Parameters
+    ----------
+    mode:
+        ``'adaptive'`` (default) for early stopping, or ``'diameter'`` to
+        reproduce the fixed-iteration behaviour of the article.
+    diameter_cap:
+        Hard upper bound on the number of iterations ``k_tilde`` (eq. 30).
+    max_iterations:
+        Optional manual override of the hard cap.
+    tol:
+        Relative Frobenius-norm tolerance for the early-stop criterion.
+    patience:
+        Number of consecutive iterations with an unchanged argmax assignment
+        required to declare convergence.
+    floor:
+        Minimum number of iterations before early stopping is allowed.
+    """
+
+    def __init__(
+        self,
+        mode: str = "adaptive",
+        diameter_cap: int = 1,
+        max_iterations: int | None = None,
+        tol: float = 1e-6,
+        patience: int = 2,
+        floor: int = 2,
+    ):
+        if mode not in ("adaptive", "diameter"):
+            raise ValueError("convergence must be 'adaptive' or 'diameter'.")
+        self.mode = mode
+        cap = diameter_cap if max_iterations is None else max_iterations
+        self.cap = max(int(cap), 1)
+        self.tol = tol
+        self.patience = patience
+        self.floor = max(floor, 1)
+        self._prev_argmax: np.ndarray | None = None
+        self._prev_X: np.ndarray | None = None
+        self._stable = 0
+        self.iterations = 0
+
+    @property
+    def max_steps(self) -> int:
+        """Maximum number of update iterations that will be performed."""
+        return self.cap
+
+    def update(self, k: int, X: np.ndarray) -> bool:
+        """Register iteration ``k`` and return ``True`` if iteration should stop.
+
+        Parameters
+        ----------
+        k:
+            Current iteration index (``>= 1``).
+        X:
+            Current vertex score matrix.
+        """
+        self.iterations = k
+        if k >= self.cap:
+            return True
+        if self.mode == "diameter":
+            return False
+        if k < self.floor:
+            self._prev_argmax = X.argmax(axis=1)
+            self._prev_X = X
+            return False
+
+        argmax = X.argmax(axis=1)
+        stable = False
+        if self._prev_argmax is not None and np.array_equal(argmax, self._prev_argmax):
+            self._stable += 1
+        else:
+            self._stable = 0
+
+        if self._prev_X is not None:
+            denom = np.linalg.norm(X)
+            if denom > 0:
+                rel = np.linalg.norm(X - self._prev_X) / denom
+                if rel < self.tol:
+                    stable = True
+
+        self._prev_argmax = argmax
+        self._prev_X = X
+        return stable or self._stable >= self.patience

gasm/cpu/__init__.py

@@ -0,0 +1,5 @@
+"""CPU platform for GASM (reference implementation)."""
+
+from . import core
+
+__all__ = ["core"]

gasm/cpu/core.py

@@ -0,0 +1,180 @@
+"""CPU implementation of the GASM iterative procedure (eq. 15-31).
+
+This is the reference implementation, faithful to Candelier (JGAA 29(1), 2025).
+It uses dense NumPy score matrices with sparse incidence multiplications and is
+the platform used when ``platform='CPU'`` or when no OpenCL device is available.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import scipy.sparse as sp
+from scipy.sparse.csgraph import shortest_path
+
+from .. import graph as graphmod
+from ..convergence import ConvergenceMonitor
+
+
+def _effective_diameter(g, use_comp: bool) -> int:
+    """Diameter of the graph actually propagated during the iterations.
+
+    When the complement is used (eq. 18 / 26) the structural information flows
+    along the complement graph, whose diameter governs how many message-passing
+    steps are needed. Self-loops are irrelevant to distances and are ignored.
+    """
+    if not use_comp:
+        return graphmod.diameter(g)
+    n = g.n
+    A = (g.adjacency > 0).toarray()
+    comp = np.ones((n, n), dtype=bool)
+    np.fill_diagonal(comp, False)
+    comp &= ~A
+    if not g.directed:
+        comp |= comp.T
+    if not comp.any():
+        return 0
+    dist = shortest_path(
+        sp.csr_matrix(comp.astype(np.float64)),
+        directed=g.directed,
+        unweighted=True,
+    )
+    finite = dist[np.isfinite(dist)]
+    return int(finite.max()) if finite.size else 0
+
+
+
+def _l(Ssp, D):
+    """Sparse-left product ``Ssp @ D`` returning a dense array."""
+    return np.asarray(Ssp @ D)
+
+
+def _r(D, Ssp):
+    """Dense-right product ``D @ Ssp`` returning a dense array.
+
+    Computed as ``(Ssp.T @ D.T).T`` to keep the multiplication as
+    sparse-times-dense, which SciPy supports efficiently.
+    """
+    return np.asarray((Ssp.transpose() @ D.T).T)
+
+
+def _init_structure(ga, gb, E):
+    """Structure term of the initialization (eq. 15 / eq. 27)."""
+    if ga.directed:
+        return _r(_l(ga.S, E), gb.S.transpose()) + _r(_l(ga.T, E), gb.T.transpose())
+    return _r(_l(ga.R, E), gb.R.transpose())
+
+
+def run(
+    ga,
+    gb,
+    V,
+    E,
+    *,
+    structure: bool = True,
+    complement: bool = True,
+    noise: float = 1e-10,
+    convergence: str = "adaptive",
+    tol: float = 1e-6,
+    patience: int = 2,
+    max_iterations: int | None = None,
+    normalize: bool = True,
+    match_on: str = "vertices",
+    seed: int | None = None,
+):
+    """Run the GASM iterations on the CPU.
+
+    Returns
+    -------
+    score_matrix:
+        The converged score matrix the LAP should be run on: the vertex score
+        matrix ``X`` (``match_on='vertices'``) or the edge score matrix ``Y``
+        (``match_on='edges'``).
+    labels_a, labels_b:
+        Labels of the rows and columns of ``score_matrix`` (node labels for
+        vertices, ``(u, v)`` edge tuples for edges).
+    iterations:
+        Number of iterations actually performed.
+    """
+    rng = np.random.default_rng(seed)
+    nA, nB = ga.n, gb.n
+
+    # Noise term H, h_uv ~ U[0, eta] (eq. 11).
+    if noise and noise > 0:
+        H = rng.uniform(0.0, noise, size=(nA, nB))
+    else:
+        H = np.zeros((nA, nB))
+    Vplus = V + H
+
+    do_iterate = structure and ga.m > 0 and gb.m > 0
+
+    # Initialization (eq. 15 / 27). Always uses the original incidence matrices.
+    if do_iterate:
+        X = Vplus * _init_structure(ga, gb, E)
+    else:
+        X = Vplus.copy()
+    Y = None
+
+    # Normalization factor fx = 4 dA dB + 1 (eq. S2); fy = 1.
+    fx = (4.0 * ga.mean_degree * gb.mean_degree + 1.0) if normalize else 1.0
+
+    # Incidence matrices used in the iterations: complements when dense enough
+    # (eq. 18 / 26), unless matching on edges (Y must index real edges).
+    use_comp = complement and match_on != "edges" and graphmod.use_complement(ga, gb)
+    if ga.directed:
+        if use_comp:
+            _, SA, TA = ga.complement_incidence()
+            _, SB, TB = gb.complement_incidence()
+        else:
+            SA, TA, SB, TB = ga.S, ga.T, gb.S, gb.T
+    else:
+        if use_comp:
+            RA, _, _ = ga.complement_incidence()
+            RB, _, _ = gb.complement_incidence()
+        else:
+            RA, RB = ga.R, gb.R
+
+    # Convergence cap k_tilde = min(diam_A, diam_B) (eq. 30). In 'diameter' mode
+    # this faithfully uses the original graph diameters; in 'adaptive' mode the
+    # cap follows the iterated (complement) graph so early stopping is not
+    # artificially capped below the number of steps needed to propagate.
+    if convergence == "diameter":
+        cap = max(min(graphmod.diameter(ga), graphmod.diameter(gb)), 1)
+    else:
+        cap = max(min(_effective_diameter(ga, use_comp), _effective_diameter(gb, use_comp)), 1)
+    monitor = ConvergenceMonitor(
+        mode=convergence,
+        diameter_cap=cap,
+        max_iterations=max_iterations,
+        tol=tol,
+        patience=patience,
+        floor=2,
+    )
+
+    k = 1
+    if do_iterate:
+        while not monitor.update(k, X):
+            k += 1
+            if ga.directed:
+                Y = _r(_l(SA.transpose(), X), SB) + _r(_l(TA.transpose(), X), TB)
+                X = _r(_l(SA, Y), SB.transpose()) + _r(_l(TA, Y), TB.transpose())
+            else:
+                Y = _r(_l(RA.transpose(), X), RB)
+                X = _r(_l(RA, Y), RB.transpose())
+            if normalize:
+                X = X / fx
+
+        # Restore isolated vertices (eq. 31): x_{u,v} = nu_{u,v} / fx^{k-1},
+        # with nu = V (the initial vertex distances, without noise).
+        iso = ga.isolated[:, None] | gb.isolated[None, :]
+        if iso.any():
+            X = X.copy()
+            X[iso] = V[iso] / (fx ** (k - 1))
+
+    if match_on == "edges":
+        if Y is None:
+            raise ValueError(
+                "match_on='edges' requires a structural iteration; the graphs "
+                "have no edges or structure is disabled."
+            )
+        return Y, ga.edges, gb.edges, k
+    return X, ga.nodes, gb.nodes, k

gasm/gpu/__init__.py

@@ -0,0 +1,5 @@
+"""GPU (OpenCL) platform for GASM.
+
+The :mod:`gasm.gpu.core` module is imported lazily by :func:`gasm.match` so that
+the package works without :mod:`pyopencl` installed.
+"""