nerdamer 1.1.13 → 2.0.0-rc.2

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

@@ -0,0 +1,235 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.product = product;
+exports.sum = sum;
+exports.stripPower = stripPower;
+exports.cloneExpressionTree = cloneExpressionTree;
+exports.copyOver = copyOver;
+exports.toArrays = toArrays;
+exports.largestPower = largestPower;
+exports.assertPlainVariableAndGetString = assertPlainVariableAndGetString;
+exports.getNumericOrAssumedValue = getNumericOrAssumedValue;
+const errors_1 = require("../../errors");
+const assume_1 = require("../assumption/assume");
+const Expression_1 = require("./Expression");
+const shortcuts_1 = require("./shortcuts");
+/** Multiplies a series of Expressions into one product. */
+function product(...args) {
+    let retval = (0, shortcuts_1.one)();
+    for (const x of args) {
+        retval = retval.times(x);
+    }
+    return retval;
+}
+/** Adds a series of Expressions into one sum. */
+function sum(...args) {
+    let retval = (0, shortcuts_1.zero)();
+    for (const x of args) {
+        retval = retval.plus(x);
+    }
+    return retval;
+}
+/** Removes the power from an Expression. The original object is unchanged. */
+function stripPower(x) {
+    const retval = x.copy();
+    delete retval.power;
+    return retval;
+}
+/**
+ * Deep-copies an Expression tree without routing every nested node back through the
+ * Expression constructor and factory.
+ *
+ * Expression.hook is still applied once for each copied node, matching the existing
+ * copy path. Mutable nested values are recreated so the returned tree remains
+ * independent from the source.
+ */
+function cloneExpressionTree(source) {
+    const hooked = Expression_1.Expression.hook(source);
+    if (!Expression_1.Expression.isExpression(hooked)) {
+        return Expression_1.Expression.create(hooked);
+    }
+    const src = hooked;
+    const target = Object.create(Expression_1.Expression.prototype);
+    target.dataType = src.dataType;
+    target.deferred = src.deferred;
+    target.isEnumerable = src.isEnumerable;
+    target.type = src.type;
+    target.value = src.value;
+    target.precision = src.precision;
+    target.scientific = src.scientific;
+    if (src.multiplier) {
+        target.multiplier = src.multiplier.copy();
+    }
+    if (src.name !== undefined) {
+        target.name = src.name;
+    }
+    if (src.power) {
+        target.power = cloneExpressionTree(src.power);
+    }
+    if (src.args) {
+        target.args = src.args.map(cloneExpressionTree);
+    }
+    if (src.base) {
+        target.base = cloneExpressionTree(src.base);
+    }
+    if (src.elements) {
+        target.elements = {};
+        for (const key in src.elements) {
+            target.elements[key] = cloneExpressionTree(src.elements[key]);
+        }
+    }
+    return target;
+}
+/**
+ * Copies over all the properties of the provided symbolic essentially cloning it to x.
+ *
+ * @param sym
+ * @returns
+ */
+function copyOver(src, target, options) {
+    options = {
+        ...{ omitMultiplier: false, omitPower: false },
+        ...options,
+    };
+    // Copy over the multiplier
+    if (src.multiplier && !options.omitMultiplier) {
+        target.multiplier = src.multiplier.copy();
+    }
+    // toFunctions have name so we need those copied
+    if (src.name !== undefined) {
+        target.name = src.name;
+    }
+    // Copy over the power
+    if (src.power && !options.omitPower) {
+        target.power = cloneExpressionTree(src.power);
+    }
+    // Copy over the args if any
+    if (src.args) {
+        target.args = [];
+        for (const arg of src.args) {
+            target.args.push(cloneExpressionTree(arg));
+        }
+    }
+    // Copy over the base if an
+    if (src.base) {
+        target.base = cloneExpressionTree(src.base);
+    }
+    // Copy over the elements if any
+    if (src.elements) {
+        target.elements = {};
+        for (const x in src.elements) {
+            target.elements[x] = cloneExpressionTree(src.elements[x]);
+        }
+    }
+    // Last but not least
+    target.type = src.type;
+    target.value = src.value;
+    target.precision = src.precision;
+    target.scientific = src.scientific;
+    target.deferred = src.deferred;
+    return target;
+}
+/**
+ * This function converts the expression in a collection of arrays
+ *
+ * @param x
+ * @param arrayObj
+ * @returns
+ */
+function toArrays(x, arrayObj) {
+    /*
+     * The first thing to realize is that only PRD elements can have a numerator and denominators.
+     * All others are either the numerator or the denominator. To illustrate let look at some examples:
+     * x^2/4 => x^2/4
+     * cos(x)^(1/3) => cos(x)^(1/3)
+     * 5*x^-1+(5/6)*x^3+x => (5*x^3)/6+x+5/x
+     * (x+1)/(x+5) => (x+1)/(x+5)
+     * Out of all the examples, the only one with symbolic values in the denominator is the last one which is of type PRD.
+     * We can now simplify the problem by only focusing on PRD elements for symbolic denominators
+     */
+    const retval = arrayObj || {
+        num: [],
+        den: [],
+    };
+    function addMultiplier(m) {
+        retval.num.push(Expression_1.Expression.Number(m.numerator));
+        // Only add the denominator if it's not one
+        if (m.denominator !== 1n) {
+            retval.den.push(Expression_1.Expression.Number(m.denominator));
+        }
+    }
+    if (x.isNUM()) {
+        addMultiplier(x.getMultiplier());
+    }
+    else {
+        addMultiplier(x.getMultiplier());
+        const power = x.getPower();
+        // Handle products. Their elements should be distributed over the numerator and denominator
+        // Consider 2*x*y/(a*b). The desired output is { num: [2, y, y], den: [a, b]}
+        if (x.isProduct()) {
+            const elements = x.elementsArray();
+            for (const element of elements) {
+                // Pass in this object so they're added to the numerator or the denominator of this retval object
+                toArrays(element, retval);
+            }
+        }
+        // Consider 2/3*x. The desired output is { num: [2, x], den [3] };
+        // Consider (3*y)^(2/3). The desired output = { num: [3, y], den: [], power: { num: [2], den: [3]} };
+        else {
+            const term = stripPower(x.toUnitMultiplier());
+            // Put it in numerator if positive power else the denominator
+            const target = power.getMultiplier().isNegative() ? retval.den : retval.num;
+            target.push(term);
+        }
+        // Handle the power. Remember that x^(-2) is now 1/x^2 so the power has to be the absolute value
+        retval.power = toArrays(power.abs());
+        // Handle args
+        // Consider cos(2*pi). The desired output = { name: 'cos', args[{ num: [2, pi], den: [] }] }
+        if (x.args) {
+            retval.args = x.getArguments().map(x => {
+                return toArrays(x);
+            });
+        }
+    }
+    return retval;
+}
+/**
+ * Gets the max between two or more Expressions. Just know that if two variable arguments are provided,
+ * it will not be able to know with any certainty which is bigger so the first one will be returned.
+ *
+ * @param x
+ * @param args
+ * @returns
+ */
+function largestPower(x, ...args) {
+    let retval = x;
+    for (const y of args) {
+        if (y.getPower().gt(retval.getPower())) {
+            retval = y;
+        }
+    }
+    return retval;
+}
+function assertPlainVariableAndGetString(x) {
+    if (!x.isVAR()) {
+        throw new errors_1.UnexpectedInputError((0, errors_1.message)('plainVariableExpected', { input: x.text() }));
+    }
+    return x.value;
+}
+function getNumericOrAssumedValue(x) {
+    let retval = undefined;
+    // If it's numeric then we're done
+    if (x.isNUM()) {
+        retval = x;
+    }
+    else {
+        // Check the assumptions
+        const assumedValue = (0, assume_1.getAssumptionFor)(x);
+        // Make sure it's a single value. Since this is used for comparison,
+        // we cannot compare a point to a range.
+        if (assumedValue && assumedValue.isSingleton) {
+            retval = assumedValue.getSingletonValue();
+        }
+    }
+    return retval;
+}

