graphwise 1.9.1 → 1.11.0

package/dist/kernel-DukrXtVb.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"kernel-DukrXtVb.cjs","names":[],"sources":["../src/gpu/kernels/intersection/kernel.ts"],"sourcesContent":["/**\n * TypeGPU compute kernel for batch neighbourhood intersection.\n *\n * Computes intersection size and neighbourhood sizes for multiple node pairs.\n * One thread per pair: iterates the smaller neighbourhood and binary-searches the other.\n *\n * @module gpu/kernels/intersection/kernel\n */\n\nimport tgpu, { d, type StorageFlag, type TgpuBuffer } from \"typegpu\";\nimport type { TypedBufferGroup } from \"../../csr\";\nimport type { GraphwiseGPURoot } from \"../../root\";\n\n/**\n * Bind group layout for Intersection kernel.\n */\nconst IntersectionLayout = tgpu.bindGroupLayout({\n\trowOffsets: { storage: d.arrayOf(d.u32) },\n\tcolIndices: { storage: d.arrayOf(d.u32) },\n\tpairsU: { storage: d.arrayOf(d.u32) },\n\tpairsV: { storage: d.arrayOf(d.u32) },\n\tintersections: { storage: d.arrayOf(d.u32), access: \"mutable\" },\n\tsizeUs: { storage: d.arrayOf(d.u32), access: \"mutable\" },\n\tsizeVs: { storage: d.arrayOf(d.u32), access: \"mutable\" },\n\tpairCount: { uniform: d.u32 },\n});\n\n/**\n * Intersection compute pipeline: one thread per pair.\n *\n * For each pair (u, v):\n *  - Count intersection by iterating smaller neighbourhood\n *  - Binary search in larger neighbourhood\n *  - Write intersection, sizeU, sizeV to output buffers\n */\nconst intersectionPipeline = (pairIdx: number): void => {\n\t\"use gpu\";\n\tconst u = IntersectionLayout.$.pairsU[pairIdx] ?? 0;\n\tconst v = IntersectionLayout.$.pairsV[pairIdx] ?? 0;\n\n\tconst uStart = IntersectionLayout.$.rowOffsets[u] ?? 0;\n\tconst uEnd = IntersectionLayout.$.rowOffsets[u + 1] ?? 0;\n\tconst vStart = IntersectionLayout.$.rowOffsets[v] ?? 0;\n\tconst vEnd = IntersectionLayout.$.rowOffsets[v + 1] ?? 0;\n\n\tconst degU = uEnd - uStart;\n\tconst degV = vEnd - vStart;\n\n\t// Write sizes first\n\tIntersectionLayout.$.sizeUs[pairIdx] = degU;\n\tIntersectionLayout.$.sizeVs[pairIdx] = degV;\n\n\t// Empty neighbourhoods → intersection = 0\n\tif (degU === 0 || degV === 0) {\n\t\tIntersectionLayout.$.intersections[pairIdx] = 0;\n\t\treturn;\n\t}\n\n\tlet intersection = 0;\n\n\tif (degU <= degV) {\n\t\t// Iterate u's neighbours, search in v's\n\t\tfor (let i = uStart; i < uEnd; i = i + 1) {\n\t\t\tconst neighbour = IntersectionLayout.$.colIndices[i] ?? 0;\n\t\t\t// Binary search in v's neighbourhood\n\t\t\tlet lo = vStart;\n\t\t\tlet hi = vEnd;\n\t\t\twhile (lo < hi) {\n\t\t\t\tconst mid = lo + (hi - lo) / 2;\n\t\t\t\tconst midVal = IntersectionLayout.$.colIndices[mid] ?? 0;\n\t\t\t\tif (midVal === neighbour) {\n\t\t\t\t\tintersection = intersection + 1;\n\t\t\t\t\tlo = hi; // break\n\t\t\t\t} else if (midVal < neighbour) {\n\t\t\t\t\tlo = mid + 1;\n\t\t\t\t} else {\n\t\t\t\t\thi = mid;\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t} else {\n\t\t// Iterate v's neighbours, search in u's\n\t\tfor (let i = vStart; i < vEnd; i = i + 1) {\n\t\t\tconst neighbour = IntersectionLayout.$.colIndices[i] ?? 0;\n\t\t\t// Binary search in u's neighbourhood\n\t\t\tlet lo = uStart;\n\t\t\tlet hi = uEnd;\n\t\t\twhile (lo < hi) {\n\t\t\t\tconst mid = lo + (hi - lo) / 2;\n\t\t\t\tconst midVal = IntersectionLayout.$.colIndices[mid] ?? 0;\n\t\t\t\tif (midVal === neighbour) {\n\t\t\t\t\tintersection = intersection + 1;\n\t\t\t\t\tlo = hi; // break\n\t\t\t\t} else if (midVal < neighbour) {\n\t\t\t\t\tlo = mid + 1;\n\t\t\t\t} else {\n\t\t\t\t\thi = mid;\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t}\n\n\tIntersectionLayout.$.intersections[pairIdx] = intersection;\n};\n\n/**\n * Dispatch batch intersection on GPU.\n *\n * @param root - TypeGPU root instance\n * @param csrBuffers - CSR matrix as typed buffers\n * @param pairsU - First node of each pair (u32 array)\n * @param pairsV - Second node of each pair (u32 array)\n * @param intersections - Output intersections (u32 array, mutable)\n * @param sizeUs - Output sizeU per pair (u32 array, mutable)\n * @param sizeVs - Output sizeV per pair (u32 array, mutable)\n * @param pairCount - Number of pairs to compute\n */\nexport function dispatchIntersection(\n\troot: GraphwiseGPURoot,\n\tcsrBuffers: TypedBufferGroup,\n\tpairsU: TgpuBuffer<ReturnType<typeof d.arrayOf<typeof d.u32>>> & StorageFlag,\n\tpairsV: TgpuBuffer<ReturnType<typeof d.arrayOf<typeof d.u32>>> & StorageFlag,\n\tintersections: TgpuBuffer<ReturnType<typeof d.arrayOf<typeof d.u32>>> &\n\t\tStorageFlag,\n\tsizeUs: TgpuBuffer<ReturnType<typeof d.arrayOf<typeof d.u32>>> & StorageFlag,\n\tsizeVs: TgpuBuffer<ReturnType<typeof d.arrayOf<typeof d.u32>>> & StorageFlag,\n\tpairCount: number,\n): void {\n\tconst pipeline = root.createGuardedComputePipeline(intersectionPipeline);\n\n\tconst pairCountBuffer = root.createBuffer(d.u32, pairCount).$usage(\"uniform\");\n\n\tconst bindGroup = root.createBindGroup(IntersectionLayout, {\n\t\trowOffsets: csrBuffers.rowOffsets,\n\t\tcolIndices: csrBuffers.colIndices,\n\t\tpairsU,\n\t\tpairsV,\n\t\tintersections,\n\t\tsizeUs,\n\t\tsizeVs,\n\t\tpairCount: pairCountBuffer,\n\t});\n\n\tpipeline.with(bindGroup).dispatchThreads(pairCount);\n}\n\nexport { IntersectionLayout };\n"],"mappings":"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"}

package/dist/{kmeans-B8x9D1kt.cjs → kmeans-CZ7tJFYw.cjs}

@@ -262,4 +262,4 @@ Object.defineProperty(exports, "normaliseFeatures", {
 	}
 });
 
-//# sourceMappingURL=kmeans-B8x9D1kt.cjs.map
+//# sourceMappingURL=kmeans-CZ7tJFYw.cjs.map

package/dist/{kmeans-B8x9D1kt.cjs.map → kmeans-CZ7tJFYw.cjs.map}

