@cortex-js/compute-engine 0.29.0 → 0.30.0

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

@@ -1,12 +1,13 @@
-/* 0.29.0 */
+/* 0.30.0 */
 import type { OneOf } from '../common/one-of';
-import type { Expression, MathJsonNumber, MathJsonString, MathJsonSymbol, MathJsonFunction, MathJsonIdentifier } from '../math-json';
-import { LatexDictionaryEntry, LatexString, ParseLatexOptions, SerializeLatexOptions } from './latex-syntax/types';
-import { ExactNumericValueData, NumericValue, NumericValueData } from './numeric-value/types';
-import { BigNum, IBigNum, Rational } from './numerics/types';
-import { Type, TypeString } from '../common/type/types';
-import { BoxedType } from '../common/type/boxed-type';
-import { IndexedLatexDictionary } from './latex-syntax/dictionary/definitions';
+import type { Expression, MathJsonNumberObject, MathJsonStringObject, MathJsonFunctionObject, MathJsonSymbolObject, MathJsonSymbol, MathJsonDictionaryObject } from '../math-json';
+import type { Type, TypeReference, TypeResolver, TypeString } from '../common/type/types';
+import type { BoxedType } from '../common/type/boxed-type';
+import type { ConfigurationChangeListener } from '../common/configuration-change';
+import type { ExactNumericValueData, NumericValue, NumericValueData } from './numeric-value/types';
+import type { BigNum, IBigNum, Rational } from './numerics/types';
+import type { LatexDictionaryEntry, LatexString, ParseLatexOptions, SerializeLatexOptions } from './latex-syntax/types';
+import type { IndexedLatexDictionary } from './latex-syntax/dictionary/definitions';
 /** @category Compiling */
 export type CompiledType = boolean | number | string | object;
 /** @category Compiling */
@@ -17,7 +18,10 @@ export type CompiledExpression = {
         [symbol: string]: BoxedExpression;
     }) => number | BoxedExpression;
 };
