gcn-python 1.0.0__py3-none-any.whl

gcn_python/layer2/reference.py

@@ -0,0 +1,159 @@
+from __future__ import annotations
+import numpy as np
+
+
+def _relu(x: np.ndarray) -> np.ndarray:
+    return np.maximum(0.0, x)
+
+
+def _relu_grad(x: np.ndarray) -> np.ndarray:
+    return (x > 0).astype(np.float32)
+
+
+class _LinearLayer:
+    def __init__(self, in_dim: int, out_dim: int, rng: np.random.Generator):
+        scale = np.sqrt(2.0 / in_dim)  # He init
+        self.W = rng.normal(0, scale, (out_dim, in_dim)).astype(np.float32)
+        self.b = np.zeros(out_dim, dtype=np.float32)
+        self._cache: dict = {}
+
+    def forward(self, x: np.ndarray) -> np.ndarray:
+        out = x @ self.W.T + self.b
+        self._cache["x"] = x
+        return out
+
+    def backward(self, d_out: np.ndarray) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
+        x = self._cache["x"]
+        dW = np.outer(d_out, x)
+        db = d_out.copy()
+        dx = d_out @ self.W
+        return dx, dW, db
+
+
+class MLPEncoder:
+    """
+    Implémentation de référence de la Couche 2 en NumPy pur.
+    Architecture : fc(D_in→128)+ReLU → fc(128→64)+ReLU → fc(64→out)
+
+    Le data scientist substitue par son propre CausalEncoder
+    (PyTorch, JAX, etc.) sans modifier le pipeline.
+    update_node / update_edge délèguent à _apply_grads — toute modification
+    de la règle de mise à jour (clipping, weight decay…) se fait une seule fois.
+    """
+
+    def __init__(self, d_clause: int, d_edge: int, seed: int = 42):
+        rng = np.random.default_rng(seed)
+
+        # Node MLP : d_clause → 128 → 64 → 7
+        self._node_layers = [
+            _LinearLayer(d_clause, 128, rng),
+            _LinearLayer(128, 64, rng),
+            _LinearLayer(64, 7, rng),
+        ]
+
+        # Edge MLP : d_edge → 256 → 128 → 11
+        self._edge_layers = [
+            _LinearLayer(d_edge, 256, rng),
+            _LinearLayer(256, 128, rng),
+            _LinearLayer(128, 11, rng),
+        ]
+
+        self._node_cache: list = []
+        self._edge_cache: list = []
+
+    def _forward_mlp(
+        self, x: np.ndarray, layers: list[_LinearLayer], cache_out: list
+    ) -> np.ndarray:
+        cache_out.clear()
+        h = x
+        for i, layer in enumerate(layers):
+            z = layer.forward(h)
+            if i < len(layers) - 1:
+                h = _relu(z)
+                cache_out.append((z, h))
+            else:
+                h = z
+                cache_out.append((z, z))
+        return h
+
+    def forward_node(self, x: np.ndarray) -> np.ndarray:
+        self._node_cache = []
+        return self._forward_mlp(x, self._node_layers, self._node_cache)
+
+    def forward_edge(self, x: np.ndarray) -> np.ndarray:
+        self._edge_cache = []
+        return self._forward_mlp(x, self._edge_layers, self._edge_cache)
+
+    def _backward_mlp(
+        self, d_logits: np.ndarray, layers: list[_LinearLayer], cache: list
+    ) -> tuple[list[tuple[np.ndarray, np.ndarray]], np.ndarray]:
+        """Retourne (grads, d_input) où d_input est le gradient vers l'entrée."""
+        grads = []
+        d = d_logits
+        for i in reversed(range(len(layers))):
+            z, _ = cache[i]
+            if i < len(layers) - 1:
+                d = d * _relu_grad(z)
+            dx, dW, db = layers[i].backward(d)
+            grads.insert(0, (dW, db))
+            d = dx
+        return grads, d
+
+    def backward_node(self, d_logits: np.ndarray) -> list[tuple[np.ndarray, np.ndarray]]:
+        grads, _ = self._backward_mlp(d_logits, self._node_layers, self._node_cache)
+        return grads
+
+    def backward_node_dx(self, d_logits: np.ndarray) -> tuple[list[tuple[np.ndarray, np.ndarray]], np.ndarray]:
+        """Comme backward_node mais retourne aussi le gradient vers l'entrée (pour R-GCN)."""
+        return self._backward_mlp(d_logits, self._node_layers, self._node_cache)
+
+    def backward_edge(self, d_logits: np.ndarray) -> list[tuple[np.ndarray, np.ndarray]]:
+        grads, _ = self._backward_mlp(d_logits, self._edge_layers, self._edge_cache)
+        return grads
+
+    def snapshot_node_cache(self) -> list:
+        """Snapshot du cache node + inputs des couches (pour backward par nœud)."""
+        return [
+            ((z.copy(), h.copy()), l._cache.get("x", np.zeros(0)).copy())
+            for (z, h), l in zip(self._node_cache, self._node_layers)
+        ]
+
+    def restore_node_cache(self, snapshot: list) -> None:
+        self._node_cache = [(z.copy(), h.copy()) for (z, h), _ in snapshot]
+        for ((_, _), x), layer in zip(snapshot, self._node_layers):
+            layer._cache["x"] = x.copy()
+
+    def snapshot_edge_cache(self) -> list:
+        return [
+            ((z.copy(), h.copy()), l._cache.get("x", np.zeros(0)).copy())
+            for (z, h), l in zip(self._edge_cache, self._edge_layers)
+        ]
+
+    def restore_edge_cache(self, snapshot: list) -> None:
+        self._edge_cache = [(z.copy(), h.copy()) for (z, h), _ in snapshot]
+        for ((_, _), x), layer in zip(snapshot, self._edge_layers):
+            layer._cache["x"] = x.copy()
+
+    def parameters(self) -> list[np.ndarray]:
+        params = []
+        for layer in self._node_layers + self._edge_layers:
+            params.extend([layer.W, layer.b])
+        return params
+
+    def _apply_grads(
+        self, layers: list[_LinearLayer],
+        grads: list[tuple[np.ndarray, np.ndarray]], lr: float,
+    ) -> None:
+        for layer, (dW, db) in zip(layers, grads):
+            layer.W -= lr * dW
+            layer.b -= lr * db
+
+    def update_node(self, grads: list[tuple[np.ndarray, np.ndarray]], lr: float) -> None:
+        self._apply_grads(self._node_layers, grads, lr)
+
+    def update_edge(self, grads: list[tuple[np.ndarray, np.ndarray]], lr: float) -> None:
+        self._apply_grads(self._edge_layers, grads, lr)
+
+    def update(self, grads: list[np.ndarray], lr: float) -> None:
+        for p, g in zip(self.parameters(), grads):
+            p -= lr * g

