@cloudglides/nox 1.1.6 → 3.0.0

package/src/utils/bits.js

@@ -1,25 +1,150 @@
 export const rotateBits = (val, shift) => {
-  const mask = BigInt(64);
-  shift = BigInt(shift) % mask;
-  return (val << shift) | (val >> (mask - shift));
-};
+   if (typeof val !== 'bigint') {
+     throw new TypeError('val must be bigint');
+   }
+   if (typeof shift !== 'number' && typeof shift !== 'bigint') {
+     throw new TypeError('shift must be number or bigint');
+   }
+   const mask = BigInt(64);
+   shift = BigInt(shift) % mask;
+   return (val << shift) | (val >> (mask - shift));
+ };
+ 
+ export const extractBits = (val, start, length) => {
+   if (typeof val !== 'bigint') {
+     throw new TypeError('val must be bigint');
+   }
+   if (typeof start !== 'number' || !Number.isInteger(start)) {
+     throw new TypeError('start must be an integer');
+   }
+   if (start < 0) {
+     throw new RangeError('start must be non-negative');
+   }
+   if (typeof length !== 'number' || !Number.isInteger(length)) {
+     throw new TypeError('length must be an integer');
+   }
+   if (length <= 0) {
+     throw new RangeError('length must be positive');
+   }
+   const mask = (BigInt(1) << BigInt(length)) - BigInt(1);
+   return (val >> BigInt(start)) & mask;
+ };
+ 
+ export const hammingWeight = (val) => {
+   if (typeof val !== 'bigint') {
+     throw new TypeError('val must be bigint');
+   }
+   let count = 0;
+   let v = val < 0n ? -val : val;
+   while (v > 0n) {
+     v = v & (v - 1n);
+     count++;
+   }
+   return count;
+ };
+ 
+ export const bitRange = (val, min, max) => {
+   if (typeof val !== 'bigint') {
+     throw new TypeError('val must be bigint');
+   }
+   if (typeof min !== 'number' || !Number.isInteger(min)) {
+     throw new TypeError('min must be an integer');
+   }
+   if (min < 0) {
+     throw new RangeError('min must be non-negative');
+   }
+   if (typeof max !== 'number' || !Number.isInteger(max)) {
+     throw new TypeError('max must be an integer');
+   }
+   if (max <= min) {
+     throw new RangeError('max must be greater than min');
+   }
+   const shift = BigInt(min);
+   const mask = (BigInt(1) << BigInt(max - min)) - BigInt(1);
+   return (val >> shift) & mask;
+ };
 
-export const extractBits = (val, start, length) => {
-  const mask = (BigInt(1) << BigInt(length)) - BigInt(1);
-  return (val >> BigInt(start)) & mask;
-};
+ export const popcountNum = (val) => {
+ if (typeof val !== 'number' || !Number.isInteger(val) || val < 0) {
+   throw new TypeError('val must be a non-negative integer');
+ }
+ let count = 0;
+ let v = val >>> 0;
+ while (v) {
+   count += v & 1;
+   v >>>= 1;
+ }
+ return count;
+ };
 
-export const hammingWeight = (val) => {
-  let count = 0;
-  while (val > 0n) {
-    count += val & 1n ? 1 : 0;
-    val >>= 1n;
-  }
-  return count;
-};
+ export const clz = (val) => {
+ if (typeof val !== 'bigint') {
+   throw new TypeError('val must be bigint');
+ }
+ if (val === 0n) return 64;
+ let count = 0;
+ let mask = 1n << 63n;
+ while ((val & mask) === 0n) {
+   count++;
+   mask >>= 1n;
+ }
+ return count;
+ };
 
