@cortex-js/compute-engine 0.7.0 → 0.9.0

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

@@ -1,4 +1,4 @@
-/* 0.7.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,584 +240,582 @@ 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 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 rational number, return `[number, number]`.
-     *
      * If the expression is a symbol, return the name of the symbol as a `string`.
      *
      * Otherwise return a LaTeX representation of the expression.
      *
-     * @category Object Methods
+     * @category Primitive Methods
      */
-    valueOf(): number | string | [number, number];
+    valueOf(): number | string | boolean;
     /** From `Object.toString()`, return a LaTeX representation of the expression.
      *
-     * @category Object Methods
+     * Used when coercing a `BoxedExpression` to a `String`.
+     *
+     * @category Primitive Methods
      */
     toString(): string;
-    /** From `Object.toJSON()`, equivalent to `JSON.stringify(this.json)`
-     *
-     * @category Object Methods
+    /** Similar to`expr.valueOf()` but includes a hint.
+     * @category Primitive Methods
      */
-    toJSON(): string;
-    /** From `Object.is()`. Equivalent to `BoxedExpression.isSame()`
+    [Symbol.toPrimitive](hint: 'number' | 'string' | 'default'): number | string | null;
+    /** Used by `JSON.stringify()` to serialize this object to JSON.
      *
-     * @category Object Methods
+     * Method version of `expr.json`.
      *
+     * @category Primitive Methods
      */
-    is(rhs: unknown): boolean;
-    /** @internal */
-    get hash(): number;
-    /** An optional short description of the symbol or function head.
-     *
-     * May include markdown. Each string is a paragraph. */
-    readonly description: string[];
-    /** An optional URL pointing to more information about the symbol or function head */
-    readonly url: string;
-    /** All boxed expressions have a head.
+    toJSON(): Expression;
+    /** If `true`, this expression is in a canonical form.
      *
-     * If not a function this can be `Symbol`, `String`, `Number` or `Dictionary`.
+     * **Note** applicable to canonical and non-canonical expressions.
      *
-     * If the head expression can be represented as a string, it is returned
-     * as a string.
-     */
-    get head(): BoxedExpression | string;
-    /**
-     * If `this.isPure` is `true`, this is a synonym for `this.evaluate()`.
-     * Otherwise, it returns `undefined`.
-     */
-    get value(): BoxedExpression | undefined;
-    /** Only the value of variables can be changed (symbols that are not constants) */
-    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 impure expressions.
-     */
-    get numericValue(): BoxedExpression | undefined;
-    /** 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
-     * value of other expression changes or for other reasons.
-     *
-     * If `this.isPure` is `false`, `this.value` is undefined. Call
-     * `this.evaluate()` to determine the value of the expression instead.
-     *
-     * As an example, the `Random` function is not pure.
      */
-    get isPure(): boolean;
-    /** True if the expression is a free variable, that is a symbol with no value */
-    get isFree(): boolean;
-    /** True if the expression is a constant, that is a symbol with an immutable value */
-    get isConstant(): boolean;
-    /**
-     * If `true`, this expression represents a value that was not calculated
-     * or that does not reference another expression.
-     * This means the expression is either a number, a string or a dictionary.
-     * Functions and symbols are not literals.
-     */
-    get isLiteral(): boolean;
-    /** If `true`, this expression is in a canonical form */
     get isCanonical(): boolean;
     /** For internal use only, set when a canonical expression is created.
      * @internal
      */
     set isCanonical(val: boolean);
-    /** All the subexpressions matching the head */
-    getSubexpressions(head: string): BoxedExpression[];
-    /** All the subexpressions in this expression, recursively */
-    get subexpressions(): BoxedExpression[];
-    /** All the symbols in the expression, recursively */
-    get symbols(): BoxedExpression[];
-    /** All the `["Error"]` subexpressions */
-    get errors(): BoxedExpression[];
-    /** `ops` is the list of arguments of the function, its "tail"
+    /** MathJSON representation of this expression.
      *
-     * @category Function Expression
+     * **Note** applicable to canonical and non-canonical expressions.
      *
      */
-    get ops(): null | BoxedExpression[];
-    /** If this expression is a function, the number of operands, otherwise 0.
-     *
-     * Note that a function can have 0 operands, so to check if this expression
-     * is a function, check if `this.ops !== null` instead.
-     *
-     * @category Function Expression
-     *
+    readonly json: Expression;
+    /**
+     * The scope in which this expression has been defined.
+     * Is null when the expression is not canonical.
      */
-    get nops(): number;
-    /** First operand, i.e.`this.ops[0]`
-     *
-     *
-     * @category Function Expression
+    readonly scope: RuntimeScope | null;
+    /** From `Object.is()`. Equivalent to `BoxedExpression.isSame()`
      *
+     * @category Primitive Methods
      *
      */