gcn_python/layer3/interface.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+from typing import Protocol, runtime_checkable
+import numpy as np
+
+
+@runtime_checkable
+class CausalGraph(Protocol):
+    """
+    Contrat d'interface de la Couche 3 — Graphe causal R-GCN.
+
+    Implémente le message passing relationnel sur le graphe causal.
+    Supporte les cycles (pas de restriction DAG).
+
+    Formule R-GCN :
+      h_i^(l+1) = σ( Σ_r Σ_{j∈N_r(i)} (1/c_{i,r}) W_r^(l) h_j^(l) + W_0^(l) h_i^(l) )
+    """
+
+    d_out: int
+
+    def message_pass(
+        self,
+        node_features: np.ndarray,  # (N, D_node)
+        edge_index: np.ndarray,     # (2, E) — [sources, targets]
+        edge_types: np.ndarray,     # (E,) int — index dans RELATION_TYPES
+    ) -> np.ndarray:                # (N, D_out) — représentations enrichies
+        ...
+
+    def parameters(self) -> list[np.ndarray]:
+        ...
+
+    def update(self, grads: list[np.ndarray], lr: float) -> None:
+        ...

gcn_python/layer3/pytorch_rgcn.py

@@ -0,0 +1,190 @@
+"""
+R-GCN PyTorch — implémentation haute performance de la couche 3.
+
+Remplace RGCNLayer (NumPy référence) par une implémentation PyTorch optimisée :
+- GPU / MPS support via device placement
+- Gradient automatique (autograd) pour la rétropropagation
+- Scatter-add vectorisé (pas de boucle Python par relation)
+- Compatible avec le Protocol CausalGraph de layer3/interface.py
+
+Usage (à la place de RGCNLayer) :
+    from gcn_python.layer3.pytorch_rgcn import RGCNLayerPT
+    layer = RGCNLayerPT(d_in=64, d_out=128)
+    out = layer.message_pass(node_feat, edge_index, edge_types)
+
+Intégration dans une boucle d'entraînement PyTorch standard :
+    optimizer = torch.optim.Adam(layer.torch_parameters(), lr=1e-3)
+    loss = criterion(out, targets)
+    loss.backward()
+    optimizer.step()
+
+Note : torch est une dépendance optionnelle. Si PyTorch n'est pas installé,
+l'import de ce module lève ImportError avec un message explicite.
+"""
+from __future__ import annotations
+
+try:
+    import torch
+    import torch.nn as nn
+    import torch.nn.functional as F
+except ImportError as e:  # pragma: no cover
+    raise ImportError(
+        "PyTorch est requis pour RGCNLayerPT. "
+        "Installez-le avec : pip install torch  "
+        "(voir https://pytorch.org/get-started/locally/ pour les options GPU)"
+    ) from e
+
+import numpy as np
+from typing import Any
+from ..constants import RELATION_TYPES
+
+
+class RGCNLayerPT(nn.Module):
+    """
+    Couche R-GCN PyTorch.
+
+    Formule :
+      h_i^(out) = σ( Σ_r (1/c_{i,r}) Σ_{j∈N_r(i)} W_r h_j  +  W_0 h_i )
+
+    Implémentée avec scatter_add_ vectorisé pour éviter les boucles Python
+    par relation. Supportant nativement les cycles.
+
+    Compatible avec le Protocol CausalGraph : message_pass / parameters / update.
+    Les utilisateurs PyTorch utiliseront de préférence torch_parameters() et
+    un optimizer PyTorch standard plutôt que update() (qui reste disponible
+    pour la compatibilité avec CGNPipeline).
+    """
+
+    def __init__(
+        self,
+        d_in: int,
+        d_out: int,
+        n_relations: int | None = None,
+        device: str | torch.device | None = None,
+        seed: int = 42,
+    ) -> None:
+        super().__init__()
+        self.d_in = d_in
+        self.d_out = d_out
+        self.n_relations = n_relations or len(RELATION_TYPES)
+
+        if device is None:
+            device = (
+                "cuda" if torch.cuda.is_available()
+                else "mps" if torch.backends.mps.is_available()
+                else "cpu"
+            )
+        self._device = torch.device(device)
+
+        torch.manual_seed(seed)
+        scale = (2.0 / d_in) ** 0.5
+
+        # Relation-specific weights: (R, D_out, D_in)
+        self.W_r = nn.Parameter(
+            torch.empty(self.n_relations, d_out, d_in, device=self._device).normal_(0, scale)
+        )
+        # Self-loop weight: (D_out, D_in)
+        self.W_0 = nn.Parameter(
+            torch.empty(d_out, d_in, device=self._device).normal_(0, scale)
+        )
+
+    # ------------------------------------------------------------------
+    # CausalGraph Protocol — message_pass
+    # ------------------------------------------------------------------
+
+    def message_pass(
+        self,
+        node_features: np.ndarray,  # (N, D_in)
+        edge_index: np.ndarray,     # (2, E)
+        edge_types: np.ndarray,     # (E,) int
+    ) -> np.ndarray:                # (N, D_out)
+        """Passe les messages sur le graphe causal et retourne les représentations enrichies."""
+        H = torch.as_tensor(node_features, dtype=torch.float32, device=self._device)
+        out = self._forward_pt(H, edge_index, edge_types)
+        return out.detach().cpu().numpy()
+
+    def _forward_pt(
+        self,
+        H: torch.Tensor,           # (N, D_in)
+        edge_index: np.ndarray,
+        edge_types: np.ndarray,
+    ) -> torch.Tensor:             # (N, D_out)
+        """Version PyTorch native (pour l'entraînement avec autograd)."""
+        N = H.shape[0]
+
+        # Self-loop : H @ W_0^T
+        out = H @ self.W_0.t()  # (N, D_out)
+
+        if edge_index.shape[1] > 0:
+            src = torch.as_tensor(edge_index[0], dtype=torch.long, device=self._device)
+            dst = torch.as_tensor(edge_index[1], dtype=torch.long, device=self._device)
+            rtypes = torch.as_tensor(edge_types, dtype=torch.long, device=self._device)
+
+            # Pour chaque type de relation, scatter_add vectorisé
+            for r in range(self.n_relations):
+                mask = rtypes == r
+                if not mask.any():
+                    continue
+                src_r = src[mask]   # arêtes de type r
+                dst_r = dst[mask]
+
+                # Comptage des voisins par destination (normalisation)
+                counts = torch.zeros(N, device=self._device, dtype=torch.float32)
+                counts.scatter_add_(0, dst_r, torch.ones_like(dst_r, dtype=torch.float32))
+                counts = counts.clamp(min=1.0)
+
+                # Messages : (|E_r|, D_out) = H[src_r] @ W_r[r]^T
+                msgs = H[src_r] @ self.W_r[r].t()
+
+                # Aggrégation dans les nœuds destination
+                agg = torch.zeros(N, self.d_out, device=self._device)
+                agg.scatter_add_(0, dst_r.unsqueeze(1).expand_as(msgs), msgs)
+                out = out + agg / counts.unsqueeze(1)
+
+        return torch.sigmoid(out)
+
+    # ------------------------------------------------------------------
+    # CausalGraph Protocol — parameters / update (compatibilité NumPy)
+    # ------------------------------------------------------------------
+
+    def parameters(self) -> list[np.ndarray]:  # type: ignore[override]
+        """Retourne les poids sous forme NumPy (compatibilité Protocol)."""
+        return [
+            self.W_r.detach().cpu().numpy(),
+            self.W_0.detach().cpu().numpy(),
+        ]
+
+    def update(self, grads: list[np.ndarray], lr: float) -> None:
+        """Mise à jour manuelle des poids (gradient descent numpy).
+        Les utilisateurs PyTorch préféreront optimizer.step() via torch_parameters().
+        """
+        with torch.no_grad():
+            self.W_r -= lr * torch.as_tensor(grads[0], dtype=torch.float32, device=self._device)
+            self.W_0 -= lr * torch.as_tensor(grads[1], dtype=torch.float32, device=self._device)
+
+    # ------------------------------------------------------------------
+    # API PyTorch native
+    # ------------------------------------------------------------------
+
+    def torch_parameters(self) -> list[nn.Parameter]:
+        """Retourne les paramètres PyTorch pour un optimizer standard."""
+        return list(super().parameters())
+
+    def forward_torch(
+        self,
+        H: torch.Tensor,
+        edge_index: np.ndarray,
+        edge_types: np.ndarray,
+    ) -> torch.Tensor:
+        """Forward pass PyTorch natif, conserve le graphe de calcul pour backward()."""
+        return self._forward_pt(H, edge_index, edge_types)
+
+    def to_device(self, device: str | torch.device) -> "RGCNLayerPT":
+        self._device = torch.device(device)
+        return self.to(self._device)
+
+    def __repr__(self) -> str:
+        return (
+            f"RGCNLayerPT(d_in={self.d_in}, d_out={self.d_out}, "
+            f"n_relations={self.n_relations}, device={self._device})"
+        )

