@cortex-js/compute-engine 0.28.0 → 0.29.0

package/dist/types/compute-engine/{boxed-expression/public.d.ts → global-types.d.ts}

@@ -1,18 +1,61 @@
-/* 0.28.0 */
-import type { Expression, MathJsonNumber, MathJsonString, MathJsonSymbol, MathJsonFunction, MathJsonIdentifier } from '../../math-json';
-import type { SerializeLatexOptions, LatexDictionaryEntry, ParseLatexOptions } from '../latex-syntax/public';
-import type { IndexedLatexDictionary } from '../latex-syntax/dictionary/definitions';
-import { Rational } from '../numerics/rationals';
-import { ExactNumericValueData, NumericValue, NumericValueData } from '../numeric-value/public';
-import { BigNum, IBigNum } from '../numerics/bignum';
-import { Type, TypeString } from '../../common/type/types';
-import { AbstractTensor } from '../tensor/tensors';
-import { OneOf } from '../../common/one-of';
-import { CompiledType, JSSource } from '../compile';
-import { BoxedType } from '../../common/type/boxed-type';
+/* 0.29.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';
+/** @category Compiling */
+export type CompiledType = boolean | number | string | object;
+/** @category Compiling */
+export type JSSource = string;
+/** @category Compiling */
+export type CompiledExpression = {
+    evaluate?: (scope: {
+        [symbol: string]: BoxedExpression;
+    }) => number | BoxedExpression;
+};
+/** @category Tensors */
+export type DataTypeMap = {
+    float64: number;
+    float32: number;
+    int32: number;
+    uint8: number;
+    complex128: Complex;
+    complex64: Complex;
+    bool: boolean;
+    string: string;
+    expression: BoxedExpression;
+};
+/** @category Tensors */
+export type TensorDataType = keyof DataTypeMap;
+/** @category Tensors */
+export interface TensorData<DT extends keyof DataTypeMap = 'float64'> {
+    dtype: DT;
+    shape: number[];
+    rank: number;
+    data: DataTypeMap[DT][];
+}
 /**
  * :::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`.
+ *
+ * When a member function is not applicable to this `BoxedExpression`,
+ * for example `get symbol()` on a `BoxedNumber`, it returns `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()`.
+ *
+ *
  * To create a boxed expression:
  *
  * ### `ce.box()` and `ce.parse()`
@@ -109,52 +152,6 @@ import { BoxedType } from '../../common/type/boxed-type';
  * used directly, for example `canonicalAdd(a, b)` instead of
  * `ce.function('Add', [a, b])`.
  *
- * :::
- */
-export type Sign = 
-/** The expression is equal to 0 */
-'zero'
-/** The expression is > 0 */
- | 'positive'
-/** The expression is < 0 */
- | 'negative'
-/** The expression is >= 0 and isPositive is either false or undefined*/
- | 'non-negative'
-/** The expression is <= 0 and isNegative is either false or undefined*/
- | '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';
-/**
- * :::info[THEORY OF OPERATIONS]
- *
- * The `BoxedExpression` interface includes most of the member functions
- * applicable to any kind of expression, for example `get symbol()` or
- * `get ops()`.
- *
- * When a member function is not applicable to this `BoxedExpression`,
- * for example `get symbol()` on a `BoxedNumber`, it returns `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()`, or to
- * get a boxed expression from a MathJSON expression use `ce.box()`.
- *
  * @category Boxed Expression
  *
  */
