nerdamer 2.0.0-rc.1 → 2.0.0

package/output/core/classes/polynomial/SparsePolynomialAdapter.d.ts

@@ -0,0 +1,56 @@
+/**
+ * @module sparsePolynomialAdapter
+ *
+ * Conversion from Nerdamer's expression-facing polynomial forms to the exact
+ * integer sparse polynomial representation.
+ */
+import { Expression } from '../expression/Expression';
+import { SparsePolynomial } from './SparsePolynomial';
+import type { Polynomial } from './Polynomial';
+/**
+ * Converts an integer-coefficient polynomial expression directly to sparse form.
+ *
+ * Sums, products, and non-negative integer powers are evaluated with sparse
+ * polynomial arithmetic, so callers do not need to construct the legacy Polynomial
+ * representation first. Variables are ordered by ascending degree and then by name.
+ */
+export declare function expressionToSparsePolynomial(expression: Expression): Readonly<{
+    polynomial: SparsePolynomial;
+    variables: readonly string[];
+}>;
+/**
+ * Converts a rational-coefficient polynomial expression directly to integer sparse form.
+ *
+ * The supplied variables define the sparse ring coordinates. Rational denominators are
+ * carried separately while sums, products, and non-negative integer powers are evaluated,
+ * then reduced against common integer coefficient content.
+ */
+export declare function expressionToIntegerSparsePolynomial(expression: Expression, variables: readonly string[]): Readonly<{
+    polynomial: SparsePolynomial;
+    denominator: bigint;
+}>;
+/**
+ * Converts a Polynomial with rational numeric coefficients to an integer sparse
+ * polynomial by clearing one common positive denominator.
+ *
+ * The supplied variables define the sparse ring coordinates and must include every
+ * variable in the polynomial.
+ */
+export declare function polynomialToIntegerSparsePolynomial(polynomial: Polynomial, variables: readonly string[]): Readonly<{
+    polynomial: SparsePolynomial;
+    denominator: bigint;
+}>;
+/**
+ * Converts a Polynomial to an exact sparse polynomial over the integers.
+ *
+ * Coefficients must already be integers; use
+ * {@link polynomialToIntegerSparsePolynomial} when rational coefficients should be
+ * cleared first.
+ */
+export declare function polynomialToSparsePolynomial(polynomial: Polynomial, variables: readonly string[]): SparsePolynomial;
+/**
+ * Converts an exact sparse polynomial directly to an Expression.
+ *
+ * Conversion does not pass through Polynomial, so bigint exponents remain exact.
+ */
+export declare function sparsePolynomialToExpression(polynomial: SparsePolynomial, variables: readonly string[]): Expression;

package/output/core/classes/polynomial/SparsePolynomialAdapter.js

