@cloudglides/nox 1.1.0

package/src/index.d.ts

@@ -0,0 +1,114 @@
+export interface IGenerator {
+  next(): number | bigint;
+  nextInt(max?: number): number;
+  nextFloat(): number;
+}
+
+export type GeneratorConstructor = new (seed?: number | bigint) => IGenerator;
+
+export class RNG {
+  gen: IGenerator;
+  constructor(generator?: GeneratorConstructor | IGenerator, seed?: number | bigint);
+  next(): any;
+  nextInt(max?: number): number;
+  nextFloat(): number;
+  int(min: number, max: number): number;
+  bool(probability?: number): boolean;
+  range(min: number, max: number, step?: number): number;
+  choice<T>(arr: T[]): T;
+  batch<T>(count: number, fn: (rng: RNG, index: number) => T): T[];
+  floats(count: number): number[];
+  ints(count: number, max?: number): number[];
+  bools(count: number, probability?: number): boolean[];
+}
+
+export function rng(): RNG;
+export function deterministic(seed: number | bigint): RNG;
+
+export function normal(rng: RNG | IGenerator, mean?: number, stddev?: number): number;
+export function exponential(rng: RNG | IGenerator, lambda?: number): number;
+export function uniform(rng: RNG | IGenerator, min: number, max: number): number;
+export function poisson(rng: RNG | IGenerator, lambda: number): number;
+
+export function shuffle<T>(arr: T[], rng: RNG | IGenerator, inPlace?: boolean): T[];
+export function pick<T>(arr: T[], rng: RNG | IGenerator): T;
+export function sample<T>(arr: T[], count: number, rng: RNG | IGenerator): T[];
+
+export function saveState(rng: RNG): any;
+export function restoreState(rng: RNG, snapshot: any): void;
+export function cloneGenerator(rng: RNG): RNG;
+
+export function weightedPick<T>(arr: T[], weights: number[], rng: RNG | IGenerator): T;
+export function weightedSample<T>(arr: T[], weights: number[], count: number, rng: RNG | IGenerator): T[];
+export function reservoirSample<T>(stream: T[], k: number, rng: RNG | IGenerator): T[];
+
+export interface TestResult {
+  mean?: number;
+  variance?: number;
+  stdDev?: number;
+  tStatistic?: number;
+  expectedMean?: number;
+  expectedVariance?: number;
+  chi2Statistic?: number;
+  degreesOfFreedom?: number;
+}
+
+export interface KSTestResult {
+  statistic: number;
+  pass_0_10: boolean;
+  pass_0_05: boolean;
+  pass_0_01: boolean;
+}
+
+export function meanTest(data: number[], expectedMean?: number): TestResult;
+export function varianceTest(data: number[], expectedVariance?: number): TestResult;
+export function kolmogorovSmirnovTest(data: number[]): KSTestResult;
+
+export class Xorshift64 {
+  constructor(seed?: number | bigint);
+  next(): bigint;
+  nextInt(max?: number): number;
+  nextFloat(): number;
+}
+
+export class Splitmix64 {
+  constructor(seed?: number | bigint);
+  next(): bigint;
+  nextInt(max?: number): number;
+  nextFloat(): number;
+}
+
+export class PCG64 {
+  constructor(seed?: bigint, inc?: bigint);
+  next(): bigint;
+  nextInt(max?: number): number;
+  nextFloat(): number;
+}
+
+export class MT19937 {
+  constructor(seed?: number);
+  next(): number;
+  nextInt(max?: number): number;
+  nextFloat(): number;
+}
+
+export class Logistic {
+  constructor(seed?: number, r?: number);
+  next(): number;
+  nextInt(max?: number): number;
+  nextFloat(): number;
+}
+
+export class Tent {
+  constructor(seed?: number, mu?: number);
+  next(): number;
+  nextInt(max?: number): number;
+  nextFloat(): number;
+}
+
+export class Mixer {
+  constructor(rng1: any, rng2: any);
+  next(): bigint;
+  nextInt(max?: number): number;
+  nextFloat(): number;
+}