@@ -164,7 +161,7 @@ export interface BoxedExpression {
      * and functions.
      *
      */
-    readonly engine: IComputeEngine;
+    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
@@ -289,11 +286,6 @@ export interface BoxedExpression {
      *
      */
     readonly symbol: string | null;
-    /**
-     * @category Symbol Expression
-     *
-     */
-    readonly tensor: null | AbstractTensor<'expression'>;
     /** If this expression is a string, return the value of the string.
      * Otherwise, return `null`.
      *
@@ -305,6 +297,7 @@ export interface BoxedExpression {
      *
      */
     readonly string: string | null;
+    readonly tensor: null | TensorData<'expression'>;
     /** All the subexpressions matching the named operator, recursively.
      *
      * :::info[Note]
@@ -737,13 +730,13 @@ export interface BoxedExpression {
      *
      * Attempts to make `rest` a positive value (i.e. pulls out negative sign).
      *
-     * For example:
-     *
+     *```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];
     neg(): BoxedExpression;
@@ -938,7 +931,7 @@ export interface BoxedExpression {
      * integers) are performed but exact calculations may be performed,
      * for example:
      *
-     * \\( \sin(\frac{\pi}{4}) \longrightarrow \frac{\sqrt{2}}{2} \\).
+     * $$ \sin(\frac{\pi}{4}) \longrightarrow \frac{\sqrt{2}}{2} $$.
      *
      * The result is canonical.
      *
@@ -1140,7 +1133,7 @@ export interface BoxedExpression {
      * - `expr.isSame(other)` for a structural comparison
      * - `expr.is(other)` for a comparison of a number literal
      *
-     * ## Examples
+     * **Examples**
      *
      * ```js
      * let expr = ce.parse('2 + 2');
@@ -1219,30 +1212,6 @@ export interface BoxedExpression {
  * @category Boxed Expression
  */
 export type SemiBoxedExpression = number | bigint | string | BigNum | MathJsonNumber | MathJsonString | MathJsonSymbol | MathJsonFunction | readonly [MathJsonIdentifier, ...SemiBoxedExpression[]] | BoxedExpression;
-/**
- * @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;
-    /** 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.
-     */
-    reset(): void;
-}
 /**
  * These handlers compare two expressions.
  *
@@ -1253,251 +1222,542 @@ export interface BoxedBaseDefinition {
  *  @category Definitions
  *
  */
-export type EqHandlers = {
+export interface EqHandlers {
     eq: (a: BoxedExpression, b: BoxedExpression) => boolean | undefined;
     neq: (a: BoxedExpression, b: BoxedExpression) => boolean | undefined;
-};
+}
+/** @category Definitions */
+export type Hold = 'none' | 'all' | 'first' | 'rest' | 'last' | 'most';
 /**
- * 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.
+ * Options to control the serialization to MathJSON when using `BoxedExpression.toMathJson()`.
  *
- *  @category Definitions
+ * @category Serialization
  */
-export type CollectionHandlers = {
-    /** Return the number of elements in the collection.
+export type JsonSerializationOptions = {
+    /** If true, the serialization applies some transformations to make
+     * the JSON more readable. For example, `["Power", "x", 2]` is serialized
+     * as `["Square", "x"]`.
+     */
+    prettify: boolean;
+    /** A list of space separated function names that should be excluded from
+     * the JSON output.
      *
-     * An empty collection has a size of 0.
+     * Those functions are replaced with an equivalent, for example, `Square` with
+     * `Power`, etc...
+     *
+     * Possible values include `Sqrt`, `Root`, `Square`, `Exp`, `Subtract`,
+     * `Rational`, `Complex`
+     *
+     * **Default**: `[]` (none)
      */
-    size: (collection: BoxedExpression) => number;
-    /**
-     * Return `true` if the target
-     * expression is in the collection, `false` otherwise.
+    exclude: string[];
+    /** A list of space separated keywords indicating which MathJSON expressions
+     * can use a shorthand.
+     *
+     * **Default**: `["all"]`
      */
-    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
+    shorthands: ('all' | 'number' | 'symbol' | 'function' | 'string')[];
+    /** A list of space separated keywords indicating which metadata should be
+     * included in the MathJSON. If metadata is included, shorthand notation
+     * is not used.
      *
-     * If there is a `keys()` handler, there is no `iterator()` handler.
+     * **Default**: `[]`  (none)
+     */
+    metadata: ('all' | 'wikidata' | 'latex')[];
+    /** If true, repeating decimals are detected and serialized accordingly
+     * For example:
+     * - `1.3333333333333333` \( \to \) `1.(3)`
+     * - `0.142857142857142857142857142857142857142857142857142` \( \to \) `0.(1428571)`
      *
-     * @category Definitions
+     * **Default**: `true`
      */
-    iterator: (collection: BoxedExpression, start?: number, count?: number) => Iterator<BoxedExpression, undefined>;
+    repeatingDecimal: boolean;
     /**
-     * Return the element at the specified index.
-     *
-     * The first element is `at(1)`, the last element is `at(-1)`.
+     * The maximum number of significant digits in serialized numbers.
+     * - `"max"`: all availabe digits are serialized.
+     * - `"auto"`: use the same precision as the compute engine.
      *
-     * If the index is &lt;0, return the element at index `size() + index + 1`.
+     * **Default**: `"auto"`
+     */
+    fractionalDigits: 'auto' | 'max' | number;
+};
+/**
+ * Control how a pattern is matched to an expression.
+ *
+ * - `substitution`: if present, assumes these values for the named wildcards,
+ *    and ensure that subsequent occurrence of the same wildcard have the same
+ *    value.
+ * - `recursive`: if true, match recursively, otherwise match only the top
+ *    level.
+ * - `useVariations`: if false, only match expressions that are structurally identical.
+ *    If true, match expressions that are structurally identical or equivalent.
+ *
+ *    For example, when true, `["Add", '_a', 2]` matches `2`, with a value of
+ *    `_a` of `0`. If false, the expression does not match. **Default**: `false`
+ *
+ * @category Pattern Matching
+ *
+ */
+export type PatternMatchOptions = {
+    substitution?: BoxedSubstitution;
+    recursive?: boolean;
+    useVariations?: boolean;
+};
+/**
+ * @category Boxed Expression
+ *
+ */
+export type ReplaceOptions = {
+    /**
+     * If `true`, apply replacement rules to all sub-expressions.
      *
-     * The index can also be a string for example for maps. The set of valid keys
-     * is returned by the `keys()` handler.
+     * If `false`, only consider the top-level expression.
      *
-     * If the index is invalid, return `undefined`.
+     * **Default**: `false`
      */
-    at: (collection: BoxedExpression, index: number | string) => undefined | BoxedExpression;
+    recursive: boolean;
     /**
-     * If the collection can be indexed by strings, return the valid values
-     * for the index.
+     * If `true`, stop after the first rule that matches.
+     *
+     * If `false`, apply all the remaining rules even after the first match.
+     *
+     * **Default**: `false`
      */
-    keys: (collection: BoxedExpression) => undefined | Iterable<string>;
+    once: boolean;
     /**
-     * Return the index of the first element that matches the target expression.
+     * If `true` the rule will use some equivalent variations to match.
      *
-     * The comparison is done using the `target.isEqual()` method.
+     * For example when `useVariations` is true:
+     * - `x` matches `a + x` with a = 0
+     * - `x` matches `ax` with a = 1
+     * - etc...
      *
-     * If the expression is not found, return `undefined`.
+     * Setting this to `true` can save time by condensing multiple rules
+     * into one. This can be particularly useful when describing equations
+     * solutions. However, it can lead to infinite recursion and should be
+     * used with caution.
      *
-     * If the expression is found, return the index, 1-based.
+     */
+    useVariations: boolean;
+    /**
+     * If `iterationLimit` > 1, the rules will be repeatedly applied
+     * until no rules apply, up to `maxIterations` times.
      *
-     * Return the index of the first match.
+     * Note that if `once` is true, `iterationLimit` has no effect.
      *
-     * `from` is the starting index for the search. If negative, start from
-     * the end  and search backwards.
+     * **Default**: `1`
      */
-    indexOf: (collection: BoxedExpression, target: BoxedExpression, from?: number) => number | undefined;
+    iterationLimit: number;
     /**
-     * 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`.
+     * Indicate if the expression should be canonicalized after the replacement.
+     * If not provided, the expression is canonicalized if the expression
+     * that matched the pattern is canonical.
      */
-    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;
+    canonical: CanonicalOptions;
 };
 /**
- * A function definition can have some flags to indicate specific
- * properties of the function.
+ * 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')
  * @category Definitions
  */
-export type FunctionDefinitionFlags = {
+export type SymbolDefinition = BaseDefinition & Partial<SymbolAttributes> & {
+    type?: Type | TypeString;
+    /** 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;
+    /** `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>;
+};
+/**
+ * Definition record for a function.
+ * @category Definitions
+ *
+ */
+export type FunctionDefinition = BaseDefinition & Partial<FunctionDefinitionFlags> & {
     /**
-     * If `true`, the arguments to this function are not automatically
-     * evaluated. The default is `false` (the arguments are evaluated).
+     * The function signature.
      *
-     * This can be useful for example for functions that take symbolic
-     * expressions as arguments, such as `D` or `Integrate`.
+     * If a `type` handler is provided, the return type of the function should
+     * be a subtype of the return type in the signature.
      *
-     * This is also useful for functions that take an argument that is
-     * potentially an infinite collection.
+     */
+    signature?: Type | TypeString;
+    /**
+     * The actual type of the result based on the arguments.
      *
-     * 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.
+     * Should be a subtype of the type indicated in the signature.
      *
-     * This also applies to the `canonical()` handler.
+     * Do not evaluate the arguments.
      *
-     */
-    lazy: boolean;
-    /**  If `true`, the function is applied element by element to lists, matrices
-     * (`["List"]` or `["Tuple"]` expressions) and equations (relational
-     * operators).
+     * The type of the arguments can be used to determine the type of the
+     * result.
      *
-     * **Default**: `false`
      */
-    threadable: boolean;
-    /** If `true`, `["f", ["f", a], b]` simplifies to `["f", a, b]`
+    type?: (ops: ReadonlyArray<BoxedExpression>, options: {
+        engine: ComputeEngine;
+    }) => Type | TypeString | BoxedType | undefined;
+    /** Return the sign of the function expression.
      *
-     * **Default**: `false`
-     */
-    associative: boolean;
-    /** If `true`, `["f", a, b]` equals `["f", b, a]`. The canonical
-     * version of the function will order the arguments.
+     * If the sign cannot be determined, return `undefined`.
+     *
+     * When determining the sign, only literal values and the values of
+     * symbols, if they are literals, should be considered.
+     *
+     * Do not evaluate the arguments.
+     *
+     * The type and sign of the arguments can be used to determine the sign.
      *
-     * **Default**: `false`
      */
-    commutative: boolean;
+    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.
+     */
+    even?: (ops: ReadonlyArray<BoxedExpression>, options: {
+        engine: ComputeEngine;
+    }) => boolean | undefined;
     /**
-     * If `commutative` is `true`, the order of the arguments is determined by
-     * this function.
+     * A number used to order arguments.
      *
-     * If the function is not provided, the arguments are ordered by the
-     * default order of the arguments.
+     * Argument with higher complexity are placed after arguments with
+     * lower complexity when ordered canonically in commutative functions.
+     *
+     * - Additive functions: 1000-1999
+     * - Multiplicative functions: 2000-2999
+     * - Root and power functions: 3000-3999
+     * - Log functions: 4000-4999
+     * - Trigonometric functions: 5000-5999
+     * - Hypertrigonometric functions: 6000-6999
+     * - Special functions (factorial, Gamma, ...): 7000-7999
+     * - Collections: 8000-8999
+     * - Inert and styling:  9000-9999
+     * - Logic: 10000-10999
+     * - Relational: 11000-11999
      *
+     * **Default**: 100,000
      */
-    commutativeOrder: ((a: BoxedExpression, b: BoxedExpression) => number) | undefined;
-    /** If `true`, when the function is univariate, `["f", ["Multiply", x, c]]`
-     * simplifies to `["Multiply", ["f", x], c]` where `c` is constant
+    complexity?: number;
+    /**
+     * Return the canonical form of the expression with the arguments `args`.
      *
-     * When the function is multivariate, multiplicativity is considered only on
-     * the first argument: `["f", ["Multiply", x, y], z]` simplifies to
-     * `["Multiply", ["f", x, z], ["f", y, z]]`
+     * The arguments (`args`) may not be in canonical form. If necessary, they
+     * can be put in canonical form.
      *
-     * Default: `false`
-     */
-    /** If `true`, `["f", ["f", x]]` simplifies to `["f", x]`.
+     * This handler should validate the type and number of the arguments.
      *
-     * **Default**: `false`
-     */
-    idempotent: boolean;
-    /** If `true`, `["f", ["f", x]]` simplifies to `x`.
+     * 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
      *
-     * **Default**: `false`
-     */
-    involution: boolean;
-    /** If `true`, the value of this function is always the same for a given
-     * set of arguments and it has no side effects.
+     * If the type of an argument is not compatible, it should be indicated
+     * with an `incompatible-type` error.
      *
-     * An expression using this function is pure if the function and all its
-     * arguments are pure.
+     * `["Sequence"]` expressions are not folded and need to be handled
+     *  explicitly.
      *
-     * For example `Sin` is pure, `Random` isn't.
+     * If the function is associative, idempotent or an involution,
+     * this handler should account for it. Notably, if it is commutative, the
+     * arguments should be sorted in canonical order.
      *
-     * This information may be used to cache the value of expressions.
      *
-     * **Default:** `true`
-     */
-    pure: boolean;
-};
-/** @category Compiling */
-export type CompiledExpression = {
-    evaluate?: (scope: {
-        [symbol: string]: BoxedExpression;
-    }) => number | BoxedExpression;
-};
-/** @category Definitions */
-export type Hold = 'none' | 'all' | 'first' | 'rest' | 'last' | 'most';
-/**
- * @category Definitions
- *
- */
-export type BoxedFunctionDefinition = BoxedBaseDefinition & FunctionDefinitionFlags & {
-    complexity: number;
-    /** If true, the signature was inferred from usage and may be modified
-     * as more information becomes available.
-     */
-    inferredSignature: boolean;
-    /** The type of the arguments and return value of this function */
-    signature: BoxedType;
-    /** If present, this handler can be used to more precisely determine the
-     * return type based on the type of the arguments. The arguments themselves
-     * should *not* be evaluated, only their types should be used.
-     */
-    type?: (ops: ReadonlyArray<BoxedExpression>, options: {
-        engine: IComputeEngine;
-    }) => Type | TypeString | BoxedType | undefined;
-    /** If present, this handler can be used to determine the sign of the
-     *  return value of the function, based on the sign and type of its
-     *  arguments.
+     * Values of symbols should not be substituted, unless they have
+     * a `holdUntil` attribute of `"never"`.
      *
-     * The arguments themselves should *not* be evaluated, only their types and
-     * sign should be used.
+     * The handler should not consider the value or any assumptions about any
+     * of the arguments that are symbols or functions (i.e. `arg.isZero`,
+     * `arg.isInteger`, etc...) since those may change over time.
+     *
+     * The result of the handler should be a canonical expression.
+     *
+     * If the arguments do not match, they should be replaced with an appropriate
+     * `["Error"]` expression. If the expression cannot be put in canonical form,
+     * the handler should return `null`.
      *
-     * This can be used in some case for example to determine when certain
-     * simplifications are valid.
      */
-    sgn?: (ops: ReadonlyArray<BoxedExpression>, options: {
-        engine: IComputeEngine;
-    }) => Sign | undefined;
-    eq?: (a: BoxedExpression, b: BoxedExpression) => boolean | undefined;
-    neq?: (a: BoxedExpression, b: BoxedExpression) => boolean | undefined;
     canonical?: (ops: ReadonlyArray<BoxedExpression>, options: {
-        engine: IComputeEngine;
+        engine: ComputeEngine;
     }) => BoxedExpression | null;
-    evaluate?: (ops: ReadonlyArray<BoxedExpression>, options: Partial<EvaluateOptions> & {
-        engine?: IComputeEngine;
-    }) => BoxedExpression | undefined;
-    evaluateAsync?: (ops: ReadonlyArray<BoxedExpression>, options?: Partial<EvaluateOptions> & {
-        engine?: IComputeEngine;
+    /**
+     * Evaluate a function expression.
+     *
+     * The arguments have been evaluated, except the arguments to which a
+     * `hold` applied.
+     *
+     * It is not necessary to further simplify or evaluate the arguments.
+     *
+     * If performing numerical calculations and `options.numericalApproximation`
+     * is `false` return an exact numeric value, for example return a rational
+     * 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
+     * an `["Error"]` expression.
+     */
+    evaluate?: ((ops: ReadonlyArray<BoxedExpression>, options: EvaluateOptions & {
+        engine: ComputeEngine;
+    }) => BoxedExpression | undefined) | BoxedExpression;
+    /**
+     * An option asynchronous version of `evaluate`.
+     *
+     */
+    evaluateAsync?: (ops: ReadonlyArray<BoxedExpression>, options: EvaluateOptions & {
+        engine: ComputeEngine;
     }) => Promise<BoxedExpression | undefined>;
-    evalDimension?: (ops: ReadonlyArray<BoxedExpression>, options: {
-        engine: IComputeEngine;
+    /** Dimensional analysis
+     * @experimental
+     */
+    evalDimension?: (args: ReadonlyArray<BoxedExpression>, options: EvaluateOptions & {
+        engine: ComputeEngine;
     }) => BoxedExpression;
+    /** Return a compiled (optimized) expression. */
     compile?: (expr: BoxedExpression) => CompiledExpression;
+    eq?: (a: BoxedExpression, b: BoxedExpression) => boolean | undefined;
+    neq?: (a: BoxedExpression, b: BoxedExpression) => boolean | undefined;
+    collection?: Partial<CollectionHandlers>;
 };
 /**
  * @category Definitions
  *
  */
-export type SymbolAttributes = {
+export type BaseDefinition = {
+    /** A short (about 1 line) description. May contain Markdown. */
+    description?: string | string[];
+    /** A URL pointing to more information about this symbol or operator. */
+    url?: string;
     /**
-     * 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.
+     * A short string representing an entry in a wikibase.
      *
-     * **Default**: `false`
+     * For example `Q167` is the [wikidata entry](https://www.wikidata.org/wiki/Q167)
+     * for the `Pi` constant.
      */
-    constant: boolean;
+    wikidata?: string;
+};
+/** Options for `BoxedExpression.simplify()`
+ *
+ * @category Boxed Expression
+ */
+export type SimplifyOptions = {
     /**
-     * If the symbol has a value, it is held as indicated in the table below.
-     * A green checkmark indicate that the symbol is substituted.
-  
+     * The set of rules to apply. If `null`, use no rules. If not provided,
+     * use the default simplification rules.
+     */
+    rules?: null | Rule | ReadonlyArray<BoxedRule | Rule> | BoxedRuleSet;
+    /**
+     * Use this cost function to determine if a simplification is worth it.
+     *
+     * If not provided, `ce.costFunction`, the cost function of the engine is
+     * used.
+     */
+    costFunction?: (expr: BoxedExpression) => number;
+};
+/**
+ * A table mapping identifiers to their definition.
+ *
+ * Identifiers should be valid MathJSON identifiers. In addition, the
+ * following rules are recommended:
+ *
+ * - Use only latin letters, digits and `-`: `/[a-zA-Z0-9-]+/`
+ * - The first character should be a letter: `/^[a-zA-Z]/`
+ * - Functions and symbols exported from a library should start with an uppercase letter `/^[A-Z]/`
+ *
+ * @category Definitions
+ *
+ */
+export type IdentifierDefinition = OneOf<[
+    SymbolDefinition,
+    FunctionDefinition,
+    SemiBoxedExpression
+]>;
+/**
+ * @category Definitions
+ *
+ */
+export type IdentifierDefinitions = Readonly<{
+    [id: string]: IdentifierDefinition;
+}>;
+/** @category Numerics */
+export type Sign = 
+/** The expression is equal to 0 */
+'zero'
+/** The expression is > 0 */
+ | 'positive'
+/** The expression is < 0 */
+ | 'negative'
+/** The expression is >= 0 and isPositive is either false or undefined*/
+ | 'non-negative'
+/** The expression is <= 0 and isNegative is either false or undefined*/
+ | '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.
+ *
+ *  @category Definitions
+ */
+export type CollectionHandlers = {
+    /** Return the number of elements in the collection.
+     *
+     * An empty collection has a size of 0.
+     */
+    size: (collection: BoxedExpression) => number;
+    /**
+     * Return `true` if the target
+     * expression is in the collection, `false` otherwise.
+     */
+    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
+     *
+     * If there is a `keys()` handler, there is no `iterator()` handler.
+     *
+     * @category Definitions
+     */
+    iterator: (collection: BoxedExpression, start?: number, count?: number) => Iterator<BoxedExpression, undefined>;
+    /**
+     * 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`.
+     *
+     * The index can also be a string for example for maps. 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.
+     *
+     * 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.
+     */
+    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;
+};
+/**
+ * @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;
+    /** 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.
+     */
+    reset(): void;
+}
+/**
+ * @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;
+    /**
+     * 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">
   
   | Operation     | `"never"` | `"evaluate"` | `"N"` |
@@ -1518,21 +1778,6 @@ export type SymbolAttributes = {
     holdUntil: 'never' | 'evaluate' | 'N';
 };
 /**
- * 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;
-};
-/**
- * @noInheritDoc
  * @category Definitions
  */
 export interface BoxedSymbolDefinition extends BoxedBaseDefinition, SymbolAttributes, Partial<NumericFlags> {
@@ -1547,112 +1792,201 @@ export interface BoxedSymbolDefinition extends BoxedBaseDefinition, SymbolAttrib
     type: BoxedType;
 }
 /**
- * Given an expression and set of wildcards, return a new expression.
- *
- * For example:
- *
- * ```ts
- * {
- *    match: '_x',
- *    replace: (expr, {_x}) => { return ['Add', 1, _x] }
- * }
- * ```
- *
- * @category Rules */
-export type RuleReplaceFunction = (expr: BoxedExpression, wildcards: BoxedSubstitution) => BoxedExpression | undefined;
-/** @category Rules */
-export type RuleConditionFunction = (wildcards: BoxedSubstitution, ce: IComputeEngine) => boolean;
-/** @category Rules */
-export type RuleFunction = (expr: BoxedExpression) => undefined | BoxedExpression | RuleStep;
-export declare function isRuleStep(x: any): x is RuleStep;
-/**
- * A rule describes how to modify an expressions that matches a pattern `match`
- * into a new expression `replace`.
- *
- * - `x-1` \( \to \) `1-x`
- * - `(x+1)(x-1)` \( \to \) `x^2-1
- *
- * The patterns can be expressed as LaTeX strings or a MathJSON expressions.
- *
- * As a shortcut, a rule can be defined as a LaTeX string: `x-1 -> 1-x`.
- * The expression to the left of `->` is the `match` and the expression to the
- * right is the `replace`. When using LaTeX strings, single character variables
- * are assumed to be wildcards.
+ * A scope is a set of names in a dictionary that are bound (defined) in
+ * a MathJSON expression.
  *
- * When using MathJSON expressions, anonymous wildcards (`_`) will match any
- * expression. Named wildcards (`_x`, `_a`, etc...) will match any expression
- * and bind the expression to the wildcard name.
+ * 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.
  *
- * In addition the sequence wildcard (`__1`, `__a`, etc...) will match
- * a sequence of one or more expressions, and bind the sequence to the
- * wildcard name.
+ * The scope stack is used to resolve symbols, and it is possible for
+ * a scope to 'mask' definitions from previous scopes.
  *
- * Sequence wildcards are useful when the number of elements in the sequence
- * is not known in advance. For example, in a sum, the number of terms is
- * not known in advance. ["Add", 0, `__a`] will match two or more terms and
- * the `__a` wildcard will be a sequence of the matchign terms.
+ * 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.
  *
- * If `exact` is false, the rule will match variants.
+ * @category Compute Engine
+ */
+export type Scope = Record<string, any>;
+/** Options for `BoxedExpression.evaluate()`
  *
- * For example 'x' will match 'a + x', 'x' will match 'ax', etc...
- *
- * For simplification rules, you generally want `exact` to be true, but
- * to solve equations, you want it to be false. Default to true.
- *
- * When set to false, infinite recursion is possible.
- *
- * @category Rules
+ * @category Boxed Expression
  */
-export type Rule = string | RuleFunction | {
-    match?: LatexString | SemiBoxedExpression | Pattern;
-    replace: LatexString | SemiBoxedExpression | RuleReplaceFunction | RuleFunction;
-    condition?: LatexString | RuleConditionFunction;
-    useVariations?: boolean;
-    id?: string;
+export type EvaluateOptions = {
+    numericApproximation: boolean;
+    signal: AbortSignal;
 };
 /**
- *
- * If the `match` property is `undefined`, all expressions match this rule
- * and `condition` should also be `undefined`. The `replace` property should
- * be a `BoxedExpression` or a `RuleFunction`, and further filtering can be
- * done in the `replace` function.
- *
- * @category Rules */
-export type BoxedRule = {
-    /** @internal */
-    readonly _tag: 'boxed-rule';
-    match: undefined | Pattern;
-    replace: BoxedExpression | RuleReplaceFunction | RuleFunction;
-    condition: undefined | RuleConditionFunction;
-    useVariations?: boolean;
-    id?: string;
-};
-export declare function isBoxedRule(x: any): x is BoxedRule;
-export type RuleStep = {
-    value: BoxedExpression;
-    because: string;
+ * A function definition can have some flags to indicate specific
+ * properties of the function.
+ * @category Definitions
+ */
+export type FunctionDefinitionFlags = {
+    /**
+     * If `true`, the arguments to this function 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 is also useful for functions 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.
+     *
+     * This also applies to the `canonical()` handler.
+     *
+     */
+    lazy: boolean;
+    /**  If `true`, the function is applied element by element to lists, matrices
+     * (`["List"]` or `["Tuple"]` expressions) and equations (relational
+     * operators).
+     *
+     * **Default**: `false`
+     */
+    threadable: boolean;
+    /** If `true`, `["f", ["f", a], b]` simplifies to `["f", a, b]`
+     *
+     * **Default**: `false`
+     */
+    associative: boolean;
+    /** If `true`, `["f", a, b]` equals `["f", b, a]`. The canonical
+     * version of the function will order the arguments.
+     *
+     * **Default**: `false`
+     */
+    commutative: boolean;
+    /**
+     * If `commutative` is `true`, the order of the arguments is determined by
+     * this function.
+     *
+     * If the function is not provided, the arguments are ordered by the
+     * default order of the arguments.
+     *
+     */
+    commutativeOrder: ((a: BoxedExpression, b: BoxedExpression) => number) | undefined;
+    /** If `true`, when the function 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
+     * the first argument: `["f", ["Multiply", x, y], z]` simplifies to
+     * `["Multiply", ["f", x, z], ["f", y, z]]`
+     *
+     * Default: `false`
+     */
+    /** If `true`, `["f", ["f", x]]` simplifies to `["f", x]`.
+     *
+     * **Default**: `false`
+     */
+    idempotent: boolean;
+    /** If `true`, `["f", ["f", x]]` simplifies to `x`.
+     *
+     * **Default**: `false`
+     */
+    involution: boolean;
+    /** If `true`, the value of this function 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
+     * arguments are pure.
+     *
+     * For example `Sin` is pure, `Random` isn't.
+     *
+     * This information may be used to cache the value of expressions.
+     *
+     * **Default:** `true`
+     */
+    pure: boolean;
 };
-export type RuleSteps = RuleStep[];
 /**
- * To create a BoxedRuleSet use the `ce.rules()` method.
- *
- * Do not create a `BoxedRuleSet` directly.
+ * @category Definitions
  *
- * @category Rules */
-export type BoxedRuleSet = {
-    rules: ReadonlyArray<BoxedRule>;
+ */
+export type BoxedFunctionDefinition = BoxedBaseDefinition & FunctionDefinitionFlags & {
+    complexity: number;
+    /** If true, the signature was inferred from usage and may be modified
+     * as more information becomes available.
+     */
+    inferredSignature: boolean;
+    /** The type of the arguments and return value of this function */
+    signature: BoxedType;
+    /** If present, this handler can be used to more precisely determine the
+     * return type based on the type of the arguments. The arguments themselves
+     * should *not* be evaluated, only their types should be used.
+     */
+    type?: (ops: ReadonlyArray<BoxedExpression>, options: {
+        engine: ComputeEngine;
+    }) => Type | TypeString | BoxedType | undefined;
+    /** If present, this handler can be used to determine the sign of the
+     *  return value of the function, based on the sign and type of its
+     *  arguments.
+     *
+     * The arguments themselves should *not* be evaluated, only their types and
+     * sign should be used.
+     *
+     * This can be used in some case for example to determine when certain
+     * simplifications are valid.
+     */
+    sgn?: (ops: ReadonlyArray<BoxedExpression>, options: {
+        engine: ComputeEngine;
+    }) => Sign | undefined;
+    eq?: (a: BoxedExpression, b: BoxedExpression) => boolean | undefined;
+    neq?: (a: BoxedExpression, b: BoxedExpression) => boolean | undefined;
+    canonical?: (ops: ReadonlyArray<BoxedExpression>, options: {
+        engine: ComputeEngine;
+    }) => BoxedExpression | null;
+    evaluate?: (ops: ReadonlyArray<BoxedExpression>, options: Partial<EvaluateOptions> & {
+        engine?: ComputeEngine;
+    }) => BoxedExpression | undefined;
+    evaluateAsync?: (ops: ReadonlyArray<BoxedExpression>, options?: Partial<EvaluateOptions> & {
+        engine?: ComputeEngine;
+    }) => Promise<BoxedExpression | undefined>;
+    evalDimension?: (ops: ReadonlyArray<BoxedExpression>, options: {
+        engine: ComputeEngine;
+    }) => BoxedExpression;
+    compile?: (expr: BoxedExpression) => CompiledExpression;
 };
 /**
- * @noInheritDoc
+ * The entries have been validated and optimized for faster evaluation.
  *
- * @category Pattern Matching
+ * 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 Pattern = BoxedExpression;
+export type RuntimeIdentifierDefinitions = Map<string, OneOf<[BoxedSymbolDefinition, BoxedFunctionDefinition]>>;
+/** @category Assumptions */
+export interface ExpressionMapInterface<U> {
+    has(expr: BoxedExpression): boolean;
+    get(expr: BoxedExpression): U | undefined;
+    set(expr: BoxedExpression, value: U): void;
+    delete(expr: BoxedExpression): void;
+    clear(): void;
+    [Symbol.iterator](): IterableIterator<[BoxedExpression, U]>;
+    entries(): IterableIterator<[BoxedExpression, U]>;
+}
+/** @category Assumptions */
+export type AssumeResult = 'internal-error' | 'not-a-predicate' | 'contradiction' | 'tautology' | 'ok';
 /**
- * @category Boxed Expression
+ * 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 BoxedSubstitution = Substitution<BoxedExpression>;
+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.
@@ -1679,33 +2013,8 @@ export type BoxedSubstitution = Substitution<BoxedExpression>;
  * @category Boxed Expression
  */
 export type CanonicalForm = 'InvisibleOperator' | 'Number' | 'Multiply' | 'Add' | 'Power' | 'Divide' | 'Flatten' | 'Order';
+/** @category Boxed Expression */
 export type CanonicalOptions = boolean | CanonicalForm | CanonicalForm[];
-/** Options for `BoxedExpression.simplify()`
- *
- * @category Compute Engine
- */
-export type SimplifyOptions = {
-    /**
-     * The set of rules to apply. If `null`, use no rules. If not provided,
-     * use the default simplification rules.
-     */
-    rules?: null | Rule | ReadonlyArray<BoxedRule | Rule> | BoxedRuleSet;
-    /**
-     * Use this cost function to determine if a simplification is worth it.
-     *
-     * If not provided, `ce.costFunction`, the cost function of the engine is
-     * used.
-     */
-    costFunction?: (expr: BoxedExpression) => number;
-};
-/** Options for `BoxedExpression.evaluate()`
- *
- * @category Boxed Expression
- */
-export type EvaluateOptions = {
-    numericApproximation: boolean;
-    signal: AbortSignal;
-};
 /**
  * Metadata that can be associated with a `BoxedExpression`
  *
@@ -1716,33 +2025,132 @@ export type Metadata = {
     wikidata?: string | undefined;
 };
 /**
- * When a unitless value is passed to or returned from a trigonometric function,
- * the angular unit of the value.
+ * A substitution describes the values of the wildcards in a pattern so that
+ * the pattern is equal to a target expression.
  *
- * - `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
+ * A substitution can also be considered a more constrained version of a
+ * rule whose `match` is always a symbol.
+
+* @category Pattern Matching
+ */
+export type Substitution<T = SemiBoxedExpression> = {
+    [symbol: string]: T;
+};
+/**
+ * @category Pattern Matching
  *
- * @category Compute Engine
  */
-export type AngularUnit = 'rad' | 'deg' | 'grad' | 'turn';
-/** @category Compute Engine */
-export type ArrayValue = boolean | number | string | BigNum | BoxedExpression | undefined;
-/** @category Assumptions */
-export type AssumeResult = 'internal-error' | 'not-a-predicate' | 'contradiction' | 'tautology' | 'ok';
-/** @category Compute Engine */
-export type AssignValue = boolean | number | SemiBoxedExpression | ((args: ReadonlyArray<BoxedExpression>, options: EvaluateOptions & {
-    engine: IComputeEngine;
-}) => BoxedExpression) | undefined;
-/** @internal */
-export interface IComputeEngine extends IBigNum {
-    latexDictionary: readonly LatexDictionaryEntry[];
-    /** @private */
-    indexedLatexDictionary: IndexedLatexDictionary;
-    decimalSeparator: LatexString;
-    readonly True: BoxedExpression;
-    readonly False: BoxedExpression;
+export type BoxedSubstitution = Substitution<BoxedExpression>;
+/**
+ * Given an expression and set of wildcards, return a new expression.
+ *
+ * For example:
+ *
+ * ```ts
+ * {
+ *    match: '_x',
+ *    replace: (expr, {_x}) => { return ['Add', 1, _x] }
+ * }
+ * ```
+ *
+ * @category Rules */
+export type RuleReplaceFunction = (expr: BoxedExpression, wildcards: BoxedSubstitution) => BoxedExpression | undefined;
+/** @category Rules */
+export type RuleConditionFunction = (wildcards: BoxedSubstitution, ce: ComputeEngine) => boolean;
+/** @category Rules */
+export type RuleFunction = (expr: BoxedExpression) => undefined | BoxedExpression | RuleStep;
+/** @category Rules */
+export type RuleStep = {
+    value: BoxedExpression;
+    because: string;
+};
+/** @category Rules */
+export type RuleSteps = RuleStep[];
+/**
+ * A rule describes how to modify an expressions that matches a pattern `match`
+ * into a new expression `replace`.
+ *
+ * - `x-1` \( \to \) `1-x`
+ * - `(x+1)(x-1)` \( \to \) `x^2-1
+ *
+ * The patterns can be expressed as LaTeX strings or a MathJSON expressions.
+ *
+ * As a shortcut, a rule can be defined as a LaTeX string: `x-1 -> 1-x`.
+ * The expression to the left of `->` is the `match` and the expression to the
+ * right is the `replace`. When using LaTeX strings, single character variables
+ * are assumed to be wildcards.
+ *
+ * When using MathJSON expressions, anonymous wildcards (`_`) will match any
+ * expression. Named wildcards (`_x`, `_a`, etc...) will match any expression
+ * and bind the expression to the wildcard name.
+ *
+ * In addition the sequence wildcard (`__1`, `__a`, etc...) will match
+ * a sequence of one or more expressions, and bind the sequence to the
+ * wildcard name.
+ *
+ * Sequence wildcards are useful when the number of elements in the sequence
+ * is not known in advance. For example, in a sum, the number of terms is
+ * not known in advance. ["Add", 0, `__a`] will match two or more terms and
+ * the `__a` wildcard will be a sequence of the matchign terms.
+ *
+ * If `exact` is false, the rule will match variants.
+ *
+ * For example 'x' will match 'a + x', 'x' will match 'ax', etc...
+ *
+ * For simplification rules, you generally want `exact` to be true, but
+ * to solve equations, you want it to be false. Default to true.
+ *
+ * When set to false, infinite recursion is possible.
+ *
+ * @category Rules
+ */
+export type Rule = string | RuleFunction | {
+    match?: LatexString | SemiBoxedExpression | BoxedExpression;
+    replace: LatexString | SemiBoxedExpression | RuleReplaceFunction | RuleFunction;
+    condition?: LatexString | RuleConditionFunction;
+    useVariations?: boolean;
+    id?: string;
+};
+/**
+ *
+ * If the `match` property is `undefined`, all expressions match this rule
+ * and `condition` should also be `undefined`. The `replace` property should
+ * be a `BoxedExpression` or a `RuleFunction`, and further filtering can be
+ * done in the `replace` function.
+ *
+ * @category Rules
+ */
+export type BoxedRule = {
+    /** @internal */
+    readonly _tag: 'boxed-rule';
+    match: undefined | BoxedExpression;
+    replace: BoxedExpression | RuleReplaceFunction | RuleFunction;
+    condition: undefined | RuleConditionFunction;
+    useVariations?: boolean;
+    id?: string;
+};
+/**
+ * To create a BoxedRuleSet use the `ce.rules()` method.
+ *
+ * Do not create a `BoxedRuleSet` directly.
+ *
+ * @category Rules
+ */
+export type BoxedRuleSet = {
+    rules: ReadonlyArray<BoxedRule>;
+};
+/** @category Compute Engine */
+export type AssignValue = boolean | number | SemiBoxedExpression | ((args: ReadonlyArray<BoxedExpression>, options: EvaluateOptions & {
+    engine: ComputeEngine;
+}) => BoxedExpression) | undefined;
+/** @internal */
+export interface ComputeEngine extends IBigNum {
+    latexDictionary: readonly LatexDictionaryEntry[];
+    /** @private */
+    indexedLatexDictionary: IndexedLatexDictionary;
+    decimalSeparator: LatexString;
+    readonly True: BoxedExpression;
+    readonly False: BoxedExpression;
     readonly Pi: BoxedExpression;
     readonly E: BoxedExpression;
     readonly Nothing: BoxedExpression;
@@ -1875,8 +2283,8 @@ export interface IComputeEngine extends IBigNum {
     parse(latex: LatexString | null, options?: Partial<ParseLatexOptions> & {
         canonical?: CanonicalOptions;
     }): BoxedExpression | null;
-    pushScope(scope?: Partial<Scope>): IComputeEngine;
-    popScope(): IComputeEngine;
+    pushScope(scope?: Partial<Scope>): ComputeEngine;
+    popScope(): ComputeEngine;
     swapScope(scope: RuntimeScope | null): RuntimeScope | null;
     resetContext(): void;
     defineSymbol(name: string, def: SymbolDefinition): BoxedSymbolDefinition;
@@ -1885,18 +2293,18 @@ export interface IComputeEngine extends IBigNum {
     lookupFunction(name: string, scope?: RuntimeScope | null): undefined | BoxedFunctionDefinition;
     assign(ids: {
         [id: string]: AssignValue;
-    }): IComputeEngine;
-    assign(id: string, value: AssignValue): IComputeEngine;
+    }): ComputeEngine;
+    assign(id: string, value: AssignValue): ComputeEngine;
     assign(arg1: string | {
         [id: string]: AssignValue;
-    }, arg2?: AssignValue): IComputeEngine;
+    }, arg2?: AssignValue): ComputeEngine;
     declare(identifiers: {
         [id: string]: Type | TypeString | OneOf<[SymbolDefinition | FunctionDefinition]>;
-    }): IComputeEngine;
-    declare(id: string, def: Type | TypeString | SymbolDefinition | FunctionDefinition): IComputeEngine;
+    }): 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]>): IComputeEngine;
+    }, arg2?: Type | OneOf<[SymbolDefinition | FunctionDefinition]>): ComputeEngine;
     assume(predicate: BoxedExpression): AssumeResult;
     forget(symbol?: string | string[]): void;
     get assumptions(): ExpressionMapInterface<boolean>;
@@ -1923,383 +2331,3 @@ export interface ComputeEngineStats {
     expressions: null | Set<BoxedExpression>;
     highwaterMark: number;
 }
-/**
- * Options to control the serialization to MathJSON when using `BoxedExpression.toMathJson()`.
- *
- * @category Compute Engine
- */
-export type JsonSerializationOptions = {
-    /** If true, the serialization applies some transformations to make
-     * the JSON more readable. For example, `["Power", "x", 2]` is serialized
-     * as `["Square", "x"]`.
-     */
-    prettify: boolean;
-    /** A list of space separated function names that should be excluded from
-     * the JSON output.
-     *
-     * Those functions are replaced with an equivalent, for example, `Square` with
-     * `Power`, etc...
-     *
-     * Possible values include `Sqrt`, `Root`, `Square`, `Exp`, `Subtract`,
-     * `Rational`, `Complex`
-     *
-     * **Default**: `[]` (none)
-     */
-    exclude: string[];
-    /** A list of space separated keywords indicating which MathJSON expressions
-     * can use a shorthand.
-     *
-     * **Default**: `["all"]`
-     */
-    shorthands: ('all' | 'number' | 'symbol' | 'function' | 'string')[];
-    /** A list of space separated keywords indicating which metadata should be
-     * included in the MathJSON. If metadata is included, shorthand notation
-     * is not used.
-     *
-     * **Default**: `[]`  (none)
-     */
-    metadata: ('all' | 'wikidata' | 'latex')[];
-    /** If true, repeating decimals are detected and serialized accordingly
-     * For example:
-     * - `1.3333333333333333` \( \to \) `1.(3)`
-     * - `0.142857142857142857142857142857142857142857142857142` \( \to \) `0.(1428571)`
-     *
-     * **Default**: `true`
-     */
-    repeatingDecimal: boolean;
-    /**
-     * The maximum number of significant digits in serialized numbers.
-     * - `"max"`: all availabe digits are serialized.
-     * - `"auto"`: use the same precision as the compute engine.
-     *
-     * **Default**: `"auto"`
-     */
-    fractionalDigits: 'auto' | 'max' | number;
-};
-/** A LaTeX string starts and end with `$`, for example
- * `"$\frac{\pi}{2}$"`.
- *
- * @category Latex Parsing and Serialization
- */
-export type LatexString = string;
-/**
- * Control how a pattern is matched to an expression.
- *
- * - `substitution`: if present, assumes these values for the named wildcards,
- *    and ensure that subsequent occurrence of the same wildcard have the same
- *    value.
- * - `recursive`: if true, match recursively, otherwise match only the top
- *    level.
- * - `useVariations`: if false, only match expressions that are structurally identical.
- *    If true, match expressions that are structurally identical or equivalent.
- *
- *    For example, when true, `["Add", '_a', 2]` matches `2`, with a value of
- *    `_a` of `0`. If false, the expression does not match. **Default**: `false`
- *
- * @category Pattern Matching
- *
- */
-export type PatternMatchOptions = {
-    substitution?: BoxedSubstitution;
-    recursive?: boolean;
-    useVariations?: boolean;
-};
-/**
- * @category Boxed Expression
- *
- */
-export type ReplaceOptions = {
-    /**
-     * If `true`, apply replacement rules to all sub-expressions.
-     *
-     * If `false`, only consider the top-level expression.
-     *
-     * **Default**: `false`
-     */
-    recursive: boolean;
-    /**
-     * If `true`, stop after the first rule that matches.
-     *
-     * If `false`, apply all the remaining rules even after the first match.
-     *
-     * **Default**: `false`
-     */
-    once: boolean;
-    /**
-     * If `true` the rule will use some equivalent variations to match.
-     *
-     * For example when `useVariations` is true:
-     * - `x` matches `a + x` with a = 0
-     * - `x` matches `ax` with a = 1
-     * - etc...
-     *
-     * Setting this to `true` can save time by condensing multiple rules
-     * into one. This can be particularly useful when describing equations
-     * solutions. However, it can lead to infinite recursion and should be
-     * used with caution.
-     *
-     */
-    useVariations: boolean;
-    /**
-     * If `iterationLimit` > 1, the rules will be repeatedly applied
-     * until no rules apply, up to `maxIterations` times.
-     *
-     * Note that if `once` is true, `iterationLimit` has no effect.
-     *
-     * **Default**: `1`
-     */
-    iterationLimit: number;
-    /**
-     * Indicate if the expression should be canonicalized after the replacement.
-     * If not provided, the expression is canonicalized if the expression
-     * that matched the pattern is canonical.
-     */
-    canonical: CanonicalOptions;
-};
-/**
- * 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 Boxed Expression
- */
-export type Substitution<T = SemiBoxedExpression> = {
-    [symbol: string]: T;
-};
-/** @category Assumptions */
-export interface ExpressionMapInterface<U> {
-    has(expr: BoxedExpression): boolean;
-    get(expr: BoxedExpression): U | undefined;
-    set(expr: BoxedExpression, value: U): void;
-    delete(expr: BoxedExpression): void;
-    clear(): void;
-    [Symbol.iterator](): IterableIterator<[BoxedExpression, U]>;
-    entries(): IterableIterator<[BoxedExpression, U]>;
-}
-/**
- * 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]>>;
-/**
- * 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 = {};
-/** @category Compute Engine */
-export type RuntimeScope = Scope & {
-    parentScope?: RuntimeScope;
-    ids?: RuntimeIdentifierDefinitions;
-    assumptions: undefined | ExpressionMapInterface<boolean>;
-};
-/**
- * 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')
- * @category Definitions
- */
-export type SymbolDefinition = BaseDefinition & Partial<SymbolAttributes> & {
-    type?: Type | TypeString;
-    /** 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;
-    /** `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: IComputeEngine) => BoxedExpression | null);
-    flags?: Partial<NumericFlags>;
-    eq?: (a: BoxedExpression) => boolean | undefined;
-    neq?: (a: BoxedExpression) => boolean | undefined;
-    cmp?: (a: BoxedExpression) => '=' | '>' | '<' | undefined;
-    collection?: Partial<CollectionHandlers>;
-};
-/**
- * Definition record for a function.
- * @category Definitions
- *
- */
-export type FunctionDefinition = BaseDefinition & Partial<FunctionDefinitionFlags> & {
-    /**
-     * The function signature.
-     *
-     * 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;
-    /**
-     * The actual type of the result based on the arguments.
-     *
-     * Should be a subtype of the type indicated in the signature.
-     *
-     * Do not evaluate the arguments.
-     *
-     * The type of the arguments can be used to determine the type of the
-     * result.
-     *
-     */
-    type?: (ops: ReadonlyArray<BoxedExpression>, options: {
-        engine: IComputeEngine;
-    }) => Type | TypeString | BoxedType | undefined;
-    /** Return the sign of the function expression.
-     *
-     * If the sign cannot be determined, return `undefined`.
-     *
-     * When determining the sign, only literal values and the values of
-     * symbols, if they are literals, should be considered.
-     *
-     * Do not evaluate the arguments.
-     *
-     * The type and sign of the arguments can be used to determine the sign.
-     *
-     */
-    sgn?: (ops: ReadonlyArray<BoxedExpression>, options: {
-        engine: IComputeEngine;
-    }) => Sign | undefined;
-    /** Return true of the function expression is even, false if it is odd and
-     * undefined if it is neither.
-     */
-    even?: (ops: ReadonlyArray<BoxedExpression>, options: {
-        engine: IComputeEngine;
-    }) => boolean | undefined;
-    /**
-     * A number used to order arguments.
-     *
-     * Argument with higher complexity are placed after arguments with
-     * lower complexity when ordered canonically in commutative functions.
-     *
-     * - Additive functions: 1000-1999
-     * - Multiplicative functions: 2000-2999
-     * - Root and power functions: 3000-3999
-     * - Log functions: 4000-4999
-     * - Trigonometric functions: 5000-5999
-     * - Hypertrigonometric functions: 6000-6999
-     * - Special functions (factorial, Gamma, ...): 7000-7999
-     * - Collections: 8000-8999
-     * - Inert and styling:  9000-9999
-     * - Logic: 10000-10999
-     * - Relational: 11000-11999
-     *
-     * **Default**: 100,000
-     */
-    complexity?: number;
-    /**
-     * Return the canonical form of the expression with the arguments `args`.
-     *
-     * 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.
-     *
-     * 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
-     *
-     * If the type of an argument is not compatible, it should be indicated
-     * with an `incompatible-type` error.
-     *
-     * `["Sequence"]` expressions are not folded and need to be handled
-     *  explicitly.
-     *
-     * If the function is associative, idempotent or an involution,
-     * this handler should account for it. Notably, if it is commutative, the
-     * arguments should be sorted in canonical order.
-     *
-     *
-     * Values of symbols should not be substituted, unless they have
-     * a `holdUntil` attribute of `"never"`.
-     *
-     * The handler should not consider the value or any assumptions about any
-     * of the arguments that are symbols or functions (i.e. `arg.isZero`,
-     * `arg.isInteger`, etc...) since those may change over time.
-     *
-     * The result of the handler should be a canonical expression.
-     *
-     * If the arguments do not match, they should be replaced with an appropriate
-     * `["Error"]` expression. If the expression cannot be put in canonical form,
-     * the handler should return `null`.
-     *
-     */
-    canonical?: (ops: ReadonlyArray<BoxedExpression>, options: {
-        engine: IComputeEngine;
-    }) => BoxedExpression | null;
-    /**
-     * Evaluate a function expression.
-     *
-     * The arguments have been evaluated, except the arguments to which a
-     * `hold` applied.
-     *
-     * It is not necessary to further simplify or evaluate the arguments.
-     *
-     * If performing numerical calculations and `options.numericalApproximation`
-     * is `false` return an exact numeric value, for example return a rational
-     * 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
-     * an `["Error"]` expression.
-     */
-    evaluate?: ((ops: ReadonlyArray<BoxedExpression>, options: EvaluateOptions & {
-        engine: IComputeEngine;
-    }) => BoxedExpression | undefined) | BoxedExpression;
-    /**
-     * An option asynchronous version of `evaluate`.
-     *
-     */
-    evaluateAsync?: (ops: ReadonlyArray<BoxedExpression>, options: EvaluateOptions & {
-        engine: IComputeEngine;
-    }) => Promise<BoxedExpression | undefined>;
-    /** Dimensional analysis
-     * @experimental
-     */
-    evalDimension?: (args: ReadonlyArray<BoxedExpression>, options: EvaluateOptions & {
-        engine: IComputeEngine;
-    }) => BoxedExpression;
-    /** Return a compiled (optimized) expression. */
-    compile?: (expr: BoxedExpression) => CompiledExpression;
-    eq?: (a: BoxedExpression, b: BoxedExpression) => boolean | undefined;
-    neq?: (a: BoxedExpression, b: BoxedExpression) => boolean | undefined;
-    collection?: Partial<CollectionHandlers>;
-};
-/**
- * @category Definitions
- *
- */
-export type BaseDefinition = {
-    /** A short (about 1 line) description. May contain Markdown. */
-    description?: string | string[];
-    /** A URL pointing to more information about this symbol or operator. */
-    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 the `Pi` constant.
-     */
-    wikidata?: string;
-};