-export const bitRange = (val, min, max) => {
-  const shift = BigInt(min);
-  const mask = (BigInt(1) << BigInt(max - min)) - BigInt(1);
-  return (val >> shift) & mask;
-};
+ export const ctz = (val) => {
+ if (typeof val !== 'bigint') {
+   throw new TypeError('val must be bigint');
+ }
+ if (val === 0n) return 64;
+ let count = 0;
+ let mask = 1n;
+ while ((val & mask) === 0n) {
+   count++;
+   mask <<= 1n;
+ }
+ return count;
+ };
+
+ export const reverseBits = (val, width = 64) => {
+ if (typeof val !== 'bigint') {
+   throw new TypeError('val must be bigint');
+ }
+ if (typeof width !== 'number' || !Number.isInteger(width) || width <= 0) {
+   throw new TypeError('width must be a positive integer');
+ }
+ let result = 0n;
+ for (let i = 0; i < width; i++) {
+   result = (result << 1n) | ((val >> BigInt(i)) & 1n);
+ }
+ return result;
+ };
+
+ export const setBit = (val, pos) => {
+ if (typeof val !== 'bigint') {
+   throw new TypeError('val must be bigint');
+ }
+ if (typeof pos !== 'number' || !Number.isInteger(pos) || pos < 0) {
+   throw new TypeError('pos must be a non-negative integer');
+ }
+ return val | (1n << BigInt(pos));
+ };
+
+ export const clearBit = (val, pos) => {
+ if (typeof val !== 'bigint') {
+   throw new TypeError('val must be bigint');
+ }
+ if (typeof pos !== 'number' || !Number.isInteger(pos) || pos < 0) {
+   throw new TypeError('pos must be a non-negative integer');
+ }
+ return val & ~(1n << BigInt(pos));
+ };
+
+ export const toggleBit = (val, pos) => {
+ if (typeof val !== 'bigint') {
+   throw new TypeError('val must be bigint');
+ }
+ if (typeof pos !== 'number' || !Number.isInteger(pos) || pos < 0) {
+   throw new TypeError('pos must be a non-negative integer');
+ }
+ return val ^ (1n << BigInt(pos));
+ };

package/src/utils/categorical.js

@@ -1,12 +1,21 @@
 export const categorical = (rng, categories, probabilities) => {
-  if (!categories || !probabilities) throw new Error('Categories and probabilities required');
-  if (categories.length === 0) throw new Error('Categories cannot be empty');
-  if (probabilities.length !== categories.length) {
-    throw new Error('Probabilities and categories must have same length');
-  }
+    if (!rng || typeof rng.nextFloat !== 'function') {
+      throw new TypeError('First argument must be RNG instance');
+    }
+    if (!Array.isArray(categories) || !Array.isArray(probabilities)) {
+      throw new TypeError('Categories and probabilities must be arrays');
+    }
+    if (categories.length === 0) {
+      throw new RangeError('Categories cannot be empty');
+    }
+    if (probabilities.length !== categories.length) {
+      throw new RangeError('Probabilities and categories must have same length');
+    }
 
-  const total = probabilities.reduce((a, b) => a + b, 0);
-  if (total <= 0) throw new Error('Probabilities must sum to positive value');
+    const total = probabilities.reduce((a, b) => a + b, 0);
+    if (total <= 0) {
+      throw new RangeError('Probabilities must sum to positive value');
+    }
   
   const normalized = probabilities.map(p => p / total);
 
@@ -24,34 +33,62 @@ export const categorical = (rng, categories, probabilities) => {
 };
 
 export const multinomial = (rng, n, categories, probabilities) => {
-  const result = {};
-  for (const cat of categories) {
-    result[cat] = 0;
-  }
+    if (!rng || typeof rng.nextFloat !== 'function') {
+      throw new TypeError('First argument must be RNG instance');
+    }
+    if (typeof n !== 'number' || !Number.isInteger(n)) {
+      throw new TypeError('n must be an integer');
+    }
+    if (n <= 0) {
+      throw new RangeError('n must be positive');
+    }
+    if (!Array.isArray(categories) || categories.length === 0) {
+      throw new RangeError('categories must be a non-empty array');
+    }
+    if (!Array.isArray(probabilities) || probabilities.length === 0) {
+      throw new RangeError('probabilities must be a non-empty array');
+    }
+    if (probabilities.length !== categories.length) {
+      throw new RangeError('probabilities and categories must have same length');
+    }
+   const result = {};
+   for (const cat of categories) {
+     result[cat] = 0;
+   }
 
-  for (let i = 0; i < n; i++) {
-    const pick = categorical(rng, categories, probabilities);
-    result[pick]++;
-  }
+   for (let i = 0; i < n; i++) {
+     const pick = categorical(rng, categories, probabilities);
+     result[pick]++;
+   }
 
-  return result;
-};
+   return result;
+ };
 
 export const categorical2D = (rng, matrix) => {
-  const rows = matrix.length;
-  const cols = matrix[0].length;
-
-  const total = matrix.flat().reduce((a, b) => a + b, 0);
-  let rand = rng.nextFloat() * total;
+    if (!rng || typeof rng.nextFloat !== 'function') {
+      throw new TypeError('First argument must be RNG instance');
+    }
+    if (!Array.isArray(matrix) || matrix.length === 0) {
+      throw new RangeError('matrix must be non-empty array');
+    }
+    const rows = matrix.length;
+    const cols = matrix[0].length;
 
-  for (let i = 0; i < rows; i++) {
-    for (let j = 0; j < cols; j++) {
-      rand -= matrix[i][j];
-      if (rand <= 0) {
-        return [i, j];
-      }
+    const flat = matrix.flat();
+    const total = flat.reduce((a, b) => a + b, 0);
+    if (total <= 0) {
+      throw new RangeError('Matrix values must sum to positive');
     }
-  }
+   
+   let cumsum = 0;
+   const rand = rng.nextFloat() * total;
 
-  return [rows - 1, cols - 1];
-};
+   for (let idx = 0; idx < flat.length; idx++) {
+     cumsum += flat[idx];
+     if (rand < cumsum) {
+       return [Math.floor(idx / cols), idx % cols];
+     }
+   }
+
+   return [rows - 1, cols - 1];
+ };