gcn_python/layer3/reference.py

@@ -0,0 +1,102 @@
+from __future__ import annotations
+import numpy as np
+from ..constants import RELATION_TYPES
+
+
+def _sigmoid(x: np.ndarray) -> np.ndarray:
+    return 1.0 / (1.0 + np.exp(-np.clip(x, -30, 30)))
+
+
+class RGCNLayer:
+    """
+    Implémentation NumPy de référence d'une couche R-GCN.
+
+    h_i^(out) = σ( Σ_r (1/c_{i,r}) Σ_{j∈N_r(i)} W_r h_j + W_0 h_i )
+
+    Supporte les cycles — aucune restriction DAG.
+    Le DS empile plusieurs couches ou substitue par PyTorch Geometric.
+    """
+
+    def __init__(self, d_in: int, d_out: int, n_relations: int | None = None, seed: int = 42):
+        self.d_in = d_in
+        self.d_out = d_out
+        self.n_relations = n_relations or len(RELATION_TYPES)
+        rng = np.random.default_rng(seed)
+        scale = np.sqrt(2.0 / d_in)
+        self.W_r = rng.normal(0, scale, (self.n_relations, d_out, d_in)).astype(np.float32)
+        self.W_0 = rng.normal(0, scale, (d_out, d_in)).astype(np.float32)
+        self._fwd_inputs: tuple | None = None
+        self._fwd_output: np.ndarray | None = None
+
+    def message_pass(
+        self,
+        node_features: np.ndarray,  # (N, D_in)
+        edge_index: np.ndarray,     # (2, E)
+        edge_types: np.ndarray,     # (E,) int
+    ) -> np.ndarray:                # (N, D_out)
+        N = node_features.shape[0]
+        out = node_features @ self.W_0.T  # self-loop
+
+        if edge_index.shape[1] > 0:
+            src, dst = edge_index[0], edge_index[1]
+            for r in range(self.n_relations):
+                mask = edge_types == r
+                if not np.any(mask):
+                    continue
+                src_r, dst_r = src[mask], dst[mask]
+                counts = np.maximum(np.bincount(dst_r, minlength=N).astype(np.float32), 1.0)
+                msgs = node_features[src_r] @ self.W_r[r].T  # (|E_r|, D_out)
+                for e_idx, d in enumerate(dst_r):
+                    out[d] += msgs[e_idx] / counts[d]
+
+        h = _sigmoid(out)
+        # Copier les tableaux : évite que des mutations externes corrompent le backward
+        self._fwd_inputs = (node_features.copy(), edge_index.copy(), edge_types.copy())
+        self._fwd_output = h
+        return h
+
+    def backward_message_pass(
+        self,
+        d_output: np.ndarray,       # (N, D_out)
+    ) -> tuple[np.ndarray, list[np.ndarray]]:
+        """Rétropropagation à travers le message passing R-GCN.
+
+        Retourne (d_input, [dW_r, dW_0]) où d_input est le gradient vers
+        les features d'entrée (ignoré — pas de paramètres apprenables en amont).
+        """
+        assert self._fwd_inputs is not None, "backward_message_pass appelé avant message_pass"
+        node_features, edge_index, edge_types = self._fwd_inputs
+        h = self._fwd_output
+        N = node_features.shape[0]
+
+        # Gradient à travers sigmoid : d_pre_act = d_output * h * (1 - h)
+        d_pre_act = d_output * h * (1.0 - h)  # (N, D_out)
+
+        # Self-loop : out_self = node_features @ W_0.T
+        dW_0 = d_pre_act.T @ node_features           # (D_out, D_in)
+        d_input = d_pre_act @ self.W_0               # (N, D_in)
+
+        dW_r = np.zeros_like(self.W_r)               # (n_relations, D_out, D_in)
+
+        if edge_index.shape[1] > 0:
+            src, dst = edge_index[0], edge_index[1]
+            for r in range(self.n_relations):
+                mask = edge_types == r
+                if not np.any(mask):
+                    continue
+                src_r, dst_r = src[mask], dst[mask]
+                counts = np.maximum(np.bincount(dst_r, minlength=N).astype(np.float32), 1.0)
+
+                # Gradient des messages normalisés vers W_r et noeuds sources
+                d_msgs = d_pre_act[dst_r] / counts[dst_r, np.newaxis]  # (|E_r|, D_out)
+                dW_r[r] = d_msgs.T @ node_features[src_r]               # (D_out, D_in)
+                np.add.at(d_input, src_r, d_msgs @ self.W_r[r])         # (|E_r|, D_in)
+
+        return d_input, [dW_r, dW_0]
+
+    def parameters(self) -> list[np.ndarray]:
+        return [self.W_r, self.W_0]
+
+    def update(self, grads: list[np.ndarray], lr: float) -> None:
+        self.W_r -= lr * grads[0]
+        self.W_0 -= lr * grads[1]