package/output/core/classes/lookupTable/LookupTable.d.ts

@@ -0,0 +1,12 @@
+import type { Pattern } from '../../converters/Pattern';
+import type { Expression } from '../expression/Expression';
+export type TableEntryHandler = (f: Pattern, depth?: number) => Expression | undefined;
+export type TableEntries = Record<string, TableEntryHandler>;
+export declare class LookupTable {
+    private _entries;
+    private addEntry;
+    private get;
+    addEntries(table: TableEntries): void;
+    lookup(pattern: Pattern, depth?: number): Expression | undefined;
+    set(pattern: string, handler: TableEntryHandler): boolean;
+}

package/output/core/classes/lookupTable/LookupTable.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LookupTable = void 0;
+class LookupTable {
+    _entries = new Map();
+    addEntry(pattern, handler) {
+        // Check if there's an existing entry
+        const existingEntry = this._entries.get(pattern);
+        // If not then just add it
+        if (!existingEntry) {
+            this._entries.set(pattern, [handler]);
+        }
+        // Add the handler if there's an existing entry
+        else {
+            existingEntry.push(handler);
+        }
+    }
+    get(pattern) {
+        return this._entries.get(pattern);
+    }
+    addEntries(table) {
+        for (const pattern in table) {
+            // Get the handler in the table
+            const handler = table[pattern];
+            this.addEntry(pattern, handler);
+        }
+    }
+    lookup(pattern, depth) {
+        // Get the handlers
+        const handlers = this.get(pattern.patternString);
+        // console.log('Looking up\n');
+        // console.log(
+        // 	`pattern: ${pattern.patternString}, expression: ${pattern.expression}, handler found: ${handlers ? handlers.length : 'none'}\n`
+        // );
+        if (handlers) {
+            // If there are handlers then try each one until a match is found.
+            for (const handler of handlers) {
+                const result = handler(pattern, depth);
+                if (result) {
+                    return result;
+                }
+            }
+        }
+        return undefined;
+    }
+    set(pattern, handler) {
+        const handlers = this._entries.get(pattern);
+        if (handler) {
+            handlers?.push(handler);
+            return true;
+        }
+        return false;
+    }
+}
+exports.LookupTable = LookupTable;

