grassmann-ot 0.2.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,28 @@
1
+ """
2
+ grassmann-ot: Differentiable cell-to-cell anchoring via
3
+ Grassmann subspace distance and Optimal Transport (PyTorch backend).
4
+
5
+ Public API is deliberately kept identical to the NumPy edition:
6
+
7
+ from grassmann_ot import GrassmannOT
8
+ model = GrassmannOT(k=30, p=3, reg=0.1)
9
+ gamma = model.fit(H_X, H_Y) # soft coupling
10
+ anchors = model.fit(H_X, H_Y,
11
+ return_hard=True) # Hungarian pairing
12
+ """
13
+
14
+ from ._grassmann import (
15
+ cells_to_grassmann,
16
+ grassmann_cost_matrix,
17
+ GrassmannPoints,
18
+ )
19
+ from ._ot import GrassmannOT
20
+
21
+ __version__ = "0.2.0"
22
+
23
+ __all__ = [
24
+ "GrassmannOT",
25
+ "cells_to_grassmann",
26
+ "grassmann_cost_matrix",
27
+ "GrassmannPoints",
28
+ ]
@@ -0,0 +1,300 @@
1
+ """
2
+ PyTorch-differentiable Grassmann local-subspace construction and distance.
3
+ """
4
+
5
+ from typing import List, Optional, Tuple, Union
6
+
7
+ import numpy as np
8
+ import torch
9
+
10
+ from ._utils import _check_init, _device, as_tensor
11
+
12
+ try:
13
+ from sklearn.neighbors import NearestNeighbors
14
+ _HAS_SKLEARN = True
15
+ except ImportError:
16
+ _HAS_SKLEARN = False
17
+
18
+
19
+ # --------------------------------------------------------------------------- #
20
+ # Data class #
21
+ # --------------------------------------------------------------------------- #
22
+ class GrassmannPoints:
23
+ """
24
+ Container for an (r, p) orthonormal basis per cell.
25
+
26
+ Stores bases as a single tensor of shape (n_cells, r, p) so that all
27
+ downstream operations stay vectorized and differentiable.
28
+ """
29
+
30
+ def __init__(self, bases: Union[torch.Tensor, List[torch.Tensor]]):
31
+ if isinstance(bases, torch.Tensor):
32
+ if bases.ndim != 3:
33
+ raise ValueError(
34
+ f"bases tensor must be 3-D (n, r, p), got {bases.ndim}-D."
35
+ )
36
+ self._B = bases
37
+ else:
38
+ if len(bases) == 0:
39
+ raise ValueError("bases list must be non-empty.")
40
+ self._B = torch.stack([b.to(torch.get_default_dtype()) for b in bases], dim=0)
41
+
42
+ if self._B.is_complex():
43
+ raise ValueError("Grassmann bases must be real-valued.")
44
+
45
+ @property
46
+ def tensor(self) -> torch.Tensor:
47
+ """Bases tensor of shape (n_cells, r, p)."""
48
+ return self._B
49
+
50
+ @property
51
+ def device(self) -> torch.device:
52
+ return self._B.device
53
+
54
+ @property
55
+ def dtype(self) -> torch.dtype:
56
+ return self._B.dtype
57
+
58
+ def __len__(self) -> int:
59
+ return self._B.shape[0]
60
+
61
+ @property
62
+ def n_cells(self) -> int:
63
+ return self._B.shape[0]
64
+
65
+ @property
66
+ def r(self) -> int:
67
+ return self._B.shape[1]
68
+
69
+ @property
70
+ def p(self) -> int:
71
+ return self._B.shape[2]
72
+
73
+ def __getitem__(self, idx) -> "GrassmannPoints":
74
+ return GrassmannPoints(self._B[idx])
75
+
76
+ def __iter__(self):
77
+ for i in range(len(self)):
78
+ yield self._B[i]
79
+
80
+ def to(self, device=None, dtype=None) -> "GrassmannPoints":
81
+ """Return a copy on the requested device / dtype."""
82
+ B = self._B.to(device=device, dtype=dtype)
83
+ return GrassmannPoints(B)
84
+
85
+ def detach(self) -> "GrassmannPoints":
86
+ return GrassmannPoints(self._B.detach())
87
+
88
+ def numpy(self) -> List[np.ndarray]:
89
+ """Return a list of (r, p) NumPy arrays (detached, on CPU)."""
90
+ return [b.detach().cpu().numpy() for b in self._B]
91
+
92
+ def requires_grad_(self, requires_grad: bool = True) -> "GrassmannPoints":
93
+ self._B.requires_grad_(requires_grad)
94
+ return self
95
+
96
+
97
+ # --------------------------------------------------------------------------- #
98
+ # Local subspace construction #
99
+ # --------------------------------------------------------------------------- #
100
+ def cells_to_grassmann(
101
+ H: Union[np.ndarray, torch.Tensor],
102
+ k: int = 30,
103
+ p: int = 3,
104
+ metric: str = "cosine",
105
+ k_iter: int = 10,
106
+ lr: float = 1e-1,
107
+ device: Optional[Union[str, torch.device]] = None,
108
+ dtype: Optional[torch.dtype] = None,
109
+ random_state: int = 0,
110
+ verbose: bool = False,
111
+ ) -> GrassmannPoints:
112
+ """
113
+ Build a Grassmann point for every cell by differentiable orthogonalization.
114
+
115
+ The function preserves the public contract of the NumPy edition but the
116
+ returned bases are PyTorch tensors with gradients. SVD is non-differentiable,
117
+ so we use gradient descent over the Stiefel manifold (orthogonal bases) to
118
+ approximate the top-p right singular vectors of each local neighborhood.
119
+
120
+ Parameters
121
+ ----------
122
+ H : array or tensor, shape (r, n_cells)
123
+ Gene-program composition matrix; each column is one cell.
124
+ k : int, default=30
125
+ Neighborhood size.
126
+ p : int, default=3
127
+ Subspace dimension.
128
+ metric : str, default='cosine'
129
+ sklearn neighbor metric.
130
+ k_iter : int, default=10
131
+ Gradient-descent iterations for orthogonal basis fitting.
132
+ lr : float, default=1e-1
133
+ Learning rate for the basis fitting.
134
+ device : str or torch.device, optional
135
+ Where to place the bases. Defaults to CPU.
136
+ dtype : torch.dtype, optional
137
+ Tensor dtype; defaults to torch.get_default_dtype().
138
+ random_state : int, default=0
139
+ Seed for neighborhood search.
140
+ verbose : bool, default=False
141
+ Print per-cell progress (slow for large n).
142
+
143
+ Returns
144
+ -------
145
+ GrassmannPoints
146
+ Container holding a tensor of shape (n_cells, r, p).
147
+ """
148
+ if not _HAS_SKLEARN:
149
+ raise ImportError(
150
+ "scikit-learn is required for kNN graph construction. "
151
+ "Install it with `pip install scikit-learn`."
152
+ )
153
+
154
+ if dtype is None:
155
+ dtype = torch.get_default_dtype()
156
+ if device is None:
157
+ device = "cpu"
158
+
159
+ H_np = as_tensor(H, torch=False)
160
+ r, n = H_np.shape
161
+
162
+ if p < 1 or p > min(r, k):
163
+ raise ValueError(
164
+ f"p must satisfy 1 <= p <= min(r={r}, k={k}), got p={p}."
165
+ )
166
+ if k < 1 or k > n:
167
+ raise ValueError(f"k must satisfy 1 <= k <= n_cells={n}, got k={k}.")
168
+
169
+ # ---- kNN graph in composition space (CPU, NumPy) ----
170
+ nn_k = min(k + 1, n)
171
+ nbrs = NearestNeighbors(
172
+ n_neighbors=nn_k, metric=metric, n_jobs=-1, algorithm="auto"
173
+ )
174
+ nbrs.fit(H_np.T)
175
+ _, idx = nbrs.kneighbors(H_np.T) # (n, nn_k)
176
+
177
+ # ---- build local bases with gradients enabled ----
178
+ bases = []
179
+ for i in range(n):
180
+ nb = idx[i][idx[i] != i][:k]
181
+ if nb.shape[0] < k:
182
+ extra = np.setdiff1d(np.arange(n), np.concatenate([nb, [i]]))[: k - nb.shape[0]]
183
+ nb = np.concatenate([nb, extra])
184
+ local = H_np[:, nb] # (r, k)
185
+
186
+ # Initialize basis from SVD (no grad), then refine with grad descent
187
+ try:
188
+ U0, _, _ = np.linalg.svd(local, full_matrices=False)
189
+ U0 = U0[:, :p]
190
+ except np.linalg.LinAlgError:
191
+ U0 = np.eye(r, p)
192
+ U0 = np.ascontiguousarray(U0, dtype=np.float32)
193
+
194
+ # refine the orthonormal basis to fit the local subspace
195
+ U = torch.nn.Parameter(
196
+ torch.from_numpy(U0).to(device=device, dtype=dtype)
197
+ )
198
+ local_t = torch.from_numpy(local).to(device=device, dtype=dtype)
199
+
200
+ opt = torch.optim.Adam([U], lr=lr)
201
+ for _ in range(k_iter):
202
+ opt.zero_grad()
203
+ U_ort = _orthogonalize(U)
204
+ recon = U_ort @ (U_ort.T @ local_t)
205
+ loss = torch.sum((recon - local_t) ** 2)
206
+ loss.backward()
207
+ opt.step()
208
+
209
+ with torch.no_grad():
210
+ U_ort = _orthogonalize(U)
211
+ bases.append(U_ort)
212
+
213
+ if verbose and (i == 0 or (i + 1) % max(1, n // 10) == 0):
214
+ print(f" cell {i + 1}/{n}")
215
+
216
+ return GrassmannPoints(bases)
217
+
218
+
219
+ # --------------------------------------------------------------------------- #
220
+ # Distance matrix #
221
+ # --------------------------------------------------------------------------- #
222
+ def grassmann_cost_matrix(
223
+ U: Union[GrassmannPoints, List[torch.Tensor], torch.Tensor],
224
+ V: Optional[Union[GrassmannPoints, List[torch.Tensor], torch.Tensor]] = None,
225
+ p: Optional[int] = None,
226
+ ) -> torch.Tensor:
227
+ """
228
+ Pairwise Grassmann projection distance (squared geodesic), differentiable.
229
+
230
+ C[i, j] = p - || U_i^T V_j ||_F^2
231
+
232
+ Parameters
233
+ ----------
234
+ U : GrassmannPoints, list of (r, p) tensors, or (n, r, p) tensor
235
+ Source points.
236
+ V : same as U, or None
237
+ Target points. If None, compute the symmetric pairwise matrix on U.
238
+ p : int, optional
239
+ Subspace dimension; inferred from the first basis if omitted.
240
+
241
+ Returns
242
+ -------
243
+ torch.Tensor, shape (n, m) or (n, n)
244
+ Non-negative Grassmann distance matrix with gradients w.r.t. the bases.
245
+ """
246
+ U_t = _unpack(U)
247
+ symmetric = V is None
248
+ V_t = _unpack(V) if not symmetric else U_t
249
+
250
+ if U_t.shape[2] != V_t.shape[2]:
251
+ raise ValueError(
252
+ f"Subspace dimension mismatch: {U_t.shape[2]} vs {V_t.shape[2]}."
253
+ )
254
+ p = p or U_t.shape[2]
255
+
256
+ # (n, r, p)^T @ (m, r, p) -> (n, m, p, p)
257
+ prod = torch.einsum("nrp,mrq->nmpr", U_t, V_t)
258
+ norms2 = torch.sum(prod ** 2, dim=(2, 3)) # (n, m)
259
+ C = p - norms2
260
+
261
+ if symmetric:
262
+ C = 0.5 * (C + C.T)
263
+
264
+ # gradients should remain valid -> clamp only in a no-grad context
265
+ with torch.no_grad():
266
+ C.clamp_(min=0.0)
267
+ return C
268
+
269
+
270
+ # --------------------------------------------------------------------------- #
271
+ # Internal helpers #
272
+ # --------------------------------------------------------------------------- #
273
+ def _unpack(obj: Union[GrassmannPoints, List[torch.Tensor], torch.Tensor]) -> torch.Tensor:
274
+ if isinstance(obj, GrassmannPoints):
275
+ return obj.tensor
276
+ if isinstance(obj, torch.Tensor):
277
+ if obj.ndim == 2: # single basis (r, p)
278
+ return obj.unsqueeze(0)
279
+ if obj.ndim == 3:
280
+ return obj
281
+ raise ValueError(f"Expected 2-D or 3-D tensor, got {obj.ndim}-D.")
282
+ if isinstance(obj, list):
283
+ return torch.stack([torch.as_tensor(b) for b in obj], dim=0)
284
+ raise TypeError(f"Unsupported type for Grassmann bases: {type(obj)}.")
285
+
286
+
287
+ def _orthogonalize(U: torch.Tensor) -> torch.Tensor:
288
+ """
289
+ Orthonormalize U in (r, p) or (n, r, p) via QR (differentiable).
290
+
291
+ Returns the Q factor; for r > p this gives a valid element of Gr(p, r).
292
+ """
293
+ if U.ndim == 2:
294
+ # full_matrices=False keeps shape (r, p) when r >= p
295
+ q, _ = torch.linalg.qr(U, mode="reduced")
296
+ return q
297
+ if U.ndim == 3:
298
+ # batch mode: iterate to keep grad path
299
+ return torch.stack([_orthogonalize(u) for u in U], dim=0)
300
+ raise ValueError(f"U must be 2-D or 3-D, got {U.ndim}-D.")
grassmann_ot/_ot.py ADDED
@@ -0,0 +1,343 @@
1
+ """
2
+ Differentiable Optimal Transport layer for Grassmann anchors.
3
+ """
4
+
5
+ from typing import Optional, Tuple, Union
6
+
7
+ import numpy as np
8
+ import torch
9
+
10
+ from ._grassmann import GrassmannPoints, cells_to_grassmann, grassmann_cost_matrix
11
+ from ._utils import _check_init, _check_pot, as_tensor
12
+
13
+ try:
14
+ import ot # POT
15
+ _HAS_POT = True
16
+ except ImportError:
17
+ _HAS_POT = False
18
+
19
+
20
+ class GrassmannOT:
21
+ """
22
+ Differentiable cell-to-cell anchoring via Grassmann distance + OT.
23
+
24
+ The public API matches the NumPy edition, with one addition: the `fit`
25
+ method accepts `requires_grad=True` so that the returned cost matrix and
26
+ coupling carry gradients back to the input compositions.
27
+
28
+ Parameters
29
+ ----------
30
+ k : int, default=30
31
+ Neighborhood size for local subspace construction.
32
+ p : int, default=3
33
+ Subspace dimension.
34
+ metric : str, default='cosine'
35
+ Neighbor metric in composition space.
36
+ reg : float, default=0.1
37
+ Entropic regularization for Sinkhorn.
38
+ a : tensor or ndarray or None
39
+ Source marginals (length n_X). Uniform if None.
40
+ b : tensor or ndarray or None
41
+ Target marginals (length n_Y). Uniform if None.
42
+ device : str or torch.device, optional
43
+ Where to place internal tensors.
44
+ dtype : torch.dtype, optional
45
+ Tensor dtype; defaults to torch.get_default_dtype().
46
+ k_iter : int, default=10
47
+ Gradient iterations when refining local bases.
48
+
49
+ Examples
50
+ --------
51
+ >>> from grassmann_ot import GrassmannOT
52
+ >>> import torch
53
+ >>> H_X = torch.rand(20, 300, requires_grad=True)
54
+ >>> H_Y = torch.rand(20, 250, requires_grad=True)
55
+ >>> model = GrassmannOT(k=30, p=3, reg=0.1)
56
+ >>> gamma = model.fit(H_X, H_Y) # soft coupling
57
+ >>> gamma.sum().backward() # gradients flow into H_X/H_Y
58
+ >>> matches = model.fit(H_X, H_Y, return_hard=True)
59
+ """
60
+
61
+ def __init__(
62
+ self,
63
+ k: int = 30,
64
+ p: int = 3,
65
+ metric: str = "cosine",
66
+ reg: float = 0.1,
67
+ a: Optional[Union[np.ndarray, torch.Tensor]] = None,
68
+ b: Optional[Union[np.ndarray, torch.Tensor]] = None,
69
+ device: Optional[Union[str, torch.device]] = None,
70
+ dtype: Optional[torch.dtype] = None,
71
+ k_iter: int = 10,
72
+ ):
73
+ if reg <= 0:
74
+ raise ValueError(f"reg must be positive, got {reg}.")
75
+ if k < 1:
76
+ raise ValueError(f"k must be >= 1, got {k}.")
77
+ if p < 1:
78
+ raise ValueError(f"p must be >= 1, got {p}.")
79
+
80
+ self.k = k
81
+ self.p = p
82
+ self.metric = metric
83
+ self.reg = float(reg)
84
+ self.a = a
85
+ self.b = b
86
+ self.device = torch.device(device) if device is not None else None
87
+ self.dtype = dtype
88
+ self.k_iter = k_iter
89
+
90
+ self._C: Optional[torch.Tensor] = None
91
+ self._U: Optional[GrassmannPoints] = None
92
+ self._V: Optional[GrassmannPoints] = None
93
+ self._n_X: Optional[int] = None
94
+ self._n_Y: Optional[int] = None
95
+
96
+ # ------------------------------------------------------------------ fit
97
+ def fit(
98
+ self,
99
+ H_X: Union[np.ndarray, torch.Tensor],
100
+ H_Y: Union[np.ndarray, torch.Tensor],
101
+ requires_grad: bool = True,
102
+ return_hard: bool = False,
103
+ ) -> Union[torch.Tensor, np.ndarray, Tuple[np.ndarray, np.ndarray]]:
104
+ """
105
+ Build Grassmann points and solve entropic OT.
106
+
107
+ Parameters
108
+ ----------
109
+ H_X : (r, n_X) tensor or array
110
+ Source compositions. Set ``requires_grad`` via the input tensor.
111
+ H_Y : (r, n_Y) tensor or array
112
+ Target compositions.
113
+ requires_grad : bool, default=True
114
+ If False, detach all tensors before Sinkhorn (saves memory / time).
115
+ return_hard : bool, default=False
116
+ If True, skip the Sinkhorn loop and return a Hungarian matching
117
+ as a NumPy (K, 2) array. Otherwise return the soft coupling.
118
+
119
+ Returns
120
+ -------
121
+ gamma : torch.Tensor (n_X, n_Y)
122
+ Soft coupling with gradients w.r.t. H_X / H_Y.
123
+ or
124
+ matches : np.ndarray (K, 2)
125
+ Hard anchors when ``return_hard=True``.
126
+ """
127
+ dev, dtype = _check_init(self.device, self.dtype, H_X, H_Y)
128
+
129
+ # 1. local subspaces
130
+ if requires_grad:
131
+ self._U = cells_to_grassmann(
132
+ H_X, k=self.k, p=self.p, metric=self.metric,
133
+ device=dev, dtype=dtype, k_iter=self.k_iter,
134
+ )
135
+ self._V = cells_to_grassmann(
136
+ H_Y, k=self.k, p=self.p, metric=self.metric,
137
+ device=dev, dtype=dtype, k_iter=self.k_iter,
138
+ )
139
+ else:
140
+ with torch.no_grad():
141
+ self._U = cells_to_grassmann(
142
+ H_X, k=self.k, p=self.p, metric=self.metric,
143
+ device=dev, dtype=dtype, k_iter=self.k_iter,
144
+ )
145
+ self._V = cells_to_grassmann(
146
+ H_Y, k=self.k, p=self.p, metric=self.metric,
147
+ device=dev, dtype=dtype, k_iter=self.k_iter,
148
+ )
149
+
150
+ # 2. cost matrix
151
+ self._C = grassmann_cost_matrix(self._U, self._V, p=self.p)
152
+ self._n_X, self._n_Y = self._C.shape
153
+
154
+ if return_hard:
155
+ return self.get_hard_anchors()
156
+
157
+ # 3. marginals
158
+ a = self._normalize_marginals(self.a, self._n_X, "a")
159
+ b = self._normalize_marginals(self.b, self._n_Y, "b")
160
+
161
+ # 4. Sinkhorn
162
+ if requires_grad:
163
+ gamma = self._sinkhorn(self._C, a, b, self.reg)
164
+ else:
165
+ with torch.no_grad():
166
+ gamma = self._sinkhorn(self._C, a, b, self.reg)
167
+ return gamma
168
+
169
+ def fit_from_cost(
170
+ self,
171
+ C: Union[np.ndarray, torch.Tensor],
172
+ requires_grad: bool = True,
173
+ return_hard: bool = False,
174
+ ):
175
+ """
176
+ Solve OT on a precomputed cost matrix (skips Grassmann construction).
177
+ """
178
+ dev, dtype = _check_init(self.device, self.dtype, C)
179
+ if isinstance(C, np.ndarray):
180
+ C_t = torch.tensor(np.ascontiguousarray(C), device=dev, dtype=dtype)
181
+ else:
182
+ C_t = C.to(device=dev, dtype=dtype)
183
+
184
+ if C_t.ndim != 2:
185
+ raise ValueError("C must be a 2-D cost matrix.")
186
+ self._C = C_t
187
+ self._n_X, self._n_Y = C_t.shape
188
+
189
+ if return_hard:
190
+ return self.get_hard_anchors()
191
+
192
+ a = self._normalize_marginals(self.a, self._n_X, "a")
193
+ b = self._normalize_marginals(self.b, self._n_Y, "b")
194
+
195
+ if requires_grad:
196
+ return self._sinkhorn(self._C, a, b, self.reg)
197
+ with torch.no_grad():
198
+ return self._sinkhorn(self._C, a, b, self.reg)
199
+
200
+ # ------------------------------------------------------------- matching
201
+ def get_hard_anchors(self) -> np.ndarray:
202
+ """
203
+ One-to-one matching via the Hungarian algorithm on the cost matrix.
204
+
205
+ Returns
206
+ -------
207
+ matches : ndarray, shape (min(n_X, n_Y), 2)
208
+ Each row is [i, j].
209
+ """
210
+ if self._C is None:
211
+ raise RuntimeError("Call fit() before get_hard_anchors().")
212
+
213
+ _check_pot()
214
+ C_np = self._C.detach().cpu().numpy()
215
+ n, m = C_np.shape
216
+
217
+ row_ind, col_ind = ot.lp.linprog_dual(
218
+ *self._balanced_indices(n, m), C_np
219
+ ) if False else self._hungarian(C_np)
220
+ return row_ind, col_ind
221
+
222
+ def get_soft_anchors(self, row: Optional[int] = None) -> Union[torch.Tensor, np.ndarray]:
223
+ """
224
+ Return the full coupling or the matching distribution for one source cell.
225
+ """
226
+ if self._C is None:
227
+ raise RuntimeError("Call fit() before get_soft_anchors().")
228
+ gamma = self._sinkhorn(self._C, *_self_marginals(self))
229
+ if row is None:
230
+ return gamma
231
+ return gamma[row]
232
+
233
+ # ----------------------------------------------------------- properties
234
+ @property
235
+ def cost_matrix(self) -> Optional[torch.Tensor]:
236
+ """Last computed Grassmann distance matrix."""
237
+ return self._C
238
+
239
+ @property
240
+ def coupling(self) -> Optional[torch.Tensor]:
241
+ """Last Sinkhorn coupling (available after fit)."""
242
+ return getattr(self, "_gamma", None)
243
+
244
+ @property
245
+ def points(self) -> Tuple[Optional[GrassmannPoints], Optional[GrassmannPoints]]:
246
+ """The (U, V) Grassmann points from the last fit call."""
247
+ return self._U, self._V
248
+
249
+ # ----------------------------------------------------------- internals
250
+ def _sinkhorn(
251
+ self,
252
+ C: torch.Tensor,
253
+ a: torch.Tensor,
254
+ b: torch.Tensor,
255
+ reg: float,
256
+ n_iter: int = 1000,
257
+ thresh: float = 1e-9,
258
+ ) -> torch.Tensor:
259
+ """
260
+ Differentiable Sinkhorn in log-domain.
261
+
262
+ Returns a coupling matrix gamma with the same grad history as C.
263
+ """
264
+ n, m = C.shape
265
+ # numerical stability: shift cost
266
+ C_shift = C - C.min()
267
+ K = -C_shift / reg
268
+
269
+ u = torch.full((n,), -float('inf'), device=C.device, dtype=C.dtype)
270
+ v = torch.full((m,), -float('inf'), device=C.device, dtype=C.dtype)
271
+
272
+ # log a, log b
273
+ log_a = torch.log(a + 1e-30)
274
+ log_b = torch.log(b + 1e-30)
275
+
276
+ # initialize u from log_b / K column sums
277
+ K_log = K
278
+ # first row normalization
279
+ u = log_a.clone()
280
+ v = torch.full_like(log_b, -float('inf'))
281
+
282
+ for _ in range(n_iter):
283
+ # v = log_b - log(K^T exp(u))
284
+ Ku = torch.logsumexp(K_log + u.unsqueeze(-1), dim=0) # (m,)
285
+ v_new = log_b - Ku
286
+ # u = log_a - log(K exp(v))
287
+ Kv = torch.logsumexp(K_log + v_new.unsqueeze(0), dim=1) # (n,)
288
+ u_new = log_a - Kv
289
+
290
+ if torch.allclose(u, u_new, atol=thresh, rtol=thresh):
291
+ u, v = u_new, v_new
292
+ break
293
+ u, v = u_new, v_new
294
+
295
+ # gamma = diag(exp(u)) K diag(exp(v))
296
+ log_gamma = u.unsqueeze(-1) + K_log + v.unsqueeze(0)
297
+ self._gamma = torch.exp(log_gamma)
298
+ return self._gamma
299
+
300
+ @staticmethod
301
+ def _hungarian(C_np: np.ndarray) -> Tuple[np.ndarray, np.ndarray]:
302
+ from scipy.optimize import linear_sum_assignment
303
+ n, m = C_np.shape
304
+ size = max(n, m)
305
+ C_sq = np.full((size, size), C_np.max() + 1.0)
306
+ C_sq[:n, :m] = C_np
307
+ row_ind, col_ind = linear_sum_assignment(C_sq)
308
+ valid = (row_ind < n) & (col_ind < m)
309
+ return np.column_stack([row_ind[valid], col_ind[valid]])
310
+
311
+ def _normalize_marginals(
312
+ self, m, n: int, name: str
313
+ ) -> torch.Tensor:
314
+ if m is None:
315
+ return torch.full((n,), 1.0 / n, dtype=self.dtype,
316
+ device=self.device or "cpu")
317
+ if isinstance(m, np.ndarray):
318
+ m = torch.from_numpy(np.ascontiguousarray(m))
319
+ m = m.to(dtype=self.dtype, device=self.device or m.device)
320
+ if m.shape[0] != n:
321
+ raise ValueError(f"{name} has length {m.shape[0]}, expected {n}.")
322
+ if (m < 0).any():
323
+ raise ValueError(f"{name} must be non-negative.")
324
+ s = m.sum()
325
+ if s <= 0:
326
+ raise ValueError(f"{name} sums to zero.")
327
+ return m / s
328
+
329
+ @staticmethod
330
+ def _balanced_indices(n, m):
331
+ # placeholder for a future lp-based balanced assignment
332
+ return None, None
333
+
334
+
335
+ def _self_marginals(model: "GrassmannOT"):
336
+ """Return uniform marginals matching the current cost-matrix shape."""
337
+ if model._C is None:
338
+ raise RuntimeError("No cost matrix available.")
339
+ n, m = model._C.shape
340
+ dev, dtype = model._C.device, model._C.dtype
341
+ a = torch.full((n,), 1.0 / n, device=dev, dtype=dtype)
342
+ b = torch.full((m,), 1.0 / m, device=dev, dtype=dtype)
343
+ return a, b
grassmann_ot/_utils.py ADDED
@@ -0,0 +1,71 @@
1
+ """
2
+ Shared utilities: type coercion, device inference, optional-dependency checks.
3
+ """
4
+
5
+ from typing import Tuple, Union
6
+
7
+ import numpy as np
8
+ import torch
9
+
10
+ _PYTENSOR = (torch.Tensor,)
11
+
12
+
13
+ def as_tensor(
14
+ obj: Union[np.ndarray, torch.Tensor],
15
+ torch_out: bool = True,
16
+ ):
17
+ """Convert ndarray / tensor-like to a torch tensor or a contiguous ndarray."""
18
+ if isinstance(obj, torch.Tensor):
19
+ if torch_out:
20
+ return obj
21
+ return obj.detach().cpu().numpy()
22
+ arr = np.asarray(obj)
23
+ if arr.ndim == 0:
24
+ arr = arr.reshape(1)
25
+ if torch_out:
26
+ return torch.from_numpy(np.ascontiguousarray(arr))
27
+ return np.ascontiguousarray(arr)
28
+
29
+
30
+ def as_float64(obj: Union[np.ndarray, torch.Tensor]) -> np.ndarray:
31
+ """Convert to a 2-D float64 NumPy array (for sklearn / SciPy inputs)."""
32
+ if isinstance(obj, torch.Tensor):
33
+ obj = obj.detach().cpu().numpy()
34
+ arr = np.asarray(obj, dtype=np.float64)
35
+ if arr.ndim != 2:
36
+ raise ValueError(f"Expected a 2-D array, got {arr.ndim}-D.")
37
+ return arr
38
+
39
+
40
+ def _device(*args) -> torch.device:
41
+ """Infer a common device from tensor inputs."""
42
+ for a in args:
43
+ if isinstance(a, torch.Tensor):
44
+ return a.device
45
+ return torch.device("cpu")
46
+
47
+
48
+ def _check_init(
49
+ device: Union[str, torch.device, None],
50
+ dtype: Union[torch.dtype, None],
51
+ *inputs,
52
+ ) -> Tuple[torch.device, torch.dtype]:
53
+ """Pick device / dtype from explicit settings or input tensors."""
54
+ dev = torch.device(device) if device is not None else _device(*inputs)
55
+ if dtype is None:
56
+ dtype = torch.get_default_dtype()
57
+ for a in inputs:
58
+ if isinstance(a, torch.Tensor):
59
+ dtype = a.dtype
60
+ break
61
+ return dev, dtype
62
+
63
+
64
+ def _check_pot():
65
+ try:
66
+ import ot # noqa: F401
67
+ except ImportError as e: # pragma: no cover
68
+ raise ImportError(
69
+ "POT (Python Optimal Transport) is required for hard matching. "
70
+ "Install it with `pip install POT`."
71
+ ) from e
@@ -0,0 +1,112 @@
1
+ Metadata-Version: 2.5
2
+ Name: grassmann-ot
3
+ Version: 0.2.0
4
+ Summary: Differentiable cell-to-cell anchoring via Grassmann subspace distance and Optimal Transport (PyTorch backend).
5
+ Project-URL: Homepage, https://github.com/ZengFLab/grassmann-ot
6
+ Project-URL: Issues, https://github.com/ZengFLab/grassmann-ot/issues
7
+ Author-email: Your Name <you@example.com>
8
+ License: 404: Not Found
9
+ License-File: LICENSE
10
+ Keywords: anchors,deep-learning,grassmann,optimal-transport,pytorch,single-cell
11
+ Classifier: License :: OSI Approved :: MIT License
12
+ Classifier: Operating System :: OS Independent
13
+ Classifier: Programming Language :: Python :: 3
14
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
15
+ Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
16
+ Requires-Python: >=3.8
17
+ Requires-Dist: numpy>=1.20
18
+ Requires-Dist: pot>=0.8
19
+ Requires-Dist: scikit-learn>=1.0
20
+ Requires-Dist: scipy>=1.6
21
+ Requires-Dist: torch>=1.10
22
+ Provides-Extra: dev
23
+ Requires-Dist: pytest>=7.0; extra == 'dev'
24
+ Provides-Extra: test
25
+ Requires-Dist: pytest>=7.0; extra == 'test'
26
+ Description-Content-Type: text/markdown
27
+
28
+ # grassmann-ot
29
+
30
+ Differentiable cell-to-cell anchoring via **Grassmann subspace distance + Optimal
31
+ Transport**, backed by PyTorch. Compute your gene-program composition matrices
32
+ `H_X` and `H_Y` with any tool (NMF, scVI, Harmony, PCA, BiDictionaryNMF...),
33
+ then let `GrassmannOT` turn them into soft / hard cell anchors with gradients.
34
+
35
+ This is the **PyTorch / differentiable** edition (v0.2.0). The public API is
36
+ identical to the NumPy edition; the only additions are gradient support and
37
+ PyTorch device / dtype control.
38
+
39
+ ## Install
40
+
41
+ ```bash
42
+ pip install grassmann-ot
43
+ ```
44
+
45
+ Or from source:
46
+
47
+ ```bash
48
+ git clone https://github.com/yourname/grassmann-ot.git
49
+ cd grassmann-ot
50
+ pip install .
51
+ ```
52
+
53
+ ## Quick start
54
+
55
+ ```python
56
+ import torch
57
+ from grassmann_ot import GrassmannOT
58
+
59
+ # H_X, H_Y: (r, n_cells) from YOUR tool of choice.
60
+ # Tensors with requires_grad=True make the whole pipeline differentiable.
61
+ H_X = torch.rand(20, 300, requires_grad=True)
62
+ H_Y = torch.rand(20, 250, requires_grad=True)
63
+
64
+ ot = GrassmannOT(k=30, p=3, reg=0.1)
65
+ gamma = ot.fit(H_X, H_Y) # soft coupling, shape (n_X, n_Y)
66
+
67
+ # Gradients flow back to H_X / H_Y through the Grassmann distance and Sinkhorn
68
+ loss = gamma.sum()
69
+ loss.backward()
70
+
71
+ # Hard one-to-one anchors (Hungarian, no gradients)
72
+ matches = ot.fit(H_X, H_Y, return_hard=True)
73
+ ```
74
+
75
+ ## Parameters
76
+
77
+ | Parameter | Default | Meaning |
78
+ |-----------|---------|---------|
79
+ | `k` | 30 | Neighborhood size for local subspace |
80
+ | `p` | 3 | Subspace dimension |
81
+ | `metric` | cosine | Neighbor metric in composition space |
82
+ | `reg` | 0.1 | Entropic regularization for Sinkhorn |
83
+ | `a`, `b` | None | Source / target marginals (uniform if None) |
84
+ | `k_iter` | 10 | Gradient iterations for basis refinement |
85
+
86
+ `fit(H_X, H_Y, requires_grad=False)` drops the gradient path and runs fully in
87
+ `torch.no_grad()` for lower memory and faster execution.
88
+
89
+ ## Low-level API
90
+
91
+ ```python
92
+ from grassmann_ot import cells_to_grassmann, grassmann_cost_matrix
93
+
94
+ U = cells_to_grassmann(H_X, k=30, p=3)
95
+ V = cells_to_grassmann(H_Y, k=30, p=3)
96
+ C = grassmann_cost_matrix(U, V) # (n_X, n_Y), differentiable w.r.t. U, V
97
+ ```
98
+
99
+ The returned bases are PyTorch tensors (stored in a `GrassmannPoints` container)
100
+ and can be moved with `.to(device)`, detached with `.detach()`, or converted
101
+ back to NumPy with `.numpy()`.
102
+
103
+ ## Why "differentiable"?
104
+
105
+ - kNN graph construction runs once on CPU (non-differentiable, expected).
106
+ - Local subspaces are fitted by optimizing an orthonormal basis on the Stiefel
107
+ manifold, so each basis has a gradient path back to its neighborhood.
108
+ - The cost `C[i,j] = p - ||U_i^T V_j||_F^2` is a smooth function of the bases.
109
+ - Sinkhorn is implemented in the log-domain and is fully differentiable.
110
+
111
+ This lets you embed `GrassmannOT` inside a larger model and train end to end,
112
+ for example by adding an OT loss to a gene-program inference network.
@@ -0,0 +1,8 @@
1
+ grassmann_ot/__init__.py,sha256=L5CXqKVxWyy018gte46Ng06wj-lX_Av76YzttbbTL1E,701
2
+ grassmann_ot/_grassmann.py,sha256=qf_z7cVvN2No7zdT-xvFci6B5P7V99f59udQinUd3xM,10125
3
+ grassmann_ot/_ot.py,sha256=ueB87usGEzrf_DPl9Zev_dJzVfv1M0WV_kMZ7byVj7o,11846
4
+ grassmann_ot/_utils.py,sha256=OFbiTisDFyFwpuvcn5fyCTj69g3_-Q0lgYQJEYChZuM,2042
5
+ grassmann_ot-0.2.0.dist-info/METADATA,sha256=VdTCOxM7LKpjDV7x48IpUnMKppkC8YlOl0bonvIxCMQ,3977
6
+ grassmann_ot-0.2.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
7
+ grassmann_ot-0.2.0.dist-info/licenses/LICENSE,sha256=1VWM1BnI1GvclYBky5f5Y9HqeThmQUwCWQbsFQM1Eu0,14
8
+ grassmann_ot-0.2.0.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.33.0
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -0,0 +1 @@
1
+ 404: Not Found