@@ -1 +1 @@
-{"version":3,"file":"kmeans-B8x9D1kt.cjs","names":[],"sources":["../src/utils/kmeans.ts"],"sourcesContent":["/**\n * Minimal K-means clustering implementation for GRASP seed selection.\n *\n * This is a lightweight implementation specifically designed for 3D feature vectors\n * used in structural seed selection. For general-purpose clustering, consider\n * using a dedicated library.\n *\n * @packageDocumentation\n */\n\n/**\n * A 3D feature vector representing node structural properties.\n */\nexport interface FeatureVector3D {\n\t/** First dimension (e.g., log-degree) */\n\treadonly f1: number;\n\t/** Second dimension (e.g., clustering coefficient) */\n\treadonly f2: number;\n\t/** Third dimension (e.g., approximate PageRank) */\n\treadonly f3: number;\n}\n\n/**\n * A labelled feature vector with associated node ID.\n */\nexport interface LabelledFeature extends FeatureVector3D {\n\t/** Node identifier */\n\treadonly nodeId: string;\n}\n\n/**\n * Result of K-means clustering.\n */\nexport interface KMeansResult {\n\t/** Cluster centroids */\n\treadonly centroids: readonly FeatureVector3D[];\n\t/** Cluster assignments: nodeId -> cluster index */\n\treadonly assignments: ReadonlyMap<string, number>;\n\t/** Number of clusters */\n\treadonly k: number;\n}\n\n/**\n * Options for K-means clustering.\n */\nexport interface KMeansOptions {\n\t/** Number of clusters */\n\treadonly k: number;\n\t/** Maximum iterations (default: 100) */\n\treadonly maxIterations?: number;\n\t/** Convergence threshold (default: 1e-6) */\n\treadonly tolerance?: number;\n\t/** Random seed for reproducibility */\n\treadonly seed?: number;\n}\n\n/** Small epsilon to prevent division by zero */\nconst EPSILON = 1e-10;\n\n/**\n * Simple seeded pseudo-random number generator using mulberry32.\n */\nfunction createRNG(seed: number): () => number {\n\tlet state = seed >>> 0;\n\treturn (): number => {\n\t\tstate = (state + 0x6d2b79f5) >>> 0;\n\t\tlet t = Math.imul(state ^ (state >>> 15), state | 1);\n\t\tt = (t ^ (t >>> 7)) * (t | 0x61c88647);\n\t\treturn ((t ^ (t >>> 14)) >>> 0) / 4294967296;\n\t};\n}\n\n/**\n * Compute Euclidean distance between two 3D feature vectors.\n */\nfunction euclideanDistance(a: FeatureVector3D, b: FeatureVector3D): number {\n\tconst d1 = a.f1 - b.f1;\n\tconst d2 = a.f2 - b.f2;\n\tconst d3 = a.f3 - b.f3;\n\treturn Math.sqrt(d1 * d1 + d2 * d2 + d3 * d3);\n}\n\n/**\n * Compute the mean of a set of feature vectors.\n * @internal - Used for testing\n */\nexport function _computeMean(\n\tvectors: readonly FeatureVector3D[],\n): FeatureVector3D {\n\tif (vectors.length === 0) {\n\t\treturn { f1: 0, f2: 0, f3: 0 };\n\t}\n\tlet sum1 = 0;\n\tlet sum2 = 0;\n\tlet sum3 = 0;\n\tfor (const v of vectors) {\n\t\tsum1 += v.f1;\n\t\tsum2 += v.f2;\n\t\tsum3 += v.f3;\n\t}\n\tconst n = vectors.length;\n\treturn { f1: sum1 / n, f2: sum2 / n, f3: sum3 / n };\n}\n\n/**\n * Z-score normalise features (zero mean, unit variance).\n */\nexport { normaliseFeatures as zScoreNormalise };\n\nexport function normaliseFeatures(\n\tfeatures: readonly LabelledFeature[],\n): LabelledFeature[] {\n\tif (features.length === 0) {\n\t\treturn [];\n\t}\n\n\t// Compute means\n\tlet sum1 = 0;\n\tlet sum2 = 0;\n\tlet sum3 = 0;\n\tfor (const f of features) {\n\t\tsum1 += f.f1;\n\t\tsum2 += f.f2;\n\t\tsum3 += f.f3;\n\t}\n\tconst n = features.length;\n\tconst mean1 = sum1 / n;\n\tconst mean2 = sum2 / n;\n\tconst mean3 = sum3 / n;\n\n\t// Compute standard deviations\n\tlet var1 = 0;\n\tlet var2 = 0;\n\tlet var3 = 0;\n\tfor (const f of features) {\n\t\tvar1 += (f.f1 - mean1) ** 2;\n\t\tvar2 += (f.f2 - mean2) ** 2;\n\t\tvar3 += (f.f3 - mean3) ** 2;\n\t}\n\tconst std1 = Math.sqrt(var1 / n + EPSILON);\n\tconst std2 = Math.sqrt(var2 / n + EPSILON);\n\tconst std3 = Math.sqrt(var3 / n + EPSILON);\n\n\t// Normalise\n\treturn features.map(\n\t\t(f): LabelledFeature => ({\n\t\t\tnodeId: f.nodeId,\n\t\t\tf1: (f.f1 - mean1) / std1,\n\t\t\tf2: (f.f2 - mean2) / std2,\n\t\t\tf3: (f.f3 - mean3) / std3,\n\t\t}),\n\t);\n}\n\n/**\n * Mini-batch K-means clustering for 3D feature vectors.\n *\n * Uses Mini-batch K-means for efficiency with large datasets.\n * This is specifically designed for the GRASP seed selection algorithm.\n *\n * @param features - Array of labelled feature vectors\n * @param options - Clustering options\n * @returns Clustering result with centroids and assignments\n */\nexport function miniBatchKMeans(\n\tfeatures: readonly LabelledFeature[],\n\toptions: KMeansOptions,\n): KMeansResult {\n\tconst { k, maxIterations = 100, tolerance = 1e-6, seed = 42 } = options;\n\n\tif (features.length === 0) {\n\t\treturn {\n\t\t\tcentroids: [],\n\t\t\tassignments: new Map(),\n\t\t\tk,\n\t\t};\n\t}\n\n\tconst rng = createRNG(seed);\n\tconst n = features.length;\n\tconst effectiveK = Math.min(k, n);\n\n\t// Initialise centroids using k-means++ seeding\n\tconst centroids: FeatureVector3D[] = initialiseCentroidsKMeansPP(\n\t\tfeatures,\n\t\teffectiveK,\n\t\trng,\n\t);\n\n\t// Assignments map\n\tconst assignments = new Map<string, number>();\n\n\t// Mini-batch size (10% of data or at least 10)\n\tconst batchSize = Math.max(10, Math.floor(n / 10));\n\n\tfor (let iter = 0; iter < maxIterations; iter++) {\n\t\t// Sample mini-batch\n\t\tconst batchIndices = new Set<number>();\n\t\twhile (batchIndices.size < Math.min(batchSize, n)) {\n\t\t\tbatchIndices.add(Math.floor(rng() * n));\n\t\t}\n\n\t\t// Assign batch points to nearest centroid\n\t\tconst batchPoints: { feature: LabelledFeature; cluster: number }[] = [];\n\t\tfor (const idx of batchIndices) {\n\t\t\tconst feature = features[idx];\n\t\t\tif (feature === undefined) continue;\n\t\t\tlet minDist = Infinity;\n\t\t\tlet bestCluster = 0;\n\t\t\tfor (let c = 0; c < centroids.length; c++) {\n\t\t\t\tconst centroid = centroids[c];\n\t\t\t\tif (centroid === undefined) continue;\n\t\t\t\tconst dist = euclideanDistance(feature, centroid);\n\t\t\t\tif (dist < minDist) {\n\t\t\t\t\tminDist = dist;\n\t\t\t\t\tbestCluster = c;\n\t\t\t\t}\n\t\t\t}\n\t\t\tbatchPoints.push({ feature, cluster: bestCluster });\n\t\t}\n\n\t\t// Update centroids based on batch\n\t\tconst oldCentroids = centroids.map((c) => ({ ...c }));\n\n\t\t// Compute per-cluster counts and sums from batch\n\t\tconst clusterCounts = Array.from({ length: centroids.length }, () => 0);\n\t\tconst clusterSums: [number, number, number][] = Array.from(\n\t\t\t{ length: centroids.length },\n\t\t\t(): [number, number, number] => [0, 0, 0],\n\t\t);\n\n\t\tfor (const { feature, cluster } of batchPoints) {\n\t\t\tconst currentCount = clusterCounts[cluster];\n\t\t\tif (currentCount !== undefined) {\n\t\t\t\tclusterCounts[cluster] = currentCount + 1;\n\t\t\t}\n\t\t\tconst sum = clusterSums[cluster];\n\t\t\tif (sum !== undefined) {\n\t\t\t\tsum[0] += feature.f1;\n\t\t\t\tsum[1] += feature.f2;\n\t\t\t\tsum[2] += feature.f3;\n\t\t\t}\n\t\t}\n\n\t\t// Update centroids\n\t\tfor (let c = 0; c < centroids.length; c++) {\n\t\t\tconst count = clusterCounts[c] ?? 0;\n\t\t\tif (count > 0) {\n\t\t\t\tconst sum = clusterSums[c];\n\t\t\t\tif (sum !== undefined) {\n\t\t\t\t\tcentroids[c] = {\n\t\t\t\t\t\tf1: sum[0] / count,\n\t\t\t\t\t\tf2: sum[1] / count,\n\t\t\t\t\t\tf3: sum[2] / count,\n\t\t\t\t\t};\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\n\t\t// Check convergence\n\t\tlet maxShift = 0;\n\t\tfor (let c = 0; c < centroids.length; c++) {\n\t\t\tconst newCentroid = centroids[c];\n\t\t\tconst oldCentroid = oldCentroids[c];\n\t\t\tif (newCentroid !== undefined && oldCentroid !== undefined) {\n\t\t\t\tconst shift = euclideanDistance(newCentroid, oldCentroid);\n\t\t\t\tmaxShift = Math.max(maxShift, shift);\n\t\t\t}\n\t\t}\n\n\t\tif (maxShift < tolerance) {\n\t\t\tbreak;\n\t\t}\n\t}\n\n\t// Final assignment of all points\n\tfor (const feature of features) {\n\t\tlet minDist = Infinity;\n\t\tlet bestCluster = 0;\n\t\tfor (let c = 0; c < centroids.length; c++) {\n\t\t\tconst centroid = centroids[c];\n\t\t\tif (centroid === undefined) continue;\n\t\t\tconst dist = euclideanDistance(feature, centroid);\n\t\t\tif (dist < minDist) {\n\t\t\t\tminDist = dist;\n\t\t\t\tbestCluster = c;\n\t\t\t}\n\t\t}\n\t\tassignments.set(feature.nodeId, bestCluster);\n\t}\n\n\treturn {\n\t\tcentroids,\n\t\tassignments,\n\t\tk: effectiveK,\n\t};\n}\n\n/**\n * K-means++ initialisation for better centroid seeding.\n */\nfunction initialiseCentroidsKMeansPP(\n\tfeatures: readonly LabelledFeature[],\n\tk: number,\n\trng: () => number,\n): FeatureVector3D[] {\n\tconst centroids: FeatureVector3D[] = [];\n\tconst n = features.length;\n\n\t// Choose first centroid randomly\n\tconst firstIdx = Math.floor(rng() * n);\n\tconst firstFeature = features[firstIdx];\n\tif (firstFeature === undefined) {\n\t\treturn [{ f1: 0, f2: 0, f3: 0 }];\n\t}\n\tcentroids.push({\n\t\tf1: firstFeature.f1,\n\t\tf2: firstFeature.f2,\n\t\tf3: firstFeature.f3,\n\t});\n\n\t// Choose remaining centroids with probability proportional to squared distance\n\tconst distances = Array.from({ length: n }, () => Infinity);\n\n\tfor (let c = 1; c < k; c++) {\n\t\t// Update distances to nearest centroid\n\t\tlet totalDistSq = 0;\n\t\tfor (let i = 0; i < n; i++) {\n\t\t\tconst feature = features[i];\n\t\t\tif (feature === undefined) continue;\n\t\t\tconst lastCentroid = centroids[c - 1];\n\t\t\tif (lastCentroid === undefined) continue;\n\t\t\tconst dist = euclideanDistance(feature, lastCentroid);\n\t\t\tconst currentMin = distances[i];\n\t\t\tif (currentMin !== undefined && dist < currentMin) {\n\t\t\t\tdistances[i] = dist;\n\t\t\t}\n\t\t\tconst d = distances[i];\n\t\t\tif (d !== undefined) {\n\t\t\t\ttotalDistSq += d * d;\n\t\t\t}\n\t\t}\n\n\t\t// Choose next centroid with probability proportional to squared distance\n\t\tconst threshold = rng() * totalDistSq;\n\t\tlet cumulative = 0;\n\t\tlet nextIdx = 0;\n\t\tfor (let i = 0; i < n; i++) {\n\t\t\tconst d = distances[i];\n\t\t\tif (d !== undefined) {\n\t\t\t\tcumulative += d * d;\n\t\t\t\tif (cumulative >= threshold) {\n\t\t\t\t\tnextIdx = i;\n\t\t\t\t\tbreak;\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\n\t\tconst nextFeature = features[nextIdx];\n\t\tif (nextFeature !== undefined) {\n\t\t\tcentroids.push({\n\t\t\t\tf1: nextFeature.f1,\n\t\t\t\tf2: nextFeature.f2,\n\t\t\t\tf3: nextFeature.f3,\n\t\t\t});\n\t\t} else {\n\t\t\t// Fallback: use zero centroid\n\t\t\tcentroids.push({ f1: 0, f2: 0, f3: 0 });\n\t\t}\n\t}\n\n\treturn centroids;\n}\n"],"mappings":"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"}
+{"version":3,"file":"kmeans-CZ7tJFYw.cjs","names":[],"sources":["../src/utils/kmeans.ts"],"sourcesContent":["/**\n * Minimal K-means clustering implementation for GRASP seed selection.\n *\n * This is a lightweight implementation specifically designed for 3D feature vectors\n * used in structural seed selection. For general-purpose clustering, consider\n * using a dedicated library.\n *\n * @packageDocumentation\n */\n\n/**\n * A 3D feature vector representing node structural properties.\n */\nexport interface FeatureVector3D {\n\t/** First dimension (e.g., log-degree) */\n\treadonly f1: number;\n\t/** Second dimension (e.g., clustering coefficient) */\n\treadonly f2: number;\n\t/** Third dimension (e.g., approximate PageRank) */\n\treadonly f3: number;\n}\n\n/**\n * A labelled feature vector with associated node ID.\n */\nexport interface LabelledFeature extends FeatureVector3D {\n\t/** Node identifier */\n\treadonly nodeId: string;\n}\n\n/**\n * Result of K-means clustering.\n */\nexport interface KMeansResult {\n\t/** Cluster centroids */\n\treadonly centroids: readonly FeatureVector3D[];\n\t/** Cluster assignments: nodeId -> cluster index */\n\treadonly assignments: ReadonlyMap<string, number>;\n\t/** Number of clusters */\n\treadonly k: number;\n}\n\n/**\n * Options for K-means clustering.\n */\nexport interface KMeansOptions {\n\t/** Number of clusters */\n\treadonly k: number;\n\t/** Maximum iterations (default: 100) */\n\treadonly maxIterations?: number;\n\t/** Convergence threshold (default: 1e-6) */\n\treadonly tolerance?: number;\n\t/** Random seed for reproducibility */\n\treadonly seed?: number;\n}\n\n/** Small epsilon to prevent division by zero */\nconst EPSILON = 1e-10;\n\n/**\n * Simple seeded pseudo-random number generator using mulberry32.\n */\nfunction createRNG(seed: number): () => number {\n\tlet state = seed >>> 0;\n\treturn (): number => {\n\t\tstate = (state + 0x6d2b79f5) >>> 0;\n\t\tlet t = Math.imul(state ^ (state >>> 15), state | 1);\n\t\tt = (t ^ (t >>> 7)) * (t | 0x61c88647);\n\t\treturn ((t ^ (t >>> 14)) >>> 0) / 4294967296;\n\t};\n}\n\n/**\n * Compute Euclidean distance between two 3D feature vectors.\n */\nfunction euclideanDistance(a: FeatureVector3D, b: FeatureVector3D): number {\n\tconst d1 = a.f1 - b.f1;\n\tconst d2 = a.f2 - b.f2;\n\tconst d3 = a.f3 - b.f3;\n\treturn Math.sqrt(d1 * d1 + d2 * d2 + d3 * d3);\n}\n\n/**\n * Compute the mean of a set of feature vectors.\n * @internal - Used for testing\n */\nexport function _computeMean(\n\tvectors: readonly FeatureVector3D[],\n): FeatureVector3D {\n\tif (vectors.length === 0) {\n\t\treturn { f1: 0, f2: 0, f3: 0 };\n\t}\n\tlet sum1 = 0;\n\tlet sum2 = 0;\n\tlet sum3 = 0;\n\tfor (const v of vectors) {\n\t\tsum1 += v.f1;\n\t\tsum2 += v.f2;\n\t\tsum3 += v.f3;\n\t}\n\tconst n = vectors.length;\n\treturn { f1: sum1 / n, f2: sum2 / n, f3: sum3 / n };\n}\n\n/**\n * Z-score normalise features (zero mean, unit variance).\n */\nexport { normaliseFeatures as zScoreNormalise };\n\nexport function normaliseFeatures(\n\tfeatures: readonly LabelledFeature[],\n): LabelledFeature[] {\n\tif (features.length === 0) {\n\t\treturn [];\n\t}\n\n\t// Compute means\n\tlet sum1 = 0;\n\tlet sum2 = 0;\n\tlet sum3 = 0;\n\tfor (const f of features) {\n\t\tsum1 += f.f1;\n\t\tsum2 += f.f2;\n\t\tsum3 += f.f3;\n\t}\n\tconst n = features.length;\n\tconst mean1 = sum1 / n;\n\tconst mean2 = sum2 / n;\n\tconst mean3 = sum3 / n;\n\n\t// Compute standard deviations\n\tlet var1 = 0;\n\tlet var2 = 0;\n\tlet var3 = 0;\n\tfor (const f of features) {\n\t\tvar1 += (f.f1 - mean1) ** 2;\n\t\tvar2 += (f.f2 - mean2) ** 2;\n\t\tvar3 += (f.f3 - mean3) ** 2;\n\t}\n\tconst std1 = Math.sqrt(var1 / n + EPSILON);\n\tconst std2 = Math.sqrt(var2 / n + EPSILON);\n\tconst std3 = Math.sqrt(var3 / n + EPSILON);\n\n\t// Normalise\n\treturn features.map(\n\t\t(f): LabelledFeature => ({\n\t\t\tnodeId: f.nodeId,\n\t\t\tf1: (f.f1 - mean1) / std1,\n\t\t\tf2: (f.f2 - mean2) / std2,\n\t\t\tf3: (f.f3 - mean3) / std3,\n\t\t}),\n\t);\n}\n\n/**\n * Mini-batch K-means clustering for 3D feature vectors.\n *\n * Uses Mini-batch K-means for efficiency with large datasets.\n * This is specifically designed for the GRASP seed selection algorithm.\n *\n * @param features - Array of labelled feature vectors\n * @param options - Clustering options\n * @returns Clustering result with centroids and assignments\n */\nexport function miniBatchKMeans(\n\tfeatures: readonly LabelledFeature[],\n\toptions: KMeansOptions,\n): KMeansResult {\n\tconst { k, maxIterations = 100, tolerance = 1e-6, seed = 42 } = options;\n\n\tif (features.length === 0) {\n\t\treturn {\n\t\t\tcentroids: [],\n\t\t\tassignments: new Map(),\n\t\t\tk,\n\t\t};\n\t}\n\n\tconst rng = createRNG(seed);\n\tconst n = features.length;\n\tconst effectiveK = Math.min(k, n);\n\n\t// Initialise centroids using k-means++ seeding\n\tconst centroids: FeatureVector3D[] = initialiseCentroidsKMeansPP(\n\t\tfeatures,\n\t\teffectiveK,\n\t\trng,\n\t);\n\n\t// Assignments map\n\tconst assignments = new Map<string, number>();\n\n\t// Mini-batch size (10% of data or at least 10)\n\tconst batchSize = Math.max(10, Math.floor(n / 10));\n\n\tfor (let iter = 0; iter < maxIterations; iter++) {\n\t\t// Sample mini-batch\n\t\tconst batchIndices = new Set<number>();\n\t\twhile (batchIndices.size < Math.min(batchSize, n)) {\n\t\t\tbatchIndices.add(Math.floor(rng() * n));\n\t\t}\n\n\t\t// Assign batch points to nearest centroid\n\t\tconst batchPoints: { feature: LabelledFeature; cluster: number }[] = [];\n\t\tfor (const idx of batchIndices) {\n\t\t\tconst feature = features[idx];\n\t\t\tif (feature === undefined) continue;\n\t\t\tlet minDist = Infinity;\n\t\t\tlet bestCluster = 0;\n\t\t\tfor (let c = 0; c < centroids.length; c++) {\n\t\t\t\tconst centroid = centroids[c];\n\t\t\t\tif (centroid === undefined) continue;\n\t\t\t\tconst dist = euclideanDistance(feature, centroid);\n\t\t\t\tif (dist < minDist) {\n\t\t\t\t\tminDist = dist;\n\t\t\t\t\tbestCluster = c;\n\t\t\t\t}\n\t\t\t}\n\t\t\tbatchPoints.push({ feature, cluster: bestCluster });\n\t\t}\n\n\t\t// Update centroids based on batch\n\t\tconst oldCentroids = centroids.map((c) => ({ ...c }));\n\n\t\t// Compute per-cluster counts and sums from batch\n\t\tconst clusterCounts = Array.from({ length: centroids.length }, () => 0);\n\t\tconst clusterSums: [number, number, number][] = Array.from(\n\t\t\t{ length: centroids.length },\n\t\t\t(): [number, number, number] => [0, 0, 0],\n\t\t);\n\n\t\tfor (const { feature, cluster } of batchPoints) {\n\t\t\tconst currentCount = clusterCounts[cluster];\n\t\t\tif (currentCount !== undefined) {\n\t\t\t\tclusterCounts[cluster] = currentCount + 1;\n\t\t\t}\n\t\t\tconst sum = clusterSums[cluster];\n\t\t\tif (sum !== undefined) {\n\t\t\t\tsum[0] += feature.f1;\n\t\t\t\tsum[1] += feature.f2;\n\t\t\t\tsum[2] += feature.f3;\n\t\t\t}\n\t\t}\n\n\t\t// Update centroids\n\t\tfor (let c = 0; c < centroids.length; c++) {\n\t\t\tconst count = clusterCounts[c] ?? 0;\n\t\t\tif (count > 0) {\n\t\t\t\tconst sum = clusterSums[c];\n\t\t\t\tif (sum !== undefined) {\n\t\t\t\t\tcentroids[c] = {\n\t\t\t\t\t\tf1: sum[0] / count,\n\t\t\t\t\t\tf2: sum[1] / count,\n\t\t\t\t\t\tf3: sum[2] / count,\n\t\t\t\t\t};\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\n\t\t// Check convergence\n\t\tlet maxShift = 0;\n\t\tfor (let c = 0; c < centroids.length; c++) {\n\t\t\tconst newCentroid = centroids[c];\n\t\t\tconst oldCentroid = oldCentroids[c];\n\t\t\tif (newCentroid !== undefined && oldCentroid !== undefined) {\n\t\t\t\tconst shift = euclideanDistance(newCentroid, oldCentroid);\n\t\t\t\tmaxShift = Math.max(maxShift, shift);\n\t\t\t}\n\t\t}\n\n\t\tif (maxShift < tolerance) {\n\t\t\tbreak;\n\t\t}\n\t}\n\n\t// Final assignment of all points\n\tfor (const feature of features) {\n\t\tlet minDist = Infinity;\n\t\tlet bestCluster = 0;\n\t\tfor (let c = 0; c < centroids.length; c++) {\n\t\t\tconst centroid = centroids[c];\n\t\t\tif (centroid === undefined) continue;\n\t\t\tconst dist = euclideanDistance(feature, centroid);\n\t\t\tif (dist < minDist) {\n\t\t\t\tminDist = dist;\n\t\t\t\tbestCluster = c;\n\t\t\t}\n\t\t}\n\t\tassignments.set(feature.nodeId, bestCluster);\n\t}\n\n\treturn {\n\t\tcentroids,\n\t\tassignments,\n\t\tk: effectiveK,\n\t};\n}\n\n/**\n * K-means++ initialisation for better centroid seeding.\n */\nfunction initialiseCentroidsKMeansPP(\n\tfeatures: readonly LabelledFeature[],\n\tk: number,\n\trng: () => number,\n): FeatureVector3D[] {\n\tconst centroids: FeatureVector3D[] = [];\n\tconst n = features.length;\n\n\t// Choose first centroid randomly\n\tconst firstIdx = Math.floor(rng() * n);\n\tconst firstFeature = features[firstIdx];\n\tif (firstFeature === undefined) {\n\t\treturn [{ f1: 0, f2: 0, f3: 0 }];\n\t}\n\tcentroids.push({\n\t\tf1: firstFeature.f1,\n\t\tf2: firstFeature.f2,\n\t\tf3: firstFeature.f3,\n\t});\n\n\t// Choose remaining centroids with probability proportional to squared distance\n\tconst distances = Array.from({ length: n }, () => Infinity);\n\n\tfor (let c = 1; c < k; c++) {\n\t\t// Update distances to nearest centroid\n\t\tlet totalDistSq = 0;\n\t\tfor (let i = 0; i < n; i++) {\n\t\t\tconst feature = features[i];\n\t\t\tif (feature === undefined) continue;\n\t\t\tconst lastCentroid = centroids[c - 1];\n\t\t\tif (lastCentroid === undefined) continue;\n\t\t\tconst dist = euclideanDistance(feature, lastCentroid);\n\t\t\tconst currentMin = distances[i];\n\t\t\tif (currentMin !== undefined && dist < currentMin) {\n\t\t\t\tdistances[i] = dist;\n\t\t\t}\n\t\t\tconst d = distances[i];\n\t\t\tif (d !== undefined) {\n\t\t\t\ttotalDistSq += d * d;\n\t\t\t}\n\t\t}\n\n\t\t// Choose next centroid with probability proportional to squared distance\n\t\tconst threshold = rng() * totalDistSq;\n\t\tlet cumulative = 0;\n\t\tlet nextIdx = 0;\n\t\tfor (let i = 0; i < n; i++) {\n\t\t\tconst d = distances[i];\n\t\t\tif (d !== undefined) {\n\t\t\t\tcumulative += d * d;\n\t\t\t\tif (cumulative >= threshold) {\n\t\t\t\t\tnextIdx = i;\n\t\t\t\t\tbreak;\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\n\t\tconst nextFeature = features[nextIdx];\n\t\tif (nextFeature !== undefined) {\n\t\t\tcentroids.push({\n\t\t\t\tf1: nextFeature.f1,\n\t\t\t\tf2: nextFeature.f2,\n\t\t\t\tf3: nextFeature.f3,\n\t\t\t});\n\t\t} else {\n\t\t\t// Fallback: use zero centroid\n\t\t\tcentroids.push({ f1: 0, f2: 0, f3: 0 });\n\t\t}\n\t}\n\n\treturn centroids;\n}\n"],"mappings":"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"}

