nerdamer 1.1.13 → 2.0.0-rc.1

package/output/core/functions/subst.js

@@ -0,0 +1,498 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.prodSubst = prodSubst;
+exports.sumSubst = sumSubst;
+exports.subst = subst;
+exports.getU = getU;
+exports.uSub = uSub;
+exports.rewriteRadicals = rewriteRadicals;
+exports.subRadicals = subRadicals;
+exports.uUnSub = uUnSub;
+exports.uSubConstants = uSubConstants;
+exports.uSubFN = uSubFN;
+exports.uSubEXP = uSubEXP;
+const Expression_1 = require("../classes/expression/Expression");
+const shortcuts_1 = require("../classes/expression/shortcuts");
+const utils_1 = require("../classes/expression/utils");
+const helpers_1 = require("../classes/parser/helpers");
+const Settings_1 = require("../Settings");
+function prodSubst(expression, value, withValue, includeNumeric) {
+    let retval;
+    /**
+     * The overview:
+     * We loop through the elements of each. The multiplier of the the power (meaning the power being substituted divided by the existing),
+     * has to match for each of the elements. Additionally, that ratio has to be an integer. If neither criteria is satisfied, then
+     * we exit and return the expression.
+     */
+    if (expression.isProduct()) {
+        if (value.isProduct()) {
+            // First check the multipliers. This has to be an integer
+            const m = expression.getMultiplier().div(value.getMultiplier());
+            if (!m.isInteger() && !Settings_1.Settings.ALLOW_RAT_SUBS) {
+                retval = new Expression_1.Expression(expression);
+            }
+            else {
+                let power;
+                // Get the expression elements
+                let expressionElements = expression.elementsArray();
+                // Get the elements of the value being subbed.
+                const valueElements = value.elementsArray();
+                // We'll loop through the elements of the value to be subbed
+                // Create an array of the items not substituted
+                // A flag to keep track if a substitution occurred
+                let success = false;
+                // The array of the elements encountered
+                let filtered = [];
+                // Keep track of the number of element substituted
+                let remaining = valueElements.length;
+                while (valueElements.length > 0) {
+                    // Reset the filtered array
+                    filtered = [];
+                    // Start with the assumption that no substitution occurred
+                    success = false;
+                    const vc = valueElements[valueElements.length - 1];
+                    valueElements.pop();
+                    for (const ec of expressionElements) {
+                        // First find the value
+                        if (ec.value === vc.value) {
+                            // Then get the ratio of their powers
+                            const pr = ec.getPower().div(vc.getPower());
+                            // If the power ratio is undefined then we're at the first value. So just set the value to this value
+                            if (power === undefined) {
+                                power = pr;
+                            }
+                            // If the ratio of the powers is not an integer then we're done and exit or
+                            // If the power ratios don't match then we're done. For instance if we're substituting x*y in x^2*y,
+                            // the ratio will be (2, 1) and it's therefore not a valid substitution
+                            if ((!pr.isInteger() || !pr.eq(power)) && !ec.isEXP()) {
+                                break;
+                            }
+                            success = true;
+                            remaining--;
+                        }
+                        else {
+                            filtered.push(subst(ec, value, withValue, includeNumeric));
+                        }
+                    }
+                    // If any substitution failed then we're done and exit
+                    if (!success) {
+                        break;
+                    }
+                    // Update the list with the new one which doesn't have the substituted element
+                    expressionElements = filtered;
+                }
+                // If all the elements weren't substituted then return the original expression
+                if (remaining !== 0 || power === undefined) {
+                    retval = (0, utils_1.product)(...expression.elementsArray(true).map(x => {
+                        return subst(x, value, withValue, includeNumeric);
+                    })).pow(expression.getPower());
+                }
+                // Otherwise add the substituted value to the filtered set and return the sum product
+                else {
+                    filtered.push(withValue.pow(power));
+                    retval = (0, utils_1.product)(...filtered);
+                    // Transfer the power and multiplier
+                    retval.multiplier = retval.getMultiplier().times(m);
+                }
+                // Make substitutions in the power
+                retval = retval.pow(subst(expression.getPower(), value, withValue, includeNumeric));
+            }
+        }
+        else {
+            // Convert it to an array, substitute out each element, convert it back to a product
+            // but make sure to put back the expression multiplier.
+            retval = (0, utils_1.product)(...expression.elementsArray(true).map(x => {
+                return subst(x, value, withValue, includeNumeric);
+            })).pow(expression.getPower());
+        }
+    }
+    return retval || expression;
+}
+/**
+ * Performs a substitution on a sum
+ *
+ * @param expression
+ * @param value
+ * @param withValue
+ * @returns
+ */
+function sumSubst(expression, value, withValue, includeNumeric) {
+    let retval;
+    if (!expression.isSum()) {
+        return expression;
+    }
+    // Put back later (do NOT mutate fields directly)
+    const exprPow = expression.getPower();
+    const exprMul = expression.getMultiplier();
+    if (value.isSum()) {
+        // Work on raw elements first (do not subst yet)
+        const remaining = expression.elementsArray().slice();
+        // Decide how to treat the value being substituted
+        const valueElements = value.isSum() && value.isLinear() ? value.elementsArray() : [value.toUnitMultiplier()];
+        const matched = [];
+        let m;
+        for (const vc of valueElements) {
+            // Find exactly one matching term in the remaining pool
+            const idx = remaining.findIndex(ec => ec.value === vc.value && ec.getPower().eq(vc.getPower()));
+            if (idx === -1) {
+                // Fail: cannot substitute, so just recurse normally on the whole sum
+                const out = (0, utils_1.sum)(...expression
+                    .elementsArray()
+                    .map(x => subst(x, value, withValue, includeNumeric)));
+                return out.pow(exprPow).times(exprMul);
+            }
+            const ec = remaining[idx];
+            remaining.splice(idx, 1);
+            matched.push(ec);
+            const tm = ec.div(vc);
+            if (!m) {
+                m = tm;
+            }
+            else if (!tm.eq(m)) {
+                // Ratio mismatch: fail -> normal recursion
+                const out = (0, utils_1.sum)(...expression
+                    .elementsArray()
+                    .map(x => subst(x, value, withValue, includeNumeric)));
+                return out.pow(exprPow).times(exprMul);
+            }
+        }
+        // Success: substitute the whole group by withValue * m,
+        // and recurse into the remaining terms (important!)
+        const substituted = withValue.times(m || (0, shortcuts_1.one)());
+        const rewrittenTerms = remaining.map(t => subst(t, value, withValue, includeNumeric));
+        rewrittenTerms.push(substituted);
+        retval = (0, utils_1.sum)(...rewrittenTerms)
+            .pow(exprPow)
+            .times(exprMul);
+    }
+    else {
+        // Original behavior for non-sum value: recurse per term
+        retval = (0, utils_1.sum)(...expression.elementsArray().map(x => subst(x, value, withValue, includeNumeric)))
+            .pow(exprPow)
+            .times(exprMul);
+    }
+    return retval || expression;
+}
+/**
+ * Replaces a value with another using the existing Expression tree.
+ *
+ * @param expression The expression being used to perform the substitution
+ * @param value The value currently in the expression
+ * @param withValue The value that the substitution is being replaced with
+ */
+function subst(expression, value, withValue, includeNumeric = false) {
+    expression = Expression_1.Expression.create(expression);
+    value = Expression_1.Expression.create(value);
+    withValue = Expression_1.Expression.create(withValue);
+    let retval;
+    // If the value to be substituted is a sum or product but the value does not contain
+    // any then we're done. Also, we don't consider a number a proper LHS value.
+    if (expression.isNUM() && !includeNumeric) {
+        retval = expression;
+    }
+    // We next move to the most obvious substitution which is the expression is equal to the value
+    else if (expression.eq(value)) {
+        retval = withValue;
+    }
+    // A variable can carry its coefficient and numeric power on the node itself. Replace
+    // that base directly so a simple substitution stays within the existing expression tree.
+    else if (value.isVAR() &&
+        value.getPower().isOne() &&
+        value.getMultiplier().isOne() &&
+        expression.isVAR() &&
+        expression.value === value.value) {
+        const exponent = subst(expression.getPower(), value, withValue, includeNumeric);
+        const multiplier = expression.getMultiplier();
+        if (exponent.isNUM() && exponent.getMultiplier().isNegative()) {
+            retval = (0, shortcuts_1.one)().div(withValue.copy().pow(exponent.abs()));
+        }
+        else {
+            retval = withValue.copy().pow(exponent);
+        }
+        if (!multiplier.isOne()) {
+            retval = retval.times(multiplier);
+        }
+    }
+    else if (expression.isProduct()) {
+        retval = prodSubst(expression, value, withValue, includeNumeric);
+    }
+    // The power has to be one because we cannot swap terms otherwise
+    // TODO: SUM with nested GRP
+    else if (expression.isSum()) {
+        // Perform a simple sum factor on the expression so we can detect the t+1 in expression like a*t+a.
+        // This should not affect a substitution for the a*t since products are checked first.
+        // expression = sumFactor(expression);
+        // If it was factored then it belongs to the product substitution
+        retval = sumSubst(expression, value, withValue, includeNumeric);
+    }
+    else if (expression.isFunction()) {
+        if (expression.value === value.value) {
+            retval = new Expression_1.Expression(withValue);
+        }
+        else {
+            retval = Expression_1.Expression.Function(expression.name);
+            retval.args = expression.getArguments().map((x) => {
+                return subst(x, value, withValue, includeNumeric);
+            });
+            // Update the value to reflect the new argument(s)
+            retval.updateValue();
+        }
+        retval = retval.pow(expression.getPower()).times(expression.getMultiplier());
+    }
+    else if (expression.isEXP()) {
+        const base = subst(expression.getBase(), value, withValue, true);
+        const exp = subst(expression.getPower(), value, withValue, includeNumeric);
+        retval = base.pow(exp).times(expression.getMultiplier());
+    }
+    return retval || expression;
+}
+function getU(x, map) {
+    x = Expression_1.Expression.create(x);
+    const variables = x.variables();
+    map ??= {};
+    let count = 0;
+    let u;
+    do {
+        u = `u${count}`;
+        count++;
+    } while (variables.includes(u) || u in map);
+    return u;
+}
+/**
+ * Replaces one repeated sub-expression with a generated `uN` symbol.
+ *
+ * The generated symbol is chosen so it does not collide with variables already present
+ * in the expression or substitution map. Pass the returned map to later calls when
+ * several substitutions should share one namespace, then use {@link uUnSub} to restore
+ * the original expressions.
+ *
+ * @param x - Expression in which the substitution will occur.
+ * @param value - Sub-expression to replace.
+ * @param map - Existing substitution map to extend.
+ * @returns The substituted expression and the updated substitution map.
+ *
+ * @example
+ * ```ts
+ * const [substituted, map] = uSub('cos(x)^2+cos(x)+1', 'cos(x)');
+ * substituted.text({ sort: true }); // "u0^2+u0+1"
+ * uUnSub(substituted, map).eq('cos(x)^2+cos(x)+1'); // true
+ * ```
+ */
+function uSub(x, value, map) {
+    // Create the map object is one wasn't provided
+    map ??= {};
+    x = Expression_1.Expression.create(x);
+    value = Expression_1.Expression.create(value);
+    // Get a suitable u
+    const u = getU(x, map);
+    // Perform the substitution
+    const subbed = subst(x, value, (0, helpers_1._)(u));
+    // Mark it as updated
+    if (!subbed.eq(x)) {
+        map[u] = value;
+    }
+    return [subbed, map];
+}
+/**
+ * Rewrites powers of one variable through a radical substitution without
+ * sending the replacement back through generic nested-power simplification.
+ * The caller supplies the substitution degree, so fractional powers become
+ * exact integer powers of the replacement variable when possible.
+ */
+function rewriteRadicals(e, variable, newVar, n) {
+    let retval = e;
+    if ((e.isVAR() || e.isEXP()) && e.value === variable) {
+        const m = e.getMultiplier();
+        const p = e.getPower();
+        if (p.isNUM()) {
+            const r = p.getMultiplier();
+            const newNum = n * r.numerator;
+            const newDen = r.denominator < 0n ? -r.denominator : r.denominator;
+            if (newNum % newDen !== 0n) {
+                retval = Expression_1.Expression.fromRational(m).times(newVar.pow(`${newNum}/${newDen}`));
+            }
+            else {
+                const intPower = newNum / newDen;
+                retval = Expression_1.Expression.fromRational(m).times(newVar.pow(intPower.toString()));
+            }
+        }
+        else {
+            retval = Expression_1.Expression.fromRational(m).times(newVar.pow(p.times(n.toString())));
+        }
+    }
+    else if (e.isEXP()) {
+        const base = rewriteRadicals(e.getBase(), variable, newVar, n);
+        const power = rewriteRadicals(e.getPower(), variable, newVar, n);
+        retval = Expression_1.Expression.toEXP(base, power);
+        if (!e.getMultiplier().isOne()) {
+            retval = retval.times(Expression_1.Expression.fromRational(e.getMultiplier()));
+        }
+    }
+    else if (e.isSum()) {
+        const m = e.getMultiplier();
+        const p = e.getPower();
+        retval = (0, shortcuts_1.zero)();
+        for (const term of e.elementsArray()) {
+            retval = retval.plus(rewriteRadicals(term, variable, newVar, n));
+        }
+        if (!p.isOne()) {
+            retval = retval.pow(p);
+        }
+        if (!m.isOne()) {
+            retval = retval.times(Expression_1.Expression.fromRational(m));
+        }
+    }
+    else if (e.isProduct()) {
+        const m = e.getMultiplier();
+        const p = e.getPower();
+        retval = (0, shortcuts_1.one)();
+        for (const element of e.elementsArray()) {
+            retval = retval.times(rewriteRadicals(element, variable, newVar, n));
+        }
+        if (!p.isOne()) {
+            retval = retval.pow(p);
+        }
+        if (!m.isOne()) {
+            retval = retval.times(Expression_1.Expression.fromRational(m));
+        }
+    }
+    else if (e.isFunction()) {
+        const args = e.getArguments();
+        if (args.length > 0) {
+            const newArgs = args.map(a => rewriteRadicals(a, variable, newVar, n));
+            retval = Expression_1.Expression.toFunction(e.name, newArgs);
+            retval.multiplier = e.getMultiplier().copy();
+            retval = Expression_1.Expression.setPower(retval, e.getPower());
+        }
+    }
+    return retval;
+}
+function subRadicals(x) {
+    let num = x.getNumerator();
+    let den = x.getDenominator();
+    const subs = {};
+    // The map of uSubstitutions
+    const map = {};
+    // A record to track which variables already map to which u
+    const references = {};
+    function collectPowers(exp) {
+        const elements = exp.elementsArray();
+        // We're going to loop through the elements and look for radicals
+        // Like variables are just going to get their combined power so
+        // a^(1/n)+a^(1/m) will just be mapped to a: n*m
+        for (const e of elements) {
+            if (e.hasRadical()) {
+                // Don't touch numbers.
+                if (e.isNUM()) {
+                    continue;
+                }
+                const n = e.getPower().getDenominator();
+                const v = e.value;
+                const existing = subs[v];
+                // Multiply the power on the existing if one already exists
+                subs[v] = existing ? subs[v].times(n) : n;
+            }
+        }
+    }
+    function makeSubstitutions(exp) {
+        // Make the substitutions
+        for (const y in subs) {
+            const u = references[y] ? references[y] : getU(exp, map);
+            // Map the u to the variable
+            references[y] = u;
+            const pow = subs[y];
+            // Make the substitution
+            const n = pow.getMultiplier().numerator;
+            map[u] = Expression_1.Expression.create(y).pow(pow.invert());
+            exp = rewriteRadicals(exp, y, Expression_1.Expression.create(u), n);
+        }
+        return exp;
+    }
+    collectPowers(num);
+    collectPowers(den);
+    num = makeSubstitutions(num);
+    den = makeSubstitutions(den);
+    return [num.div(den), map];
+}
+/**
+ * Restores substitutions produced by {@link uSub}.
+ *
+ * @param expression - Expression containing generated substitution symbols.
+ * @param map - Map returned by one or more u-substitution calls.
+ * @returns The expression after restoring every mapped value.
+ */
+function uUnSub(expression, map) {
+    // Substitute back in all the elements. Remember that the order is not preserved.
+    for (const u in map) {
+        const value = map[u];
+        expression = subst(expression, (0, helpers_1._)(u), value);
+    }
+    return expression;
+}
+/**
+ * Performs a u-substitution of all the constants in the expression.
+ *
+ * @param expression
+ * @param map
+ * @returns
+ */
+function uSubConstants(expression, map) {
+    map ??= {};
+    const constants = new Set();
+    // forEveryElement returns immediately for a VAR root. Check the root first so standalone
+    // mathematical constants and their powers are promoted just like the same constants nested
+    // inside sums and products.
+    if (expression.isVAR() && (expression.isConstant() || expression.isI())) {
+        constants.add(expression.value);
+    }
+    expression.forEveryElement(e => {
+        // The imaginary unit is a mathematical constant, but isConstant() only recognizes parser
+        // constants such as pi and e. Promote i here as well so polynomial factorization does not
+        // treat it as an ordinary polynomial variable.
+        if (e.isVAR() && (e.isConstant() || e.isI())) {
+            constants.add(e.value);
+        }
+        return e;
+    });
+    for (const c of constants) {
+        [expression, map] = uSub(expression, (0, helpers_1._)(c), map);
+    }
+    return [expression, map];
+}
+/**
+ * Performs a u-substitution on all the functions in the expression
+ *
+ * @param expression
+ * @param map
+ * @returns
+ */
+function uSubFN(expression, map) {
+    // Create the map object if none was provided
+    map ??= {};
+    // We get all the functions in the expression. Next we'll u-substitute each one.
+    expression.functions(undefined, true).forEach(fn => {
+        [expression, map] = uSub(expression, (0, helpers_1._)(fn), map);
+    });
+    return [expression, map];
+}
+/**
+ * Performs a u-substitution on all the exponential functions in the expression
+ * @param expression
+ * @param map
+ * @returns
+ */
+function uSubEXP(expression, map) {
+    map ??= {};
+    const elementSet = new Set();
+    // Create a list of all the EXP function
+    expression.forEveryElement(e => {
+        if (e.isEXP()) {
+            elementSet.add(e.toUnitMultiplier().text());
+        }
+        return e;
+    });
+    for (const x of elementSet) {
+        [expression, map] = uSub(expression, (0, helpers_1._)(x), map);
+    }
+    return [expression, map];
+}