-/** @category Tensors */
+/**
+ * Map of `TensorDataType` to JavaScript type.
+ *
+ * @category Tensors */
 export type DataTypeMap = {
     float64: number;
     float32: number;
@@ -26,199 +30,373 @@ export type DataTypeMap = {
     complex128: Complex;
     complex64: Complex;
     bool: boolean;
-    string: string;
     expression: BoxedExpression;
 };
-/** @category Tensors */
+/**
+ * The type of the cells in a tensor.
+ * @category Tensors */
 export type TensorDataType = keyof DataTypeMap;
+/** @internal */
+export type NestedArray<T> = NestedArray_<T>[];
+/** @internal */
+export type NestedArray_<T> = T | NestedArray_<T>[];
+/**
+ * A record representing the type, shape and data of a tensor.
+ * @category Tensors */
+export interface TensorData<DT extends TensorDataType> {
+    dtype: DT;
+    shape: number[];
+    rank?: number;
+    data: DataTypeMap[DT][];
+}
 /** @category Tensors */
-export interface TensorData<DT extends keyof DataTypeMap = 'float64'> {
+export interface TensorField<T extends number | Complex | BoxedExpression | boolean | string = number> {
+    readonly one: T;
+    readonly zero: T;
+    readonly nan: T;
+    cast(x: T, dtype: 'float64'): undefined | number;
+    cast(x: T, dtype: 'float32'): undefined | number;
+    cast(x: T, dtype: 'int32'): undefined | number;
+    cast(x: T, dtype: 'uint8'): undefined | number;
+    cast(x: T, dtype: 'complex128'): undefined | Complex;
+    cast(x: T, dtype: 'complex64'): undefined | Complex;
+    cast(x: T, dtype: 'bool'): undefined | boolean;
+    cast(x: T, dtype: 'expression'): undefined | BoxedExpression;
+    cast(x: T[], dtype: 'float64'): undefined | number[];
+    cast(x: T[], dtype: 'float32'): undefined | number[];
+    cast(x: T[], dtype: 'int32'): undefined | number[];
+    cast(x: T[], dtype: 'uint8'): undefined | number[];
+    cast(x: T[], dtype: 'complex128'): undefined | Complex[];
+    cast(x: T[], dtype: 'complex64'): undefined | Complex[];
+    cast(x: T[], dtype: 'bool'): undefined | boolean[];
+    cast(x: T[], dtype: 'expression'): undefined | BoxedExpression[];
+    cast(x: T | T[], dtype: TensorDataType): undefined | Complex | number | boolean | BoxedExpression | Complex[] | number[] | boolean[] | BoxedExpression[];
+    expression(x: T): BoxedExpression;
+    isZero(x: T): boolean;
+    isOne(x: T): boolean;
+    equals(lhs: T, rhs: T): boolean;
+    add(lhs: T, rhs: T): T;
+    addn(...xs: T[]): T;
+    neg(x: T): T;
+    sub(lhs: T, rhs: T): T;
+    mul(lhs: T, rhs: T): T;
+    muln(...xs: T[]): T;
+    div(lhs: T, rhs: T): T;
+    pow(rhs: T, n: number): T;
+    conjugate(x: T): T;
+}
+/**
+ * @category Tensors
+ */
+export interface Tensor<DT extends TensorDataType> extends TensorData<DT> {
     dtype: DT;
     shape: number[];
     rank: number;
     data: DataTypeMap[DT][];
+    readonly field: TensorField<DT>;
+    readonly expression: BoxedExpression;
+    readonly array: NestedArray<DataTypeMap[DT]>;
+    readonly isSquare: boolean;
+    readonly isSymmetric: boolean;
+    readonly isSkewSymmetric: boolean;
+    readonly isDiagonal: boolean;
+    readonly isUpperTriangular: boolean;
+    readonly isLowerTriangular: boolean;
+    readonly isTriangular: boolean;
+    readonly isIdentity: boolean;
+    readonly isZero: boolean;
+    at(...indices: number[]): DataTypeMap[DT] | undefined;
+    diagonal(axis1?: number, axis2?: number): undefined | DataTypeMap[DT][];
+    trace(axis1?: number, axis2?: number): undefined | DataTypeMap[DT];
+    reshape(...shape: number[]): Tensor<DT>;
+    slice(index: number): Tensor<DT>;
+    flatten(): DataTypeMap[DT][];
+    upcast<DT extends TensorDataType>(dtype: DT): Tensor<DT>;
+    transpose(axis1?: number, axis2?: number): undefined | Tensor<DT>;
+    conjugateTranspose(axis1?: number, axis2?: number): undefined | Tensor<DT>;
+    determinant(): undefined | DataTypeMap[DT];
+    inverse(): undefined | Tensor<DT>;
+    pseudoInverse(): undefined | Tensor<DT>;
+    adjugateMatrix(): undefined | Tensor<DT>;
+    minor(axis1: number, axis2: number): undefined | DataTypeMap[DT];
+    map1(fn: (lhs: DataTypeMap[DT], rhs: DataTypeMap[DT]) => DataTypeMap[DT], scalar: DataTypeMap[DT]): Tensor<DT>;
+    map2(fn: (lhs: DataTypeMap[DT], rhs: DataTypeMap[DT]) => DataTypeMap[DT], rhs: Tensor<DT>): Tensor<DT>;
+    add(other: Tensor<DT> | DataTypeMap[DT]): Tensor<DT>;
+    subtract(other: Tensor<DT> | DataTypeMap[DT]): Tensor<DT>;
+    multiply(other: Tensor<DT> | DataTypeMap[DT]): Tensor<DT>;
+    divide(other: Tensor<DT> | DataTypeMap[DT]): Tensor<DT>;
+    power(other: Tensor<DT> | DataTypeMap[DT]): Tensor<DT>;
+    equals(other: Tensor<DT>): boolean;
 }
 /**
  * :::info[THEORY OF OPERATIONS]
  *
  * The `BoxedExpression` interface includes the methods and properties
- * applicable to any kind of expression, for example `expr.symbol` or
- * `expr.ops`.
+ * applicable to all kinds of expression. For example it includes `expr.symbol`
+ * which only applies to symbols or `expr.ops` which only applies to
+ * function expressions.
  *
- * When a member function is not applicable to this `BoxedExpression`,
- * for example `get symbol()` on a `BoxedNumber`, it returns `null`.
+ * When a property is not applicable to this `BoxedExpression` its value is
+ * `null`. For example `expr.symbol` for a `BoxedNumber` is `null`.
  *
  * This convention makes it convenient to manipulate expressions without
  * having to check what kind of instance they are before manipulating them.
  * :::
  *
- * To get a boxed expression from a LaTeX string use `ce.parse()`, and to
- * get a boxed expression from a MathJSON expression use `ce.box()`.
+ * :::info[THEORY OF OPERATIONS]
+ * A boxed expression can represent a canonical or a non-canonical
+ * expression. A non-canonical expression is a "raw" form of the
+ * expression. For example, the non-canonical representation of `\frac{10}{20}`
+ * is `["Divide", 10, 20]`. The canonical representation of the same
+ * expression is the boxed number `1/2`.
+ *
+ * The canonical representation of symbols and function expressions are
+ * bound to a definition. The definition contains metadata about the symbol
+ * or function operator, such as its type, its signature, and other attributes.
+ * The value of symbols are tracked in a separate table for each
+ * evaluation context.
+ *
+ * The binding only occurs when the expression is constructed, if it is created
+ * as a canonical expression. If the expression is constructed as a
+ * non-canonical expression, no binding is done.
+ *
+ * <!--
+ * Rules:
+ * - nothing should cause the binding to occur outside of the constructor
+ * - if an operation require a canonical expression (e.g. evaluate()),
+ *  it should return undefined or throw an error if the expression is not
+ *   canonical
+ * -->
+ *
+ *
+ * :::
+ *
+ * :::info[THEORY OF OPERATIONS]
+ * The **value** of an expression is a number, a string, a boolean or a tensor.
+ *
+ * The value of number literals and strings are themselves.
+ *
+ * A symbol can have a value associated with it, in which case the value
+ * of the symbol is the value associated with it.
+ *
+ * Some symbols (unknowns) are purely symbolic and have no value associated
+ * with them.
  *
+ * Function expressions do not have a value associated with them.
+ * For example, `["Add", 2, 3]` has no value associated with it, it is a
+ * symbolic expression.
+ *
+ * Some properties of a Boxed Expression are only applicable if the expression
+ * has a value associated with it. For example, `expr.isNumber` is only
+ * applicable if the value of the expression is a number, that is if the
+ * expression is a number literal or a symbol with a numeric value.
+ *
+ * The following properties are applicable to expressions with a value:
+ * - `expr.isNumber`
+ * :::
  *
  * To create a boxed expression:
  *
  * ### `ce.box()` and `ce.parse()`
  *
- * Use `ce.box()` or `ce.parse()` to get a canonical expression.
+ * Use `ce.box()` or `ce.parse()`.
+ *
+ * Use `ce.parse()` to get a boxed expression from a LaTeX string.
+ * Use `ce.box()` to get a boxed expression from a MathJSON expression.
+ *
+ * By default, the result of these methods is a canonical expression. For
+ * example, if it is a rational literal, it is reduced to its canonical form.
+ * If it is a function expression:
  *    - the arguments are put in canonical form
+ *    - the arguments of commutative functions are sorted
  *    - invisible operators are made explicit
  *    - a limited number of core simplifications are applied,
- *      for example 0 is removed from additions
+ *      for example rationals are reduced
  *    - sequences are flattened: `["Add", 1, ["Sequence", 2, 3]]` is
  *      transformed to `["Add", 1, 2, 3]`
  *    - associative functions are flattened: `["Add", 1, ["Add", 2, 3]]` is
  *      transformed to `["Add", 1, 2, 3]`
- *    - the arguments of commutative functions are sorted
- *    - identifiers are **not** replaced with their values
+ *    - symbols are **not** replaced with their values (unless they have
+ *       a `holdUntil` flag set to `never`).
  *
- * ### Algebraic methods (expr.add(), expr.mul(), etc...)
+ * ### `ce.function()`
  *
- * The boxed expression have some algebraic methods,
- * i.e. `add`, `mul`, `div`, `pow`, etc. These methods are suitable for
+ * This is a specialized version of `ce.box()` for creating a new function
+ * expression.
+ *
+ * The canonical handler of the operator is called.
+ *
+ *
+ * ### Algebraic methods (`expr.add()`, `expr.mul()`, etc...)
+ *
+ * The boxed expression have some algebraic methods, i.e. `add()`, `mul()`,
+ * `div()`, `pow()`, etc. These methods are suitable for
  * internal calculations, although they may be used as part of the public
  * API as well.
  *
- *    - the operation is performed on the canonical version of the expression
- *
+ *    - a runtime error is thrown if the expression is not canonical
  *    - the arguments are not evaluated
- *
  *    - the canonical handler (of the corresponding operation) is not called
- *
  *    - some additional simplifications over canonicalization are applied.
  *      For example number literals are combined.
  *      However, the result is exact, and no approximation is made. Use `.N()`
  *      to get an approximate value.
  *      This is equivalent to calling `simplify()` on the expression (but
  *      without simplifying the arguments).
- *
  *    - sequences were already flattened as part of the canonicalization process
  *
- *   For 'add' and 'mul', which take multiple arguments, separate functions
- *   are provided that take an array of arguments. They are equivalent
- *   to calling the boxed algebraic method, i.e. `ce.Zero.add(1, 2, 3)` and
- *   `add(1, 2, 3)` are equivalent.
+ * For 'add()' and 'mul()', which take multiple arguments, separate functions
+ * are provided that take an array of arguments. They are equivalent
+ * to calling the boxed algebraic method, i.e. `ce.Zero.add(1, 2, 3)` and
+ * `add(1, 2, 3)` are equivalent.
  *
  * These methods are not equivalent to calling `expr.evaluate()` on the
- * expression: evaluate will replace identifiers with their values, and
- * evaluate the expression
+ * expression: evaluate will replace symbols with their values, and
+ * evaluate the expression.
  *
- * ### `ce._fn()`
+ * For algebraic functions (`add()`, `mul()`, etc..), use the corresponding
+ * canonicalization function, i.e. `canonicalAdd(a, b)` instead of
+ * `ce.function('Add', [a, b])`.
+ *
+ * Another option is to use the algebraic methods directly, i.e. `a.add(b)`
+ * instead of `ce.function('Add', [a, b])`. However, the algebraic methods will
+ * apply further simplifications which may or may not be desirable. For
+ * example, number literals will be combined.
  *
- * Use `ce._fn()` to create a new function expression.
+ * ### `ce._fn()`
  *
- * This is a low level method which is typically invoked in the canonical
- * handler of a function definition.
+ * This method is a low level method to create a new function expression which
+ * is typically invoked in the canonical handler of an operator definition.
  *
  * The arguments are not modified. The expression is not put in canonical
  * form. The canonical handler is *not* called.
  *
- * A canonical flag can be set when calling the function, but it only
- * asserts that the function and its arguments are canonical. The caller
- * is responsible for ensuring that is the case.
+ * A canonical flag can be set when calling this method, but it only
+ * asserts that the function expression is canonical. The caller is responsible
+ * for ensuring that is the case.
  *
  *
- * ### `ce.function()`
- *
- * This is a specialized version of `ce.box()`. It is used to create a new
- * function expression.
- *
- * The arguments are put in canonical form and the canonical handler is called.
- *
- * For algebraic functions (add, mul, etc..), use the corresponding
- * canonicalization function, i.e. `canonicalAdd(a, b)` instead of
- * `ce.function('Add', a, b)`.
- *
- * Another option is to use the algebraic methods directly, i.e. `a.add(b)`
- * instead of `ce.function('Add', a, b)`. However, the algebraic methods will
- * apply further simplifications which may or may not be desirable. For
- * example, number literals will be combined.
  *
  * ### Canonical Handlers
  *
  * Canonical handlers are responsible for:
- *    - validating the signature (type and number of arguments)
+ *    - validating the signature: this can involve checking the
+ *      number of arguments. It is recommended to avoid checking the
+ *      type of non-literal arguments, since the type of symbols or
+ *      function expressions may change. Similarly, the canonicalization
+ *      process should not rely on the value of or assumptions about non-literal
+ *      arguments.
  *    - flattening sequences
- *    - flattening associative functions
+ *    - flattening arguments if the function is associative
  *    - sort the arguments (if the function is commutative)
  *    - calling `ce._fn()` to create a new function expression
- *    - if the function definition has a hold, they should also put
- *      their arguments in canonical form, if appropriate
  *
  * When the canonical handler is invoked, the arguments have been put in
- * canonical form according to the `hold` flag.
+ * canonical form unless the `lazy` flag is set to `true`.
  *
- * Some canonical handlers are available as separate functions and can be
- * used directly, for example `canonicalAdd(a, b)` instead of
- * `ce.function('Add', [a, b])`.
+ * Note that the result of a canonical handler should be a canonical expression,
+ * but not all arguments need to be canonical. For example, the arguments of
+ * `["Declare", "x", 2]` are not canonical, since `x` refers to the name
+ * of the symbol, not its value.
  *
  * @category Boxed Expression
  *
  */
 export interface BoxedExpression {
-    /** The Compute Engine associated with this expression provides
+    /** @internal */
+    readonly hash: number;
+    /**
+     * The Compute Engine instance associated with this expression provides
      * a context in which to interpret it, such as definition of symbols
      * and functions.
-     *
      */
     readonly engine: ComputeEngine;
-    /** From `Object.valueOf()`, return a primitive value for the expression.
+    /**
      *
-     * If the expression is a machine number, or bignum or rational that can be
-     * converted to a machine number, return a JavaScript `number`.
+     * Return a JavaScript primitive value for the expression, based on
+     * `Object.valueOf()`.
      *
-     * If the expression is a symbol, return the name of the symbol as a `string`.
+     * This method is intended to make it easier to work with JavaScript
+     * primitives, for example when mixing JavaScript computations with
+     * symbolic computations from the Compute Engine.
      *
-     * Otherwise return a JavaScript primitive representation of the expression.
+     * If the expression is a **machine number**, a **bignum**, or a **rational**
+     * that can be converted to a machine number, return a JavaScript `number`.
+     * This conversion may result in a loss of precision.
+     *
+     * If the expression is the **symbol `"True"`** or the **symbol `"False"`**,
+     * return `true` or `false`, respectively.
+     *
+     * If the expression is a **symbol with a numeric value**, return the numeric
+     * value of the symbol.
+     *
+     * If the expression is a **string literal**, return the string value.
+     *
+     * If the expression is a **tensor** (list of number or multidimensional
+     * array or matrix), return an array of numbers, or an array of
+     * arrays of numbers, or an array of arrays of arrays of numbers.
+     *
+     * If the expression is a function expression return a string representation
+     * of the expression.
+     *
+     * @category Primitive Methods
+     */
+    valueOf(): number | number[] | number[][] | number[][][] | string | boolean;
+    /** Similar to`expr.valueOf()` but includes a hint.
      *
      * @category Primitive Methods
      */
-    valueOf(): number | any | string | boolean;
-    /** From `Object.toString()`, return a string representation of the
-     *  expression. This string is suitable to be output to the console
-     * for debugging, for example. It is formatted as a ASCIIMath expression.
+    [Symbol.toPrimitive](hint: 'number' | 'string' | 'default'): number | string | null;
+    /**
+     * Return an ASCIIMath representation of the expression. This string is
+     * suitable to be output to the console for debugging, for example.
+     *
+     * Based on `Object.toString()`.
      *
      * To get a LaTeX representation of the expression, use `expr.latex`.
      *
+     * Note that lazy collections are eagerly evaluated.
+     *
      * Used when coercing a `BoxedExpression` to a `String`.
      *
      * @category Primitive Methods
      */
     toString(): string;
-    /**
-     * Output to the console a string representation of the expression.
+    /** Serialize to a LaTeX string.
      *
-     * @category Primitive Methods
+     * Note that lazy collections are eagerly evaluated.
+     *
+     * Will ignore any LaTeX metadata.
      */
-    print(): void;
-    /** Similar to`expr.valueOf()` but includes a hint.
+    toLatex(options?: Partial<SerializeLatexOptions>): LatexString;
+    /** LaTeX representation of this expression.
+     *
+     * If the expression was parsed from LaTeX, the LaTeX representation is
+     * the same as the input LaTeX.
+     *
+     * To customize the serialization, use `expr.toLatex()`.
+     *
+     * Note that lazy collections are eagerly evaluated.
+     *
+     * :::info[Note]
+     * Applicable to canonical and non-canonical expressions.
+     * :::
      *
-     * @category Primitive Methods
      */
-    [Symbol.toPrimitive](hint: 'number' | 'string' | 'default'): number | string | null;
+    get latex(): LatexString;
     /** Used by `JSON.stringify()` to serialize this object to JSON.
      *
      * Method version of `expr.json`.
      *
+     * Based on `Object.toJSON()`.
+     *
+     * Note that lazy collections are *not* eagerly evaluated.
+     *
      * @category Primitive Methods
      */
     toJSON(): Expression;
-    /** Serialize to a MathJSON expression with specified options*/
+    /** Serialize to a MathJSON expression with specified options */
     toMathJson(options?: Readonly<Partial<JsonSerializationOptions>>): Expression;
-    /** Serialize to a LaTeX string.
-     *
-     * Will ignore any LaTeX metadata.
-     */
-    toLatex(options?: Partial<SerializeLatexOptions>): LatexString;
-    verbatimLatex?: string;
-    /** 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);
-    /** If `true`, this expression is in a structural form. */
-    get isStructural(): boolean;
     /** MathJSON representation of this expression.
      *
      * This representation always use shorthands when possible. Metadata is not
@@ -231,6 +409,8 @@ export interface BoxedExpression {
      *
      * For more control over the serialization, use `expr.toMathJson()`.
      *
+     * Note that lazy collections are *not* eagerly evaluated.
+     *
      * :::info[Note]
      * Applicable to canonical and non-canonical expressions.
      * :::
@@ -238,75 +418,161 @@ export interface BoxedExpression {
      */
     readonly json: Expression;
     /**
-     * The scope in which this expression has been defined.
+     * Output to the console a string representation of the expression.
+     *
+     * Note that lazy collections are eagerly evaluated when printed.
      *
-     * Is `null` when the expression is not canonical.
      */
-    readonly scope: RuntimeScope | null;
-    /**
-     * Equivalent to `BoxedExpression.isSame()` but the argument can be
-     * a JavaScript primitive. For example, `expr.is(2)` is equivalent to
-     * `expr.isSame(ce.number(2))`.
+    print(): void;
+    /** If the expression was constructed from a LaTeX string, the verbatim LaTeX
+     *  string it was parsed from.
+     */
+    verbatimLatex?: string;
+    /** 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);
+    /** If `true`, this expression is in a structural form.
      *
-     * @category Primitive Methods
+     * The structural form of an expression is used when applying rules to
+     * an expression. For example, a rational number is represented as a
+     * function expression instead of a `BoxedExpression` object.
      *
      */
-    is(rhs: any): boolean;
-    /** @internal */
-    readonly hash: number;
-    /** LaTeX representation of this expression.
+    get isStructural(): boolean;
+    /**
+     * Return the canonical form of this expression.
      *
-     * If the expression was parsed from LaTeX, the LaTeX representation is
-     * the same as the input LaTeX.
+     * If a function expression or symbol, they are first bound with a definition
+     * in the current scope.
      *
-     * To customize the serialization, use `expr.toLatex()`.
+     * When determining the canonical form the following operator 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 this expression is already canonical, the value of canonical is
+     * `this`.
+     *
+     * The arguments of a canonical function expression may not all be
+     * canonical, for example in the `["Declare", "i", 2]` expression,
+     * `i` is not canonical since it is used only as the name of a symbol, not
+     * as a (potentially) existing symbol.
      *
      * :::info[Note]
-     * Applicable to canonical and non-canonical expressions.
+     * Partially canonical expressions, such as those produced through
+     * `CanonicalForm`, also yield an expression which is marked as `canonical`.
+     * This means that, likewise for partially canonical expressions, the
+     * `canonical` property will return the self-same expression (and
+     * 'isCanonical' will also be true).
      * :::
      *
      */
-    get latex(): LatexString;
+    get canonical(): BoxedExpression;
     /**
+     * Return the structural form of this expression.
+     *
+     * Some expressions, such as rational numbers, are represented with
+     * a `BoxedExpression` object. In some cases, for example when doing a
+     * structural comparison of two expressions, it is useful to have a
+     * structural representation of the expression where the rational numbers
+     * is represented by a function expression instead.
+     *
+     * If there is a structural representation of the expression, return it,
+     * otherwise return `this`.
+     *
+     */
+    get structural(): BoxedExpression;
+    /** `false` if this expression or any of its subexpressions is an `["Error"]`
+     * expression.
      *
      * :::info[Note]
-     * Applicable to canonical and non-canonical expressions.
+     * 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 type
+     * mismatch, or missing or unexpected arguments.
      * :::
-     * @internal
+     *
      */
-    set latex(val: LatexString);
-    /** If this expression is a symbol, return the name of the symbol as a string.
-     * Otherwise, return `null`.
+    readonly isValid: boolean;
+    /** If *true*, evaluating this expression has no side-effects (does not
+     * change the state of the Compute Engine).
+     *
+     * If *false*, evaluating this expression may change the state of the
+     * Compute Engine or it may return a different value each time it is
+     * evaluated, even if the state of the Compute Engine is the same.
+     *
+     * As an example, the ["Add", 2, 3]` function expression is pure, but
+     * the `["Random"]` function expression is not pure.
+     *
+     * For a function expression to be pure, the function itself (its operator)
+     * must be pure, and all of its arguments must be pure too.
+     *
+     * A pure function expression may return a different value each time it is
+     * evaluated if its arguments are not constant. For example, the
+     * `["Add", "x", 1]` function expression is pure, but it is not
+     * constant, because `x` is not constant.
      *
      * :::info[Note]
-     * Applicable to canonical and non-canonical expressions.
+     * Applicable to canonical expressions only
      * :::
+     */
+    readonly isPure: boolean;
+    /**
+     * `True` if evaluating this expression always returns the same value.
      *
-     * @category Symbol Expression
+     * If *true* and a function expression, implies that it is *pure* and
+     * that all of its arguments are constant.
      *
+     * Number literals, symbols with constant values, and pure numeric functions
+     * with constant arguments are all *constant*, i.e.:
+     * - `42` is constant
+     * - `Pi` is constant
+     * - `["Divide", "Pi", 2]` is constant
+     * - `x` is not constant, unless declared with a constant flag.
+     * - `["Add", "x", 2]` is either constant only if `x` is constant.
      */
-    readonly symbol: string | null;
-    /** If this expression is a string, return the value of the string.
-     * Otherwise, return `null`.
+    readonly isConstant: boolean;
+    /** All the `["Error"]` subexpressions.
+     *
+     * If an expression includes an error, the expression is also an error.
+     * In that case, the `this.isValid` property is `false`.
      *
      * :::info[Note]
      * Applicable to canonical and non-canonical expressions.
      * :::
-  
-    * @category String Expression
      *
      */
-    readonly string: string | null;
-    readonly tensor: null | TensorData<'expression'>;
+    readonly errors: ReadonlyArray<BoxedExpression>;
     /** All the subexpressions matching the named operator, recursively.
+     *
+     * Example:
+     *
+     * ```js
+     * const expr = ce.parse('a + b * c + d');
+     * const subexpressions = expr.getSubexpressions('Add');
+     * // -> `[['Add', 'a', 'b'], ['Add', 'c', 'd']]`
+     * ```
      *
      * :::info[Note]
      * Applicable to canonical and non-canonical expressions.
      * :::
      *
      */
-    getSubexpressions(name: string): ReadonlyArray<BoxedExpression>;
+    getSubexpressions(operator: string): ReadonlyArray<BoxedExpression>;
     /** All the subexpressions in this expression, recursively
+     *
+     * Example:
+     *
+     * ```js
+     * const expr = ce.parse('a + b * c + d');
+     * const subexpressions = expr.subexpressions;
+     * // -> `[['Add', 'a', 'b'], ['Add', 'c', 'd'], 'a', 'b', 'c', 'd']`
+     * ```
      *
      * :::info[Note]
      * Applicable to canonical and non-canonical expressions.
@@ -318,6 +584,12 @@ export interface BoxedExpression {
      *
      * All the symbols in the expression, recursively
      *
+     * ```js
+     * const expr = ce.parse('a + b * c + d');
+     * const symbols = expr.symbols;
+     * // -> ['a', 'b', 'c', 'd']
+     * ```
+     *
      * :::info[Note]
      * Applicable to canonical and non-canonical expressions.
      * :::
@@ -325,42 +597,220 @@ export interface BoxedExpression {
      */
     readonly symbols: ReadonlyArray<string>;
     /**
-     * All the identifiers used in the expression that do not have a value
+     * All the symbols used in the expression that do not have a value
      * associated with them, i.e. they are declared but not defined.
      */
     readonly unknowns: ReadonlyArray<string>;
     /**
+     * Return `true` if this expression is a number literal, for example
+     * `2`, `3.14`, `1/2`, `√2` etc.
+     *
+     * When `true`, `expr.numericValue` is not `null`.
      *
-     * All the identifiers (symbols and functions) in the expression that are
-     * not a local variable or a parameter of that function.
+     * @category Numeric Expression
      *
      */
-    readonly freeVariables: ReadonlyArray<string>;
-    /** All the `["Error"]` subexpressions.
+    readonly isNumberLiteral: boolean;
+    /**
+     * Return the value of this expression, if a number literal.
      *
-     * If an expression includes an error, the expression is also an error.
-     * In that case, the `this.isValid` property is `false`.
+     * Note it is possible for `expr.numericValue` to be `null`, and for
+     * `expr.isNotZero` to be true. For example, when a symbol has been
+     * defined with an assumption.
      *
-     * :::info[Note]
-     * Applicable to canonical and non-canonical expressions.
-     * :::
+     * Conversely, `expr.isNumber` may be true even if `expr.numericValue` is
+     * `null`, for example the symbol `Pi` return `true` for `isNumber` but
+     * `expr.numericValue` is `null` (it's a symbol, not a number literal).
+     * Its value can be accessed with `expr.value`.
+     *
+     * To check if an expression is a number literal, use `expr.isNumberLiteral`.
+     * If `expr.isNumberLiteral` is `true`, `expr.numericValue` is not `null`.
+     *
+     * @category Numeric Expression
      *
      */
-    readonly errors: ReadonlyArray<BoxedExpression>;
-    /** `true` if this expression or any of its subexpressions is an `["Error"]`
-     * expression.
+    readonly numericValue: number | NumericValue | null;
+    /**
+     * Attempt to factor a numeric coefficient `c` and a `rest` out of a
+     * canonical expression such that `rest.mul(c)` is equal to `this`.
+     *
+     * Attempts to make `rest` a positive value (i.e. pulls out negative sign).
+     *
+     *```json
+     * ['Multiply', 2, 'x', 3, 'a']
+     *    -> [NumericValue(6), ['Multiply', 'x', 'a']]
+     *
+     * ['Divide', ['Multiply', 2, 'x'], ['Multiply', 3, 'y', 'a']]
+     *    -> [NumericValue({rational: [2, 3]}), ['Divide', 'x', ['Multiply, 'y', 'a']]]
+     * ```
+     */
+    toNumericValue(): [NumericValue, BoxedExpression];
+    /**
+     * If the value of this expression is not an **integer** return `undefined`.
+     *
+     * @category Numeric Expression
+     */
+    readonly isEven: boolean | undefined;
+    /**
+     * If the value of this expression is not an **integer** return `undefined`.
+     *
+     * @category Numeric Expression
+     */
+    readonly isOdd: boolean | undefined;
+    /**
+     * Return the real part of the value of this expression, if a number.
+     *
+     * Otherwise, return `NaN` (not a number).
+     *
+     * @category Numeric Expression
+     */
+    readonly re: number;
+    /**
+     * If value of this expression is a number, return the imaginary part of the
+     * value. If the value is a real number, the imaginary part is 0.
+     *
+     * Otherwise, return `NaN` (not a number).
+     *
+     * @category Numeric Expression
+     */
+    readonly im: number;
+    /**
+     * If the value of this expression is a number, return the real part of the
+     * value as a `BigNum`.
+     *
+     * If the value is not available as a bignum return `undefined`. That is,
+     * the value is not upconverted to a bignum.
+     *
+     * To get the real value either as a bignum or a number, use
+     * `expr.bignumRe ?? expr.re`.
+     *
+     * When using this pattern, the value is returned as a bignum if available,
+     * otherwise as a number or `NaN` if the value is not a number.
+     *
+     * @category Numeric Expression
+     *
+     */
+    readonly bignumRe: BigNum | undefined;
+    /**
+     * If the value of this expression is a number, return the imaginary part as
+     * a `BigNum`.
+     *
+     * It may be 0 if the number is real.
+     *
+     * If the value of the expression is not a number or the value is not
+     * available as a bignum return `undefined`. That is, the value is not
+     * upconverted to a bignum.
+     *
+     * To get the imaginary value either as a bignum or a number, use
+     * `expr.bignumIm ?? expr.im`.
+     *
+     * When using this pattern, the value is returned as a bignum if available, otherwise as a number or `NaN` if the value is not a number.
+     *
+     * @category Numeric Expression
+     */
+    readonly bignumIm: BigNum | undefined;
+    /**
+     * Return the sign of the expression.
+     *
+     * Note that complex numbers have no natural ordering, so if the value is an
+     * imaginary number (a complex number with a non-zero imaginary part),
+     * `this.sgn` will return `unsigned`.
+     *
+     * If a symbol, this does take assumptions into account, that is `this.sgn`
+     * will return `positive` if the symbol is assumed to be positive
+     * using `ce.assume()`.
+     *
+     * Non-canonical expressions return `undefined`.
+     *
+     * @category Numeric Expression
+     *
+     */
+    readonly sgn: Sign | undefined;
+    /** The value of this expression is > 0, same as `isGreaterEqual(0)`
+     *
+     * @category Numeric Expression
+     */
+    readonly isPositive: boolean | undefined;
+    /** The value of this expression is >= 0, same as `isGreaterEqual(0)`
+     *
+     * @category Numeric Expression
+     */
+    readonly isNonNegative: boolean | undefined;
+    /** The value of this expression is &lt; 0, same as `isLess(0)`
+     *
+     * @category Numeric Expression
+     */
+    readonly isNegative: boolean | undefined;
+    /** The  value of this expression is &lt;= 0, same as `isLessEqual(0)`
+     *
+     * @category Numeric Expression
+     */
+    readonly isNonPositive: boolean | undefined;
+    /** Negate (additive inverse) */
+    neg(): BoxedExpression;
+    /** Inverse (multiplicative inverse) */
+    inv(): BoxedExpression;
+    /** Absolute value */
+    abs(): BoxedExpression;
+    /** Addition */
+    add(rhs: number | BoxedExpression): BoxedExpression;
+    /** Subtraction */
+    sub(rhs: BoxedExpression): BoxedExpression;
+    /** Multiplication */
+    mul(rhs: NumericValue | number | BoxedExpression): BoxedExpression;
+    /** Division */
+    div(rhs: number | BoxedExpression): BoxedExpression;
+    /** Power */
+    pow(exp: number | BoxedExpression): BoxedExpression;
+    /** Exponentiation */
+    root(exp: number | BoxedExpression): BoxedExpression;
+    /** Square root */
+    sqrt(): BoxedExpression;
+    /** Logarithm (natural by default) */
+    ln(base?: number | BoxedExpression): BoxedExpression;
+    /**
+     * Return this expression expressed as a numerator.
+     */
+    get numerator(): BoxedExpression;
+    /**
+     * Return this expression expressed as a denominator.
+     */
+    get denominator(): BoxedExpression;
+    /**
+     * Return this expression expressed as a numerator and denominator.
+     */
+    get numeratorDenominator(): [BoxedExpression, BoxedExpression];
+    /** If this expression is a symbol, return the name of the symbol as a string.
+     * Otherwise, return `null`.
      *
      * :::info[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 type
-     * mismatch, or missing or unexpected arguments.
+     * Applicable to canonical and non-canonical expressions.
      * :::
      *
      * @category Symbol Expression
      *
      */
-    readonly isValid: boolean;
+    readonly symbol: string | null;
+    /** If this expression is a string, return the value of the string.
+      * Otherwise, return `null`.
+      *
+      * :::info[Note]
+      * Applicable to canonical and non-canonical expressions.
+      * :::
+  
+      * @category String Expression
+      *
+      */
+    readonly string: string | null;
+    /**
+     * Return `true` if this expression is a function expression.
+     *
+     * If `true`, `expr.ops` is not `null`, and `expr.operator` is the name
+     * of the function.
+     *
+     * @category Function Expression
+     */
+    readonly isFunctionExpression: boolean;
     /**
      * The name of the operator of the expression.
      *
@@ -370,8 +820,11 @@ export interface BoxedExpression {
      *
      * A symbol has a `"Symbol"` operator.
      *
-     * A number has a `"Number"`, `"Real"`, `"Rational"` or `"Integer"` operator.
+     * A number has a `"Number"`, `"Real"`, `"Rational"` or `"Integer"` operator; amongst some others.
+     * Practically speaking, for fully canonical and valid expressions, all of these are likely to
+     * collapse to `"Number"`.
      *
+     * @category Function Expression
      */
     readonly operator: string;
     /** The list of operands of the function.
@@ -438,71 +891,18 @@ export interface BoxedExpression {
      *
      */
     readonly op3: BoxedExpression;
-    /** 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.
-     *
-     * :::info[Note]
-     * Applicable to canonical and non-canonical expressions.
-     * :::
-     */
-    readonly isPure: boolean;
-    /**
-     * True if the the value of the expression does not depend on the value of
-     * any other expression.
-     *
-     * For example, a number literal, a symbol with a constant value.
-     * - `2` is constant
-     * - `Pi` is constant
-     * - `["Add", "Pi", 2]` is constant
-     * - `x` is not constant
-     * - `["Add", "x", 2]` is not constant
+    /** If true, the expression has its own local scope that can be used
+     * for local variables and arguments. Only true if the expression is a
+     * function expression.
      */
-    readonly isConstant: boolean;
-    /**
-     * Return the canonical form of this expression.
-     *
-     * If this is a function expression, a definition is associated with the
-     * canonical expression.
-     *
-     * 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 this expression is already canonical, the value of canonical is
-     * `this`.
-     *
-     */
-    get canonical(): BoxedExpression;
-    /**
-     * Return the structural form of this expression.
-     *
-     * Some expressions, such as rational numbers, are represented with
-     * a `BoxedExpression` object. In some cases, for example when doing a
-     * structural comparison of two expressions, it is useful to have a
-     * structural representation of the expression where the rational numbers
-     * is represented by a function expression instead.
-     *
-     * If there is a structural representation of the expression, return it,
-     * otherwise return `this`.
-     *
-     */
-    get structural(): BoxedExpression;
+    readonly isScoped: boolean;
+    /** If this expression has a local scope, return it. */
+    get localScope(): Scope | undefined;
     /**
      * Replace all the symbols in the expression as indicated.
      *
      * Note the same effect can be achieved with `this.replace()`, but
-     * using `this.subs()` is more efficient, and simpler, but limited
+     * using `this.subs()` is more efficient and simpler, but limited
      * to replacing symbols.
      *
      * The result is bound to the current scope, not to `this.scope`.
@@ -511,396 +911,281 @@ export interface BoxedExpression {
      * is canonical.
      *
      * :::info[Note]
-     * Applicable to canonical and non-canonical expressions.
-     * :::
-     *
-     */
-    subs(sub: Substitution, options?: {
-        canonical?: CanonicalOptions;
-    }): BoxedExpression;
-    /**
-     * Recursively replace all the subexpressions in the expression as indicated.
-     *
-     * To remove a subexpression, return an empty `["Sequence"]` expression.
-     *
-     * The canonical option is applied to each function subexpression after
-     * the substitution is applied.
-     *
-     * If no `options.canonical` is set, the result is canonical if `this`
-     * is canonical.
-     *
-     * **Default**: `{ canonical: this.isCanonical, recursive: true }`
-     */
-    map(fn: (expr: BoxedExpression) => BoxedExpression, options?: {
-        canonical: CanonicalOptions;
-        recursive?: boolean;
-    }): BoxedExpression;
-    /**
-     * Transform the expression by applying one or more replacement rules:
-     *
-     * - If the expression matches the `match` pattern and the `condition`
-     *  predicate is true, replace it with the `replace` pattern.
-     *
-     * - If no rules apply, return `null`.
-     *
-     * See also `expr.subs()` for a simple substitution of symbols.
-     *
-     * If `options.canonical` is not set, the result is canonical if `this`
-     * is canonical.
-     *
-     * :::info[Note]
-     * Applicable to canonical and non-canonical expressions.
-     * :::
-     */
-    replace(rules: BoxedRuleSet | Rule | Rule[], options?: Partial<ReplaceOptions>): null | BoxedExpression;
-    /**
-     * True if the expression includes a symbol `v` or a function operator `v`.
-     *
-     * :::info[Note]
-     * Applicable to canonical and non-canonical expressions.
-     * :::
-     */
-    has(v: string | string[]): boolean;
-    /** Structural/symbolic equality (weak equality).
-     *
-     * `ce.parse('1+x').isSame(ce.parse('x+1'))` is `false`.
-     *
-     * See `expr.isEqual()` for mathematical equality.
-     *
-     * :::info[Note]
-     * Applicable to canonical and non-canonical expressions.
-     * :::
-     *
-     * @category Relational Operator
-     */
-    isSame(rhs: BoxedExpression): boolean;
-    /**
-     * Return this expression expressed as a numerator and denominator.
-     */
-    get numerator(): BoxedExpression;
-    get denominator(): BoxedExpression;
-    get numeratorDenominator(): [BoxedExpression, BoxedExpression];
-    /**
-     * If this expression matches `pattern`, return a substitution that makes
-     * `pattern` equal to `this`. Otherwise return `null`.
-     *
-     * If `pattern` includes wildcards (identifiers that start
-     * with `_`), the substitution will include a prop for each matching named
-     * wildcard.
-     *
-     * If this expression matches `pattern` but there are no named wildcards,
-     * return the empty substitution, `{}`.
-     *
-     * Read more about [**patterns and rules**](/compute-engine/guides/patterns-and-rules/).
-     *
-     * :::info[Note]
-     * Applicable to canonical and non-canonical expressions.
-     * :::
-     *
-     */
-    match(pattern: 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 Numeric Expression
-     *
-     */
-    readonly isNaN: boolean | undefined;
-    /**
-     * The numeric value of this expression is `±Infinity` or Complex Infinity
-     *
-     * @category Numeric Expression
-     */
-    readonly isInfinity: boolean | undefined;
-    /** This expression is a number, but not `±Infinity`, 'ComplexInfinity` or
-     *  `NaN`
+     * Applicable to canonical and non-canonical expressions.
+     * :::
      *
-     * @category Numeric Expression
-     */
-    readonly isFinite: boolean | undefined;
-    /**
-     * @category Numeric Expression
-     */
-    readonly isEven: boolean | undefined;
-    /**
-     * @category Numeric Expression
      */
-    readonly isOdd: boolean | undefined;
+    subs(sub: Substitution, options?: {
+        canonical?: CanonicalOptions;
+    }): BoxedExpression;
     /**
-     * Return the value of this expression, if a number literal.
+     * Recursively replace all the subexpressions in the expression as indicated.
      *
-     * Note it is possible for `this.numericValue` to be `null`, and for
-     * `this.isNotZero` to be true. For example, when a symbol has been
-     * defined with an assumption.
+     * To remove a subexpression, return an empty `["Sequence"]` expression.
      *
-     * Conversely, `this.isNumber` may be true even if `numericValue` is `null`,
-     * example the symbol `Pi` return `true` for `isNumber` but `numericValue` is
-     * `null`. Its value can be accessed with `.N().numericValue`.
+     * The `canonical` option is applied to each function subexpression after
+     * the substitution is applied.
      *
-     * To check if an expression is a number literal, use `this.isNumberLiteral`.
-     * If `this.isNumberLiteral` is `true`, `this.numericValue` is not `null`
+     * If no `options.canonical` is set, the result is canonical if `this`
+     * is canonical.
      *
-     * @category Numeric Expression
+     * **Default**: `{ canonical: this.isCanonical, recursive: true }`
      *
+     * :::info[Note]
+     * Applicable to canonical and non-canonical expressions.
+     * :::
      */
-    readonly numericValue: number | NumericValue | null;
+    map(fn: (expr: BoxedExpression) => BoxedExpression, options?: {
+        canonical: CanonicalOptions;
+        recursive?: boolean;
+    }): BoxedExpression;
     /**
-     * Return `true` if this expression is a number literal, for example
-     * `2`, `3.14`, `1/2`, `√2` etc.
+     * Transform the expression by applying one or more replacement rules:
+     *
+     * - If the expression matches the `match` pattern and the `condition`
+     *  predicate is true, replace it with the `replace` pattern.
      *
-     * This is equivalent to checking if `this.numericValue` is not `null`.
+     * - If no rules apply, return `null`.
      *
-     * @category Numeric Expression
+     * See also `expr.subs()` for a simple substitution of symbols.
+     *
+     * If `options.canonical` is not set, the result is canonical if `this`
+     * is canonical.
      *
+     * :::info[Note]
+     * Applicable to canonical and non-canonical expressions.
+     * :::
      */
-    readonly isNumberLiteral: boolean;
+    replace(rules: BoxedRuleSet | Rule | Rule[], options?: Partial<ReplaceOptions>): null | BoxedExpression;
     /**
-     * Return `true` if this expression is a function expression.
+     * True if the expression includes a symbol `v` or a function operator `v`.
      *
-     * If `true`, `this.ops` is not `null`, and `this.operator` is the name
-     * of the function.
+     * :::info[Note]
+     * Applicable to canonical and non-canonical expressions.
+     * :::
      */
-    readonly isFunctionExpression: boolean;
-    /**
-     * If this expression is a number literal or a symbol with a value that
-     * is a number literal, return the real part of the value.
+    has(v: string | string[]): boolean;
+    /** Structural/symbolic equality (weak equality).
      *
-     * If the expression is not a number literal, or a symbol with a value
-     * that is a number literal, return `NaN` (not a number).
+     * `ce.parse('1+x', {canonical: false}).isSame(ce.parse('x+1', {canonical: false}))` is `false`.
      *
-     * @category Numeric Expression
-     */
-    readonly re: number;
-    /**
-     * If this expression is a number literal or a symbol with a value that
-     * is a number literal, return the imaginary part of the value. If the value
-     * is a real number, the imaginary part is 0.
+     * See `expr.isEqual()` for mathematical equality.
      *
-     * If the expression is not a number literal, or a symbol with a value
-     * that is a number literal, return `NaN` (not a number).
+     * :::info[Note]
+     * Applicable to canonical and non-canonical expressions.
+     * :::
      *
-     * @category Numeric Expression
+     * @category Relational Operator
      */
-    readonly im: number;
+    isSame(rhs: BoxedExpression): boolean;
     /**
-     * If this expression is a number literal or a symbol with a value that
-     * is a number literal, return the real part of the value as a `BigNum`.
-     *
-     * If the value is not available as a bignum return `undefined`. That is,
-     * the value is not upconverted to a bignum.
-     *
-     * To get the real value either as a bignum or a number, use
-     * `this.bignumRe ?? this.re`. When using this pattern, the value is
-     * returned as a bignum if available, otherwise as a number or NaN if
-     * the value is not a number literal or a symbol with a value that is a
-     * number literal.
+     * Equivalent to `BoxedExpression.isSame()` but the argument can be
+     * a JavaScript primitive. For example, `expr.is(2)` is equivalent to
+     * `expr.isSame(ce.number(2))`.
      *
-     * @category Numeric Expression
+     * @category Primitive Methods
      *
      */
-    readonly bignumRe: BigNum | undefined;
+    is(other: BoxedExpression | number | bigint | boolean | string): boolean;
     /**
-     * If this expression is a number literal, return the imaginary part as a
-     * `BigNum`.
+     * If this expression matches `pattern`, return a substitution that makes
+     * `pattern` equal to `this`. Otherwise return `null`.
      *
-     * It may be 0 if the number is real.
+     * If `pattern` includes wildcards (symbols that start
+     * with `_`), the substitution will include a prop for each matching named
+     * wildcard.
+     *
+     * If this expression matches `pattern` but there are no named wildcards,
+     * return the empty substitution, `{}`.
      *
-     * If the expression is not a number literal or the value is not available
-     * as a bignum return `undefined`. That is, the value is not upconverted
-     * to a bignum.
+     * Read more about [**patterns and rules**](/compute-engine/guides/patterns-and-rules/).
      *
-     * To get the imaginary value either as a bignum or a number, use
-     * `this.bignumIm ?? this.im`. When using this pattern, the value is
-     * returned as a bignum if available, otherwise as a number or NaN if
-     * the value is not a number literal or a symbol with a value that is a
-     * number literal.
+     * :::info[Note]
+     * Applicable to canonical and non-canonical expressions.
+     * :::
      *
-     * @category Numeric Expression
      */
-    readonly bignumIm: BigNum | undefined;
-    /**
-     * Attempt to factor a numeric coefficient `c` and a `rest` out of a
-     * canonical expression such that `rest.mul(c)` is equal to `this`.
+    match(pattern: BoxedExpression, options?: PatternMatchOptions): BoxedSubstitution | null;
+    /** If this expression is a tensor, return the tensor data.
+     * Otherwise, return `null`.
      *
-     * Attempts to make `rest` a positive value (i.e. pulls out negative sign).
+     * :::info[Note]
+     * Applicable to canonical and non-canonical expressions.
+     * :::
      *
-     *```json
-     * ['Multiply', 2, 'x', 3, 'a']
-     *    -> [NumericValue(6), ['Multiply', 'x', 'a']]
+     * @category Tensor Expression
      *
-     * ['Divide', ['Multiply', 2, 'x'], ['Multiply', 3, 'y', 'a']]
-     *    -> [NumericValue({rational: [2, 3]}), ['Divide', 'x', ['Multiply, 'y', 'a']]]
-     * ```
      */
-    toNumericValue(): [NumericValue, BoxedExpression];
-    neg(): BoxedExpression;
-    inv(): BoxedExpression;
-    abs(): BoxedExpression;
-    add(rhs: number | BoxedExpression): BoxedExpression;
-    sub(rhs: BoxedExpression): BoxedExpression;
-    mul(rhs: NumericValue | number | BoxedExpression): BoxedExpression;
-    div(rhs: number | BoxedExpression): BoxedExpression;
-    pow(exp: number | BoxedExpression): BoxedExpression;
-    root(exp: number | BoxedExpression): BoxedExpression;
-    sqrt(): BoxedExpression;
-    ln(base?: number | BoxedExpression): BoxedExpression;
+    readonly tensor: null | Tensor<any>;
     /**
      *
-     * The shape describes the axis of the expression.
+     * The **shape** describes the **axes** of the expression, where each axis
+     * represent a way to index the elements of the expression.
      *
      * When the expression is a scalar (number), the shape is `[]`.
      *
      * When the expression is a vector of length `n`, the shape is `[n]`.
      *
      * When the expression is a `n` by `m` matrix, the shape is `[n, m]`.
+     *
+     * @category Tensor Expression
+     *
      */
     readonly shape: number[];
-    /** Return 0 for a scalar, 1 for a vector, 2 for a matrix, > 2 for
-     * a multidimensional matrix.
-     *
-     * The rank is equivalent to the length of `expr.shape` */
-    readonly rank: number;
     /**
-     * Return the sign of the expression.
+     * The **rank** refers to the number of dimensions (or axes) of the
+     * expression.
      *
-     * Note that complex numbers have no natural ordering,
-     * so if the value is an imaginary number (a complex number with a non-zero
-     * imaginary part), `this.sgn` will return `unsigned`.
+     * Return 0 for a scalar, 1 for a vector, 2 for a matrix, > 2 for
+     * a multidimensional matrix.
      *
-     * If a symbol, this does take assumptions into account, that is `this.sgn`
-     * will return `positive` if the symbol is assumed to be positive
-     * (using `ce.assume()`).
+     * The rank is equivalent to the length of `expr.shape`
      *
-     * @category Numeric Expression
+     * :::info[Note]
+     * There are several definitions of rank in the literature.
+     * For example, the row rank of a matrix is the number of linearly
+     * independent rows. The rank can also refer to the number of non-zero
+     * singular values of a matrix.
+     * :::
      *
-     */
-    readonly sgn: Sign | undefined;
-    /** If the expressions cannot be compared, return `undefined`
+     * @category Tensor Expression
+     * */
+    readonly rank: number;
+    /**
      *
-     * The numeric value of both expressions are compared.
+     * The value of both expressions are compared.
      *
-     * The expressions are evaluated before being compared, which may be
-     * expensive.
+     * If the expressions cannot be compared, return `undefined`
      *
      * @category Relational Operator
      */
     isLess(other: number | BoxedExpression): boolean | undefined;
     /**
-     * The numeric value of both expressions are compared.
+     * The value of both expressions are compared.
+     *
+     * If the expressions cannot be compared, return `undefined`
      * @category Relational Operator
      */
     isLessEqual(other: number | BoxedExpression): boolean | undefined;
     /**
-     * The numeric value of both expressions are compared.
+     * The value of both expressions are compared.
+     *
+     * If the expressions cannot be compared, return `undefined`
      * @category Relational Operator
      */
     isGreater(other: number | BoxedExpression): boolean | undefined;
     /**
-     * The numeric value of both expressions are compared.
+     * The value of both expressions are compared.
+     *
+     * If the expressions cannot be compared, return `undefined`
      * @category Relational Operator
      */
     isGreaterEqual(other: number | BoxedExpression): boolean | undefined;
-    /** The numeric value of this expression is > 0, same as `isGreater(0)`
+    /**
+     * If true, the value of this expression is "Not a Number".
      *
-     * @category Numeric Expression
-     */
-    readonly isPositive: boolean | undefined;
-    /** The numeric value of this expression is >= 0, same as `isGreaterEqual(0)`
+     * 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 Numeric Expression
+     *
      */
-    readonly isNonNegative: boolean | undefined;
-    /** The numeric value of this expression is < 0, same as `isLess(0)`
+    readonly isNaN: boolean | undefined;
+    /**
+     * The numeric value of this expression is `±Infinity` or ComplexInfinity.
      *
      * @category Numeric Expression
      */
-    readonly isNegative: boolean | undefined;
-    /** The numeric value of this expression is &lt;= 0, same as `isLessEqual(0)`
+    readonly isInfinity: boolean | undefined;
+    /** This expression is a number, but not `±Infinity`, `ComplexInfinity` or
+     *  `NaN`
      *
      * @category Numeric Expression
      */
-    readonly isNonPositive: boolean | undefined;
-    /** Wikidata identifier.
+    readonly isFinite: boolean | undefined;
+    /**
+     * Wikidata identifier.
+     *
+     * If not a canonical expression, return `undefined`.
      *
-     * :::info[Note]
-     * `undefined` if not a canonical expression.
-     * :::
      */
     readonly wikidata: string | undefined;
     /** An optional short description if a symbol or function expression.
      *
      * May include markdown. Each string is a paragraph.
      *
-     * :::info[Note]
-     * `undefined` if not a canonical expression.
-     * :::
+     * If not a canonical expression, return `undefined`.
      *
      */
     readonly description: undefined | string[];
     /** An optional URL pointing to more information about the symbol or
      *  function operator.
      *
-     * :::info[Note]
-     * `undefined` if not a canonical expression.
-     * :::
+     * If not a canonical expression, return `undefined`.
      *
      */
     readonly url: string | undefined;
     /** Expressions with a higher complexity score are sorted
      * first in commutative functions
      *
-     * :::info[Note]
-     * `undefined` if not a canonical expression.
-     * :::
+     * If not a canonical expression, return `undefined`.
      */
     readonly complexity: number | undefined;
     /**
      * For symbols and functions, a definition associated with the
-     *  expression. `this.baseDefinition` is the base class of symbol and function
-     *  definition.
+     * expression. `this.baseDefinition` is the base class of symbol and function
+     * definition.
      *
-     * :::info[Note]
-     * `undefined` if not a canonical expression.
-     * :::
+     * If not a canonical expression, return `undefined`.
      *
      */
     readonly baseDefinition: BoxedBaseDefinition | undefined;
     /**
-     * For functions, a definition associated with the expression.
+     * For function expressions, the definition of the operator associated with
+     * the expression. For symbols, the definition of the symbol if it is an
+     * operator, for example `"Sin"`.
      *
-     * :::info[Note]
-     * `undefined` if not a canonical expression or not a function.
-     * :::
+     * If not a canonical expression or not a function expression,
+     * its value is `undefined`.
      *
      */
-    readonly functionDefinition: BoxedFunctionDefinition | undefined;
+    readonly operatorDefinition: BoxedOperatorDefinition | undefined;
     /**
-     * For symbols, a definition associated with the expression.
+     * For symbols, a definition associated with the expression, if it is
+     * not an operator.
      *
-     * Return `undefined` if not a symbol
+     * If not a canonical expression, or not a value, its value is `undefined`.
      *
      */
-    readonly symbolDefinition: BoxedSymbolDefinition | undefined;
+    readonly valueDefinition: BoxedValueDefinition | undefined;
     /**
      *
      * Infer the type of this expression.
      *
-     * If the type of this expression is already known, return `false`.
+     * For symbols, inference may take place for undeclared symbols,
+     * symbols with an `unknown` type, or symbols with an inferred type.
      *
-     * If the type was not set, set it to the inferred type, return `true`
-     * If the type was previously inferred, widen it and return `true`.
+     * Constant symbols always have a defined type, and will return `false`.
+     *
+     * For functions, inference only takes place if it has an *inferred
+     * signature*.
+     *
+     *
+     * For a successful inference, *narrows* the type for symbols,
+     * and for functions, narrows the *(return) type*.
+     *
+     * Subsequent inferences can be made and will refine previous ones if valid.
+     *
+     * If the given type is incompatible with the declared or previously inferred
+     * type, return `false`.
      *
-     * If the type cannot be inferred, return `false`.
      *
      * @internal
      */
-    infer(t: Type): boolean;
+    infer(t: Type, inferenceMode?: 'narrow' | 'widen'): boolean;
     /**
      * Update the definition associated with this expression, using the
      * current scope (`ce.context`).
@@ -947,23 +1232,18 @@ export interface BoxedExpression {
     /**
      * Return the value of the canonical form of this expression.
      *
-     * A pure expression always return the same value and has no side effects.
-     * 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.
+     * A pure expression always returns the same value (provided that it
+     * remains constant / values of sub-expressions or symbols do not change),
+     * and has no side effects.
      *
-     * The result may be a rational number or the product of a rational number
-     * and the square root of an integer.
+     * Evaluating an impure expression may return a varying value, and may have
+     * some side effects such as adjusting symbol assumptions.
      *
      * To perform approximate calculations, use `expr.N()` instead,
-     * or set `options.numericApproximation` to `true`.
+     * or call with `options.numericApproximation` to `true`.
      *
-     * The result of `expr.evaluate()` may be the same as `expr.simplify()`.
+     * It is possible that the result of `expr.evaluate()` may be the same as
+     * `expr.simplify()`.
      *
      * The result is in canonical form.
      *
@@ -1000,72 +1280,101 @@ export interface BoxedExpression {
      *
      *
      * ```javascript
-     * const expr = ce.parse('x^2 + y^2');
+     * const expr = ce.parse("x^2 + y^2");
      * const f = expr.compile();
      * console.log(f({x: 2, y: 3}));
+     * // -> 13
      * ```
+     *
+     * If the expression is a function literal, the function takes the
+     * arguments of the function as arguments, and returns the value of the
+     * expression.
+     *
+     * ```javascript
+     * const expr = ce.parse("(x) \mapsto 2x");
+     * const f = expr.compile();
+     * console.log(f(42));
+     * // -> 84
+     * ```
+     *
+     * If the expression cannot be compiled, a JS function is returned that
+     * falls back to the interpreting the expression, unless the
+     * `options.fallback` is set to `false`. If it is set to `false`, the
+     * function will throw an error if it cannot be compiled.
+     *
      */
     compile(options?: {
         to?: 'javascript';
-        optimize?: ('simplify' | 'evaluate')[];
-        functions?: Record<MathJsonIdentifier, JSSource | ((...any: any[]) => any)>;
-        vars?: Record<MathJsonIdentifier, CompiledType>;
-        imports?: unknown[];
+        functions?: Record<MathJsonSymbol, JSSource | ((...any: any[]) => any)>;
+        vars?: Record<MathJsonSymbol, CompiledType>;
+        imports?: ((...any: any[]) => any)[];
         preamble?: string;
-    }): (args?: Record<string, CompiledType>) => CompiledType;
+        fallback?: boolean;
+    }): ((...args: any[]) => any) & {
+        isCompiled?: boolean;
+    };
     /**
      * If this is an equation, solve the equation for the variables in vars.
      * Otherwise, solve the equation `this = 0` for the variables in vars.
      *
      *
      * ```javascript
-     * const expr = ce.parse('x^2 + 2*x + 1 = 0');
-     * console.log(expr.solve('x'));
+     * const expr = ce.parse("x^2 + 2*x + 1 = 0");
+     * console.log(expr.solve("x"));
      * ```
      *
      *
      */
     solve(vars?: Iterable<string> | string | BoxedExpression | Iterable<BoxedExpression>): null | ReadonlyArray<BoxedExpression>;
     /**
-     * Return a JavaScript primitive representing the value of this expression.
+     * If this expression is a number literal, a string literal or a function
+     *  literal, return the expression.
      *
-     * Equivalent to `expr.N().valueOf()`.
+     * If the expression is a symbol, return the value of the symbol.
+     *
+     * Otherwise, the expression is a symbolic expression, including an unknown
+     * symbol, i.e. a symbol with no value, return `undefined`.
      *
      */
-    get value(): number | boolean | string | object | undefined;
+    get value(): BoxedExpression | undefined;
     /**
-     * Only the value of variables can be changed (symbols that are not
-     * constants).
+     * If the expression is a symbol, set the value of the symbol.
      *
-     * Throws a runtime error if a constant.
+     * Will throw a runtime error if either not a symbol, or a symbol with the
+     * `constant` flag set to `true`.
      *
-     * :::info[Note]
-     * If non-canonical, does nothing
-     * :::
+     * Setting the value of a symbol results in the forgetting of all assumptions
+     * about it in the current scope.
      *
      */
-    set value(value: boolean | string | BigNum | {
-        re: number;
-        im: number;
-    } | {
-        num: number;
-        denom: number;
-    } | number[] | BoxedExpression | number | undefined);
+    set value(value: boolean | string | BigNum | OneOf<[
+        {
+            re: number;
+            im: number;
+        },
+        {
+            num: number;
+            denom: number;
+        },
+        BoxedExpression
+    ]> | number[] | number | undefined);
     /**
      *
      * The type of the value of this expression.
      *
+     * If a symbol the type of the value of the symbol.
+     *
      * If a function expression, the type of the value of the function
      * (the result type).
      *
-     * If a symbol the type of the value of the symbol.
+     * If a symbol with a `"function"` type (a function literal), returns the
+     * signature.
      *
-     * :::info[Note]
      * If not valid, return `"error"`.
-     * If non-canonical, return `undefined`.
+     *
      * If the type is not known, return `"unknown"`.
-     * :::
      *
+     * @category Type Properties
      */
     get type(): BoxedType;
     set type(type: Type | TypeString | BoxedType);
@@ -1128,9 +1437,10 @@ export interface BoxedExpression {
      * considered equal. This tolerance is set when the `engine.precision` is
      * changed to be such that the last two digits are ignored.
      *
-     * The evaluations may be expensive operations. Other options to consider
+     * Evaluating the expressions may be expensive. Other options to consider
      * to compare two expressions include:
-     * - `expr.isSame(other)` for a structural comparison
+     * - `expr.isSame(other)` for a structural comparison which does not involve
+     *   evaluating the expressions.
      * - `expr.is(other)` for a comparison of a number literal
      *
      * **Examples**
@@ -1152,29 +1462,51 @@ export interface BoxedExpression {
      */
     isEqual(other: number | BoxedExpression): boolean | undefined;
     /**
-     * Return true if the expression is a collection: a list, a vector, a matrix, a map, a tuple, etc...
+     * Is `true` if the expression is a collection.
+     *
+     * When `isCollection` is `true`, the expression:
+     *
+     * - has an `each()` method that returns a generator over the elements
+     *   of the collection.
+     * - has a `size` property that returns the number of elements in the
+     *   collection.
+     * - has a `contains(other)` method that returns `true` if the `other`
+     *   expression is in the collection.
+     *
      */
     isCollection: boolean;
     /**
-     * If this is a collection, return true if the `rhs` expression is in the
-     * collection.
+     * Is `true` if this is an indexed collection, such as a list, a vector,
+     * a matrix, a tuple, etc...
      *
-     * Return `undefined` if the membership cannot be determined.
+     * The elements of an indexed collection can be accessed by a one-based
+     * index.
+     *
+     * When `isIndexedCollection` is `true`, the expression:
+     * - has an `each()`, `size()` and `contains(rhs)` methods
+     *    as for a collection.
+     * - has an `at(index: number)` method that returns the element at the
+     *    specified index.
+     * - has an `indexWhere(predicate: (element: BoxedExpression) => boolean)`
+     *    method that returns the index of the first element that matches the
+     *    predicate.
      */
-    contains(rhs: BoxedExpression): boolean | undefined;
+    isIndexedCollection: boolean;
     /**
-     * If this is a collection, return the number of elements in the collection.
+     * False if not a collection, or if the elements of the collection
+     * are not computed lazily.
      *
-     * If the collection is infinite, return `Infinity`.
+     * The elements of a lazy collection are computed on demand, when
+     * iterating over the collection using `each()`.
+     *
+     * Use `ListFrom` and related functions to create eager collections from
+     * lazy collections.
      *
      */
-    get size(): number;
+    isLazyCollection: boolean;
     /**
-     * If this is a collection, return an iterator over the elements of the collection.
-     *
-     * If `start` is not specified, start from the first element.
-     *
-     * If `count` is not specified or negative, return all the elements from `start` to the end.
+     * If this is a collection, return an iterator over the elements of the
+     * collection.
      *
      * ```js
      * const expr = ce.parse('[1, 2, 3, 4]');
@@ -1183,25 +1515,62 @@ export interface BoxedExpression {
      * }
      * ```
      */
-    each: (start?: number, count?: number) => Iterator<BoxedExpression, undefined>;
-    /** If this is an indexable collection, return the element at the specified
-     *  index.
+    each(): Generator<BoxedExpression>;
+    /**
+     * If this is a collection, return true if the `rhs` expression is in the
+     * collection.
+     *
+     * Return `undefined` if the membership cannot be determined without
+     * iterating over the collection.
+     */
+    xcontains(rhs: BoxedExpression): boolean | undefined;
+    /**
+     * Check if this collection is a subset of another collection.
+     *
+     * @param other The other collection to check against.
+     * @param strict If true, the subset relation is strict (i.e., proper subset).
+     */
+    subsetOf(other: BoxedExpression, strict: boolean): boolean | undefined;
+    /**
+     * If this is a collection, return the number of elements in the collection.
+     *
+     * If the collection is infinite, return `Infinity`.
+     *
+     * If the number of elements cannot be determined, return `undefined`, for
+     * example, if the collection is lazy and not finite and the size cannot
+     * be determined without iterating over the collection.
+     *
+     */
+    get xsize(): number | undefined;
+    /** If this is a finite collection, return true. */
+    isFiniteCollection: boolean | undefined;
+    /** If this is an empty collection, return true.
+     *
+     * An empty collection has a size of 0.
+     */
+    isEmptyCollection: boolean | undefined;
+    /** If this is an indexed collection, return the element at the specified
+     *  index. The first element is at index 1.
      *
      * If the index is negative, return the element at index `size() + index + 1`.
      *
+     * The last element is at index -1.
+     *
      */
     at(index: number): BoxedExpression | undefined;
-    /** If this is a map or a tuple, return the value of the corresponding key.
+    /** If this is a keyed collection (map, record, tuple), return the value of
+     * the corresponding key.
      *
      * If `key` is a `BoxedExpression`, it should be a string.
      *
      */
     get(key: string | BoxedExpression): BoxedExpression | undefined;
     /**
-     * If this is an indexable collection, return the index of the first element
-     * that matches the target expression.
+     * If this is an indexed collection, return the index of the first element
+     * that matches the predicate.
+     *
      */
-    indexOf(expr: BoxedExpression): number | undefined;
+    indexWhere(predicate: (element: BoxedExpression) => boolean): number | undefined;
 }
 /** A semi boxed expression is a MathJSON expression which can include some
  * boxed terms.
@@ -1211,7 +1580,17 @@ export interface BoxedExpression {
  *
  * @category Boxed Expression
  */
-export type SemiBoxedExpression = number | bigint | string | BigNum | MathJsonNumber | MathJsonString | MathJsonSymbol | MathJsonFunction | readonly [MathJsonIdentifier, ...SemiBoxedExpression[]] | BoxedExpression;
+export type SemiBoxedExpression = number | bigint | string | BigNum | MathJsonNumberObject | MathJsonStringObject | MathJsonSymbolObject | MathJsonFunctionObject | MathJsonDictionaryObject | readonly [MathJsonSymbol, ...SemiBoxedExpression[]] | BoxedExpression;
+/** Interface for dictionary-like structures.
+ * Use `isDictionary()` to check if an expression is a dictionary.
+ */
+export interface DictionaryInterface {
+    get(key: string): BoxedExpression | undefined;
+    has(key: string): boolean;
+    get keys(): string[];
+    get entries(): [string, BoxedExpression][];
+    get values(): BoxedExpression[];
+}
 /**
  * These handlers compare two expressions.
  *
@@ -1341,7 +1720,7 @@ export type ReplaceOptions = {
     useVariations: boolean;
     /**
      * If `iterationLimit` > 1, the rules will be repeatedly applied
-     * until no rules apply, up to `maxIterations` times.
+     * until no rules apply, up to `iterationLimit` times.
      *
      * Note that if `once` is true, `iterationLimit` has no effect.
      *
@@ -1357,49 +1736,57 @@ export type ReplaceOptions = {
 };
 /**
  * A bound symbol (i.e. one with an associated definition) has either a type
- * (e.g. ∀ x ∈ ℝ), a value (x = 5) or both (π: value = 3.14... type = 'real')
+ * (e.g. ∀ x ∈ ℝ), a value (x = 5) or both (π: value = 3.14... type = 'real').
+ *
  * @category Definitions
  */
-export type SymbolDefinition = BaseDefinition & Partial<SymbolAttributes> & {
-    type?: Type | TypeString;
+export type ValueDefinition = BaseDefinition & {
+    holdUntil: 'never' | 'evaluate' | 'N';
+    type: Type | TypeString | BoxedType;
     /** If true, the type is inferred, and could be adjusted later
      * as more information becomes available or if the symbol is explicitly
      * declared.
      */
-    inferred?: boolean;
+    inferred: boolean;
     /** `value` can be a JS function since for some constants, such as
      * `Pi`, the actual value depends on the `precision` setting of the
      * `ComputeEngine` and possible other environment settings */
-    value?: LatexString | SemiBoxedExpression | ((ce: ComputeEngine) => BoxedExpression | null);
-    flags?: Partial<NumericFlags>;
-    eq?: (a: BoxedExpression) => boolean | undefined;
-    neq?: (a: BoxedExpression) => boolean | undefined;
-    cmp?: (a: BoxedExpression) => '=' | '>' | '<' | undefined;
-    collection?: Partial<CollectionHandlers>;
+    value: LatexString | SemiBoxedExpression | ((ce: ComputeEngine) => BoxedExpression | null);
+    eq: (a: BoxedExpression) => boolean | undefined;
+    neq: (a: BoxedExpression) => boolean | undefined;
+    cmp: (a: BoxedExpression) => '=' | '>' | '<' | undefined;
+    collection: CollectionHandlers;
 };
 /**
  * Definition record for a function.
  * @category Definitions
  *
  */
-export type FunctionDefinition = BaseDefinition & Partial<FunctionDefinitionFlags> & {
+export type OperatorDefinition = Partial<BaseDefinition> & Partial<OperatorDefinitionFlags> & {
     /**
-     * The function signature.
+     * The function signature, describing the type of the arguments and the
+     * return type.
      *
      * If a `type` handler is provided, the return type of the function should
      * be a subtype of the return type in the signature.
      *
      */
-    signature?: Type | TypeString;
+    signature?: Type | TypeString | BoxedType;
     /**
-     * The actual type of the result based on the arguments.
+     * The type of the result (return type) based on the type of
+     * the arguments.
+     *
+     * Should be a subtype of the type indicated by the signature.
      *
-     * Should be a subtype of the type indicated in the signature.
+     * For example, if the signature is `(number) -> real`, the type of the
+     * result could be `real` or `integer`, but not `complex`.
      *
+     * :::info[Note]
      * Do not evaluate the arguments.
      *
-     * The type of the arguments can be used to determine the type of the
-     * result.
+     * However, the type of the arguments can be used to determine the type of
+     * the result.
+     * :::
      *
      */
     type?: (ops: ReadonlyArray<BoxedExpression>, options: {
@@ -1414,14 +1801,36 @@ export type FunctionDefinition = BaseDefinition & Partial<FunctionDefinitionFlag
      *
      * Do not evaluate the arguments.
      *
-     * The type and sign of the arguments can be used to determine the sign.
+     * However, the type and sign of the arguments can be used to determine the
+     * sign.
      *
      */
     sgn?: (ops: ReadonlyArray<BoxedExpression>, options: {
         engine: ComputeEngine;
     }) => Sign | undefined;
-    /** Return true of the function expression is even, false if it is odd and
-     * undefined if it is neither.
+    /** The value of this expression is > 0, same as `isGreater(0)`
+     *
+     * @category Numeric Expression
+     */
+    readonly isPositive?: boolean | undefined;
+    /** The value of this expression is >= 0, same as `isGreaterEqual(0)`
+     *
+     * @category Numeric Expression
+     */
+    readonly isNonNegative?: boolean | undefined;
+    /** The value of this expression is &lt; 0, same as `isLess(0)`
+     *
+     * @category Numeric Expression
+     */
+    readonly isNegative?: boolean | undefined;
+    /** The  value of this expression is &lt;= 0, same as `isLessEqual(0)`
+     *
+     * @category Numeric Expression
+     */
+    readonly isNonPositive?: boolean | undefined;
+    /** Return `true` if the function expression is even, `false` if it is odd
+     * and `undefined` if it is neither (for example if it is not a number,
+     * or if it is a complex number).
      */
     even?: (ops: ReadonlyArray<BoxedExpression>, options: {
         engine: ComputeEngine;
@@ -1453,12 +1862,13 @@ export type FunctionDefinition = BaseDefinition & Partial<FunctionDefinitionFlag
      * The arguments (`args`) may not be in canonical form. If necessary, they
      * can be put in canonical form.
      *
-     * This handler should validate the type and number of the arguments.
+     * This handler should validate the type and number of the arguments
+     * (arity).
      *
      * 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 an
-     * ["Error", "'unexpected-argument'"]` error expression
+     * `["Error", "'unexpected-argument'"]` error expression
      *
      * If the type of an argument is not compatible, it should be indicated
      * with an `incompatible-type` error.
@@ -1480,19 +1890,20 @@ export type FunctionDefinition = BaseDefinition & Partial<FunctionDefinitionFlag
      *
      * 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`.
+     * 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?: (ops: ReadonlyArray<BoxedExpression>, options: {
         engine: ComputeEngine;
+        scope: Scope | undefined;
     }) => BoxedExpression | null;
     /**
      * Evaluate a function expression.
      *
-     * The arguments have been evaluated, except the arguments to which a
-     * `hold` applied.
+     * When the handler is invoked, the arguments have been evaluated, except
+     * if the `lazy` option is set to `true`.
      *
      * It is not necessary to further simplify or evaluate the arguments.
      *
@@ -1501,19 +1912,15 @@ export type FunctionDefinition = BaseDefinition & Partial<FunctionDefinitionFlag
      * number or a square root, rather than a floating point approximation.
      * Use `ce.number()` to create the numeric value.
      *
-     * When `numericalApproximation` is `false`, return a floating point number:
-     * - do not reduce rational numbers to decimal (floating point approximation)
-     * - do not reduce square roots of rational numbers
-     *
      * If the expression cannot be evaluated, due to the values, types, or
-     * assumptions about its arguments, for example, return `undefined` or
+     * assumptions about its arguments, return `undefined` or
      * an `["Error"]` expression.
      */
     evaluate?: ((ops: ReadonlyArray<BoxedExpression>, options: EvaluateOptions & {
         engine: ComputeEngine;
     }) => BoxedExpression | undefined) | BoxedExpression;
     /**
-     * An option asynchronous version of `evaluate`.
+     * An asynchronous version of `evaluate`.
      *
      */
     evaluateAsync?: (ops: ReadonlyArray<BoxedExpression>, options: EvaluateOptions & {
@@ -1526,28 +1933,44 @@ export type FunctionDefinition = BaseDefinition & Partial<FunctionDefinitionFlag
         engine: ComputeEngine;
     }) => BoxedExpression;
     /** Return a compiled (optimized) expression. */
-    compile?: (expr: BoxedExpression) => CompiledExpression;
+    xcompile?: (expr: BoxedExpression) => CompiledExpression;
     eq?: (a: BoxedExpression, b: BoxedExpression) => boolean | undefined;
     neq?: (a: BoxedExpression, b: BoxedExpression) => boolean | undefined;
-    collection?: Partial<CollectionHandlers>;
+    collection?: CollectionHandlers;
 };
 /**
+ * Metadata common to both symbols and functions.
+ *
  * @category Definitions
  *
  */
-export type BaseDefinition = {
-    /** A short (about 1 line) description. May contain Markdown. */
-    description?: string | string[];
+export interface BaseDefinition {
+    /**
+     * If a string, a short description, about one line long.
+     *
+     * Otherwise, a list of strings, each string a paragraph.
+     *
+     * May contain Markdown.
+     */
+    description: string | string[];
+    /** A list of examples of how to use this symbol or operator.
+     *
+     * Each example is a string, which can be a MathJSON expression or LaTeX, bracketed by `$` signs.
+     * For example, `["Add", 1, 2]` or `$\\sin(\\pi/4)$`.
+     */
+    examples: string | string[];
     /** A URL pointing to more information about this symbol or operator. */
-    url?: string;
+    url: string;
     /**
      * A short string representing an entry in a wikibase.
      *
-     * For example `Q167` is the [wikidata entry](https://www.wikidata.org/wiki/Q167)
+     * For example `"Q167"` is the [wikidata entry](https://www.wikidata.org/wiki/Q167)
      * for the `Pi` constant.
      */
-    wikidata?: string;
-};
+    wikidata: string;
+    /** If true, the value or type of the definition cannot be changed */
+    readonly isConstant?: boolean;
+}
 /** Options for `BoxedExpression.simplify()`
  *
  * @category Boxed Expression
@@ -1567,9 +1990,9 @@ export type SimplifyOptions = {
     costFunction?: (expr: BoxedExpression) => number;
 };
 /**
- * A table mapping identifiers to their definition.
+ * A table mapping symbols to their definition.
  *
- * Identifiers should be valid MathJSON identifiers. In addition, the
+ * Symbols should be valid MathJSON symbols. In addition, the
  * following rules are recommended:
  *
  * - Use only latin letters, digits and `-`: `/[a-zA-Z0-9-]+/`
@@ -1579,18 +2002,34 @@ export type SimplifyOptions = {
  * @category Definitions
  *
  */
-export type IdentifierDefinition = OneOf<[
-    SymbolDefinition,
-    FunctionDefinition,
-    SemiBoxedExpression
-]>;
+export type SymbolDefinition = OneOf<[ValueDefinition, OperatorDefinition]>;
 /**
  * @category Definitions
  *
  */
-export type IdentifierDefinitions = Readonly<{
-    [id: string]: IdentifierDefinition;
+export type SymbolDefinitions = Readonly<{
+    [id: string]: Partial<SymbolDefinition>;
 }>;
+/**
+ * When a unitless value is passed to or returned from a trigonometric function,
+ * the angular unit of the value.
+ *
+ * | Angular Unit | Description |
+ * |:--------------|:-------------|
+ * | `rad` | radians, 2π radians is a full circle |
+ * | `deg` | degrees, 360 degrees is a full circle |
+ * | `grad` | gradians, 400 gradians is a full circle |
+ * | `turn` | turns, 1 turn is a full circle |
+ *
+ * To change the angular unit used by the Compute Engine, use:
+ *
+ * ```js
+ * ce.angularUnit = 'deg';
+ * ```
+ *
+ * @category Compute Engine
+ */
+export type AngularUnit = 'rad' | 'deg' | 'grad' | 'turn';
 /** @category Numerics */
 export type Sign = 
 /** The expression is equal to 0 */
@@ -1605,248 +2044,226 @@ export type Sign =
  | 'non-positive'
 /** The expression is not equal to 0 (possibly with an imaginary part) and isPositive, isNegative, isUnsigned are all false or undefined */
  | 'not-zero'
-/** The expression has no imaginary part and a non-zero real part and isPositive and isNegative are false or undefined*/
- | 'real-not-zero'
-/** The expression has no imaginary part and isNotZero,isPositive,isNegative,isNonNegative,isNonPositive,isZero are either false or undefined*/
- | 'real'
-/** The expression is NaN */
- | 'nan'
-/** The expression is +∞ */
- | 'positive-infinity'
-/** The expression is -∞ */
- | 'negative-infinity'
-/** The expression is ~∞ */
- | 'complex-infinity'
 /** The expression has an imaginary part or is NaN */
  | 'unsigned';
-/**
- * When used in a `SymbolDefinition` or `Functiondefinition` these flags
- * provide additional information about the value of the symbol or function.
- *
- * If provided, they will override the value derived from
- * the symbol's value.
- *
- * @category Definitions
- */
-export type NumericFlags = {
-    sgn: Sign | undefined;
-    even: boolean | undefined;
-    odd: boolean | undefined;
-};
 /**
  * These handlers are the primitive operations that can be performed on
- * collections.
- *
- * There are two types of collections:
- *
- * - finite collections, such as lists, tuples, sets, matrices, etc...
- *  The `size()` handler of finite collections returns the number of elements
- *
- * - infinite collections, such as sequences, ranges, etc...
- *  The `size()` handler of infinite collections returns `Infinity`
- *  Infinite collections are not indexable: they have no `at()` handler.
+ * all collections, indexed or not.
  *
  *  @category Definitions
  */
-export type CollectionHandlers = {
+export interface BaseCollectionHandlers {
+    /**
+     * Return an iterator that iterates over the elements of the collection.
+     *
+     * The order in which the elements are returned is not defined. Requesting
+     * two iterators on the same collection may return the elements in a
+     * different order.
+     *
+     * @category Definitions
+     */
+    iterator: (collection: BoxedExpression) => Iterator<BoxedExpression, undefined> | undefined;
     /** Return the number of elements in the collection.
      *
-     * An empty collection has a size of 0.
+     * An empty collection has a count of 0.
+     */
+    count: (collection: BoxedExpression) => number | undefined;
+    /** Optional flag to quickly check if the collection is empty, without having to count exactly how may elements it has (useful for lazy evaluation). */
+    isEmpty?: (collection: BoxedExpression) => boolean | undefined;
+    /** Optional flag to quickly check if the collection is finite, without having to count exactly how many elements it has (useful for lazy evaluation). */
+    isFinite?: (collection: BoxedExpression) => boolean | undefined;
+    /** Return `true` if the collection is lazy, `false` otherwise.
+     * If the collection is lazy, it means that the elements are not
+     * computed until they are needed, for example when iterating over the
+     * collection.
+     *
+     * Default: `true`
      */
-    size: (collection: BoxedExpression) => number;
+    isLazy?: (collection: BoxedExpression) => boolean;
     /**
-     * Return `true` if the target
-     * expression is in the collection, `false` otherwise.
+     * Return `true` if the target expression is in the collection,
+     * `false` otherwise.
+     *
+     * Return `undefined` if the membership cannot be determined.
      */
-    contains: (collection: BoxedExpression, target: BoxedExpression) => boolean;
-    /** Return an iterator
-     * - start is optional and is a 1-based index.
-     * - if start is not specified, start from index 1
-     * - count is optional and is the number of elements to return
-     * - if count is not specified or negative, return all the elements from
-     *   start to the end
+    contains?: (collection: BoxedExpression, target: BoxedExpression) => boolean | undefined;
+    /**
+     * Return `true` if all the elements of `other` are in `collection`.
+     * Both `collection` and `other` are collections.
      *
-     * If there is a `keys()` handler, there is no `iterator()` handler.
+     * If strict is `true`, the subset must be strict, that is, `collection` must
+     * have more elements than `other`.
      *
-     * @category Definitions
+     * Return `undefined` if the subset relation cannot be determined.
      */
-    iterator: (collection: BoxedExpression, start?: number, count?: number) => Iterator<BoxedExpression, undefined>;
+    subsetOf?: (collection: BoxedExpression, other: BoxedExpression, strict: boolean) => boolean | undefined;
+    /** Return the sign of all the elements of the collection. */
+    eltsgn?: (collection: BoxedExpression) => Sign | undefined;
+    /** Return the widest type of all the elements in the collection */
+    elttype?: (collection: BoxedExpression) => Type | undefined;
+}
+/**
+ * These additional collection handlers are applicable to indexed
+ * collections only.
+ *
+ * The elements of an indexed collection can be accessed by index, and
+ * the order of the elements is defined.
+ *
+ *  @category Definitions
+ */
+export interface IndexedCollectionHandlers {
     /**
      * Return the element at the specified index.
      *
      * The first element is `at(1)`, the last element is `at(-1)`.
      *
-     * If the index is &lt;0, return the element at index `size() + index + 1`.
+     * If the index is &lt;0, return the element at index `count() + index + 1`.
      *
-     * The index can also be a string for example for maps. The set of valid keys
-     * is returned by the `keys()` handler.
+     * The index can also be a string for example for records. The set of valid
+     * keys is returned by the `keys()` handler.
      *
      * If the index is invalid, return `undefined`.
      */
     at: (collection: BoxedExpression, index: number | string) => undefined | BoxedExpression;
     /**
-     * If the collection can be indexed by strings, return the valid values
-     * for the index.
-     */
-    keys: (collection: BoxedExpression) => undefined | Iterable<string>;
-    /**
-     * Return the index of the first element that matches the target expression.
+     * Return the index of the first element that matches the predicate.
      *
-     * The comparison is done using the `target.isEqual()` method.
-     *
-     * If the expression is not found, return `undefined`.
-     *
-     * If the expression is found, return the index, 1-based.
-     *
-     * Return the index of the first match.
-     *
-     * `from` is the starting index for the search. If negative, start from
-     * the end  and search backwards.
+     * If no element matches the predicate, return `undefined`.
      */
-    indexOf: (collection: BoxedExpression, target: BoxedExpression, from?: number) => number | undefined;
-    /**
-     * Return `true` if all the elements of `target` are in `expr`.
-     * Both `expr` and `target` are collections.
-     * If strict is `true`, the subset must be strict, that is, `expr` must
-     * have more elements than `target`.
-     */
-    subsetOf: (collection: BoxedExpression, target: BoxedExpression, strict: boolean) => boolean;
-    /** Return the sign of all the elements of the collection. */
-    eltsgn: (collection: BoxedExpression) => Sign | undefined;
-    /** Return the widest type of all the elements in the collection */
-    elttype: (collection: BoxedExpression) => Type | undefined;
+    indexWhere: (collection: BoxedExpression, predicate: (element: BoxedExpression) => boolean) => number | undefined;
+}
+/**
+ * The collection handlers are the primitive operations that can be
+ * performed on collections, such as lists, sets, tuples, etc...
+ *
+ *  @category Definitions
+ */
+export type CollectionHandlers = BaseCollectionHandlers & Partial<IndexedCollectionHandlers>;
+/**
+ *
+ * The definition for a value, represented as a tagged object literal.
+ * @category Definitions
+ *
+ */
+export type TaggedValueDefinition = {
+    value: BoxedValueDefinition;
 };
 /**
+ *
+ * The definition for an operator, represented as a tagged object literal.
+ *
  * @category Definitions
  *
  */
-export interface BoxedBaseDefinition {
-    name: string;
-    wikidata?: string;
-    description?: string | string[];
-    url?: string;
-    /**
-     * The scope this definition belongs to.
-     *
-     * This field is usually undefined, but its value is set by `getDefinition()`
-     */
-    scope: RuntimeScope | undefined;
+export type TaggedOperatorDefinition = {
+    operator: BoxedOperatorDefinition;
+};
+/**
+ * A definition can be either a value or an operator.
+ *
+ * It is collected in a tagged object literal, instead of being a simple union
+ * type, so that the type of the definition can be changed while keeping
+ * references to the definition in bound expressions.
+ *
+ * @category Definitions
+ *
+ */
+export type BoxedDefinition = TaggedValueDefinition | TaggedOperatorDefinition;
+/**
+ * @category Definitions
+ *
+ */
+export interface BoxedBaseDefinition extends Partial<BaseDefinition> {
     /** If this is the definition of a collection, the set of primitive operations
      * that can be performed on this collection (counting the number of elements,
-     * enumerating it, etc...). */
-    collection?: Partial<CollectionHandlers>;
-    /** When the environment changes, for example the numerical precision,
-     * call `reset()` so that any cached values can be recalculated.
+     * enumerating it, etc...).
      */
-    reset(): void;
+    collection?: CollectionHandlers;
 }
 /**
- * @category Definitions
  *
+ * @category Definitions
  */
-export type SymbolAttributes = {
-    /**
-     * If `true` the value of the symbol is constant. The value or type of
-     * symbols with this attribute set to `true` cannot be changed.
-     *
-     * If `false`, the symbol is a variable.
-     *
-     * **Default**: `false`
-     */
-    constant: boolean;
+export interface BoxedValueDefinition extends BoxedBaseDefinition {
     /**
-     * If the symbol has a value, it is held as indicated in the table below.
-     * A green checkmark indicate that the symbol is substituted.
+      * If the symbol has a value, it is held as indicated in the table below.
+      * A green checkmark indicate that the symbol is substituted.
   
-  <div className="symbols-table">
+    <div className="symbols-table">
   
-  | Operation     | `"never"` | `"evaluate"` | `"N"` |
-  | :---          | :-----:   | :----:      | :---:  |
-  | `canonical()` |    (X)    |              |       |
-  | `evaluate()`  |    (X)    |     (X)      |       |
-  | `"N()"`       |    (X)    |     (X)      |  (X)  |
+    | Operation     | `"never"` | `"evaluate"` | `"N"` |
+    | :---          | :-----:   | :----:      | :---:  |
+    | `canonical()` |    (X)    |              |       |
+    | `evaluate()`  |    (X)    |     (X)      |       |
+    | `"N()"`       |    (X)    |     (X)      |  (X)  |
   
-  </div>
+    </div>
   
-    * Some examples:
-    * - `ImaginaryUnit` has `holdUntil: 'never'`: it is substituted during canonicalization
-    * - `x` has `holdUntil: 'evaluate'` (variables)
-    * - `Pi` has `holdUntil: 'N'` (special numeric constant)
-    *
-    * **Default:** `evaluate`
-    */
+      * Some examples:
+      * - `ImaginaryUnit` has `holdUntil: 'never'`: it is substituted during canonicalization
+      * - `x` has `holdUntil: 'evaluate'` (variables)
+      * - `Pi` has `holdUntil: 'N'` (special numeric constant)
+      *
+      * **Default:** `evaluate`
+      */
     holdUntil: 'never' | 'evaluate' | 'N';
-};
-/**
- * @category Definitions
- */
-export interface BoxedSymbolDefinition extends BoxedBaseDefinition, SymbolAttributes, Partial<NumericFlags> {
-    get value(): BoxedExpression | undefined;
-    set value(val: BoxedExpression | number | undefined);
-    readonly isFunction: boolean;
-    readonly isConstant: boolean;
+    /** This is either the initial value of the symbol (i.e. when a new
+     *  evaluation context is created), or its constant value, if a constant.
+     *  Otherwise, the current value is tracked in the evaluation context.
+     *
+     */
+    readonly value: BoxedExpression | undefined;
     eq?: (a: BoxedExpression) => boolean | undefined;
     neq?: (a: BoxedExpression) => boolean | undefined;
     cmp?: (a: BoxedExpression) => '=' | '>' | '<' | undefined;
+    /**
+     * True if the type has been inferred. An inferred type can be updated as
+     * more information becomes available.
+     *
+     * A type that is not inferred, but has been set explicitly, cannot be updated.
+     */
     inferredType: boolean;
     type: BoxedType;
 }
 /**
- * A scope is a set of names in a dictionary that are bound (defined) in
- * a MathJSON expression.
- *
- * Scopes are arranged in a stack structure. When an expression that defined
- * a new scope is evaluated, the new scope is added to the scope stack.
- * Outside of the expression, the scope is removed from the scope stack.
- *
- * The scope stack is used to resolve symbols, and it is possible for
- * a scope to 'mask' definitions from previous scopes.
- *
- * Scopes are lexical (also called a static scope): they are defined based on
- * where they are in an expression, they are not determined at runtime.
- *
- * @category Compute Engine
- */
-export type Scope = Record<string, any>;
-/** Options for `BoxedExpression.evaluate()`
- *
- * @category Boxed Expression
- */
-export type EvaluateOptions = {
-    numericApproximation: boolean;
-    signal: AbortSignal;
-};
-/**
- * A function definition can have some flags to indicate specific
- * properties of the function.
+ * An operator definition can have some flags to indicate specific
+ * properties of the operator.
  * @category Definitions
  */
-export type FunctionDefinitionFlags = {
+export type OperatorDefinitionFlags = {
     /**
-     * If `true`, the arguments to this function are not automatically
+     * If `true`, the arguments to this operator are not automatically
      * evaluated. The default is `false` (the arguments are evaluated).
      *
-     * This can be useful for example for functions that take symbolic
-     * expressions as arguments, such as `D` or `Integrate`.
+     * This can be useful for example for operators that take symbolic
+     * expressions as arguments, such as `Declare` or `Integrate`.
      *
-     * This is also useful for functions that take an argument that is
+     * This is also useful for operators that take an argument that is
      * potentially an infinite collection.
      *
      * It will be up to the `evaluate()` handler to evaluate the arguments as
-     * needed. This is conveninent to pass symbolic expressions as arguments
-     * to functions without having to explicitly use a `Hold` expression.
+     * needed. This is convenient to pass symbolic expressions as arguments
+     * to operators without having to explicitly use a `Hold` expression.
      *
      * This also applies to the `canonical()` handler.
      *
      */
     lazy: boolean;
-    /**  If `true`, the function is applied element by element to lists, matrices
+    /**
+     * If `true`, the operator requires a new lexical scope when canonicalized.
+     * This will allow it to declare variables that are not visible outside
+     * the function expression using the operator.
+     *
+     * **Default**: `false`
+     */
+    scoped: boolean;
+    /**  If `true`, the operator is applied element by element to lists, matrices
      * (`["List"]` or `["Tuple"]` expressions) and equations (relational
      * operators).
      *
      * **Default**: `false`
      */
-    threadable: boolean;
+    broadcastable: boolean;
     /** If `true`, `["f", ["f", a], b]` simplifies to `["f", a, b]`
      *
      * **Default**: `false`
@@ -1867,10 +2284,10 @@ export type FunctionDefinitionFlags = {
      *
      */
     commutativeOrder: ((a: BoxedExpression, b: BoxedExpression) => number) | undefined;
-    /** If `true`, when the function is univariate, `["f", ["Multiply", x, c]]`
+    /** If `true`, when the operator is univariate, `["f", ["Multiply", x, c]]`
      * simplifies to `["Multiply", ["f", x], c]` where `c` is constant
      *
-     * When the function is multivariate, multiplicativity is considered only on
+     * When the operator is multivariate, multiplicativity is considered only on
      * the first argument: `["f", ["Multiply", x, y], z]` simplifies to
      * `["Multiply", ["f", x, z], ["f", y, z]]`
      *
@@ -1886,10 +2303,10 @@ export type FunctionDefinitionFlags = {
      * **Default**: `false`
      */
     involution: boolean;
-    /** If `true`, the value of this function is always the same for a given
+    /** If `true`, the value of this operator is always the same for a given
      * set of arguments and it has no side effects.
      *
-     * An expression using this function is pure if the function and all its
+     * An expression using this operator is pure if the operator and all its
      * arguments are pure.
      *
      * For example `Sin` is pure, `Random` isn't.
@@ -1901,10 +2318,15 @@ export type FunctionDefinitionFlags = {
     pure: boolean;
 };
 /**
+ *
+ * The definition includes information specific about an operator, such as
+ * handlers to canonicalize or evaluate a function expression with this
+ * operator.
+ *
  * @category Definitions
  *
  */
-export type BoxedFunctionDefinition = BoxedBaseDefinition & FunctionDefinitionFlags & {
+export interface BoxedOperatorDefinition extends BoxedBaseDefinition, OperatorDefinitionFlags {
     complexity: number;
     /** If true, the signature was inferred from usage and may be modified
      * as more information becomes available.
@@ -1936,6 +2358,7 @@ export type BoxedFunctionDefinition = BoxedBaseDefinition & FunctionDefinitionFl
     neq?: (a: BoxedExpression, b: BoxedExpression) => boolean | undefined;
     canonical?: (ops: ReadonlyArray<BoxedExpression>, options: {
         engine: ComputeEngine;
+        scope: Scope | undefined;
     }) => BoxedExpression | null;
     evaluate?: (ops: ReadonlyArray<BoxedExpression>, options: Partial<EvaluateOptions> & {
         engine?: ComputeEngine;
@@ -1947,16 +2370,33 @@ export type BoxedFunctionDefinition = BoxedBaseDefinition & FunctionDefinitionFl
         engine: ComputeEngine;
     }) => BoxedExpression;
     compile?: (expr: BoxedExpression) => CompiledExpression;
-};
-/**
- * The entries have been validated and optimized for faster evaluation.
- *
- * When a new scope is created with `pushScope()` or when creating a new
- * engine instance, new instances of this type are created as needed.
- *
- * @category Definitions
- */
-export type RuntimeIdentifierDefinitions = Map<string, OneOf<[BoxedSymbolDefinition, BoxedFunctionDefinition]>>;
+    /** @internal */
+    update(def: OperatorDefinition): void;
+}
+/** @category Assumptions */
+export interface Assumption {
+    isPositive: boolean | undefined;
+    isNonNegative: boolean | undefined;
+    isNegative: boolean | undefined;
+    isNonPositive: boolean | undefined;
+    isNumber: boolean | undefined;
+    isInteger: boolean | undefined;
+    isRational: boolean | undefined;
+    isReal: boolean | undefined;
+    isComplex: boolean | undefined;
+    isImaginary: boolean | undefined;
+    isFinite: boolean | undefined;
+    isInfinite: boolean | undefined;
+    isNaN: boolean | undefined;
+    isZero: boolean | undefined;
+    matches(t: BoxedType): boolean | undefined;
+    isGreater(other: BoxedExpression): boolean | undefined;
+    isGreaterEqual(other: BoxedExpression): boolean | undefined;
+    isLess(other: BoxedExpression): boolean | undefined;
+    isLessEqual(other: BoxedExpression): boolean | undefined;
+    isEqual(other: BoxedExpression): boolean | undefined;
+    toExpression(ce: ComputeEngine, x: MathJsonSymbol): BoxedExpression;
+}
 /** @category Assumptions */
 export interface ExpressionMapInterface<U> {
     has(expr: BoxedExpression): boolean;
@@ -1969,24 +2409,6 @@ export interface ExpressionMapInterface<U> {
 }
 /** @category Assumptions */
 export type AssumeResult = 'internal-error' | 'not-a-predicate' | 'contradiction' | 'tautology' | 'ok';
-/**
- * When a unitless value is passed to or returned from a trigonometric function,
- * the angular unit of the value.
- *
- * - `rad`: radians, 2π radians is a full circle
- * - `deg`: degrees, 360 degrees is a full circle
- * - `grad`: gradians, 400 gradians is a full circle
- * - `turn`: turns, 1 turn is a full circle
- *
- * @category Compute Engine
- */
-export type AngularUnit = 'rad' | 'deg' | 'grad' | 'turn';
-/** @category Compute Engine */
-export type RuntimeScope = Scope & {
-    parentScope?: RuntimeScope;
-    ids?: RuntimeIdentifierDefinitions;
-    assumptions: undefined | ExpressionMapInterface<boolean>;
-};
 /**
  * When provided, canonical forms are used to put an expression in a
  * "standard" form.
@@ -1997,7 +2419,8 @@ export type RuntimeScope = Scope & {
  *
  * - `InvisibleOperator`: replace use of the `InvisibleOperator` with
  *    another operation, such as multiplication (i.e. `2x` or function
- *    application (`f(x)`).
+ *    application (`f(x)`). Also replaces ['InvisibleOperator', real, imaginary] instances with
+ *    complex (imaginary) numbers.
  * - `Number`: replace all numeric values with their
  *    canonical representation, for example, reduce
  *    rationals and replace complex numbers with no imaginary part with a real number.
@@ -2015,8 +2438,38 @@ export type RuntimeScope = Scope & {
 export type CanonicalForm = 'InvisibleOperator' | 'Number' | 'Multiply' | 'Add' | 'Power' | 'Divide' | 'Flatten' | 'Order';
 /** @category Boxed Expression */
 export type CanonicalOptions = boolean | CanonicalForm | CanonicalForm[];
+/** Options for `BoxedExpression.evaluate()`
+ *
+ * @category Boxed Expression
+ */
+export type EvaluateOptions = {
+    /**
+     * If `true`, the evaluation will return a numeric approximation
+     * of the expression, if possible.
+     * If `false`, the evaluation will return an exact value, if possible.
+     * Defaults to `false`.
+     */
+    numericApproximation: boolean;
+    /**
+     * If `false`, and the result of the expression is a lazy collection,
+     * the collection will not be evaluated and will remain lazy.
+     *
+     * If `true` and the expression is a finite lazy collection,
+     * the collection will be evaluated and returned as a non-lazy collection.
+     *
+     * If an integer, the collection will be evaluated up to that many elements.
+     *
+     * If a pair of integers `[n,m]`, and the collection is finite, the first `n`
+     * elements will be evaluated, and the last `m` elements will be evaluated.
+     *
+     * Defaults to `false`.
+     */
+    materialization: boolean | number | [number, number];
+    signal: AbortSignal;
+    withArguments: Record<MathJsonSymbol, BoxedExpression>;
+};
 /**
- * Metadata that can be associated with a `BoxedExpression`
+ * Metadata that can be associated with an MathJSON expression.
  *
  * @category Boxed Expression
  */
@@ -2025,14 +2478,14 @@ export type Metadata = {
     wikidata?: string | undefined;
 };
 /**
- * A substitution describes the values of the wildcards in a pattern so that
- * the pattern is equal to a target expression.
- *
- * A substitution can also be considered a more constrained version of a
- * rule whose `match` is always a symbol.
+  * A substitution describes the values of the wildcards in a pattern so that
+  * the pattern is equal to a target expression.
+  *
+  * A substitution can also be considered a more constrained version of a
+  * rule whose `match` is always a symbol.
 
-* @category Pattern Matching
- */
+  * @category Pattern Matching
+  */
 export type Substitution<T = SemiBoxedExpression> = {
     [symbol: string]: T;
 };
@@ -2110,6 +2563,8 @@ export type Rule = string | RuleFunction | {
     condition?: LatexString | RuleConditionFunction;
     useVariations?: boolean;
     id?: string;
+    onBeforeMatch?: (rule: Rule, expr: BoxedExpression) => void;
+    onMatch?: (rule: Rule, expr: BoxedExpression, replace: BoxedExpression | RuleStep) => void;
 };
 /**
  *
@@ -2128,6 +2583,8 @@ export type BoxedRule = {
     condition: undefined | RuleConditionFunction;
     useVariations?: boolean;
     id?: string;
+    onBeforeMatch?: (rule: Rule, expr: BoxedExpression) => void;
+    onMatch?: (rule: Rule, expr: BoxedExpression, replace: BoxedExpression | RuleStep) => void;
 };
 /**
  * To create a BoxedRuleSet use the `ce.rules()` method.
@@ -2139,15 +2596,77 @@ export type BoxedRule = {
 export type BoxedRuleSet = {
     rules: ReadonlyArray<BoxedRule>;
 };
-/** @category Compute Engine */
-export type AssignValue = boolean | number | SemiBoxedExpression | ((args: ReadonlyArray<BoxedExpression>, options: EvaluateOptions & {
+/**
+ * The argument of `ce.assign()` is a value that can be assigned to a variable.
+ * It can be a primitive value, a boxed expression, or a function that
+ * takes a list of arguments and returns a boxed expression.
+ * @category Compute Engine */
+export type AssignValue = boolean | number | bigint | SemiBoxedExpression | ((args: ReadonlyArray<BoxedExpression>, options: EvaluateOptions & {
     engine: ComputeEngine;
 }) => BoxedExpression) | undefined;
+/**
+ * A lexical scope is a table mapping symbols to their definitions. The
+ * symbols are the names of the variables, unknowns and functions in the scope.
+ *
+ * The lexical scope is used to resolve the metadata about symbols, such as
+ * their type, whether they are constant, etc...
+ *
+ * It does not resolve the values of the symbols, since those depend on the
+ * evaluation context. For example, the local variables of a recursive function
+ * will have the same lexical scope, but different values in each evaluation
+ * context.
+ *
+ * @category Definitions
+ */
+export type Scope = {
+    parent: Scope | null;
+    bindings: Map<string, BoxedDefinition>;
+    types?: Record<string, TypeReference>;
+};
+/**
+ * An evaluation context is a set of bindings mapping symbols to their
+ * values. It also includes a reference to the lexical scope of the
+ * context, as well as a set of assumptions about the values of the
+ * symbols.
+ *
+ *
+ * Eval contexts are arranged in a stack structure. When a new context is
+ * created, it is pushed on the top of the stack.
+ *
+ * A new eval context is created when a function expression that needs to track
+ * its own local variables and named arguments is evaluated. This kind of
+ * function is a "scoped" function, meaning that it has its own local variables
+ * and named arguments.
+ *
+ * For example, the `Sum` function creates a new eval context to track the local
+ * variable used as the index of the sum.
+ *
+ * The eval context stack is used to resolve the value of symbols.
+ *
+ * When a scoped recursive function is called, a new context is created for each
+ * recursive call.
+ *
+ * In contrast, the lexical scope is used to resolve the metadata about
+ * symbols, such as their type, whether they are constant, etc... A new
+ * scope is not created for recursive calls, since the metadata
+ * does not change, only the values of the symbols change.
+ *
+ * The name of the eval context is used to print a "stack trace" for
+ * debugging.
+ *
+ * @category Compute Engine
+ */
+export type EvalContext = {
+    lexicalScope: Scope;
+    assumptions: ExpressionMapInterface<boolean>;
+    values: Record<string, BoxedExpression | undefined>;
+    name: undefined | string;
+};
 /** @internal */
 export interface ComputeEngine extends IBigNum {
     latexDictionary: readonly LatexDictionaryEntry[];
     /** @private */
-    indexedLatexDictionary: IndexedLatexDictionary;
+    _indexedLatexDictionary: IndexedLatexDictionary;
     decimalSeparator: LatexString;
     readonly True: BoxedExpression;
     readonly False: BoxedExpression;
@@ -2158,6 +2677,7 @@ export interface ComputeEngine extends IBigNum {
     readonly One: BoxedExpression;
     readonly Half: BoxedExpression;
     readonly NegativeOne: BoxedExpression;
+    /** ImaginaryUnit */
     readonly I: BoxedExpression;
     readonly NaN: BoxedExpression;
     readonly PositiveInfinity: BoxedExpression;
@@ -2177,34 +2697,22 @@ export interface ComputeEngine extends IBigNum {
     readonly _BIGNUM_PI: BigNum;
     /** @internal */
     readonly _BIGNUM_NEGATIVE_ONE: BigNum;
-    /** The current scope */
-    context: RuntimeScope | null;
+    readonly context: EvalContext;
+    contextStack: ReadonlyArray<EvalContext>;
+    /** @internal */
+    readonly _typeResolver: TypeResolver;
     /** Absolute time beyond which evaluation should not proceed
      * @internal
      */
     _deadline?: number;
-    /** Time remaining before _deadline */
-    _timeRemaining: number;
-    /** @private */
-    generation: number;
-    /** Throw a `CancellationError` when the duration of an evaluation exceeds
-     * the time limit.
-     *
-     * Time in milliseconds, default 2000 ms = 2 seconds.
-     *
+    /** Time remaining before _deadline
+     * @internal
      */
+    _timeRemaining: number;
+    /** @internal */
+    _generation: number;
     timeLimit: number;
-    /** Throw `CancellationError` `iteration-limit-exceeded` when the iteration limit
-     * in a loop is exceeded. Default: no limits.
-     *
-     * @experimental
-     */
     iterationLimit: number;
-    /** Signal `recursion-depth-exceeded` when the recursion depth for this
-     * scope is exceeded.
-     *
-     * @experimental
-     */
     recursionLimit: number;
     chop(n: number): number;
     chop(n: BigNum): BigNum | 0;
@@ -2213,14 +2721,6 @@ export interface ComputeEngine extends IBigNum {
     complex: (a: number | Complex, b?: number) => Complex;
     /** @internal */
     _numericValue(value: number | bigint | OneOf<[BigNum | NumericValueData | ExactNumericValueData]>): NumericValue;
-    /** If the precision is set to `machine`, floating point numbers
-     * are represented internally as a 64-bit floating point number (as
-     * per IEEE 754-2008), with a 52-bit mantissa, which gives about 15
-     * digits of precision.
-     *
-     * If the precision is set to `auto`, the precision is set to 300 digits.
-     *
-     */
     set precision(p: number | 'machine' | 'auto');
     get precision(): number;
     tolerance: number;
@@ -2230,18 +2730,37 @@ export interface ComputeEngine extends IBigNum {
     box(expr: NumericValue | SemiBoxedExpression, options?: {
         canonical?: CanonicalOptions;
         structural?: boolean;
+        scope?: Scope;
     }): BoxedExpression;
     function(name: string, ops: ReadonlyArray<SemiBoxedExpression>, options?: {
         metadata?: Metadata;
         canonical?: CanonicalOptions;
         structural?: boolean;
+        scope?: Scope;
+    }): BoxedExpression;
+    /**
+     * This is a primitive to create a boxed function.
+     *
+     * In general, consider using `ce.box()` or `ce.function()` or
+     * `canonicalXXX()` instead.
+     *
+     * The caller must ensure that the arguments are in canonical form:
+     * - arguments are `canonical()`
+     * - arguments are sorted
+     * - arguments are flattened and desequenced
+     *
+     * @internal
+     */
+    _fn(name: string, ops: ReadonlyArray<BoxedExpression>, options?: {
+        metadata?: Metadata;
+        canonical?: boolean;
+        scope?: Scope;
     }): BoxedExpression;
-    number(value: number | bigint | string | NumericValue | MathJsonNumber | BigNum | Complex | Rational, options?: {
+    number(value: number | bigint | string | NumericValue | MathJsonNumberObject | BigNum | Complex | Rational, options?: {
         metadata?: Metadata;
         canonical?: CanonicalOptions;
     }): BoxedExpression;
     symbol(sym: string, options?: {
-        metadata?: Metadata;
         canonical?: CanonicalOptions;
     }): BoxedExpression;
     string(s: string, metadata?: Metadata): BoxedExpression;
@@ -2254,26 +2773,7 @@ export interface ComputeEngine extends IBigNum {
     rules(rules: Rule | ReadonlyArray<Rule | BoxedRule> | BoxedRuleSet | undefined | null, options?: {
         canonical?: boolean;
     }): BoxedRuleSet;
-    /**
-     * Return a set of built-in rules.
-     */
     getRuleSet(id?: 'harmonization' | 'solve-univariate' | 'standard-simplification'): BoxedRuleSet | undefined;
-    /**
-     * This is a primitive to create a boxed function.
-     *
-     * In general, consider using `ce.box()` or `ce.function()` or
-     * `canonicalXXX()` instead.
-     *
-     * The caller must ensure that the arguments are in canonical form:
-     * - arguments are `canonical()`
-     * - arguments are sorted
-     * - arguments are flattened and desequenced
-     *
-     * @internal
-     */
-    _fn(name: string, ops: ReadonlyArray<BoxedExpression>, options?: Metadata & {
-        canonical?: boolean;
-    }): BoxedExpression;
     parse(latex: null, options?: Partial<ParseLatexOptions> & {
         canonical?: CanonicalOptions;
     }): null;
@@ -2283,51 +2783,90 @@ export interface ComputeEngine extends IBigNum {
     parse(latex: LatexString | null, options?: Partial<ParseLatexOptions> & {
         canonical?: CanonicalOptions;
     }): BoxedExpression | null;
-    pushScope(scope?: Partial<Scope>): ComputeEngine;
-    popScope(): ComputeEngine;
-    swapScope(scope: RuntimeScope | null): RuntimeScope | null;
-    resetContext(): void;
-    defineSymbol(name: string, def: SymbolDefinition): BoxedSymbolDefinition;
-    lookupSymbol(name: string, wikidata?: string, scope?: RuntimeScope): undefined | BoxedSymbolDefinition;
-    defineFunction(name: string, def: FunctionDefinition): BoxedFunctionDefinition;
-    lookupFunction(name: string, scope?: RuntimeScope | null): undefined | BoxedFunctionDefinition;
+    pushScope(scope?: Scope, name?: string): void;
+    popScope(): void;
+    /**
+     *
+     * When a new eval context is created, it has slots for the local variables
+     * from the current lexical scope. It also copies the current set of
+     * assumptions.
+     *
+     * Need a pointer to the current lexical scope (may have a scope chain without an evaluation context). Each lexical scope includes a pointer to the parent scope (it's a DAG).
+     *
+     * If a function is "scoped" (has a `scoped` flag), create a new lexical scope
+     * when the function is canonicalized, store the scope with the function
+     * definition (if the function has a lazy flag, and a canonical handler, it
+     * can behave like a scoped function, but a scoped flag is convenient,
+     * it would still evaluate the arguments).
+     *
+     * Note: if an expression is not canonical, evaluating it return itself.
+     * This is important to support arguments that are just symbol names
+     * (they are not canonicalized).
+     *
+     * When the function expression is evaluated, if it is "scoped", push the
+     * scope associated with the function (maybe not?) and a matching eval
+     * context, including all the symbols in the lexical scope (including
+     * constants). Need some way to indicate that a symbol maps to an argument
+     * (in value definition?).
+     *
+     * When searching the value of a symbol, start with the current
+     * eval context, then the previous one.
+     *
+     * When looking for a definition, start with the lexical scope of the
+     * current eval context, then the parent lexical context.
+     *
+     * @internal */
+    _pushEvalContext(scope: Scope, name?: string): void;
+    /** @internal */
+    _popEvalContext(): void;
+    /**
+     * Temporarily sets the lexical scope to the provided scope, then
+     * executes the function `f` in that scope and returns the result.
+     * @internal */
+    _inScope<T>(scope: Scope | undefined, f: () => T): T;
+    /**
+     * Use `ce.box(id)` instead
+     * @internal */
+    _getSymbolValue(id: MathJsonSymbol): BoxedExpression | undefined;
+    /**
+     * Use `ce.assign(id, value)` instead.
+     * @internal */
+    _setSymbolValue(id: MathJsonSymbol, value: BoxedExpression | boolean | number | undefined): void;
+    /** A list of the function calls to the current evaluation context */
+    trace: ReadonlyArray<string>;
+    lookupContext(id: MathJsonSymbol): undefined | EvalContext;
+    /** @internal */
+    _swapContext(context: EvalContext): void;
+    lookupDefinition(id: MathJsonSymbol): undefined | BoxedDefinition;
     assign(ids: {
-        [id: string]: AssignValue;
+        [id: MathJsonSymbol]: AssignValue;
     }): ComputeEngine;
-    assign(id: string, value: AssignValue): ComputeEngine;
-    assign(arg1: string | {
-        [id: string]: AssignValue;
+    assign(id: MathJsonSymbol, value: AssignValue): ComputeEngine;
+    assign(arg1: MathJsonSymbol | {
+        [id: MathJsonSymbol]: AssignValue;
     }, arg2?: AssignValue): ComputeEngine;
-    declare(identifiers: {
-        [id: string]: Type | TypeString | OneOf<[SymbolDefinition | FunctionDefinition]>;
+    declareType(name: string, type: Type, options?: {
+        alias?: boolean;
+    }): void;
+    declare(symbols: {
+        [id: MathJsonSymbol]: Type | TypeString | Partial<SymbolDefinition>;
     }): ComputeEngine;
-    declare(id: string, def: Type | TypeString | SymbolDefinition | FunctionDefinition): ComputeEngine;
-    declare(arg1: string | {
-        [id: string]: Type | TypeString | OneOf<[SymbolDefinition | FunctionDefinition]>;
-    }, arg2?: Type | OneOf<[SymbolDefinition | FunctionDefinition]>): ComputeEngine;
+    declare(id: MathJsonSymbol, def: Type | TypeString | Partial<SymbolDefinition>, scope?: Scope): ComputeEngine;
+    declare(arg1: MathJsonSymbol | {
+        [id: MathJsonSymbol]: Type | TypeString | Partial<SymbolDefinition>;
+    }, arg2?: Type | TypeString | Partial<SymbolDefinition>, arg3?: Scope): ComputeEngine;
     assume(predicate: BoxedExpression): AssumeResult;
-    forget(symbol?: string | string[]): void;
-    get assumptions(): ExpressionMapInterface<boolean>;
+    forget(symbol?: MathJsonSymbol | MathJsonSymbol[]): void;
     ask(pattern: BoxedExpression): BoxedSubstitution[];
     verify(query: BoxedExpression): boolean;
     /** @internal */
-    shouldContinueExecution(): boolean;
-    /** @internal */
-    checkContinueExecution(): void;
+    _shouldContinueExecution(): boolean;
     /** @internal */
-    cache<T>(name: string, build: () => T, purge?: (t: T) => T | undefined): T;
+    _checkContinueExecution(): void;
     /** @internal */
-    readonly stats: ComputeEngineStats;
+    _cache<T>(name: string, build: () => T, purge?: (t: T) => T | undefined): T;
     /** @internal */
-    reset(): void;
-    /** @internal */
-    _register(expr: BoxedExpression): void;
+    _reset(): void;
     /** @internal */
-    _unregister(expr: BoxedExpression): void;
-}
-/** @internal */
-export interface ComputeEngineStats {
-    symbols: Set<BoxedExpression>;
-    expressions: null | Set<BoxedExpression>;
-    highwaterMark: number;
+    listenToConfigurationChange(tracker: ConfigurationChangeListener): () => void;
 }