-    get op1(): BoxedExpression;
-    /** Second operand, i.e.`this.ops[0]`
-     *
+    is(rhs: unknown): boolean;
+    /** @internal */
+    readonly hash: number;
+    /** LaTeX representation of this expression.
      *
-     * @category Function Expression
+     * The serialization can be customized with `ComputeEngine.latexOptions`
      *
+     * **Note** applicable to canonical and non-canonical expressions.
      *
      */
-    get op2(): BoxedExpression;
-    /** Third operand, i.e. `this.ops[2]`
-     *
-     *
-     * @category Function Expression
-     *
+    get latex(): LatexString;
+    /**
      *
+     * **Note** applicable to canonical and non-canonical expressions.
+     * @internal
      */
-    get op3(): BoxedExpression;
-    /** The keys of the dictionary.
-     *
-     * If this expression not a dictionary, return `null`
+    set latex(val: string);
+    /** If this expression is a symbol, return the name of the symbol as a string.
+     * Otherwise, return `null`.
      *
-     * @category Dictionary Expression
+     * **Note** applicable to canonical and non-canonical expressions.
+  
+    * @category Symbol Expression
      *
      */
-    get keys(): IterableIterator<string> | null;
+    readonly symbol: string | null;
     /**
+     * If this is the `Nothing` symbol, return `true`.
      *
-     * @category Dictionary Expression
+     * **Note** applicable to canonical and non-canonical expressions.
      */
-    get keysCount(): number;
-    /**
-     * If this expression is a dictionary, return the value of the `key` entry.
+    readonly isNothing: boolean;
+    /** If this expression is a string, return the value of the string.
+     * Otherwise, return `null`.
      *
-     * @category Dictionary Expression
+     * **Note** applicable to canonical and non-canonical expressions.
+  
+    * @category String Expression
      *
      */
-    getKey(key: string): BoxedExpression | undefined;
-    /**
-     * If this expression is a dictionary, return true if the dictionary has a
-     * `key` entry.
+    readonly string: string | null;
+    /** All the subexpressions matching the head
      *
-     * @category Dictionary Expression
+     * **Note** applicable to canonical and non-canonical expressions.
      *
      */
-    hasKey(key: string): boolean;
-    /**
-     * Return the value of this number or symbol, if stored as a machine number.
+    getSubexpressions(head: string): BoxedExpression[];
+    /** All the subexpressions in this expression, recursively
      *
-     * Note it is possible for `machineValue` to be `null`, and for `isNotZero` to be true.
-     * For example, when a symbol has been defined with an assumption.
+     * **Note** applicable to canonical and non-canonical expressions.
      *
-     * If `machineValue` is not `null`, then `decimalValue`, `rationalValue`
-     * and `complexValue` are `null.
+     */
+    readonly subexpressions: BoxedExpression[];
+    /** All the symbols in the expression, recursively
      *
-     * @category Numeric Expression
+     * **Note** applicable to canonical and non-canonical expressions.
      *
      */
-    get 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.
+    readonly symbols: BoxedExpression[];
+    /** All the `["Error"]` subexpressions
      *
-     * @category Numeric Expression
+     * **Note** applicable to canonical and non-canonical expressions.
      *
      */
-    get 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.
+    readonly errors: BoxedExpression[];
+    /** All boxed expressions have a head.
      *
-     * If `decimalValue` is not `null`, then `machineValue`
-     * and `complexValue` are `null` and `rationalValue` is `[null, null]`.
+     * If not a function this can be `Symbol`, `String`, `Number` or `Dictionary`.
      *
-     * @category Numeric Expression
+     * If the head expression can be represented as a string, it is returned
+     * as a string.
      *
+     * **Note** applicable to canonical and non-canonical expressions. The head
+     * of a non-canonical expression may be different than the head of its
+     * canonical counterpart. For example the canonical counterpart of `["Divide", 5, 7]` is `["Rational", 5, 5]`.
      */
-    get decimalValue(): Decimal | null;
-    /** If the value of this expression is a `Complex` number, return it.
-     * Otherwise, return `null`.
+    readonly head: BoxedExpression | string;
+    /** The list of arguments of the function, its "tail".
      *
-     * If `complexValue` is not `null`, then `machineValue`, `rationalValue`
-     * and `decimalValue` are `null.
+     * If the expression is not a function, return `null`.
      *
-     * @category Numeric Expression
+     * **Note** applicable to canonical and non-canonical expressions.
      *
+     * @category Function Expression
      *
      */
