@obinexusmk2/hypernum 0.1.0

package/src/operations/factorial.ts

@@ -0,0 +1,279 @@
+/**
+ * Factorial operations module for Hypernum library
+ * Provides efficient implementations for factorial and related computations
+ */
+
+import {
+    toBigInt,
+    ValidationError,
+    OverflowError,
+    validateNonNegative
+  } from '../utils/validation';
+  
+  /**
+   * Options for factorial operations
+   */
+  export interface FactorialOptions {
+    /** Maximum allowed computation value */
+    maxValue?: number;
+    /** Whether to check for overflow */
+    checkOverflow?: boolean;
+    /** Cache computed values */
+    useCache?: boolean;
+  }
+  
+  const DEFAULT_OPTIONS: Required<FactorialOptions> = {
+    maxValue: 1000,
+    checkOverflow: true,
+    useCache: true
+  };
+  
+  // Cache for factorial values
+  const factorialCache = new Map<bigint, bigint>();
+  
+  /**
+   * Calculates factorial of a number (n!)
+   */
+  export function factorial(
+    value: bigint | string | number,
+    options: FactorialOptions = {}
+  ): bigint {
+    const opts = { ...DEFAULT_OPTIONS, ...options };
+    const n = toBigInt(value);
+  
+    validateNonNegative(n);
+  
+    if (opts.checkOverflow && n > BigInt(opts.maxValue)) {
+      throw new OverflowError(`Factorial input too large: maximum allowed is ${opts.maxValue}`);
+    }
+  
+    // Handle base cases
+    if (n <= 1n) {
+      return 1n;
+    }
+  
+    // Check cache
+    if (opts.useCache && factorialCache.has(n)) {
+      return factorialCache.get(n)!;
+    }
+  
+    // Calculate factorial
+    let result = 1n;
+    for (let i = 2n; i <= n; i++) {
+      result *= i;
+    }
+  
+    // Cache result
+    if (opts.useCache) {
+      factorialCache.set(n, result);
+    }
+  
+    return result;
+  }
+  
+  /**
+   * Calculates binomial coefficient (n choose k)
+   */
+  export function binomial(
+    n: bigint | string | number,
+    k: bigint | string | number,
+    options: FactorialOptions = {}
+  ): bigint {
+    const opts = { ...DEFAULT_OPTIONS, ...options };
+    const bigN = toBigInt(n);
+    const bigK = toBigInt(k);
+  
+    validateNonNegative(bigN);
+    validateNonNegative(bigK);
+  
+    if (bigK > bigN) {
+      throw new ValidationError('K cannot be greater than N in binomial coefficient');
+    }
+  
+    // Optimize for k > n/2 by using symmetry
+    if (bigK > bigN / 2n) {
+      return binomial(bigN, bigN - bigK, opts);
+    }
+  
+    // Use multiplicative formula instead of factorial for efficiency
+    let result = 1n;
+    for (let i = 0n; i < bigK; i++) {
+      result = (result * (bigN - i)) / (i + 1n);
+    }
+  
+    return result;
+  }
+  
+  /**
+   * Calculates subfactorial (derangement number)
+   * Number of permutations of n elements with no fixed points
+   */
+  export function subfactorial(
+    value: bigint | string | number,
+    options: FactorialOptions = {}
+  ): bigint {
+    const opts = { ...DEFAULT_OPTIONS, ...options };
+    const n = toBigInt(value);
+  
+    validateNonNegative(n);
+  
+    if (opts.checkOverflow && n > BigInt(opts.maxValue)) {
+      throw new OverflowError(`Subfactorial input too large: maximum allowed is ${opts.maxValue}`);
+    }
+  
+    // Handle base cases
+    if (n === 0n) return 1n;
+    if (n === 1n) return 0n;
+  
+    // Use recursive formula !n = n * !(n-1) + (-1)^n
+    let result = 0n;
+    const nFact = factorial(n, opts);
+  
+    for (let k = 0n; k <= n; k++) {
+      const term = factorial(n - k, opts) * (k % 2n === 0n ? 1n : -1n);
+      result += term;
+    }
+  
+    return nFact - result;
+  }
+  
+  /**
+   * Calculates rising factorial (Pochhammer symbol)
+   * x^(n) = x(x+1)(x+2)...(x+n-1)
+   */
+  export function risingFactorial(
+    x: bigint | string | number,
+    n: bigint | string | number,
+    options: FactorialOptions = {}
+  ): bigint {
+    const opts = { ...DEFAULT_OPTIONS, ...options };
+    const bigX = toBigInt(x);
+    const bigN = toBigInt(n);
+  
+    validateNonNegative(bigN);
+  
+    if (opts.checkOverflow && bigN > BigInt(opts.maxValue)) {
+      throw new OverflowError(`Rising factorial input too large: maximum allowed is ${opts.maxValue}`);
+    }
+  
+    let result = 1n;
+    for (let i = 0n; i < bigN; i++) {
+      result *= (bigX + i);
+    }
+  
+    return result;
+  }
+  
+  /**
+   * Calculates falling factorial
+   * x_(n) = x(x-1)(x-2)...(x-n+1)
+   */
+  export function fallingFactorial(
+    x: bigint | string | number,
+    n: bigint | string | number,
+    options: FactorialOptions = {}
+  ): bigint {
+    const opts = { ...DEFAULT_OPTIONS, ...options };
+    const bigX = toBigInt(x);
+    const bigN = toBigInt(n);
+  
+    validateNonNegative(bigN);
+  
+    if (opts.checkOverflow && bigN > BigInt(opts.maxValue)) {
+      throw new OverflowError(`Falling factorial input too large: maximum allowed is ${opts.maxValue}`);
+    }
+  
+    let result = 1n;
+    for (let i = 0n; i < bigN; i++) {
+      result *= (bigX - i);
+    }
+  
+    return result;
+  }
+  
+  /**
+   * Calculates multifactorial (n!!)
+   * Product of numbers from 1 to n that leave the same remainder as n when divided by k
+   */
+  export function multiFactorial(
+    value: bigint | string | number,
+    k: bigint | string | number = 2n,
+    options: FactorialOptions = {}
+  ): bigint {
+    const opts = { ...DEFAULT_OPTIONS, ...options };
+    const n = toBigInt(value);
+    const bigK = toBigInt(k);
+  
+    validateNonNegative(n);
+    if (bigK <= 0n) {
+      throw new ValidationError('K must be positive in multifactorial');
+    }
+  
+    if (opts.checkOverflow && n > BigInt(opts.maxValue)) {
+      throw new OverflowError(`Multifactorial input too large: maximum allowed is ${opts.maxValue}`);
+    }
+  
+    let result = 1n;
+    let current = n;
+  
+    while (current > 0n) {
+      result *= current;
+      current -= bigK;
+    }
+  
+    return result;
+  }
+  
+  /**
+   * Calculates primorial (product of primes up to n)
+   */
+  export function primorial(
+    value: bigint | string | number,
+    options: FactorialOptions = {}
+  ): bigint {
+    const opts = { ...DEFAULT_OPTIONS, ...options };
+    const n = toBigInt(value);
+  
+    validateNonNegative(n);
+  
+    if (opts.checkOverflow && n > BigInt(opts.maxValue)) {
+      throw new OverflowError(`Primorial input too large: maximum allowed is ${opts.maxValue}`);
+    }
+  
+    if (n <= 1n) return 1n;
+  
+    // Generate primes up to n using Sieve of Eratosthenes
+    const num = Number(n);
+    const sieve = new Array(num + 1).fill(true);
+    sieve[0] = sieve[1] = false;
+  
+    for (let i = 2; i * i <= num; i++) {
+      if (sieve[i]) {
+        for (let j = i * i; j <= num; j += i) {
+          sieve[j] = false;
+        }
+      }
+    }
+  
+    // Calculate product of all primes up to n
+    let result = 1n;
+    for (let i = 2; i <= num; i++) {
+      if (sieve[i]) {
+        result *= BigInt(i);
+      }
+    }
+  
+    return result;
+  }
+
+  
+  
+  export default {
+    factorial,
+    binomial,
+    subfactorial,
+    risingFactorial,
+    fallingFactorial,
+    multiFactorial,
+    primorial
+  };