package/src/index.js

@@ -0,0 +1,31 @@
+export {
+  rng,
+  RNG,
+  deterministic,
+  normal,
+  exponential,
+  uniform,
+  poisson,
+  shuffle,
+  pick,
+  sample,
+  saveState,
+  restoreState,
+  cloneGenerator,
+  weightedPick,
+  weightedSample,
+  reservoirSample,
+  meanTest,
+  varianceTest,
+  kolmogorovSmirnovTest
+} from './core.js';
+
+export {
+  Xorshift64,
+  Splitmix64,
+  PCG64,
+  MT19937,
+  Logistic,
+  Tent,
+  Mixer
+} from './generators/index.js';

package/src/presets.js

@@ -0,0 +1,15 @@
+import { RNG } from './rng.js';
+import { PCG64 } from './generators/index.js';
+
+export const deterministic = (seed) => {
+  if (seed === null || seed === undefined) {
+    throw new TypeError('Deterministic mode requires an explicit seed');
+  }
+  if (typeof seed !== 'number' && typeof seed !== 'bigint') {
+    throw new TypeError('Seed must be a number or bigint');
+  }
+  if (typeof seed === 'number' && !Number.isFinite(seed)) {
+    throw new Error('Seed must be a finite number');
+  }
+  return new RNG(PCG64, seed);
+};

package/src/rng.js

@@ -0,0 +1,141 @@
+import { PCG64 } from './generators/index.js';
+import { combined } from './utils/entropy.js';
+
+export class RNG {
+  constructor(generator = null, seed = null) {
+    if (generator === null) {
+      seed = seed || combined();
+      this.gen = new PCG64(seed);
+    } else if (typeof generator === 'function') {
+      this.gen = new generator(seed || combined());
+    } else if (typeof generator === 'object' && generator !== null) {
+      this.gen = generator;
+    } else {
+      throw new TypeError('Generator must be a constructor function or instance');
+    }
+  }
+
+  next() {
+    return this.gen.next();
+  }
+
+  nextInt(max = 2147483647) {
+    return this.gen.nextInt(max);
+  }
+
+  nextFloat() {
+    return this.gen.nextFloat();
+  }
+
+  int(min, max) {
+    if (typeof min !== 'number' || typeof max !== 'number') {
+      throw new TypeError('int() requires two number arguments');
+    }
+    if (!Number.isInteger(min) || !Number.isInteger(max)) {
+      throw new TypeError('int() arguments must be integers');
+    }
+    if (min > max) [min, max] = [max, min];
+    return Math.floor(this.nextFloat() * (max - min + 1)) + min;
+  }
+
+  bool(probability = 0.5) {
+    if (typeof probability !== 'number') {
+      throw new TypeError('probability must be a number');
+    }
+    if (probability < 0 || probability > 1) {
+      throw new RangeError('probability must be between 0 and 1');
+    }
+    return this.nextFloat() < probability;
+  }
+
+  range(min, max, step = 1) {
+    if (typeof min !== 'number' || typeof max !== 'number' || typeof step !== 'number') {
+      throw new TypeError('min, max, and step must be numbers');
+    }
+    if (!Number.isInteger(min) || !Number.isInteger(max) || !Number.isInteger(step)) {
+      throw new Error('min, max, and step must be integers');
+    }
+    if (step <= 0) {
+      throw new Error('step must be positive');
+    }
+    if (min > max) {
+      throw new Error('min must be less than or equal to max');
+    }
+    
+    const count = Math.floor((max - min) / step) + 1;
+    const idx = this.nextInt(count);
+    return min + idx * step;
+  }
+
+  choice(arr) {
+    if (!Array.isArray(arr) || arr.length === 0) {
+      throw new TypeError('choice() requires non-empty array');
+    }
+    return arr[this.nextInt(arr.length)];
+  }
+
+  batch(count, fn) {
+    if (typeof count !== 'number' || !Number.isInteger(count)) {
+      throw new TypeError('count must be an integer');
+    }
+    if (count < 0) {
+      throw new RangeError('count must be non-negative');
+    }
+    if (typeof fn !== 'function') {
+      throw new TypeError('fn must be a function');
+    }
+    
+    const result = [];
+    for (let i = 0; i < count; i++) {
+      result.push(fn(this, i));
+    }
+    return result;
+  }
+
+  floats(count) {
+    if (typeof count !== 'number' || !Number.isInteger(count)) {
+      throw new TypeError('count must be an integer');
+    }
+    if (count < 0) {
+      throw new RangeError('count must be non-negative');
+    }
+    
+    const result = new Array(count);
+    for (let i = 0; i < count; i++) {
+      result[i] = this.nextFloat();
+    }
+    return result;
+  }
+
+  ints(count, max = 2147483647) {
+    if (typeof count !== 'number' || !Number.isInteger(count)) {
+      throw new TypeError('count must be an integer');
+    }
+    if (count < 0) {
+      throw new RangeError('count must be non-negative');
+    }
+    
+    const result = new Array(count);
+    for (let i = 0; i < count; i++) {
+      result[i] = this.nextInt(max);
+    }
+    return result;
+  }
+
+  bools(count, probability = 0.5) {
+    if (typeof count !== 'number' || !Number.isInteger(count)) {
+      throw new TypeError('count must be an integer');
+    }
+    if (count < 0) {
+      throw new RangeError('count must be non-negative');
+    }
+    
+    const result = new Array(count);
+    for (let i = 0; i < count; i++) {
+      result[i] = this.bool(probability);
+    }
+    return result;
+  }
+}
+
+export const rng = () => new RNG();

