arch: more free functions

Author: arnog

CHANGELOG.md

@@ -52,15 +52,45 @@ ce.function('Add', [1, 'x'], { form: 'structural' }); // bound, not fully canoni
 ce.box(['Add', 1, 'x'], { form: ['Number', 'Order'] }); // selective passes
 ```
 
+#### New Free Functions: `parse()`, `simplify()`, `evaluate()`, `N()`, `assign()`
+
+Top-level free functions are now available for the most common operations. They
+use a shared `ComputeEngine` instance created on first call, so no setup is
+required.
+
+```ts
+import { parse, simplify, evaluate, N, assign } from '@cortex-js/compute-engine';
+
+simplify('x + x + 1');     // 2x + 1
+evaluate('2^{11} - 1');    // 2047
+N('\\sqrt{2}');             // 1.414213562…
+
+assign('x', 3);
+evaluate('x + 2');          // 5
+```
+
+Except for `parse()` (which only accepts a LaTeX string), each function accepts
+either a LaTeX string or an existing `BoxedExpression`:
+
+```ts
+const expr = parse('x + x + 1');
+simplify(expr);             // same as simplify('x + x + 1')
+```
+
+Use `getDefaultEngine()` to access the shared engine for configuration
+(precision, angular unit, etc.) or to call methods like `forget()`.
+
 #### `compile()` Is Now a Free Function
 
 The `expr.compile()` method has been replaced by a standalone `compile()`
-function with a structured `CompilationResult` return type.
+function with a structured `CompilationResult` return type. It accepts either a
+LaTeX string or a `BoxedExpression`.
 
 ```ts
 import { compile } from '@cortex-js/compute-engine';
 
-const result = compile(ce.parse('x^2 + 1'));
+// From a LaTeX string
+const result = compile('x^2 + 1');
 result.run({ x: 3 });  // 10
 result.code;            // generated source
 result.success;         // true
@@ -79,24 +109,51 @@ Custom compilation targets can be registered and unregistered dynamically via
 while `expandAll()` applies it recursively. Both return `null` if the expression
 cannot be expanded.
 
+Both accept a LaTeX string or a `BoxedExpression`, consistent with the other free
+functions (`simplify`, `evaluate`, `N`).
+
 ```ts
 import { expand, expandAll } from '@cortex-js/compute-engine';
 
+// From a LaTeX string
+expand('(x+1)^2');         // x^2 + 2x + 1
+expandAll('(x+1)(x+2) + (a+b)^2');  // recursive expansion
+
+// From a BoxedExpression
 const expr = ce.parse('(x+1)(x+2)');
 expand(expr);               // x^2 + 3x + 2
-expandAll(complexExpr);     // recursive expansion
 
 // Returns null when not expandable — use ?? for fallback
 const result = expand(expr) ?? expr;
 ```
 
+#### `solve()` Is a Free Function
+
+A new `solve()` free function is available for solving equations without
+explicitly creating a `ComputeEngine` instance. Like the other free functions, it
+accepts either a LaTeX string or a `BoxedExpression`.
+
+```ts
+import { solve } from '@cortex-js/compute-engine';
+
+// Solve from LaTeX
+solve('x^2 - 5x + 6 = 0', 'x');  // [2, 3]
+
+// Solve from a BoxedExpression
+const expr = ce.parse('x^2 - 5x + 6 = 0');
+solve(expr, 'x');                   // [2, 3]
+```
+
 #### `factor()` Is a Free Function
 
