nerdamer 1.1.13 → 2.0.0-rc.2

package/output/algebra/partfrac.js

@@ -0,0 +1,365 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.partfrac = partfrac;
+const Expression_1 = require("../core/classes/expression/Expression");
+const shortcuts_1 = require("../core/classes/expression/shortcuts");
+const Matrix_1 = require("../core/classes/matrix/Matrix");
+const Polynomial_1 = require("../core/classes/polynomial/Polynomial");
+const utils_1 = require("../core/classes/polynomial/utils");
+const factor_1 = require("./factor/factor");
+/**
+ * Decomposes a rational expression P(x)/Q(x) into partial fractions.
+ *
+ * @remarks
+ * The routine extracts `P(x)/Q(x)`, performs polynomial long division for an improper
+ * fraction, factors `Q` over the supported exact polynomial domain, and solves the
+ * undetermined coefficients by exact evaluation and row reduction. Each denominator
+ * factor of degree d receives a numerator polynomial of degree less than d, including
+ * repeated factors. A singular coefficient system, a denominator independent of the
+ * selected variable, or a factorization that does not expose a useful decomposition
+ * leaves the original expression unchanged.
+ *
+ * @param x - Rational expression to decompose.
+ * @param variable - Main variable; defaults to the first variable reported by the expression.
+ * @returns A new decomposition when one is found, otherwise the original parsed expression.
+ */
+function partfrac(x, variable) {
+    const expr = Expression_1.Expression.create(x);
+    let result = expr;
+    // Determine the variable
+    const vars = expr.variables();
+    const v = variable ? String(variable) : vars[0];
+    if (v && vars.length > 0) {
+        // Extract numerator and denominator.
+        const { num, den } = extractNumDen(expr, v);
+        // Proceed only if the denominator depends on the variable
+        if (den.hasVariable(v)) {
+            const pNum = new Polynomial_1.Polynomial(num, [v]);
+            const pDen = new Polynomial_1.Polynomial(den, [v]);
+            const degNum = pNum.deg();
+            const degDen = pDen.deg();
+            // Step 1: If improper fraction, do polynomial long division
+            let polyPart = (0, shortcuts_1.zero)();
+            let remainder = num;
+            if (degNum >= degDen) {
+                const [quotient, rem] = (0, utils_1.divide)(num, den);
+                polyPart = quotient;
+                remainder = rem;
+            }
+            if (Expression_1.Expression.create(remainder).isZero()) {
+                // Remainder is zero — the expression is a polynomial
+                result = polyPart;
+            }
+            else if (degDen <= 1) {
+                // Denominator is linear or constant — no further decomposition possible.
+                // If we performed long division, return polyPart + remainder/den.
+                if (!polyPart.isZero()) {
+                    result = polyPart.plus(remainder.div(den));
+                }
+            }
+            else {
+                // Step 2: Factor the denominator
+                const factors = (0, factor_1.polyFactorExpressions)(den);
+                const factorList = collectFactors(factors, v);
+                // Only decompose if factoring produced multiple factors or a repeated factor
+                const canDecompose = factorList.length > 1 || (factorList.length === 1 && factorList[0].power > 1);
+                if (canDecompose) {
+                    // Step 3: Set up and solve partial fractions for remainder/den
+                    const decomposition = decompose(remainder, den, factorList, v);
+                    if (decomposition !== undefined) {
+                        result = polyPart.isZero() ? decomposition : polyPart.plus(decomposition);
+                    }
+                }
+            }
+        }
+    }
+    // A successful decomposition is mathematically equal to its input by definition.
+    // Use canonical text here to detect an unchanged shape rather than semantic equality.
+    return result.text() === expr.text() ? expr : result;
+}
+/**
+ * Extracts the numerator and denominator from an expression.
+ * For P/Q, returns { num: P, den: Q }.
+ *
+ * Rational expressions are typically stored as products where denominator
+ * factors have negative powers: P * Q^(-1).
+ */
+function extractNumDen(expr, _v) {
+    // Use getNumerator/getDenominator if available
+    try {
+        const num = expr.getNumerator();
+        const den = expr.getDenominator();
+        if (den && !den.isOne()) {
+            return { num, den };
+        }
+    }
+    catch {
+        // Fall through to manual extraction
+    }
+    // Manual extraction: examine the product structure
+    // If the expression is a product, separate positive-power and negative-power factors
+    if (expr.isProduct()) {
+        let num = (0, shortcuts_1.one)();
+        let den = (0, shortcuts_1.one)();
+        for (const element of expr.elementsArray()) {
+            if (element.getPower().isNegative()) {
+                // Negative power → denominator factor
+                den = den.times(element.invert());
+            }
+            else {
+                num = num.times(element);
+            }
+        }
+        // Apply the overall multiplier
+        num = num.times(Expression_1.Expression.fromRational(expr.getMultiplier()));
+        return { num, den };
+    }
+    // Not a product — check if it has a negative power overall
+    if (expr.getPower().sign() === -1) {
+        return { num: Expression_1.Expression.fromRational(expr.getMultiplier()), den: expr.invert() };
+    }
+    // No denominator
+    return { num: expr, den: (0, shortcuts_1.one)() };
+}
+/**
+ * Collects factors from the factor() result, grouping repeated factors.
+ * Extracts embedded powers from expressions like (x-1)^3 so that the
+ * base (x-1) is stored with degree 1 and power 3.
+ */
+function collectFactors(factors, v) {
+    const result = [];
+    const seen = new Map(); // text → index in result
+    for (const factor of factors) {
+        let f = factor;
+        // Skip constant factors (no variable)
+        if (!f.hasVariable(v)) {
+            continue;
+        }
+        // Extract embedded power from the expression (e.g., (x-1)^3 → base=(x-1), power=3)
+        let expPower = 1;
+        const p = f.getPower();
+        if (p.isInteger()) {
+            const n = Number(p.getNumerator());
+            if (n > 1) {
+                expPower = n;
+                f = f.getBase();
+            }
+        }
+        const key = f.text();
+        const deg = new Polynomial_1.Polynomial(f, [v]).deg();
+        if (seen.has(key)) {
+            // Repeated factor — accumulate power
+            result[seen.get(key)].power += expPower;
+        }
+        else {
+            seen.set(key, result.length);
+            result.push({ expr: f, power: expPower, degree: deg });
+        }
+    }
+    return result;
+}
+/**
+ * Decomposes remainder/den into partial fractions given the factored denominator.
+ *
+ * For each factor f(x)^k of degree d, the numerator at every power level is
+ * a polynomial of degree less than d. For example, a cubic factor receives
+ * A*x^2+B*x+C over each repeated power of that factor.
+ *
+ * Uses evaluation at strategic points to solve for coefficients.
+ */
+function decompose(numerator, denominator, factors, v) {
+    // Build the list of partial fraction terms and count unknowns.
+    // A factor of degree d contributes d numerator coefficients at each power level.
+    const terms = [];
+    let totalUnknowns = 0;
+    for (const f of factors) {
+        for (let k = 1; k <= f.power; k++) {
+            terms.push({
+                factor: f.expr,
+                power: k,
+                unknownIndex: totalUnknowns,
+                numUnknowns: f.degree,
+            });
+            totalUnknowns += f.degree;
+        }
+    }
+    // We need to solve: P(x)/Q(x) = Σ terms
+    // Multiply both sides by Q(x):
+    // P(x) = Σ (coefficients_i × Q(x) / factor_i^power_i)
+    //
+    // Strategy: evaluate at `totalUnknowns` distinct values of x to get a linear system,
+    // then solve it.
+    // Collect evaluation points: roots of linear factors + additional integer points
+    const evalPoints = [];
+    for (const f of factors) {
+        if (f.degree === 1) {
+            // Linear factor ax + b: root is x = -b/a
+            const root = findLinearRoot(f.expr, v);
+            if (root !== undefined) {
+                evalPoints.push(root);
+            }
+        }
+    }
+    // Add additional integer points to get enough equations
+    let pointVal = 0;
+    while (evalPoints.length < totalUnknowns) {
+        const candidate = Expression_1.Expression.Number(pointVal);
+        // Make sure this isn't a root of the denominator (would give division by zero)
+        const denAtPoint = evaluateAt(denominator, v, candidate);
+        if (!denAtPoint.isZero()) {
+            // Also make sure it's not already in our list
+            const isDuplicate = evalPoints.some(p => p.eq(candidate));
+            if (!isDuplicate) {
+                evalPoints.push(candidate);
+            }
+        }
+        pointVal = pointVal <= 0 ? -pointVal + 1 : -pointVal;
+    }
+    // Build and solve the linear system by evaluation.
+    // For each eval point xᵢ:
+    //   P(xᵢ) = Σⱼ unknowns_j × basisⱼ(xᵢ)
+    // where basisⱼ(x) is what multiplies the j-th unknown after clearing denominators.
+    const rows = [];
+    const rhs = [];
+    const cofactors = terms.map(term => computeCofactor(denominator, term.factor, term.power));
+    for (let i = 0; i < totalUnknowns; i++) {
+        const x = evalPoints[i];
+        const numVal = evaluateAt(numerator, v, x);
+        rhs.push(numVal);
+        const row = [];
+        for (let j = 0; j < terms.length; j++) {
+            const term = terms[j];
+            // The basis for this term: Q(x) / factor^power, evaluated at x.
+            const cofactor = evaluateAt(cofactors[j], v, x);
+            for (let degree = term.numUnknowns - 1; degree >= 0; degree--) {
+                const monomial = degree === 0 ? (0, shortcuts_1.one)() : x.pow(Expression_1.Expression.Number(degree));
+                row.push(monomial.times(cofactor));
+            }
+        }
+        rows.push(row);
+    }
+    // Solve the system
+    const solution = solveLinearSystem(rows, rhs);
+    if (solution === undefined) {
+        return undefined;
+    }
+    // Build the result expression from the solved coefficients
+    let result = (0, shortcuts_1.zero)();
+    const variable = Expression_1.Expression.create(v);
+    for (const term of terms) {
+        const denomPart = term.power === 1 ? term.factor : term.factor.pow(Expression_1.Expression.Number(term.power));
+        let numPart = (0, shortcuts_1.zero)();
+        for (let i = 0; i < term.numUnknowns; i++) {
+            const coefficient = solution[term.unknownIndex + i];
+            const degree = term.numUnknowns - 1 - i;
+            const monomial = degree === 0 ? (0, shortcuts_1.one)() : variable.pow(Expression_1.Expression.Number(degree));
+            numPart = numPart.plus(coefficient.times(monomial));
+        }
+        if (!numPart.isZero()) {
+            result = result.plus(numPart.div(denomPart));
+        }
+    }
+    return result;
+}
+/**
+ * Finds the root of a linear expression ax + b, returning -b/a.
+ */
+function findLinearRoot(expr, v) {
+    // A linear expression ax + b: evaluate at x=0 to get b, at x=1 to get a+b
+    const atZero = evaluateAt(expr, v, (0, shortcuts_1.zero)());
+    const atOne = evaluateAt(expr, v, (0, shortcuts_1.one)());
+    const a = atOne.plus(atZero.times((0, shortcuts_1.minusOne)())); // a = f(1) - f(0)
+    if (a.isZero()) {
+        return undefined;
+    }
+    // root = -b/a = -f(0)/a
+    return atZero.times((0, shortcuts_1.minusOne)()).div(a);
+}
+/**
+ * Evaluates a polynomial expression at a specific rational value of the variable.
+ * Returns the result as an Expression.
+ */
+function evaluateAt(expr, v, value) {
+    return expr.subst(v, value);
+}
+/**
+ * Computes Q(x) / factor(x)^power.
+ * This is the "cofactor" — the part of the denominator that remains after removing this term's factor.
+ */
+function computeCofactor(denominator, fac, power) {
+    // Q / factor^power
+    const facPow = power === 1 ? fac : fac.pow(Expression_1.Expression.Number(power));
+    const [quotient] = (0, utils_1.divide)(denominator, facPow);
+    return quotient;
+}
+/**
+ * Solves a linear system Ax = b using Gaussian elimination with partial pivoting.
+ * Works with Expression arithmetic (exact rational arithmetic).
+ *
+ * @param A The coefficient matrix (array of rows)
+ * @param b The right-hand side vector
+ * @returns The solution vector, or undefined if the system is singular
+ */
+function solveLinearSystem(A, b) {
+    const n = b.length;
+    if (n === 0) {
+        return [];
+    }
+    // This solver is used to recover exact coefficients for partial fractions.
+    // Use Matrix.rref() so we don't duplicate row-reduction logic.
+    // Require a unique solution (square, full-rank). Otherwise return undefined.
+    const A_mat = new Matrix_1.Matrix(...A);
+    const b_col = new Matrix_1.Matrix(...b.map(v => [v]));
+    const aug = A_mat.augment(b_col).rref();
+    const rows = aug.rows();
+    const cols = aug.cols();
+    const unknowns = cols - 1;
+    if (rows !== n || unknowns !== n) {
+        return undefined;
+    }
+    // Inconsistency: [0 ... 0 | nonzero]
+    for (let i = 0; i < rows; i++) {
+        let allZero = true;
+        for (let j = 0; j < unknowns; j++) {
+            if (!aug.elements[i][j].isZero()) {
+                allZero = false;
+                break;
+            }
+        }
+        if (allZero && !aug.elements[i][unknowns].isZero()) {
+            return undefined;
+        }
+    }
+    // Extract solution from pivots. Expect [I | x] up to row ordering.
+    const solution = new Array(n);
+    const pivotCols = new Set();
+    for (let i = 0; i < rows; i++) {
+        let pivot = -1;
+        for (let j = 0; j < unknowns; j++) {
+            if (!aug.elements[i][j].isZero()) {
+                pivot = j;
+                break;
+            }
+        }
+        if (pivot === -1) {
+            continue;
+        }
+        if (!aug.elements[i][pivot].eq('1')) {
+            return undefined;
+        }
+        if (pivotCols.has(pivot)) {
+            return undefined;
+        }
+        pivotCols.add(pivot);
+        solution[pivot] = aug.elements[i][unknowns];
+    }
+    if (pivotCols.size !== n) {
+        return undefined;
+    }
+    for (let i = 0; i < n; i++) {
+        if (!solution[i]) {
+            return undefined;
+        }
+    }
+    return solution;
+}