package/src/utils/bits.js

@@ -0,0 +1,25 @@
+export const rotateBits = (val, shift) => {
+  const mask = BigInt(64);
+  shift = BigInt(shift) % mask;
+  return (val << shift) | (val >> (mask - shift));
+};
+
+export const extractBits = (val, start, length) => {
+  const mask = (BigInt(1) << BigInt(length)) - BigInt(1);
+  return (val >> BigInt(start)) & mask;
+};
+
+export const hammingWeight = (val) => {
+  let count = 0;
+  while (val > 0n) {
+    count += val & 1n ? 1 : 0;
+    val >>= 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;
+};

package/src/utils/categorical.js

@@ -0,0 +1,57 @@
+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');
+  }
+
+  const total = probabilities.reduce((a, b) => a + b, 0);
+  if (total <= 0) throw new Error('Probabilities must sum to positive value');
+  
+  const normalized = probabilities.map(p => p / total);
+
+  let cumsum = 0;
+  const cumulative = normalized.map(p => (cumsum += p));
+
+  const rand = rng.nextFloat();
+  for (let i = 0; i < cumulative.length; i++) {
+    if (rand <= cumulative[i]) {
+      return categories[i];
+    }
+  }
+
+  return categories[categories.length - 1];
+};
+
+export const multinomial = (rng, n, categories, probabilities) => {
+  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]++;
+  }
+
+  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;
+
+  for (let i = 0; i < rows; i++) {
+    for (let j = 0; j < cols; j++) {
+      rand -= matrix[i][j];
+      if (rand <= 0) {
+        return [i, j];
+      }
+    }
+  }
+
+  return [rows - 1, cols - 1];
+};

package/src/utils/combinatorics.js

@@ -0,0 +1,85 @@
+export const combinations = (arr, k) => {
+  if (k > arr.length) return [];
+  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;
+};
+
+export const permutations = (arr) => {
+  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]];
+    }
+  };
+
+  permute([...arr], 0);
+  return result;
+};
+
+export const kPermutations = (arr, k) => {
+  if (k > arr.length) return [];
+  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]);
+    }
+  };
+
+  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);
+    }
+  }
+  
+  return 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;
+};