-    get complexValue(): Complex | null;
-    /** Return an approximation of the numeric value of this expression as
-     * a 64-bit floating point number.
+    readonly ops: null | BoxedExpression[];
+    /** If this expression is a function, the number of operands, otherwise 0.
      *
-     * If the value is a machine number, return it exactly.
+     * Note that a function can have 0 operands, so to check if this expression
+     * is a function, check if `this.ops !== null` instead.
      *
-     * If the value is a rational number, return the numerator divided by the
-     * denominator.
+     * **Note** applicable to canonical and non-canonical expressions.
      *
-     * If the value is a Decimal number that can be represented by a machine
-     * number, return this value. There might be a small loss of precision due
-     * to the limitations of the binary representation of numbers as machine
-     * numbers.
+     * @category Function Expression
      *
-     * If the value of this expression cannot be represented by a float,
-     * return `null`.
+     */
+    readonly nops: number;
+    /** First operand, i.e.`this.ops[0]`
      *
-     * @category Numeric Expression
+     * **Note** applicable to canonical and non-canonical expressions.
+     *
+     * @category Function Expression
      *
      *
      */
-    get asFloat(): number | null;
-    /**
-     * If the value of this expression is an integer with a 'small' absolute value,
-     * return this value. Otherwise, return `null`.
+    readonly op1: BoxedExpression;
+    /** Second operand, i.e.`this.ops[1]`
      *
-     * 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.
+     * **Note** applicable to canonical and non-canonical expressions.
      *
-     * By default, "small" is less than 1,000,000.
+     * @category Function Expression
      *
-     * @category Numeric Expression
      *
      */
-    get asSmallInteger(): number | null;
-    /**
-     * If the value of this an expression is a small integer or a rational,
-     * return this value. Otherwise, return `[null, null`].
+    readonly op2: BoxedExpression;
+    /** Third operand, i.e. `this.ops[2]`
      *
-     * @category Numeric Expression
+     * **Note** applicable to canonical and non-canonical expressions.
      *
-     */
-    get asRational(): [number, number] | [null, null];
-    /**
-     * Return the following, depending on the value of this expression:
+     * @category Function Expression
      *
-     * * `-1` if it is < 0
-     * * `0` if it is = 0
-     * * `+1` if it is > 0
-     * * `undefined` this value may be positive, negative or zero. We don't know
-     *    right now (a symbol with an Integer domain, but no currently assigned
-     *    value, for example)
-     * * `null` this value will never be positive, negative or zero (`NaN`,
-     *     a string or a complex number for example)
      *
-     * Note that complex numbers have no natural ordering,
-     * so if the value is a complex number, `sgn` is either 0, or `null`
+     */
+    readonly op3: BoxedExpression;
+    /** `true` if this expression or any of its subexpressions is an `["Error"]`
+     * expression.
      *
-     * If a symbol, this does take assumptions into account, that is `this.sgn`
-     * will return `1` if `isPositive` is `true`, even if this expression has
-     * no value
+     * **Note** applicable to canonical and non-canonical expressions. For
+     * non-canonical expression, this may indicate a syntax error while parsing
+     * LaTeX. For canonical expression, this may indicate argument domain
+     * mismatch, or missing or unexpected arguments.
      *
-     * @category Numeric Expression
+     * @category Symbol Expression
      *
      */
-    get sgn(): -1 | 0 | 1 | undefined | null;
-    /** If this expression is a symbol, return the name of the symbol as a string.
-     * Otherwise, return `null`.
+    readonly isValid: boolean;
+    /**
+     * If `true`, this expression represents a value that was not calculated
+     * and that does not reference another expression.
      *
-     * @category Symbol Expression
+     * This means the expression is either a number, a string or a dictionary.
+     * Functions and symbols are not literals.
      *
+     * **Note** applicable to canonical and non-canonical expressions.
      */
-    get symbol(): string | null;
+    readonly isLiteral: boolean;
     /**
-     * If this is the `Nothing`, return `true`.
-     */
-    get isNothing(): boolean;
-    /** `true` if this expression or any subexpression is an `["Error"]`
-     * expression.
+     * An exact value is not further transformed when evaluated. To get an
+     * approximate evaluation of an exact value, use `.N()`.
      *
-     * @category Symbol Expression
+     * Non-exact values includes:
+     * - numbers with a fractional part
+     * - complex numbers with a real or imaginary fractional part
      *
      */
-    get isValid(): boolean;
-    /** If this expression is a string, return the value of the string.
-     * Otherwise, return `null`.
+    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
+     * value of other expression changes or for other reasons.
      *
-     * @category String Expression
+     * If `this.isPure` is `false`, `this.value` is undefined. Call
+     * `this.evaluate()` to determine the value of the expression instead.
      *
+     * As an example, the `Random` function is not pure.
+     *
+     * **Note** applicable to canonical and non-canonical expressions.
      */
