@cortex-js/compute-engine 0.4.3 → 0.6.0

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

@@ -1,12 +1,20 @@
-/* 0.4.3 */
+/* 0.6.0 */
+ * The most important classes are {@link ComputeEngine} and
+ * {@link BoxedExpression}.
+ *
+ * With `ComputeEngine` you create `BoxedExpression` objects. With
+ * `BoxedExpression` you simplify, evaluate and serialize expressions.
+ *
+ * @module ComputeEngine
+ */
+import type { Decimal } from 'decimal.js';
 import type { Complex } from 'complex.js';
-import { SignalMessage, WarningSignal, WarningSignalHandler } from '../common/signals';
-import { Expression, MathJsonDictionary, MathJsonFunction, MathJsonNumber, MathJsonString, MathJsonSymbol } from '../math-json/math-json-format';
-import { NumberFormattingOptions, ParseLatexOptions, SerializeLatexOptions } from '../math-json';
-export declare const DEFAULT_COMPLEXITY = 100000;
-export declare const DEBUG = true;
+import type { SignalMessage, WarningSignal, WarningSignalHandler } from '../common/signals';
+import type { Expression, MathJsonDictionary, MathJsonFunction, MathJsonNumber, MathJsonString, MathJsonSymbol } from '../math-json/math-json-format';
+import type { NumberFormattingOptions, ParseLatexOptions, SerializeLatexOptions } from './latex-syntax/public';
+export * from './latex-syntax/public';
 /**
- * Metadata that can be associated with a BoxedExpression
+ * Metadata that can be associated with a `BoxedExpression`
  */
 export declare type Metadata = {
     latex?: string;
@@ -15,32 +23,45 @@ export declare type Metadata = {
 /**
  * The numeric evaluation mode:
  *
- * - `machine`: 64-bit float, **IEEE 754-2008**, 52-bit, about 15 digits of precision
- * - `decimal`: arbitrary precision floating point numbers
- * - `complex`: complex number represented by two machine numbers, a real and
- * an imaginary part
  * - `auto`: use machine number if precision is 15 or less, allow complex numbers.
+ * - `machine`: 64-bit float, **IEEE 754-2008**, 64-bit float, 52-bit mantissa,
+ *    about 15 digits of precision
+ * - `decimal`: arbitrary precision floating point numbers, as provided by the
+ * "decimal.js" library
+ * - `complex`: complex number represented by two machine numbers, a real and
+ * an imaginary part, as provided by the "complex.js" library
  */
 export declare type NumericMode = 'auto' | 'machine' | 'decimal' | 'complex';
-/** Options for `expr.simplify()` */
+/** Options for `BoxedExpression.simplify()`
+ *
+ */
 export declare type SimplifyOptions = EvaluateOptions & {
     recursive?: boolean;
     rules?: BoxedRuleSet;
 };
-/** Options for `expr.evaluate()` */
+/** Options for `BoxedExpression.evaluate()`
+ *
+ * @internal
+ */
 export declare type EvaluateOptions = {};
-/** Options for `expr.N()` */
+/** Options for `BoxedExpression.N()`
+ * @internal
+ */
 export declare type NOptions = {};
 export declare type ReplaceOptions = {
     /** If true, apply replacement rules to all sub-expressions.
      * If false, only consider the top-level expression.
      *
-     * **Default**: true*/
+     * **Default**: `true`
+     */
     recursive?: boolean;
-    /** If true, stop after the first rule that matches.
+    /**
+     * If true, stop after the first rule that matches.
+     *
      * If false, apply all the remaining rules even after the first match.
      *
-     * **Default**: true*/
+     * **Default**: `true`
+     */
     once?: boolean;
     /**
      * If `iterationLimit` > 1, the rules will be repeatedly applied
@@ -48,7 +69,7 @@ export declare type ReplaceOptions = {
      *
      * Note that if `once` is true, `maxIterations` has no effect.
      *
-     * **Default**: 1
+     * **Default**: `1`
      */
     iterationLimit?: number;
 };
@@ -70,8 +91,8 @@ export declare type LatexString = string;
  *  A rule describes how to modify an expressions that matches a `lhs` pattern
  * into a new expressions matching `rhs`.
  *
- * `x-1` -> `1-x`
- * `(x+1)(x-1)` -> `x^2-1
+ * `x-1` \( \to \) `1-x`
+ * `(x+1)(x-1)` \( \to \) `x^2-1
  *
  * The `lhs` can be expressed as a LaTeX string or a MathJSON expression.
  *
@@ -101,13 +122,62 @@ export declare type BoxedRule = [
     condition: undefined | ((wildcards: Substitution) => boolean)
 ];
 export declare type BoxedRuleSet = Set<BoxedRule>;
+export declare type ParametricDomainFunction = 'Function' | 'Union' | 'List' | 'Record' | 'Tuple' | 'Intersection' | 'Range' | 'Interval' | 'Optional' | 'Some' | 'Head' | 'Symbol' | 'Literal';
+export declare type ParametricDomain = [
+    ParametricDomainFunction,
+    ...DomainExpression[]
+];
+export declare type DomainExpression = string | ParametricDomain;
 /**
  * Domains can be defined as a union or intersection of domains:
  * - `["Union", "Number", "Boolean"]` A number or a boolean.
  * - `["SetMinus", "Number", 1]`  Any number except "1".
  *
  */
-export declare type DomainExpression = BoxedExpression;
+export interface Domain extends BoxedExpression {
+    isSubdomainOf(dom: Domain | string): boolean;
+    isMemberOf(expr: BoxedExpression): boolean;
+    readonly domainExpression: DomainExpression;
+    codomain: Domain | null;
+    readonly isNothing: boolean;
+    is(s: BoxedExpression): boolean;
+    readonly isBoolean: boolean;
+    readonly isNumeric: boolean;
+    readonly isFunction: boolean;
+    readonly isPredicate: 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
+     */
+    readonly isNumericFunction: boolean;
+    readonly isRealFunction: boolean;
+    /**
+     * 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
+     */
+    readonly isLogicOperator: boolean;
+    /**
+     * 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`.
+ */
 export declare type JsonSerializationOptions = {
     /** A list of space separated function names that should be excluded from
      * the JSON output.
@@ -131,13 +201,13 @@ export declare type JsonSerializationOptions = {
      * included in the MathJSON. If metadata is included, shorthand notation
      * is not used.
      *
-     * **Default**: `[]`
+     * **Default**: `[]`  (none)
      */
     metadata: ('all' | 'wikidata' | 'latex')[];
     /** If true, repeating decimals are detected and serialized accordingly
      * For example:
-     * - `1.3333333333333333` -> `1.(3)`
-     * - `0.142857142857142857142857142857142857142857142857142` -> `0.(1428571)`
+     * - `1.3333333333333333` \( \to \) `1.(3)`
+     * - `0.142857142857142857142857142857142857142857142857142` \( \to \) `0.(1428571)`
      *
      * **Default**: `true`
      */
@@ -146,12 +216,12 @@ export declare type JsonSerializationOptions = {
 /**
  * **Theory of Operations**
  *
- * The `BoxedExpression` interface includes most of the methods applicable
- * to any kind of expression, for example `get string()` or
- * `get machineValue()`.
+ * The `BoxedExpression` interface includes most of the member functions
+ * applicable to any kind of expression, for example `get symbol()` or
+ * `get ops()`.
  *
- * When they are not applicable, for example `get string()` on a
- * `BoxedNumber`, they return `null`.
+ * 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.
@@ -163,19 +233,43 @@ export interface BoxedExpression {
      * and functions.
      */
     readonly engine: IComputeEngine;
-    /** From Object.valueOf() */
+    /** From `Object.valueOf()`, return a primitive value for the expression.
+     *
+     * If the expression is a machine number, or a Decimal that can be
+     * converted to a machine number, return a `number`.
+     *
+     * If the expression is a rational number, return `[number, number]`.
+     *
+     * If the expression is a symbol, return the name of the symbol as a `string`.
+     *
+     * Otherwise return a LaTeX representation of the expression.
+     *
+     * @category Object Methods
+     */
     valueOf(): number | string | [number, number];
-    /** From Object.toString() */
+    /** From `Object.toString()`, return a LaTeX representation of the expression.
+     *
+     * @category Object Methods
+     */
     toString(): string;
-    /** From Object.toJSON(), equivalent to `JSON.stringify(this.json)` */
+    /** From `Object.toJSON()`, equivalent to `JSON.stringify(this.json)`
+     *
+     * @category Object Methods
+     */
     toJSON(): string;
-    /** From Object.is(). Equivalent to `isSame()` */
-    is(rhs: any): boolean;
+    /** From `Object.is()`. Equivalent to `BoxedExpression.isSame()`
+     *
+     * @category Object Methods
+     *
+     */
+    is(rhs: unknown): boolean;
+    /** @internal */
     get hash(): number;
-    /** A short description of the symbol or function head. May include markdown.
-     * Each string is a paragraph. */
+    /** An optional short description of the symbol or function head.
+     *
+     * May include markdown. Each string is a paragraph. */
     readonly description: string[];
-    /** A URL pointing to more information about the symbol or function head */
+    /** An optional URL pointing to more information about the symbol or function head */
     readonly url: string;
     /** All boxed expressions have a head.
      *
@@ -186,16 +280,16 @@ export interface BoxedExpression {
      */
     get head(): BoxedExpression | string;
     /**
-     * If `expr.isPure` is `true`, this is a synonym for `expr.evaluate()`.
+     * If `this.isPure` is `true`, this is a synonym for `this.evaluate()`.
      * Otherwise, it returns `undefined`.
      */
     get value(): BoxedExpression | undefined;
     /** Only the value of variables can be changed (symbols that are not constants) */
-    set value(value: BoxedExpression | undefined);
+    set value(value: BoxedExpression | number | undefined);
     /** Return an approximation of the value of this expression. Floating-point
      * operations may be performed.
      *
-     * Just like `expr.value`, it returns `undefined` for impure expressions.
+     * Just like `this.value`, it returns `undefined` for impure expressions.
      */
     get numericValue(): BoxedExpression | undefined;
     /** If true, the value of the expression never changes and evaluating it has
@@ -203,8 +297,8 @@ export interface BoxedExpression {
      * If false, the value of the expression may change, if the
      * value of other expression changes or for other reasons.
      *
-     * If `expr.isPure` is `false`, `expr.value` is undefined. Call
-     * `expr.evaluate()` to determine the value of the expression instead.
+     * If `this.isPure` is `false`, `this.value` is undefined. Call
+     * `this.evaluate()` to determine the value of the expression instead.
      *
      * As an example, the `Random` function is not pure.
      */
@@ -218,25 +312,76 @@ export interface BoxedExpression {
     get isLiteral(): boolean;
     /** If `true`, this expression is in a canonical form */
     get isCanonical(): boolean;
-    /** For internal use only, set when a canonical expression is created. */
+    /** For internal use only, set when a canonical expression is created.
+     * @internal
+     */
     set isCanonical(val: boolean);
-    /** `ops` is the list of arguments of the function, its "tail" */
+    /** `ops` is the list of arguments of the function, its "tail"
+     *
+     * @category Function Expression
+     *
+     */
     get ops(): null | BoxedExpression[];
-    /** If a function, the number of operands, otherwise 0.
+    /** If this expression is a function, the number of operands, otherwise 0.
      *
      * Note that a function can have 0 operands, so to check if this expression
-     * is a function, check if `expr.tail !== null` instead. */
+     * is a function, check if `this.ops !== null` instead.
+     *
+     * @category Function Expression
+     *
+     */
     get nops(): number;
-    /** First operand, i.e. first element of `this.tail` */
+    /** First operand, i.e.`this.ops[0]`
+     *
+     *
+     * @category Function Expression
+     *
+     *
+     */
     get op1(): BoxedExpression;
-    /** Second operand, i.e. second element of `this.tail` */
+    /** Second operand, i.e.`this.ops[0]`
+     *
+     *
+     * @category Function Expression
+     *
+     *
+     */
     get op2(): BoxedExpression;
-    /** Third operand, i.e. third element of `this.tail` */
+    /** Third operand, i.e. `this.ops[2]`
+     *
+     *
+     * @category Function Expression
+     *
+     *
+     */
     get op3(): BoxedExpression;
-    /** The keys of the dictionary. If this expression not a dictionary, return `null` */
+    /** The keys of the dictionary.
+     *
+     * If this expression not a dictionary, return `null`
+     *
+     * @category Dictionary Expression
+     *
+     */
     get keys(): IterableIterator<string> | null;
+    /**
+     *
+     * @category Dictionary Expression
+     */
     get keysCount(): number;
+    /**
+     * If this expression is a dictionary, return the value of the `key` entry.
+     *
+     * @category Dictionary Expression
+     *
+     */
     getKey(key: string): BoxedExpression | undefined;
+    /**
+     * If this expression is a dictionary, return true if the dictionary has a
+     * `key` entry.
+     *
+     * @category Dictionary Expression
+     *
+     */
     hasKey(key: string): boolean;
     /**
      * Return the value of this number or symbol, if stored as a machine number.
@@ -247,6 +392,8 @@ export interface BoxedExpression {
      * If `machineValue` is not `null`, then `decimalValue`, `rationalValue`
      * and `complexValue` are `null.
      *
+     * @category Numeric Expression
+     *
      */
     get machineValue(): number | null;
     /** If the value of this expression is a rational number, return it.
@@ -254,6 +401,9 @@ export interface BoxedExpression {
      *
      * If `rationalValue` is not `[null, null]`, then `machineValue`, `decimalValue`
      * and `complexValue` are `null.
+     *
+     * @category Numeric Expression
+     *
      */
     get rationalValue(): [numer: number, denom: number] | [null, null];
     /** If the value of this expression is a `Decimal` number, return it.
@@ -263,6 +413,9 @@ export interface BoxedExpression {
      *
      * If `decimalValue` is not `null`, then `machineValue`
      * and `complexValue` are `null` and `rationalValue` is `[null, null]`.
+     *
+     * @category Numeric Expression
+     *
      */
     get decimalValue(): Decimal | null;
     /** If the value of this expression is a `Complex` number, return it.
@@ -271,6 +424,9 @@ export interface BoxedExpression {
      * If `complexValue` is not `null`, then `machineValue`, `rationalValue`
      * and `decimalValue` are `null.
      *
+     * @category Numeric Expression
+     *
+     *
      */
     get complexValue(): Complex | null;
     /** Return an approximation of the numeric value of this expression as
@@ -289,6 +445,9 @@ export interface BoxedExpression {
      * If the value of this expression cannot be represented by a float,
      * return `null`.
      *
+     * @category Numeric Expression
+     *
+     *
      */
     get asFloat(): number | null;
     /**
@@ -300,57 +459,85 @@ export interface BoxedExpression {
      * to check for this, whether the value is a Decimal or a number.
      *
      * By default, "small" is less than 10,000.
+     *
+     * @category Numeric Expression
+     *
      */
     get asSmallInteger(): number | null;
     /**
      * If the value of this an expression is a small integer or a rational,
      * return this value. Otherwise, return `[null, null`].
+     *
+     * @category Numeric Expression
+     *
      */
     get asRational(): [number, number] | [null, null];
     /**
      * Return the following, depending on the value of this expression:
      *
-     * * `-1`: if it is < 0
-     * * `0`: if it is = 0
-     * * `+1`: if it is > 0
-     * * `undefined`: this value may be positive, negative or zero. We don't know
+     * * `-1` if it is < 0
+     * * `0` if it is = 0
+     * * `+1` if it is > 0
+     * * `undefined` this value may be positive, negative or zero. We don't know
      *    right now (a symbol with an Integer domain, but no currently assigned
      *    value, for example)
-     * * `null`: this value will never be positive, negative or zero (`NaN`,
+     * * `null` this value will never be positive, negative or zero (`NaN`,
      *     a string or a complex number for example)
      *
      * Note that complex numbers have no natural ordering,
      * so if the value is a complex number, `sgn` is either 0, or `null`
      *
-     * If a symbol, this does take assumptions into account, that is `expr.sgn` will return
+     * If a symbol, this does take assumptions into account, that is `this.sgn` will return
      * `1` if `isPositive` is `true`, even if this expression has no value
+     *
+     * @category Numeric Expression
+     *
      */
     get sgn(): -1 | 0 | 1 | undefined | null;
     /** If this expression is a symbol, return the name of the symbol as a string.
-     * Otherwise, return `null`. */
+     * Otherwise, return `null`.
+     *
+     * @category Symbol Expression
+     *
+     */
     get symbol(): string | null;
-    /**  Shortcut for `this.symbol === 'Missing'` */
+    /**  Shortcut for `this.symbol === "Missing"`
+     *
+     * @category Symbol Expression
+     *
+     */
     get isMissing(): boolean;
     /** If this expression is a string, return the value of the string.
      * Otherwise, return `null`.
+     *
+     * @category String Expression
+     *
      */
     get string(): string | null;
-    /** True if this domain is a subset of domain d */
-    isSubsetOf(d: BoxedExpression | string): undefined | boolean;
     /** True if the value of this expression is a number.
      *
      * `isExtendedComplex || isNaN` = `isReal || isImaginary || isInfinity || isNaN`
      *
      * Note that in a fateful twist of cosmic irony, `NaN` ("Not a Number")
      * is a number.
+     *
+     * @category Expression Properties
      */
     get isNumber(): boolean | undefined;
-    /** The value of this expression is an element of the set ℤ: ...,-2, -1, 0, 1, 2... */
+    /** The value of this expression is an element of the set ℤ: ...,-2, -1, 0, 1, 2...
+     *
+     *
+     * @category Expression Properties
+     *
+     */
     get isInteger(): boolean | undefined;
     /** The value of this expression is an element of the set ℚ, p/q with p ∈ ℕ, q ∈ ℤ ⃰  q >= 1
      *
      * Note that every integer is also a rational.
      *
+     *
+     * @category Expression Properties
+     *
      */
     get isRational(): boolean | undefined;
     /**
@@ -361,17 +548,26 @@ export interface BoxedExpression {
      *
      * Transcendental numbers, such as \\( \pi \\) or \\( e \\) are not algebraic.
      *
+     *
+     * @category Expression Properties
+     *
      */
     get isAlgebraic(): boolean | undefined;
     /**
      * The value of this expression is real number: finite and not imaginary.
      *
      * `isFinite && !isImaginary`
+     *
+     *
+     * @category Expression Properties
      */
     get isReal(): boolean | undefined;
     /** Real or ±Infinity
      *
      * `isReal || isInfinity`
+     *
+     *
+     * @category Expression Properties
      */
     get isExtendedReal(): boolean | undefined;
     /**
@@ -379,50 +575,100 @@ export interface BoxedExpression {
      *
      * `isReal || isImaginary`
      *
+     *
+     * @category Expression Properties
+     *
      */
     get isComplex(): boolean | undefined;
-    /** `isReal || isImaginary || isInfinity` */
+    /** `isReal || isImaginary || isInfinity`
+     *
+     *
+     * @category Expression Properties
+     */
     get isExtendedComplex(): boolean | undefined;
-    /** The value of this expression is a number with a imaginary part */
+    /** The value of this expression is a number with a imaginary part
+     *
+     *
+     * @category Expression Properties
+     */
     get isImaginary(): boolean | undefined;
+    /**
+     * @category Expression Properties
+     */
     get isZero(): boolean | undefined;
+    /**
+     * @category Expression Properties
+     */
     get isNotZero(): boolean | undefined;
+    /**
+     * @category Expression Properties
+     */
     get isOne(): boolean | undefined;
+    /**
+     * @category Expression Properties
+     */
     get isNegativeOne(): boolean | undefined;
-    /** ±Infinity or Complex Infinity */
+    /** ±Infinity or Complex Infinity
+     *
+     * @category Expression Properties
+     */
     get isInfinity(): boolean | undefined;
     /**
      * "Not a Number".
      *
      * A value representing undefined result of computations, such as `0/0`,
-     * as per the the floating point format standard IEEE-754.
+     * as per the floating point format standard IEEE-754.
+     *
+     * Note that if `isNaN` is true, `isNumber` is also true (yes, `NaN` is a
+     * number).
      *
-     * Note that if `isNaN` is true, `isNumber` is also true.
+     * @category Expression Properties
      *
      */
     get isNaN(): boolean | undefined;
-    /** Not ±Infinity and not NaN */
+    /** Not ±Infinity and not `NaN`
+     *
+     * @category Expression Properties
+     */
     get isFinite(): boolean | undefined;
+    /**
+     * @category Expression Properties
+     */
     get isEven(): boolean | undefined;
+    /**
+     * @category Expression Properties
+     */
     get isOdd(): boolean | undefined;
+    /**
+     * @category Expression Properties
+     */
     get isPrime(): boolean | undefined;
+    /**
+     * @category Expression Properties
+     */
     get isComposite(): boolean | undefined;
     /** Structural/symbolic equality (weak equality).
      *
-     * `ce.parse('1+x').isSame(ce.parse('x+1'))` is `true`
+     * `ce.parse('1+x').isSame(ce.parse('x+1'))` is `false`
      *
+     * @category Relational Operator
      */
     isSame(rhs: BoxedExpression): boolean;
     /**
-     * True if the expression includes a symbol `v`, or a function head `v`.
+     * True if the expression includes a symbol `v` or a function head `v`.
      */
     has(v: string | string[]): boolean;
-    /** Attempt to match this pattern to the `rhs`.
+    /** Attempt to match this expression to the `rhs` expression.
      *
      * If `rhs` does not match, return `null`.
-     * Otherwise return an object literal, with a prop for
-     * each matching named wildcard. If `rhs` matches
-     * this pattern but there are no named wildcards, return
+     *
+     * Otherwise return an object literal.
+     *
+     * If this expression includes wildcards (symbols with a name that starts
+     * with `_`), the object literal will include a prop for each matching named
+     * wildcard.
+     *
+     * If `rhs` matches this pattern but there are no named wildcards, return
      * the empty object literal, `{}`.
      */
     match(rhs: BoxedExpression, options?: PatternMatchOption): Substitution | null;
@@ -432,22 +678,48 @@ export interface BoxedExpression {
      * Both expressions are numerically evaluated.
      *
      * Numbers whose difference is less than `engine.tolerance` are
-     * considered equal. This value is set when the `engine.precision` is
+     * considered equal. This tolerance is set when the `engine.precision` is
      * changed to be such that the last two digits are ignored.
+     *
+     * @category Relational Operator
      */
     isEqual(rhs: BoxedExpression): boolean;
-    /** If the expressions cannot be compared, `undefined` is returned */
+    /** If the expressions cannot be compared, `undefined` is returned
+     *
+     * @category Relational Operator
+     */
     isLess(rhs: BoxedExpression): boolean | undefined;
+    /**
+     * @category Relational Operator
+     */
     isLessEqual(rhs: BoxedExpression): boolean | undefined;
+    /**
+     * @category Relational Operator
+     */
     isGreater(rhs: BoxedExpression): boolean | undefined;
+    /**
+     * @category Relational Operator
+     */
     isGreaterEqual(rhs: BoxedExpression): boolean | undefined;
-    /** The value of this expression is > 0, same as `isGreater(0)` */
+    /** The value of this expression is > 0, same as `isGreater(0)`
+     *
+     * @category Expression Properties
+     */
     get isPositive(): boolean | undefined;
-    /** The value of this expression is  >= 0, same as `isGreaterEqual(0)` */
+    /** The value of this expression is  >= 0, same as `isGreaterEqual(0)`
+     *
+     * @category Expression Properties
+     */
     get isNonNegative(): boolean | undefined;
-    /** The value of this expression is  < 0, same as `isLess(0)` */
+    /** The value of this expression is  < 0, same as `isLess(0)`
+     *
+     * @category Expression Properties
+     */
     get isNegative(): boolean | undefined;
-    /** The value of this expression is  <= 0, same as `isLessEqual(0)` */
+    /** The value of this expression is  <= 0, same as `isLessEqual(0)`
+     *
+     * @category Expression Properties
+     */
     get isNonPositive(): boolean | undefined;
     /** Wikidata identifier */
     get wikidata(): string;
@@ -461,11 +733,17 @@ export interface BoxedExpression {
      * first in commutative functions
      */
     get complexity(): number;
-    /** The domain of this expression, using the value of the expression,
-     * definitions associated with this expression and assumptions if necessary */
-    get domain(): BoxedExpression;
+    /** The domain of this expression. */
+    get domain(): Domain;
     /** Symbols that represent a variable, can have their domain modified */
-    set domain(domain: BoxedExpression | string);
+    set domain(domain: Domain | string);
+    /** The domain of the value of this expression, using the value of the expression,
+     * definitions associated with this expression and assumptions if necessary.
+     *
+     * For symbols, the `domain` and `valueDomain` are the same.  For functions,
+     * the `valueDomain` is the codomain of the function.
+     */
+    get valueDomain(): Domain;
     /** For symbols and functions, a possible definition associated with the expression */
     get functionDefinition(): BoxedFunctionDefinition | undefined;
     get symbolDefinition(): BoxedSymbolDefinition | undefined;
@@ -519,22 +797,22 @@ export interface BoxedExpression {
      * The expression is first converted to canonical form.
      *
      * A pure expression always return the same value and has no side effects.
-     * If `expr.isPure` is `true`, `expr.value` and `expr.evaluate()` are synonyms.
-     * For an impure expression, `expr.value` is undefined.
+     * If `this.isPure` is `true`, `this.value` and `this.evaluate()` are synonyms.
+     * For an impure expression, `this.value` is undefined.
      *
      * Evaluating an impure expression may have some side effects, for
      * example modifying the `ComputeEngine` environment, such as its set of assumptions.
      *
      * Only exact calculations are performed, no floating point calculations.
-     * To perform approximate floating point calculations, use `N()` instead.
+     * To perform approximate floating point calculations, use `this.N()` instead.
      *
-     * The result of `expr.evaluate()` may be the same as `expr.simplify()`.
+     * The result of `this.evaluate()` may be the same as `this.simplify()`.
      *
      * The result is in canonical form.
      *
      */
     evaluate(options?: EvaluateOptions): BoxedExpression;
-    /** Return a numerical approximation of this expression.
+    /** Return a numeric approximation of this expression.
      *
      * The expression is first converted to canonical form.
      *
@@ -542,7 +820,10 @@ export interface BoxedExpression {
      * are performed. The calculations are performed according
      * to the `numericMode` and `precision` properties of the `ComputeEngine`.
      *
-     * If the function is not numeric, this is equivalent to `expr.evaluate()`.
+     * To only perform exact calculations, use `this.evaluate()` instead.
+     *
+     * If the function is not numeric, the result of `this.N()` is the same as
+     * `this.evaluate()`.
      *
      * The result is in canonical form.
      */
@@ -564,13 +845,15 @@ export interface BoxedExpression {
      * the matching `lhs` of a rule is replaced by its `rhs`.
      *
      * If no rules apply, return `null`.
+     *
+     * See also `subs` for a simple substitution.
      */
     replace(rules: BoxedRuleSet, options?: ReplaceOptions): null | BoxedExpression;
     /**
      * Replace all the symbols in the expression as indicated.
      *
-     * Note the same effect can be achieved with `expr.replace()`, but
-     * this is more efficient, and simpler.
+     * Note the same effect can be achieved with `this.replace()`, but
+     * using `this.subs()` is more efficient, and simpler.
      *
      */
     subs(sub: Substitution): BoxedExpression;
@@ -578,10 +861,13 @@ export interface BoxedExpression {
      * Update the definition associated with this expression, taking
      * into account the current context.
      *
-     * For internal use only.
+     * @internal
      */
     _repairDefinition(): void;
-    /** Purge any cached values */
+    /** Purge any cached values.
+     *
+     * @internal
+     */
     _purge(): undefined;
 }
 /** A semi boxed expression is an MathJSON expression which can include some
@@ -601,6 +887,7 @@ export declare type PatternMatchOption = {
 export interface Pattern extends BoxedExpression {
     /**
      * If `expr` does not match the pattern, return `null`.
+     *
      * Otherwise, return a substitution describing the values that the named
      * wildcard in the pattern should be changed to in order for the pattern to be
      * equal to the expression. If there are no named wildcards and the expression
@@ -664,17 +951,27 @@ export declare type Scope = {
     warn?: WarningSignalHandler;
     /** 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.
+     *
+     * @experimental
      */
     memoryLimit?: number;
     /** Signal `recursion-depth-exceeded` when the recursion depth for this
-     * scope is exceeded. */
+     * scope is exceeded.
+     *
+     * @experimental
+     */
     recursionLimit?: number;
     /** Signal `iteration-limit-exceeded` when the iteration limit for this
-     * scope is exceeded. Default: no limits.*/
+     * scope is exceeded. Default: no limits.
+     *
+     * @experimental
+     */
     iterationLimit?: number;
 };
 export declare type RuntimeScope = Scope & {
@@ -717,12 +1014,21 @@ export declare type BaseDefinition = {
     wikidata?: string;
     /**
      * The domain of this item.
-     * For dictionaries, this is the domain of all the items in the dictionary
-     * For strings, it's always 'String'
+     *
+     * For dictionaries, this is the domain of all the items in the dictionary.
+     *
+     * For strings, it's always 'String'.
+     *
      * For symbols, this is the domain of their value.
-     * For functions, this is the domain of their result (aka codomain)
+     *
+     * For functions, this is the signature of the function
+     *
+     * When `domain` is a handler, calculate the domain (or signature) based on
+     * the arguments (for expressions others than functions, `args` is an empty
+     * array). If the function cannot be applied to the arguments, return
+     * `null`.
      */
-    domain?: BoxedExpression | string;
+    domain?: Domain | DomainExpression | string | ((ce: IComputeEngine, args: BoxedExpression[]) => Domain | DomainExpression);
 };
 export declare type BoxedBaseDefinition = {
     name: string;
@@ -735,7 +1041,7 @@ export declare type BoxedBaseDefinition = {
      * This field is usually undefined, but its value is set by `getDefinition()`
      */
     scope: RuntimeScope | undefined;
-    domain?: BoxedExpression;
+    domain?: Domain | ((ce: IComputeEngine, args: BoxedExpression[]) => Domain | DomainExpression);
     _purge(): undefined;
 };
 /**
@@ -746,86 +1052,58 @@ export declare type FunctionDefinitionFlags = {
     /**  If true, the function is applied element by element to lists, matrices
      * and equations.
      *
-     * Default: false
+     * **Default**: `false`
      */
     threadable: boolean;
-    /** If true, [f, [f, a], b] simplifies to [f, a, b]
+    /** If true, `["f", ["f", a], b]` simplifies to `["f", a, b]`
      *
-     * Default: false
+     * **Default**: `false`
      */
     associative: boolean;
-    /** If true, `[f, a, b]` equals `[f, b, a]`. The canonical
+    /** If true, `["f", a, b]` equals `["f", b, a]`. The canonical
      * version of the function will order the arguments.
      *
-     * Default: false
+     * **Default**: `false`
      */
     commutative: boolean;
-    /** If true, when the function is univariate, `[f, ["Add", x, c]]` where `c`
-     * is constant, is simplified to `["Add", [f, x], c]`.
+    /** If true, when the function is univariate, `["f", ["Add", x, c]]` where `c`
+     * is constant, is simplified to `["Add", ["f", x], c]`.
      *
      * When the function is multivariate, additivity is considered only on the
-     * first argument: `[f, ["Add", x, c], y]` simplifies to `["Add", [f, x, y], c]`.
+     * first argument: `["f", ["Add", x, c], y]` simplifies to `["Add", ["f", x, y], c]`.
      *
-     * For example, `log` is additive.
+     * For example, `Log` is additive.
      *
-     * Default: false
+     * **Default**: `false`
      */
-    /** If true, when the function is univariate, `[f, ["Multiply", x, y]]`
-     * simplifies to `["Multiply", [f, x], [f, y]]`.
+    /** If true, when the function is univariate, `["f", ["Multiply", x, y]]`
+     * simplifies to `["Multiply", ["f", x], ["f", y]]`.
      *
      * 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]]`
+     * first argument: `["f", ["Multiply", x, y], z]` simplifies to
+     * `["Multiply", ["f", x, z], ["f", y, z]]`
      *
-     * Default: false
+     * **Default**: `false`
      */
-    /** If true, when the function is univariate, `[f, ["Multiply", x, c]]`
-     * simplifies to `["Multiply", [f, x], c]` where `c` is constant
+    /** 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]]`
+     * first argument: `["f", ["Multiply", x, y], z]` simplifies to
+     * `["Multiply", ["f", x, z], ["f", y, z]]`
      *
-     * Default: false
+     * Default: `false`
      */
-    /** If true, `[f, [f, x]]` simplifies to `[f, x]`.
+    /** If true, `["f", ["f", x]]` simplifies to `["f", x]`.
      *
-     * Default: false
+     * **Default**: `false`
      */
     idempotent: boolean;
-    /** If true, `[f, [f, x]]` simplifies to `x`.
+    /** If true, `["f", ["f", x]]` simplifies to `x`.
      *
-     * Default: false
+     * **Default**: `false`
      */
     involution: 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
-     */
-    numeric: boolean;
-    /**
-     * 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
-     */
-    logic: boolean;
-    /**
-     * 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
-     */
-    relationalOperator: boolean;
     /** If true, the value of this function is always the same for a given
      * set of arguments and it has no side effects.
      *
@@ -849,35 +1127,35 @@ export declare type FunctionDefinitionFlags = {
     inert: boolean;
 };
 /**
- *
+ * Definition record for a function.
  *
  */
 export declare type FunctionDefinition = BaseDefinition & Partial<FunctionDefinitionFlags> & {
     /**
-     * A number used to order expressions. Expressions with higher
-     * complexity are placed after expressions with lower complexity when
-     * ordered canonically.
-     *
-     * 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 (DEFAULT_COMPLEXITY)
+     * 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;
     /**
-     * - `none`: Each of the arguments is evaluated (default)
-     * - `all`: None of the arguments are evaluated and they are passed as is
-     * - `first`: The first argument is not evaluated, the others are
-     * - `rest`: The first argument is evaluated, the others aren't
+     * - `none` Each of the arguments is evaluated (default)
+     * - `all` None of the arguments are evaluated and they are passed as is
+     * - `first` The first argument is not evaluated, the others are
+     * - `rest` The first argument is evaluated, the others aren't
      */
     hold?: 'none' | 'all' | 'first' | 'rest' | 'last' | 'most';
     /**
@@ -926,12 +1204,12 @@ export declare type FunctionDefinition = BaseDefinition & Partial<FunctionDefini
      * `arg.isPositive`.
      *
      * Even though a symbol may not have a value, there may be some information
-     * about it reflected for example in `expr.isZero` or `expr.isPrime`.
+     * about it reflected for example in `this.isZero` or `this.isPrime`.
      *
      * The handler should not perform approximate numeric calculations, such
      * as calculations involving floating point numbers. Making exact
      * calculations on integers or rationals is OK. It is recommended, but not
-     * required, that the calculations be limited to `expr.smallIntegerValue`
+     * required, that the calculations be limited to `this.smallIntegerValue`
      * (i.e. numeric representations of the expression as an integer of small
      * magnitude).
      *
@@ -959,12 +1237,12 @@ export declare type FunctionDefinition = BaseDefinition & Partial<FunctionDefini
      */
     evaluate?: LambdaExpression | ((ce: IComputeEngine, args: BoxedExpression[]) => BoxedExpression | undefined);
     /**
-     * Evaluate numerically `expr`.
+     * Evaluate numerically an expression.
      *
-     * The arguments of `expr` have been simplified and evaluated, numerically
+     * The arguments `args` have been simplified and evaluated, numerically
      * if possible, except the arguments to which a `hold` apply.
      *
-     * The arguments of `expr` may be a combination of numbers, symbolic
+     * The arguments may be a combination of numbers, symbolic
      * expressions and other expressions.
      *
      * Perform as many calculations as possible, and return the result.
@@ -982,13 +1260,13 @@ export declare type FunctionDefinition = BaseDefinition & Partial<FunctionDefini
      * number, but complex numbers are not allowed (the `engine.numericMode`
      * is not `complex` or `auto`).
      *
-     * If the `expr.engine.numericMode` is `auto` or `complex`, you may return
+     * If the `ce.numericMode` is `auto` or `complex`, you may return
      * a Complex number as a result. Otherwise, if the result is a complex
      * value, return `NaN`. If Complex are not allowed, none of the arguments
      * will be complex literals.
      *
-     * If the `expr.engine.numericMode` is `decimal` or `auto` and
-     * `expr.engine.precision` is > 15, you may return a Decimal number.
+     * If the `ce.numericMode` is `decimal` or `auto` and
+     * `this.engine.precision` is > 15, you may return a Decimal number.
      * Otherwise, return a `machine` number approximation. If Decimal are
      * not allowed, none of the arguments will be Decimal literal.
      *
@@ -997,32 +1275,9 @@ export declare type FunctionDefinition = BaseDefinition & Partial<FunctionDefini
      *
      */
     N?: (ce: IComputeEngine, args: BoxedExpression[]) => BoxedExpression | undefined;
-    /**
-     *
-     * Calculate the domain of the result, based on the value of the arguments.
-     *
-     * If the domain of the result is always the same, use the `domain` property
-     * instead.
-     *
-     * The argument `args` represent the arguments of the function.
-     *
-     * The return value is `null` if the input arguments cannot be handled by
-     * this definition.
-     *
-     * Otherwise, the return value is the domain of the result.
-     *
-     * Return `Nothing` if the arguments are acceptable, but the evaluation
-     * will fail, for example in some cases if there are missing arguments.
-     *
-     * This function is used to select the correct definition when there are
-     * multiple definitions for the same function name.
-     *
-     * For example it allows to distinguish between a `Add` function that
-     * applies to numbers and an `Add` function that applies to tensors.
-     *
+    /** Dimensional analysis
+     * @experimental
      */
-    evalDomain?: (ce: IComputeEngine, args: BoxedExpression[]) => BoxedExpression | string | null;
-    /** Dimensional analysis */
     evalDimension?: (ce: IComputeEngine, args: BoxedExpression[]) => BoxedExpression;
     /** Return the sign of the function given a list of arguments. */
     sgn?: (ce: IComputeEngine, args: BoxedExpression[]) => -1 | 0 | 1 | undefined;
@@ -1038,13 +1293,13 @@ export declare type BoxedFunctionDefinition = BoxedBaseDefinition & FunctionDefi
     simplify?: (ce: IComputeEngine, args: BoxedExpression[]) => BoxedExpression | undefined;
     evaluate?: BoxedLambdaExpression | ((ce: IComputeEngine, args: BoxedExpression[]) => BoxedExpression | undefined);
     N?: (ce: IComputeEngine, args: BoxedExpression[]) => BoxedExpression | undefined;
-    evalDomain?: (ce: IComputeEngine, args: BoxedExpression[]) => BoxedExpression | string | null;
     evalDimension?: (ce: IComputeEngine, args: BoxedExpression[]) => BoxedExpression;
     sgn?: (ce: IComputeEngine, args: BoxedExpression[]) => -1 | 0 | 1 | undefined;
     compile?: (expr: BoxedExpression) => CompiledExpression;
 };
 /**
  * When used in a `SymbolDefinition`, these flags are optional.
+ *
  * If provided, they will override the value derived from
  * the symbol's value.
  *
@@ -1103,7 +1358,7 @@ export declare type SymbolDefinition = BaseDefinition & Partial<SymbolFlags> & P
      * `Pi`, the actual value depends on the `precision` setting of the
      * `ComputeEngine` */
     value?: LatexString | SemiBoxedExpression | ((ce: IComputeEngine) => SemiBoxedExpression | null);
-    domain?: string | BoxedExpression;
+    domain?: string | Domain;
 };
 export interface BoxedSymbolDefinition extends BoxedBaseDefinition, Partial<SymbolFlags>, SymbolDefinitionFlags {
     get value(): BoxedExpression | undefined;
@@ -1121,38 +1376,65 @@ export interface ComputeEngineStats {
     expressions: null | Set<BoxedExpression>;
     highwaterMark: number;
 }
+/** @internal */
 export interface IComputeEngine {
+    /** @internal */
     readonly ZERO: BoxedExpression;
+    /** @internal */
     readonly ONE: BoxedExpression;
+    /** @internal */
     readonly TWO: 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;
+    /** @internal */
     readonly DECIMAL_NAN: Decimal;
+    /** @internal */
     readonly DECIMAL_ZERO: Decimal;
+    /** @internal */
     readonly DECIMAL_ONE: Decimal;
+    /** @internal */
     readonly DECIMAL_TWO: Decimal;
+    /** @internal */
     readonly DECIMAL_HALF: Decimal;
+    /** @internal */
     readonly DECIMAL_PI: Decimal;
+    /** @internal */
     readonly DECIMAL_NEGATIVE_ONE: Decimal;
+    /** The current scope */
     context: RuntimeScope;
-    /** Absolute time beyond which evaluation should not proceed */
+    /** Absolute time beyond which evaluation should not proceed
+     * @internal
+     */
     deadline?: number;
+    /** @experimental */
     readonly timeLimit: number;
+    /** @experimental */
     readonly iterationLimit: number;
+    /** @experimental */
     readonly recursionLimit: number;
-    readonly defaultDomain: null | BoxedExpression;
+    defaultDomain: null | Domain;
+    /** {@inheritDoc  NumericMode} */
     numericMode: NumericMode;
     tolerance: number;
     chop(n: number): number;
     chop(n: Decimal): Decimal | 0;
     chop(n: Complex): Complex | 0;
     chop(n: number | Decimal | Complex): number | Decimal | Complex;
+    /** @internal */
     decimal: (a: Decimal.Value) => Decimal;
+    /** @internal */
     complex: (a: number | Complex, b?: number) => Complex;
     set precision(p: number | 'machine');
     get precision(): number;
@@ -1167,7 +1449,7 @@ export interface IComputeEngine {
     /**
      * Return `undefined` if no definition exist for this `head.
      */
-    getFunctionDefinition(head: string, wikidata?: string): undefined | BoxedFunctionDefinition;
+    getFunctionDefinition(head: string, args?: BoxedExpression[]): undefined | BoxedFunctionDefinition;
     /**
      * Returned a boxed expression from the input.
      *
@@ -1181,13 +1463,13 @@ export interface IComputeEngine {
     /** Return a canonical boxed string */
     string(s: string, metadata?: Metadata): BoxedExpression;
     /** Return a canonical boxed domain */
-    domain(domain: BoxedExpression | string, metadata?: Metadata): BoxedExpression;
+    domain(domain: SemiBoxedExpression | Domain | string, metadata?: Metadata): Domain;
     /** Return a canonical expression.
      *
      * Note that the result may not be a function, or may have a different
      * `head` than the one specified.
      *
-     * For example `ce.fn('Add', [ce.number(2),  ce.number(3)]))` -> 5
+     * For example `ce.fn("Add", [ce.number(2),  ce.number(3)]))` \( \to \) 5
      *
      */
     fn(head: string | SemiBoxedExpression, ops: SemiBoxedExpression[], metadata?: Metadata): BoxedExpression;
@@ -1202,47 +1484,47 @@ export interface IComputeEngine {
      * ops canonical, etc..) so that the result is actually canonical.
      */
     _fn(head: string | BoxedExpression, ops: BoxedExpression[], metadata?: Metadata): BoxedExpression;
-    /** Shortcut for `fn('Error'...)`.
+    /** Shortcut for `this.fn("Error"...)`.
      *
      * The result is canonical.
      */
     error(val: BoxedExpression, message: string, messageArg: SemiBoxedExpression): any;
-    /** Shortcut for `fn('Add'...)`.
+    /** Shortcut for `this.fn("Add"...)`.
      *
      * The result is canonical.
      */
     add(ops: BoxedExpression[], metadata?: Metadata): BoxedExpression;
-    /** Shortcut for `fn('Multiply'...)`
+    /** Shortcut for `this.fn("Multiply"...)`
      *
      * The result is canonical.
      */
     mul(ops: BoxedExpression[], metadata?: Metadata): BoxedExpression;
-    /** Shortcut for `fn('Power'...)`
+    /** Shortcut for `this.fn("Power"...)`
      *
      * The result is canonical.
      */
     power(base: BoxedExpression, exponent: number | [number, number] | BoxedExpression, metadata?: Metadata): BoxedExpression;
-    /** Shortcut for `fn('Divide', 1, expr)`
+    /** Shortcut for `this.fn("Divide", [1, expr])`
      *
      * The result is canonical.
      */
     inverse(expr: BoxedExpression, metadata?: Metadata): BoxedExpression;
-    /** Shortcut for `fn('Negate'...)`
+    /** Shortcut for `this.fn("Negate", [expr])`
      *
      * The result is canonical.
      */
     negate(expr: BoxedExpression, metadata?: Metadata): BoxedExpression;
-    /** Shortcut for `fn('Divide'...)`
+    /** Shortcut for `this.fn("Divide", [num, denom])`
      *
      * The result is canonical.
      */
     divide(num: BoxedExpression, denom: BoxedExpression, metadata?: Metadata): BoxedExpression;
-    /** Shortcut for `fn('Pair'...)`
+    /** Shortcut for `this.fn("Pair"...)`
      *
      * The result is canonical.
      */
     pair(first: BoxedExpression, second: BoxedExpression, metadata?: Metadata): BoxedExpression;
-    /** Shortcut for `fn('Tuple'...)`
+    /** Shortcut for `this.fn("Tuple"...)`
      *
      * The result is canonical.
      */
@@ -1255,18 +1537,47 @@ export interface IComputeEngine {
      * The result may not be canonical.
      *
      */
-    parse(s: null | string | LatexString): BoxedExpression | null;
+    parse(s: LatexString | string): BoxedExpression;
+    parse(s: null): null;
+    parse(s: LatexString | string | null): null | BoxedExpression;
     /** Serialize a `BoxedExpression` or a `MathJSON` expression to
      * a LaTeX string
      */
     serialize(expr: SemiBoxedExpression): LatexString;
-    get latexOptions(): Required<NumberFormattingOptions> & Required<ParseLatexOptions> & Required<SerializeLatexOptions>;
-    set latexOptions(opts: NumberFormattingOptions & ParseLatexOptions & SerializeLatexOptions);
+    /**
+     * Options to control the serailization of MathJSON expression to LaTeX
+     * when using `this.latex` or `this.engine.serialize()`.
+     *
+     *
+     * {@inheritDoc  NumberFormattingOptions}
+     * {@inheritDoc  ParseLatexOptions}
+     * {@inheritDoc  SerializeLatexOptions}
+     *
+     */
+    get latexOptions(): NumberFormattingOptions & ParseLatexOptions & SerializeLatexOptions;
+    set latexOptions(opts: Partial<NumberFormattingOptions> & Partial<ParseLatexOptions> & Partial<SerializeLatexOptions>);
+    /** {@inheritDoc  JsonSerializationOptions} */
     get jsonSerializationOptions(): JsonSerializationOptions;
     set jsonSerializationOptions(val: Partial<JsonSerializationOptions>);
-    assume(symbol: LatexString | SemiBoxedExpression, domain: BoxedExpression): AssumeResult;
+    /**
+     * Add an assumption.
+     *
+     * Note that the assumption is put into canonical form before being added.
+     *
+     * @param symbol - The symbol to make an assumption about
+     *
+     * Returns:
+     * - `contradiction` if the new assumption is incompatible with previous
+     * ones.
+     * - `tautology` if the new assumption is redundant with previous ones.
+     * - `ok` if the assumption was successfully added to the assumption set.
+     *
+     *
+     */
+    assume(symbol: LatexString | SemiBoxedExpression, domain: Domain): AssumeResult;
     assume(predicate: LatexString | SemiBoxedExpression): AssumeResult;
     assume(arg1: LatexString | SemiBoxedExpression, arg2?: BoxedExpression): AssumeResult;
+    /** Remove all assumptions about one or more symbols */
     forget(symbol?: string | string[]): void;
     get assumptions(): ExpressionMapInterface<boolean>;
     ask(pattern: LatexString | SemiBoxedExpression): Substitution[];
@@ -1276,15 +1587,27 @@ export interface IComputeEngine {
         scope?: Partial<Scope>;
     }): void;
     popScope(): void;
+    /**
+     * When `condition` is false, signal.
+     *
+     * - `condition` - If `true`, do nothing. If `false`, signal.
+     *
+     * @experimental
+     */
     assert(condition: boolean, expr: BoxedExpression, msg: string, code?: SignalMessage): any;
     signal(expr: BoxedExpression, msg: string, code?: SignalMessage): void;
     signal(sig: WarningSignal): void;
+    /** @internal */
     shouldContinueExecution(): boolean;
+    /** @internal */
     checkContinueExecution(): void;
+    /** @internal */
     cache<T>(name: string, build: () => T, purge?: (T: any) => T | undefined): T;
     readonly stats: ComputeEngineStats;
+    /** @internal */
     purge(): void;
+    /** @internal */
     _register(expr: BoxedExpression): void;
+    /** @internal */
     _unregister(expr: BoxedExpression): void;
 }
-export declare function getVars(expr: BoxedExpression): string[];