@cortex-js/compute-engine 0.32.1 → 0.34.0

package/dist/types/compute-engine/global-types.d.ts

@@ -1,4 +1,4 @@
-/* 0.32.1 */
+/* 0.34.0 */
 import type { OneOf } from '../common/one-of';
 import type { Expression, MathJsonNumberObject, MathJsonStringObject, MathJsonFunctionObject, MathJsonSymbolObject, MathJsonSymbol, MathJsonDictionaryObject } from '../math-json';
 import type { Type, TypeReference, TypeResolver, TypeString } from '../common/type/types';
@@ -107,7 +107,7 @@ export interface Tensor<DT extends TensorDataType> extends TensorData<DT> {
     readonly isZero: boolean;
     at(...indices: number[]): DataTypeMap[DT] | undefined;
     diagonal(axis1?: number, axis2?: number): undefined | DataTypeMap[DT][];
-    trace(axis1?: number, axis2?: number): undefined | DataTypeMap[DT];
+    trace(axis1?: number, axis2?: number): undefined | DataTypeMap[DT] | Tensor<DT>;
     reshape(...shape: number[]): Tensor<DT>;
     slice(index: number): Tensor<DT>;
     flatten(): DataTypeMap[DT][];
@@ -506,7 +506,7 @@ export interface BoxedExpression {
      * Compute Engine or it may return a different value each time it is
      * evaluated, even if the state of the Compute Engine is the same.
      *
-     * As an example, the ["Add", 2, 3]` function expression is pure, but
+     * As an example, the `["Add", 2, 3]` function expression is pure, but
      * the `["Random"]` function expression is not pure.
      *
      * For a function expression to be pure, the function itself (its operator)
@@ -615,7 +615,7 @@ export interface BoxedExpression {
      * Return the value of this expression, if a number literal.
      *
      * Note it is possible for `expr.numericValue` to be `null`, and for
-     * `expr.isNotZero` to be true. For example, when a symbol has been
+     * `expr.is(0)` to be false. For example, when a symbol has been
      * defined with an assumption.
      *
      * Conversely, `expr.isNumber` may be true even if `expr.numericValue` is
@@ -1242,6 +1242,30 @@ export interface BoxedExpression {
      *
      */
     simplify(options?: Partial<SimplifyOptions>): BoxedExpression;
+    /**
+     * Apply the Fu algorithm to simplify trigonometric expressions.
+     *
+     * The Fu algorithm is a systematic approach to trigonometric simplification
+     * that uses transformation rules (TR1-TR22), combination transforms (CTR),
+     * and rule lists (RL) to reduce the number of trigonometric functions.
+     *
+     * This is equivalent to calling `simplify({ strategy: 'fu' })` but is
+     * more convenient for trig-heavy expressions.
+     *
+     * Reference: Fu, Hongguang, Xiuqin Zhong, and Zhenbing Zeng.
+     * "Automated and readable simplification of trigonometric expressions."
+     * Mathematical and Computer Modelling 44.11 (2006): 1169-1177.
+     *
+     * @example
+     * ```typescript
+     * ce.parse('\\sin(x)\\cos(x)').trigSimplify()
+     * // => sin(2x)/2
+     *
+     * ce.parse('\\sin^2(x) + \\cos^2(x)').trigSimplify()
+     * // => 1
+     * ```
+     */
+    trigSimplify(): BoxedExpression;
     /**
      * Expand the expression: distribute multiplications over additions,
      * and expand powers.
@@ -1320,9 +1344,25 @@ export interface BoxedExpression {
      * `options.fallback` is set to `false`. If it is set to `false`, the
      * function will throw an error if it cannot be compiled.
      *
+     * **Custom operators**: You can override operators to use function calls
+     * instead of native operators, useful for vector/matrix operations:
+     *
+     * ```javascript
+     * const expr = ce.parse("v + w");
+     * const f = expr.compile({
+     *   operators: {
+     *     Add: ['add', 11],      // Convert + to add()
+     *     Multiply: ['mul', 12]   // Convert * to mul()
+     *   }
+     * });
+     * // Result: add(v, w) instead of v + w
+     * ```
+     *
      */
     compile(options?: {
-        to?: 'javascript' | 'wgsl' | 'python' | 'webassembly';
+        to?: string;
+        target?: any;
+        operators?: Partial<Record<MathJsonSymbol, [op: string, prec: number]>> | ((op: MathJsonSymbol) => [op: string, prec: number] | undefined);
         functions?: Record<MathJsonSymbol, JSSource | ((...any: any[]) => any)>;
         vars?: Record<MathJsonSymbol, JSSource>;
         imports?: ((...any: any[]) => any)[];
@@ -1335,15 +1375,27 @@ export interface BoxedExpression {
      * If this is an equation, solve the equation for the variables in vars.
      * Otherwise, solve the equation `this = 0` for the variables in vars.
      *
+     * For univariate equations, returns an array of solutions (roots).
+     * For systems of linear equations (List of Equal expressions), returns
+     * an object mapping variable names to their values.
+     * For non-linear polynomial systems (like xy=6, x+y=5), returns an array
+     * of solution objects (multiple solutions possible).
      *
      * ```javascript
+     * // Univariate equation
      * const expr = ce.parse("x^2 + 2*x + 1 = 0");
-     * console.log(expr.solve("x"));
-     * ```
+     * console.log(expr.solve("x")); // Returns array of roots
      *
+     * // System of linear equations
+     * const system = ce.parse("\\begin{cases}x+y=70\\\\2x-4y=80\\end{cases}");
+     * console.log(system.solve(["x", "y"])); // Returns { x: 60, y: 10 }
      *
+     * // Non-linear polynomial system (product + sum)
+     * const nonlinear = ce.parse("\\begin{cases}xy=6\\\\x+y=5\\end{cases}");
+     * console.log(nonlinear.solve(["x", "y"])); // Returns [{ x: 2, y: 3 }, { x: 3, y: 2 }]
+     * ```
      */
-    solve(vars?: Iterable<string> | string | BoxedExpression | Iterable<BoxedExpression>): null | ReadonlyArray<BoxedExpression>;
+    solve(vars?: Iterable<string> | string | BoxedExpression | Iterable<BoxedExpression>): null | ReadonlyArray<BoxedExpression> | Record<string, BoxedExpression> | Array<Record<string, BoxedExpression>>;
     /**
      * If this expression is a number literal, a string literal or a function
      *  literal, return the expression.
@@ -1809,7 +1861,194 @@ export type ValueDefinition = BaseDefinition & {
     neq: (a: BoxedExpression) => boolean | undefined;
     cmp: (a: BoxedExpression) => '=' | '>' | '<' | undefined;
     collection: CollectionHandlers;
+    /**
+     * Custom evaluation handler for subscripted expressions of this symbol.
+     * Called when evaluating `Subscript(symbol, index)`.
+     *
+     * @param subscript - The subscript expression (already evaluated)
+     * @param options - Contains the compute engine and evaluation options
+     * @returns The evaluated result, or `undefined` to fall back to symbolic form
+     */
+    subscriptEvaluate?: (subscript: BoxedExpression, options: {
+        engine: ComputeEngine;
+        numericApproximation?: boolean;
+    }) => BoxedExpression | undefined;
 };
+/**
+ * Definition for a sequence declared with `ce.declareSequence()`.
+ *
+ * A sequence is defined by base cases and a recurrence relation.
+ *
+ * @example
+ * ```typescript
+ * // Fibonacci sequence
+ * ce.declareSequence('F', {
+ *   base: { 0: 0, 1: 1 },
+ *   recurrence: 'F_{n-1} + F_{n-2}',
+ * });
+ * ce.parse('F_{10}').evaluate();  // → 55
+ * ```
+ *
+ * @category Definitions
+ */
+export interface SequenceDefinition {
+    /**
+     * Index variable name for single-index sequences, default 'n'.
+     * For multi-index sequences, use `variables` instead.
+     */
+    variable?: string;
+    /**
+     * Index variable names for multi-index sequences.
+     * Example: `['n', 'k']` for Pascal's triangle P_{n,k}
+     *
+     * If provided, this takes precedence over `variable`.
+     */
+    variables?: string[];
+    /**
+     * Base cases as index → value mapping.
+     *
+     * For single-index sequences, use numeric keys:
+     * ```typescript
+     * base: { 0: 0, 1: 1 }  // F_0 = 0, F_1 = 1
+     * ```
+     *
+     * For multi-index sequences, use comma-separated string keys:
+     * ```typescript
+     * base: {
+     *   '0,0': 1,    // Exact: P_{0,0} = 1
+     *   'n,0': 1,    // Pattern: P_{n,0} = 1 for all n
+     *   'n,n': 1,    // Pattern: P_{n,n} = 1 (diagonal)
+     * }
+     * ```
+     *
+     * Pattern keys use variable names to match any value. When the same
+     * variable appears multiple times (e.g., 'n,n'), the indices must be equal.
+     */
+    base: Record<number | string, number | BoxedExpression>;
+    /** Recurrence relation as LaTeX string or BoxedExpression */
+    recurrence: string | BoxedExpression;
+    /** Whether to memoize computed values (default: true) */
+    memoize?: boolean;
+    /**
+     * Valid index domain constraints.
+     *
+     * For single-index sequences:
+     * ```typescript
+     * domain: { min: 0, max: 100 }
+     * ```
+     *
+     * For multi-index sequences, use per-variable constraints:
+     * ```typescript
+     * domain: { n: { min: 0 }, k: { min: 0 } }
+     * ```
+     */
+    domain?: {
+        min?: number;
+        max?: number;
+    } | Record<string, {
+        min?: number;
+        max?: number;
+    }>;
+    /**
+     * Constraint expression for multi-index sequences.
+     * The expression should evaluate to a boolean/numeric value.
+     * If it evaluates to false or 0, the subscript is considered out of domain.
+     *
+     * Example: `'k <= n'` for Pascal's triangle (only valid when k ≤ n)
+     */
+    constraints?: string | BoxedExpression;
+}
+/**
+ * Status of a sequence definition.
+ * @category Definitions
+ */
+export interface SequenceStatus {
+    /**
+     * Status of the sequence:
+     * - 'complete': Both base case(s) and recurrence defined
+     * - 'pending': Waiting for base case(s) or recurrence
+     * - 'not-a-sequence': Symbol is not a sequence
+     */
+    status: 'complete' | 'pending' | 'not-a-sequence';
+    /** Whether at least one base case is defined */
+    hasBase: boolean;
+    /** Whether a recurrence relation is defined */
+    hasRecurrence: boolean;
+    /**
+     * Keys of defined base cases.
+     * For single-index: numeric indices (e.g., [0, 1])
+     * For multi-index: string keys including patterns (e.g., ['0,0', 'n,0', 'n,n'])
+     */
+    baseIndices: (number | string)[];
+    /** Index variable name if recurrence is defined (single-index) */
+    variable?: string;
+    /** Index variable names if recurrence is defined (multi-index) */
+    variables?: string[];
+}
+/**
+ * Information about a defined sequence for introspection.
+ * @category Definitions
+ */
+export interface SequenceInfo {
+    /** The sequence name */
+    name: string;
+    /** Index variable name for single-index sequences (e.g., `"n"`) */
+    variable?: string;
+    /** Index variable names for multi-index sequences (e.g., `["n", "k"]`) */
+    variables?: string[];
+    /**
+     * Base case keys.
+     * For single-index: numeric indices
+     * For multi-index: string keys including patterns
+     */
+    baseIndices: (number | string)[];
+    /** Whether memoization is enabled */
+    memoize: boolean;
+    /**
+     * Domain constraints.
+     * For single-index: `{ min?, max? }`
+     * For multi-index: per-variable constraints
+     */
+    domain: {
+        min?: number;
+        max?: number;
+    } | Record<string, {
+        min?: number;
+        max?: number;
+    }>;
+    /** Number of cached values */
+    cacheSize: number;
+    /** Whether this is a multi-index sequence */
+    isMultiIndex: boolean;
+}
+/**
+ * Result from an OEIS lookup operation.
+ * @category OEIS
+ */
+export interface OEISSequenceInfo {
+    /** OEIS sequence ID (e.g., 'A000045') */
+    id: string;
+    /** Sequence name/description */
+    name: string;
+    /** First several terms of the sequence */
+    terms: number[];
+    /** Formula or recurrence (if available) */
+    formula?: string;
+    /** Comments about the sequence */
+    comments?: string[];
+    /** URL to the OEIS page */
+    url: string;
+}
+/**
+ * Options for OEIS operations.
+ * @category OEIS
+ */
+export interface OEISOptions {
+    /** Request timeout in milliseconds (default: 10000) */
+    timeout?: number;
+    /** Maximum number of results to return for lookups (default: 5) */
+    maxResults?: number;
+}
 /**
  * Definition record for a function.
  * @category Definitions
@@ -2041,6 +2280,21 @@ export type SimplifyOptions = {
      * used.
      */
     costFunction?: (expr: BoxedExpression) => number;
+    /**
+     * The simplification strategy to use.
+     *
+     * - `'default'`: Use standard simplification rules (default)
+     * - `'fu'`: Use the Fu algorithm for trigonometric simplification.
+     *   This is more aggressive for trig expressions and may produce
+     *   different results than the default strategy.
+     *
+     *   **Note:** When using the `'fu'` strategy, the `costFunction` and `rules`
+     *   options are ignored. The Fu algorithm uses its own specialized cost
+     *   function that prioritizes minimizing the number of trigonometric
+     *   functions. Standard simplification is applied before and after the
+     *   Fu transformations using the engine's default rules.
+     */
+    strategy?: 'default' | 'fu';
 };
 /**
  * A table mapping symbols to their definition.
@@ -2277,6 +2531,14 @@ export interface BoxedValueDefinition extends BoxedBaseDefinition {
      */
     inferredType: boolean;
     type: BoxedType;