-    get string(): string | null;
-    /** `true` if the value of this expression is a number.
+    readonly isPure: boolean;
+    /** True if the expression is a free variable, that is a symbol with no value */
+    readonly isFree: boolean;
+    /** True if the expression is a constant, that is a symbol with an immutable value */
+    readonly isConstant: boolean;
+    /**
+     * Return the canonical form of this expression.
      *
-     * `isExtendedComplex || isNaN` = `isReal || isImaginary || isInfinity || isNaN`
+     * If this is a function expressin, a definition is associated with the
+     * canonical expression.
      *
-     * Note that in a fateful twist of cosmic irony, `NaN` ("Not a Number")
-     * **is** a number.
+     * 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.
+     *
+     * If his expression is already canonical, the value of canonical is
+     * `this`.
      *
-     * @category Expression Properties
      */
-    get isNumber(): boolean | undefined;
-    /** The value of this expression is an element of the set ℤ: ...,-2, -1, 0, 1, 2...
+    get canonical(): BoxedExpression;
+    /**
+     * If this expression is a function, apply the function `fn` to all its operands.
      *
+     * Replace the head of this expression with `head`, if defined.
      *
-     * @category Expression Properties
+     * If this expression is a dictionary, return a new dictionary with the values
+     * modified by `fn`.
      *
-     */
-    get isInteger(): boolean | undefined;
-    /** The value of this expression is an element of the set ℚ, p/q with p ∈ ℕ, q ∈ ℤ ⃰  q >= 1
+     * If `head` is provided, return a function expression with the modified
+     * dictionary as operand, otherwise return the  modified dictionary.
      *
-     * Note that every integer is also a rational.
+     * **Note** applicable to canonical and non-canonical expressions.
      *
+     * */
+    apply(fn: (x: BoxedExpression) => SemiBoxedExpression, head?: string): BoxedExpression;
+    /**
+     * Replace all the symbols in the expression as indicated.
      *
-     * @category Expression Properties
+     * Note the same effect can be achieved with `this.replace()`, but
+     * using `this.subs()` is more efficient, and simpler.
+     *
+     * **Note** applicable to canonical and non-canonical expressions.
      *
      */
-    get isRational(): boolean | undefined;
+    subs(sub: Substitution, options?: {
+        canonical?: boolean;
+    }): BoxedExpression;
     /**
-     * The value of this expression is a number that is the root of a non-zero
-     * univariate polynomial with rational coefficients.
+     * Transform the expression by applying the rules:
+     * if the `lhs` of a rule matches, it is replaced by its `rhs`.
      *
-     * All integers and rational numbers are algebraic.
+     * If no rules apply, return `null`.
      *
-     * Transcendental numbers, such as \\( \pi \\) or \\( e \\) are not algebraic.
+     * See also `subs` for a simple substitution.
      *
      *
-     * @category Expression Properties
+     * **Note** applicable to canonical and non-canonical expressions.
      *
      */
-    get isAlgebraic(): boolean | undefined;
+    replace(rules: BoxedRuleSet, options?: ReplaceOptions): null | BoxedExpression;
     /**
-     * The value of this expression is real number: finite and not imaginary.
-     *
-     * `isFinite && !isImaginary`
-     *
+     * True if the expression includes a symbol `v` or a function head `v`.
      *
-     * @category Expression Properties
+     * **Note** applicable to canonical and non-canonical expressions.
      */
-    get isReal(): boolean | undefined;
-    /** Real or ±Infinity
+    has(v: string | string[]): boolean;
+    /** Structural/symbolic equality (weak equality).
      *
-     * `isReal || isInfinity`
+     * `ce.parse('1+x').isSame(ce.parse('x+1'))` is `false`
      *
+     * **Note** applicable to canonical and non-canonical expressions.
      *
-     * @category Expression Properties
+     * @category Relational Operator
      */
-    get isExtendedReal(): boolean | undefined;
-    /**
-     * The value of this expression is a number, but not `NaN` or any Infinity
+    isSame(rhs: BoxedExpression): boolean;
+    /** Attempt to match this expression to the `rhs` expression.
      *
-     * `isReal || isImaginary`
+     * If `rhs` does not match, return `null`.
      *
+     * Otherwise return an object literal.
      *
-     * @category Expression Properties
+     * If this expression includes wildcards (symbols with a name that starts
+     * with `_`), the object literal will include a prop for each matching named
+     * wildcard.
      *
-     */
-    get isComplex(): boolean | undefined;
-    /** `isReal || isImaginary || isInfinity`
+     * If `rhs` matches this pattern but there are no named wildcards, return
+     * the empty object literal, `{}`.
      *
+     * **Note** applicable to canonical and non-canonical expressions.
      *
-     * @category Expression Properties
      */
-    get isExtendedComplex(): boolean | undefined;
-    /** The value of this expression is a number with a imaginary part
+    match(rhs: BoxedExpression, options?: PatternMatchOptions): BoxedSubstitution | null;
+    /**
+     * "Not a Number".
+     *
+     * A value representing undefined result of computations, such as `0/0`,
+     * as per the floating point format standard IEEE-754.
      *
+     * Note that if `isNaN` is true, `isNumber` is also true (yes, `NaN` is a
+     * number).
      *
      * @category Expression Properties
+     *
      */