package/output/core/functions/utils.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Removes duplicates from an array
+ *
+ * @param arr
+ * @returns
+ */
+export declare function arrayUnique<T>(arr: T[]): T[];
+/**
+ * Similar to concat but only adds elements if they're unique
+ *
+ * @param fromArray The array being added from
+ * @param toArray The array being added to
+ */
+export declare function arrayAddUnique<T>(fromArray: T[], toArray: T[]): T[];
+/**
+ * Checks to see if the inverse of decimal is within a max bound.
+ * For example: given the number 0.01 it will return true for 0 - 100
+ *
+ * @param n
+ * @param max
+ * @returns
+ */
+export declare function checkDecimal(n: number, max: number): boolean;
+export declare function isSorted<T>(arr: T[]): boolean;

package/output/core/functions/utils.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.arrayUnique = arrayUnique;
+exports.arrayAddUnique = arrayAddUnique;
+exports.checkDecimal = checkDecimal;
+exports.isSorted = isSorted;
+/**
+ * Removes duplicates from an array
+ *
+ * @param arr
+ * @returns
+ */
+function arrayUnique(arr) {
+    return [...new Set(arr)];
+}
+/**
+ * Similar to concat but only adds elements if they're unique
+ *
+ * @param fromArray The array being added from
+ * @param toArray The array being added to
+ */
+function arrayAddUnique(fromArray, toArray) {
+    for (const x of fromArray) {
+        if (!toArray.includes(x)) {
+            toArray.push(x);
+        }
+    }
+    return toArray;
+}
+/**
+ * Checks to see if the inverse of decimal is within a max bound.
+ * For example: given the number 0.01 it will return true for 0 - 100
+ *
+ * @param n
+ * @param max
+ * @returns
+ */
+function checkDecimal(n, max) {
+    return 1 / (n % 1) <= max;
+}
+function isSorted(arr) {
+    if (arr.length <= 1) {
+        return true; // An empty array or an array with one element is considered sorted
+    }
+    for (let i = 1; i < arr.length; i++) {
+        if (arr[i - 1] > arr[i]) {
+            return false; // If any element is smaller than the previous one, the array is not sorted
+        }
+    }
+    return true; // If the loop completes without returning false, the array is sorted
+}

