@obinexusmk2/hypernum 0.1.0

package/src/storage/Heap.ts

@@ -0,0 +1,238 @@
+
+/**
+ * Represents the result of a comparison operation
+ * -1: first value is less than second value
+ *  0: values are equal
+ *  1: first value is greater than second value
+ */
+export type ComparisonResult = -1 | 0 | 1;
+
+/**
+ * Generic comparator function type for heap elements
+ */
+export type Comparator<T> = (a: T, b: T) => ComparisonResult;
+
+/**
+ * Abstract base heap class implementing common heap operations
+ */
+abstract class Heap<T> {
+  protected heap: T[];
+  protected readonly compare: Comparator<T>;
+
+  constructor(comparator: Comparator<T>) {
+    this.heap = [];
+    this.compare = comparator;
+  }
+
+  /**
+   * Gets the size of the heap
+   */
+  public size(): number {
+    return this.heap.length;
+  }
+
+  /**
+   * Checks if the heap is empty
+   */
+  public isEmpty(): boolean {
+    return this.heap.length === 0;
+  }
+
+  /**
+   * Peeks at the root element without removing it
+   */
+  public peek(): T | undefined {
+    return this.heap[0];
+  }
+
+  /**
+   * Inserts a new element into the heap
+   */
+  public push(value: T): void {
+    this.heap.push(value);
+    this.siftUp(this.heap.length - 1);
+  }
+
+  /**
+   * Removes and returns the root element
+   */
+  public pop(): T | undefined {
+    if (this.isEmpty()) {
+      return undefined;
+    }
+
+    const root = this.heap[0];
+    const last = this.heap.pop()!;
+
+    if (!this.isEmpty()) {
+      this.heap[0] = last;
+      this.siftDown(0);
+    }
+
+    return root;
+  }
+
+  /**
+   * Removes all elements from the heap
+   */
+  public clear(): void {
+    this.heap = [];
+  }
+
+  /**
+   * Creates a heap from an array of elements
+   */
+  public static heapify<T extends {}>(array: T[], comparator: Comparator<T>): Heap<T> {
+    const heap = this instanceof MinHeap ? new MinHeap(comparator) : new MaxHeap(comparator);
+    array.forEach(item => heap.push(item));
+    return heap;
+  }
+
+  /**
+   * Gets the parent index of a node
+   */
+  protected getParentIndex(index: number): number {
+    return Math.floor((index - 1) / 2);
+  }
+
+  /**
+   * Gets the left child index of a node
+   */
+  protected getLeftChildIndex(index: number): number {
+    return 2 * index + 1;
+  }
+
+  /**
+   * Gets the right child index of a node
+   */
+  protected getRightChildIndex(index: number): number {
+    return 2 * index + 2;
+  }
+
+  /**
+   * Swaps two elements in the heap
+   */
+  protected swap(i: number, j: number): void {
+    const temp = this.heap[i]!;
+    this.heap[i] = this.heap[j]!;
+    this.heap[j] = temp;
+  }
+
+  /**
+   * Moves an element up the heap until heap property is satisfied
+   */
+  protected abstract siftUp(index: number): void;
+
+  /**
+   * Moves an element down the heap until heap property is satisfied
+   */
+  protected abstract siftDown(index: number): void;
+}
+
+/**
+ * MinHeap implementation where the root is the smallest element
+ */
+export class MinHeap<T> extends Heap<T> {
+  constructor(comparator: Comparator<T>) {
+    super(comparator);
+  }
+
+  protected siftUp(index: number): void {
+    while (index > 0) {
+      const parentIndex = this.getParentIndex(index);
+      if (this.compare(this.heap[index]!, this.heap[parentIndex]!) >= 0) {
+        break;
+      }
+      this.swap(index, parentIndex);
+      index = parentIndex;
+    }
+  }
+
+  protected siftDown(index: number): void {
+    const size = this.heap.length;
+    
+    while (true) {
+      let smallest = index;
+      const left = this.getLeftChildIndex(index);
+      const right = this.getRightChildIndex(index);
+
+      if (left < size && this.compare(this.heap[left]!, this.heap[smallest]!) < 0) {
+        smallest = left;
+      }
+
+      if (right < size && this.heap[right] !== undefined && this.compare(this.heap[right] as T, this.heap[smallest] as T) < 0) {
+        smallest = right;
+      }
+
+      if (smallest === index) {
+        break;
+      }
+
+      this.swap(index, smallest);
+      index = smallest;
+    }
+  }
+}
+
+/**
+ * MaxHeap implementation where the root is the largest element
+ */
+export class MaxHeap<T> extends Heap<T> {
+  constructor(comparator: Comparator<T>) {
+    super(comparator);
+  }
+
+  protected siftUp(index: number): void {
+    while (index > 0) {
+      const parentIndex = this.getParentIndex(index);
+      if (this.compare(this.heap[index]!, this.heap[parentIndex]!) <= 0) {
+        break;
+      }
+      this.swap(index, parentIndex);
+      index = parentIndex;
+    }
+  }
+
+  protected siftDown(index: number): void {
+    const size = this.heap.length;
+    
+    while (true) {
+      let largest = index;
+      const left = this.getLeftChildIndex(index);
+      const right = this.getRightChildIndex(index);
+
+      if (left < size && this.heap[left] !== undefined && this.compare(this.heap[left]!, this.heap[largest]!) > 0) {
+        largest = left;
+      }
+
+      if (right < size && this.heap[right] !== undefined && this.compare(this.heap[right]!, this.heap[largest]!) > 0) {
+        largest = right;
+      }
+
+      if (largest === index) {
+        break;
+      }
+
+      this.swap(index, largest);
+      index = largest;
+    }
+  }
+}
+
+// Type Guards
+export const isMinHeap = <T>(heap: Heap<T>): heap is MinHeap<T> => {
+  return heap instanceof MinHeap;
+};
+
+export const isMaxHeap = <T>(heap: Heap<T>): heap is MaxHeap<T> => {
+  return heap instanceof MaxHeap;
+};
+
+/**
+ * Custom comparator for large numbers
+ */
+export function createLargeNumberComparator(): (a: bigint, b: bigint) => number {
+  return (a, b) => {
+    return a > b ? 1 : a < b ? -1 : 0;
+  };
+}