-    get isImaginary(): boolean | undefined;
+    readonly isNaN: boolean | undefined;
     /**
+     * The numeric value of this expression is 0.
+     *
      * @category Expression Properties
      */
-    get isZero(): boolean | undefined;
+    readonly isZero: boolean | undefined;
     /**
+     * The numeric value of this expression is not 0.
      * @category Expression Properties
      */
-    get isNotZero(): boolean | undefined;
+    readonly isNotZero: boolean | undefined;
     /**
+     * The numeric value of this expression is not 1.
      * @category Expression Properties
      */
-    get isOne(): boolean | undefined;
+    readonly isOne: boolean | undefined;
     /**
+     * The numeric value of this expression is not -1.
      * @category Expression Properties
      */
-    get isNegativeOne(): boolean | undefined;
-    /** ±Infinity or Complex Infinity
-     *
-     * @category Expression Properties
-     */
-    get isInfinity(): boolean | undefined;
-    /**
-     * "Not a Number".
-     *
-     * A value representing undefined result of computations, such as `0/0`,
-     * as per the floating point format standard IEEE-754.
-     *
-     * Note that if `isNaN` is true, `isNumber` is also true (yes, `NaN` is a
-     * number).
+    readonly isNegativeOne: boolean | undefined;
+    /** The numeric value of this expression is ±Infinity or Complex Infinity
      *
      * @category Expression Properties
-     *
      */
-    get isNaN(): boolean | undefined;
+    readonly isInfinity: boolean | undefined;
     /** This expression is a number, but not ±Infinity and not `NaN`
      *
      * @category Expression Properties
      */
-    get isFinite(): boolean | undefined;
+    readonly isFinite: boolean | undefined;
     /**
      * @category Expression Properties
      */
-    get isEven(): boolean | undefined;
+    readonly isEven: boolean | undefined;
     /**
      * @category Expression Properties
      */
-    get isOdd(): boolean | undefined;
+    readonly isOdd: boolean | undefined;
     /**
      * @category Expression Properties
      */
-    get isPrime(): boolean | undefined;
+    readonly isPrime: boolean | undefined;
     /**
      * @category Expression Properties
      */
-    get isComposite(): boolean | undefined;
-    /** Structural/symbolic equality (weak equality).
+    readonly isComposite: boolean | undefined;
+    /**
+     * Return the value of this expression, if a number literal.
      *
-     * `ce.parse('1+x').isSame(ce.parse('x+1'))` is `false`
+     * 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.
+     *
+     * @category Numeric Expression
      *
-     * @category Relational Operator
      */
-    isSame(rhs: BoxedExpression): boolean;
+    readonly numericValue: number | Decimal | Complex | Rational | null;
     /**
-     * True if the expression includes a symbol `v` or a function head `v`.
-     */
-    has(v: string | string[]): boolean;
-    /** Attempt to match this expression to the `rhs` expression.
-     *
-     * If `rhs` does not match, return `null`.
-     *
-     * Otherwise return an object literal.
+     * Return the following, depending on the value of this expression:
      *
-     * If this expression includes wildcards (symbols with a name that starts
-     * with `_`), the object literal will include a prop for each matching named
-     * wildcard.
+     * * `-1` if it is < 0
+     * * `0` if it is = 0
+     * * `+1` if it is > 0
+     * * `undefined` this value may be positive, negative or zero. We don't know
+     *    right now (a symbol with an Integer domain, but no currently assigned
+     *    value, for example)
+     * * `null` this value will never be positive, negative or zero (`NaN`,
+     *     a string or a complex number for example)
      *
-     * If `rhs` matches this pattern but there are no named wildcards, return
-     * the empty object literal, `{}`.
-     */
-    match(rhs: BoxedExpression, options?: PatternMatchOption): Substitution | null;
-    /** Mathematical equality (strong equality), that is the value
-     * of this expression and of `rhs` are numerically equal.
+     * Note that complex numbers have no natural ordering,
+     * so if the value is a complex number, `sgn` is either 0, or `null`
      *
-     * Both expressions are numerically evaluated.
+     * If a symbol, this does take assumptions into account, that is `this.sgn`
+     * will return `1` if `isPositive` is `true`, even if this expression has
+     * no value
      *
-     * Numbers whose difference is less than `engine.tolerance` are
-     * considered equal. This tolerance is set when the `engine.precision` is
-     * changed to be such that the last two digits are ignored.
+     * @category Numeric Expression
      *
-     * @category Relational Operator
      */
