fastlinkage 0.1.1__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,6 @@
1
+ """Exact hierarchical clustering on the GPU, without the n x n distance matrix."""
2
+ from .cluster import AgglomerativeClustering, cut
3
+ from .core import METHODS, linkage
4
+
5
+ __version__ = "0.1.1"
6
+ __all__ = ["linkage", "cut", "AgglomerativeClustering", "METHODS"]
@@ -0,0 +1,274 @@
1
+ """Cluster summaries, nearest neighbours and the neighbour lists that survive merges.
2
+
3
+ Cluster ids: the n points are 0 .. n-1 and every merge makes the next id, so
4
+ there are at most 2n - 1. All arrays here are indexed by cluster id.
5
+ """
6
+ import time
7
+ import warnings
8
+
9
+ import numpy as np
10
+ import torch
11
+
12
+ from ._distance import exact_key
13
+
14
+
15
+ def _float64_fits(device, nbytes):
16
+ """Whether a float64 array of nbytes can live on the device next to the search."""
17
+ if torch.device(device).type != "cuda": # MPS has no float64
18
+ return False
19
+ free, _ = torch.cuda.mem_get_info(device)
20
+ return nbytes <= free // 4
21
+
22
+
23
+ class Clusters:
24
+ """State of a run: one summary, one nearest neighbour and one neighbour
25
+ list per cluster.
26
+
27
+ The neighbour list of cluster c is up to `width` clusters with their exact
28
+ keys, nearest first, and a radius: every cluster that holds no member of
29
+ the list has a key to c of at least the radius. That stays true after any
30
+ merges (the linkages are reducible), so when c's nearest neighbour is
31
+ merged away the next one can usually be read off the list.
32
+ """
33
+
34
+ def __init__(self, X, method, device, width):
35
+ n, d = X.shape
36
+ total = 2 * n - 1
37
+ self.method, self.device, self.width, self.n = method, device, width, n
38
+ self.C = np.empty((total, d)) # cluster means, float64
39
+ self.C[:n] = X
40
+ self.G = torch.empty((total, d), dtype=torch.float32, device=device) # float32 copy on the device
41
+ self.G[:n] = torch.from_numpy(X.astype(np.float32)).to(device)
42
+ # float64 means for the exact keys: on the device when it supports
43
+ # float64 and has room (CUDA), otherwise the numpy array itself
44
+ self.on_device64 = _float64_fits(device, total * d * 8)
45
+ if self.on_device64:
46
+ self.C64 = torch.empty((total, d), dtype=torch.float64, device=device)
47
+ self.C64[:n] = torch.from_numpy(X).to(device)
48
+ else:
49
+ self.C64 = torch.from_numpy(self.C) # shares memory; threaded on the CPU
50
+ self.size = np.ones(total)
51
+ self.var = np.zeros(total) # mean squared distance to the cluster mean
52
+ self.norm = np.zeros(total)
53
+ self.norm[:n] = np.sqrt(np.einsum("ij,ij->i", X, X))
54
+ self.rep = np.arange(total) # one member point of each cluster
55
+ self.succ = np.arange(total) # the cluster this one was merged into
56
+ self.gone = np.zeros(total, bool)
57
+ self.nn_id = np.full(total, -1, np.int64)
58
+ self.nn_key = np.full(total, np.inf)
59
+ self.valid = np.zeros(total, bool) # nn_id is the true nearest neighbour right now
60
+ self.L_id = np.full((total, width), -1, np.int64) # neighbour list, nearest first
61
+ self.L_key = np.full((total, width), np.inf)
62
+ self.rad = np.full(total, -np.inf) # every cluster outside the list is at least this far
63
+ self.next_id = n
64
+ self.stats = {"rounds": [], "t_gpu": 0.0, "t_verify": 0.0, "t_cache": 0.0, "pair_evals": 0,
65
+ "full_searches": 0, "rechecked": 0, "fresh_hits": 0, "fresh_total": 0,
66
+ "orphan_hits": 0, "orphan_total": 0, "tie_rounds": 0, "recheck_pairs": 0}
67
+
68
+ # ---- exact keys and current cluster ids ----
69
+
70
+ def exact(self, q, c):
71
+ """Float64 keys for cluster ids q (n,) against c (n, w), in chunks."""
72
+ out = np.empty(c.shape)
73
+ step = max(1, (1 << 25) // (c.shape[1] * self.C.shape[1]))
74
+ for s in range(0, len(q), step):
75
+ out[s:s + step] = exact_key(self.method, self.C64, self.size, self.var, q[s:s + step], c[s:s + step])
76
+ return out
77
+
78
+ def find(self, ids):
79
+ """Current cluster of each id (-1 stays -1)."""
80
+ cur = ids.copy()
81
+ while True:
82
+ nxt = np.where(cur < 0, -1, self.succ[cur])
83
+ if np.array_equal(nxt, cur):
84
+ return cur
85
+ cur = nxt
86
+
87
+ # ---- neighbour lists ----
88
+
89
+ def store(self, q, ids, keys, r):
90
+ """Set the neighbour lists of clusters q from candidates with exact keys.
91
+
92
+ Outside the candidates every cluster is at least r away. Returns which
93
+ clusters got a nearest neighbour out of it."""
94
+ W = self.width
95
+ keys = np.where((ids >= 0) & (keys <= r[:, None]), keys, np.inf)
96
+ o = np.lexsort((ids, keys), axis=1)
97
+ ids = np.take_along_axis(ids, o, 1)
98
+ keys = np.take_along_axis(keys, o, 1)
99
+ dup = (ids[:, 1:] == ids[:, :-1]) & np.isfinite(keys[:, 1:])
100
+ if dup.any():
101
+ keys[:, 1:][dup] = np.inf
102
+ o = np.lexsort((ids, keys), axis=1)
103
+ ids = np.take_along_axis(ids, o, 1)
104
+ keys = np.take_along_axis(keys, o, 1)
105
+ if ids.shape[1] > W:
106
+ r = np.minimum(r, keys[:, W]) # the nearest entry that does not fit
107
+ ids, keys = ids[:, :W], keys[:, :W]
108
+ ids = np.where(np.isfinite(keys), ids, -1)
109
+ self.L_id[q, :] = -1
110
+ self.L_key[q, :] = np.inf
111
+ self.L_id[q, :ids.shape[1]] = ids
112
+ self.L_key[q, :ids.shape[1]] = keys
113
+ self.rad[q] = r
114
+ ok = ids[:, 0] >= 0
115
+ self.nn_id[q[ok]] = ids[ok, 0]
116
+ self.nn_key[q[ok]] = keys[ok, 0]
117
+ self.valid[q[ok]] = True
118
+ return ok
119
+
120
+ def from_lists(self, q, ids, r, known=None):
121
+ """Try to settle clusters q from inherited list entries `ids` (n, w).
122
+
123
+ known: the keys of those entries, if q are old clusters (entries that
124
+ were not merged keep their key). Returns which clusters were settled."""
125
+ cur = self.find(ids)
126
+ cur[cur == q[:, None]] = -1
127
+ if known is None: # two parents' lists overlap: drop repeats
128
+ cur = np.sort(cur, axis=1)
129
+ cur[:, 1:][cur[:, 1:] == cur[:, :-1]] = -1
130
+ keys = np.full(cur.shape, np.inf)
131
+ need = cur >= 0
132
+ if known is not None:
133
+ same = need & (cur == ids)
134
+ keys[same] = known[same]
135
+ need &= ~same
136
+ rows, cols = np.nonzero(need)
137
+ if len(rows):
138
+ keys[rows, cols] = self.exact(q[rows], cur[rows, cols][:, None])[:, 0]
139
+ return self.store(q, cur, keys, r)
140
+
141
+ def inherited_radius(self, a, b):
142
+ """Radius for the lists a new cluster a+b inherits: a lower bound on its
143
+ key to any cluster that holds no member of either parent's list."""
144
+ sa, sb, ra, rb = self.size[a], self.size[b], self.rad[a], self.rad[b]
145
+ if self.method != "ward": # the key to a+b is the size-weighted mean
146
+ r = (sa * ra + sb * rb) / (sa + sb)
147
+ else:
148
+ # Lance-Williams for Ward, with x = size of the third cluster:
149
+ # key >= (sa ra + sb rb + x (ra + rb - key(a, b))) / (sa + sb + x),
150
+ # monotone in x, so the minimum is at x = 1 or x = infinity
151
+ g = ra + rb - self.nn_key[a]
152
+ r = np.minimum((sa * ra + sb * rb + g) / (sa + sb + 1.0), g)
153
+ with np.errstate(invalid="ignore"):
154
+ return np.where(np.isfinite(r), r - 1e-12 * np.abs(r), r)
155
+
156
+ def refresh_from_lists(self, active, fresh, pa, pb):
157
+ """Before a search: settle the new clusters `fresh` (parents pa, pb) and
158
+ the old clusters whose neighbour was merged away, from their lists."""
159
+ stats = self.stats
160
+ t0 = time.perf_counter()
161
+ ids = np.concatenate((self.L_id[pa], self.L_id[pb]), 1)
162
+ ok = self.from_lists(fresh, ids, self.inherited_radius(pa, pb))
163
+ stats["fresh_hits"] += int(ok.sum())
164
+ stats["fresh_total"] += len(fresh)
165
+ old = active[: len(active) - len(fresh)]
166
+ orphans = old[~self.valid[old]]
167
+ ok = self.from_lists(orphans, self.L_id[orphans], self.rad[orphans], known=self.L_key[orphans])
168
+ stats["orphan_hits"] += int(ok.sum())
169
+ stats["orphan_total"] += len(orphans)
170
+ stats["t_cache"] += time.perf_counter() - t0
171
+
172
+ # ---- full search ----
173
+
174
+ def full_search(self, searcher, query):
175
+ """Nearest neighbour and neighbour list of every cluster in query, from
176
+ a float32 search on the device checked in float64."""
177
+ stats = self.stats
178
+ t0 = time.perf_counter()
179
+ cand, r = searcher.candidates(query)
180
+ stats["t_gpu"] += time.perf_counter() - t0
181
+ stats["pair_evals"] += len(query) * searcher.m
182
+ stats["full_searches"] += len(query)
183
+ t0 = time.perf_counter()
184
+ cand = np.where(cand < 0, query[:, None], cand)
185
+ keys = self.exact(query, cand)
186
+ keys[cand == query[:, None]] = np.inf
187
+ best = keys.min(1)
188
+ sure = best <= r
189
+ self.store(query[sure], cand[sure], keys[sure], r[sure])
190
+ stats["t_verify"] += time.perf_counter() - t0
191
+ if sure.all():
192
+ return
193
+ # float32 could not separate the best candidate from the other columns:
194
+ # fetch every column that could be nearer and check it in float64
195
+ q = query[~sure]
196
+ t0 = time.perf_counter()
197
+ qi, ci = searcher.within(q, best[~sure])
198
+ stats["t_gpu"] += time.perf_counter() - t0
199
+ stats["pair_evals"] += len(q) * searcher.m
200
+ stats["rechecked"] += len(q)
201
+ stats["recheck_pairs"] += len(qi)
202
+ if not stats.get("warned") and stats["recheck_pairs"] > 50 * self.n + 1_000_000:
203
+ stats["warned"] = True
204
+ warnings.warn("many neighbours are closer together than float32 can resolve; "
205
+ "they are being checked in float64 on the CPU, which is slow", stacklevel=3)
206
+ t0 = time.perf_counter()
207
+ ek = self.exact(q[qi], ci[:, None])[:, 0]
208
+ o = np.lexsort((ci, ek, qi))
209
+ qi, ci, ek = qi[o], ci[o], ek[o]
210
+ first = np.r_[True, qi[1:] != qi[:-1]]
211
+ q = q[qi[first]]
212
+ self.L_id[q, :] = -1
213
+ self.L_key[q, :] = np.inf
214
+ self.L_id[q, 0] = ci[first]
215
+ self.L_key[q, 0] = ek[first]
216
+ self.rad[q] = ek[first]
217
+ self.nn_id[q] = ci[first]
218
+ self.nn_key[q] = ek[first]
219
+ self.valid[q] = True
220
+ stats["t_verify"] += time.perf_counter() - t0
221
+
222
+ # ---- choosing and applying merges ----
223
+
224
+ def reciprocal_pairs(self, active):
225
+ """The smaller id of every pair of clusters that are each other's nearest neighbour."""
226
+ a = active[self.valid[active]]
227
+ b = self.nn_id[a]
228
+ keep = self.valid[b] & (self.nn_id[b] == a) & (a < b)
229
+ return a[keep]
230
+
231
+ def tied_pairs(self, active):
232
+ """Fallback when no pair is reciprocal, which happens only with exact ties.
233
+
234
+ Any pair at the smallest key is a valid next merge, and stays one after
235
+ other pairs at that key have merged, so take as many disjoint ones as
236
+ there are."""
237
+ kmin = self.nn_key[active].min()
238
+ used, xs, ys = set(), [], []
239
+ for x in active[self.nn_key[active] == kmin].tolist():
240
+ y = int(self.nn_id[x])
241
+ if x not in used and y not in used:
242
+ used.update((x, y))
243
+ xs.append(min(x, y))
244
+ ys.append(max(x, y))
245
+ a = np.array(xs)
246
+ self.nn_id[a] = ys
247
+ self.nn_key[a] = kmin
248
+ self.stats["tie_rounds"] += 1
249
+ return a
250
+
251
+ def merge(self, a, b):
252
+ """Merge clusters a[i] and b[i] for every i; returns the new cluster ids."""
253
+ C, size, var = self.C, self.size, self.var
254
+ p = len(a)
255
+ new = np.arange(self.next_id, self.next_id + p)
256
+ self.next_id += p
257
+ sa, sb = size[a], size[b]
258
+ sn = sa + sb
259
+ C[new] = (C[a] * sa[:, None] + C[b] * sb[:, None]) / sn[:, None]
260
+ self.norm[new] = np.sqrt(np.einsum("ij,ij->i", C[new], C[new]))
261
+ self.G[new[0]:new[0] + p] = torch.from_numpy(C[new].astype(np.float32)).to(self.device)
262
+ if self.on_device64:
263
+ self.C64[new[0]:new[0] + p] = torch.from_numpy(C[new]).to(self.device)
264
+ if self.method == "average_sqeuclidean":
265
+ da = np.einsum("ij,ij->i", C[a] - C[new], C[a] - C[new])
266
+ db = np.einsum("ij,ij->i", C[b] - C[new], C[b] - C[new])
267
+ var[new] = (sa * (var[a] + da) + sb * (var[b] + db)) / sn
268
+ size[new] = sn
269
+ self.rep[new] = self.rep[a]
270
+ self.succ[a] = new
271
+ self.succ[b] = new
272
+ self.gone[a] = True
273
+ self.gone[b] = True
274
+ return new
@@ -0,0 +1,40 @@
1
+ """Cluster-to-cluster distances from cluster summaries, in float64.
2
+
3
+ Each supported linkage has a "key": a number that orders pairs of clusters the
4
+ same way the linkage distance does, and that follows from each cluster's size,
5
+ mean vector and (for one linkage) a variance.
6
+
7
+ ward |A||B| / (|A|+|B|) * ||mean(A) - mean(B)||^2
8
+ (the merge height is sqrt(2 * key))
9
+ average_cosine 1 - mean(A) . mean(B) (rows scaled to unit length)
10
+ average_sqeuclidean ||mean(A) - mean(B)||^2 + var(A) + var(B)
11
+ where var is the mean squared distance to the cluster mean
12
+ """
13
+ import numpy as np
14
+ import torch
15
+
16
+ METHODS = ("ward", "average_cosine", "average_sqeuclidean")
17
+
18
+
19
+ def exact_key(method, Ct, size, var, q, c):
20
+ """Key between each cluster id in q (n,) and its candidates c (n, k).
21
+
22
+ Ct holds the cluster means as a float64 tensor (one row per cluster id),
23
+ on the CPU or on a device that supports float64. size and var are the
24
+ cluster sizes and variances (numpy)."""
25
+ cq = Ct[torch.from_numpy(q).to(Ct.device)]
26
+ cc = Ct[torch.from_numpy(c).to(Ct.device)]
27
+ if method == "average_cosine":
28
+ return 1.0 - torch.einsum("nd,nkd->nk", cq, cc).cpu().numpy()
29
+ diff = cc - cq[:, None, :]
30
+ d2 = torch.einsum("nkd,nkd->nk", diff, diff).cpu().numpy()
31
+ sq = size[q][:, None]
32
+ if method == "ward":
33
+ return d2 * (sq * size[c] / (sq + size[c]))
34
+ return d2 + var[q][:, None] + var[c]
35
+
36
+
37
+ def height(method, key):
38
+ """Merge height, as scipy reports it, from a key."""
39
+ key = np.maximum(key, 0.0) # duplicate rows can give -1e-16 from rounding
40
+ return np.sqrt(2.0 * key) if method == "ward" else key
fastlinkage/_search.py ADDED
@@ -0,0 +1,179 @@
1
+ """Nearest-neighbour search among the active clusters, in float32 on the device."""
2
+ import numpy as np
3
+ import torch
4
+
5
+ MAX_SIZE_GROUPS = 24 # Ward: sort columns by cluster size while there are this few sizes
6
+ FLOAT32_ROUNDOFF = 6e-8 # float32 unit roundoff
7
+
8
+
9
+ class Searcher:
10
+ """Nearest-neighbour candidates among the active clusters, on the device.
11
+
12
+ The float32 key comes out of a single matrix product: the squared distance
13
+ (plus the variance term, for average linkage) is folded into extra columns.
14
+ The columns are cut into a few hundred equal segments and one pass takes
15
+ the minimum of each. The k segments with the smallest minima supply the
16
+ candidates. A second look at just those k segments finds their runners-up,
17
+ which gives a lower bound on every column that is not a candidate.
18
+
19
+ Ward's key also has the factor |A||B| / (|A|+|B|). While there are few
20
+ distinct cluster sizes, the columns are sorted by size and padded so every
21
+ segment holds one size; the factor is then applied to the segment minima.
22
+ Otherwise it is applied to the whole block.
23
+ """
24
+
25
+ BIG = 1e30
26
+
27
+ def __init__(self, method, G, size, var, norm, active, k, segs, budget, device):
28
+ self.method = method
29
+ self.device = device
30
+ self.size, self.var, self.norm = size, var, norm
31
+ m = len(active)
32
+ self.m = m
33
+ d = G.shape[1]
34
+ s_act = size[active]
35
+ self.ward_div = False
36
+ self.grouped = False
37
+ w = max(1, -(-m // segs))
38
+ self.w = w
39
+ if method == "ward":
40
+ uniq, counts = np.unique(s_act, return_counts=True)
41
+ if len(uniq) <= MAX_SIZE_GROUPS:
42
+ self.grouped = True
43
+ else:
44
+ self.ward_div = True
45
+ if self.grouped:
46
+ order = np.argsort(s_act, kind="stable")
47
+ nseg = -(-counts // w)
48
+ cols = np.full(int(nseg.sum()) * w, -1, np.int64)
49
+ start = np.r_[0, np.cumsum(nseg[:-1])] * w
50
+ src = 0
51
+ for st, c in zip(start, counts, strict=True):
52
+ cols[st:st + c] = active[order[src:src + c]]
53
+ src += c
54
+ seg_size = np.repeat(uniq, nseg).astype(np.float32)
55
+ self.seg_size64 = np.repeat(uniq, nseg).astype(np.float64)
56
+ self.seg_size = torch.from_numpy(seg_size).to(device)
57
+ else:
58
+ cols = np.full(-(-m // w) * w, -1, np.int64)
59
+ cols[:m] = active
60
+ self.cols = cols # cluster id of each device column, -1 = padding
61
+ self.S = len(cols) // w
62
+ self.kk = min(k, self.S)
63
+ self.rows = max(1, budget // len(cols))
64
+ real = cols >= 0
65
+ Cg = G.index_select(0, torch.from_numpy(np.maximum(cols, 0)).to(device))
66
+ if not real.all():
67
+ Cg = Cg * torch.from_numpy(real.astype(np.float32)).to(device)[:, None]
68
+ pad = torch.from_numpy(np.where(real, 0.0, self.BIG).astype(np.float32)).to(device)[:, None]
69
+ one = torch.ones_like(pad)
70
+ if method == "average_cosine":
71
+ self.A_t = torch.cat((-Cg, pad), 1).T.contiguous() # key = -dot
72
+ self.Q = torch.cat((Cg, one), 1)
73
+ else:
74
+ n2 = (Cg * Cg).sum(1, keepdim=True)
75
+ extra = n2 + pad
76
+ if method == "average_sqeuclidean":
77
+ vp = np.zeros(len(cols), np.float32)
78
+ vp[real] = var[cols[real]]
79
+ extra = extra + torch.from_numpy(vp).to(device)[:, None]
80
+ self.A_t = torch.cat((-2.0 * Cg, one, extra), 1).T.contiguous()
81
+ self.Q = torch.cat((Cg, n2, one), 1) # Q @ A_t = squared distance (+ column variance)
82
+ if self.ward_div:
83
+ sp = np.ones(len(cols), np.float32)
84
+ sp[real] = s_act
85
+ self.inv = 1.0 / torch.from_numpy(sp).to(device)
86
+ self.col_of = np.full(len(size), -1, np.int64)
87
+ self.col_of[cols[real]] = np.nonzero(real)[0]
88
+ # float32 rounding bound on a key, relative to the sum of the absolute terms
89
+ self.gamma = 4.0 * (d + 4) * FLOAT32_ROUNDOFF
90
+ self.amax = float(norm[active].max())
91
+ self.vmax = float(var[active].max())
92
+
93
+ def _err(self, query):
94
+ if self.method == "average_cosine":
95
+ return np.full(len(query), self.gamma)
96
+ return self.gamma * ((self.norm[query] + self.amax) ** 2 + self.var[query] + self.vmax)
97
+
98
+ def _shift(self, query):
99
+ """exact key = float32 key + shift, for the two average linkages."""
100
+ if self.method == "average_cosine":
101
+ return np.ones(len(query))
102
+ if self.method == "average_sqeuclidean":
103
+ return self.var[query]
104
+ return np.zeros(len(query))
105
+
106
+ def _keys(self, qc):
107
+ key = self.Q[qc] @ self.A_t
108
+ if self.ward_div:
109
+ key.div_(self.inv[qc][:, None] + self.inv[None, :])
110
+ key[torch.arange(len(qc), device=self.device), qc] = float("inf")
111
+ return key.view(len(qc), self.S, self.w)
112
+
113
+ def _low(self, v, err, sq, segs=None):
114
+ """Lower bound (float32) on the exact key, up to the shift, from float32 keys v."""
115
+ if self.ward_div:
116
+ return v - 1e-5 * v.abs() - err * sq
117
+ low = v - err
118
+ if self.grouped:
119
+ gs = self.seg_size[None, :] if segs is None else self.seg_size[segs]
120
+ low = low * (sq * gs / (sq + gs))
121
+ return low
122
+
123
+ def _dev(self, x):
124
+ return torch.from_numpy(np.asarray(x, np.float32)).to(self.device)[:, None]
125
+
126
+ def candidates(self, query):
127
+ """Candidate cluster ids (n, k), -1 for none, and per query a float64
128
+ radius: every active cluster that is not a candidate has an exact key
129
+ of at least that."""
130
+ qcol = torch.from_numpy(self.col_of[query]).to(self.device)
131
+ err = self._dev(self._err(query) * 1.001)
132
+ sq = self._dev(self.size[query])
133
+ kk, w = self.kk, self.w
134
+ inf = float("inf")
135
+ out, rad = [], []
136
+ for s in range(0, len(query), self.rows):
137
+ qc = qcol[s:s + self.rows]
138
+ e, z = err[s:s + self.rows], sq[s:s + self.rows]
139
+ k3 = self._keys(qc)
140
+ q = len(qc)
141
+ i = k3.argmin(2) # best of every segment
142
+ v = k3.gather(2, i[:, :, None])[:, :, 0]
143
+ vals, order = self._low(v, e, z).sort(1)
144
+ chosen = order[:, :kk]
145
+ imin = i.gather(1, chosen)
146
+ rows = (chosen + self.S * torch.arange(q, device=self.device)[:, None]).reshape(-1)
147
+ sub = k3.reshape(q * self.S, w).index_select(0, rows)
148
+ sub.scatter_(1, imin.reshape(-1, 1), inf)
149
+ r = self._low(sub.amin(1).view(q, kk), e, z, chosen).amin(1) # runners-up of the chosen segments
150
+ if self.S > kk:
151
+ r = torch.minimum(r, vals[:, kk]) # best of the segments not chosen
152
+ out.append(chosen * w + imin)
153
+ rad.append(r)
154
+ cand = self.cols[torch.cat(out).cpu().numpy()]
155
+ r = torch.cat(rad).cpu().numpy().astype(np.float64)
156
+ with np.errstate(invalid="ignore"):
157
+ r = np.where(r > 1e29, np.inf, r - 4e-6 * np.abs(r)) # float32 arithmetic in _low
158
+ return cand, r + self._shift(query)
159
+
160
+ def within(self, query, key):
161
+ """All (query index, cluster id) pairs whose exact key could be below key (n,)."""
162
+ err = self._err(query) * 1.001
163
+ if self.grouped:
164
+ sq = self.size[query][:, None]
165
+ gs = self.seg_size64[None, :]
166
+ thr = key[:, None] * (sq + gs) / (sq * gs) + err[:, None]
167
+ elif self.ward_div:
168
+ thr = (key + 1e-5 * np.abs(key) + err * self.size[query])[:, None]
169
+ else:
170
+ thr = (key - self._shift(query) + err)[:, None]
171
+ thr = thr + 4e-6 * np.abs(thr)
172
+ thr = torch.from_numpy(thr.astype(np.float32)).to(self.device)[:, :, None]
173
+ qcol = torch.from_numpy(self.col_of[query]).to(self.device)
174
+ qi, ci = [], []
175
+ for s in range(0, len(query), self.rows):
176
+ nz = (self._keys(qcol[s:s + self.rows]) <= thr[s:s + self.rows]).nonzero().cpu().numpy()
177
+ qi.append(nz[:, 0] + s)
178
+ ci.append(self.cols[nz[:, 1] * self.w + nz[:, 2]])
179
+ return np.concatenate(qi), np.concatenate(ci)
fastlinkage/_tree.py ADDED
@@ -0,0 +1,39 @@
1
+ """Turn the list of merges into scipy's linkage matrix."""
2
+ import numpy as np
3
+
4
+
5
+ def to_scipy(ra, rb, h, n):
6
+ """Linkage matrix in scipy's format from merges given in any order.
7
+
8
+ ra, rb: one member point of each of the two clusters merged; h: the merge
9
+ heights; n: number of points. Merges are sorted by height and the clusters
10
+ numbered the way scipy does."""
11
+ order = np.argsort(h, kind="stable")
12
+ parent = np.arange(n)
13
+ label = np.arange(n)
14
+ csize = np.ones(n, np.int64)
15
+ Z = np.empty((n - 1, 4))
16
+
17
+ def find(x):
18
+ root = x
19
+ while parent[root] != root:
20
+ root = parent[root]
21
+ while parent[x] != root:
22
+ parent[x], x = root, parent[x]
23
+ return root
24
+
25
+ ra = ra.tolist()
26
+ rb = rb.tolist()
27
+ for i, j in enumerate(order.tolist()):
28
+ x = find(ra[j])
29
+ y = find(rb[j])
30
+ lx, ly = int(label[x]), int(label[y])
31
+ Z[i, 0] = min(lx, ly)
32
+ Z[i, 1] = max(lx, ly)
33
+ Z[i, 2] = h[j]
34
+ s = csize[x] + csize[y]
35
+ Z[i, 3] = s
36
+ parent[y] = x
37
+ label[x] = n + i
38
+ csize[x] = s
39
+ return Z
fastlinkage/cluster.py ADDED
@@ -0,0 +1,77 @@
1
+ """Flat clusters from a linkage matrix, and a scikit-learn style estimator."""
2
+ import numpy as np
3
+
4
+ from .core import linkage
5
+
6
+ _METHOD = {("ward", "euclidean"): "ward", ("average", "cosine"): "average_cosine",
7
+ ("average", "sqeuclidean"): "average_sqeuclidean"}
8
+
9
+
10
+ def cut(Z, n_clusters=None, distance_threshold=None):
11
+ """Cluster label (0 .. k-1) of every point after cutting the tree.
12
+
13
+ Give exactly one of:
14
+ n_clusters: stop when this many clusters are left.
15
+ distance_threshold: apply every merge whose height is below it (the
16
+ scikit-learn rule: clusters at or above the threshold are not merged).
17
+ """
18
+ if (n_clusters is None) == (distance_threshold is None):
19
+ raise ValueError("give exactly one of n_clusters and distance_threshold")
20
+ Z = np.asarray(Z)
21
+ n = len(Z) + 1
22
+ if n_clusters is not None:
23
+ if not 1 <= n_clusters <= n:
24
+ raise ValueError(f"n_clusters must be between 1 and {n}")
25
+ k = n - int(n_clusters)
26
+ else:
27
+ k = int(np.searchsorted(Z[:, 2], distance_threshold, side="left"))
28
+ root = np.arange(n + k)
29
+ root[Z[:k, 0].astype(np.int64)] = n + np.arange(k)
30
+ root[Z[:k, 1].astype(np.int64)] = n + np.arange(k)
31
+ while True: # pointer jumping: follow parents to the top
32
+ nxt = root[root]
33
+ if np.array_equal(nxt, root):
34
+ break
35
+ root = nxt
36
+ return np.unique(root[:n], return_inverse=True)[1]
37
+
38
+
39
+ class AgglomerativeClustering:
40
+ """Exact agglomerative clustering with scikit-learn's interface.
41
+
42
+ Supported: linkage="ward" (metric="euclidean"), and linkage="average" with
43
+ metric="cosine" or "sqeuclidean". Set n_clusters, or set n_clusters=None
44
+ and distance_threshold.
45
+
46
+ After fit: labels_, n_clusters_, n_leaves_, children_, distances_, and
47
+ linkage_matrix_ (scipy's format, for scipy.cluster.hierarchy.dendrogram).
48
+ """
49
+
50
+ def __init__(self, n_clusters=2, *, metric="euclidean", linkage="ward",
51
+ distance_threshold=None, device=None):
52
+ self.n_clusters = n_clusters
53
+ self.metric = metric
54
+ self.linkage = linkage
55
+ self.distance_threshold = distance_threshold
56
+ self.device = device
57
+
58
+ def fit(self, X, y=None):
59
+ method = _METHOD.get((self.linkage, self.metric))
60
+ if method is None:
61
+ raise ValueError(
62
+ f"linkage={self.linkage!r} with metric={self.metric!r} is not supported; "
63
+ f"supported pairs: {sorted(_METHOD)}")
64
+ if (self.n_clusters is None) == (self.distance_threshold is None):
65
+ raise ValueError("exactly one of n_clusters and distance_threshold has to be set, "
66
+ "and the other needs to be None")
67
+ Z = linkage(X, method=method, device=self.device)
68
+ self.linkage_matrix_ = Z
69
+ self.children_ = Z[:, :2].astype(np.int64)
70
+ self.distances_ = Z[:, 2]
71
+ self.n_leaves_ = len(Z) + 1
72
+ self.labels_ = cut(Z, self.n_clusters, self.distance_threshold)
73
+ self.n_clusters_ = int(self.labels_.max()) + 1
74
+ return self
75
+
76
+ def fit_predict(self, X, y=None):
77
+ return self.fit(X).labels_
fastlinkage/core.py ADDED
@@ -0,0 +1,144 @@
1
+ """Exact hierarchical clustering without the n x n distance matrix.
2
+
3
+ For some linkages the distance between two clusters depends only on a small
4
+ summary of each cluster (size, mean vector, sometimes one scalar). Those
5
+ linkages can be run from the summaries alone:
6
+
7
+ ward sqrt(2 |A||B| / (|A|+|B|)) * ||mean(A) - mean(B)||
8
+ average, cosine 1 - mean(A) . mean(B) (rows scaled to unit length)
9
+ average, sqeuclidean ||mean(A) - mean(B)||^2 + var(A) + var(B)
10
+ where var is the mean squared distance to the cluster mean
11
+
12
+ All three are "reducible": merging two clusters never brings the result closer
13
+ to a third cluster than both parts were. Three consequences:
14
+
15
+ 1. Every pair of clusters that are each other's nearest neighbour can be
16
+ merged in the same round, and the tree is the same one the usual
17
+ one-merge-at-a-time algorithm builds.
18
+ 2. A cluster's nearest neighbour stays valid until that neighbour itself is
19
+ merged.
20
+ 3. Neighbour lists survive merges (`cache=True`). Say cluster c knows a list
21
+ of clusters with their exact distances, and a radius r such that every
22
+ cluster outside the list is at least r away. After any merges, a cluster
23
+ that contains no list member is still at least r away. So c's new nearest
24
+ neighbour is the nearest of the list members' current clusters, as long
25
+ as that one is within r. A new cluster A+B inherits the lists of A and B
26
+ with a radius computed from r_A and r_B. Only when a list runs dry does
27
+ the cluster go back to the full search.
28
+
29
+ The full search is one big matrix product, which runs on the GPU in float32.
30
+ It returns a few candidates per cluster and the smallest float32 distance
31
+ among all the other columns. The CPU computes the candidates' distances in
32
+ float64. A candidate is accepted only if it beats the other columns by more
33
+ than the float32 rounding bound; otherwise every column inside the bound is
34
+ fetched and checked in float64. Merge decisions and heights are float64.
35
+ """
36
+ import time
37
+
38
+ import numpy as np
39
+ import torch
40
+
41
+ from ._clusters import Clusters
42
+ from ._distance import METHODS, height
43
+ from ._search import Searcher
44
+ from ._tree import to_scipy
45
+
46
+ __all__ = ["METHODS", "linkage"]
47
+
48
+
49
+ def _default_device():
50
+ if torch.backends.mps.is_available():
51
+ return "mps"
52
+ return "cuda" if torch.cuda.is_available() else "cpu"
53
+
54
+
55
+ def _identical_rows(X):
56
+ """For each row, the index of the first row equal to it."""
57
+ n, d = X.shape
58
+ probe = X @ np.random.default_rng(0).standard_normal(d)
59
+ if len(np.unique(probe)) == n: # cheap test: no two rows can be equal
60
+ return np.arange(n)
61
+ _, first, inverse = np.unique(X, axis=0, return_index=True, return_inverse=True)
62
+ return first[inverse.ravel()]
63
+
64
+
65
+ def linkage(X, method="ward", device=None, k=16, segs=256, budget=1 << 25, cache=True,
66
+ width=None, return_stats=False):
67
+ """Exact linkage matrix in scipy's format, without the n x n distance matrix.
68
+
69
+ X: (n, d) array of points.
70
+ method: "ward", "average_cosine" or "average_sqeuclidean".
71
+ device: "mps", "cuda" or "cpu" (default: the GPU if there is one).
72
+ k: candidates per cluster that come back from a full search.
73
+ segs: about how many segments the columns are cut into for the search.
74
+ budget: number of float32 elements per distance block on the device.
75
+ cache: keep each cluster's neighbour list across merges and use it before
76
+ falling back to a full search.
77
+ width: entries kept per neighbour list (default k).
78
+ return_stats: also return a dict of timings and work counts.
79
+
80
+ Returns Z, an (n - 1, 4) array as scipy.cluster.hierarchy.linkage returns.
81
+ """
82
+ if method not in METHODS:
83
+ raise ValueError(f"method must be one of {METHODS}")
84
+ if device is None:
85
+ device = _default_device()
86
+ t_start = time.perf_counter()
87
+ X = np.ascontiguousarray(X, dtype=np.float64)
88
+ n = len(X)
89
+ if method == "average_cosine":
90
+ norms = np.linalg.norm(X, axis=1, keepdims=True)
91
+ if not np.all(norms > 0):
92
+ raise ValueError("cosine distance is undefined for zero rows")
93
+ X = X / norms
94
+ else:
95
+ X = X - X.mean(axis=0) # distances do not change; float32 keeps more digits
96
+
97
+ cl = Clusters(X, method, device, width or k)
98
+ stats = cl.stats
99
+ active = np.arange(n, dtype=np.int64)
100
+ m_a, m_b, m_h = [], [], [] # the merges: one member of each side, and the height
101
+
102
+ # Identical rows merge first, at height zero, in any order. Do that up
103
+ # front: they would otherwise be exact ties all the way through.
104
+ first = _identical_rows(X)
105
+ extra = np.nonzero(first != np.arange(n))[0]
106
+ if len(extra):
107
+ m_a.append(first[extra])
108
+ m_b.append(extra)
109
+ m_h.append(np.zeros(len(extra)))
110
+ active = np.unique(first)
111
+ cl.size[active] = np.bincount(first, minlength=n)[active]
112
+
113
+ fresh = pa = pb = None # clusters made in the last round, and their parents
114
+ while len(active) > 1:
115
+ m = len(active)
116
+ if cache and fresh is not None:
117
+ cl.refresh_from_lists(active, fresh, pa, pb)
118
+ todo = active[~cl.valid[active]]
119
+ if len(todo):
120
+ t0 = time.perf_counter()
121
+ searcher = Searcher(method, cl.G, cl.size, cl.var, cl.norm, active, k, segs, budget, device)
122
+ stats["t_gpu"] += time.perf_counter() - t0
123
+ cl.full_search(searcher, todo)
124
+ del searcher
125
+ a = cl.reciprocal_pairs(active)
126
+ if len(a) == 0:
127
+ a = cl.tied_pairs(active)
128
+ b = cl.nn_id[a]
129
+ m_a.append(cl.rep[a])
130
+ m_b.append(cl.rep[b])
131
+ m_h.append(height(method, cl.nn_key[a]))
132
+ new = cl.merge(a, b)
133
+ keep = active[~cl.gone[active]]
134
+ cl.valid[keep[cl.gone[cl.nn_id[keep]]]] = False # their nearest neighbour was merged away
135
+ stats["rounds"].append((m, len(todo), len(a)))
136
+ active = np.concatenate((keep, new))
137
+ fresh, pa, pb = new, a, b
138
+
139
+ Z = to_scipy(np.concatenate(m_a), np.concatenate(m_b), np.concatenate(m_h), n)
140
+ stats["t_total"] = time.perf_counter() - t_start
141
+ stats["n_rounds"] = len(stats["rounds"])
142
+ stats["pair_work_vs_n2"] = stats["pair_evals"] / (n * n)
143
+ stats["device"] = device
144
+ return (Z, stats) if return_stats else Z
@@ -0,0 +1,309 @@
1
+ Metadata-Version: 2.5
2
+ Name: fastlinkage
3
+ Version: 0.1.1
4
+ Summary: Exact hierarchical clustering (Ward, average linkage) on the GPU, without the n x n distance matrix
5
+ Project-URL: Homepage, https://github.com/michael-L-i/fastlinkage
6
+ Project-URL: Issues, https://github.com/michael-L-i/fastlinkage/issues
7
+ Project-URL: Changelog, https://github.com/michael-L-i/fastlinkage/blob/main/CHANGELOG.md
8
+ Author: Michael Li
9
+ License: MIT
10
+ License-File: LICENSE
11
+ Keywords: agglomerative,embeddings,gpu,hierarchical clustering,linkage
12
+ Classifier: Development Status :: 3 - Alpha
13
+ Classifier: Intended Audience :: Science/Research
14
+ Classifier: License :: OSI Approved :: MIT License
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3.10
17
+ Classifier: Programming Language :: Python :: 3.11
18
+ Classifier: Programming Language :: Python :: 3.12
19
+ Classifier: Programming Language :: Python :: 3.13
20
+ Classifier: Topic :: Scientific/Engineering
21
+ Classifier: Topic :: Scientific/Engineering :: Information Analysis
22
+ Requires-Python: >=3.10
23
+ Requires-Dist: numpy>=1.24
24
+ Requires-Dist: scipy>=1.10
25
+ Requires-Dist: torch>=2.1
26
+ Provides-Extra: bench
27
+ Requires-Dist: datasets; extra == 'bench'
28
+ Requires-Dist: fastcluster; extra == 'bench'
29
+ Requires-Dist: scikit-learn; extra == 'bench'
30
+ Requires-Dist: sentence-transformers; extra == 'bench'
31
+ Provides-Extra: dev
32
+ Requires-Dist: pytest; extra == 'dev'
33
+ Requires-Dist: ruff; extra == 'dev'
34
+ Requires-Dist: scikit-learn; extra == 'dev'
35
+ Provides-Extra: test
36
+ Requires-Dist: pytest; extra == 'test'
37
+ Requires-Dist: scikit-learn; extra == 'test'
38
+ Description-Content-Type: text/markdown
39
+
40
+ # fastlinkage
41
+
42
+ [![tests](https://github.com/michael-L-i/fastlinkage/actions/workflows/test.yml/badge.svg)](https://github.com/michael-L-i/fastlinkage/actions/workflows/test.yml)
43
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
44
+ ![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)
45
+
46
+ Exact hierarchical clustering on the GPU, without the n x n distance matrix.
47
+
48
+ It returns the same tree as `scipy.cluster.hierarchy.linkage` for Ward and
49
+ average linkage, runs in seconds at 100,000+ points, and uses memory that
50
+ grows with the number of points, not its square.
51
+
52
+ <picture>
53
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/michael-L-i/fastlinkage/main/assets/speed-dark.svg">
54
+ <img src="https://raw.githubusercontent.com/michael-L-i/fastlinkage/main/assets/speed-light.svg" alt="Time to build the exact tree. 20,000 text embeddings, average linkage with cosine distance: 0.8 s against 47 s for SciPy. 100,000 points with 32 features, Ward: 2.2 s against 2.3 minutes for fastcluster. 120,000 text embeddings, Ward: 8.7 s against 59 minutes for fastcluster." width="800">
55
+ </picture>
56
+
57
+ > **Status: early release.** Tested on NVIDIA GPUs (CUDA), Apple GPUs (PyTorch
58
+ > MPS) and the CPU on Linux, macOS and Windows.
59
+
60
+ ## Why
61
+
62
+ SciPy and scikit-learn build the full distance matrix. At 120,000 points that
63
+ is 58 GB, so most people give up on hierarchical clustering long before that
64
+ and switch to k-means or HDBSCAN. This package keeps the exact tree and drops
65
+ the matrix:
66
+
67
+ | | SciPy / scikit-learn | fastlinkage |
68
+ |---|---|---|
69
+ | Memory | n x n distances | one mean vector per cluster |
70
+ | 20,000 text embeddings (384 features), average cosine | 47 s | 0.8 s |
71
+ | 120,000 text embeddings, average cosine | needs a 58 GB matrix | 6.9 s |
72
+ | Result | exact | exact, same tree |
73
+
74
+ ## Install
75
+
76
+ ```
77
+ pip install fastlinkage
78
+ ```
79
+
80
+ Needs Python 3.10+, NumPy, SciPy and PyTorch. It uses CUDA or Apple MPS when
81
+ PyTorch sees one, and the CPU otherwise.
82
+
83
+ | Hardware | Status |
84
+ |---|---|
85
+ | Apple GPU (MPS) | tested; main benchmarks below |
86
+ | CPU on Linux, macOS, Windows | tested on every commit |
87
+ | NVIDIA GPU (CUDA) | tested on a Tesla T4 ([notebook](https://colab.research.google.com/github/michael-L-i/fastlinkage/blob/main/notebooks/cuda_check.ipynb)) |
88
+
89
+ The package is pure Python on top of PyTorch, so there is nothing to compile.
90
+
91
+ ## Use
92
+
93
+ Drop-in for SciPy's `linkage`:
94
+
95
+ ```python
96
+ from fastlinkage import linkage
97
+
98
+ Z = linkage(X, method="ward") # scipy: linkage(X, "ward")
99
+ Z = linkage(X, method="average_cosine") # scipy: linkage(X, "average", metric="cosine")
100
+ Z = linkage(X, method="average_sqeuclidean") # scipy: linkage(X, "average", metric="sqeuclidean")
101
+ ```
102
+
103
+ `Z` is SciPy's linkage matrix, so everything downstream keeps working:
104
+
105
+ ```python
106
+ from scipy.cluster.hierarchy import dendrogram, fcluster
107
+
108
+ labels = fcluster(Z, t=50, criterion="maxclust")
109
+ dendrogram(Z, truncate_mode="lastp", p=40)
110
+ ```
111
+
112
+ Cluster embeddings without choosing the number of clusters:
113
+
114
+ ```python
115
+ from fastlinkage import AgglomerativeClustering
116
+
117
+ model = AgglomerativeClustering(
118
+ n_clusters=None, distance_threshold=0.35, linkage="average", metric="cosine"
119
+ ).fit(embeddings)
120
+
121
+ model.labels_ # cluster of every row
122
+ model.n_clusters_ # how many clusters the threshold gave
123
+ ```
124
+
125
+ The class follows scikit-learn's `AgglomerativeClustering` (`labels_`,
126
+ `children_`, `distances_`, `fit_predict`). Cutting one tree at several levels
127
+ costs almost nothing:
128
+
129
+ ```python
130
+ from fastlinkage import cut, linkage
131
+
132
+ Z = linkage(embeddings, method="average_cosine")
133
+ coarse = cut(Z, n_clusters=20)
134
+ fine = cut(Z, distance_threshold=0.25)
135
+ ```
136
+
137
+ A runnable version is in [`examples/quickstart.py`](examples/quickstart.py).
138
+
139
+ ### Reference
140
+
141
+ | | |
142
+ |---|---|
143
+ | `linkage(X, method="ward", device=None)` | SciPy-format linkage matrix. `method` is `"ward"`, `"average_cosine"` or `"average_sqeuclidean"`. `device` is `"cuda"`, `"mps"` or `"cpu"`; by default the GPU if there is one. |
144
+ | `cut(Z, n_clusters=None, distance_threshold=None)` | Labels from a tree. Give exactly one of the two. |
145
+ | `AgglomerativeClustering(n_clusters=2, *, metric="euclidean", linkage="ward", distance_threshold=None, device=None)` | scikit-learn style estimator. Supported pairs: `ward` + `euclidean`, `average` + `cosine`, `average` + `sqeuclidean`. |
146
+
147
+ ## Benchmarks
148
+
149
+ Measured on an Apple laptop GPU (PyTorch MPS, 18 CPU cores for the baselines).
150
+ Every timing builds the full tree.
151
+
152
+ | Data | Points | Linkage | fastlinkage | Baseline |
153
+ |---|---|---|---|---|
154
+ | Text embeddings, 384 features | 20,000 | Average, cosine | 0.8 s | SciPy 47 s |
155
+ | Text embeddings, 384 features | 20,000 | Ward | 1.0 s | SciPy 16 s |
156
+ | Text embeddings, 384 features | 120,000 | Average, cosine | 6.9 s | SciPy needs 58 GB |
157
+ | Text embeddings, 384 features | 120,000 | Ward | 8.7 s | fastcluster 59 min |
158
+ | Synthetic, 32 features | 100,000 | Ward | 2.2 s | fastcluster 135 s |
159
+ | Synthetic, 32 features | 200,000 | all three | 5.9 to 6.4 s | not run |
160
+ | Synthetic, 32 features | 500,000 | Average, cosine | 33 s | not run |
161
+ | Synthetic, 32 features | 500,000 | Ward | 36 s | not run |
162
+
163
+ - The text embeddings are AG News titles and descriptions, embedded with
164
+ all-MiniLM-L6-v2.
165
+ - fastcluster's `linkage_vector` is the standard exact Ward that avoids the
166
+ matrix. It is single-threaded.
167
+ - The same code on the CPU is 2x to 4x slower than on this GPU, so most of
168
+ the gap to SciPy comes from the method, not the hardware.
169
+
170
+ <picture>
171
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/michael-L-i/fastlinkage/main/assets/scaling-dark.svg">
172
+ <img src="https://raw.githubusercontent.com/michael-L-i/fastlinkage/main/assets/scaling-light.svg" alt="Exact Ward tree on 32-feature data. fastlinkage: 0.4 s at 20,000 points, 2.2 s at 100,000, 6.4 s at 200,000, 36 s at 500,000. fastcluster: 5.2 s at 20,000, 32 s at 50,000, 2.3 minutes at 100,000." width="800">
173
+ </picture>
174
+
175
+ Time grows with the square of the number of points. About a million points is
176
+ the practical limit.
177
+
178
+ ### NVIDIA GPU
179
+
180
+ A free Google Colab machine: Tesla T4 with 2 virtual CPUs. Synthetic data.
181
+
182
+ | Points | Features | Ward | Average, cosine | Average, sq. Euclidean | Baseline on the same machine |
183
+ |---|---|---|---|---|---|
184
+ | 20,000 | 32 | 1.0 s | 0.8 s | 0.9 s | SciPy 23 to 24 s |
185
+ | 100,000 | 32 | 3.9 s | 4.0 s | 5.3 s | fastcluster Ward 490 s |
186
+ | 100,000 | 384 | 11.4 s | 12.7 s | 14.8 s | not run |
187
+ | 200,000 | 32 | 10.8 s | 10.0 s | 11.1 s | not run |
188
+
189
+ The trees match SciPy at 20,000 points and fastcluster at 100,000 to 1e-12.
190
+ [`notebooks/cuda_check.ipynb`](notebooks/cuda_check.ipynb) reproduces this.
191
+
192
+ ## Exactness
193
+
194
+ The tree is checked against independent implementations:
195
+
196
+ | Check | Result |
197
+ |---|---|
198
+ | SciPy, 5,000 and 20,000 points, all three linkages, synthetic and real embeddings | merge heights equal to 1e-12; flat clusterings identical |
199
+ | fastcluster Ward, 100,000 synthetic points | heights equal to 5e-13 |
200
+ | fastcluster Ward, 120,000 text embeddings | heights equal to 1.4e-14 |
201
+ | Duplicated rows, near-duplicates (1e-7 noise), data offset by 1e4 | equal to SciPy to 1e-13 |
202
+
203
+ This takes some care. The GPU search runs in float32, and a plain float32
204
+ search picks a slightly wrong neighbour often enough to change the tree: an
205
+ earlier version of this code was off by up to 1.6 in merge height (tallest
206
+ merge 82) on the 120,000 embeddings. The current version accepts a float32
207
+ result only when it wins by more than the possible rounding error, and
208
+ otherwise compares the close contenders in float64.
209
+
210
+ With exact ties between different pairs (an integer grid, for example) the
211
+ tree is not unique, and this package and SciPy can return different valid
212
+ trees.
213
+
214
+ ## How it works
215
+
216
+ Three known ideas and two additions.
217
+
218
+ 1. **Cluster summaries instead of a matrix.** For these linkages the distance
219
+ between two clusters follows from each cluster's size, mean vector and one
220
+ scalar:
221
+
222
+ | Linkage | Distance between clusters A and B |
223
+ |---|---|
224
+ | Ward | sqrt(2 \|A\|\|B\| / (\|A\|+\|B\|)) x \|\|mean(A) - mean(B)\|\| |
225
+ | Average, cosine | 1 - mean(A) . mean(B), rows scaled to unit length |
226
+ | Average, squared Euclidean | \|\|mean(A) - mean(B)\|\|^2 + var(A) + var(B) |
227
+
228
+ 2. **Merge in rounds.** Every pair of clusters that are each other's nearest
229
+ neighbour merges in the same round. For these linkages that gives exactly
230
+ the tree of the one-merge-at-a-time algorithm. A full run takes 50 to 180
231
+ rounds.
232
+
233
+ 3. **Nearest-neighbour search as one matrix product** on the GPU.
234
+
235
+ 4. **Neighbour lists that survive merges.** A search returns 16 candidates and
236
+ a radius beyond which nothing else can be. When a cluster's neighbour is
237
+ merged away, the next one usually comes from that list with no new search,
238
+ and a merged cluster inherits its parents' lists. This halves the search
239
+ work (from about 3 n^2 to 1.5 n^2 pair evaluations).
240
+
241
+ 5. **A float32 rounding check** with a float64 fallback, described above.
242
+
243
+ [`docs/DESIGN.md`](docs/DESIGN.md) has the details: the neighbour-list rule,
244
+ the rounding check, more measurements, and what was tried and dropped.
245
+
246
+ ## Related work
247
+
248
+ None of the underlying algorithm is new, and this package does not claim it.
249
+
250
+ | Idea | Where it comes from |
251
+ |---|---|
252
+ | Merging reciprocal nearest neighbours in rounds | Murtagh (1980s); [ParChain](https://arxiv.org/abs/2106.04727) (2021, CPU); [RAC](https://arxiv.org/abs/2105.11653) (2021) |
253
+ | Average linkage from means and variances in linear memory | ParChain (CPU, kd-trees, low dimensions); [arXiv 1404.3439](https://arxiv.org/abs/1404.3439) |
254
+ | Exact Ward on the GPU | [cuhc](https://pypi.org/project/cuhc/) (2026, CUDA) |
255
+
256
+ What I could not find elsewhere is a GPU implementation of exact average
257
+ linkage (cosine or squared Euclidean) that avoids the distance matrix and
258
+ works on high-dimensional embeddings. cuhc keeps the matrix for average
259
+ linkage; ParChain's version is CPU-only and built for low dimensions. The
260
+ search was not exhaustive, so treat "first" as unconfirmed. I have also not
261
+ checked whether the neighbour-list rule (item 4) is published.
262
+
263
+ ## Limits
264
+
265
+ - Three linkages only: Ward, average with cosine, average with squared
266
+ Euclidean. Complete linkage and average linkage with plain Euclidean
267
+ distance have no per-cluster summary and are not supported.
268
+ - Time is quadratic in the number of points.
269
+ - A float32 copy of every cluster mean lives on the GPU: 8 n d bytes (3 GB
270
+ for a million points with 384 features). On CUDA a float64 copy is kept
271
+ there too when it fits in a quarter of the free memory.
272
+ - When distances are below float32 resolution (cosine distance between
273
+ almost parallel vectors), the float64 fallback does most of the work and is
274
+ slow. A warning is raised.
275
+ - Tested on one NVIDIA GPU (Tesla T4) so far, and not compared with cuhc on
276
+ the same hardware.
277
+
278
+ ## Reproduce
279
+
280
+ ```
281
+ git clone https://github.com/michael-L-i/fastlinkage && cd fastlinkage
282
+ pip install -e ".[test,bench]"
283
+ pytest # exactness tests, CPU only
284
+ python experiments/correctness.py # against SciPy
285
+ python experiments/make_embeddings.py # AG News embeddings (176 MB)
286
+ python experiments/neighbour_lists.py # 20k to 120k points
287
+ python experiments/large_runs.py # fastcluster check, 200k, 500k
288
+ python experiments/make_charts.py # the charts above
289
+ ```
290
+
291
+ [`experiments/`](experiments) lists every script, and the raw numbers are in
292
+ [`results/`](results).
293
+
294
+ ## Repository layout
295
+
296
+ ```
297
+ src/fastlinkage/ the package
298
+ tests/ exactness tests against SciPy and scikit-learn
299
+ notebooks/ CUDA check for Google Colab
300
+ examples/ quickstart
301
+ experiments/ benchmark and correctness scripts
302
+ results/ their output (JSON)
303
+ docs/DESIGN.md how it works, measurements, prior work
304
+ assets/ README charts
305
+ ```
306
+
307
+ ## License
308
+
309
+ MIT
@@ -0,0 +1,11 @@
1
+ fastlinkage/__init__.py,sha256=g4D3nujenpxfF1M94iabiGMU3xvs5unww5WxVeaJspA,258
2
+ fastlinkage/_clusters.py,sha256=hkiQiuezPgmXqguYnw-Xxt3H04tjw03-z4tgxmZHXms,12360
3
+ fastlinkage/_distance.py,sha256=I--srmHeitHRIgoc50K0Ri_273nN-N6p-E1Wp5dzb-k,1708
4
+ fastlinkage/_search.py,sha256=Ih3__aDJ4ukE0waYI3QbCQ7UdE0jlOPtj8pYXBCsPHM,8292
5
+ fastlinkage/_tree.py,sha256=4h5XtvpMk6SVXLMUJuOnrgw1p0BIsFW5FaIsh9WAdFo,1123
6
+ fastlinkage/cluster.py,sha256=txi8hLLp90v_uw6Hn2f0tsF62x0nj1bkHtG07ebcGSQ,3177
7
+ fastlinkage/core.py,sha256=FTKvObDsj78jrRL5xb6UimyTdaFSCxIBGV8sCwEnWGQ,6352
8
+ fastlinkage-0.1.1.dist-info/METADATA,sha256=15ykg84Z_3s4AaWy2wUyfaQG3tWtNdJh3mltNR1ZxX0,13598
9
+ fastlinkage-0.1.1.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
10
+ fastlinkage-0.1.1.dist-info/licenses/LICENSE,sha256=A0GUbLMfiMvHoPCRShY9hS-5IV-IkiemE559FRedeOc,1067
11
+ fastlinkage-0.1.1.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,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Michael Li
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.