package/src/operations/index.ts

@@ -0,0 +1,5 @@
+export * from './arithmetic';
+export * from './comparison';
+export * from './conversion';
+export * from './bitwise';
+export * from './factorial'

package/src/operations/power.ts

@@ -0,0 +1,316 @@
+/**
+ * Power operations module for Hypernum library
+ * Provides efficient implementations for exponentiation and related operations
+ */
+
+import {
+    toBigInt,
+    ValidationError,
+    OverflowError,
+    validateNonNegative,
+    checkPowerOverflow
+  } from '../utils/validation';
+  
+  import {
+    RoundingMode,
+    round,
+  } from '../utils/precision';
+  
+  /**
+   * Options for power operations
+   */
+  export interface PowerOptions {
+    /** Precision for decimal operations */
+    precision?: number;
+    /** Rounding mode for decimal operations */
+    roundingMode?: RoundingMode;
+    /** Whether to check for overflow */
+    checkOverflow?: boolean;
+    /** Maximum allowed computation steps */
+    maxSteps?: number;
+  }
+  
+  const DEFAULT_OPTIONS: Required<PowerOptions> = {
+    precision: 0,
+    roundingMode: RoundingMode.HALF_EVEN,
+    checkOverflow: true,
+    maxSteps: 1000
+  };
+  
+  /**
+   * Raises a number to an integer power using binary exponentiation
+   */
+  export function power(
+    baseValue: bigint | string | number,
+    exponentValue: bigint | string | number,
+    options: PowerOptions = {}
+  ): bigint {
+    const opts = { ...DEFAULT_OPTIONS, ...options };
+    const bigBase = toBigInt(baseValue);
+    const bigExponent = toBigInt(exponentValue);
+  
+    // Handle special cases
+    if (bigExponent === 0n) {
+      return 1n;
+    }
+    if (bigExponent === 1n) {
+      return bigBase;
+    }
+    if (bigBase === 0n && bigExponent < 0n) {
+      throw new ValidationError('Zero cannot be raised to a negative power');
+    }
+    if (bigBase === 0n) {
+      return 0n;
+    }
+    if (bigBase === 1n) {
+      return 1n;
+    }
+    if (bigBase === -1n) {
+      return bigExponent % 2n === 0n ? 1n : -1n;
+    }
+  
+    // Validate inputs
+    if (bigExponent < 0n) {
+      throw new ValidationError('Negative exponents not supported for integer power');
+    }
+  
+    if (opts.checkOverflow) {
+      checkPowerOverflow(bigBase, bigExponent);
+    }
+  
+    // Binary exponentiation algorithm
+    let result = 1n;
+    let base = bigBase;
+    let exponent = bigExponent;
+    let steps = 0;
+  
+    while (exponent > 0n) {
+      if (steps++ > opts.maxSteps) {
+        throw new OverflowError('Power operation exceeded maximum computation steps');
+      }
+  
+      if (exponent & 1n) {
+        result *= base;
+      }
+      base *= base;
+      exponent >>= 1n;
+    }
+  
+    if (opts.precision > 0) {
+      return round(result, opts.precision, opts.roundingMode);
+    }
+  
+    return result;
+  }
+  
+  /**
+   * Calculates square root using Newton's method
+   */
+  export function sqrt(
+    value: bigint | string | number,
+    options: PowerOptions = {}
+  ): bigint {
+    const opts = { ...DEFAULT_OPTIONS, ...options };
+    const bigValue = toBigInt(value);
+  
+    validateNonNegative(bigValue);
+  
+    if (bigValue === 0n) {
+      return 0n;
+    }
+    if (bigValue === 1n) {
+      return 1n;
+    }
+  
+    // Newton's method for square root
+    let guess = bigValue >> 1n;
+    let lastGuess: bigint;
+    let steps = 0;
+  
+    do {
+      if (steps++ > opts.maxSteps) {
+        throw new OverflowError('Square root operation exceeded maximum computation steps');
+      }
+  
+      lastGuess = guess;
+      guess = (guess + bigValue / guess) >> 1n;
+    } while (guess < lastGuess);
+  
+    if (opts.precision > 0) {
+      return round(lastGuess, opts.precision, opts.roundingMode);
+    }
+  
+    return lastGuess;
+  }
+  
+  /**
+   * Calculates nth root using Newton's method
+   */
+  export function nthRoot(
+    value: bigint | string | number,
+    n: bigint | string | number,
+    options: PowerOptions = {}
+  ): bigint {
+    const opts = { ...DEFAULT_OPTIONS, ...options };
+    const bigValue = toBigInt(value);
+    const bigN = toBigInt(n);
+  
+    validateNonNegative(bigValue);
+    if (bigN <= 0n) {
+      throw new ValidationError('Root index must be positive');
+    }
+  
+    if (bigValue === 0n) {
+      return 0n;
+    }
+    if (bigValue === 1n) {
+      return 1n;
+    }
+    if (bigN === 1n) {
+      return bigValue;
+    }
+    if (bigN === 2n) {
+      return sqrt(bigValue, opts);
+    }
+  
+    // Newton's method for nth root
+    let guess = bigValue >> 1n;
+    let lastGuess: bigint;
+    let steps = 0;
+  
+    const nMinus1 = bigN - 1n;
+  
+    do {
+      if (steps++ > opts.maxSteps) {
+        throw new OverflowError('Nth root operation exceeded maximum computation steps');
+      }
+  
+      lastGuess = guess;
+      const powered = power(guess, nMinus1, opts);
+      guess = ((nMinus1 * guess) + (bigValue / powered)) / bigN;
+    } while (guess < lastGuess);
+  
+    if (opts.precision > 0) {
+      return round(lastGuess, opts.precision, opts.roundingMode);
+    }
+  
+    return lastGuess;
+  }
+  
+  /**
+   * Calculates tetration (repeated exponentiation)
+   * a↑↑n = a^(a^(a^...)) (n times)
+   */
+  export function tetration(
+    base: bigint | string | number,
+    height: bigint | string | number,
+    options: PowerOptions = {}
+  ): bigint {
+    const opts = { ...DEFAULT_OPTIONS, ...options };
+    const bigBase = toBigInt(base);
+    const bigHeight = toBigInt(height);
+  
+    validateNonNegative(bigHeight);
+  
+    if (bigHeight === 0n) {
+      return 1n;
+    }
+    if (bigHeight === 1n) {
+      return bigBase;
+    }
+    if (bigBase === 0n) {
+      return bigHeight % 2n === 0n ? 1n : 0n;
+    }
+    if (bigBase === 1n) {
+      return 1n;
+    }
+    if (bigBase === 2n && bigHeight > 4n) {
+      throw new OverflowError('Tetration would overflow for base 2 and height > 4');
+    }
+  
+    let result = bigBase;
+    let steps = 0;
+  
+    for (let i = 1n; i < bigHeight; i++) {
+      if (steps++ > opts.maxSteps) {
+        throw new OverflowError('Tetration operation exceeded maximum computation steps');
+      }
+  
+      result = power(bigBase, result, opts);
+    }
+  
+    if (opts.precision > 0) {
+      return round(result, opts.precision, opts.roundingMode);
+    }
+  
+    return result;
+  }
+  
+  /**
+   * Calculates super-root (inverse tetration)
+   * Finds x where x↑↑n = value
+   */
+  export function superRoot(
+    value: bigint | string | number,
+    height: bigint | string | number,
+    options: PowerOptions = {}
+  ): bigint {
+    const opts = { ...DEFAULT_OPTIONS, ...options };
+    const bigValue = toBigInt(value);
+    const bigHeight = toBigInt(height);
+  
+    validateNonNegative(bigHeight);
+    if (bigHeight === 0n) {
+      throw new ValidationError('Height cannot be zero for super-root');
+    }
+    if (bigValue < 1n) {
+      throw new ValidationError('Value must be at least 1 for super-root');
+    }
+  
+    if (bigValue === 1n) {
+      return 1n;
+    }
+    if (bigHeight === 1n) {
+      return bigValue;
+    }
+  
+    // Binary search for super-root
+    let left = 1n;
+    let right = bigValue;
+    let steps = 0;
+  
+    while (left <= right) {
+      if (steps++ > opts.maxSteps) {
+        throw new OverflowError('Super-root operation exceeded maximum computation steps');
+      }
+  
+      const mid = (left + right) >> 1n;
+      try {
+        const test = tetration(mid, bigHeight, opts);
+        if (test === bigValue) {
+          return mid;
+        }
+        if (test < bigValue) {
+          left = mid + 1n;
+        } else {
+          right = mid - 1n;
+        }
+      } catch (error) {
+        right = mid - 1n;
+      }
+    }
+  
+    if (opts.precision > 0) {
+      return round(right, opts.precision, opts.roundingMode);
+    }
+  
+    return right;
+  }
+  
+  export default {
+    power,
+    sqrt,
+    nthRoot,
+    tetration,
+    superRoot
+  };