-    isEqual(rhs: BoxedExpression): boolean;
+    readonly sgn: -1 | 0 | 1 | undefined | null;
     /** If the expressions cannot be compared, return `undefined`
+     *
+     * The numeric value of both expressions are compared.
      *
      * @category Relational Operator
      */
     isLess(rhs: BoxedExpression): boolean | undefined;
     /**
+     * The numeric value of both expressions are compared.
      * @category Relational Operator
      */
     isLessEqual(rhs: BoxedExpression): boolean | undefined;
     /**
+     * The numeric value of both expressions are compared.
      * @category Relational Operator
      */
     isGreater(rhs: BoxedExpression): boolean | undefined;
     /**
+     * The numeric value of both expressions are compared.
      * @category Relational Operator
      */
     isGreaterEqual(rhs: BoxedExpression): boolean | undefined;
-    /** The value of this expression is > 0, same as `isGreater(0)`
+    /** The numeric value of this expression is > 0, same as `isGreater(0)`
      *
      * @category Expression Properties
      */
-    get isPositive(): boolean | undefined;
-    /** The value of this expression is >= 0, same as `isGreaterEqual(0)`
+    readonly isPositive: boolean | undefined;
+    /** The numeric value of this expression is >= 0, same as `isGreaterEqual(0)`
      *
      * @category Expression Properties
      */
-    get isNonNegative(): boolean | undefined;
-    /** The value of this expression is < 0, same as `isLess(0)`
+    readonly isNonNegative: boolean | undefined;
+    /** The numeric value of this expression is < 0, same as `isLess(0)`
      *
      * @category Expression Properties
      */
-    get isNegative(): boolean | undefined;
-    /** The value of this expression is <= 0, same as `isLessEqual(0)`
+    readonly isNegative: boolean | undefined;
+    /** The numeric value of this expression is <= 0, same as `isLessEqual(0)`
      *
      * @category Expression Properties
      */
-    get isNonPositive(): boolean | undefined;
-    /** Wikidata identifier */
-    get wikidata(): string;
-    set wikidata(val: string);
-    /** MathJSON representation of this expression */
-    get json(): Expression;
-    /** LaTeX representation of this expression */
-    get latex(): LatexString;
-    set latex(val: string);
+    readonly isNonPositive: boolean | undefined;
+    /** The keys of the dictionary.
+     *
+     * If this expression not a dictionary, return `null`
+     *
+     * @category Dictionary Expression
+     *
+     */
+    readonly keys: IterableIterator<string> | null;
+    /**
+     *
+     * @category Dictionary Expression
+     */
+    readonly keysCount: number;
+    /**
+     * If this expression is a dictionary, return the value of the `key` entry.
+     *
+     * @category Dictionary Expression
+     *
+     */
+    getKey(key: string): BoxedExpression | undefined;
+    /**
+     * If this expression is a dictionary, return true if the
+     *  dictionary has a `key` entry.
+     *
+     * @category Dictionary Expression
+     *
+     */
+    hasKey(key: string): boolean;
+    /** Wikidata identifier.
+     *
+     * **Note** `undefined` if not a canonical expression.
+     *
+     *
+     */
+    get wikidata(): string | undefined;
+    set wikidata(val: string | undefined);
+    /** An optional short description if the symbol or function head.
+     *
+     * May include markdown. Each string is a paragraph.
+     *
+     * **Note** `undefined` if not a canonical expression.
+     *
+     */
+    readonly description: undefined | string[];
+    /** An optional URL pointing to more information about the symbol or
+     *  function head
+     *
+     * **Note** `undefined` if not a canonical expression.
+     *
+     */
+    readonly url: string | undefined;
     /** Expressions with a higher complexity score are sorted
      * first in commutative functions
+     *
+     * **Note** `undefined` if not a canonical expression.
      */
-    get complexity(): number;
-    /** The domain of this expression. If a function expression, this the domain
-     * of the value of the function(the codomain of the function), if a symbol
-     * the domain of the value of the symbol.
+    readonly complexity: number | undefined;
+    /**
+     * For symbols and functions, a possible definition associated with the
+     *  expression. `basedDefinition` is the base class of symbol and function
+     *  definition.
+     *
+     * **Note** `undefined` if not a canonical expression.
+     *
      */
-    get domain(): BoxedDomain;
-    /** Symbols that represent a variable (or a function name), can have their
-     *  domain modified */
-    set domain(domain: BoxedDomain | string);
+    readonly basedDefinition: BoxedBaseDefinition | undefined;
     /**
-     * The domain of this expression, without accounting for any inferred domain
-     * or `defaultDomain`. If no domain has been explicitly set via assignment
-     * or via an `.assume()` directive, the `expr.explicitDomain` is `null.
+     * For functions, a possible definition associated with the expression.
      *
-     * This is useful to determine if the domain of an expression is inferred.
+     * **Note** `undefined` if not a canonical expression or not a function.
      *
-     * In most cases you'll want to  use `.domain` instead.
      */