package/dist/{kmeans-DKkL9rAN.js → kmeans-DLrlrp6i.js}

@@ -245,4 +245,4 @@ function initialiseCentroidsKMeansPP(features, k, rng) {
 //#endregion
 export { miniBatchKMeans as n, normaliseFeatures as r, _computeMean as t };
 
-//# sourceMappingURL=kmeans-DKkL9rAN.js.map
+//# sourceMappingURL=kmeans-DLrlrp6i.js.map

package/dist/{kmeans-DKkL9rAN.js.map → kmeans-DLrlrp6i.js.map}

@@ -1 +1 @@
-{"version":3,"file":"kmeans-DKkL9rAN.js","names":[],"sources":["../src/utils/kmeans.ts"],"sourcesContent":["/**\n * Minimal K-means clustering implementation for GRASP seed selection.\n *\n * This is a lightweight implementation specifically designed for 3D feature vectors\n * used in structural seed selection. For general-purpose clustering, consider\n * using a dedicated library.\n *\n * @packageDocumentation\n */\n\n/**\n * A 3D feature vector representing node structural properties.\n */\nexport interface FeatureVector3D {\n\t/** First dimension (e.g., log-degree) */\n\treadonly f1: number;\n\t/** Second dimension (e.g., clustering coefficient) */\n\treadonly f2: number;\n\t/** Third dimension (e.g., approximate PageRank) */\n\treadonly f3: number;\n}\n\n/**\n * A labelled feature vector with associated node ID.\n */\nexport interface LabelledFeature extends FeatureVector3D {\n\t/** Node identifier */\n\treadonly nodeId: string;\n}\n\n/**\n * Result of K-means clustering.\n */\nexport interface KMeansResult {\n\t/** Cluster centroids */\n\treadonly centroids: readonly FeatureVector3D[];\n\t/** Cluster assignments: nodeId -> cluster index */\n\treadonly assignments: ReadonlyMap<string, number>;\n\t/** Number of clusters */\n\treadonly k: number;\n}\n\n/**\n * Options for K-means clustering.\n */\nexport interface KMeansOptions {\n\t/** Number of clusters */\n\treadonly k: number;\n\t/** Maximum iterations (default: 100) */\n\treadonly maxIterations?: number;\n\t/** Convergence threshold (default: 1e-6) */\n\treadonly tolerance?: number;\n\t/** Random seed for reproducibility */\n\treadonly seed?: number;\n}\n\n/** Small epsilon to prevent division by zero */\nconst EPSILON = 1e-10;\n\n/**\n * Simple seeded pseudo-random number generator using mulberry32.\n */\nfunction createRNG(seed: number): () => number {\n\tlet state = seed >>> 0;\n\treturn (): number => {\n\t\tstate = (state + 0x6d2b79f5) >>> 0;\n\t\tlet t = Math.imul(state ^ (state >>> 15), state | 1);\n\t\tt = (t ^ (t >>> 7)) * (t | 0x61c88647);\n\t\treturn ((t ^ (t >>> 14)) >>> 0) / 4294967296;\n\t};\n}\n\n/**\n * Compute Euclidean distance between two 3D feature vectors.\n */\nfunction euclideanDistance(a: FeatureVector3D, b: FeatureVector3D): number {\n\tconst d1 = a.f1 - b.f1;\n\tconst d2 = a.f2 - b.f2;\n\tconst d3 = a.f3 - b.f3;\n\treturn Math.sqrt(d1 * d1 + d2 * d2 + d3 * d3);\n}\n\n/**\n * Compute the mean of a set of feature vectors.\n * @internal - Used for testing\n */\nexport function _computeMean(\n\tvectors: readonly FeatureVector3D[],\n): FeatureVector3D {\n\tif (vectors.length === 0) {\n\t\treturn { f1: 0, f2: 0, f3: 0 };\n\t}\n\tlet sum1 = 0;\n\tlet sum2 = 0;\n\tlet sum3 = 0;\n\tfor (const v of vectors) {\n\t\tsum1 += v.f1;\n\t\tsum2 += v.f2;\n\t\tsum3 += v.f3;\n\t}\n\tconst n = vectors.length;\n\treturn { f1: sum1 / n, f2: sum2 / n, f3: sum3 / n };\n}\n\n/**\n * Z-score normalise features (zero mean, unit variance).\n */\nexport { normaliseFeatures as zScoreNormalise };\n\nexport function normaliseFeatures(\n\tfeatures: readonly LabelledFeature[],\n): LabelledFeature[] {\n\tif (features.length === 0) {\n\t\treturn [];\n\t}\n\n\t// Compute means\n\tlet sum1 = 0;\n\tlet sum2 = 0;\n\tlet sum3 = 0;\n\tfor (const f of features) {\n\t\tsum1 += f.f1;\n\t\tsum2 += f.f2;\n\t\tsum3 += f.f3;\n\t}\n\tconst n = features.length;\n\tconst mean1 = sum1 / n;\n\tconst mean2 = sum2 / n;\n\tconst mean3 = sum3 / n;\n\n\t// Compute standard deviations\n\tlet var1 = 0;\n\tlet var2 = 0;\n\tlet var3 = 0;\n\tfor (const f of features) {\n\t\tvar1 += (f.f1 - mean1) ** 2;\n\t\tvar2 += (f.f2 - mean2) ** 2;\n\t\tvar3 += (f.f3 - mean3) ** 2;\n\t}\n\tconst std1 = Math.sqrt(var1 / n + EPSILON);\n\tconst std2 = Math.sqrt(var2 / n + EPSILON);\n\tconst std3 = Math.sqrt(var3 / n + EPSILON);\n\n\t// Normalise\n\treturn features.map(\n\t\t(f): LabelledFeature => ({\n\t\t\tnodeId: f.nodeId,\n\t\t\tf1: (f.f1 - mean1) / std1,\n\t\t\tf2: (f.f2 - mean2) / std2,\n\t\t\tf3: (f.f3 - mean3) / std3,\n\t\t}),\n\t);\n}\n\n/**\n * Mini-batch K-means clustering for 3D feature vectors.\n *\n * Uses Mini-batch K-means for efficiency with large datasets.\n * This is specifically designed for the GRASP seed selection algorithm.\n *\n * @param features - Array of labelled feature vectors\n * @param options - Clustering options\n * @returns Clustering result with centroids and assignments\n */\nexport function miniBatchKMeans(\n\tfeatures: readonly LabelledFeature[],\n\toptions: KMeansOptions,\n): KMeansResult {\n\tconst { k, maxIterations = 100, tolerance = 1e-6, seed = 42 } = options;\n\n\tif (features.length === 0) {\n\t\treturn {\n\t\t\tcentroids: [],\n\t\t\tassignments: new Map(),\n\t\t\tk,\n\t\t};\n\t}\n\n\tconst rng = createRNG(seed);\n\tconst n = features.length;\n\tconst effectiveK = Math.min(k, n);\n\n\t// Initialise centroids using k-means++ seeding\n\tconst centroids: FeatureVector3D[] = initialiseCentroidsKMeansPP(\n\t\tfeatures,\n\t\teffectiveK,\n\t\trng,\n\t);\n\n\t// Assignments map\n\tconst assignments = new Map<string, number>();\n\n\t// Mini-batch size (10% of data or at least 10)\n\tconst batchSize = Math.max(10, Math.floor(n / 10));\n\n\tfor (let iter = 0; iter < maxIterations; iter++) {\n\t\t// Sample mini-batch\n\t\tconst batchIndices = new Set<number>();\n\t\twhile (batchIndices.size < Math.min(batchSize, n)) {\n\t\t\tbatchIndices.add(Math.floor(rng() * n));\n\t\t}\n\n\t\t// Assign batch points to nearest centroid\n\t\tconst batchPoints: { feature: LabelledFeature; cluster: number }[] = [];\n\t\tfor (const idx of batchIndices) {\n\t\t\tconst feature = features[idx];\n\t\t\tif (feature === undefined) continue;\n\t\t\tlet minDist = Infinity;\n\t\t\tlet bestCluster = 0;\n\t\t\tfor (let c = 0; c < centroids.length; c++) {\n\t\t\t\tconst centroid = centroids[c];\n\t\t\t\tif (centroid === undefined) continue;\n\t\t\t\tconst dist = euclideanDistance(feature, centroid);\n\t\t\t\tif (dist < minDist) {\n\t\t\t\t\tminDist = dist;\n\t\t\t\t\tbestCluster = c;\n\t\t\t\t}\n\t\t\t}\n\t\t\tbatchPoints.push({ feature, cluster: bestCluster });\n\t\t}\n\n\t\t// Update centroids based on batch\n\t\tconst oldCentroids = centroids.map((c) => ({ ...c }));\n\n\t\t// Compute per-cluster counts and sums from batch\n\t\tconst clusterCounts = Array.from({ length: centroids.length }, () => 0);\n\t\tconst clusterSums: [number, number, number][] = Array.from(\n\t\t\t{ length: centroids.length },\n\t\t\t(): [number, number, number] => [0, 0, 0],\n\t\t);\n\n\t\tfor (const { feature, cluster } of batchPoints) {\n\t\t\tconst currentCount = clusterCounts[cluster];\n\t\t\tif (currentCount !== undefined) {\n\t\t\t\tclusterCounts[cluster] = currentCount + 1;\n\t\t\t}\n\t\t\tconst sum = clusterSums[cluster];\n\t\t\tif (sum !== undefined) {\n\t\t\t\tsum[0] += feature.f1;\n\t\t\t\tsum[1] += feature.f2;\n\t\t\t\tsum[2] += feature.f3;\n\t\t\t}\n\t\t}\n\n\t\t// Update centroids\n\t\tfor (let c = 0; c < centroids.length; c++) {\n\t\t\tconst count = clusterCounts[c] ?? 0;\n\t\t\tif (count > 0) {\n\t\t\t\tconst sum = clusterSums[c];\n\t\t\t\tif (sum !== undefined) {\n\t\t\t\t\tcentroids[c] = {\n\t\t\t\t\t\tf1: sum[0] / count,\n\t\t\t\t\t\tf2: sum[1] / count,\n\t\t\t\t\t\tf3: sum[2] / count,\n\t\t\t\t\t};\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\n\t\t// Check convergence\n\t\tlet maxShift = 0;\n\t\tfor (let c = 0; c < centroids.length; c++) {\n\t\t\tconst newCentroid = centroids[c];\n\t\t\tconst oldCentroid = oldCentroids[c];\n\t\t\tif (newCentroid !== undefined && oldCentroid !== undefined) {\n\t\t\t\tconst shift = euclideanDistance(newCentroid, oldCentroid);\n\t\t\t\tmaxShift = Math.max(maxShift, shift);\n\t\t\t}\n\t\t}\n\n\t\tif (maxShift < tolerance) {\n\t\t\tbreak;\n\t\t}\n\t}\n\n\t// Final assignment of all points\n\tfor (const feature of features) {\n\t\tlet minDist = Infinity;\n\t\tlet bestCluster = 0;\n\t\tfor (let c = 0; c < centroids.length; c++) {\n\t\t\tconst centroid = centroids[c];\n\t\t\tif (centroid === undefined) continue;\n\t\t\tconst dist = euclideanDistance(feature, centroid);\n\t\t\tif (dist < minDist) {\n\t\t\t\tminDist = dist;\n\t\t\t\tbestCluster = c;\n\t\t\t}\n\t\t}\n\t\tassignments.set(feature.nodeId, bestCluster);\n\t}\n\n\treturn {\n\t\tcentroids,\n\t\tassignments,\n\t\tk: effectiveK,\n\t};\n}\n\n/**\n * K-means++ initialisation for better centroid seeding.\n */\nfunction initialiseCentroidsKMeansPP(\n\tfeatures: readonly LabelledFeature[],\n\tk: number,\n\trng: () => number,\n): FeatureVector3D[] {\n\tconst centroids: FeatureVector3D[] = [];\n\tconst n = features.length;\n\n\t// Choose first centroid randomly\n\tconst firstIdx = Math.floor(rng() * n);\n\tconst firstFeature = features[firstIdx];\n\tif (firstFeature === undefined) {\n\t\treturn [{ f1: 0, f2: 0, f3: 0 }];\n\t}\n\tcentroids.push({\n\t\tf1: firstFeature.f1,\n\t\tf2: firstFeature.f2,\n\t\tf3: firstFeature.f3,\n\t});\n\n\t// Choose remaining centroids with probability proportional to squared distance\n\tconst distances = Array.from({ length: n }, () => Infinity);\n\n\tfor (let c = 1; c < k; c++) {\n\t\t// Update distances to nearest centroid\n\t\tlet totalDistSq = 0;\n\t\tfor (let i = 0; i < n; i++) {\n\t\t\tconst feature = features[i];\n\t\t\tif (feature === undefined) continue;\n\t\t\tconst lastCentroid = centroids[c - 1];\n\t\t\tif (lastCentroid === undefined) continue;\n\t\t\tconst dist = euclideanDistance(feature, lastCentroid);\n\t\t\tconst currentMin = distances[i];\n\t\t\tif (currentMin !== undefined && dist < currentMin) {\n\t\t\t\tdistances[i] = dist;\n\t\t\t}\n\t\t\tconst d = distances[i];\n\t\t\tif (d !== undefined) {\n\t\t\t\ttotalDistSq += d * d;\n\t\t\t}\n\t\t}\n\n\t\t// Choose next centroid with probability proportional to squared distance\n\t\tconst threshold = rng() * totalDistSq;\n\t\tlet cumulative = 0;\n\t\tlet nextIdx = 0;\n\t\tfor (let i = 0; i < n; i++) {\n\t\t\tconst d = distances[i];\n\t\t\tif (d !== undefined) {\n\t\t\t\tcumulative += d * d;\n\t\t\t\tif (cumulative >= threshold) {\n\t\t\t\t\tnextIdx = i;\n\t\t\t\t\tbreak;\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\n\t\tconst nextFeature = features[nextIdx];\n\t\tif (nextFeature !== undefined) {\n\t\t\tcentroids.push({\n\t\t\t\tf1: nextFeature.f1,\n\t\t\t\tf2: nextFeature.f2,\n\t\t\t\tf3: nextFeature.f3,\n\t\t\t});\n\t\t} else {\n\t\t\t// Fallback: use zero centroid\n\t\t\tcentroids.push({ f1: 0, f2: 0, f3: 0 });\n\t\t}\n\t}\n\n\treturn centroids;\n}\n"],"mappings":"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"}
+{"version":3,"file":"kmeans-DLrlrp6i.js","names":[],"sources":["../src/utils/kmeans.ts"],"sourcesContent":["/**\n * Minimal K-means clustering implementation for GRASP seed selection.\n *\n * This is a lightweight implementation specifically designed for 3D feature vectors\n * used in structural seed selection. For general-purpose clustering, consider\n * using a dedicated library.\n *\n * @packageDocumentation\n */\n\n/**\n * A 3D feature vector representing node structural properties.\n */\nexport interface FeatureVector3D {\n\t/** First dimension (e.g., log-degree) */\n\treadonly f1: number;\n\t/** Second dimension (e.g., clustering coefficient) */\n\treadonly f2: number;\n\t/** Third dimension (e.g., approximate PageRank) */\n\treadonly f3: number;\n}\n\n/**\n * A labelled feature vector with associated node ID.\n */\nexport interface LabelledFeature extends FeatureVector3D {\n\t/** Node identifier */\n\treadonly nodeId: string;\n}\n\n/**\n * Result of K-means clustering.\n */\nexport interface KMeansResult {\n\t/** Cluster centroids */\n\treadonly centroids: readonly FeatureVector3D[];\n\t/** Cluster assignments: nodeId -> cluster index */\n\treadonly assignments: ReadonlyMap<string, number>;\n\t/** Number of clusters */\n\treadonly k: number;\n}\n\n/**\n * Options for K-means clustering.\n */\nexport interface KMeansOptions {\n\t/** Number of clusters */\n\treadonly k: number;\n\t/** Maximum iterations (default: 100) */\n\treadonly maxIterations?: number;\n\t/** Convergence threshold (default: 1e-6) */\n\treadonly tolerance?: number;\n\t/** Random seed for reproducibility */\n\treadonly seed?: number;\n}\n\n/** Small epsilon to prevent division by zero */\nconst EPSILON = 1e-10;\n\n/**\n * Simple seeded pseudo-random number generator using mulberry32.\n */\nfunction createRNG(seed: number): () => number {\n\tlet state = seed >>> 0;\n\treturn (): number => {\n\t\tstate = (state + 0x6d2b79f5) >>> 0;\n\t\tlet t = Math.imul(state ^ (state >>> 15), state | 1);\n\t\tt = (t ^ (t >>> 7)) * (t | 0x61c88647);\n\t\treturn ((t ^ (t >>> 14)) >>> 0) / 4294967296;\n\t};\n}\n\n/**\n * Compute Euclidean distance between two 3D feature vectors.\n */\nfunction euclideanDistance(a: FeatureVector3D, b: FeatureVector3D): number {\n\tconst d1 = a.f1 - b.f1;\n\tconst d2 = a.f2 - b.f2;\n\tconst d3 = a.f3 - b.f3;\n\treturn Math.sqrt(d1 * d1 + d2 * d2 + d3 * d3);\n}\n\n/**\n * Compute the mean of a set of feature vectors.\n * @internal - Used for testing\n */\nexport function _computeMean(\n\tvectors: readonly FeatureVector3D[],\n): FeatureVector3D {\n\tif (vectors.length === 0) {\n\t\treturn { f1: 0, f2: 0, f3: 0 };\n\t}\n\tlet sum1 = 0;\n\tlet sum2 = 0;\n\tlet sum3 = 0;\n\tfor (const v of vectors) {\n\t\tsum1 += v.f1;\n\t\tsum2 += v.f2;\n\t\tsum3 += v.f3;\n\t}\n\tconst n = vectors.length;\n\treturn { f1: sum1 / n, f2: sum2 / n, f3: sum3 / n };\n}\n\n/**\n * Z-score normalise features (zero mean, unit variance).\n */\nexport { normaliseFeatures as zScoreNormalise };\n\nexport function normaliseFeatures(\n\tfeatures: readonly LabelledFeature[],\n): LabelledFeature[] {\n\tif (features.length === 0) {\n\t\treturn [];\n\t}\n\n\t// Compute means\n\tlet sum1 = 0;\n\tlet sum2 = 0;\n\tlet sum3 = 0;\n\tfor (const f of features) {\n\t\tsum1 += f.f1;\n\t\tsum2 += f.f2;\n\t\tsum3 += f.f3;\n\t}\n\tconst n = features.length;\n\tconst mean1 = sum1 / n;\n\tconst mean2 = sum2 / n;\n\tconst mean3 = sum3 / n;\n\n\t// Compute standard deviations\n\tlet var1 = 0;\n\tlet var2 = 0;\n\tlet var3 = 0;\n\tfor (const f of features) {\n\t\tvar1 += (f.f1 - mean1) ** 2;\n\t\tvar2 += (f.f2 - mean2) ** 2;\n\t\tvar3 += (f.f3 - mean3) ** 2;\n\t}\n\tconst std1 = Math.sqrt(var1 / n + EPSILON);\n\tconst std2 = Math.sqrt(var2 / n + EPSILON);\n\tconst std3 = Math.sqrt(var3 / n + EPSILON);\n\n\t// Normalise\n\treturn features.map(\n\t\t(f): LabelledFeature => ({\n\t\t\tnodeId: f.nodeId,\n\t\t\tf1: (f.f1 - mean1) / std1,\n\t\t\tf2: (f.f2 - mean2) / std2,\n\t\t\tf3: (f.f3 - mean3) / std3,\n\t\t}),\n\t);\n}\n\n/**\n * Mini-batch K-means clustering for 3D feature vectors.\n *\n * Uses Mini-batch K-means for efficiency with large datasets.\n * This is specifically designed for the GRASP seed selection algorithm.\n *\n * @param features - Array of labelled feature vectors\n * @param options - Clustering options\n * @returns Clustering result with centroids and assignments\n */\nexport function miniBatchKMeans(\n\tfeatures: readonly LabelledFeature[],\n\toptions: KMeansOptions,\n): KMeansResult {\n\tconst { k, maxIterations = 100, tolerance = 1e-6, seed = 42 } = options;\n\n\tif (features.length === 0) {\n\t\treturn {\n\t\t\tcentroids: [],\n\t\t\tassignments: new Map(),\n\t\t\tk,\n\t\t};\n\t}\n\n\tconst rng = createRNG(seed);\n\tconst n = features.length;\n\tconst effectiveK = Math.min(k, n);\n\n\t// Initialise centroids using k-means++ seeding\n\tconst centroids: FeatureVector3D[] = initialiseCentroidsKMeansPP(\n\t\tfeatures,\n\t\teffectiveK,\n\t\trng,\n\t);\n\n\t// Assignments map\n\tconst assignments = new Map<string, number>();\n\n\t// Mini-batch size (10% of data or at least 10)\n\tconst batchSize = Math.max(10, Math.floor(n / 10));\n\n\tfor (let iter = 0; iter < maxIterations; iter++) {\n\t\t// Sample mini-batch\n\t\tconst batchIndices = new Set<number>();\n\t\twhile (batchIndices.size < Math.min(batchSize, n)) {\n\t\t\tbatchIndices.add(Math.floor(rng() * n));\n\t\t}\n\n\t\t// Assign batch points to nearest centroid\n\t\tconst batchPoints: { feature: LabelledFeature; cluster: number }[] = [];\n\t\tfor (const idx of batchIndices) {\n\t\t\tconst feature = features[idx];\n\t\t\tif (feature === undefined) continue;\n\t\t\tlet minDist = Infinity;\n\t\t\tlet bestCluster = 0;\n\t\t\tfor (let c = 0; c < centroids.length; c++) {\n\t\t\t\tconst centroid = centroids[c];\n\t\t\t\tif (centroid === undefined) continue;\n\t\t\t\tconst dist = euclideanDistance(feature, centroid);\n\t\t\t\tif (dist < minDist) {\n\t\t\t\t\tminDist = dist;\n\t\t\t\t\tbestCluster = c;\n\t\t\t\t}\n\t\t\t}\n\t\t\tbatchPoints.push({ feature, cluster: bestCluster });\n\t\t}\n\n\t\t// Update centroids based on batch\n\t\tconst oldCentroids = centroids.map((c) => ({ ...c }));\n\n\t\t// Compute per-cluster counts and sums from batch\n\t\tconst clusterCounts = Array.from({ length: centroids.length }, () => 0);\n\t\tconst clusterSums: [number, number, number][] = Array.from(\n\t\t\t{ length: centroids.length },\n\t\t\t(): [number, number, number] => [0, 0, 0],\n\t\t);\n\n\t\tfor (const { feature, cluster } of batchPoints) {\n\t\t\tconst currentCount = clusterCounts[cluster];\n\t\t\tif (currentCount !== undefined) {\n\t\t\t\tclusterCounts[cluster] = currentCount + 1;\n\t\t\t}\n\t\t\tconst sum = clusterSums[cluster];\n\t\t\tif (sum !== undefined) {\n\t\t\t\tsum[0] += feature.f1;\n\t\t\t\tsum[1] += feature.f2;\n\t\t\t\tsum[2] += feature.f3;\n\t\t\t}\n\t\t}\n\n\t\t// Update centroids\n\t\tfor (let c = 0; c < centroids.length; c++) {\n\t\t\tconst count = clusterCounts[c] ?? 0;\n\t\t\tif (count > 0) {\n\t\t\t\tconst sum = clusterSums[c];\n\t\t\t\tif (sum !== undefined) {\n\t\t\t\t\tcentroids[c] = {\n\t\t\t\t\t\tf1: sum[0] / count,\n\t\t\t\t\t\tf2: sum[1] / count,\n\t\t\t\t\t\tf3: sum[2] / count,\n\t\t\t\t\t};\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\n\t\t// Check convergence\n\t\tlet maxShift = 0;\n\t\tfor (let c = 0; c < centroids.length; c++) {\n\t\t\tconst newCentroid = centroids[c];\n\t\t\tconst oldCentroid = oldCentroids[c];\n\t\t\tif (newCentroid !== undefined && oldCentroid !== undefined) {\n\t\t\t\tconst shift = euclideanDistance(newCentroid, oldCentroid);\n\t\t\t\tmaxShift = Math.max(maxShift, shift);\n\t\t\t}\n\t\t}\n\n\t\tif (maxShift < tolerance) {\n\t\t\tbreak;\n\t\t}\n\t}\n\n\t// Final assignment of all points\n\tfor (const feature of features) {\n\t\tlet minDist = Infinity;\n\t\tlet bestCluster = 0;\n\t\tfor (let c = 0; c < centroids.length; c++) {\n\t\t\tconst centroid = centroids[c];\n\t\t\tif (centroid === undefined) continue;\n\t\t\tconst dist = euclideanDistance(feature, centroid);\n\t\t\tif (dist < minDist) {\n\t\t\t\tminDist = dist;\n\t\t\t\tbestCluster = c;\n\t\t\t}\n\t\t}\n\t\tassignments.set(feature.nodeId, bestCluster);\n\t}\n\n\treturn {\n\t\tcentroids,\n\t\tassignments,\n\t\tk: effectiveK,\n\t};\n}\n\n/**\n * K-means++ initialisation for better centroid seeding.\n */\nfunction initialiseCentroidsKMeansPP(\n\tfeatures: readonly LabelledFeature[],\n\tk: number,\n\trng: () => number,\n): FeatureVector3D[] {\n\tconst centroids: FeatureVector3D[] = [];\n\tconst n = features.length;\n\n\t// Choose first centroid randomly\n\tconst firstIdx = Math.floor(rng() * n);\n\tconst firstFeature = features[firstIdx];\n\tif (firstFeature === undefined) {\n\t\treturn [{ f1: 0, f2: 0, f3: 0 }];\n\t}\n\tcentroids.push({\n\t\tf1: firstFeature.f1,\n\t\tf2: firstFeature.f2,\n\t\tf3: firstFeature.f3,\n\t});\n\n\t// Choose remaining centroids with probability proportional to squared distance\n\tconst distances = Array.from({ length: n }, () => Infinity);\n\n\tfor (let c = 1; c < k; c++) {\n\t\t// Update distances to nearest centroid\n\t\tlet totalDistSq = 0;\n\t\tfor (let i = 0; i < n; i++) {\n\t\t\tconst feature = features[i];\n\t\t\tif (feature === undefined) continue;\n\t\t\tconst lastCentroid = centroids[c - 1];\n\t\t\tif (lastCentroid === undefined) continue;\n\t\t\tconst dist = euclideanDistance(feature, lastCentroid);\n\t\t\tconst currentMin = distances[i];\n\t\t\tif (currentMin !== undefined && dist < currentMin) {\n\t\t\t\tdistances[i] = dist;\n\t\t\t}\n\t\t\tconst d = distances[i];\n\t\t\tif (d !== undefined) {\n\t\t\t\ttotalDistSq += d * d;\n\t\t\t}\n\t\t}\n\n\t\t// Choose next centroid with probability proportional to squared distance\n\t\tconst threshold = rng() * totalDistSq;\n\t\tlet cumulative = 0;\n\t\tlet nextIdx = 0;\n\t\tfor (let i = 0; i < n; i++) {\n\t\t\tconst d = distances[i];\n\t\t\tif (d !== undefined) {\n\t\t\t\tcumulative += d * d;\n\t\t\t\tif (cumulative >= threshold) {\n\t\t\t\t\tnextIdx = i;\n\t\t\t\t\tbreak;\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\n\t\tconst nextFeature = features[nextIdx];\n\t\tif (nextFeature !== undefined) {\n\t\t\tcentroids.push({\n\t\t\t\tf1: nextFeature.f1,\n\t\t\t\tf2: nextFeature.f2,\n\t\t\t\tf3: nextFeature.f3,\n\t\t\t});\n\t\t} else {\n\t\t\t// Fallback: use zero centroid\n\t\t\tcentroids.push({ f1: 0, f2: 0, f3: 0 });\n\t\t}\n\t}\n\n\treturn centroids;\n}\n"],"mappings":"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"}

package/dist/logic-Dbyfb_-7.cjs

@@ -0,0 +1,289 @@
+const require_typegpu = require("./typegpu-Dq5FfUB8.cjs");
+//#region src/gpu/csr.ts
+/**
+* Compressed Sparse Row (CSR) matrix representation for GPU computation.
+*
+* CSR format is memory-efficient for sparse graphs and maps well to
+* GPU parallel operations. The format stores adjacency information
+* in three arrays: row offsets, column indices, and optional values.
+*/
+/**
+* Convert a ReadableGraph to CSR format.
+*
+* For undirected graphs, each edge is stored twice (once in each direction).
+* For directed graphs, edges are stored in the out-direction by default.
+*
+* @param graph - The graph to convert
+* @param direction - Edge direction to include (default: 'out' for directed, 'both' for undirected)
+* @returns CSR representation with index mapping
+*/
+function graphToCSR(graph, direction = graph.directed ? "out" : "both") {
+	const nodeToIndex = /* @__PURE__ */ new Map();
+	const indexToNode = [];
+	for (const nodeId of graph.nodeIds()) {
+		const index = indexToNode.length;
+		nodeToIndex.set(nodeId, index);
+		indexToNode.push(nodeId);
+	}
+	const nodeCount = indexToNode.length;
+	const degrees = new Uint32Array(nodeCount);
+	for (const nodeId of graph.nodeIds()) {
+		const srcIndex = nodeToIndex.get(nodeId);
+		if (srcIndex === void 0) continue;
+		degrees[srcIndex] = graph.degree(nodeId, direction);
+	}
+	let totalEdges = 0;
+	for (let i = 0; i < nodeCount; i++) totalEdges += degrees[i] ?? 0;
+	const rowOffsets = new Uint32Array(nodeCount + 1);
+	for (let i = 0; i < nodeCount; i++) rowOffsets[i + 1] = (rowOffsets[i] ?? 0) + (degrees[i] ?? 0);
+	const colIndices = new Uint32Array(totalEdges);
+	const values = new Float32Array(totalEdges);
+	for (const nodeId of graph.nodeIds()) {
+		const srcIndex = nodeToIndex.get(nodeId);
+		if (srcIndex === void 0) continue;
+		const baseOffset = rowOffsets[srcIndex] ?? 0;
+		let localOffset = 0;
+		for (const neighbourId of graph.neighbours(nodeId, direction)) {
+			const dstIndex = nodeToIndex.get(neighbourId);
+			if (dstIndex === void 0) continue;
+			const edgeIdx = baseOffset + localOffset;
+			colIndices[edgeIdx] = dstIndex;
+			values[edgeIdx] = graph.getEdge(nodeId, neighbourId)?.weight ?? 1;
+			localOffset++;
+		}
+	}
+	return {
+		csr: {
+			rowOffsets,
+			colIndices,
+			values,
+			nodeCount,
+			edgeCount: graph.directed ? graph.edgeCount : graph.edgeCount * 2
+		},
+		indexMap: {
+			nodeToIndex,
+			indexToNode
+		}
+	};
+}
+/**
+* Create TypeGPU typed buffers from a CSR matrix.
+*
+* Uses TypeGPU's typed buffer API for type-safe GPU computation.
+* Buffers are created with storage usage for compute operations.
+*
+* @param root - TypeGPU root instance
+* @param csr - CSR matrix to upload
+* @returns Typed buffer group
+*
+* @example
+* ```typescript
+* import { initGPU, csrToTypedBuffers, graphToCSR } from "graphwise/gpu";
+*
+* const root = await initGPU();
+* const { csr } = graphToCSR(graph);
+* const buffers = csrToTypedBuffers(root, csr);
+*
+* // Read data back to CPU
+* const rowOffsets = await buffers.rowOffsets.read();
+* console.log(rowOffsets); // Uint32Array
+* ```
+*/
+function csrToTypedBuffers(root, csr) {
+	const rowOffsetsArray = Array.from(csr.rowOffsets);
+	const colIndicesArray = Array.from(csr.colIndices);
+	const rowOffsetsBuffer = (globalThis.__TYPEGPU_AUTONAME__ ?? ((a) => a))(root.createBuffer(require_typegpu.data_exports.arrayOf(require_typegpu.data_exports.u32, csr.rowOffsets.length), rowOffsetsArray).$usage("storage"), "rowOffsetsBuffer");
+	const colIndicesBuffer = (globalThis.__TYPEGPU_AUTONAME__ ?? ((a) => a))(root.createBuffer(require_typegpu.data_exports.arrayOf(require_typegpu.data_exports.u32, csr.colIndices.length), colIndicesArray).$usage("storage"), "colIndicesBuffer");
+	if (csr.values !== void 0) {
+		const valuesArray = Array.from(csr.values);
+		return {
+			rowOffsets: rowOffsetsBuffer,
+			colIndices: colIndicesBuffer,
+			values: (globalThis.__TYPEGPU_AUTONAME__ ?? ((a) => a))(root.createBuffer(require_typegpu.data_exports.arrayOf(require_typegpu.data_exports.f32, csr.values.length), valuesArray).$usage("storage"), "valuesBuffer"),
+			nodeCount: csr.nodeCount,
+			edgeCount: csr.edgeCount
+		};
+	}
+	return {
+		rowOffsets: rowOffsetsBuffer,
+		colIndices: colIndicesBuffer,
+		nodeCount: csr.nodeCount,
+		edgeCount: csr.edgeCount
+	};
+}
+//#endregion
+//#region src/gpu/kernels/intersection/logic.ts
+/**
+* Binary search in a sorted subarray of colIndices.
+*
+* @param colIndices - CSR column indices array (must be sorted per row)
+* @param start - Start index (inclusive)
+* @param end - End index (exclusive)
+* @param target - Value to search for
+* @returns true if target is found between colIndices[start] and colIndices[end-1]
+*/
+function binarySearch(colIndices, start, end, target) {
+	let lo = start;
+	let hi = end;
+	while (lo < hi) {
+		const mid = lo + Math.floor((hi - lo) / 2);
+		const midVal = colIndices[mid] ?? 0;
+		if (midVal === target) return true;
+		else if (midVal < target) lo = mid + 1;
+		else hi = mid;
+	}
+	return false;
+}
+/**
+* Compute intersection stats for a single pair of nodes in CSR format.
+*
+* Neighbours must be sorted (CSR guarantees this from graphToCSR).
+*
+* @param rowOffsets - CSR row offset array
+* @param colIndices - CSR column indices array
+* @param u - First node index
+* @param v - Second node index
+* @returns Intersection result with sizes
+*/
+function intersectionPair(rowOffsets, colIndices, u, v) {
+	const uStart = rowOffsets[u] ?? 0;
+	const uEnd = rowOffsets[u + 1] ?? 0;
+	const vStart = rowOffsets[v] ?? 0;
+	const vEnd = rowOffsets[v + 1] ?? 0;
+	const sizeU = uEnd - uStart;
+	const sizeV = vEnd - vStart;
+	if (sizeU === 0 || sizeV === 0) return {
+		intersection: 0,
+		sizeU,
+		sizeV
+	};
+	let intersection = 0;
+	if (sizeU <= sizeV) {
+		for (let i = uStart; i < uEnd; i++) if (binarySearch(colIndices, vStart, vEnd, colIndices[i] ?? 0)) intersection++;
+	} else for (let i = vStart; i < vEnd; i++) if (binarySearch(colIndices, uStart, uEnd, colIndices[i] ?? 0)) intersection++;
+	return {
+		intersection,
+		sizeU,
+		sizeV
+	};
+}
+/**
+* Batch intersection stats for multiple node pairs.
+*
+* @param rowOffsets - CSR row offset array
+* @param colIndices - CSR column indices array
+* @param pairs - Array of [u, v] node index pairs
+* @returns Object with parallel arrays: intersections, sizeUs, sizeVs
+*/
+function intersectionBatch(rowOffsets, colIndices, pairs) {
+	const n = pairs.length;
+	const intersections = new Uint32Array(n);
+	const sizeUs = new Uint32Array(n);
+	const sizeVs = new Uint32Array(n);
+	for (let i = 0; i < n; i++) {
+		const pair = pairs[i];
+		if (pair !== void 0) {
+			const [u, v] = pair;
+			const result = intersectionPair(rowOffsets, colIndices, u, v);
+			intersections[i] = result.intersection;
+			sizeUs[i] = result.sizeU;
+			sizeVs[i] = result.sizeV;
+		}
+	}
+	return {
+		intersections,
+		sizeUs,
+		sizeVs
+	};
+}
+/**
+* Compute Jaccard from intersection stats.
+* J = intersection / (sizeU + sizeV - intersection)
+*/
+function jaccardFromIntersection(result) {
+	const union = result.sizeU + result.sizeV - result.intersection;
+	return union === 0 ? 0 : result.intersection / union;
+}
+/**
+* Compute Cosine similarity from intersection stats.
+* Cosine = intersection / sqrt(sizeU * sizeV)
+*/
+function cosineFromIntersection(result) {
+	const denominator = Math.sqrt(result.sizeU * result.sizeV);
+	return denominator === 0 ? 0 : result.intersection / denominator;
+}
+/**
+* Compute Sorensen-Dice from intersection stats.
+* SD = 2 * intersection / (sizeU + sizeV)
+*/
+function sorensenDiceFromIntersection(result) {
+	const denominator = result.sizeU + result.sizeV;
+	return denominator === 0 ? 0 : 2 * result.intersection / denominator;
+}
+/**
+* Compute Overlap coefficient from intersection stats.
+* Overlap = intersection / min(sizeU, sizeV)
+*/
+function overlapFromIntersection(result) {
+	const minSize = Math.min(result.sizeU, result.sizeV);
+	return minSize === 0 ? 0 : result.intersection / minSize;
+}
+/**
+* Compute Hub Promoted from intersection stats.
+* HP = intersection / min(sizeU, sizeV)
+* Note: Same formula as Overlap coefficient
+*/
+function hubPromotedFromIntersection(result) {
+	return overlapFromIntersection(result);
+}
+//#endregion
+Object.defineProperty(exports, "cosineFromIntersection", {
+	enumerable: true,
+	get: function() {
+		return cosineFromIntersection;
+	}
+});
+Object.defineProperty(exports, "csrToTypedBuffers", {
+	enumerable: true,
+	get: function() {
+		return csrToTypedBuffers;
+	}
+});
+Object.defineProperty(exports, "graphToCSR", {
+	enumerable: true,
+	get: function() {
+		return graphToCSR;
+	}
+});
+Object.defineProperty(exports, "hubPromotedFromIntersection", {
+	enumerable: true,
+	get: function() {
+		return hubPromotedFromIntersection;
+	}
+});
+Object.defineProperty(exports, "intersectionBatch", {
+	enumerable: true,
+	get: function() {
+		return intersectionBatch;
+	}
+});
+Object.defineProperty(exports, "jaccardFromIntersection", {
+	enumerable: true,
+	get: function() {
+		return jaccardFromIntersection;
+	}
+});
+Object.defineProperty(exports, "overlapFromIntersection", {
+	enumerable: true,
+	get: function() {
+		return overlapFromIntersection;
+	}
+});
+Object.defineProperty(exports, "sorensenDiceFromIntersection", {
+	enumerable: true,
+	get: function() {
+		return sorensenDiceFromIntersection;
+	}
+});
+
+//# sourceMappingURL=logic-Dbyfb_-7.cjs.map

package/dist/logic-Dbyfb_-7.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"logic-Dbyfb_-7.cjs","names":[],"sources":["../src/gpu/csr.ts","../src/gpu/kernels/intersection/logic.ts"],"sourcesContent":["/**\n * Compressed Sparse Row (CSR) matrix representation for GPU computation.\n *\n * CSR format is memory-efficient for sparse graphs and maps well to\n * GPU parallel operations. The format stores adjacency information\n * in three arrays: row offsets, column indices, and optional values.\n */\n\nimport { d, type StorageFlag, type TgpuBuffer } from \"typegpu\";\nimport type { NodeId, Direction, NodeData, EdgeData } from \"../graph/types\";\nimport type { ReadableGraph } from \"../graph\";\nimport type { GraphwiseGPURoot } from \"./root\";\n\n/**\n * CSR matrix representation of a graph adjacency structure.\n *\n * The rowOffsets array has length nodeCount + 1, where rowOffsets[i]\n * gives the start index in colIndices for node i's neighbours.\n * The neighbours of node i are colIndices[rowOffsets[i] : rowOffsets[i+1]].\n */\nexport interface CSRMatrix {\n\t/** Row offsets array (length: nodeCount + 1) */\n\treadonly rowOffsets: Uint32Array;\n\t/** Column indices array (length: edgeCount for directed, 2*edgeCount for undirected) */\n\treadonly colIndices: Uint32Array;\n\t/** Optional edge weights aligned with colIndices */\n\treadonly values?: Float32Array;\n\t/** Number of nodes in the graph */\n\treadonly nodeCount: number;\n\t/** Number of directed edges (undirected edges counted once) */\n\treadonly edgeCount: number;\n}\n\n/**\n * Mapping from node IDs to CSR indices.\n *\n * Required because CSR uses dense integer indices while graphs\n * may use arbitrary string identifiers.\n */\nexport interface CSRIndexMap {\n\t/** Map from NodeId to CSR row index */\n\treadonly nodeToIndex: ReadonlyMap<NodeId, number>;\n\t/** Map from CSR row index to NodeId */\n\treadonly indexToNode: readonly NodeId[];\n}\n\n/**\n * Combined CSR matrix with index mapping.\n */\nexport interface CSRGraph {\n\treadonly csr: CSRMatrix;\n\treadonly indexMap: CSRIndexMap;\n}\n\n/**\n * Group of TypeGPU typed buffers holding a CSR matrix.\n *\n * Uses TypeGPU's typed buffer API for type-safe GPU computation.\n * Buffers are created with storage usage for compute operations.\n */\nexport interface TypedBufferGroup {\n\t/** Buffer containing rowOffsets data (u32 array) */\n\treadonly rowOffsets: TgpuBuffer<ReturnType<typeof d.arrayOf<typeof d.u32>>> &\n\t\tStorageFlag;\n\t/** Buffer containing colIndices data (u32 array) */\n\treadonly colIndices: TgpuBuffer<ReturnType<typeof d.arrayOf<typeof d.u32>>> &\n\t\tStorageFlag;\n\t/** Buffer containing values data (f32 array, optional) */\n\treadonly values?: TgpuBuffer<ReturnType<typeof d.arrayOf<typeof d.f32>>> &\n\t\tStorageFlag;\n\t/** Number of nodes */\n\treadonly nodeCount: number;\n\t/** Number of edges */\n\treadonly edgeCount: number;\n}\n\n/**\n * Convert a ReadableGraph to CSR format.\n *\n * For undirected graphs, each edge is stored twice (once in each direction).\n * For directed graphs, edges are stored in the out-direction by default.\n *\n * @param graph - The graph to convert\n * @param direction - Edge direction to include (default: 'out' for directed, 'both' for undirected)\n * @returns CSR representation with index mapping\n */\nexport function graphToCSR<N extends NodeData, E extends EdgeData>(\n\tgraph: ReadableGraph<N, E>,\n\tdirection: Direction = graph.directed ? \"out\" : \"both\",\n): CSRGraph {\n\t// Build node index mapping\n\tconst nodeToIndex = new Map<NodeId, number>();\n\tconst indexToNode: NodeId[] = [];\n\n\tfor (const nodeId of graph.nodeIds()) {\n\t\tconst index = indexToNode.length;\n\t\tnodeToIndex.set(nodeId, index);\n\t\tindexToNode.push(nodeId);\n\t}\n\n\tconst nodeCount = indexToNode.length;\n\n\t// Count edges per node to build row offsets\n\tconst degrees = new Uint32Array(nodeCount);\n\n\tfor (const nodeId of graph.nodeIds()) {\n\t\tconst srcIndex = nodeToIndex.get(nodeId);\n\t\tif (srcIndex === undefined) continue;\n\t\tdegrees[srcIndex] = graph.degree(nodeId, direction);\n\t}\n\n\t// Calculate total edge count\n\tlet totalEdges = 0;\n\tfor (let i = 0; i < nodeCount; i++) {\n\t\ttotalEdges += degrees[i] ?? 0;\n\t}\n\n\t// Build rowOffsets array\n\tconst rowOffsets = new Uint32Array(nodeCount + 1);\n\tfor (let i = 0; i < nodeCount; i++) {\n\t\trowOffsets[i + 1] = (rowOffsets[i] ?? 0) + (degrees[i] ?? 0);\n\t}\n\n\t// Build colIndices and values arrays\n\tconst colIndices = new Uint32Array(totalEdges);\n\tconst values = new Float32Array(totalEdges);\n\n\tfor (const nodeId of graph.nodeIds()) {\n\t\tconst srcIndex = nodeToIndex.get(nodeId);\n\t\tif (srcIndex === undefined) continue;\n\n\t\tconst baseOffset = rowOffsets[srcIndex] ?? 0;\n\t\tlet localOffset = 0;\n\n\t\tfor (const neighbourId of graph.neighbours(nodeId, direction)) {\n\t\t\tconst dstIndex = nodeToIndex.get(neighbourId);\n\t\t\tif (dstIndex === undefined) continue;\n\n\t\t\tconst edgeIdx = baseOffset + localOffset;\n\t\t\tcolIndices[edgeIdx] = dstIndex;\n\n\t\t\t// Get edge weight if available\n\t\t\tconst edge = graph.getEdge(nodeId, neighbourId);\n\t\t\tvalues[edgeIdx] = edge?.weight ?? 1.0;\n\n\t\t\tlocalOffset++;\n\t\t}\n\t}\n\n\tconst csr: CSRMatrix = {\n\t\trowOffsets,\n\t\tcolIndices,\n\t\tvalues,\n\t\tnodeCount,\n\t\tedgeCount: graph.directed ? graph.edgeCount : graph.edgeCount * 2,\n\t};\n\n\tconst indexMap: CSRIndexMap = {\n\t\tnodeToIndex,\n\t\tindexToNode,\n\t};\n\n\treturn { csr, indexMap };\n}\n\n/**\n * Create TypeGPU typed buffers from a CSR matrix.\n *\n * Uses TypeGPU's typed buffer API for type-safe GPU computation.\n * Buffers are created with storage usage for compute operations.\n *\n * @param root - TypeGPU root instance\n * @param csr - CSR matrix to upload\n * @returns Typed buffer group\n *\n * @example\n * ```typescript\n * import { initGPU, csrToTypedBuffers, graphToCSR } from \"graphwise/gpu\";\n *\n * const root = await initGPU();\n * const { csr } = graphToCSR(graph);\n * const buffers = csrToTypedBuffers(root, csr);\n *\n * // Read data back to CPU\n * const rowOffsets = await buffers.rowOffsets.read();\n * console.log(rowOffsets); // Uint32Array\n * ```\n */\nexport function csrToTypedBuffers(\n\troot: GraphwiseGPURoot,\n\tcsr: CSRMatrix,\n): TypedBufferGroup {\n\t// Convert typed arrays to regular arrays for TypeGPU\n\tconst rowOffsetsArray = Array.from(csr.rowOffsets);\n\tconst colIndicesArray = Array.from(csr.colIndices);\n\n\t// Row offsets buffer (u32 array)\n\tconst rowOffsetsBuffer = root\n\t\t.createBuffer(d.arrayOf(d.u32, csr.rowOffsets.length), rowOffsetsArray)\n\t\t.$usage(\"storage\");\n\n\t// Column indices buffer (u32 array)\n\tconst colIndicesBuffer = root\n\t\t.createBuffer(d.arrayOf(d.u32, csr.colIndices.length), colIndicesArray)\n\t\t.$usage(\"storage\");\n\n\t// Values buffer (f32 array, optional)\n\tif (csr.values !== undefined) {\n\t\tconst valuesArray = Array.from(csr.values);\n\t\tconst valuesBuffer = root\n\t\t\t.createBuffer(d.arrayOf(d.f32, csr.values.length), valuesArray)\n\t\t\t.$usage(\"storage\");\n\n\t\treturn {\n\t\t\trowOffsets: rowOffsetsBuffer,\n\t\t\tcolIndices: colIndicesBuffer,\n\t\t\tvalues: valuesBuffer,\n\t\t\tnodeCount: csr.nodeCount,\n\t\t\tedgeCount: csr.edgeCount,\n\t\t};\n\t}\n\n\treturn {\n\t\trowOffsets: rowOffsetsBuffer,\n\t\tcolIndices: colIndicesBuffer,\n\t\tnodeCount: csr.nodeCount,\n\t\tedgeCount: csr.edgeCount,\n\t};\n}\n","/**\n * Pure CPU implementation of batch neighbourhood intersection.\n *\n * Computes intersection size and neighbourhood sizes for multiple node pairs.\n * This is the foundation for ALL Jaccard-family MI variants:\n *   J(A,B) = |A ∩ B| / |A ∪ B| = intersection / (sizeA + sizeB - intersection)\n *   Cosine(A,B) = |A ∩ B| / sqrt(|A| * |B|)\n *   Sorensen-Dice(A,B) = 2|A ∩ B| / (|A| + |B|)\n *   Overlap(A,B) = |A ∩ B| / min(|A|, |B|)\n *\n * Uses binary search optimisation: iterate smaller neighbourhood, search in larger.\n *\n * @module gpu/kernels/intersection/logic\n */\n\n/**\n * Result of computing intersection for a single pair.\n */\nexport interface IntersectionResult {\n\t/** Size of the intersection |N(u) ∩ N(v)| */\n\treadonly intersection: number;\n\t/** Size of first neighbourhood |N(u)| */\n\treadonly sizeU: number;\n\t/** Size of second neighbourhood |N(v)| */\n\treadonly sizeV: number;\n}\n\n/**\n * Binary search in a sorted subarray of colIndices.\n *\n * @param colIndices - CSR column indices array (must be sorted per row)\n * @param start - Start index (inclusive)\n * @param end - End index (exclusive)\n * @param target - Value to search for\n * @returns true if target is found between colIndices[start] and colIndices[end-1]\n */\nexport function binarySearch(\n\tcolIndices: Uint32Array,\n\tstart: number,\n\tend: number,\n\ttarget: number,\n): boolean {\n\tlet lo = start;\n\tlet hi = end;\n\n\twhile (lo < hi) {\n\t\tconst mid = lo + Math.floor((hi - lo) / 2);\n\t\tconst midVal = colIndices[mid] ?? 0;\n\n\t\tif (midVal === target) {\n\t\t\treturn true;\n\t\t} else if (midVal < target) {\n\t\t\tlo = mid + 1;\n\t\t} else {\n\t\t\thi = mid;\n\t\t}\n\t}\n\n\treturn false;\n}\n\n/**\n * Compute intersection stats for a single pair of nodes in CSR format.\n *\n * Neighbours must be sorted (CSR guarantees this from graphToCSR).\n *\n * @param rowOffsets - CSR row offset array\n * @param colIndices - CSR column indices array\n * @param u - First node index\n * @param v - Second node index\n * @returns Intersection result with sizes\n */\nexport function intersectionPair(\n\trowOffsets: Uint32Array,\n\tcolIndices: Uint32Array,\n\tu: number,\n\tv: number,\n): IntersectionResult {\n\tconst uStart = rowOffsets[u] ?? 0;\n\tconst uEnd = rowOffsets[u + 1] ?? 0;\n\tconst vStart = rowOffsets[v] ?? 0;\n\tconst vEnd = rowOffsets[v + 1] ?? 0;\n\n\tconst sizeU = uEnd - uStart;\n\tconst sizeV = vEnd - vStart;\n\n\t// Empty neighbourhoods → intersection = 0\n\tif (sizeU === 0 || sizeV === 0) {\n\t\treturn { intersection: 0, sizeU, sizeV };\n\t}\n\n\t// Count intersection by iterating smaller neighbourhood, binary searching in larger\n\tlet intersection = 0;\n\n\tif (sizeU <= sizeV) {\n\t\t// Iterate u's neighbours, search in v's\n\t\tfor (let i = uStart; i < uEnd; i++) {\n\t\t\tconst neighbour = colIndices[i] ?? 0;\n\t\t\tif (binarySearch(colIndices, vStart, vEnd, neighbour)) {\n\t\t\t\tintersection++;\n\t\t\t}\n\t\t}\n\t} else {\n\t\t// Iterate v's neighbours, search in u's\n\t\tfor (let i = vStart; i < vEnd; i++) {\n\t\t\tconst neighbour = colIndices[i] ?? 0;\n\t\t\tif (binarySearch(colIndices, uStart, uEnd, neighbour)) {\n\t\t\t\tintersection++;\n\t\t\t}\n\t\t}\n\t}\n\n\treturn { intersection, sizeU, sizeV };\n}\n\n/**\n * Batch intersection stats for multiple node pairs.\n *\n * @param rowOffsets - CSR row offset array\n * @param colIndices - CSR column indices array\n * @param pairs - Array of [u, v] node index pairs\n * @returns Object with parallel arrays: intersections, sizeUs, sizeVs\n */\nexport function intersectionBatch(\n\trowOffsets: Uint32Array,\n\tcolIndices: Uint32Array,\n\tpairs: readonly (readonly [number, number])[],\n): {\n\tintersections: Uint32Array;\n\tsizeUs: Uint32Array;\n\tsizeVs: Uint32Array;\n} {\n\tconst n = pairs.length;\n\tconst intersections = new Uint32Array(n);\n\tconst sizeUs = new Uint32Array(n);\n\tconst sizeVs = new Uint32Array(n);\n\n\tfor (let i = 0; i < n; i++) {\n\t\tconst pair = pairs[i];\n\t\tif (pair !== undefined) {\n\t\t\tconst [u, v] = pair;\n\t\t\tconst result = intersectionPair(rowOffsets, colIndices, u, v);\n\t\t\tintersections[i] = result.intersection;\n\t\t\tsizeUs[i] = result.sizeU;\n\t\t\tsizeVs[i] = result.sizeV;\n\t\t}\n\t}\n\n\treturn { intersections, sizeUs, sizeVs };\n}\n\n/**\n * Compute Jaccard from intersection stats.\n * J = intersection / (sizeU + sizeV - intersection)\n */\nexport function jaccardFromIntersection(result: IntersectionResult): number {\n\tconst union = result.sizeU + result.sizeV - result.intersection;\n\treturn union === 0 ? 0 : result.intersection / union;\n}\n\n/**\n * Compute Cosine similarity from intersection stats.\n * Cosine = intersection / sqrt(sizeU * sizeV)\n */\nexport function cosineFromIntersection(result: IntersectionResult): number {\n\tconst denominator = Math.sqrt(result.sizeU * result.sizeV);\n\treturn denominator === 0 ? 0 : result.intersection / denominator;\n}\n\n/**\n * Compute Sorensen-Dice from intersection stats.\n * SD = 2 * intersection / (sizeU + sizeV)\n */\nexport function sorensenDiceFromIntersection(\n\tresult: IntersectionResult,\n): number {\n\tconst denominator = result.sizeU + result.sizeV;\n\treturn denominator === 0 ? 0 : (2 * result.intersection) / denominator;\n}\n\n/**\n * Compute Overlap coefficient from intersection stats.\n * Overlap = intersection / min(sizeU, sizeV)\n */\nexport function overlapFromIntersection(result: IntersectionResult): number {\n\tconst minSize = Math.min(result.sizeU, result.sizeV);\n\treturn minSize === 0 ? 0 : result.intersection / minSize;\n}\n\n/**\n * Compute Hub Promoted from intersection stats.\n * HP = intersection / min(sizeU, sizeV)\n * Note: Same formula as Overlap coefficient\n */\nexport function hubPromotedFromIntersection(\n\tresult: IntersectionResult,\n): number {\n\treturn overlapFromIntersection(result);\n}\n"],"mappings":"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"}