-Polynomial factoring functions are now standalone free functions.
+Polynomial factoring functions are now standalone free functions. `factor()`
+accepts a LaTeX string or a `BoxedExpression`. The specialized variants
+(`factorPolynomial`, `factorQuadratic`, etc.) accept only a `BoxedExpression`.
 
 ```ts
 import { factor, factorPolynomial, factorQuadratic } from '@cortex-js/compute-engine';
 
+factor('(2x)(4y)');        // 8xy — from LaTeX
 factor(expr);              // general factoring
 factorPolynomial(expr);    // polynomial-specific
 factorQuadratic(expr);     // quadratic-specific

src/compute-engine.ts

@@ -29,16 +29,18 @@ export { IntervalJavaScriptTarget } from './compute-engine/compilation/interval-
 export { IntervalGLSLTarget } from './compute-engine/compilation/interval-glsl-target';
 export { BaseCompiler } from './compute-engine/compilation/base-compiler';
 
-export { expand } from './compute-engine/boxed-expression/expand';
-export { compile } from './compute-engine/compilation/compile-expression';
-
 // Free functions backed by a lazily-instantiated global engine
 export {
   parse,
   simplify,
   evaluate,
   N,
   assign,
+  expand,
+  expandAll,
+  factor,
+  solve,
+  compile,
   getDefaultEngine,
 } from './compute-engine/free-functions';
 

src/compute-engine/free-functions.ts

@@ -1,5 +1,8 @@
 import type { BoxedExpression, AssignValue, IComputeEngine } from './global-types';
 import type { LatexString } from './latex-syntax/types';
+import { expand as expandExpr, expandAll as expandAllExpr } from './boxed-expression/expand';
+import { factor as factorExpr } from './boxed-expression/factor';
+import { compile as compileExpr } from './compilation/compile-expression';
 
 let _defaultEngine: IComputeEngine | null = null;
 
@@ -47,3 +50,53 @@ export function assign(
 ): void {
   getDefaultEngine().assign(arg1 as any, arg2 as any);
 }
+
+export function expand(
+  latex: LatexString | BoxedExpression
+): BoxedExpression | null {
+  const expr =
+    typeof latex === 'string' ? getDefaultEngine().parse(latex) : latex;
+  return expandExpr(expr);
+}
+
+export function solve(
+  latex: LatexString | BoxedExpression,
+  vars?:
+    | string
+    | Iterable<string>
+    | BoxedExpression
+    | Iterable<BoxedExpression>
+):
+  | null
+  | ReadonlyArray<BoxedExpression>
+  | Record<string, BoxedExpression>
+  | Array<Record<string, BoxedExpression>> {
+  const expr =
+    typeof latex === 'string' ? getDefaultEngine().parse(latex) : latex;
+  return expr.solve(vars);
+}
+
+export function expandAll(
+  latex: LatexString | BoxedExpression
+): BoxedExpression | null {
+  const expr =
+    typeof latex === 'string' ? getDefaultEngine().parse(latex) : latex;
+  return expandAllExpr(expr);
+}
+
+export function factor(
+  latex: LatexString | BoxedExpression
+): BoxedExpression {
+  const expr =
+    typeof latex === 'string' ? getDefaultEngine().parse(latex) : latex;
+  return factorExpr(expr);
+}
+
+export function compile(
+  latex: LatexString | BoxedExpression,
+  options?: Parameters<typeof compileExpr>[1]
+): ReturnType<typeof compileExpr> {
+  const expr =
+    typeof latex === 'string' ? getDefaultEngine().parse(latex) : latex;
+  return compileExpr(expr, options);
+}

src/compute-engine/index.ts

@@ -176,23 +176,24 @@ export {
   evaluate,
   N,
   assign,
+  expand,
+  expandAll,
+  factor,
+  solve,
+  compile,
   getDefaultEngine,
 } from './free-functions';
 
 export { validatePattern };
 
-// Export polynomial factoring functions for advanced users
+// Export specialized polynomial factoring functions for advanced users
 export {
-  factor,
   factorPerfectSquare,
   factorDifferenceOfSquares,
   factorQuadratic,
   factorPolynomial,
 };
 
-// Export expression expansion functions
-export { expand, expandAll } from './boxed-expression/expand';
-
 // Export compilation types and classes for advanced users
 export type {
   CompileTarget,

test/compute-engine/workflow-entrypoints.test.ts

@@ -5,6 +5,11 @@ import {
   evaluate,
   N,
   assign,
+  expand,
+  expandAll,
+  factor,
+  solve,
+  compile,
   getDefaultEngine,
 } from '../../src/compute-engine';
 
@@ -89,4 +94,75 @@ describe('Free Functions', () => {
     // Reset
     getDefaultEngine().forget('w');
   });
+
+  test('expand() expands a LaTeX string', () => {
+    const result = expand('(x+1)^2');
+    expect(result).not.toBeNull();
+    expect(result!.latex).toBe('x^2+2x+1');
+  });
+
+  test('expand() expands a BoxedExpression', () => {
+    const expr = parse('(x+1)(x+2)');
+    const result = expand(expr);
+    expect(result).not.toBeNull();
+    expect(result!.latex).toBe('x^2+3x+2');
+  });
+
+  test('solve() solves from a LaTeX string', () => {
+    const result = solve('x^2 - 5x + 6 = 0', 'x');
+    expect(result).not.toBeNull();
+    expect(Array.isArray(result)).toBe(true);
+    const values = (result as any[]).map((r) => r.valueOf());
+    expect(values).toContain(2);
+    expect(values).toContain(3);
+  });
+
+  test('solve() solves from a BoxedExpression', () => {
+    const expr = parse('x^2 - 5x + 6 = 0');
+    const result = solve(expr, 'x');
+    expect(result).not.toBeNull();
+    expect(Array.isArray(result)).toBe(true);
+    const values = (result as any[]).map((r) => r.valueOf());
+    expect(values).toContain(2);
+    expect(values).toContain(3);
+  });
+
+  test('expandAll() expands from a LaTeX string', () => {
+    const result = expandAll('(x+1)(x+2) + (a+b)^2');
+    expect(result).not.toBeNull();
+  });
+
+  test('expandAll() expands from a BoxedExpression', () => {
+    const expr = parse('(x+1)^2');
+    const result = expandAll(expr);
+    expect(result).not.toBeNull();
+    expect(result!.latex).toBe('x^2+2x+1');
+  });
+
+  test('factor() factors from a LaTeX string', () => {
+    const result = factor('(2x)(4y)');
+    expect(result).toBeDefined();
+    expect(result.latex).toBe('8xy');
+  });
+
+  test('factor() factors from a BoxedExpression', () => {
+    const expr = parse('(2x)(4y)');
+    const result = factor(expr);
+    expect(result).toBeDefined();
+    expect(result.latex).toBe('8xy');
+  });
+
+  test('compile() compiles from a LaTeX string', () => {
+    const result = compile('x^2 + 1');
+    expect(result).toBeDefined();
+    expect(result.success).toBe(true);
+    expect(typeof result.code).toBe('string');
+  });
+
+  test('compile() compiles from a BoxedExpression', () => {
+    const expr = parse('x^2 + 1');
+    const result = compile(expr);
+    expect(result).toBeDefined();
+    expect(result.success).toBe(true);
+  });
 });