@@ -0,0 +1,241 @@
+"use strict";
+/**
+ * @module sparsePolynomialAdapter
+ *
+ * Conversion from Nerdamer's expression-facing polynomial forms to the exact
+ * integer sparse polynomial representation.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.expressionToSparsePolynomial = expressionToSparsePolynomial;
+exports.expressionToIntegerSparsePolynomial = expressionToIntegerSparsePolynomial;
+exports.polynomialToIntegerSparsePolynomial = polynomialToIntegerSparsePolynomial;
+exports.polynomialToSparsePolynomial = polynomialToSparsePolynomial;
+exports.sparsePolynomialToExpression = sparsePolynomialToExpression;
+const errors_1 = require("../../errors");
+const bigint_1 = require("../../functions/bigint/bigint");
+const Expression_1 = require("../expression/Expression");
+const shortcuts_1 = require("../expression/shortcuts");
+const SparsePolynomial_1 = require("./SparsePolynomial");
+/**
+ * Converts an integer-coefficient polynomial expression directly to sparse form.
+ *
+ * Sums, products, and non-negative integer powers are evaluated with sparse
+ * polynomial arithmetic, so callers do not need to construct the legacy Polynomial
+ * representation first. Variables are ordered by ascending degree and then by name.
+ */
+function expressionToSparsePolynomial(expression) {
+    const sourceVariables = expression.variables().sort();
+    const variableIndices = new Map(sourceVariables.map((variable, index) => [variable, index]));
+    function powerOf(current) {
+        const power = current.getPower();
+        if (!power.isInteger() || power.sign() < 0) {
+            throw new errors_1.PolynomialError((0, errors_1.message)('notAPolynomial'));
+        }
+        return power.getMultiplier().numerator;
+    }
+    function integerMultiplier(current) {
+        const multiplier = current.getMultiplier();
+        if (multiplier.denominator !== 1n) {
+            throw new Error((0, errors_1.message)('integerRequired'));
+        }
+        return multiplier.numerator;
+    }
+    function convert(current) {
+        const variableCount = sourceVariables.length;
+        if (current.isNUM()) {
+            return SparsePolynomial_1.SparsePolynomial.constant(variableCount, integerMultiplier(current));
+        }
+        if (current.isVAR()) {
+            const variableIndex = variableIndices.get(current.value);
+            if (variableIndex === undefined) {
+                throw new errors_1.PolynomialError((0, errors_1.message)('notAPolynomial'));
+            }
+            const exponents = new Array(variableCount).fill(0n);
+            exponents[variableIndex] = powerOf(current);
+            return SparsePolynomial_1.SparsePolynomial.monomial(variableCount, integerMultiplier(current), exponents);
+        }
+        if (current.isSum()) {
+            let sum = SparsePolynomial_1.SparsePolynomial.zero(variableCount);
+            for (const term of current.elementsArray()) {
+                sum = sum.add(convert(term));
+            }
+            return sum.pow(powerOf(current)).scale(integerMultiplier(current));
+        }
+        if (current.isProduct()) {
+            let product = SparsePolynomial_1.SparsePolynomial.constant(variableCount, 1n);
+            for (const factor of current.elementsArray()) {
+                product = product.multiply(convert(factor));
+            }
+            return product.pow(powerOf(current)).scale(integerMultiplier(current));
+        }
+        throw new errors_1.PolynomialError((0, errors_1.message)('notAPolynomial'));
+    }
+    const source = convert(expression);
+    const order = sourceVariables
+        .map((variable, index) => ({
+        variable,
+        index,
+        degree: source.degree(index) ?? 0n,
+    }))
+        .sort((left, right) => {
+        if (left.degree < right.degree) {
+            return -1;
+        }
+        if (left.degree > right.degree) {
+            return 1;
+        }
+        return left.variable.localeCompare(right.variable);
+    });
+    const variables = order.map(entry => entry.variable);
+    if (order.every((entry, index) => entry.index === index)) {
+        return { polynomial: source, variables };
+    }
+    const terms = source.terms().map(term => ({
+        coefficient: term.coefficient,
+        exponents: order.map(entry => term.exponents[entry.index]),
+    }));
+    return {
+        polynomial: new SparsePolynomial_1.SparsePolynomial(source.variableCount, terms),
+        variables,
+    };
+}
+/**
+ * Converts a rational-coefficient polynomial expression directly to integer sparse form.
+ *
+ * The supplied variables define the sparse ring coordinates. Rational denominators are
+ * carried separately while sums, products, and non-negative integer powers are evaluated,
+ * then reduced against common integer coefficient content.
+ */
+function expressionToIntegerSparsePolynomial(expression, variables) {
+    const selected = new Set();
+    for (const variable of variables) {
+        if (selected.has(variable)) {
+            throw new RangeError((0, errors_1.message)('sparseAdapterVariablesUnique'));
+        }
+        selected.add(variable);
+    }
+    for (const variable of expression.variables()) {
+        if (!selected.has(variable)) {
+            throw new RangeError((0, errors_1.message)('sparseAdapterVariablesIncludeEvery'));
+        }
+    }
+    const variableCount = variables.length;
+    const variableIndices = new Map(variables.map((variable, index) => [variable, index]));
+    function powerOf(current) {
+        const power = current.getPower();
+        if (!power.isInteger() || power.sign() < 0) {
+            throw new errors_1.PolynomialError((0, errors_1.message)('notAPolynomial'));
+        }
+        return power.getMultiplier().numerator;
+    }
+    function normalize(polynomial, denominator) {
+        if (polynomial.isZero()) {
+            return { polynomial, denominator: 1n };
+        }
+        const divisor = (0, bigint_1.GCD)(polynomial.content(), denominator);
+        return divisor === 1n
+            ? { polynomial, denominator }
+            : {
+                polynomial: polynomial.divideByScalarExact(divisor),
+                denominator: denominator / divisor,
+            };
+    }
+    function applyPowerAndMultiplier(current, polynomial, denominator) {
+        const exponent = powerOf(current);
+        const multiplier = current.getMultiplier();
+        return normalize(polynomial.pow(exponent).scale(multiplier.numerator), denominator ** exponent * multiplier.denominator);
+    }
+    function convert(current) {
+        const multiplier = current.getMultiplier();
+        if (current.isNUM()) {
+            return normalize(SparsePolynomial_1.SparsePolynomial.constant(variableCount, multiplier.numerator), multiplier.denominator);
+        }
+        if (current.isVAR()) {
+            const variableIndex = variableIndices.get(current.value);
+            if (variableIndex === undefined) {
+                throw new errors_1.PolynomialError((0, errors_1.message)('notAPolynomial'));
+            }
+            const exponents = new Array(variableCount).fill(0n);
+            exponents[variableIndex] = powerOf(current);
+            return normalize(SparsePolynomial_1.SparsePolynomial.monomial(variableCount, multiplier.numerator, exponents), multiplier.denominator);
+        }
+        if (current.isSum()) {
+            let polynomial = SparsePolynomial_1.SparsePolynomial.zero(variableCount);
+            let denominator = 1n;
+            for (const term of current.elementsArray()) {
+                const converted = convert(term);
+                const commonDenominator = (0, bigint_1.LCM)(denominator, converted.denominator);
+                polynomial = polynomial
+                    .scale(commonDenominator / denominator)
+                    .add(converted.polynomial.scale(commonDenominator / converted.denominator));
+                denominator = commonDenominator;
+            }
+            return applyPowerAndMultiplier(current, polynomial, denominator);
+        }
+        if (current.isProduct()) {
+            let polynomial = SparsePolynomial_1.SparsePolynomial.constant(variableCount, 1n);
+            let denominator = 1n;
+            for (const factor of current.elementsArray()) {
+                const converted = convert(factor);
+                polynomial = polynomial.multiply(converted.polynomial);
+                denominator *= converted.denominator;
+            }
+            return applyPowerAndMultiplier(current, polynomial, denominator);
+        }
+        throw new errors_1.PolynomialError((0, errors_1.message)('notAPolynomial'));
+    }
+    const converted = convert(expression);
+    const terms = [...converted.polynomial.terms()].sort((left, right) => -SparsePolynomial_1.SparsePolynomial.compareMonomials(left.exponents, right.exponents, 'lex'));
+    return {
+        polynomial: new SparsePolynomial_1.SparsePolynomial(variableCount, terms),
+        denominator: converted.denominator,
+    };
+}
+/**
+ * Converts a Polynomial with rational numeric coefficients to an integer sparse
+ * polynomial by clearing one common positive denominator.
+ *
+ * The supplied variables define the sparse ring coordinates and must include every
+ * variable in the polynomial.
+ */
+function polynomialToIntegerSparsePolynomial(polynomial, variables) {
+    return expressionToIntegerSparsePolynomial(polynomial.getExpression(), variables);
+}
+/**
+ * Converts a Polynomial to an exact sparse polynomial over the integers.
+ *
+ * Coefficients must already be integers; use
+ * {@link polynomialToIntegerSparsePolynomial} when rational coefficients should be
+ * cleared first.
+ */
+function polynomialToSparsePolynomial(polynomial, variables) {
+    const converted = polynomialToIntegerSparsePolynomial(polynomial, variables);
+    if (converted.denominator !== 1n) {
+        throw new Error((0, errors_1.message)('integerRequired'));
+    }
+    return converted.polynomial;
+}
+/**
+ * Converts an exact sparse polynomial directly to an Expression.
+ *
+ * Conversion does not pass through Polynomial, so bigint exponents remain exact.
+ */
+function sparsePolynomialToExpression(polynomial, variables) {
+    if (variables.length !== polynomial.variableCount) {
+        throw new RangeError((0, errors_1.message)('sparseExpressionConversionNameCount'));
+    }
+    let result = (0, shortcuts_1.zero)();
+    for (const term of polynomial.terms()) {
+        let expression = Expression_1.Expression.Number(term.coefficient);
+        for (let variableIndex = 0; variableIndex < variables.length; variableIndex++) {
+            const exponent = term.exponents[variableIndex];
+            if (exponent === 0n) {
+                continue;
+            }
+            const variable = Expression_1.Expression.Variable(variables[variableIndex]);
+            expression = expression.times(exponent === 1n ? variable : variable.pow(Expression_1.Expression.Number(exponent)));
+        }
+        result = result.plus(expression);
+    }
+    return result;
+}

