fix: improve numeric robustness

Author: arnog

CHANGELOG.md

@@ -2,6 +2,9 @@
 
 ### Numerics
 
+- **Centralized overflow protection**: Improved robustness of `Rational` and
+  `ExactNumericValue` arithmetic by centralizing overflow checks and automatic
+  promotion to `BigInt`.
 - **\[#287\](https://github.com/cortex-js/compute-engine/issues/287) Improved
   precision for large integer products**: Multiplications and additions of large
   integers that would previously lose precision (exceeding
@@ -10,12 +13,13 @@
 
 ### Evaluation
 
-- **Fixed scope leak**: Ensured that evaluation contexts are correctly popped
-  even when an error or timeout occurs during function evaluation.
-- **Improved numerical evaluation performance**: `Sum`, `Product`, and `Divide`
-  now correctly propagate the `numericApproximation` option to their arguments,
-  significantly speeding up large numerical calculations by avoiding expensive
-  exact rational arithmetic.
+- **Fixed scope leaks**: Ensured that evaluation contexts are correctly popped
+  even when an error or timeout occurs in `BoxedFunction.evaluate()`,
+  `findUnivariateRoots()`, and rule-boxing operations.
+- **Improved numerical evaluation performance**: `Sum`, `Product`, `Divide`,
+  and statistical operators (`Mean`, `Variance`, etc.) now correctly propagate
+  the `numericApproximation` option, significantly speeding up large numerical
+  calculations by avoiding expensive exact arithmetic.
 
 ## 0.50.1 _2026-02-11_
 

benchmarks/numeric-evaluation.ts

@@ -0,0 +1,36 @@
+import { ComputeEngine } from '../src/compute-engine';
+
+const ce = new ComputeEngine();
+
+function benchmark(name: string, fn: () => void, iterations: number = 1) {
+  const start = performance.now();
+  for (let i = 0; i < iterations; i++) {
+    fn();
+  }
+  const end = performance.now();
+  console.log(`${name}: ${((end - start) / iterations).toFixed(2)}ms`);
+}
+
+console.log('--- Numerical Evaluation Benchmarks ---');
+
+// Large Sum
+benchmark('Sum(1/n, 1..10000).N()', () => {
+  ce.box(['Sum', ['Divide', 1, 'n'], ['Tuple', 'n', 1, 10000]]).N();
+}, 5);
+
+// Large Product
+benchmark('Product(1 + 1/n^2, 1..1000).N()', () => {
+  ce.box(['Product', ['Add', 1, ['Divide', 1, ['Power', 'n', 2]]], ['Tuple', 'n', 1, 1000]]).N();
+}, 5);
+
+// Statistical Mean
+const largeListData = Array.from({ length: 10000 }, (_, i) => i);
+const largeList = ce.box(['List', ...largeListData]);
+benchmark('Mean(largeList).N()', () => {
+  ce.box(['Mean', largeList]).N();
+}, 50);
+
+// Integrate
+benchmark('Integrate(x, 0..1).N()', () => {
+  ce.box(['Integrate', 'x', ['Tuple', 'x', 0, 1]]).N();
+}, 5);

src/compute-engine/boxed-expression/rules.ts

@@ -516,67 +516,64 @@ function parseRule(
     ce.pushScope({ parent: systemScope, bindings: new Map() });
   }
 
-  const expr = ce.parse(rule);
+  let expr: Expression;
+  try {
+    expr = ce.parse(rule);
 
-  ce.latexDictionary = previousDictionary;
+    ce.latexDictionary = previousDictionary;
 
-  if (!expr.isValid || expr.operator !== 'Rule') {
-    if (systemScope) {
-      ce.popScope();
+    if (!expr.isValid || expr.operator !== 'Rule') {
+      throw new Error(
+        `Invalid rule "${rule}"\n|   ${dewildcard(expr).toString()}\n|   A rule should be of the form:\n|   <match> -> <replace>; <condition>`
+      );
     }
-    throw new Error(
-      `Invalid rule "${rule}"\n|   ${dewildcard(expr).toString()}\n|   A rule should be of the form:\n|   <match> -> <replace>; <condition>`
-    );
-  }
 
-  if (!isFunction(expr)) {
-    if (systemScope) {
-      ce.popScope();
+    if (!isFunction(expr)) {
+      throw new Error(`Invalid rule "${rule}"`);
     }
-    throw new Error(`Invalid rule "${rule}"`);
-  }
-  const [match_, replace_, condition] = expr.ops;
+    const [match_, replace_, condition] = expr.ops;
 
-  let match = match_;
-  let replace = replace_;
-  if (canonical) {
-    match = match.canonical;
-    replace = replace.canonical;
-  }
-
-  // Pop the clean scope AFTER canonicalization to avoid pollution
-  if (systemScope) {
-    ce.popScope();
-  }
-
-  // Check that all the wildcards in the replace also appear in the match
-  if (!includesWildcards(replace, match))
-    throw new Error(
-      `Invalid rule "${rule}"\n|   The replace expression contains wildcards not present in the match expression`
-    );
+    let match = match_;
+    let replace = replace_;
+    if (canonical) {
+      match = match.canonical;
+      replace = replace.canonical;
+    }
 
-  if (match.isSame(replace)) {
-    throw new Error(
-      `Invalid rule "${rule}"\n|   The match and replace expressions are the same.\n|   This may be because the rule is not necessary due to canonical simplification`
-    );
-  }
+    // Check that all the wildcards in the replace also appear in the match
+    if (!includesWildcards(replace, match))
+      throw new Error(
+        `Invalid rule "${rule}"\n|   The replace expression contains wildcards not present in the match expression`
+      );
 
-  let condFn: undefined | RuleConditionFunction = undefined;
-  if (condition !== undefined) {
-    // Verify that all the wildcards in the condition also appear in the match
-    if (!includesWildcards(condition, match))
+    if (match.isSame(replace)) {
       throw new Error(
-        `Invalid rule "${rule}"\n|   The condition expression contains wildcards not present in the match expression`
+        `Invalid rule "${rule}"\n|   The match and replace expressions are the same.\n|   This may be because the rule is not necessary due to canonical simplification`
       );
+    }
 
-    // Evaluate the condition as a predicate
-    condFn = (sub: BoxedSubstitution): boolean => {
-      const evaluated = condition.subs(sub).canonical.evaluate();
-      return isSymbol(evaluated) && evaluated.symbol === 'True';
-    };
-  }
+    let condFn: undefined | RuleConditionFunction = undefined;
+    if (condition !== undefined) {
+      // Verify that all the wildcards in the condition also appear in the match
+      if (!includesWildcards(condition, match))
+        throw new Error(
+          `Invalid rule "${rule}"\n|   The condition expression contains wildcards not present in the match expression`
+        );
+
+      // Evaluate the condition as a predicate
+      condFn = (sub: BoxedSubstitution): boolean => {
+        const evaluated = condition.subs(sub).canonical.evaluate();
+        return isSymbol(evaluated) && evaluated.symbol === 'True';
+      };
+    }
 
-  return boxRule(ce, { match, replace, condition: condFn, id: rule }, options);
+    return boxRule(ce, { match, replace, condition: condFn, id: rule }, options);
+  } finally {
+    // Pop the clean scope AFTER canonicalization to avoid pollution
+    if (systemScope) {
+      ce.popScope();
+    }
+  }
 }
 
 function boxRule(
@@ -654,15 +651,22 @@ function boxRule(
   } else {
     ce.pushScope();
   }
-  // Match patterns should never be canonicalized - they need to preserve their
-  // structure with wildcards for pattern matching. For example, ['Divide', '_a', '_a']
-  // should remain as a Divide expression, not be simplified to 1.
-  const matchExpr = parseRulePart(ce, match, {
-    canonical: false,
-    autoWildcard: false,
-  });
-  const replaceExpr = parseRulePart(ce, replace, options);
-  ce.popScope();
+
+  let matchExpr: Expression | null;
+  let replaceExpr: Expression | ((...args: any[]) => Expression | null);
+  try {
+    // Match patterns should never be canonicalized - they need to preserve their
+    // structure with wildcards for pattern matching. For example, ['Divide', '_a', '_a']
+    // should remain as a Divide expression, not be simplified to 1.
+    matchExpr = parseRulePart(ce, match, {
+      canonical: false,
+      autoWildcard: false,
+    });
+    replaceExpr =
+      typeof replace === 'function' ? replace : parseRulePart(ce, replace, options);
+  } finally {
+    ce.popScope();
+  }
 
   // Make up an id if none is provided
   if (!id) {
@@ -754,6 +758,7 @@ export function applyRule(
   substitution: BoxedSubstitution,
   options?: Readonly<Partial<ReplaceOptions>>
 ): RuleStep | null {
+  if (!rule) return null;
   let canonical = options?.canonical ?? (expr.isCanonical || expr.isStructural);
 
   let operandsMatched = false;

src/compute-engine/boxed-expression/solve.ts

@@ -1121,9 +1121,12 @@ function solveNestedSqrtEquation(
   ce.pushScope();
   ce.declare(uSymbolName, { type: 'real' });
 
-  const uSolutions = findUnivariateRoots(uEquation, uSymbolName);
-
-  ce.popScope();
+  let uSolutions: ReadonlyArray<Expression>;
+  try {
+    uSolutions = findUnivariateRoots(uEquation, uSymbolName);
+  } finally {
+    ce.popScope();
+  }
 
   if (uSolutions.length === 0) return null;
 
@@ -1211,59 +1214,62 @@ export function findUnivariateRoots(
   // Create a lexical scope for the unknown
   ce.pushScope();
 
-  // Use the declared type of the variable, if any, otherwise assume 'number'
-  const varType = ce.symbol(x).type.type;
-  ce.declare('_x', typeof varType === 'string' ? varType : 'number');
-
-  let result = exprs.flatMap((expr) =>
-    matchAnyRules(
-      expr,
-      rules,
-      { _x: ce.symbol('_x') },
-      { useVariations: true, canonical: true }
-    )
-  );
+  let result: Expression[] = [];
+  try {
+    // Use the declared type of the variable, if any, otherwise assume 'number'
+    const varType = ce.symbol(x).type.type;
+    ce.declare('_x', typeof varType === 'string' ? varType : 'number');
 
-  // If we didn't find a solution yet, try modifying the expression
-  //expr.
-  // Note: @todo we can try different heuristics here:
-  // Collection: reduce the numbers of occurrences of the unknown
-  // Attraction: bring the occurrences of the unknown closer together
-  // Function Swapping: replacing function with ones easier to solve
-  //    - square roots: square both sides
-  //    - logs: exponentiate both sides
-  //    - trig functions: use inverse trig functions
-  // Homogenization: replace a function of the unknown by a new variable,
-  // e.g. exp(x) -> y, then solve for y
-
-  if (result.length === 0) {
-    exprs = exprs.flatMap((expr) => harmonize(expr));
     result = exprs.flatMap((expr) =>
       matchAnyRules(
         expr,
         rules,
-        { _x: ce.symbol(x) },
+        { _x: ce.symbol('_x') },
         { useVariations: true, canonical: true }
       )
     );
-  }
 
-  if (result.length === 0) {
-    exprs = exprs
-      .flatMap((expr) => expand(expr.canonical))
-      .filter((x) => x !== null) as Expression[];
-    exprs = exprs.flatMap((expr) => harmonize(expr));
-    result = exprs.flatMap((expr) =>
-      matchAnyRules(
-        expr,
-        rules,
-        { _x: ce.symbol(x) },
-        { useVariations: true, canonical: true }
-      )
-    );
-  }
+    // If we didn't find a solution yet, try modifying the expression
+    //expr.
+    // Note: @todo we can try different heuristics here:
+    // Collection: reduce the numbers of occurrences of the unknown
+    // Attraction: bring the occurrences of the unknown closer together
+    // Function Swapping: replacing function with ones easier to solve
+    //    - square roots: square both sides
+    //    - logs: exponentiate both sides
+    //    - trig functions: use inverse trig functions
+    // Homogenization: replace a function of the unknown by a new variable,
+    // e.g. exp(x) -> y, then solve for y
+
+    if (result.length === 0) {
+      exprs = exprs.flatMap((expr) => harmonize(expr));
+      result = exprs.flatMap((expr) =>
+        matchAnyRules(
+          expr,
+          rules,
+          { _x: ce.symbol(x) },
+          { useVariations: true, canonical: true }
+        )
+      );
+    }
 
-  ce.popScope(); // End lexical scope for the unknown
+    if (result.length === 0) {
+      exprs = exprs
+        .flatMap((expr) => expand(expr.canonical))
+        .filter((x) => x !== null) as Expression[];
+      exprs = exprs.flatMap((expr) => harmonize(expr));
+      result = exprs.flatMap((expr) =>
+        matchAnyRules(
+          expr,
+          rules,
+          { _x: ce.symbol(x) },
+          { useVariations: true, canonical: true }
+        )
+      );
+    }
+  } finally {
+    ce.popScope();
+  }
 
   // Validate the roots against the ORIGINAL expression (before clearing
   // denominators and harmonization). This filters out extraneous roots that