+    /**
+     * Custom evaluation handler for subscripted expressions of this symbol.
+     * Called when evaluating `Subscript(symbol, index)`.
+     */
+    subscriptEvaluate?: (subscript: BoxedExpression, options: {
+        engine: ComputeEngine;
+        numericApproximation?: boolean;
+    }) => BoxedExpression | undefined;
 }
 /**
  * An operator definition can have some flags to indicate specific
@@ -2577,7 +2839,7 @@ export type RuleSteps = RuleStep[];
  * into a new expression `replace`.
  *
  * - `x-1` \( \to \) `1-x`
- * - `(x+1)(x-1)` \( \to \) `x^2-1
+ * - `(x+1)(x-1)` \( \to \) `x^2-1`
  *
  * The patterns can be expressed as LaTeX strings or `SemiBoxedExpression`'s.
  * Alternatively, match/replace logic may be specified by a `RuleFunction`, allowing both custom
@@ -2757,6 +3019,8 @@ export interface ComputeEngine extends IBigNum {
     readonly context: EvalContext;
     contextStack: ReadonlyArray<EvalContext>;
     /** @internal */
+    readonly isVerifying: boolean;
+    /** @internal */
     readonly _typeResolver: TypeResolver;
     /** Absolute time beyond which evaluation should not proceed
      * @internal
@@ -2890,6 +3154,11 @@ export interface ComputeEngine extends IBigNum {
      * Use `ce.assign(id, value)` instead.
      * @internal */
     _setSymbolValue(id: MathJsonSymbol, value: BoxedExpression | boolean | number | undefined): void;