package/output/core/classes/polynomial/Term.js

@@ -132,7 +132,7 @@ class Term {
      * @returns A term with copied coefficient, powers, and variable array. Lazy caches are rebuilt on demand.
      */
     copy() {
-        return new Term(new Expression_1.Expression(this.coeff), { ...this.powers }, this.variables);
+        return new Term(this.coeff.copy(), { ...this.powers }, this.variables);
     }
     deg(v, value) {
         if (value !== undefined) {
@@ -238,7 +238,7 @@ class Term {
      */
     getExpression() {
         if (this.expression === undefined) {
-            let expression = new Expression_1.Expression(this.coeff);
+            let expression = this.coeff.copy();
             for (const variable of this.variables) {
                 const power = this.deg(variable);
                 if (power !== 0) {

package/output/core/{adapters.d.ts → classes/polynomial/adapters.d.ts}

@@ -1,5 +1,5 @@
-import { Polynomial } from './classes/polynomial/Polynomial';
-import type { ExpressionInput } from './types';
+import { Polynomial } from './Polynomial';
+import type { ExpressionInput } from '../../types';
 /**
  * Extracts the Z Polynomial from Q.
  * Given a polynomial with rational coefficients, returns:

package/output/core/classes/polynomial/adapters.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.expressionToZPoly = expressionToZPoly;
+const Expression_1 = require("../expression/Expression");
+const Polynomial_1 = require("./Polynomial");
+const SparsePolynomialAdapter_1 = require("./SparsePolynomialAdapter");
+/**
+ * Extracts the Z Polynomial from Q.
+ * Given a polynomial with rational coefficients, returns:
+ * - zPoly: the polynomial scaled to have integer coefficients (primitive part)
+ * - content: the GCD of the integer coefficients after clearing denominators
+ * - denominator: the common denominator used to clear fractions
+ *
+ * The relationship is: original = (content / denominator) * zPoly
+ *
+ * @param x
+ */
+function expressionToZPoly(x) {
+    const expression = Expression_1.Expression.create(x);
+    const variables = expression.variables().sort();
+    const converted = (0, SparsePolynomialAdapter_1.expressionToIntegerSparsePolynomial)(expression, variables);
+    const coefficientContent = converted.polynomial.isZero()
+        ? 1n
+        : converted.polynomial.content();
+    const primitive = coefficientContent === 1n
+        ? converted.polynomial
+        : converted.polynomial.divideByScalarExact(coefficientContent);
+    return {
+        zPoly: new Polynomial_1.Polynomial((0, SparsePolynomialAdapter_1.sparsePolynomialToExpression)(primitive, variables), [...variables], 'lex'),
+        content: new Polynomial_1.Polynomial(Expression_1.Expression.Number(coefficientContent)),
+        denominator: new Polynomial_1.Polynomial(Expression_1.Expression.Number(converted.denominator)),
+    };
+}

package/output/core/classes/polynomial/dispatch.d.ts

@@ -0,0 +1 @@
+export declare function loadPolynomialFunctions(): void;

package/output/core/classes/polynomial/dispatch.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadPolynomialFunctions = loadPolynomialFunctions;
+const dispatch_1 = require("../../dispatch");
+const functions_1 = require("./functions");
+function loadPolynomialFunctions() {
+    Object.assign(dispatch_1.mathFunctionRegistry, {
+        deg: (0, dispatch_1.systemFunction)({ fn: functions_1.deg, minArgs: 1, maxArgs: 2, distElWise: true }),
+        content: (0, dispatch_1.systemFunction)({ fn: functions_1.content, minArgs: 1, maxArgs: 1, distElWise: true }),
+        coeffs: (0, dispatch_1.systemFunction)({ fn: functions_1.coeffs, minArgs: 1, maxArgs: 2, distElWise: false }),
+        div: (0, dispatch_1.systemFunction)({ fn: functions_1.div, minArgs: 2, maxArgs: 2, distElWise: false }),
+        divide: (0, dispatch_1.systemFunction)({ fn: functions_1.divide, minArgs: 2, maxArgs: 2, distElWise: false }),
+    });
+}

package/output/core/classes/polynomial/functions.d.ts

@@ -42,6 +42,14 @@ export declare function deg(x: ExpressionInput | Polynomial, variable?: Expressi
  * ```
  */
 export declare function content(x: ExpressionInput | Polynomial): Expression;
+/**
+ * Returns polynomial coefficients as a dense Vector ordered by ascending power.
+ *
+ * When no variable is supplied, the first variable in the expression is used, matching
+ * the legacy parser helper. A constant expression therefore has the single coefficient
+ * at power zero.
+ */
+export declare function coeffs(x: ExpressionInput, variable?: ExpressionInput): Vector;
 /**
  * Returns the quotient and remainder of polynomial division.
  *

package/output/core/classes/polynomial/functions.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.deg = deg;
 exports.content = content;
+exports.coeffs = coeffs;
 exports.div = div;
 exports.divide = divide;
 const Expression_1 = require("../expression/Expression");
@@ -10,6 +11,7 @@ const utils_1 = require("../expression/utils");
 const constants_1 = require("../parser/constants");
 const Vector_1 = require("../vector/Vector");
 const Polynomial_1 = require("./Polynomial");
+const SparsePolynomialAdapter_1 = require("./SparsePolynomialAdapter");
 const utils_2 = require("./utils");
 /**
  * Returns the degree of a polynomial expression.
@@ -39,11 +41,34 @@ function deg(x, variable) {
         variableName = (0, utils_1.assertPlainVariableAndGetString)(variableExpression);
     }
     let retval = undefined;
-    try {
-        const polynomial = Polynomial_1.Polynomial.isPolynomial(x) ? x : new Polynomial_1.Polynomial(x);
-        retval = Expression_1.Expression.create(polynomial.deg(variableName));
+    if (Polynomial_1.Polynomial.isPolynomial(x)) {
+        retval = Expression_1.Expression.create(x.deg(variableName));
+    }
+    else {
+        const inputExpression = Expression_1.Expression.create(x);
+        try {
+            const variables = inputExpression.variables().sort();
+            const converted = (0, SparsePolynomialAdapter_1.expressionToIntegerSparsePolynomial)(inputExpression, variables);
+            let degree;
+            if (variableName === undefined) {
+                degree = converted.polynomial.totalDegree() ?? 0n;
+            }
+            else {
+                const variableIndex = variables.indexOf(variableName);
+                degree =
+                    variableIndex === -1
+                        ? 0n
+                        : (converted.polynomial.degree(variableIndex) ?? 0n);
+            }
+            retval = Expression_1.Expression.Number(degree);
+        }
+        catch {
+            try {
+                retval = Expression_1.Expression.create(new Polynomial_1.Polynomial(inputExpression).deg(variableName));
+            }
+            catch { }
+        }
     }
-    catch { }
     const input = Polynomial_1.Polynomial.isPolynomial(x) ? x.getExpression() : x;
     const args = variableExpression === undefined ? [input] : [input, variableExpression];
     return retval ?? Expression_1.Expression.toFunction(constants_1.DEG, args);
@@ -68,13 +93,51 @@ function deg(x, variable) {
  */
 function content(x) {
     let retval = undefined;
-    try {
-        const polynomial = Polynomial_1.Polynomial.isPolynomial(x) ? x : new Polynomial_1.Polynomial(x);
-        retval = Expression_1.Expression.create(polynomial.content());
+    if (Polynomial_1.Polynomial.isPolynomial(x)) {
+        retval = Expression_1.Expression.create(x.content());
+    }
+    else {
+        const inputExpression = Expression_1.Expression.create(x);
+        try {
+            if (inputExpression.isZero()) {
+                retval = Expression_1.Expression.create(new Polynomial_1.Polynomial(inputExpression).content());
+            }
+            else {
+                const variables = inputExpression.variables().sort();
+                const converted = (0, SparsePolynomialAdapter_1.expressionToIntegerSparsePolynomial)(inputExpression, variables);
+                retval = Expression_1.Expression.Number(converted.polynomial.content()).div(Expression_1.Expression.Number(converted.denominator));
+                retval.getMultiplier().asDecimal = inputExpression.hasDecimal();
+            }
+        }
+        catch {
+            try {
+                retval = Expression_1.Expression.create(new Polynomial_1.Polynomial(inputExpression).content());
+            }
+            catch { }
+        }
     }
-    catch { }
     return retval ?? Expression_1.Expression.toFunction(constants_1.CONTENT, [Polynomial_1.Polynomial.isPolynomial(x) ? x.getExpression() : x]);
 }
+/**
+ * Returns polynomial coefficients as a dense Vector ordered by ascending power.
+ *
+ * When no variable is supplied, the first variable in the expression is used, matching
+ * the legacy parser helper. A constant expression therefore has the single coefficient
+ * at power zero.
+ */
+function coeffs(x, variable) {
+    const expression = Expression_1.Expression.create(x);
+    let variableName;
+    if (variable !== undefined) {
+        variableName = (0, utils_1.assertPlainVariableAndGetString)(Expression_1.Expression.create(variable));
+    }
+    else {
+        variableName = expression.variables()[0];
+    }
+    return variableName === undefined
+        ? new Vector_1.Vector([expression.copy()])
+        : expression.coeffs(variableName).toVector();
+}
 /**
  * Returns the quotient and remainder of polynomial division.
  *

package/output/core/classes/polynomial/utils.js

@@ -7,6 +7,7 @@ exports.combinePolynomialVariables = combinePolynomialVariables;
 exports.polyMod = polyMod;
 exports.maxCommonVariableOccurrence = maxCommonVariableOccurrence;
 exports.polynomialFromNumber = polynomialFromNumber;
+const errors_1 = require("../../errors");
 const utils_1 = require("../../functions/utils");
 const shortcuts_1 = require("../expression/shortcuts");
 const Polynomial_1 = require("./Polynomial");
@@ -53,7 +54,7 @@ function polyDiv(Fs, g, ordering, variables) {
     // Begin
     while (!p.isZero()) {
         if (iter++ > maxIter) {
-            throw new Error('Maximum iterations reached');
+            throw new Error((0, errors_1.message)('polynomialMaximumIterations'));
         }
         let divisionOccurred = false;
         const s = F.length;

package/output/core/classes/rational/Rational.d.ts

@@ -2,6 +2,9 @@ import Decimal from 'decimal.js';
 import { Expression } from '../expression/Expression';
 import { RATIONAL } from '../parser/constants';
 import type { OptionsObject } from '../parser/types';
+/** Maximum scientific significant-digit count accepted by decimal.js. */
+export declare const MAX_SCIENTIFIC_SIGNIFICANT_DIGITS = 1000000000;
+export declare function validateScientificSignificantDigits(value: unknown, received?: string): number;
 /**
  * Represents an exact rational value as a `bigint` numerator and denominator.
  *
@@ -151,14 +154,6 @@ export declare class Rational {
      * @returns The pairwise rational LCM.
      */
     static LCM(...args: Rational[]): Rational;
-    /**
-     * Copies a rational's representation and presentation metadata.
-     *
-     * @param x - Rational to copy.
-     * @returns A distinct `Rational` with the same numerator, denominator, `value`, and
-     * decimal-presentation flag.
-     */
-    static makeCopy(x: Rational): Rational;
     /**
      * Updates shared numeric settings used by rational decimal conversion.
      *
@@ -418,14 +413,16 @@ export declare class Rational {
      * Formats this rational as fraction, integer, or decimal text.
      *
      * @remarks
-     * Decimal formatting is selected when {@link Rational.asDecimal} is set or when
+     * Scientific formatting is selected when `options.scientific` supplies an integer significant-digit
+     * count from 1 through 1e9. The requested count is preserved in the coefficient, including
+     * trailing zeroes. Otherwise decimal formatting is selected when {@link Rational.asDecimal} is set or when
      * `options.decimal` is truthy. Non-integer decimal output uses `decimal.js`; an optional
      * `options.precision` temporarily controls its significant-digit precision for this conversion.
      * Integer decimal output includes a `.0` suffix. Without decimal formatting, non-integer
      * fractions are emitted from the stored numerator and denominator, and integers as plain text.
      *
-     * @param options - Formatting options. `decimal` forces decimal output and `precision` controls
-     * decimal conversion precision when applicable.
+     * @param options - Formatting options. `scientific` selects significant-digit scientific output;
+     * `decimal` forces decimal output and `precision` controls decimal conversion precision when applicable.
      * @returns The formatted numeric text.
      */
     text(options?: OptionsObject): string;