-    get explicitDomain(): BoxedDomain | null;
-    /** For symbols and functions, a possible definition associated with the
-     *  expression. `basedDefinition` is the base class of symbol and function
-     *  definition. */
-    get basedDefinition(): BoxedBaseDefinition | undefined;
-    get functionDefinition(): BoxedFunctionDefinition | undefined;
-    get symbolDefinition(): BoxedSymbolDefinition | undefined;
+    readonly functionDefinition: BoxedFunctionDefinition | undefined;
     /**
-     * Return the canonical form of this expression.
+     * For symbols, a possible definition associated with the expression.
      *
-     * If a function, consider the function definition flags:
-     * - `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.
+     * **Note** `undefined` if not a symbol
      *
-     * Additionally, some simplifications involving exact computations on
-     * small integers may be performed.
+     */
+    readonly symbolDefinition: BoxedSymbolDefinition | undefined;
+    /**
+     * The domain of this expression, without accounting for any inferred domain
+     * or `ce.defaultDomain`. If no domain has been explicitly set via assignment
+     * or via an `.assume()` directive, the `expr.explicitDomain` is `undefined`.
      *
-     * For example:
-     * - \\( 2 + x + 1 \longrightarrow x + 3 \\)
-     * - \\( \sqrt{4} \longrightarrow 2 \\)
-     * - \\(\frac{4}{10} \longrightarrow \frac{2}{5} \\).
+     * This is useful to determine if the domain of an expression is inferred.
+     *
+     * In most cases you'll want to  use `expr.domain` instead.
      *
-     * However, no calculation is performed involving floating point numbers, so
-     * \\( \sqrt(2) \longrightarrow \sqrt(2) \\).
+     * **Note** `undefined` if not a canonical expression or not a function.
      *
-     * Determining the canonical form does not depend on the values assigned to,
-     * or assumptions about, symbols.
      */
-    get canonical(): BoxedExpression;
+    readonly explicitDomain: BoxedDomain | undefined;
+    /**
+     * Update the definition associated with this expression, taking
+     * into account the specified scope.
+     *
+     * **Note**: applicable only to canonical expressions
+     *
+     * @internal
+     */
+    bind(scope: RuntimeScope | null): void;
     /**
-     * Return a simpler 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.
+     * @internal
+     */
+    unbind(): void;
+    /**
+     * Return a simpler form of the canonical form of this expression.
      *
-     * If a custom `simplify` handler is associated with this function definition,
-     * it is invoked.
+     * 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.
      *
      * 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.
@@ -816,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 floating point calculations.
-     * To perform approximate floating point calculations, use `this.N()` instead.
+     * 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.
      *
-     * The result of `this.evaluate()` may be the same as `this.simplify()`.
+     * To perform approximate calculations, use `expr.N()` instead.
+     *
+     * 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.
      *
@@ -854,46 +865,131 @@ export interface BoxedExpression {
     N(options?: NOptions): BoxedExpression;
     solve(vars: Iterable<string>): null | BoxedExpression[];
     /**
-     * If this expression is a function, apply the function `fn` to all its operands.
+     * Synonym for `evaluate()`. If the expression is pure, the value may be
+     * cached.
      *
-     * Replace the head of this expression with `head`, if defined.
+     * It returns `undefined` for expressions that are not pure or that may
+     * not be evaluated.
      *
-     * If this expression is a dictionary, return a new dictionary with the values
-     * modified by `fn`.
+     * **Note**: If non-canonical, return the value of its canonical counterpart
+     */
+    get value(): BoxedExpression | undefined;
+    /** Only the value of variables can be changed (symbols that are not
+     * constants).
      *
-     * If `head` is provided, return a function
-     * with the modified dictionary as operand, otherwise return the
-     * modified dictionary. */
-    apply(fn: (x: BoxedExpression) => SemiBoxedExpression, head?: string): BoxedExpression;
+     * **Note**: If non-canonical, does nothing.
+     *
+     */
+    set value(value: BoxedExpression | number | 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).
+     *
+     * If a symbol the domain of the value of the symbol.
+     *
+     * Use `expr.head` to determine if an expression is a symbol or function.
+     *
+     * **Note**: If non-canonical, return the domain of its canonical
+     * counterpart
+     */
+    get domain(): BoxedDomain;
+    /** Modify the domain of a symbol that represent a variable
+     * (or a function name).
+     *
+     * **Note**: If non-canonical, does nothing.
+     *
+     */
+    set domain(domain: BoxedExpression | DomainExpression | BoxedDomain);
+    /** `true` if the value of this expression is a number.
+     *
+     * `isExtendedComplex || isNaN` = `isReal || isImaginary || isInfinity || isNaN`
+     *
+     * Note that in a fateful twist of cosmic irony, `NaN` ("Not a Number")
+     * **is** a number.
+     *
+     * @category Domain Properties
+     */
+    readonly isNumber: boolean | undefined;
+    /** The value of this expression is an element of the set ℤ: ...,-2, -1, 0, 1, 2...
+     *
+     *
+     * @category Domain Properties
+     *
+     */
+    readonly isInteger: boolean | undefined;
+    /** The value of this expression is an element of the set ℚ, p/q with p ∈ ℕ, q ∈ ℤ ⃰  q >= 1
+     *
+     * Note that every integer is also a rational.
+     *
+     *
+     * @category Domain Properties
+     *
+     */
+    readonly isRational: boolean | undefined;
     /**
-     * Transform the expression by according to the rules:
-     * the matching `lhs` of a rule is replaced by its `rhs`.
+     * The value of this expression is a number that is the root of a non-zero
+     * univariate polynomial with rational coefficients.
      *
-     * If no rules apply, return `null`.
+     * All integers and rational numbers are algebraic.
+     *
+     * Transcendental numbers, such as \\( \pi \\) or \\( e \\) are not algebraic.
+     *
+     *
+     * @category Domain Properties
      *
-     * See also `subs` for a simple substitution.
      */
