groupoid 0.1.0.dev2__py3-none-any.whl → 0.1.0.dev4__py3-none-any.whl

groupoid/__init__.py

@@ -1,6 +1,6 @@
 """GROUPOID: Groupoid-based federated learning with Riemannian geometry."""
 
-__version__ = "0.1.0.dev2"
+__version__ = "0.1.0.dev4"
 
 from groupoid.aggregation import (
     DisconnectedClientGraphError,

groupoid/aggregation.py

@@ -23,9 +23,11 @@ import numpy as np
 import numpy.typing as npt
 from loguru import logger
 
+from groupoid import persistence as _persistence
 from groupoid.cohomology import compute_h1
 from groupoid.groupoid import Morphism, compose, inverse
 from groupoid.manifold import karcher_mean
+from groupoid.transport import compute_transport_matrix
 
 
 class DisconnectedClientGraphError(Exception):
@@ -42,7 +44,14 @@ class DisconnectedClientGraphError(Exception):
 
 @dataclass
 class FederatedRound:
-    """Result of a single federated aggregation round."""
+    """Result of a single federated aggregation round.
+
+    ``divergence`` is populated only when the aggregator was constructed
+    with ``track_divergence=True``: it is the persistent-homology summary
+    of the transported client parameters, with the bottleneck distance to
+    the previous round's summary (None on the first round with tracking
+    off; see :func:`groupoid.persistence.track_divergence`).
+    """
 
     global_params: npt.NDArray[np.float64]
     local_updates: dict[str, npt.NDArray[np.float64]]
@@ -50,6 +59,7 @@ class FederatedRound:
     is_consistent: bool
     transport_residuals: dict[str, float]
     round_idx: int = 0
+    divergence: _persistence.PersistenceSummary | None = None
 
 
 @dataclass
@@ -73,14 +83,23 @@ class TransportGroupoidAggregator:
         The node to which all parameters are transported for aggregation.
     consistency_threshold
         Maximum H^1 norm before raising a consistency warning.
+    track_divergence
+        When True, each :meth:`aggregate` round computes the persistent
+        homology of the transported client parameters and the bottleneck
+        distance to the previous round (H0 against H0), populating
+        ``FederatedRound.divergence``.
     """
 
     manifold: object
     graph: nx.DiGraph
     base_node: str
     consistency_threshold: float = 1e-6
+    track_divergence: bool = False
     morphisms: dict[tuple[str, str], Morphism] = field(default_factory=dict)
     _round_idx: int = field(default=0, init=False)
+    _prev_divergence: _persistence.PersistenceSummary | None = field(
+        default=None, init=False, repr=False
+    )
 
     def register_transport(
         self, source: str, target: str, matrix: npt.NDArray[np.float64]
@@ -93,6 +112,42 @@ class TransportGroupoidAggregator:
         )
         logger.debug("Registered transport {} -> {}", source, target)
 
+    def register_transport_from_points(
+        self,
+        source: str,
+        target: str,
+        source_point: npt.NDArray[np.float64],
+        target_point: npt.NDArray[np.float64],
+        method: str = "pole",
+        n_rungs: int = 2,
+    ) -> npt.NDArray[np.float64]:
+        """Compute and register a transport map from two manifold points.
+
+        Builds the parallel-transport matrix along the geodesic from
+        ``source_point`` to ``target_point`` via
+        :func:`groupoid.transport.compute_transport_matrix` (pole or
+        Schild's ladder) and registers it for the ``(source, target)``
+        edge. This wires the ladder approximations into the aggregation
+        pipeline for the case where per-client base points are known but
+        explicit transport matrices are not. The ladders are
+        approximations with a small residual; see LIMITATIONS.md for the
+        measured behavior.
+
+        Returns
+        -------
+        np.ndarray
+            The registered transport matrix.
+        """
+        matrix = compute_transport_matrix(
+            self.manifold,
+            source_point,
+            target_point,
+            method=method,
+            n_rungs=n_rungs,
+        )
+        self.register_transport(source, target, matrix)
+        return matrix
+
     def _get_transport_to_base(self, node: str) -> npt.NDArray[np.float64] | None:
         """Compute the composite transport map from node to base_node.
 
@@ -194,6 +249,15 @@ class TransportGroupoidAggregator:
         nodes = sorted(transported.keys())
         param_stack = np.stack([transported[n] for n in nodes])
 
+        # Optional topological divergence tracking on the transported
+        # parameters (all in the base frame, so rounds are comparable).
+        divergence: _persistence.PersistenceSummary | None = None
+        if self.track_divergence:
+            divergence = _persistence.track_divergence(
+                param_stack, previous_summary=self._prev_divergence
+            )
+            self._prev_divergence = divergence
+
         if weights is not None:
             w = np.array([weights.get(n, 1.0) for n in nodes])
             w = w / w.sum()
@@ -223,6 +287,7 @@ class TransportGroupoidAggregator:
             is_consistent=is_consistent,
             transport_residuals=transport_residuals,
             round_idx=self._round_idx,
+            divergence=divergence,
         )
 
         logger.info(

groupoid/groupoid.py

@@ -24,6 +24,11 @@ class Morphism(BaseModel):
     def __repr__(self) -> str:
         return f"Morphism({self.source} -> {self.target})"
 
+    # pydantic's BaseModel defines __str__ separately (a field dump including
+    # the full transport matrix), which would bypass the compact __repr__ in
+    # print(), f-strings, and loguru's {} formatting. Alias it explicitly.
+    __str__ = __repr__
+
 
 class CompositionError(Exception):
     """Raised when morphism composition is not defined."""

groupoid/optimizer.py

@@ -9,6 +9,15 @@ This module provides:
 - Riemannian SGD with retraction
 - Riemannian Adam with exponential map updates
 - Adaptive learning rate based on sectional curvature
+
+Accumulated moments (the SGD momentum velocity and Adam's first moment)
+live in the tangent space of the iterate that produced them. After each
+step they are parallel-transported into the new iterate's tangent space
+when the metric provides parallel transport (the construction of
+Becigneul & Ganea, "Riemannian Adaptive Optimization Methods", ICLR 2019),
+and projected onto it otherwise. Transport is an isometry, so it moves the
+moment without shrinking it; projection is a coarser fallback that can
+lose the component normal to the new tangent space.
 """
 
 from __future__ import annotations
@@ -21,13 +30,42 @@ import numpy.typing as npt
 from loguru import logger
 
 
+def _transport_moment(
+    manifold: Any,  # geomstats manifold; no upstream type stubs
+    moment: npt.NDArray[np.float64],
+    base_point: npt.NDArray[np.float64],
+    new_point: npt.NDArray[np.float64],
+) -> npt.NDArray[np.float64]:
+    """Move an accumulated moment from base_point's tangent space to new_point's.
+
+    Uses the metric's parallel transport when available (isometric: the
+    moment's norm is preserved exactly). Falls back to projection onto the
+    new tangent space for metrics that do not implement parallel transport,
+    mirroring the compatibility shims elsewhere in this package.
+    """
+    metric = manifold.metric
+    if hasattr(metric, "parallel_transport"):
+        try:
+            transported: npt.NDArray[np.float64] = metric.parallel_transport(
+                moment, base_point, end_point=new_point
+            )
+            return transported
+        except NotImplementedError:
+            pass
+    projected: npt.NDArray[np.float64] = manifold.to_tangent(moment, new_point)
+    return projected
+
+
 @dataclass
 class RiemannianSGD:
     """Riemannian stochastic gradient descent.
 
     Updates parameters by computing the Riemannian gradient (projection
     of Euclidean gradient onto tangent space) and retracting back to
-    the manifold via the exponential map.
+    the manifold via the exponential map. With momentum, the velocity is
+    parallel-transported into each new iterate's tangent space (see the
+    module docstring), so it accumulates geometry-consistently across
+    steps.
 
     Parameters
     ----------
@@ -64,7 +102,10 @@ class RiemannianSGD:
         # Project gradient onto tangent space
         riemannian_grad = self.manifold.to_tangent(euclidean_grad, point)
 
-        # Apply momentum
+        # Apply momentum. _velocity was parallel-transported into `point`'s
+        # tangent space at the end of the previous step; the to_tangent wrap
+        # keeps the combination numerically tangent (and tolerates callers
+        # stepping from a point other than the previous iterate).
         vel: npt.NDArray[np.float64]
         if self.momentum > 0:
             if self._velocity is None:
@@ -73,7 +114,6 @@ class RiemannianSGD:
                 vel = self.manifold.to_tangent(
                     self.momentum * self._velocity + riemannian_grad, point
                 )
-            self._velocity = vel
             update = -self.lr * vel
         else:
             update = -self.lr * riemannian_grad
@@ -81,6 +121,10 @@ class RiemannianSGD:
         # Retract to manifold via exponential map
         new_point: npt.NDArray[np.float64] = self.manifold.metric.exp(update, point)
 
+        # Carry the velocity to the new iterate's tangent space.
+        if self.momentum > 0:
+            self._velocity = _transport_moment(self.manifold, vel, point, new_point)
+
         return new_point
 
 
@@ -90,7 +134,11 @@ class RiemannianAdam:
 
     Adapts the Adam optimizer to Riemannian manifolds by maintaining
     exponential moving averages of the Riemannian gradient and its
-    squared norm, with updates via the exponential map.
+    squared norm, with updates via the exponential map. The first moment
+    is parallel-transported into each new iterate's tangent space (see
+    the module docstring); the second moment is a scalar gradient-norm
+    average and needs no transport because parallel transport is an
+    isometry (norms are invariant).
 
     Parameters
     ----------
@@ -143,6 +191,10 @@ class RiemannianAdam:
         # m_hat = m_1 / (1 - beta1) recovers `grad` on the first step. Seeding
         # m_1 = grad directly would leave the 1/(1-beta1) factor uncancelled and
         # inflate the first update by ~10x (beta1=0.9).
+        # _m was parallel-transported into `point`'s tangent space at the end
+        # of the previous step; the to_tangent wrap keeps the combination
+        # numerically tangent (and tolerates callers stepping from a point
+        # other than the previous iterate).
         first_moment: npt.NDArray[np.float64]
         if self._m is None:
             first_moment = (1 - self.beta1) * grad
@@ -150,7 +202,6 @@ class RiemannianAdam:
             first_moment = self.manifold.to_tangent(
                 self.beta1 * self._m + (1 - self.beta1) * grad, point
             )
-        self._m = first_moment
 
         # Update biased second moment (scalar, norm-based)
         self._v = self.beta2 * self._v + (1 - self.beta2) * grad_norm_sq
@@ -164,6 +215,10 @@ class RiemannianAdam:
         update = self.manifold.to_tangent(update, point)
 
         new_point: npt.NDArray[np.float64] = self.manifold.metric.exp(update, point)
+
+        # Carry the first moment to the new iterate's tangent space.
+        self._m = _transport_moment(self.manifold, first_moment, point, new_point)
+
         return new_point
 
 
@@ -175,9 +230,10 @@ def curvature_adaptive_lr(
 ) -> float:
     """Adapt learning rate based on local sectional curvature.
 
-    In regions of high positive curvature, geodesics converge and
-    we should take smaller steps. In regions of negative curvature,
-    geodesics diverge and we can take larger steps.
+    In regions of high positive curvature, geodesics converge and we
+    should take smaller steps, so the base rate is damped by
+    ``1 / (1 + kappa)``. In flat or negatively curved regions the base
+    rate is returned unchanged; no enlargement is applied.
 
     Parameters
     ----------

{groupoid-0.1.0.dev2.dist-info → groupoid-0.1.0.dev4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: groupoid
-Version: 0.1.0.dev2
+Version: 0.1.0.dev4
 Summary: Research prototype: groupoid-based aggregation for federated learning on Riemannian manifolds
 Author-email: Santiago Maniches <santiago.maniches@gmail.com>
 License-Expression: Apache-2.0
@@ -109,21 +109,20 @@ integration tests:
 - **Federated aggregation pipeline**: transport-aware aggregation with
   H^1 consistency checking, multi-round convergence tested
   (`groupoid.aggregation`)
-
-## Implemented, validated against ground truth, not yet integrated
-
-These modules have unit tests that validate behavior against a
-known-correct reference, but are not yet wired into the main aggregation
-pipeline:
-
 - **Parallel transport**: Schild's ladder and pole ladder
-  (`groupoid.transport`). The pole ladder is validated against geomstats'
-  analytic parallel transport on S^2 -- it matches in direction
-  (cosine > 0.999) and magnitude. Schild's ladder is a coarser
-  first-order approximation and is asserted as such. See
-  [LIMITATIONS.md](LIMITATIONS.md) for the convergence caveat.
+  (`groupoid.transport`), wired into the pipeline via
+  `TransportGroupoidAggregator.register_transport_from_points` (computes
+  and registers the transport matrix from two client base points). The
+  pole ladder is validated against geomstats' analytic parallel transport
+  on S^2 -- it matches in direction (cosine > 0.999) and magnitude.
+  Schild's ladder is a coarser first-order approximation and is asserted
+  as such. See [LIMITATIONS.md](LIMITATIONS.md) for the convergence
+  caveat.
 - **Persistent homology**: Vietoris-Rips filtration for divergence
-  tracking (`groupoid.persistence`). Unit-tested against point clouds of
+  tracking (`groupoid.persistence`), wired into the pipeline via the
+  aggregator's opt-in `track_divergence` flag (per-round H0-vs-H0
+  bottleneck distance on the transported parameters, exposed as
+  `FederatedRound.divergence`). Unit-tested against point clouds of
   known topology: a circle's dominant 1-cycle (via maximum persistence),
   two-cluster component counting (`betti_0 == 2` at a finite filtration),
   and a translation-invariant bottleneck distance. The persistence diagram
@@ -133,17 +132,20 @@ pipeline:
   the H0 diagram. The Betti numbers are degenerate under the default
   `thresh=inf` filtration; see [LIMITATIONS.md](LIMITATIONS.md).
 
-## Implemented, smoke-tested, not yet integrated
+## Implemented and validated, not yet integrated
 
-This module has implementation with smoke-test coverage only -- the tests
-check coarse sanity (steps stay on the manifold), not core correctness --
-and it is not yet wired into the main aggregation pipeline:
+This module is validated against known-correct references but not yet
+wired into the main aggregation pipeline:
 
 - **Riemannian optimizers**: SGD and Adam with exponential map
-  retraction; smoke-tested to stay on the manifold after a step, with the
-  curvature-adaptive learning rate covered for both its damping and
-  fallback branches. Core descent/convergence behavior is not validated
-  (`groupoid.optimizer`)
+  retraction; the momentum velocity and Adam first moment are
+  parallel-transported between iterates (with a projection fallback for
+  metrics without parallel transport). Validated: descent to a known
+  target on S^2 (geodesic-distance objective) for SGD, momentum SGD, and
+  Adam; transported moments preserve norm exactly where projection would
+  annihilate them; the curvature-adaptive learning rate is covered for
+  both its damping and fallback branches. No general convergence-rate
+  guarantees are established (`groupoid.optimizer`)
 
 ## Status
 
@@ -178,8 +180,13 @@ idea -- transport-groupoid aggregation with cohomological consistency checking
 In short: use Flower/FedML/TFF for the FL system, use geomstats/pymanopt for
 manifold math; GROUPOID is a research prototype testing whether combining a
 transport groupoid with sheaf-cohomological consistency yields a better
-aggregation operator than Euclidean FedAvg. That hypothesis is **not yet
-validated** (see [STATUS.md](STATUS.md)).
+aggregation operator than Euclidean FedAvg. A preregistered synthetic
+benchmark ([experiments/](experiments/)) supports the transport benefit
+under frame misalignment -- an effect largely built into the synthetic
+setup -- and shows the pooled H^1 norm tracks corruption-induced error
+across corruption levels, though it does not rank runs within a level.
+The hypothesis remains **unvalidated on real federated learning tasks**
+(see [STATUS.md](STATUS.md)).
 
 ## Installation
 

groupoid-0.1.0.dev4.dist-info/RECORD

@@ -0,0 +1,15 @@
+groupoid/__init__.py,sha256=k4p0zjEcIY-NV9ZTo33Qu2u95M3TBAXMxo-qg25YK2k,839
+groupoid/aggregation.py,sha256=_HCkjvL6iYUYy_F5TAE-o2_WHTRDhCkTBelee92EfA0,11481
+groupoid/cohomology.py,sha256=CHZDSGjPPuDNXQG8f3xnx3sDlxpEmlYeWqRiCpfRNpU,3567
+groupoid/groupoid.py,sha256=VsZThPAamxXnNWZp3YYJtSv_AiHnw9PYajCAI2Kmkyc,2246
+groupoid/laplacian.py,sha256=jqZEU6yvBocUqKg30XUojIUlDoGZVfyMEBKNRWhdG6w,6189
+groupoid/manifold.py,sha256=2jP68SwLhbpl4EItvLBRnV6_k6l2thTFzchudIzjGJw,2100
+groupoid/optimizer.py,sha256=RmleLbxpIiUIVihYFHKsN49YAbuslV6Ip5xG2s_-QrI,9575
+groupoid/persistence.py,sha256=BuiBr00qRAXMPjdlZKuBRFhBUwFge7v2a-rn5bTF3LU,7229
+groupoid/sheaf.py,sha256=hlhvbP_rfQPy7t-EbvD8jTkjsRYv3eyk49Th2ehRNL0,2653
+groupoid/transport.py,sha256=5ItpmiIEqjEzEcFY8H1EAWiJpWHg-9h2d-UVkLAnR9A,5816
+groupoid-0.1.0.dev4.dist-info/licenses/LICENSE,sha256=qd0jMtXL8CN6XNdjjC4r2RX5u2FS6Y0TG1FtWTH4TTM,10766
+groupoid-0.1.0.dev4.dist-info/METADATA,sha256=TeyF3BIGLTWnNOTn9uIXDGQCSR0MoWnx2cCKW2AU_x4,11914
+groupoid-0.1.0.dev4.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+groupoid-0.1.0.dev4.dist-info/top_level.txt,sha256=avPz-dSDwo-4zKd7EoxNoLEEwEOYTAtByUD6BTFV9bY,9
+groupoid-0.1.0.dev4.dist-info/RECORD,,

{groupoid-0.1.0.dev2.dist-info → groupoid-0.1.0.dev4.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (82.0.1)
+Generator: setuptools (83.0.0)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

groupoid-0.1.0.dev2.dist-info/RECORD

@@ -1,15 +0,0 @@
-groupoid/__init__.py,sha256=Ygp2CQP485aQAdyO20G5BchVyM8TZPPgeLiWEYrDL4A,839
-groupoid/aggregation.py,sha256=5SbaiZkfA4HJGVR09n9oyzlEAGFyTN1eUZDVAcHoBYU,8768
-groupoid/cohomology.py,sha256=CHZDSGjPPuDNXQG8f3xnx3sDlxpEmlYeWqRiCpfRNpU,3567
-groupoid/groupoid.py,sha256=L2WmTG8-Sh_r6TsgmIJ077zRG-nz1OyYEqsorAJf1w0,1992
-groupoid/laplacian.py,sha256=jqZEU6yvBocUqKg30XUojIUlDoGZVfyMEBKNRWhdG6w,6189
-groupoid/manifold.py,sha256=2jP68SwLhbpl4EItvLBRnV6_k6l2thTFzchudIzjGJw,2100
-groupoid/optimizer.py,sha256=DPFVT93aPkygFkVrRVE0_H2I9dCkbX_qRo2-YTpZB6E,6650
-groupoid/persistence.py,sha256=BuiBr00qRAXMPjdlZKuBRFhBUwFge7v2a-rn5bTF3LU,7229
-groupoid/sheaf.py,sha256=hlhvbP_rfQPy7t-EbvD8jTkjsRYv3eyk49Th2ehRNL0,2653
-groupoid/transport.py,sha256=5ItpmiIEqjEzEcFY8H1EAWiJpWHg-9h2d-UVkLAnR9A,5816
-groupoid-0.1.0.dev2.dist-info/licenses/LICENSE,sha256=qd0jMtXL8CN6XNdjjC4r2RX5u2FS6Y0TG1FtWTH4TTM,10766
-groupoid-0.1.0.dev2.dist-info/METADATA,sha256=EmZ_ljhNpC0ffCfVBxU9r7IOi7RV3I0zdiIPdgmdUk0,11217
-groupoid-0.1.0.dev2.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-groupoid-0.1.0.dev2.dist-info/top_level.txt,sha256=avPz-dSDwo-4zKd7EoxNoLEEwEOYTAtByUD6BTFV9bY,9
-groupoid-0.1.0.dev2.dist-info/RECORD,,