@cortex-js/compute-engine 0.15.0 → 0.17.0

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

@@ -1,4 +1,4 @@
-/* 0.15.0 */
+/* 0.17.0 */
  * The most important classes are {@link ComputeEngine} and
  * {@link BoxedExpression}.
  *
@@ -7,8 +7,8 @@
  *
  * @module ComputeEngine
  */
-import type { Decimal } from 'decimal.js';
 import type { Complex } from 'complex.js';
+import type { Decimal } from 'decimal.js';
 import type { Expression, MathJsonDictionary, MathJsonFunction, MathJsonNumber, MathJsonString, MathJsonSymbol } from '../math-json/math-json-format';
 import type { LatexDictionaryEntry, NumberFormattingOptions, ParseLatexOptions, SerializeLatexOptions } from './latex-syntax/public';
 export * from './latex-syntax/public';
@@ -35,6 +35,7 @@ export type Metadata = {
 </div>
  */
 export type NumericMode = 'auto' | 'machine' | 'bignum' | 'complex';
+export type Hold = 'none' | 'all' | 'first' | 'rest' | 'last' | 'most';
 /** Options for `BoxedExpression.simplify()` */
 export type SimplifyOptions = {
     recursive?: boolean;
@@ -42,9 +43,10 @@ export type SimplifyOptions = {
 };
 /** Options for `BoxedExpression.evaluate()`
  *
- * @internal
  */
-export type EvaluateOptions = {};
+export type EvaluateOptions = {
+    numericMode?: boolean;
+};
 /** Options for `BoxedExpression.N()`
  * @internal
  */
@@ -126,49 +128,24 @@ export type BoxedRule = [
 export type BoxedRuleSet = Set<BoxedRule>;
 export type DomainCompatibility = 'covariant' | 'contravariant' | 'bivariant' | 'invariant';
 /** A domain constructor is the head of a domain expression. */
-export type DomainConstructor = 'InvalidDomain' | 'Matrix' | 'SquareMatrix' | 'Vector' | 'Function' | 'List' | 'Dictionary' | 'Tuple' | 'Range' | 'Interval' | 'Intersection' | 'Union' | 'Maybe' | 'Sequence' | 'Head' | 'Symbol' | 'Value' | 'Covariant' | 'Contravariant' | 'Bivariant' | 'Invariant';
-export type DomainLiteral = string;
-export type DomainExpression<T = SemiBoxedExpression> = DomainLiteral | [DomainConstructor, ...(string | T | DomainExpression<T>)[]] | ['InvalidDomain', T] | ['Union', ...DomainExpression<T>[]] | ['Intersection', ...DomainExpression<T>[]] | ['Matrix', DomainExpression<T>, T, T] | ['SquareMatrix', DomainExpression<T>, T] | ['Vector', DomainExpression<T>, T] | ['List', DomainExpression<T>] | ['Dictionary', DomainExpression<T>] | ['Tuple', ...DomainExpression<T>[]] | ['Maybe', DomainExpression<T>] | ['Sequence', DomainExpression<T>] | ['Range'] | ['Range', T] | ['Range', T, T] | ['Range', T, T, T] | ['Interval', T, T] | ['Interval', ['Open', T], T] | ['Interval', T, ['Open', T]] | ['Interval', ['Open', T], ['Open', T]] | ['Value', T] | ['Head', string] | ['Symbol', string] | ['Covariant', DomainExpression<T>] | ['Contravariant', DomainExpression<T>] | ['Bivariant', DomainExpression<T>] | ['Invariant', DomainExpression<T>] | ['Function', ...DomainExpression<T>[]];
+export type DomainConstructor = 'FunctionOf' | 'ListOf' | 'DictionaryOf' | 'TupleOf' | 'Intersection' | 'Union' | 'OptArg' | 'VarArg' | 'Covariant' | 'Contravariant' | 'Bivariant' | 'Invariant';
+export type DomainLiteral = 'Anything' | 'Values' | 'Domains' | 'Void' | 'NothingDomain' | 'Booleans' | 'Strings' | 'Symbols' | 'Collections' | 'Lists' | 'Dictionaries' | 'Sequences' | 'Tuples' | 'Sets' | 'Functions' | 'Predicates' | 'LogicOperators' | 'RelationalOperators' | 'NumericFunctions' | 'RealFunctions' | 'Numbers' | 'ComplexNumbers' | 'ExtendedRealNumbers' | 'ImaginaryNumbers' | 'Integers' | 'Rationals' | 'PositiveNumbers' | 'PositiveIntegers' | 'NegativeNumbers' | 'NegativeIntegers' | 'NonNegativeNumbers' | 'NonNegativeIntegers' | 'NonPositiveNumbers' | 'NonPositiveIntegers' | 'ExtendedComplexNumbers' | 'TranscendentalNumbers' | 'AlgebraicNumbers' | 'RationalNumbers' | 'RealNumbers';
+export type DomainExpression<T = SemiBoxedExpression> = DomainLiteral | ['Union', ...(DomainExpression<T> | BoxedExpression)[]] | ['Intersection', ...(DomainExpression<T> | BoxedExpression)[]] | ['ListOf', DomainExpression<T>] | ['DictionaryOf', DomainExpression<T>] | ['TupleOf', ...DomainExpression<T>[]] | ['OptArg', ...DomainExpression<T>[]] | ['VarArg', DomainExpression<T>] | ['Covariant', DomainExpression<T>] | ['Contravariant', DomainExpression<T>] | ['Bivariant', DomainExpression<T>] | ['Invariant', DomainExpression<T>] | ['FunctionOf', ...DomainExpression<T>[]];
 export interface BoxedDomain extends BoxedExpression {
-    is(s: BoxedDomain): boolean;
-    /** True if a valid domain, and compatible with `dom` */
-    isCompatible(dom: BoxedDomain | DomainLiteral, kind?: DomainCompatibility): boolean;
-    get literal(): string | null;
-    get ctor(): DomainConstructor | null;
-    get domainArgs(): (DomainExpression<BoxedExpression> | BoxedExpression | string)[] | null;
-    get domainArg1(): string | BoxedExpression | DomainExpression<BoxedExpression> | null;
-    get codomain(): BoxedDomain | null;
     get canonical(): BoxedDomain;
     get json(): Expression;
-    readonly isNothing: boolean;
+    /** True if a valid domain, and compatible with `dom`
+     * `kind` is '"covariant"' by default, i.e. `this <: dom`
+     */
+    isCompatible(dom: BoxedDomain | DomainLiteral, kind?: DomainCompatibility): boolean;
+    get base(): DomainLiteral;
+    get ctor(): DomainConstructor | null;
+    get params(): BoxedDomain[];
+    get optParams(): BoxedDomain[];
+    get restParam(): BoxedDomain | null;
+    get result(): BoxedDomain | null;
     readonly isNumeric: boolean;
     readonly isFunction: boolean;
-    /**
-     * If true, when all the arguments are numeric, the result of the
-     * evaluation is numeric. Numeric is any value with a domain of `Number`.
-     *
-     * Example of numeric functions: `Add`, `Multiply`, `Power`, `Abs`
-     *
-     * Default: `false`
-     */
-    /**
-     * If true, when all the arguments are boolean, the result of the
-     * evaluation is a boolean. Boolean is any value with a domain of `MaybeBoolean`.
-     *
-     * Example of logic functions: `And`, `Or`, `Not`, `Implies`
-     *
-     * **Default:** `false`
-     */
-    /**
-     * The function represent a relation between the first argument and
-     * the second argument, and evaluates to a boolean indicating if the relation
-     * is satisfied.
-     *
-     * For example, `Equal`, `Less`, `Approx`, etc...
-     *
-     * **Default:** `false`
-     */
-    readonly isRelationalOperator: boolean;
 }
 /**
  * Options to control the serialization to MathJSON when using `BoxedExpression.json`.
@@ -216,7 +193,7 @@ export type JsonSerializationOptions = {
     precision: 'auto' | 'max' | number;
 };
 /**
- * **Theory of Operations**
+ * ## THEORY OF OPERATIONS
  *
  * The `BoxedExpression` interface includes most of the member functions
  * applicable to any kind of expression, for example `get symbol()` or
@@ -350,17 +327,29 @@ export interface BoxedExpression {
      *
      */
     readonly subexpressions: BoxedExpression[];
-    /** All the symbols in the expression, recursively
+    /**
+     *
+     * All the symbols in the expression, recursively
      *
      * **Note** applicable to canonical and non-canonical expressions.
      *
      */
     readonly symbols: string[];
     /**
-     * All the free variables in the expression, recursively,
-     * that is all the symbols with no value
+     * All the identifiers used in the expression that do not have a value
+     * associated with them, i.e. they are declared but not defined.
+     */
+    readonly unknowns: string[];
+    /**
+     *
+     * All the identifiers (symbols and functions) in the expression that are a
+     * free variable.
+     *
+     * A free variable is an identifier that is used in a function but is not a
+     * local variable or a parameter of that function.
+     *
      */
-    readonly freeVars: string[];
+    readonly freeVariables: string[];
     /** All the `["Error"]` subexpressions
      *
      * **Note** applicable to canonical and non-canonical expressions.
@@ -462,8 +451,6 @@ export interface BoxedExpression {
      * **Note** applicable to canonical and non-canonical expressions.
      */
     readonly isPure: boolean;
-    /** True if the expression is a free variable, that is a symbol with no value */
-    readonly isFree: boolean;
     /** True if the expression is a constant, that is a symbol with an immutable value */
     readonly isConstant: boolean;
     /**
@@ -484,21 +471,6 @@ export interface BoxedExpression {
      *
      */
     get canonical(): BoxedExpression;
-    /**
-     * If this expression is a function, apply the function `fn` to all its operands.
-     *
-     * Replace the head of this expression with `head`, if defined.
-     *
-     * If this expression is a dictionary, return a new dictionary with the values
-     * modified by `fn`.
-     *
-     * If `head` is provided, return a function expression with the modified
-     * dictionary as operand, otherwise return the  modified dictionary.
-     *
-     * **Note** applicable to canonical and non-canonical expressions.
-     *
-     * */
-    apply(fn: (x: BoxedExpression) => SemiBoxedExpression, head?: string): BoxedExpression;
     /**
      * Replace all the symbols in the expression as indicated.
      *
@@ -722,12 +694,9 @@ export interface BoxedExpression {
     /** Wikidata identifier.
      *
      * **Note** `undefined` if not a canonical expression.
-     *
-     *
      */
-    get wikidata(): string | undefined;
-    set wikidata(val: string | undefined);
-    /** An optional short description if the symbol or function head.
+    readonly wikidata: string | undefined;
+    /** An optional short description if a symbol or function expression.
      *
      * May include markdown. Each string is a paragraph.
      *
@@ -736,7 +705,7 @@ export interface BoxedExpression {
      */
     readonly description: undefined | string[];
     /** An optional URL pointing to more information about the symbol or
-     *  function head
+     *  function head.
      *
      * **Note** `undefined` if not a canonical expression.
      *
@@ -750,13 +719,13 @@ export interface BoxedExpression {
     readonly complexity: number | undefined;
     /**
      * For symbols and functions, a possible definition associated with the
-     *  expression. `basedDefinition` is the base class of symbol and function
+     *  expression. `baseDefinition` is the base class of symbol and function
      *  definition.
      *
      * **Note** `undefined` if not a canonical expression.
      *
      */
-    readonly basedDefinition: BoxedBaseDefinition | undefined;
+    readonly baseDefinition: BoxedBaseDefinition | undefined;
     /**
      * For functions, a possible definition associated with the expression.
      *
@@ -772,32 +741,35 @@ export interface BoxedExpression {
      */
     readonly symbolDefinition: BoxedSymbolDefinition | undefined;
     /**
-     * The domain of this expression, without accounting for any inferred domain
-     * or `ce.defaultDomain`. If no domain has been explicitly set via assignment
-     * or via an `.assume()` directive, the `expr.explicitDomain` is `undefined`.
      *
-     * This is useful to determine if the domain of an expression is inferred.
+     * Infer the domain of this expression.
      *
-     * In most cases you'll want to  use `expr.domain` instead.
+     * If the domain of this expression is already known, return `false`.
      *
-     * **Note** `undefined` if not a canonical expression or not a function.
+     * If the domain was not set, set it to the inferred domain, return `true`
+     * If the domain was previously inferred, adjust it by widening it,
+     *    return `true`
      *
+     * @internal
      */
-    readonly explicitDomain: BoxedDomain | undefined;
+    infer(domain: BoxedDomain): boolean;
     /**
-     * Update the definition associated with this expression, taking
-     * into account the specified scope.
-     *
-     * **Note**: applicable only to canonical expressions
+     * Update the definition associated with this expression, using the
+     * current scope (`ce.context`).
      *
      * @internal
      */
-    bind(scope: RuntimeScope | null): void;
+    bind(): void;
     /**
+     *
+     * Reset the cached value associated with this expression.
+     *
+     * Use when the environment has changed, for example the numeric mode
+     * or precision, to force the expression to be re-evaluated.
      *
      * @internal
      */
-    unbind(): void;
+    reset(): void;
     /**
      * Return a simpler form of the canonical form of this expression.
      *
@@ -844,9 +816,7 @@ export interface BoxedExpression {
      * The result is in canonical form.
      *
      */
-    evaluate(ids?: {
-        [id: string]: SemiBoxedExpression | null | undefined;
-    }): BoxedExpression;
+    evaluate(options?: EvaluateOptions): BoxedExpression;
     /** Return a numeric approximation of the canonical form of this expression.
      *
      * Any necessary calculations, including on decimal numbers (non-integers),
@@ -877,32 +847,38 @@ export interface BoxedExpression {
      * **Note**: If non-canonical, return the value of its canonical counterpart
      */
     get value(): BoxedExpression | undefined;
-    /** Only the value of variables can be changed (symbols that are not
+    /**
+     * Only the value of variables can be changed (symbols that are not
      * constants).
      *
+     * Throws a runtime error if a constant.
+     *
      * **Note**: If non-canonical, does nothing.
      *
      */
     set value(value: BoxedExpression | number | undefined);
-    /** The domain of the value of this expression.
+    /**
      *
-     * If a function expression, the domain  of the value of the function (the codomain of the function).
+     * The domain of the value of this expression.
+     *
+     * If a function expression, the domain  of the value of the function
+     * (the codomain of the function).
      *
      * If a symbol the domain of the value of the symbol.
      *
-     * Use `expr.head` to determine if an expression is a symbol or function.
+     * Use `expr.head` to determine if an expression is a symbol or function
+     * expression.
+     *
+     * **Note**: if non-canonical or not valid, return `undefined`.
      *
-     * **Note**: If non-canonical, return the domain of its canonical
-     * counterpart
      */
-    get domain(): BoxedDomain;
-    /** Modify the domain of a symbol that represent a variable
-     * (or a function name).
+    get domain(): BoxedDomain | undefined;
+    /** Modify the domain of a symbol.
      *
      * **Note**: If non-canonical, does nothing.
      *
      */
-    set domain(domain: BoxedExpression | DomainExpression | BoxedDomain);
+    set domain(domain: DomainExpression | BoxedDomain | undefined);
     /** `true` if the value of this expression is a number.
      *
      * `isExtendedComplex || isNaN` = `isReal || isImaginary || isInfinity || isNaN`
@@ -1020,33 +996,32 @@ export interface ExpressionMapInterface<U> {
     delete(expr: BoxedExpression): void;
     clear(): void;
     [Symbol.iterator](): IterableIterator<[BoxedExpression, U]>;
+    entries(): IterableIterator<[BoxedExpression, U]>;
 }
 /**
- * An ID table contains definitions for symbols and functions.
- *
- * The index of the table is an identifier, the  name of the symbol or
- * function for this definition
+ * A table mapping identifiers to their definition.
  *
- * The name of a symbol or function is an arbitrary string of Unicode
- * characters, however the following conventions are recommended:
+ * Identifiers should be valid MathJSON identifiers. In addition, the
+ * following rules are recommended:
  *
- * - Use only letters, digits and `-`: `/[a-zA-Z0-9-]+/`
+ * - 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]/`
  *
+ * If a semi boxed expression
+ *
  */
-export type IdTable = {
-    [id: string]: SymbolDefinition | FunctionDefinition;
-};
+export type IdentifierDefinition = SymbolDefinition | FunctionDefinition | SemiBoxedExpression;
+export type IdentifierDefinitions = Readonly<{
+    [id: string]: IdentifierDefinition;
+}>;
 /**
- * The entries of a `RuntimeIdentifierTable` have been validated and
- * optimized for faster evaluation.
+ * 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 `RuntimeIdentifierTable` are created
- * as needed.
+ * engine instance, new instances of this type are created as needed.
  */
-export type RuntimeIdentifierTable = Map<string, BoxedSymbolDefinition | BoxedFunctionDefinition>;
+export type RuntimeIdentifierDefinitions = Map<string, BoxedSymbolDefinition | BoxedFunctionDefinition>;
 /**
  * A scope is a set of names in a dictionary that are bound (defined) in
  * a MathJSON expression.
@@ -1064,13 +1039,15 @@ export type RuntimeIdentifierTable = Map<string, BoxedSymbolDefinition | BoxedFu
  */
 export type Scope = {
     /** Signal `timeout` when the execution time for this scope is exceeded.
+     *
      * Time in seconds, default 2s.
      *
      * @experimental
      */
     timeLimit: number;
     /** Signal `out-of-memory` when the memory usage for this scope is exceeded.
-     * Memory in Megabytes, default: 1Mb.
+     *
+     * Memory is in Megabytes, default: 1Mb.
      *
      * @experimental
      */
@@ -1081,8 +1058,8 @@ export type Scope = {
      * @experimental
      */
     recursionLimit: number;
-    /** Signal `iteration-limit-exceeded` when the iteration limit for this
-     * scope is exceeded. Default: no limits.
+    /** Signal `iteration-limit-exceeded` when the iteration limit
+     * in a loop is exceeded. Default: no limits.
      *
      * @experimental
      */
@@ -1090,16 +1067,8 @@ export type Scope = {
 };
 export type RuntimeScope = Scope & {
     parentScope?: RuntimeScope;
-    idTable?: RuntimeIdentifierTable;
+    ids?: RuntimeIdentifierDefinitions;
     assumptions: undefined | ExpressionMapInterface<boolean>;
-    /** The location of the call site that created this scope */
-    origin?: {
-        name?: string;
-        line?: number;
-        column?: number;
-    };
-    /** Free memory should not go below this level for execution to proceed */
-    lowWaterMark?: number;
 };
 export type BaseDefinition = {
     /** A short (about 1 line) description. May contain Markdown. */
@@ -1229,7 +1198,7 @@ export type FunctionSignature = {
     /** An optional handler to determine the codomain of the function.
      * If not provided, the codomain of the function is determined from `domain`
      */
-    codomain?: (ce: IComputeEngine, args: BoxedDomain[]) => BoxedDomain | null;
+    codomain?: (ce: IComputeEngine, args: BoxedDomain[]) => BoxedDomain | null | undefined;
     /**
      * Return the canonical form of the expression with the arguments `args`.
      *
@@ -1237,11 +1206,14 @@ export type FunctionSignature = {
      * can be put in canonical form.
      *
      * This handler should validate the domain and number of the arguments.
+     *
      * If a required argument is missing, it should be indicated with a
      * `["Error", "'missing"]` expression. If more arguments than expected
-     * are present, this should be indicated with a `unexpected-argument` error.
-     * If the domain of an argument is not compatible, it should be indicated with
-     * a `incompatible-domain` error.
+     * are present, this should be indicated with an
+     * ["Error", "'unexpected-argument'"]` error expression
+     *
+     * If the domain of an argument is not compatible, it should be indicated
+     * with an `incompatible-domain` error.
      *
      * `["Sequence"]` expressions are not folded and need to be handled
      *  explicitly.
@@ -1251,10 +1223,11 @@ export type FunctionSignature = {
      * arguments should be sorted in canonical order.
      *
      * The handler can make transformations based on the value of the arguments
-     * that are exact and literal
-     * (i.e. `arg.numericValue !== null && arg.isExact`).
+     * that are exact and literal (i.e.
+     * `arg.numericValue !== null && arg.isExact`).
      *
-     * Values of symbols should not be substituted.
+     * 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`,
@@ -1284,6 +1257,9 @@ export type FunctionSignature = {
      * as calculations involving decimal numbers (non-integers). Making exact
      * calculations on integers or rationals is OK.
      *
+     * Do not reduce constants with a `holdUntil` attribute of `"N"`
+     * or `"evaluate"`.
+     *
      * This handler should not have any side-effects: do not modify
      * the environment of the `ComputeEngine` instance, do not perform I/O,
      * do not do calculations that depend on random values.
@@ -1294,10 +1270,10 @@ export type FunctionSignature = {
      */
     simplify?: (ce: IComputeEngine, args: BoxedExpression[]) => BoxedExpression | undefined;
     /**
-     * Evaluate symbolically a function expression.
+     * Evaluate a function expression.
      *
-     * The arguments have been symbolically evaluated, except the arguments to
-     * which a `hold` apply.
+     * The arguments have been evaluated, except the arguments to which a
+     * `hold` applied.
      *
      * It is not necessary to further simplify or evaluate the arguments.
      *
@@ -1310,7 +1286,7 @@ export type FunctionSignature = {
      * - do not reduce rational numbers to decimal (floating point approximation)
      * - do not down convert bignums to machine numbers
      * - do not reduce square roots of rational numbers
-     * - do not reduce constants with a `hold` attribute
+     * - do not reduce constants with a `holdUntil` attribute of `"N"`
      *
      * If the expression cannot be evaluated, due to the values, domains, or
      * assumptions about its arguments, for example, return `undefined` or
@@ -1337,19 +1313,19 @@ export type FunctionSignature = {
      * evaluation, but a literal argument is out of range or
      * not of the expected type.
      *
+     * Use the value of `ce.numericMode` to determine how to perform
+     * the numeric evaluation.
+     *
      * Note that regardless of the current value of `ce.numericMode`, the
      * arguments may be boxed numbers representing machine numbers, bignum
      * numbers, complex numbers, rationals or big rationals.
      *
-     * Use the value of `ce.numericMode` to determine how to perform
-     * the numeric evaluation.
-     *
      * If the numeric mode does not allow complex numbers (the
      * `engine.numericMode` is not `"complex"` or `"auto"`) and the result of
      * the evaluation would be a complex number, return `NaN` instead.
      *
-     * If `ce.numericMode` is `"bignum"` or `"auto"` the evaluation should be done
-     * using bignums.
+     * If `ce.numericMode` is `"bignum"` or `"auto"` the evaluation should
+     * be done using bignums.
      *
      * Otherwise, `ce.numericMode` is `"machine", the evaluation should be
      * performed using machine numbers.
@@ -1370,20 +1346,71 @@ export type FunctionSignature = {
 };
 export type BoxedFunctionSignature = {
     domain: BoxedDomain;
-    codomain?: BoxedDomain | ((ce: IComputeEngine, args: BoxedExpression[]) => BoxedDomain | null);
+    codomain?: BoxedDomain | ((ce: IComputeEngine, args: BoxedExpression[]) => BoxedDomain | null | undefined);
     canonical?: (ce: IComputeEngine, args: BoxedExpression[]) => BoxedExpression | null;
     simplify?: (ce: IComputeEngine, args: BoxedExpression[]) => BoxedExpression | undefined;
-    evaluate?: BoxedExpression | ((ce: IComputeEngine, args: BoxedExpression[]) => BoxedExpression | undefined);
+    evaluate?: (ce: IComputeEngine, args: BoxedExpression[]) => BoxedExpression | undefined;
     N?: (ce: IComputeEngine, args: BoxedExpression[]) => BoxedExpression | undefined;
     evalDimension?: (ce: IComputeEngine, args: BoxedExpression[]) => BoxedExpression;
     sgn?: (ce: IComputeEngine, args: BoxedExpression[]) => -1 | 0 | 1 | undefined;
     compile?: (expr: BoxedExpression) => CompiledExpression;
 };
+/**
+ * The 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.
+ *
+ */
+export type CollectionHandlers = {
+    /** 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.
+     */
+    iterator: (expr: 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 <0, return the element at index `size() + index + 1`.
+     * The index can also be a string for example for dictionaries.
+     * If the index is invalid, return `undefined`.
+     */
+    at: (expr: BoxedExpression, index: number | string) => undefined | BoxedExpression;
+    /** Return the number of elements in the collection.
+     * An empty collection has a size of 0.
+     */
+    size: (expr: BoxedExpression) => number;
+    /**
+     * If the collection is indexed by strings, return the valid values
+     * for the index.
+     */
+    keys: (expr: BoxedExpression) => undefined | Iterator<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.
+     * If the expression is found multiple times, 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: (expr: BoxedExpression, target: BoxedExpression, from?: number) => number | string | undefined;
+};
 /**
  * Definition record for a function.
  *
  */
-export type FunctionDefinition = BaseDefinition & Partial<FunctionDefinitionFlags> & {
+export type FunctionDefinition = BaseDefinition & Partial<CollectionHandlers> & Partial<FunctionDefinitionFlags> & {
     /**
      * A number used to order arguments.
      *
@@ -1415,12 +1442,12 @@ export type FunctionDefinition = BaseDefinition & Partial<FunctionDefinitionFlag
      *
      * **Default**: `"none"`
      */
-    hold?: 'none' | 'all' | 'first' | 'rest' | 'last' | 'most';
-    signature?: FunctionSignature;
+    hold?: Hold;
+    signature: FunctionSignature;
 };
-export type BoxedFunctionDefinition = BoxedBaseDefinition & FunctionDefinitionFlags & {
+export type BoxedFunctionDefinition = BoxedBaseDefinition & Partial<CollectionHandlers> & FunctionDefinitionFlags & {
     complexity: number;
-    hold: 'none' | 'all' | 'first' | 'rest' | 'last' | 'most';
+    hold: Hold;
     signature: BoxedFunctionSignature;
 };
 /**
@@ -1432,7 +1459,7 @@ export type BoxedFunctionDefinition = BoxedBaseDefinition & FunctionDefinitionFl
  * For example, it might be useful to override `algebraic = false`
  * for a transcendental number.
  */
-export type SymbolFlags = {
+export type NumericFlags = {
     number: boolean | undefined;
     integer: boolean | undefined;
     rational: boolean | undefined;
@@ -1495,21 +1522,26 @@ export type SymbolAttributes = {
 };
 /**
  * A bound symbol (i.e. one with an associated definition) has either a domain
- * (e.g. ∀ x ∈ ℝ), a value (x = 5) or both (π: value = 3.14... domain = TranscendentalNumber)
+ * (e.g. ∀ x ∈ ℝ), a value (x = 5) or both (π: value = 3.14... domain = TranscendentalNumbers)
  */
 export type SymbolDefinition = BaseDefinition & Partial<SymbolAttributes> & {
-    domain?: string | BoxedDomain;
-    /** `value` can be a function since for some constants, such as
+    domain?: DomainLiteral | BoxedDomain;
+    /** If true, the domain 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` */
+     * `ComputeEngine` and possible other environment settings */
     value?: LatexString | SemiBoxedExpression | ((ce: IComputeEngine) => SemiBoxedExpression | null);
-    flags?: Partial<SymbolFlags>;
+    flags?: Partial<NumericFlags>;
 };
-export interface BoxedSymbolDefinition extends BoxedBaseDefinition, SymbolAttributes, Partial<SymbolFlags> {
+export interface BoxedSymbolDefinition extends BoxedBaseDefinition, SymbolAttributes, Partial<NumericFlags> {
     get value(): BoxedExpression | undefined;
     set value(val: SemiBoxedExpression | number | undefined);
     domain: BoxedDomain | undefined;
-    at?: (index: string | number) => undefined | BoxedExpression;
+    inferredDomain: boolean;
 }
 export type AssumeResult = 'internal-error' | 'not-a-predicate' | 'contradiction' | 'tautology' | 'ok';
 export type CompiledExpression = {
@@ -1522,27 +1554,29 @@ export interface ComputeEngineStats {
     expressions: null | Set<BoxedExpression>;
     highwaterMark: number;
 }
+export type AssignValue = boolean | number | string | Decimal | Complex | LatexString | SemiBoxedExpression | ((ce: any, args: any) => BoxedExpression) | undefined;
 /** @internal */
 export interface IComputeEngine {
     latexDictionary: readonly LatexDictionaryEntry[];
-    /** @internal */
-    readonly _ZERO: BoxedExpression;
-    /** @internal */
-    readonly _ONE: BoxedExpression;
-    /** @internal */
-    readonly _HALF: BoxedExpression;
-    /** @internal */
-    readonly _NEGATIVE_ONE: BoxedExpression;
-    /** @internal */
-    readonly _I: BoxedExpression;
-    /** @internal */
-    readonly _NAN: BoxedExpression;
-    /** @internal */
-    readonly _POSITIVE_INFINITY: BoxedExpression;
-    /** @internal */
-    readonly _NEGATIVE_INFINITY: BoxedExpression;
-    /** @internal */
-    readonly _COMPLEX_INFINITY: BoxedExpression;
+    readonly Anything: BoxedDomain;
+    readonly Void: BoxedDomain;
+    readonly Strings: BoxedDomain;
+    readonly Booleans: BoxedDomain;
+    readonly Numbers: BoxedDomain;
+    readonly True: BoxedExpression;
+    readonly False: BoxedExpression;
+    readonly Pi: BoxedExpression;
+    readonly E: BoxedExpression;
+    readonly Nothing: BoxedExpression;
+    readonly Zero: BoxedExpression;
+    readonly One: BoxedExpression;
+    readonly Half: BoxedExpression;
+    readonly NegativeOne: BoxedExpression;
+    readonly I: BoxedExpression;
+    readonly NaN: BoxedExpression;
+    readonly PositiveInfinity: BoxedExpression;
+    readonly NegativeInfinity: BoxedExpression;
+    readonly ComplexInfinity: BoxedExpression;
     /** @internal */
     readonly _BIGNUM_NAN: Decimal;
     /** @internal */
@@ -1569,7 +1603,6 @@ export interface IComputeEngine {
     readonly iterationLimit: number;
     /** @experimental */
     readonly recursionLimit: number;
-    defaultDomain: null | BoxedDomain;
     /** {@inheritDoc  NumericMode} */
     numericMode: NumericMode;
     tolerance: number;
@@ -1691,12 +1724,21 @@ export interface IComputeEngine {
      * Associate a new definition to a symbol in the current context.
      *
      * If a definition existed previously, it is replaced.
+     *
+     *
+     * For internal use. Use `ce.declare()` instead.
+     *
+     * @internal
      */
     defineSymbol(name: string, def: SymbolDefinition): BoxedSymbolDefinition;
     /**
      * Associate a new definition to a function in the current context.
      *
      * If a definition existed previously, it is replaced.
+     *
+     * For internal use. Use `ce.declare()` instead.
+     *
+     * @internal
      */
     defineFunction(name: string, def: FunctionDefinition): BoxedFunctionDefinition;
     lookupSymbol(name: string, wikidata?: string, scope?: RuntimeScope): undefined | BoxedSymbolDefinition;
@@ -1726,7 +1768,7 @@ export interface IComputeEngine {
      * If the domain is invalid, may return an `["Error"]` expression
      *
      */
-    domain(domain: SemiBoxedExpression | BoxedDomain | string, metadata?: Metadata): BoxedDomain;
+    domain(domain: BoxedDomain | DomainExpression, metadata?: Metadata): BoxedDomain;
     /**
      * Return a canonical expression.
      *
@@ -1756,6 +1798,7 @@ export interface IComputeEngine {
      * The result is canonical.
      */
     error(message: string | [string, ...SemiBoxedExpression[]], where?: SemiBoxedExpression): BoxedExpression;
+    domainError(expectedDomain: BoxedDomain | DomainLiteral, actualDomain: undefined | BoxedDomain, where?: SemiBoxedExpression): BoxedExpression;
     /**
      * Add a`["Hold"]` wrapper to `expr.
      */
@@ -1775,6 +1818,10 @@ export interface IComputeEngine {
      * The result is canonical.
      */
     pow(base: BoxedExpression, exponent: number | Rational | BoxedExpression, metadata?: Metadata): BoxedExpression;
+    /** Shortcut for `this.fn("Sqrt"...)`
+     *
+     * The result is canonical.
+     */
     sqrt(base: BoxedExpression, metadata?: Metadata): any;
     /** Shortcut for `this.fn("Divide", [1, expr])`
      *
@@ -1821,7 +1868,9 @@ export interface IComputeEngine {
     /** Serialize a `BoxedExpression` or a `MathJSON` expression to
      * a LaTeX string
      */
-    serialize(expr: SemiBoxedExpression): LatexString;
+    serialize(expr: SemiBoxedExpression, options?: {
+        canonical?: boolean;
+    }): LatexString;
     /**
      * Options to control the serialization of MathJSON expression to LaTeX
      * when using `this.latex` or `this.engine.serialize()`.
@@ -1837,14 +1886,59 @@ export interface IComputeEngine {
     /** {@inheritDoc  JsonSerializationOptions} */
     get jsonSerializationOptions(): Readonly<JsonSerializationOptions>;
     set jsonSerializationOptions(val: Partial<JsonSerializationOptions>);
-    pushScope(identifiers?: Readonly<IdTable> | Readonly<IdTable>[], scope?: Partial<Scope>): void;
-    popScope(): void;
-    /** Assign a value to an identifier in the current scope. Use `null` to reset the identifier to no value */
-    set(ids: {
-        [id: string]: SemiBoxedExpression | null | undefined;
-    }): void;
-    /** Declare identifiers (specify their domain without necessarily assigning them a value in the current scope) */
-    let(identifiers: IdTable): void;
+    /** Create a new scope on top of the scope stack, and set it as current */
+    pushScope(scope?: Partial<Scope>): IComputeEngine;
+    /** Remove the most recent scope from the scope stack, and set its
+     *  parent scope as current. */
+    popScope(): IComputeEngine;
+    /** Set the current scope, return the previous scope. */
+    swapScope(scope: RuntimeScope | null): RuntimeScope | null;
+    /**
+     * Reset the value of any identifiers that have been assigned a value
+     * in the current scope.
+     * @internal */
+    resetContext(): void;
+    /** Assign a value to an identifier in the current scope.
+     * Use `undefined` to reset the identifier to no value.
+     *
+     * The identifier should be a valid MathJSON identifier
+     * not a LaTeX string.
+     *
+     * The identifier can take the form "f(x, y") to create a function
+     * with two parameters, "x" and "y".
+     *
+     * If the id was not previously declared, an automatic declaration
+     * is done. The domain of the identifier is inferred from the value.
+     * To more precisely define the domain of the identifier, use `ce.declare()`
+     * instead, which allows you to specify the domain, value and other
+     * attributes of the identifier.
+     */
+    assign(ids: {
+        [id: string]: AssignValue;
+    }): IComputeEngine;
+    assign(id: string, value: AssignValue): IComputeEngine;
+    assign(arg1: string | {
+        [id: string]: AssignValue;
+    }, arg2?: AssignValue): IComputeEngine;
+    /**
+     * Declare an identifier: specify their domain, and other attributes,
+     * including optionally a value.
+     *
+     * Once the domain of an identifier has been declared, it cannot be changed.
+     * The domain information is used to calculate the canonical form of
+     * expressions and ensure they are valid. If the domain could be changed
+     * after the fact, previously valid expressions could become invalid.
+     *
+     * Use the `Anyting` domain for a very generic domain.
+     *
+     */
+    declare(identifiers: {
+        [id: string]: BoxedDomain | DomainExpression | SymbolDefinition | FunctionDefinition;
+    }): IComputeEngine;
+    declare(id: string, def: BoxedDomain | DomainExpression | SymbolDefinition | FunctionDefinition): IComputeEngine;
+    declare(arg1: string | {
+        [id: string]: BoxedDomain | DomainExpression | SymbolDefinition | FunctionDefinition;
+    }, arg2?: BoxedDomain | DomainExpression | SymbolDefinition | FunctionDefinition): IComputeEngine;
     /**
      * Add an assumption.
      *
@@ -1860,13 +1954,11 @@ export interface IComputeEngine {
      *
      *
      */
-    assume(symbol: LatexString | SemiBoxedExpression, domain: BoxedDomain): AssumeResult;
-    assume(predicate: LatexString | SemiBoxedExpression): AssumeResult;
-    assume(arg1: LatexString | SemiBoxedExpression, arg2?: BoxedExpression): AssumeResult;
+    assume(predicate: SemiBoxedExpression): AssumeResult;
     /** Remove all assumptions about one or more symbols */
     forget(symbol?: string | string[]): void;
     get assumptions(): ExpressionMapInterface<boolean>;
-    ask(pattern: LatexString | SemiBoxedExpression): BoxedSubstitution[];
+    ask(pattern: SemiBoxedExpression): BoxedSubstitution[];
     /** @internal */
     shouldContinueExecution(): boolean;
     /** @internal */