@cortex-js/compute-engine 0.4.4 → 0.5.0

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

@@ -1,11 +1,20 @@
-/* 0.4.4 */
+/* 0.5.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 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 type { Parser } 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;
@@ -14,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
@@ -47,7 +69,7 @@ export declare type ReplaceOptions = {
      *
      * Note that if `once` is true, `maxIterations` has no effect.
      *
-     * **Default**: 1
+     * **Default**: `1`
      */
     iterationLimit?: number;
 };
@@ -69,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.
  *
@@ -107,6 +129,9 @@ export declare type BoxedRuleSet = Set<BoxedRule>;
  *
  */
 export declare type DomainExpression = BoxedExpression;
+/**
+ * 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.
@@ -130,13 +155,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`
      */
@@ -173,14 +198,26 @@ export interface BoxedExpression {
      *
      * Otherwise return a LaTeX representation of the expression.
      *
+     * @category Object Methods
      */
     valueOf(): number | string | [number, number];
-    /** From `Object.toString()`, return a LaTeX representation of the expression. */
+    /** 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 `expr.isSame()` */
+    /** From `Object.is()`. Equivalent to `BoxedExpression.isSame()`
+     *
+     * @category Object Methods
+     *
+     */
     is(rhs: any): boolean;
+    /** @internal */
     get hash(): number;
     /** An optional short description of the symbol or function head.
      *
@@ -197,7 +234,7 @@ 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;
@@ -206,7 +243,7 @@ export interface BoxedExpression {
     /** 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
@@ -214,8 +251,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.
      */
@@ -229,33 +266,75 @@ 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` */
+     * 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;
     /**
@@ -267,6 +346,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.
@@ -274,6 +355,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.
@@ -283,6 +367,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.
@@ -291,6 +378,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
@@ -309,6 +399,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;
     /**
@@ -320,42 +413,66 @@ 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` */
+    /** True if this domain is a subset of domain `d`
+     *
+     * @category Expression Properties
+     *
+     */
     isSubsetOf(d: BoxedExpression | string): undefined | boolean;
     /** True if the value of this expression is a number.
      *
@@ -363,14 +480,24 @@ export interface BoxedExpression {
      *
      * 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;
     /**
@@ -381,17 +508,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;
     /**
@@ -399,38 +535,83 @@ 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 `false`
      *
+     * @category Relational Operator
      */
     isSame(rhs: BoxedExpression): boolean;
     /**
@@ -459,20 +640,46 @@ export interface BoxedExpression {
      * Numbers whose difference is less than `engine.tolerance` are
      * considered equal. This tolerance is set when the `engine.precision` is
      * changed to be such that the last two digits are ignored.
+     *
+     * @category Relational Operator
      */
     isEqual(rhs: BoxedExpression): boolean;
-    /** 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;
@@ -544,22 +751,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 `expr.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.
      *
@@ -567,10 +774,10 @@ export interface BoxedExpression {
      * are performed. The calculations are performed according
      * to the `numericMode` and `precision` properties of the `ComputeEngine`.
      *
-     * To only perform exact calculations, use `expr.evaluate()` instead.
+     * To only perform exact calculations, use `this.evaluate()` instead.
      *
-     * If the function is not numeric, the result of `expr.N()` is the same as
-     * `expr.evaluate()`.
+     * If the function is not numeric, the result of `this.N()` is the same as
+     * `this.evaluate()`.
      *
      * The result is in canonical form.
      */
@@ -599,8 +806,8 @@ export interface BoxedExpression {
     /**
      * Replace all the symbols in the expression as indicated.
      *
-     * Note the same effect can be achieved with `expr.replace()`, but
-     * using `expr.subs()` 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;
@@ -608,12 +815,12 @@ 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.
      *
-     * For internal use only.
+     * @internal
      */
     _purge(): undefined;
 }
@@ -634,6 +841,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
@@ -697,17 +905,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 & {
@@ -750,9 +968,13 @@ 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)
      */
     domain?: BoxedExpression | string;
@@ -779,56 +1001,56 @@ 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;
     /**
@@ -882,35 +1104,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
+     * 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';
     /**
@@ -959,12 +1181,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).
      *
@@ -992,12 +1214,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.
@@ -1015,13 +1237,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.
      *
@@ -1044,7 +1266,7 @@ export declare type FunctionDefinition = BaseDefinition & Partial<FunctionDefini
      *
      * Otherwise, the return value is the domain of the result.
      *
-     * Return `Nothing` if the arguments are acceptable, but the evaluation
+     * 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
@@ -1055,7 +1277,9 @@ export declare type FunctionDefinition = BaseDefinition & Partial<FunctionDefini
      *
      */
     evalDomain?: (ce: IComputeEngine, args: BoxedExpression[]) => BoxedExpression | string | null;
-    /** Dimensional analysis */
+    /** Dimensional analysis
+     * @experimental
+     */
     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;
@@ -1078,6 +1302,7 @@ export declare type BoxedFunctionDefinition = BoxedBaseDefinition & FunctionDefi
 };
 /**
  * When used in a `SymbolDefinition`, these flags are optional.
+ *
  * If provided, they will override the value derived from
  * the symbol's value.
  *
@@ -1154,38 +1379,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 | BoxedExpression;
+    /** {@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;
@@ -1220,7 +1472,7 @@ export interface IComputeEngine {
      * 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;
@@ -1235,47 +1487,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.
      */
@@ -1288,18 +1540,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;
+    /**
+     * 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>);
+    /**
+     * 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: BoxedExpression): 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[];
@@ -1309,15 +1590,28 @@ 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[];