package/src/utils/distributions-extra.js

@@ -0,0 +1,32 @@
+export const beta = (rng, alpha, beta) => {
+  const u = -Math.log(rng.nextFloat()) / alpha;
+  const v = -Math.log(rng.nextFloat()) / beta;
+  return u / (u + v);
+};
+
+export const gamma = (rng, shape, scale = 1) => {
+  if (shape < 1) {
+    return gamma(rng, shape + 1, scale) * Math.pow(rng.nextFloat(), 1 / shape);
+  }
+  
+  const d = shape - 1 / 3;
+  const c = 1 / Math.sqrt(9 * d);
+  
+  let z, v, u;
+  do {
+    do {
+      const x = (rng.nextFloat() * 2 - 1);
+      v = 1 + c * x;
+    } while (v <= 0);
+    
+    v = v * v * v;
+    u = rng.nextFloat();
+    z = -Math.log(u);
+  } while (u > 1 - 0.0331 * (x * x) * (x * x) && Math.log(z + Math.log(d)) > Math.log(d * (Math.log(v) + 1)));
+  
+  return d * v * scale;
+};
+
+export const chi2 = (rng, k) => {
+  return gamma(rng, k / 2, 2);
+};

package/src/utils/distributions-special.js

@@ -0,0 +1,21 @@
+export const weibull = (rng, shape, scale = 1) => {
+  const u = rng.nextFloat();
+  return scale * Math.pow(-Math.log(1 - u), 1 / shape);
+};
+
+export const lognormal = (rng, mu, sigma) => {
+  const u1 = rng.nextFloat();
+  const u2 = rng.nextFloat();
+  const z = Math.sqrt(-2 * Math.log(u1)) * Math.cos(2 * Math.PI * u2);
+  return Math.exp(mu + sigma * z);
+};
+
+export const rayleigh = (rng, sigma = 1) => {
+  const u = rng.nextFloat();
+  return sigma * Math.sqrt(-2 * Math.log(u));
+};
+
+export const cauchy = (rng, median = 0, scale = 1) => {
+  const u = rng.nextFloat();
+  return median + scale * Math.tan(Math.PI * (u - 0.5));
+};

package/src/utils/distributions.js

@@ -0,0 +1,69 @@
+export const normal = (rng, mean = 0, stddev = 1) => {
+  if (!rng || typeof rng.nextFloat !== 'function') {
+    throw new TypeError('First argument must be RNG instance');
+  }
+  if (typeof mean !== 'number' || typeof stddev !== 'number') {
+    throw new TypeError('mean and stddev must be numbers');
+  }
+  if (stddev <= 0) {
+    throw new Error('stddev must be positive');
+  }
+  
+  let u1, u2;
+  do {
+    u1 = rng.nextFloat();
+    u2 = rng.nextFloat();
+  } while (u1 <= 0 || u2 <= 0);
+  
+  const z0 = Math.sqrt(-2 * Math.log(u1)) * Math.cos(2 * Math.PI * u2);
+  return z0 * stddev + mean;
+};
+
+export const exponential = (rng, lambda = 1) => {
+  if (!rng || typeof rng.nextFloat !== 'function') {
+    throw new TypeError('First argument must be RNG instance');
+  }
+  if (typeof lambda !== 'number' || lambda <= 0) {
+    throw new Error('lambda must be a positive number');
+  }
+  
+  let u = rng.nextFloat();
+  while (u === 0 || u === 1) {
+    u = rng.nextFloat();
+  }
+  return -Math.log(1 - u) / lambda;
+};
+
+export const poisson = (rng, lambda) => {
+  if (!rng || typeof rng.nextFloat !== 'function') {
+    throw new TypeError('First argument must be RNG instance');
+  }
+  if (typeof lambda !== 'number' || lambda <= 0) {
+    throw new Error('lambda must be a positive number');
+  }
+  
+  const L = Math.exp(-lambda);
+  let k = 0;
+  let p = 1;
+  
+  do {
+    k++;
+    p *= rng.nextFloat();
+  } while (p > L);
+  
+  return k - 1;
+};
+
+export const uniform = (rng, min, max) => {
+  if (!rng || typeof rng.nextFloat !== 'function') {
+    throw new TypeError('First argument must be RNG instance');
+  }
+  if (typeof min !== 'number' || typeof max !== 'number') {
+    throw new TypeError('min and max must be numbers');
+  }
+  if (min >= max) {
+    throw new Error('min must be less than max');
+  }
+  
+  return min + rng.nextFloat() * (max - min);
+};