package/src/utils/clustering.js

@@ -0,0 +1,143 @@
+export class KMeans {
+  constructor(k, maxIter = 100, tol = 1e-6) {
+    if (typeof k !== 'number' || k < 1) {
+      throw new RangeError('k must be positive integer');
+    }
+    if (typeof maxIter !== 'number' || maxIter < 1) {
+      throw new RangeError('maxIter must be positive integer');
+    }
+
+    this.k = k;
+    this.maxIter = maxIter;
+    this.tol = tol;
+    this.centroids = null;
+    this.labels = null;
+    this.inertia = null;
+  }
+
+  fit(X) {
+    if (!Array.isArray(X) || X.length === 0) {
+      throw new TypeError('X must be non-empty array');
+    }
+    if (!Array.isArray(X[0]) || X[0].length === 0) {
+      throw new TypeError('X must be array of numeric arrays');
+    }
+
+    const n = X.length;
+    const d = X[0].length;
+
+    if (this.k > n) {
+      throw new RangeError('k cannot exceed number of samples');
+    }
+
+    this.centroids = this._initializeCentroids(X);
+    let prevInertia = Infinity;
+
+    for (let iter = 0; iter < this.maxIter; iter++) {
+      this.labels = this._assignClusters(X);
+      const newCentroids = this._updateCentroids(X);
+      
+      this.inertia = this._calculateInertia(X);
+
+      if (Math.abs(prevInertia - this.inertia) < this.tol) {
+        break;
+      }
+
+      prevInertia = this.inertia;
+      this.centroids = newCentroids;
+    }
+
+    return this;
+  }
+
+  predict(X) {
+    if (this.centroids === null) {
+      throw new Error('Model not fitted. Call fit() first.');
+    }
+    if (!Array.isArray(X) || X.length === 0) {
+      throw new TypeError('X must be non-empty array');
+    }
+
+    return this._assignClusters(X);
+  }
+
+  _initializeCentroids(X) {
+    const indices = new Set();
+    while (indices.size < this.k) {
+      indices.add(Math.floor(Math.random() * X.length));
+    }
+
+    return Array.from(indices).map(i => [...X[i]]);
+  }
+
+  _assignClusters(X) {
+    const labels = new Array(X.length);
+
+    for (let i = 0; i < X.length; i++) {
+      let minDist = Infinity;
+      let bestCluster = 0;
+
+      for (let j = 0; j < this.k; j++) {
+        const dist = this._euclideanDistance(X[i], this.centroids[j]);
+        if (dist < minDist) {
+          minDist = dist;
+          bestCluster = j;
+        }
+      }
+
+      labels[i] = bestCluster;
+    }
+
+    return labels;
+  }
+
+  _updateCentroids(X) {
+    const newCentroids = [];
+    const d = X[0].length;
+
+    for (let j = 0; j < this.k; j++) {
+      const clusterPoints = [];
+
+      for (let i = 0; i < X.length; i++) {
+        if (this.labels[i] === j) {
+          clusterPoints.push(X[i]);
+        }
+      }
+
+      if (clusterPoints.length === 0) {
+        newCentroids.push([...this.centroids[j]]);
+      } else {
+        const centroid = new Array(d).fill(0);
+        for (let dim = 0; dim < d; dim++) {
+          let sum = 0;
+          for (let point of clusterPoints) {
+            sum += point[dim];
+          }
+          centroid[dim] = sum / clusterPoints.length;
+        }
+        newCentroids.push(centroid);
+      }
+    }
+
+    return newCentroids;
+  }
+
+  _euclideanDistance(a, b) {
+    let sum = 0;
+    for (let i = 0; i < a.length; i++) {
+      sum += (a[i] - b[i]) ** 2;
+    }
+    return Math.sqrt(sum);
+  }
+
+  _calculateInertia(X) {
+    let inertia = 0;
+
+    for (let i = 0; i < X.length; i++) {
+      const dist = this._euclideanDistance(X[i], this.centroids[this.labels[i]]);
+      inertia += dist * dist;
+    }
+
+    return inertia;
+  }
+}