package/output/core/types.d.ts

@@ -0,0 +1,48 @@
+import type { Collection } from './classes/collection/Collection';
+import type { Dictionary } from './classes/dictionary/Dictionary';
+import type { Equation } from './classes/equation/Equation';
+import type { Expression } from './classes/expression/Expression';
+import type { Matrix } from './classes/matrix/Matrix';
+import type { Rational } from './classes/rational/Rational';
+import type { ValuesSet } from './classes/valuesSet/ValuesSet';
+import type { Vector } from './classes/vector/Vector';
+import type Decimal from 'decimal.js';
+/**
+ * Values accepted by Nerdamer's expression-oriented parsing APIs.
+ *
+ * @remarks
+ * Strings are interpreted as parser notation. Primitive numbers, `bigint`, and
+ * `Decimal` instances are converted through their textual form; {@link Rational}
+ * values are converted directly, and existing {@link Expression} values retain their
+ * symbolic structure.
+ * An existing expression may be reused by identity by APIs such as
+ * {@link Expression.create}; request a copy at the receiving API when independent
+ * mutation is required.
+ */
+export type ExpressionInput = number | string | Rational | Expression | bigint | Decimal;
+/**
+ * Values accepted across Nerdamer's root API and direct object model.
+ *
+ * This extends {@link ExpressionInput} with the structured parser entities and
+ * equations that can be passed back into supported operations. Individual functions
+ * may accept a narrower subset and should document that restriction locally.
+ */
+export type NerdamerInput = ExpressionInput | Vector | ValuesSet | Collection | Matrix | Dictionary | Equation;
+/**
+ * Values that can be produced by Nerdamer's parser.
+ *
+ * @remarks
+ * Equality syntax produces an {@link Equation}; bracket, set, matrix, and dictionary
+ * syntax can produce the corresponding structured entity instead of an
+ * {@link Expression}. Callers of the general parser should therefore narrow this union
+ * before using expression-specific methods.
+ */
+export type ParserEntity = Expression | Vector | ValuesSet | Collection | Matrix | Equation | Dictionary;
+/**
+ * Structured parser entities that participate in aggregate operations.
+ *
+ * The union describes Nerdamer's supported matrix, vector, ordered collection, and
+ * keyed dictionary containers. It excludes value sets and equations, whose semantics
+ * are not ordinary elementwise structured operations.
+ */
+export type StructuredEntityType = Matrix | Vector | Collection | Dictionary;

package/output/core/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });