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.
- fastlinkage/__init__.py +6 -0
- fastlinkage/_clusters.py +274 -0
- fastlinkage/_distance.py +40 -0
- fastlinkage/_search.py +179 -0
- fastlinkage/_tree.py +39 -0
- fastlinkage/cluster.py +77 -0
- fastlinkage/core.py +144 -0
- fastlinkage-0.1.1.dist-info/METADATA +309 -0
- fastlinkage-0.1.1.dist-info/RECORD +11 -0
- fastlinkage-0.1.1.dist-info/WHEEL +4 -0
- fastlinkage-0.1.1.dist-info/licenses/LICENSE +21 -0
fastlinkage/__init__.py
ADDED
fastlinkage/_clusters.py
ADDED
|
@@ -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
|
fastlinkage/_distance.py
ADDED
|
@@ -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
|
+
[](https://github.com/michael-L-i/fastlinkage/actions/workflows/test.yml)
|
|
43
|
+
[](LICENSE)
|
|
44
|
+

|
|
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,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.
|