package/src/utils/combinatorics.js

@@ -1,85 +1,129 @@
 export const combinations = (arr, k) => {
-  if (k > arr.length) return [];
-  if (k === 1) return arr.map(x => [x]);
-  if (k === arr.length) return [arr];
+   if (!Array.isArray(arr)) {
+     throw new TypeError('arr must be an array');
+   }
+   if (typeof k !== 'number' || !Number.isInteger(k)) {
+     throw new TypeError('k must be an integer');
+   }
+   if (k <= 0) {
+     throw new RangeError('k must be positive');
+   }
+   if (k > arr.length) {
+     throw new RangeError('k cannot exceed array length');
+   }
 
-  const result = [];
-  const combine = (start, current) => {
-    if (current.length === k) {
-      result.push([...current]);
-      return;
-    }
-    for (let i = start; i < arr.length; i++) {
-      current.push(arr[i]);
-      combine(i + 1, current);
-      current.pop();
-    }
-  };
+   if (k === 1) return arr.map(x => [x]);
+   if (k === arr.length) return [arr];
+
+   const result = [];
+   const combine = (start, current) => {
+     if (current.length === k) {
+       result.push([...current]);
+       return;
+     }
+     for (let i = start; i < arr.length; i++) {
+       current.push(arr[i]);
+       combine(i + 1, current);
+       current.pop();
+     }
+   };
 
-  combine(0, []);
-  return result;
-};
+   combine(0, []);
+   return result;
+ };
 
 export const permutations = (arr) => {
-  if (arr.length <= 1) return [arr];
+   if (!Array.isArray(arr)) {
+     throw new TypeError('arr must be an array');
+   }
+   if (arr.length <= 1) return [arr];
 
-  const result = [];
-  const permute = (arr, start) => {
-    if (start === arr.length - 1) {
-      result.push([...arr]);
-      return;
-    }
-    for (let i = start; i < arr.length; i++) {
-      [arr[start], arr[i]] = [arr[i], arr[start]];
-      permute(arr, start + 1);
-      [arr[start], arr[i]] = [arr[i], arr[start]];
-    }
-  };
+   const result = [];
+   const permute = (arr, start) => {
+     if (start === arr.length - 1) {
+       result.push([...arr]);
+       return;
+     }
+     for (let i = start; i < arr.length; i++) {
+       [arr[start], arr[i]] = [arr[i], arr[start]];
+       permute(arr, start + 1);
+       [arr[start], arr[i]] = [arr[i], arr[start]];
+     }
+   };
 
-  permute([...arr], 0);
-  return result;
-};
+   permute([...arr], 0);
+   return result;
+ };
 
 export const kPermutations = (arr, k) => {
-  if (k > arr.length) return [];
-  if (k === 1) return arr.map(x => [x]);
+   if (!Array.isArray(arr)) {
+     throw new TypeError('arr must be an array');
+   }
+   if (typeof k !== 'number' || !Number.isInteger(k)) {
+     throw new TypeError('k must be an integer');
+   }
+   if (k <= 0) {
+     throw new RangeError('k must be positive');
+   }
+   if (k > arr.length) {
+     throw new RangeError('k cannot exceed array length');
+   }
+   if (k === 1) return arr.map(x => [x]);
 
-  const result = [];
-  const perm = (available, current) => {
-    if (current.length === k) {
-      result.push([...current]);
-      return;
-    }
-    for (let i = 0; i < available.length; i++) {
-      const item = available[i];
-      const remaining = available.slice(0, i).concat(available.slice(i + 1));
-      perm(remaining, [...current, item]);
-    }
-  };
+   const result = [];
+   const perm = (available, current) => {
+     if (current.length === k) {
+       result.push([...current]);
+       return;
+     }
+     for (let i = 0; i < available.length; i++) {
+       const item = available[i];
+       const remaining = available.slice(0, i).concat(available.slice(i + 1));
+       perm(remaining, [...current, item]);
+     }
+   };
 
-  perm(arr, []);
-  return result;
-};
+   perm(arr, []);
+   return result;
+ };
 
 export const randomCombination = (arr, k, rng) => {
-  const indices = [];
-  const n = arr.length;
-  
-  while (indices.length < k) {
-    const idx = rng.nextInt(n);
-    if (!indices.includes(idx)) {
-      indices.push(idx);
+    if (!Array.isArray(arr)) {
+      throw new TypeError('arr must be an array');
+    }
+    if (typeof k !== 'number' || !Number.isInteger(k)) {
+      throw new TypeError('k must be an integer');
+    }
+    if (k <= 0) {
+      throw new RangeError('k must be positive');
+    }
+    if (k > arr.length) {
+      throw new RangeError('k cannot exceed array length');
+    }
+    if (!rng || typeof rng.nextInt !== 'function') {
+      throw new TypeError('rng must be an RNG instance');
     }
-  }
-  
-  return indices.sort((a, b) => a - b).map(i => arr[i]);
-};
+   const indices = new Set();
+   const n = arr.length;
+   
+   while (indices.size < k) {
+     indices.add(rng.nextInt(n));
+   }
+   
+   return Array.from(indices).sort((a, b) => a - b).map(i => arr[i]);
+ };
 
 export const randomPermutation = (arr, rng) => {
-  const copy = [...arr];
-  for (let i = copy.length - 1; i > 0; i--) {
-    const j = rng.nextInt(i + 1);
-    [copy[i], copy[j]] = [copy[j], copy[i]];
-  }
-  return copy;
-};
+   if (!Array.isArray(arr)) {
+     throw new TypeError('arr must be array');
+   }
+   if (!rng || typeof rng.nextInt !== 'function') {
+     throw new TypeError('rng must be an RNG instance');
+   }
+   const copy = [...arr];
+   for (let i = copy.length - 1; i > 0; i--) {
+     const j = rng.nextInt(i + 1);
+     [copy[i], copy[j]] = [copy[j], copy[i]];
+   }
+   return copy;
+ };