@cortex-js/compute-engine 0.23.0 → 0.24.0

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

@@ -1,18 +1,28 @@
-/* 0.23.0 */
+/* 0.24.0 */
 import { Decimal } from 'decimal.js';
 import { Expression, MathJsonNumber } from '../math-json/math-json-format';
 import type { LibraryCategory, LatexDictionaryEntry, LatexString, NumberFormattingOptions, ParseLatexOptions, SerializeLatexOptions } from './latex-syntax/public';
-import { AssumeResult, BoxedExpression, BoxedFunctionDefinition, BoxedSymbolDefinition, IComputeEngine, IdentifierDefinitions, ExpressionMapInterface, NumericMode, Pattern, RuntimeScope, Scope, SemiBoxedExpression, SymbolDefinition, BoxedRuleSet, Rule, JsonSerializationOptions, ComputeEngineStats, Metadata, BoxedDomain, DomainExpression, FunctionDefinition, Rational, BoxedSubstitution, AssignValue, DomainLiteral, ArrayValue, CanonicalForm } from './public';
+import { AssumeResult, BoxedExpression, BoxedFunctionDefinition, BoxedSymbolDefinition, IComputeEngine, IdentifierDefinitions, ExpressionMapInterface, NumericMode, RuntimeScope, Scope, SemiBoxedExpression, SymbolDefinition, BoxedRuleSet, Rule, JsonSerializationOptions, ComputeEngineStats, Metadata, BoxedDomain, DomainExpression, FunctionDefinition, Rational, BoxedSubstitution, AssignValue, DomainLiteral, ArrayValue, CanonicalForm } from './public';
 /**
  *
- * To use the CortexJS Compute Engine, create a `ComputeEngine` instance, or if using a
- * mathfield, use the default Compute Engine instance from the `MathfieldElement` class: `ce = MathfieldElement.computeEngine`.
+ * To use the Compute Engine, create a `ComputeEngine` instance:
  *
- * Use the instance to create boxed expressions with `ce.parse()` and `ce.box()`.
+ * ```js
+ * ce = new ComputeEngine();
+ * ```
  *
+ * If using a mathfield, use the default Compute Engine instance from the
+ * `MathfieldElement` class:
+ *
+ * ```js
+ * ce = MathfieldElement.computeEngine
+ * ```
  *
- * ```ts
+ * Use the instance to create boxed expressions with `ce.parse()` and `ce.box()`.
+ *
+ * ```js
  * const ce = new ComputeEngine();
+ *
  * let expr = ce.parse("e^{i\\pi}");
  * console.log(expr.N().latex);
  * // ➔ "-1"
@@ -21,6 +31,9 @@ import { AssumeResult, BoxedExpression, BoxedFunctionDefinition, BoxedSymbolDefi
  * console.log(expr.evaluate().latex);
  * // ➔ "a^2 +  2ab + b^2"
  * ```
+ *
+ * @category Compute Engine
+ *
  */
 export declare class ComputeEngine implements IComputeEngine {
     readonly Anything: BoxedDomain;
@@ -103,6 +116,8 @@ export declare class ComputeEngine implements IComputeEngine {
     /** In strict mode (the default) the Compute Engine performs
      * validation of domains and signature and may report errors.
      *
+     * These checks may impact performance
+     *
      * When strict mode is off, results may be incorrect or generate JavaScript
      * errors if the input is not valid.
      *
@@ -168,9 +183,11 @@ export declare class ComputeEngine implements IComputeEngine {
     _register(_expr: BoxedExpression): void;
     /** @internal */
     _unregister(_expr: BoxedExpression): void;
+    /** @internal */
     get stats(): ComputeEngineStats;
     /** @internal */
     _bignum: Decimal.Constructor;
+    get precision(): number;
     /** The precision, or number of significant digits, of numeric
      * calculations when the numeric mode is `"auto"` or `"bignum"`.
      *
@@ -182,9 +199,9 @@ export declare class ComputeEngine implements IComputeEngine {
      * Trigonometric operations are accurate for precision up to 1,000.
      *
      */
-    get precision(): number;
     set precision(p: number | 'machine');
     get numericMode(): NumericMode;
+    /** {@inheritDoc  NumericMode} */
     set numericMode(f: NumericMode);
     /** @experimental */
     get timeLimit(): number;
@@ -192,16 +209,16 @@ export declare class ComputeEngine implements IComputeEngine {
     get iterationLimit(): number;
     /** @experimental */
     get recursionLimit(): number;
+    get tolerance(): number;
     /**
      * Values smaller than the tolerance are considered to be zero for the
      * purpose of comparison, i.e. if `|b - a| <= tolerance`, `b` is considered
      * equal to `a`.
      */
-    get tolerance(): number;
     set tolerance(val: number);
     /** Replace a number that is close to 0 with the exact integer 0.
      *
-     * How close to 0 the number has to be to be considered 0 is determined by {@link tolerance}.
+     * How close to 0 the number has to be to be considered 0 is determined by {@linkcode tolerance}.
      */
     chop(n: number): number;
     chop(n: Decimal): Decimal | 0;
@@ -305,10 +322,14 @@ export declare class ComputeEngine implements IComputeEngine {
     complex(a: number | Decimal | Complex, b?: number | Decimal): Complex;
     isBignum(a: unknown): a is Decimal;
     isComplex(a: unknown): a is Complex;
+    /** @internal */
     private get latexSyntax();
     static getLatexDictionary(domain?: LibraryCategory | 'all'): readonly Readonly<object>[];
-    set costFunction(fn: ((expr: BoxedExpression) => number) | undefined);
+    /**
+     * The cost function is used to determine the "cost" of an expression. For example, when simplifying an expression, the simplification that results in the lowest cost is chosen.
+     */
     get costFunction(): (expr: BoxedExpression) => number;
+    set costFunction(fn: ((expr: BoxedExpression) => number) | undefined);
     /**
      * Return a matching symbol definition, starting with the current
      * scope and going up the scope chain. Prioritize finding a match by
@@ -432,9 +453,10 @@ export declare class ComputeEngine implements IComputeEngine {
     checkContinueExecution(): void;
     /** @internal */
     cache<T>(cacheName: string, build: () => T, purge: (T: any) => T | undefined): T;
+    /** Return a canonical version of an array of semi-boxed-expressions. */
     canonical(xs: SemiBoxedExpression[]): BoxedExpression[];
-    /**
-     * Return a boxed expression from the input.
+    /** Return a boxed expression from a number, string or semiboxed expression.
+     * Calls `function()`, `number()` or `symbol()` as appropriate.
      */
     box(expr: Decimal | Complex | [num: number, denom: number] | SemiBoxedExpression, options?: {
         canonical?: boolean | CanonicalForm | CanonicalForm[];
@@ -530,7 +552,6 @@ export declare class ComputeEngine implements IComputeEngine {
         metadata?: Metadata;
     }): BoxedExpression;
     rules(rules: Rule[]): BoxedRuleSet;
-    pattern(expr: LatexString | SemiBoxedExpression): Pattern;
     /**
      * Return a function expression, but the caller is responsible for making
      * sure that the arguments are canonical.
@@ -558,19 +579,16 @@ export declare class ComputeEngine implements IComputeEngine {
     serialize(x: Expression | BoxedExpression, options?: {
         canonical?: boolean;
     }): string;
+    get latexOptions(): NumberFormattingOptions & ParseLatexOptions & SerializeLatexOptions;
     /**
      * Options to control the serialization of MathJSON expression to LaTeX
-     * when using `this.latex` or `this.engine.serialize()`.
-     *
-     *
-     * {@inheritDoc  NumberFormattingOptions}
-     * {@inheritDoc  ParseLatexOptions}
-     * {@inheritDoc  SerializeLatexOptions}
+     * when using `expr.latex` or `ce.serialize()`.
      *
      */
-    get latexOptions(): NumberFormattingOptions & ParseLatexOptions & SerializeLatexOptions;
+    /** {@inheritDoc  NumberFormattingOptions} */
+    /** {@inheritDoc  ParseLatexOptions} */
+    /** {@inheritDoc  SerializeLatexOptions} */
     set latexOptions(opts: Partial<NumberFormattingOptions> & Partial<ParseLatexOptions> & Partial<SerializeLatexOptions>);
-    /** {@inheritDoc  JsonSerializationOptions} */
     get jsonSerializationOptions(): Readonly<JsonSerializationOptions>;
     set jsonSerializationOptions(val: Partial<JsonSerializationOptions>);
     rawJson(expr: BoxedExpression): Expression;
@@ -594,8 +612,6 @@ export declare class ComputeEngine implements IComputeEngine {
      *
      * Note that the assumption is put into canonical form before being added.
      *
-     * @param symbol - The symbol to make an assumption about
-     *
      * Returns:
      * - `contradiction` if the new assumption is incompatible with previous
      * ones.

package/dist/types/compute-engine/cost-function.d.ts

@@ -1,3 +1,3 @@
-/* 0.23.0 */
+/* 0.24.0 */
 export declare function costFunction(expr: BoxedExpression): number;
 export declare const DEFAULT_COST_FUNCTION: typeof costFunction;

package/dist/types/compute-engine/domain-utils.d.ts

@@ -1,4 +1,4 @@
-/* 0.23.0 */
+/* 0.24.0 */
 import { Decimal } from 'decimal.js';
 import { BoxedDomain, BoxedFunctionSignature, DomainLiteral, FunctionSignature, IComputeEngine, Rational } from './public';
 /**

package/dist/types/compute-engine/function-utils.d.ts

@@ -1,6 +1,6 @@
-/* 0.23.0 */
+/* 0.24.0 */
 /***
- * ## THEORY OF OPERATIONS
+ * ### THEORY OF OPERATIONS
  *
  * A `["Function"]` expression has its own scope.
  * This scope includes the parameters and local variables.
@@ -15,7 +15,7 @@
  * be a number, a symbol or (more commonly) an function expression.
  *
  *
- * ### DURING BOXING (in makeLambda())
+ * #### DURING BOXING (in makeLambda())
  *
  * During the boxing/canonicalization phase of a function
  * (`["Function"]` expression or head expression):
@@ -28,7 +28,7 @@
  *    is associated with the function
  *
  *
- * ### DURING EVALUATION (executing the result of makeLambda())
+ * #### DURING EVALUATION (executing the result of makeLambda())
  *
  * 1/ The arguments are evaluated in the current scope
  * 2/ The context is swapped to the function scope

package/dist/types/compute-engine/latex-syntax/dictionary/definitions-algebra.d.ts

@@ -1,2 +1,2 @@
-/* 0.23.0 */
+/* 0.24.0 */
 export declare const DEFINITIONS_ALGEBRA: LatexDictionary;

package/dist/types/compute-engine/latex-syntax/dictionary/definitions-arithmetic.d.ts

@@ -1,2 +1,2 @@
-/* 0.23.0 */
+/* 0.24.0 */
 export declare const DEFINITIONS_ARITHMETIC: LatexDictionary;

package/dist/types/compute-engine/latex-syntax/dictionary/definitions-calculus.d.ts

@@ -1,2 +1,2 @@
-/* 0.23.0 */
+/* 0.24.0 */
 export declare const DEFINITIONS_CALCULUS: LatexDictionary;

package/dist/types/compute-engine/latex-syntax/dictionary/definitions-complex.d.ts

@@ -1,2 +1,2 @@
-/* 0.23.0 */
+/* 0.24.0 */
 export declare const DEFINITIONS_COMPLEX: LatexDictionary;

package/dist/types/compute-engine/latex-syntax/dictionary/definitions-core.d.ts

@@ -1,4 +1,4 @@
-/* 0.23.0 */
+/* 0.24.0 */
 export declare const DEFINITIONS_CORE: LatexDictionary;
 export declare const DELIMITERS_SHORTHAND: {
     '(': string;

package/dist/types/compute-engine/latex-syntax/dictionary/definitions-linear-algebra.d.ts

@@ -1,2 +1,2 @@
-/* 0.23.0 */
+/* 0.24.0 */
 export declare const DEFINITIONS_LINEAR_ALGEBRA: LatexDictionary;

package/dist/types/compute-engine/latex-syntax/dictionary/definitions-logic.d.ts

@@ -1,2 +1,2 @@
-/* 0.23.0 */
+/* 0.24.0 */
 export declare const DEFINITIONS_LOGIC: LatexDictionary;

package/dist/types/compute-engine/latex-syntax/dictionary/definitions-other.d.ts

@@ -1,2 +1,2 @@
-/* 0.23.0 */
+/* 0.24.0 */
 export declare const DEFINITIONS_OTHERS: LatexDictionary;

package/dist/types/compute-engine/latex-syntax/dictionary/definitions-relational-operators.d.ts

@@ -1,4 +1,4 @@
-/* 0.23.0 */
+/* 0.24.0 */
 import { LatexDictionaryEntry } from '../public';
 export declare const DEFINITIONS_INEQUALITIES: LatexDictionaryEntry[];
 export declare function isRelationalOperator(name: BoxedExpression | string): boolean;

package/dist/types/compute-engine/latex-syntax/dictionary/definitions-sets.d.ts

@@ -1,2 +1,2 @@
-/* 0.23.0 */
+/* 0.24.0 */
 export declare const DEFINITIONS_SETS: LatexDictionary;

package/dist/types/compute-engine/latex-syntax/dictionary/definitions-statistics.d.ts

@@ -1,2 +1,2 @@
-/* 0.23.0 */
+/* 0.24.0 */
 export declare const DEFINITIONS_STATISTICS: LatexDictionary;

package/dist/types/compute-engine/latex-syntax/dictionary/definitions-symbols.d.ts

@@ -1,3 +1,3 @@
-/* 0.23.0 */
+/* 0.24.0 */
 export declare const SYMBOLS: [string, string, number][];
 export declare const DEFINITIONS_SYMBOLS: LatexDictionary;

package/dist/types/compute-engine/latex-syntax/dictionary/definitions-trigonometry.d.ts

@@ -1,2 +1,2 @@
-/* 0.23.0 */
+/* 0.24.0 */
 export declare const DEFINITIONS_TRIGONOMETRY: LatexDictionary;

package/dist/types/compute-engine/latex-syntax/dictionary/definitions.d.ts

@@ -1,4 +1,4 @@
-/* 0.23.0 */
+/* 0.24.0 */
 import { WarningSignal } from '../../../common/signals';
 export type CommonEntry = {
     /** Note: a name is required if a serialize handler is provided */

package/dist/types/compute-engine/latex-syntax/latex-syntax.d.ts

@@ -1,4 +1,4 @@
-/* 0.23.0 */
+/* 0.24.0 */
 import { Serializer } from './serializer';
 import { Expression } from '../../math-json/math-json-format';
 import { WarningSignalHandler } from '../../common/signals';

package/dist/types/compute-engine/latex-syntax/parse-identifier.d.ts

@@ -1,4 +1,4 @@
-/* 0.23.0 */
+/* 0.24.0 */
 import { Parser } from './public';
 /** For error handling, if we have a identifier prefix, assume
  * the identifier is invalid (it would have been captured by

package/dist/types/compute-engine/latex-syntax/parse.d.ts

@@ -1,4 +1,4 @@
-/* 0.23.0 */
+/* 0.24.0 */
 import { IndexedLatexDictionary, IndexedLatexDictionaryEntry, IndexedInfixEntry, IndexedPostfixEntry, IndexedPrefixEntry, IndexedSymbolEntry, IndexedExpressionEntry, IndexedFunctionEntry } from './dictionary/definitions';
 import { IComputeEngine } from '../public';
 import { Expression } from '../../math-json/math-json-format';
@@ -7,7 +7,9 @@ export declare const DEFAULT_PARSE_LATEX_OPTIONS: ParseLatexOptions;
 export declare class _Parser implements Parser {
     readonly computeEngine: IComputeEngine;
     readonly options: NumberFormattingOptions & ParseLatexOptions;
-    index: number;
+    _index: number;
+    get index(): number;
+    set index(val: number);
     private _tokens;
     private _positiveInfinityTokens;
     private _negativeInfinityTokens;
@@ -135,7 +137,7 @@ export declare class _Parser implements Parser {
      * Parse a number, with an optional sign, exponent, decimal marker,
      * repeating decimals, etc...
      */
-    private parseNumber;
+    parseNumber(): Expression | null;
     /**
      * A Latex number can be a decimal, hex or octal number.
      * It is used in some Latex commands, such as `\char`