package/output/core/classes/matrix/Matrix.d.ts

@@ -0,0 +1,227 @@
+import { StructuredEntity } from '../../common/classes/StructuredEntity';
+import { Expression } from '../expression/Expression';
+import { MATRIX } from '../parser/constants';
+import { Vector } from '../vector/Vector';
+import type { StructuredEntityType, ParserEntity, NerdamerInput } from '../../types';
+import type { ParserValuesObject } from '../parser/types';
+/**
+ * A rectangular two-dimensional matrix of scalar {@link Expression} elements.
+ *
+ * @remarks
+ * Construction validates that all nonempty rows have the same length and
+ * converts every entry to an Expression; nested parser aggregates are not
+ * matrix elements. Existing Expression entries are retained, so use
+ * {@link copy} when independent element objects are required. `copy`,
+ * {@link evaluate}, and {@link expand} return deep independent matrices.
+ *
+ * Addition, subtraction, and division remain element-wise. {@link times}
+ * implements scalar scaling, matrix multiplication, and matrix-vector multiplication,
+ * while {@link pow} implements integer matrix powers. Scalar and matrix products return
+ * new Matrices; a matrix-vector product returns a new Vector. {@link each}, {@link set},
+ * and parser assignment mutate this matrix. `each` may also be used for observation by
+ * returning nothing; use {@link forEach} when no transformation is intended.
+ *
+ * Direct `get`/`set` indices are zero-based. The compatibility accessor
+ * {@link e} and the {@link row}/{@link col} helpers are one-based. Matrix
+ * comparisons are component-wise predicates, not a total or lexicographic
+ * ordering; a type or dimension mismatch compares false.
+ */
+export declare class Matrix extends StructuredEntity<Matrix, Vector> {
+    /**
+     * Number of row swaps performed during the last toRightTriangular call.
+     * Used internally by determinant() to correct the sign.
+     */
+    private _rowSwaps;
+    dataType: typeof MATRIX;
+    elements: Expression[][];
+    isEnumerable: boolean;
+    precision?: number | undefined;
+    /**
+     * Creates a matrix from array or Vector rows.
+     *
+     * @param elements - Rows containing values convertible to scalar Expressions.
+     * @throws {@link core!MathError} If nonempty rows have different lengths.
+     * @throws {@link core!UnexpectedDataType} If an entry cannot be converted to an
+     * Expression.
+     */
+    constructor(...elements: (NerdamerInput[] | Vector)[]);
+    /** Creates a matrix whose cells are independent copies of `value`. */
+    static fill(rows: number, cols: number, value: Expression): Matrix;
+    /** Creates the `n` by `n` identity matrix. */
+    static identity(n: number): Matrix;
+    static isMatrix(obj: unknown): obj is Matrix;
+    /** Creates a matrix filled with symbolic zeros. */
+    static zeroMatrix(rows: number, cols: number): Matrix;
+    /**
+     * Returns a row at the given zero-based index as a Vector.
+     * Used by the parser for bracket indexing, e.g. matrix[0] returns the first row.
+     * This enables chained indexing: matrix[0][1] returns the element at row 0, col 1.
+     *
+     * @param indices Zero-based indices (after INDEX_BASE adjustment).
+     *   Single index [i] returns row i as a Vector.
+     *   Two indices [i, j] returns the element at row i, col j.
+     * @returns A copied row Vector for one index, or the stored Expression for two.
+     * @throws {@link core!MathError} If either index is out of bounds.
+     */
+    __get__(indices: number[]): ParserEntity;
+    /**
+     * Sets a zero-based cell or replaces an entire row.
+     *   [i, j] sets the element at row i, col j.
+     *   [i] requires a Vector whose length matches the matrix column count.
+     *
+     * @param indices Zero-based indices
+     * @param value The value to set
+     * @throws {@link core!UnexpectedDataType} If a full-row assignment does not receive a Vector.
+     * @throws {@link core!MathError} If an index is out of bounds or a replacement row has the wrong length.
+     */
+    __set__(indices: number[] | string, value: ParserEntity): void;
+    /**
+     * Returns the horizontal augmentation `[this | matrix]` without mutating either input.
+     *
+     * @throws {@link core!MathError} If the row counts differ.
+     */
+    augment(matrix: Matrix): Matrix;
+    canMultiplyFromLeft(M: Matrix): boolean;
+    col(n: number): Matrix;
+    cols(): number;
+    /** Copies the matrix and every Expression element. */
+    copy(): Matrix;
+    /**
+     * Computes the determinant by triangular elimination.
+     *
+     * The determinant of the empty matrix is one.
+     *
+     * @throws {@link core!UnsupportedOperationError} If the matrix is not square.
+     */
+    determinant(): Expression;
+    dimensions(): number[];
+    dimensionsMatch(M: StructuredEntityType): M is Matrix;
+    /**
+     * Divides corresponding entries, or broadcasts a scalar divisor.
+     *
+     * @throws {@link core!DimensionError} If a Matrix divisor has different dimensions.
+     */
+    div(x: NerdamerInput): Matrix;
+    /**
+     * Returns a one-based matrix element for compatibility with the legacy accessor.
+     *
+     * @throws {@link core!MathError} If either index is out of bounds.
+     */
+    e(i: number, j: number): Expression;
+    /**
+     * Visits or replaces every element in row-major order.
+     * Returning `void` leaves the current cell unchanged. Callback row and column
+     * indices are zero-based.
+     */
+    each(fn: (e: Expression, i?: string | number, j?: string | number) => Expression | void): Matrix;
+    eq(M: ParserEntity): boolean;
+    /** Evaluates a copied matrix, resolving symbolic cell access when values are supplied. */
+    evaluate(): Matrix;
+    evaluate(values: ParserValuesObject): ParserEntity;
+    /** Expands a copied matrix, leaving this one unchanged. */
+    expand(): Matrix;
+    /** Visits every cell without changing the matrix. */
+    forEach(callback: (value: Expression, row: number, col: number) => void): void;
+    /**
+     * Returns the stored Expression at a zero-based row and column.
+     *
+     * @throws {@link core!MathError} If either index is out of bounds.
+     */
+    get(row: number, col: number): Expression;
+    gt(M: ParserEntity): boolean;
+    gte(M: ParserEntity): boolean;
+    inspect(): string;
+    /**
+     * Computes an inverse by augmenting with the identity and eliminating rows.
+     *
+     * @returns A new inverse matrix; this matrix is unchanged.
+     * @throws {@link core!UnsupportedOperationError} If the matrix is not square.
+     * @throws {@link core!MathError} If the matrix is singular.
+     */
+    inverse(): Matrix;
+    isSingular(): boolean;
+    isSquare(): boolean;
+    lt(M: ParserEntity): boolean;
+    lte(M: ParserEntity): boolean;
+    /** Returns a new matrix populated by callback results without mutating this matrix. */
+    map(callback: (a: Expression, row?: string | number, col?: string | number) => Expression): Matrix;
+    /**
+     * Subtracts corresponding entries, or broadcasts a scalar subtrahend.
+     *
+     * @throws {@link core!DimensionError} If a Matrix operand has different dimensions.
+     */
+    minus(x: NerdamerInput): Matrix;
+    /** Delegates the public multiplication alias to the Matrix-specific times() method. */
+    multiply(x: Expression): Matrix;
+    multiply(x: Matrix): Matrix;
+    multiply(x: Vector): Vector;
+    multiply(x: ParserEntity): Matrix | Vector;
+    /**
+     * Computes a basis for the nullspace using the same reduced row-echelon form as {@link rref}.
+     *
+     * @remarks
+     * Without `prime`, the basis is computed with exact symbolic Expression arithmetic. When
+     * `prime` is supplied, the existing modular arithmetic path is preserved and basis entries
+     * are reduced modulo that value. Each free column contributes one basis vector, ordered by
+     * increasing free-column index. A full-column-rank matrix therefore returns an empty basis.
+     *
+     * @param prime - Optional modulus for finite-field nullspace arithmetic.
+     * @returns Basis vectors as independent Expression arrays ordered by matrix column.
+     */
+    nullspace(prime?: string | number | Expression): Expression[][];
+    /**
+     * Adds corresponding entries, or broadcasts a scalar addend.
+     *
+     * @throws {@link core!DimensionError} If a Matrix operand has different dimensions.
+     */
+    plus(x: NerdamerInput): Matrix;
+    /**
+     * Raises this matrix to an integer power without mutating it.
+     *
+     * Positive powers use matrix multiplication, zero returns the identity, and
+     * negative powers use the matrix inverse. A rectangular matrix is accepted only
+     * for the identity power `1`; all other matrix powers require a square matrix.
+     *
+     * @throws {@link core!UnsupportedOperationError} If the exponent is not an integer,
+     * or if a nontrivial power is requested for a rectangular matrix.
+     * @throws {@link core!MathError} If a negative power requires the inverse of a singular matrix.
+     */
+    pow(x: NerdamerInput): Matrix;
+    rank(): number;
+    row(n: number): Matrix;
+    rows(): number;
+    /**
+     * Returns reduced row-echelon form without mutating this matrix.
+     *
+     * When `prime` is supplied, pivot arithmetic is performed modulo that value.
+     * Otherwise pivots and zero rows are determined by exact Expression equality.
+     */
+    rref(prime?: string | number | Expression): Matrix;
+    /** Sets a zero-based cell after converting `value` to an Expression. */
+    set(row: number, col: number, value: ParserEntity): this;
+    text(): string;
+    /**
+     * Returns scalar multiplication, the matrix product `this * M`, or the
+     * matrix-vector product `this * v`.
+     *
+     * @throws {@link core!MathError} If matrix or vector dimensions are incompatible.
+     * @throws {@link core!UnsupportedOperationError} If the operand is not a supported
+     * scalar, Matrix, or Vector.
+     */
+    times(M: Expression): Matrix;
+    times(M: Matrix): Matrix;
+    times(M: Vector): Vector;
+    times(M: ParserEntity): Matrix | Vector;
+    /** Returns a row-echelon copy produced by forward elimination and row swaps. */
+    toRightTriangular(): Matrix;
+    toUpperTriangular(): Matrix;
+    /**
+     * Returns the sum of the main diagonal. The empty matrix has trace zero.
+     * @throws {@link core!MathError} If the matrix is not square.
+     */
+    trace(): Expression;
+    /** Returns a transposed matrix. Existing elements are normalized by the constructor. */
+    transpose(): Matrix;
+    /** Returns elements as a column-major Vector. */
+    unroll(): Vector;
+}