-    replace(rules: BoxedRuleSet, options?: ReplaceOptions): null | BoxedExpression;
+    readonly isAlgebraic: boolean | undefined;
     /**
-     * Replace all the symbols in the expression as indicated.
+     * The value of this expression is real number: finite and not imaginary.
      *
-     * Note the same effect can be achieved with `this.replace()`, but
-     * using `this.subs()` is more efficient, and simpler.
+     * `isFinite && !isImaginary`
      *
+     *
+     * @category Domain Properties
      */
-    subs(sub: Substitution): BoxedExpression;
+    readonly isReal: boolean | undefined;
+    /** Real or ±Infinity
+     *
+     * `isReal || isInfinity`
+     *
+     *
+     * @category Domain Properties
+     */
+    readonly isExtendedReal: boolean | undefined;
     /**
-     * Update the definition associated with this expression, taking
-     * into account the specified scope.
+     * The value of this expression is a number, but not `NaN` or any Infinity
+     *
+     * `isReal || isImaginary`
+     *
+     *
+     * @category Domain Properties
      *
-     * @internal
      */
-    bind(scope: RuntimeScope | null): void;
-    /** Purge any cached values.
+    readonly isComplex: boolean | undefined;
+    /** `isReal || isImaginary || isInfinity`
      *
-     * @internal
+     *
+     * @category Domain Properties
      */
-    unbind(): void;
+    readonly isExtendedComplex: boolean | undefined;
+    /** The value of this expression is a number with a imaginary part
+     *
+     *
+     * @category Domain Properties
+     */
+    readonly isImaginary: boolean | undefined;
+    /** Mathematical equality (strong equality), that is the value
+     * of this expression and of `rhs` are numerically equal.
+     *
+     * The numeric value of both expressions are compared.
+     *
+     * Numbers whose difference is less than `engine.tolerance` are
+     * considered equal. This tolerance is set when the `engine.precision` is
+     * changed to be such that the last two digits are ignored.
+     *
+     * @category Relational Operator
+     */
+    isEqual(rhs: BoxedExpression): boolean;
 }
 /** A semi boxed expression is an MathJSON expression which can include some
  * boxed terms.
@@ -901,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;
@@ -1000,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 */
@@ -1141,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;
 };
 /**
  *
@@ -1163,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.
@@ -1251,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.
+     *
+     * Use the value of `ce.numericMode` to determine how to perform
+     * the numeric evaluation.
      *
-     * 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.
+     * 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 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 `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.
@@ -1274,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;
@@ -1377,7 +1472,7 @@ export declare type SymbolDefinitionFlags = {
      */
     constant: boolean;
     /**
-     * If false, the value of the symbol is substituted during canonicalization
+     * If `false`, the value of the symbol is substituted during canonicalization
      * or simplification.
      *
      * If true, the value is only replaced during a `ce.N()` or `ce.evaluate()`.
@@ -1421,8 +1516,6 @@ export interface IComputeEngine {
     /** @internal */
     readonly _ONE: BoxedExpression;
     /** @internal */
-    readonly _TWO: BoxedExpression;
-    /** @internal */
     readonly _HALF: BoxedExpression;
     /** @internal */
     readonly _NEGATIVE_ONE: BoxedExpression;
@@ -1437,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
@@ -1471,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');
@@ -1491,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.
@@ -1510,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.
      *
@@ -1527,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
@@ -1539,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.
@@ -1553,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.
@@ -1587,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
      */
@@ -1607,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.
      *
@@ -1630,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.
      *