@cortex-js/compute-engine 0.8.0 → 0.9.0

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

@@ -1,4 +1,4 @@
-/* 0.8.0 */
+/* 0.9.0 */
  * The most important classes are {@link ComputeEngine} and
  * {@link BoxedExpression}.
  *
@@ -13,6 +13,7 @@ import type { SignalMessage, WarningSignal, WarningSignalHandler } from '../comm
 import type { Expression, MathJsonDictionary, MathJsonFunction, MathJsonNumber, MathJsonString, MathJsonSymbol } from '../math-json/math-json-format';
 import type { NumberFormattingOptions, ParseLatexOptions, SerializeLatexOptions } from './latex-syntax/public';
 export * from './latex-syntax/public';
+export declare type Rational = [number, number] | [Decimal, Decimal];
 /**
  * Metadata that can be associated with a `BoxedExpression`
  */
@@ -23,18 +24,19 @@ export declare type Metadata = {
 /**
  * The numeric evaluation mode:
  *
- * - `"auto"`: use machine number if precision is 15 or less, allow complex numbers.
- * - `"machine"`: 64-bit float, **IEEE 754-2008**, 64-bit float, 52-bit mantissa,
- *    about 15 digits of precision
- * - `"decimal"`: arbitrary precision floating point numbers, as provided by the
- * "decimal.js" library
- * - `"complex"`: complex number represented by two machine numbers, a real and
- * an imaginary part, as provided by the "complex.js" library
- */
-export declare type NumericMode = 'auto' | 'machine' | 'decimal' | 'complex';
-/** Options for `BoxedExpression.simplify()`
- *
+<div class=symbols-table>
+
+| Mode | |
+| :--- | :----- |
+| `"auto"`| Use bignum or complex numbers. |
+| `"machine"` |  **IEEE 754-2008**, 64-bit floating point numbers: 52-bit mantissa, about 15 digits of precision |
+| `"bignum"` | Arbitrary precision floating point numbers, as provided by the "decimal.js" library |
+| `"complex"` | Complex number represented by two machine numbers, a real and an imaginary part, as provided by the "complex.js" library |
+
+</div>
  */
+export declare type NumericMode = 'auto' | 'machine' | 'bignum' | 'complex';
+/** Options for `BoxedExpression.simplify()` */
 export declare type SimplifyOptions = EvaluateOptions & {
     recursive?: boolean;
     rules?: BoxedRuleSet;
@@ -207,7 +209,14 @@ export declare type JsonSerializationOptions = {
      *
      * **Default**: `true`
      */
-    repeatingDecimal: boolean;
+    repeatingDecimals: boolean;
+    /** Number literals are serialized with this precision.
+     * If `"auto"`, the same precision as the compute engine calculations is used
+     * If `"max"`, all available digits are serialized
+     *
+     * **Default**: `"auto"`
+     */
+    precision: 'auto' | 'max' | number;
 };
 /**
  * **Theory of Operations**
@@ -231,7 +240,7 @@ export interface BoxedExpression {
     readonly engine: IComputeEngine;
     /** From `Object.valueOf()`, return a primitive value for the expression.
      *
-     * If the expression is a machine number, or a Decimal or rational that can be
+     * If the expression is a machine number, or bignum or rational that can be
      * converted to a machine number, return a `number`.
      *
      * If the expression is a symbol, return the name of the symbol as a `string`.
@@ -275,6 +284,11 @@ export interface BoxedExpression {
      *
      */
     readonly json: Expression;
+    /**
+     * The scope in which this expression has been defined.
+     * Is null when the expression is not canonical.
+     */
+    readonly scope: RuntimeScope | null;
     /** From `Object.is()`. Equivalent to `BoxedExpression.isSame()`
      *
      * @category Primitive Methods
@@ -427,6 +441,16 @@ export interface BoxedExpression {
      * **Note** applicable to canonical and non-canonical expressions.
      */
     readonly isLiteral: boolean;
+    /**
+     * An exact value is not further transformed when evaluated. To get an
+     * approximate evaluation of an exact value, use `.N()`.
+     *
+     * Non-exact values includes:
+     * - numbers with a fractional part
+     * - complex numbers with a real or imaginary fractional part
+     *
+     */
+    readonly isExact: boolean;
     /** If true, the value of the expression never changes and evaluating it has
      * no side-effects.
      * If false, the value of the expression may change, if the
@@ -447,28 +471,18 @@ export interface BoxedExpression {
     /**
      * Return the canonical form of this expression.
      *
-     * If a function, after putting all the arguments in canonical form, find
-     * a corresponding function definition in the current context.
+     * If this is a function expressin, a definition is associated with the
+     * canonical expression.
      *
-     * Apply the function definition flags:
+     * When determining the canonical form the following function definition
+     * flags are applied:
      * - `associative`: \\( f(a, f(b), c) \longrightarrow f(a, b, c) \\)
      * - `idempotent`: \\( f(f(a)) \longrightarrow f(a) \\)
      * - `involution`: \\( f(f(a)) \longrightarrow a \\)
      * - `commutative`: sort the arguments.
      *
-     * Additionally, some simplifications involving exact computations on
-     * small integers may be performed.
-     *
-     * For example:
-     * - \\( 2 + x + 1 \longrightarrow x + 3 \\)
-     * - \\( \sqrt{4} \longrightarrow 2 \\)
-     * - \\(\frac{4}{10} \longrightarrow \frac{2}{5} \\).
-     *
-     * However, no calculation is performed involving floating point numbers, so
-     * \\( \sqrt(2) \longrightarrow \sqrt(2) \\).
-     *
-     * **Note** applicable to canonical and non-canonical expressions.
-     * Expressions that are already canonical return themselves.
+     * If his expression is already canonical, the value of canonical is
+     * `this`.
      *
      */
     get canonical(): BoxedExpression;
@@ -496,7 +510,9 @@ export interface BoxedExpression {
      * **Note** applicable to canonical and non-canonical expressions.
      *
      */
-    subs(sub: Substitution): BoxedExpression;
+    subs(sub: Substitution, options?: {
+        canonical?: boolean;
+    }): BoxedExpression;
     /**
      * Transform the expression by applying the rules:
      * if the `lhs` of a rule matches, it is replaced by its `rhs`.
@@ -541,7 +557,7 @@ export interface BoxedExpression {
      * **Note** applicable to canonical and non-canonical expressions.
      *
      */
-    match(rhs: BoxedExpression, options?: PatternMatchOption): Substitution | null;
+    match(rhs: BoxedExpression, options?: PatternMatchOptions): BoxedSubstitution | null;
     /**
      * "Not a Number".
      *
@@ -603,94 +619,15 @@ export interface BoxedExpression {
      */
     readonly isComposite: boolean | undefined;
     /**
-     * Return the value of this expression, if stored as a machine
-     * number.
+     * Return the value of this expression, if a number literal.
      *
-     * Note it is possible for `machineValue` to be `null`, and for `isNotZero`
+     * Note it is possible for `numericValue` to be `null`, and for `isNotZero`
      * to be true. For example, when a symbol has been defined with an assumption.
      *
-     * If `machineValue` is not `null`, then `decimalValue`, `rationalValue`
-     * and `complexValue` are `null.
-     *
-     * @category Numeric Expression
-     *
-     */
-    readonly machineValue: number | null;
-    /** If the value of this expression is a rational number, return it.
-     * Otherwise, return `[null, null]`.
-     *
-     * If `rationalValue` is not `[null, null]`, then `machineValue`, `decimalValue`
-     * and `complexValue` are `null.
-     *
-     * @category Numeric Expression
-     *
-     */
-    readonly rationalValue: [numer: number, denom: number] | [null, null];
-    /** If the value of this expression is a `Decimal` number, return it.
-     * Otherwise, return `null`.
-     *
-     * A `Decimal` number is an arbitrarily long floating point number.
-     *
-     * If `decimalValue` is not `null`, then `machineValue`
-     * and `complexValue` are `null` and `rationalValue` is `[null, null]`.
-     *
      * @category Numeric Expression
      *
      */
-    readonly decimalValue: Decimal | null;
-    /** If the value of this expression is a `Complex` number, return it.
-     * Otherwise, return `null`.
-     *
-     * If `complexValue` is not `null`, then `machineValue`, `rationalValue`
-     * and `decimalValue` are `null.
-     *
-     * @category Numeric Expression
-     *
-     *
-     */
-    readonly complexValue: Complex | null;
-    /** Return an approximation of the numeric value of this expression as
-     * a 64-bit floating point number.
-     *
-     * If the value is a machine number, return it exactly.
-     *
-     * If the value is a rational number, return the numerator divided by the
-     * denominator.
-     *
-     * If the value is a Decimal number return an approximation of the decimal
-     * number to a machine number. There might be a loss of precision or a
-     * round to 0 or Infinity, depending on the value.
-     *
-     * If the value of this expression cannot be represented by a float,
-     * return `null`.
-     *
-     * @category Numeric Expression
-     *
-     *
-     */
-    readonly asFloat: number | null;
-    /**
-     * If the value of this expression is an integer with a 'small' absolute
-     * value, return this value. Otherwise, return `null`.
-     *
-     * Some calculations, for example to put in canonical forms, are only
-     * performed if they are safe from overflow. This method makes it easy
-     * to check for this, whether the value is a Decimal or a number.
-     *
-     * By default, "small" is less than 1,000,000.
-     *
-     * @category Numeric Expression
-     *
-     */
-    readonly asSmallInteger: number | null;
-    /**
-     * If the value of this an expression is a small integer or a rational,
-     * return this value. Otherwise, return `[null, null]`.
-     *
-     * @category Numeric Expression
-     *
-     */
-    readonly asRational: [number, number] | [null, null];
+    readonly numericValue: number | Decimal | Complex | Rational | null;
     /**
      * Return the following, depending on the value of this expression:
      *
@@ -864,19 +801,21 @@ export interface BoxedExpression {
      */
     unbind(): void;
     /**
-     * Return a simpler form of this expression.
+     * Return a simpler form of the canonical form of this expression.
      *
-     * The expression is first converted to canonical form. Then a series of
-     * rewriting rules are applied repeatedly, until no rules apply.
+     * A series of rewriting rules are applied repeatedly, until no more rules
+     * apply.
      *
-     * If a custom `simplify` handler is associated with this function definition,
-     * it is invoked.
+     * If a custom `simplify` handler is associated with this function
+     * definition, it is invoked.
      *
      * The values assigned to symbols and the assumptions about symbols may be
      * used, for example `arg.isInteger` or `arg.isPositive`.
      *
-     * No calculations involving floating point numbers are performed but exact
-     * calculations may be performed, for example
+     * No calculations involving decimal numbers (numbers that are not
+     * integers) are performed but exact calculations may be performed,
+     * for example:
+     *
      * \\( \sin(\frac{\pi}{4}) \longrightarrow \frac{\sqrt{2}}{2} \\).
      *
      * The result is in canonical form.
@@ -884,33 +823,37 @@ export interface BoxedExpression {
      */
     simplify(options?: SimplifyOptions): BoxedExpression;
     /**
-     * Return the value of this expression.
-     *
-     * The expression is first converted to canonical form.
+     * Return the value of the canonical form of this expression.
      *
      * A pure expression always return the same value and has no side effects.
-     * If `this.isPure` is `true`, `this.value` and `this.evaluate()` are synonyms.
-     * For an impure expression, `this.value` is undefined.
+     * If `expr.isPure` is `true`, `expr.value` and `expr.evaluate()` are
+     * synonyms.
+     *
+     * For an impure expression, `expr.value` is undefined.
      *
      * Evaluating an impure expression may have some side effects, for
-     * example modifying the `ComputeEngine` environment, such as its set of assumptions.
+     * example modifying the `ComputeEngine` environment, such as its set of
+     * assumptions.
+     *
+     * Only exact calculations are performed, no approximate calculations on
+     * decimal numbers (non-integer numbers). Constants, rational numbers and
+     * square root of rational numbers are preserved.
      *
-     * Only exact calculations are performed, no floating point calculations.
-     * To perform approximate floating point calculations, use `this.N()` instead.
+     * To perform approximate calculations, use `expr.N()` instead.
      *
-     * The result of `this.evaluate()` may be the same as `this.simplify()`.
+     * The result of `expr.evaluate()` may be the same as `expr.simplify()`.
      *
      * The result is in canonical form.
      *
      */
     evaluate(options?: EvaluateOptions): BoxedExpression;
-    /** Return a numeric approximation of this expression.
+    /** Return a numeric approximation of the canonical form of this expression.
      *
-     * The expression is first converted to canonical form.
+     * Any necessary calculations, including on decimal numbers (non-integers),
+     * are performed.
      *
-     * Any necessary calculations, including on floating point numbers,
-     * are performed. The calculations are performed according
-     * to the `numericMode` and `precision` properties of the `ComputeEngine`.
+     * The calculations are performed according to the `numericMode` and
+     * `precision` properties of the `ComputeEngine`.
      *
      * To only perform exact calculations, use `this.evaluate()` instead.
      *
@@ -938,16 +881,6 @@ export interface BoxedExpression {
      *
      */
     set value(value: BoxedExpression | number | undefined);
-    /** An approximation of the value of this expression. Floating-point
-     * operations may be performed.
-     *
-     * Just like `this.value`, it returns `undefined` for expressions that are
-     * not pure.
-     *
-     * **Note**: If non-canonical, return the numeric value of its canonical
-     * counterpart
-     */
-    readonly numericValue: BoxedExpression | undefined;
     /** The domain of the value of this expression.
      *
      * If a function expression, the domain  of the value of the function (the codomain of the function).
@@ -966,7 +899,7 @@ export interface BoxedExpression {
      * **Note**: If non-canonical, does nothing.
      *
      */
-    set domain(domain: BoxedDomain | string);
+    set domain(domain: BoxedExpression | DomainExpression | BoxedDomain);
     /** `true` if the value of this expression is a number.
      *
      * `isExtendedComplex || isNaN` = `isReal || isImaginary || isInfinity || isNaN`
@@ -1064,29 +997,18 @@ export interface BoxedExpression {
  * This is convenient when creating new expressions from portions
  * of an existing `BoxedExpression` while avoiding unboxing and reboxing.
  */
-export declare type SemiBoxedExpression = BoxedExpression | number | Decimal | Complex | MathJsonNumber | MathJsonString | MathJsonSymbol | string | MathJsonFunction | MathJsonDictionary | SemiBoxedExpression[];
-export declare type LambdaExpression = SemiBoxedExpression;
-export declare type BoxedLambdaExpression = BoxedExpression;
-export declare type PatternMatchOption = {
+export declare type SemiBoxedExpression = number | string | Decimal | Complex | MathJsonNumber | MathJsonString | MathJsonSymbol | MathJsonFunction | MathJsonDictionary | SemiBoxedExpression[] | BoxedExpression;
+export declare type PatternMatchOptions = {
+    substitution?: BoxedSubstitution;
     recursive?: boolean;
     numericTolerance?: number;
     exact?: boolean;
 };
 export interface Pattern extends BoxedExpression {
-    /**
-     * If `expr` does not match the pattern, return `null`.
-     *
-     * Otherwise, return a substitution describing the values that the named
-     * wildcard in the pattern should be changed to in order for the pattern to be
-     * equal to the expression. If there are no named wildcards and the expression
-     * matches the pattern, and empty object literal `{}` is returned.
-     */
-    match(expr: BoxedExpression, options?: PatternMatchOption): BoxedSubstitution | null;
     /** If `expr` matches the pattern, return `true`, otherwise `false` */
-    test(expr: BoxedExpression, options?: PatternMatchOption): boolean;
+    test(expr: BoxedExpression, options?: PatternMatchOptions): boolean;
     /** Return the number of exprs that matched the pattern */
-    count(exprs: Iterable<BoxedExpression>, options?: PatternMatchOption): number;
-    subs(sub: Substitution): Pattern;
+    count(exprs: Iterable<BoxedExpression>, options?: PatternMatchOptions): number;
 }
 export interface ExpressionMapInterface<U> {
     has(expr: BoxedExpression): boolean;
@@ -1163,7 +1085,7 @@ export declare type Scope = {
     iterationLimit?: number;
 };
 export declare type RuntimeScope = Scope & {
-    parentScope: RuntimeScope;
+    parentScope?: RuntimeScope;
     symbolTable?: RuntimeSymbolTable;
     assumptions: undefined | ExpressionMapInterface<boolean>;
     /** The location of the call site that created this scope */
@@ -1304,12 +1226,6 @@ export declare type FunctionDefinitionFlags = {
      * and its value is numeric.
      */
     numeric: boolean;
-    /**
-     * When true, evaluating the function create a temporary scope.
-     * This is used for example by the `Lambda` function to keep track of the
-     * inferred domain of its wildcard  `_` arguments
-     */
-    scoped: boolean;
 };
 /**
  *
@@ -1326,76 +1242,89 @@ export declare type FunctionSignature = {
     /**
      * Return the canonical form of the expression with the arguments `args`.
      *
-     * All the arguments that are not subject to a hold are in canonical form.
-     * Any `Nothing` argument has been removed.
+     * The arguments (`args`) may not be in canonical form. If necessary, they
+     * can be put in canonical form.
      *
-     * If the function is associative, idempotent or an involution,
-     * it should handle its arguments accordingly. Notably, if it
-     * is commutative, the arguments should be sorted in canonical order.
+     * This handler should validate the domain and number of the arguments.
+     * If a required argument is missing, it should be indicated with a
+     * `["Error", "'missing"]` expression. If more arguments than expected
+     * are present, this should be indicated with a `unexpected-argument` error.
+     * If the domain of an argument is not compatible, it should be indicated with
+     * a `incompatible-domain` error.
      *
-     * The handler can make transformations based on the value of the arguments
-     * that are literal and either rational numbers (i.e.
-     * `arg.isLiteral && arg.isRational`) or integers (i.e.
-     * `isLiteral && arg.isInteger`).
+     * `["Sequence"]` expressions are not folded and need to be handled
+     *  explicitly.
      *
-     * The handler should not consider the value of the arguments
-     * that are symbols or functions.
+     * If the function is associative, idempotent or an involution,
+     * this handler should account for it. Notably, if it is commutative, the
+     * arguments should be sorted in canonical order.
      *
-     * The handler should not consider any assumptions about any of the
-     * arguments that are symbols or functions i.e. `arg.isZero`,
-     * `arg.isInteger`, etc...
+     * The handler can make transformations based on the value of the arguments
+     * that are exact (i.e. `arg.isExact`).
      *
-     * The handler should not make transformations based on the value of
-     * floating point numbers.
+     * The handler should not consider the value or any assumptions about any
+     * of the arguments that are symbols or functions (i.e. `arg.isZero`,
+     * `arg.isInteger`, etc...) since those may change over time.
      *
      * The result of the handler should be a canonical expression.
      *
+     * If the arguments do not match, they should be replaced with an appropriate
+     * `["Error"]` expression. If the expression cannot be put in canonical form,
+     * the handler should return `null`.
+     *
      */
-    canonical?: (ce: IComputeEngine, args: BoxedExpression[]) => BoxedExpression;
+    canonical?: (ce: IComputeEngine, args: BoxedExpression[]) => BoxedExpression | null;
     /**
      * Rewrite an expression into a simpler form.
      *
      * The arguments are in canonical form and have been simplified.
      *
-     * The handler can use the values assigned to symbols and the assumptions about
-     * symbols, for example with `arg.machineValue`, `arg.isInteger` or
+     * The handler can use the values assigned to symbols and the assumptions
+     * about symbols, for example with `arg.numericValue`, `arg.isInteger` or
      * `arg.isPositive`.
      *
      * Even though a symbol may not have a value, there may be some information
      * about it reflected for example in `this.isZero` or `this.isPrime`.
      *
      * The handler should not perform approximate numeric calculations, such
-     * as calculations involving floating point numbers. Making exact
-     * calculations on integers or rationals is OK. It is recommended, but not
-     * required, that the calculations be limited to `this.smallIntegerValue`
-     * (i.e. numeric representations of the expression as an integer of small
-     * magnitude).
+     * as calculations involving decimal numbers (non-integers). Making exact
+     * calculations on integers or rationals is OK.
      *
      * This handler should not have any side-effects: do not modify
      * the environment of the `ComputeEngine` instance, do not perform I/O,
      * do not do calculations that depend on random values.
      *
-     * If no simplification can be performed due to the values, domains or assumptions
-     * about its arguments, for example, return `undefined`.
+     * If no simplification can be performed due to the values, domains or
+     * assumptions about its arguments, for example, return `undefined`.
      *
      */
     simplify?: (ce: IComputeEngine, args: BoxedExpression[]) => BoxedExpression | undefined;
     /**
-     * Evaluate symbolically an expression.
+     * Evaluate symbolically a function expression.
      *
      * The arguments have been symbolically evaluated, except the arguments to
      * which a `hold` apply.
      *
      * It is not necessary to further simplify or evaluate the arguments.
      *
-     * If the expression cannot be evaluated, due to the values, domains, or
-     * assumptions about its arguments, for example, return `undefined`.
+     * If performing numerical calculations, if all the arguments are exact,
+     * return an exact expression. If any of the arguments is not exact, that is
+     * if it is a literal decimal (non-integer) number, return an approximation.
+     * In this case, the value may be the same as `expr.N()`.
      *
+     * When doing an exact calculation:
+     * - do not reduce rational numbers to decimal (floating point approximation)
+     * - do not down convert bignums to machine numbers
+     * - do not reduce square roots of rational numbers
+     * - do not reduce constants with a `hold` attribute
      *
+     * If the expression cannot be evaluated, due to the values, domains, or
+     * assumptions about its arguments, for example, return `undefined` or
+     * an `["Error"]` expression.
      */
-    evaluate?: LambdaExpression | ((ce: IComputeEngine, args: BoxedExpression[]) => BoxedExpression | undefined);
+    evaluate?: SemiBoxedExpression | ((ce: IComputeEngine, args: BoxedExpression[]) => BoxedExpression | undefined);
     /**
-     * Evaluate numerically an expression.
+     * Evaluate numerically a function expression.
      *
      * The arguments `args` have been simplified and evaluated, numerically
      * if possible, except the arguments to which a `hold` apply.
@@ -1414,19 +1343,22 @@ export declare type FunctionSignature = {
      * evaluation, but a literal argument is out of range or
      * not of the expected type.
      *
-     * Also return `NaN` if the result of the evaluation would be a complex
-     * number, but complex numbers are not allowed (the `engine.numericMode`
-     * is not `complex` or `auto`).
+     * Note that regardless of the current value of `ce.numericMode`, the
+     * arguments may be boxed numbers representing machine numbers, bignum
+     * numbers, complex numbers, rationals or big rationals.
      *
-     * If the `ce.numericMode` is `auto` or `complex`, you may return
-     * a Complex number as a result. Otherwise, if the result is a complex
-     * value, return `NaN`. If Complex are not allowed, none of the arguments
-     * will be complex literals.
+     * Use the value of `ce.numericMode` to determine how to perform
+     * the numeric evaluation.
      *
-     * If the `ce.numericMode` is `decimal` or `auto` and
-     * `this.engine.precision` is > 15, you may return a Decimal number.
-     * Otherwise, return a `machine` number approximation. If Decimal are
-     * not allowed, none of the arguments will be Decimal literal.
+     * If the numeric mode does not allow complex numbers (the
+     * `engine.numericMode` is not `"complex"` or `"auto"`) and the result of
+     * the evaluation would be a complex number, return `NaN` instead.
+     *
+     * If `ce.numericMode` is `"bignum"` or `"auto"` the evaluation should be done
+     * using bignums.
+     *
+     * Otherwise, `ce.numericMode` is `"machine", the evaluation should be
+     * performed using machine numbers.
      *
      * You may perform any necessary computations, including approximate
      * calculations on floating point numbers.
@@ -1437,17 +1369,17 @@ export declare type FunctionSignature = {
      * @experimental
      */
     evalDimension?: (ce: IComputeEngine, args: BoxedExpression[]) => BoxedExpression;
-    /** Return the sign of the function given a list of arguments. */
+    /** Return the sign of the function expression. */
     sgn?: (ce: IComputeEngine, args: BoxedExpression[]) => -1 | 0 | 1 | undefined;
     /** Return a compiled (optimized) expression. */
     compile?: (expr: BoxedExpression) => CompiledExpression;
 };
 export declare type BoxedFunctionSignature = {
     domain: BoxedDomain;
-    codomain?: BoxedDomain | ((ce: IComputeEngine, args: BoxedDomain[]) => BoxedDomain | null);
-    canonical?: (ce: IComputeEngine, args: BoxedExpression[]) => BoxedExpression;
+    codomain?: BoxedDomain | ((ce: IComputeEngine, args: BoxedExpression[]) => BoxedDomain | null);
+    canonical?: (ce: IComputeEngine, args: BoxedExpression[]) => BoxedExpression | null;
     simplify?: (ce: IComputeEngine, args: BoxedExpression[]) => BoxedExpression | undefined;
-    evaluate?: BoxedLambdaExpression | ((ce: IComputeEngine, args: BoxedExpression[]) => BoxedExpression | undefined);
+    evaluate?: BoxedExpression | ((ce: IComputeEngine, args: BoxedExpression[]) => BoxedExpression | undefined);
     N?: (ce: IComputeEngine, args: BoxedExpression[]) => BoxedExpression | undefined;
     evalDimension?: (ce: IComputeEngine, args: BoxedExpression[]) => BoxedExpression;
     sgn?: (ce: IComputeEngine, args: BoxedExpression[]) => -1 | 0 | 1 | undefined;
@@ -1584,8 +1516,6 @@ export interface IComputeEngine {
     /** @internal */
     readonly _ONE: BoxedExpression;
     /** @internal */
-    readonly _TWO: BoxedExpression;
-    /** @internal */
     readonly _HALF: BoxedExpression;
     /** @internal */
     readonly _NEGATIVE_ONE: BoxedExpression;
@@ -1600,19 +1530,19 @@ export interface IComputeEngine {
     /** @internal */
     readonly _COMPLEX_INFINITY: BoxedExpression;
     /** @internal */
-    readonly _DECIMAL_NAN: Decimal;
+    readonly _BIGNUM_NAN: Decimal;
     /** @internal */
-    readonly _DECIMAL_ZERO: Decimal;
+    readonly _BIGNUM_ZERO: Decimal;
     /** @internal */
-    readonly _DECIMAL_ONE: Decimal;
+    readonly _BIGNUM_ONE: Decimal;
     /** @internal */
-    readonly _DECIMAL_TWO: Decimal;
+    readonly _BIGNUM_TWO: Decimal;
     /** @internal */
-    readonly _DECIMAL_HALF: Decimal;
+    readonly _BIGNUM_HALF: Decimal;
     /** @internal */
-    readonly _DECIMAL_PI: Decimal;
+    readonly _BIGNUM_PI: Decimal;
     /** @internal */
-    readonly _DECIMAL_NEGATIVE_ONE: Decimal;
+    readonly _BIGNUM_NEGATIVE_ONE: Decimal;
     /** The current scope */
     context: RuntimeScope | null;
     /** Absolute time beyond which evaluation should not proceed
@@ -1634,7 +1564,7 @@ export interface IComputeEngine {
     chop(n: Complex): Complex | 0;
     chop(n: number | Decimal | Complex): number | Decimal | Complex;
     /** @internal */
-    decimal: (a: Decimal.Value) => Decimal;
+    bignum: (a: Decimal.Value) => Decimal;
     /** @internal */
     complex: (a: number | Complex, b?: number) => Complex;
     set precision(p: number | 'machine');
@@ -1654,17 +1584,23 @@ export interface IComputeEngine {
     defineFunction(def: FunctionDefinition): BoxedFunctionDefinition;
     lookupSymbol(name: string, wikidata?: string, scope?: RuntimeScope): undefined | BoxedSymbolDefinition;
     /** Return `undefined` if no definition exist for this `head` */
-    lookupFunction(head: string, scope?: RuntimeScope): undefined | BoxedFunctionDefinition;
+    lookupFunction(head: string | BoxedExpression, scope?: RuntimeScope | null): undefined | BoxedFunctionDefinition;
     /**
      * Return a boxed expression from the input.
-     *
-     * The result may not be canonical.
      */
-    box(expr: Decimal | Complex | [num: number, denom: number] | SemiBoxedExpression): BoxedExpression;
-    /** Return a canonical boxed number */
-    number(value: number | MathJsonNumber | Decimal | Complex | [num: number, denom: number], metadata?: Metadata): BoxedExpression;
+    box(expr: Decimal | Complex | [num: number, denom: number] | SemiBoxedExpression, options?: {
+        canonical?: boolean;
+    }): BoxedExpression;
+    /** Return a boxed number */
+    number(value: number | string | MathJsonNumber | Decimal | Complex | [num: number, denom: number] | [num: Decimal, denom: Decimal], options?: {
+        metadata?: Metadata;
+        canonical?: boolean;
+    }): BoxedExpression;
     /** Return a canonical boxed symbol */
-    symbol(sym: string, metadata?: Metadata): BoxedExpression;
+    symbol(sym: string, options?: {
+        metadata?: Metadata;
+        canonical?: boolean;
+    }): BoxedExpression;
     /** Return a canonical boxed string */
     string(s: string, metadata?: Metadata): BoxedExpression;
     /** Return a canonical boxed domain.
@@ -1673,8 +1609,6 @@ export interface IComputeEngine {
      *
      */
     domain(domain: SemiBoxedExpression | BoxedDomain | string, metadata?: Metadata): BoxedDomain;
-    /** Return a canonical lambda expression */
-    lambda(expr: SemiBoxedExpression, sig: BoxedDomain): BoxedLambdaExpression;
     /**
      * Return a canonical expression.
      *
@@ -1690,7 +1624,7 @@ export interface IComputeEngine {
      * This is a primitive to create a boxed function. It doesn't perform
      * any checks or normalization on its arguments.
      *
-     * In general, consider using `fn()` or `box()` instead.
+     * In general, consider using `ce.fn()` or `ce.box()` instead.
      *
      * The result is canonical, but the caller has to ensure that all the
      * conditions are met (i.e. `ops` properly normalized and sorted, all
@@ -1702,6 +1636,10 @@ export interface IComputeEngine {
      * The result is canonical.
      */
     error(message: string | [string, ...SemiBoxedExpression[]], where?: SemiBoxedExpression): BoxedExpression;
+    /**
+     * Add a`["Hold"]` wrapper to `expr.
+     */
+    hold(expr: SemiBoxedExpression): BoxedExpression;
     /** Shortcut for `this.fn("Add"...)`.
      *
      * The result is canonical.
@@ -1716,7 +1654,8 @@ export interface IComputeEngine {
      *
      * The result is canonical.
      */
-    power(base: BoxedExpression, exponent: number | [number, number] | BoxedExpression, metadata?: Metadata): BoxedExpression;
+    power(base: BoxedExpression, exponent: number | Rational | BoxedExpression, metadata?: Metadata): BoxedExpression;
+    sqrt(base: BoxedExpression, metadata?: Metadata): any;
     /** Shortcut for `this.fn("Divide", [1, expr])`
      *
      * The result is canonical.
@@ -1750,9 +1689,15 @@ export interface IComputeEngine {
      * The result may not be canonical.
      *
      */
-    parse(s: LatexString | string): BoxedExpression;
-    parse(s: null): null;
-    parse(s: LatexString | string | null): null | BoxedExpression;
+    parse(s: LatexString | string, options?: {
+        canonical?: boolean;
+    }): BoxedExpression;
+    parse(s: null, options?: {
+        canonical?: boolean;
+    }): null;
+    parse(s: LatexString | string | null, options?: {
+        canonical?: boolean;
+    }): null | BoxedExpression;
     /** Serialize a `BoxedExpression` or a `MathJSON` expression to
      * a LaTeX string
      */
@@ -1770,8 +1715,22 @@ export interface IComputeEngine {
     get latexOptions(): NumberFormattingOptions & ParseLatexOptions & SerializeLatexOptions;
     set latexOptions(opts: Partial<NumberFormattingOptions> & Partial<ParseLatexOptions> & Partial<SerializeLatexOptions>);
     /** {@inheritDoc  JsonSerializationOptions} */
-    get jsonSerializationOptions(): JsonSerializationOptions;
+    get jsonSerializationOptions(): Readonly<JsonSerializationOptions>;
     set jsonSerializationOptions(val: Partial<JsonSerializationOptions>);
+    pushScope(options?: {
+        symbolTable?: Readonly<SymbolTable> | Readonly<SymbolTable>[];
+        assumptions?: (LatexString | Expression | BoxedExpression)[];
+        scope?: Partial<Scope>;
+    }): void;
+    popScope(): void;
+    /** Assign a value to an identifier in the current scope */
+    set(identifiers: {
+        [identifier: string]: SemiBoxedExpression;
+    }): void;
+    /** Declare identifiers (specify their domain without necessarily assigning them a value in the current scope*/
+    let(identifiers: {
+        [identifier: string]: SymbolDefinition | FunctionDefinition;
+    }): void;
     /**
      * Add an assumption.
      *
@@ -1793,13 +1752,7 @@ export interface IComputeEngine {
     /** Remove all assumptions about one or more symbols */
     forget(symbol?: string | string[]): void;
     get assumptions(): ExpressionMapInterface<boolean>;
-    ask(pattern: LatexString | SemiBoxedExpression): Substitution[];
-    pushScope(options?: {
-        symbolTable?: Readonly<SymbolTable> | Readonly<SymbolTable>[];
-        assumptions?: (LatexString | Expression | BoxedExpression)[];
-        scope?: Partial<Scope>;
-    }): void;
-    popScope(): void;
+    ask(pattern: LatexString | SemiBoxedExpression): BoxedSubstitution[];
     /**
      * When `condition` is false, signal.
      *