package/src/utils/entropy.js

@@ -0,0 +1,57 @@
+import { performance } from 'perf_hooks';
+import { randomBytes } from 'crypto';
+
+let cryptoCache = null;
+let cryptoCacheTime = 0;
+
+export const fromPerformance = () => {
+  const t = performance.now();
+  return BigInt(Math.floor(t * 1000)) ^ BigInt(Math.floor(t * 1000000) % 1000000);
+};
+
+export const fromMemory = () => {
+  if (typeof process !== 'undefined' && process.memoryUsage) {
+    const mem = process.memoryUsage();
+    const total = mem.heapUsed + mem.external + mem.heapTotal;
+    return BigInt(Math.floor(total)) ^ BigInt(Date.now());
+  }
+  return BigInt(Date.now());
+};
+
+export const fromCrypto = (bytes = 8) => {
+  try {
+    const now = Date.now();
+    if (cryptoCache && (now - cryptoCacheTime) < 100) {
+      return cryptoCache;
+    }
+    
+    const buf = randomBytes(Math.max(bytes, 8));
+    let val = 0n;
+    for (let i = 0; i < buf.length; i++) {
+      val = (val << 8n) | BigInt(buf[i]);
+    }
+    
+    cryptoCache = val;
+    cryptoCacheTime = now;
+    return val;
+  } catch {
+    return BigInt(Math.random() * Number.MAX_SAFE_INTEGER);
+  }
+};
+
+export const combined = () => {
+  const perf = fromPerformance();
+  const mem = fromMemory();
+  const crypto = fromCrypto();
+  
+  let mix = perf ^ mem ^ crypto;
+  mix = mix ^ (mix >> 33n);
+  mix = (mix * 0xff51afd7ed558ccdn) & ((1n << 64n) - 1n);
+  
+  return mix !== 0n ? mix : 1n;
+};
+
+export const clearCryptoCache = () => {
+  cryptoCache = null;
+  cryptoCacheTime = 0;
+};

package/src/utils/index.js

@@ -0,0 +1,30 @@
+export { seedFromTime, seedFromEntropy } from './seed.js';
+export { normal, exponential, poisson, uniform } from './distributions.js';
+export { beta, gamma, chi2 } from './distributions-extra.js';
+export { weibull, lognormal, rayleigh, cauchy } from './distributions-special.js';
+export { shuffle, pick, sample } from './sequence.js';
+export { fromPerformance, fromMemory, fromCrypto, combined, clearCryptoCache } from './entropy.js';
+export { rotateBits, extractBits, hammingWeight, bitRange } from './bits.js';
+export { brownianMotion, ornsteinUhlenbeck, geometricBrownian } from './stochastic.js';
+export { chiSquareTest, entropy, autocorrelation, runTest, kolmogorovSmirnovTest, meanTest, varianceTest } from './statistics.js';
+export { perlin2D, valueNoise } from './noise.js';
+export { weightedPick, weightedSample, reservoirSample } from './sampling.js';
+export { saveState, restoreState, cloneGenerator } from './state.js';
+export { SeedSequence, seedMultiple } from './seeding.js';
+export { combinations, permutations, kPermutations, randomCombination, randomPermutation } from './combinatorics.js';
+export { categorical, multinomial, categorical2D } from './categorical.js';
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+