package/output/algebra/polynomial/ModularSparsePolynomial.d.ts

@@ -0,0 +1,131 @@
+/**
+ * @module modularSparsePolynomial
+ *
+ * Sparse polynomial arithmetic over integer residue classes.
+ *
+ * External references consulted for modular coefficient arithmetic and sparse
+ * polynomial division:
+ * - SymPy finite-field polynomial arithmetic:
+ *   https://github.com/sympy/sympy/blob/120ee85f346f6292b763cc195afda4f907260d4a/sympy/polys/galoistools.py
+ * - SymPy sparse polynomial substitution, evaluation, and term division:
+ *   https://github.com/sympy/sympy/blob/120ee85f346f6292b763cc195afda4f907260d4a/sympy/polys/sparsetools.py
+ * - SymPy variable-relative leading coefficient operations used by modular GCD:
+ *   https://github.com/sympy/sympy/blob/120ee85f346f6292b763cc195afda4f907260d4a/sympy/polys/zippel.py
+ */
+import { SparsePolynomial, type MonomialOrder, type SparsePolynomialTerm } from '../../core/classes/polynomial/SparsePolynomial';
+/**
+ * Sparse polynomial whose coefficients are stored as canonical residues modulo
+ * a positive integer greater than one.
+ *
+ * The modulus is part of the polynomial ring. Prime moduli provide finite-field
+ * arithmetic; composite moduli remain valid for addition and multiplication but
+ * may not provide multiplicative inverses required by monic normalization or
+ * polynomial division.
+ */
+export declare class ModularSparsePolynomial {
+    private readonly polynomial;
+    readonly modulus: bigint;
+    readonly variableCount: number;
+    constructor(variableCount: number, modulus: bigint, terms?: Iterable<SparsePolynomialTerm> | SparsePolynomial);
+    /** Creates a constant polynomial in the selected residue ring. */
+    static constant(variableCount: number, modulus: bigint, coefficient: bigint): ModularSparsePolynomial;
+    /**
+     * Reconstructs a polynomial in one variable from specialized images.
+     *
+     * Each sample polynomial must be independent of the interpolated variable.
+     * Evaluation values are compared as residues in the shared coefficient ring.
+     */
+    static interpolateVariable(variableIndex: number, samples: ReadonlyArray<Readonly<{
+        value: bigint;
+        polynomial: ModularSparsePolynomial;
+    }>>): ModularSparsePolynomial;
+    /** Creates a one-term polynomial in the selected residue ring. */
+    static monomial(variableCount: number, modulus: bigint, coefficient: bigint, exponents: readonly bigint[]): ModularSparsePolynomial;
+    /** Creates one polynomial variable with coefficient one. */
+    static variable(variableCount: number, modulus: bigint, variableIndex: number): ModularSparsePolynomial;
+    /** Creates the zero polynomial in the selected residue ring. */
+    static zero(variableCount: number, modulus: bigint): ModularSparsePolynomial;
+    /** Verifies that another polynomial belongs to the same residue ring. */
+    private assertCompatible;
+    /** Adds another polynomial in the same residue ring. */
+    add(other: ModularSparsePolynomial): ModularSparsePolynomial;
+    /** Returns the canonical residue coefficient of one monomial. */
+    coefficient(exponents: readonly bigint[]): bigint;
+    /**
+     * Returns the coefficient polynomial at one exact power of a selected variable.
+     *
+     * The selected variable remains in the ring with exponent zero.
+     */
+    coefficientIn(variableIndex: number, exponent: bigint): ModularSparsePolynomial;
+    /** Returns the canonical residue of the constant coefficient. */
+    constantTerm(): bigint;
+    /** Returns the degree in one variable, or null for the zero polynomial. */
+    degree(variableIndex: number): bigint | null;
+    /**
+     * Differentiates with respect to one ring variable in the residue ring.
+     */
+    derivative(variableIndex: number): ModularSparsePolynomial;
+    /**
+     * Divides by one polynomial when the remainder is zero.
+     */
+    divideExact(divisor: ModularSparsePolynomial, order?: MonomialOrder): ModularSparsePolynomial | null;
+    /**
+     * Divides by one polynomial and returns quotient and remainder.
+     *
+     * The leading coefficient of the divisor must be invertible modulo the ring
+     * modulus.
+     */
+    divideWithRemainder(divisor: ModularSparsePolynomial, order?: MonomialOrder): Readonly<{
+        quotient: ModularSparsePolynomial;
+        remainder: ModularSparsePolynomial;
+    }>;
+    /** Returns whether two polynomials have the same residue ring and exact terms. */
+    equals(other: ModularSparsePolynomial): boolean;
+    /**
+     * Substitutes one variable with a residue while keeping the same ring dimension.
+     *
+     * Terms that become like terms after substitution are combined by the sparse
+     * polynomial constructor.
+     */
+    evaluateVariable(variableIndex: number, value: bigint): ModularSparsePolynomial;
+    /** Returns whether the polynomial is zero or contains only a constant term. */
+    isConstant(): boolean;
+    /** Returns whether the polynomial has no nonzero terms. */
+    isZero(): boolean;
+    /**
+     * Returns the coefficient polynomial of the highest power of one variable.
+     *
+     * The selected variable remains in the ring with exponent zero so recursive
+     * algorithms can preserve a stable variable layout.
+     */
+    leadingCoefficientIn(variableIndex: number): ModularSparsePolynomial | null;
+    /** Returns the leading term under the requested monomial order. */
+    leadingTerm(order?: MonomialOrder): SparsePolynomialTerm | null;
+    /**
+     * Scales the polynomial so its leading coefficient is one.
+     *
+     * Zero remains zero. A nonzero leading coefficient that has no inverse modulo
+     * the modulus is rejected.
+     */
+    monic(order?: MonomialOrder): ModularSparsePolynomial;
+    /** Multiplies by another polynomial in the same residue ring. */
+    multiply(other: ModularSparsePolynomial): ModularSparsePolynomial;
+    /** Returns the additive inverse in the residue ring. */
+    negate(): ModularSparsePolynomial;
+    /** Raises the polynomial to a non-negative exact integer power. */
+    pow(exponent: bigint): ModularSparsePolynomial;
+    /** Multiplies every coefficient by one residue-ring scalar. */
+    scale(scalar: bigint): ModularSparsePolynomial;
+    /** Subtracts another polynomial in the same residue ring. */
+    subtract(other: ModularSparsePolynomial): ModularSparsePolynomial;
+    /** Number of stored nonzero terms. */
+    get termCount(): number;
+    /** Returns the stored canonical residue terms. */
+    terms(): readonly SparsePolynomialTerm[];
+    /** Converts canonical residues to centered integer representatives. */
+    toSymmetricIntegerPolynomial(): SparsePolynomial;
+    /** Returns the largest total degree, or null for the zero polynomial. */
+    totalDegree(): bigint | null;
+    /** Returns the variable indices that occur with a positive exponent. */
+    variables(): readonly number[];
+}