package/src/storage/index.ts

@@ -0,0 +1 @@
+export * from './Heap';

package/src/structures/ackermann.ts

@@ -0,0 +1,233 @@
+import { Comparator } from "..";
+import { MaxHeap, createLargeNumberComparator } from "../storage/Heap";
+
+  /**
+   * Interface representing an Ackermann node in the computation structure
+   */
+  interface IAckermannNode {
+    m: number;
+    n: number;
+    value: bigint;
+    prevM?: IAckermannNode;  // Link to A(m-1, n)
+    prevN?: IAckermannNode;  // Link to A(m, n-1)
+    nextM?: IAckermannNode;  // Link to A(m+1, n)
+    nextN?: IAckermannNode;  // Link to A(m, n+1)
+  }
+  
+  /**
+   * Type for Ackermann computation path step
+   */
+  type ComputationStep = {
+    m: number;
+    n: number;
+    value: bigint;
+  };
+  
+  /**
+   * Type for growth rate analysis
+   */
+  type GrowthAnalysis = {
+    value: bigint;
+    increase: bigint;
+    multiplier: bigint;
+  };
+  
+  /**
+   * Class representing the Ackermann function computation structure
+   * Implements caching and relationship tracking between values
+   */
+  export class AckermannStructure {
+    private nodes: Map<string, IAckermannNode>;
+    private maxComputedM: number;
+    private maxComputedN: number;
+    private heap: MaxHeap<bigint>;
+  
+    constructor() {
+      this.nodes = new Map();
+      this.maxComputedM = -1;
+      this.maxComputedN = -1;
+      this.heap = new MaxHeap<bigint>(createLargeNumberComparator() as Comparator<bigint>);
+    }
+  
+    /**
+     * Generates a unique key for node storage
+     */
+    private static getNodeKey(m: number, n: number): string {
+      return `${m},${n}`;
+    }
+  
+    /**
+     * Computes the Ackermann function value
+     * Uses recursion with memoization
+     */
+    private computeAckermann(m: number, n: number): bigint {
+      // Handle invalid inputs
+      if (m < 0 || n < 0) {
+        throw new Error('Ackermann function undefined for negative numbers');
+      }
+  
+      // Check if already computed
+      const key = AckermannStructure.getNodeKey(m, n);
+      const existing = this.nodes.get(key);
+      if (existing) {
+        return existing.value;
+      }
+  
+      // Compute based on Ackermann function definition
+      let value: bigint;
+      try {
+        if (m === 0) {
+          value = BigInt(n + 1);
+        } else if (n === 0) {
+          value = this.computeAckermann(m - 1, 1);
+        } else {
+          const inner = this.computeAckermann(m, n - 1);
+          // Convert bigint to number for recursion, being careful about size
+          const innerNum = inner <= BigInt(Number.MAX_SAFE_INTEGER) 
+            ? Number(inner) 
+            : Number.MAX_SAFE_INTEGER;
+          value = this.computeAckermann(m - 1, innerNum);
+        }
+      } catch (error) {
+        // Handle stack overflow or computation limits
+        if (error instanceof RangeError) {
+          return BigInt(Number.MAX_SAFE_INTEGER);
+        }
+        throw error;
+      }
+  
+      return value;
+    }
+  
+    /**
+     * Adds a new node to the structure
+     */
+    public addNode(m: number, n: number): IAckermannNode {
+      const key = AckermannStructure.getNodeKey(m, n);
+      if (this.nodes.has(key)) {
+        return this.nodes.get(key)!;
+      }
+  
+      // Create new node
+      const value = this.computeAckermann(m, n);
+      const node: IAckermannNode = { m, n, value };
+      this.nodes.set(key, node);
+  
+      // Link to existing nodes
+      const prevMKey = AckermannStructure.getNodeKey(m - 1, n);
+      const prevNKey = AckermannStructure.getNodeKey(m, n - 1);
+  
+      if (this.nodes.has(prevMKey)) {
+        const prevM = this.nodes.get(prevMKey)!;
+        node.prevM = prevM;
+        prevM.nextM = node;
+      }
+  
+      if (this.nodes.has(prevNKey)) {
+        const prevN = this.nodes.get(prevNKey)!;
+        node.prevN = prevN;
+        prevN.nextN = node;
+      }
+  
+      // Update tracking
+      this.maxComputedM = Math.max(this.maxComputedM, m);
+      this.maxComputedN = Math.max(this.maxComputedN, n);
+      this.heap.push(value);
+  
+      return node;
+    }
+  
+    /**
+     * Builds nodes for a range of m and n values
+     */
+    public buildRange(mRange: number, nRange: number): void {
+      for (let m = 0; m <= mRange; m++) {
+        for (let n = 0; n <= nRange; n++) {
+          this.addNode(m, n);
+        }
+      }
+    }
+  
+    /**
+     * Gets the computation path to reach A(m,n)
+     */
+    public getComputationPath(m: number, n: number): ComputationStep[] {
+      const path: ComputationStep[] = [];
+      const key = AckermannStructure.getNodeKey(m, n);
+      let current = this.nodes.get(key);
+  
+      while (current) {
+        path.push({
+          m: current.m,
+          n: current.n,
+          value: current.value
+        });
+  
+        // Follow computation path backwards
+        if (current.m === 0) {
+          break;
+        } else if (current.n === 0) {
+          current = this.nodes.get(AckermannStructure.getNodeKey(current.m - 1, 1));
+        } else {
+          const prevN = this.nodes.get(AckermannStructure.getNodeKey(current.m, current.n - 1));
+          if (prevN) {
+            path.push({
+              m: prevN.m,
+              n: prevN.n,
+              value: prevN.value
+            });
+          }
+          // Convert bigint to number safely for the next lookup
+          const nextValue = prevN?.value ?? BigInt(0);
+          const safeNextValue = nextValue <= BigInt(Number.MAX_SAFE_INTEGER)
+            ? Number(nextValue)
+            : Number.MAX_SAFE_INTEGER;
+          current = this.nodes.get(AckermannStructure.getNodeKey(current.m - 1, safeNextValue));
+        }
+      }
+  
+      return path.reverse();
+    }
+  
+    /**
+     * Analyzes growth rate for a fixed m value
+     */
+    public analyzeGrowthRate(m: number): Map<number, GrowthAnalysis> {
+      const growth = new Map<number, GrowthAnalysis>();
+      let prevValue = BigInt(1);
+  
+      for (let n = 0; n <= this.maxComputedN; n++) {
+        const key = AckermannStructure.getNodeKey(m, n);
+        const node = this.nodes.get(key);
+        if (!node || node.value >= BigInt(Number.MAX_SAFE_INTEGER)) {
+          break;
+        }
+  
+        growth.set(n, {
+          value: node.value,
+          increase: node.value - prevValue,
+          multiplier: prevValue === BigInt(0) ? BigInt(0) : node.value / prevValue
+        });
+  
+        prevValue = node.value;
+      }
+  
+      return growth;
+    }
+  
+    /**
+     * Gets the largest computed value
+     */
+    public getLargestValue(): bigint {
+      return this.heap.peek() ?? BigInt(0);
+    }
+  
+    /**
+     * Gets a specific Ackermann value if it exists
+     */
+    public getValue(m: number, n: number): bigint | undefined {
+      return this.nodes.get(AckermannStructure.getNodeKey(m, n))?.value;
+    }
+  }
+  
+  export default AckermannStructure;