+    /**
+     * Set a value directly in the current context's values map.
+     * Used for assumptions so values are properly scoped.
+     * @internal */
+    _setCurrentContextValue(id: MathJsonSymbol, value: BoxedExpression | boolean | number | undefined): void;
     /** A list of the function calls to the current evaluation context */
     trace: ReadonlyArray<string>;
     lookupContext(id: MathJsonSymbol): undefined | EvalContext;
@@ -2914,9 +3183,111 @@ export interface ComputeEngine extends IBigNum {
         [id: MathJsonSymbol]: Type | TypeString | Partial<SymbolDefinition>;
     }, arg2?: Type | TypeString | Partial<SymbolDefinition>, arg3?: Scope): ComputeEngine;
     assume(predicate: BoxedExpression): AssumeResult;
+    /**
+     * Declare a sequence with a recurrence relation.
+     *
+     * @example
+     * ```typescript
+     * // Fibonacci sequence
+     * ce.declareSequence('F', {
+     *   base: { 0: 0, 1: 1 },
+     *   recurrence: 'F_{n-1} + F_{n-2}',
+     * });
+     * ce.parse('F_{10}').evaluate();  // → 55
+     * ```
+     */
+    declareSequence(name: string, def: SequenceDefinition): ComputeEngine;
+    /**
+     * Get the status of a sequence definition.
+     *
+     * @example
+     * ```typescript
+     * ce.parse('F_0 := 0').evaluate();
+     * ce.getSequenceStatus('F');
+     * // → { status: 'pending', hasBase: true, hasRecurrence: false, baseIndices: [0] }
+     * ```
+     */
+    getSequenceStatus(name: string): SequenceStatus;
+    /**
+     * Get information about a defined sequence.
+     * Returns `undefined` if the symbol is not a sequence.
+     */
+    getSequence(name: string): SequenceInfo | undefined;
+    /**
+     * List all defined sequences.
+     * Returns an array of sequence names.
+     */
+    listSequences(): string[];
+    /**
+     * Check if a symbol is a defined sequence.
+     */
+    isSequence(name: string): boolean;
+    /**
+     * Clear the memoization cache for a sequence.
+     * If no name is provided, clears caches for all sequences.
+     */
+    clearSequenceCache(name?: string): void;
+    /**
+     * Get the memoization cache for a sequence.
+     * Returns a Map of index → value, or `undefined` if not a sequence or memoization is disabled.
+     *
+     * For single-index sequences, keys are numbers.
+     * For multi-index sequences, keys are comma-separated strings (e.g., '5,2').
+     */
+    getSequenceCache(name: string): Map<number | string, BoxedExpression> | undefined;
+    /**
+     * Generate a list of sequence terms from start to end (inclusive).
+     *
+     * @param name - The sequence name
+     * @param start - Starting index (inclusive)
+     * @param end - Ending index (inclusive)
+     * @param step - Step size (default: 1)
+     * @returns Array of BoxedExpressions, or undefined if not a sequence
+     *
+     * @example
+     * ```typescript
+     * ce.declareSequence('F', { base: { 0: 0, 1: 1 }, recurrence: 'F_{n-1} + F_{n-2}' });
+     * ce.getSequenceTerms('F', 0, 10);
+     * // → [0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55]
+     * ```
+     */
+    getSequenceTerms(name: string, start: number, end: number, step?: number): BoxedExpression[] | undefined;
+    /**
+     * Look up sequences in OEIS by their terms.
+     *
+     * @param terms - Array of sequence terms to search for
+     * @param options - Optional configuration (timeout, maxResults)
+     * @returns Promise resolving to array of matching sequences
+     *
+     * @example
+     * ```typescript
+     * const results = await ce.lookupOEIS([0, 1, 1, 2, 3, 5, 8, 13]);
+     * // → [{ id: 'A000045', name: 'Fibonacci numbers', ... }]
+     * ```
+     */
+    lookupOEIS(terms: (number | BoxedExpression)[], options?: OEISOptions): Promise<OEISSequenceInfo[]>;
+    /**
+     * Check if a defined sequence matches an OEIS sequence.
+     *
+     * @param name - Name of the defined sequence
+     * @param count - Number of terms to check (default: 10)
+     * @param options - Optional configuration
+     * @returns Promise with match results including OEIS matches and generated terms
+     *
+     * @example
+     * ```typescript
+     * ce.declareSequence('F', { base: { 0: 0, 1: 1 }, recurrence: 'F_{n-1} + F_{n-2}' });
+     * const result = await ce.checkSequenceOEIS('F', 10);
+     * // → { matches: [{ id: 'A000045', name: 'Fibonacci numbers', ... }], terms: [0, 1, 1, ...] }
+     * ```
+     */
+    checkSequenceOEIS(name: string, count?: number, options?: OEISOptions): Promise<{
+        matches: OEISSequenceInfo[];
+        terms: number[];
+    }>;
     forget(symbol?: MathJsonSymbol | MathJsonSymbol[]): void;
     ask(pattern: BoxedExpression): BoxedSubstitution[];
-    verify(query: BoxedExpression): boolean;
+    verify(query: BoxedExpression): boolean | undefined;
     /** @internal */
     _shouldContinueExecution(): boolean;
     /** @internal */