nerdamer 1.1.13 → 2.0.0-rc.1

package/output/core/classes/matrix/Matrix.js

@@ -0,0 +1,889 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Matrix = void 0;
+const math_1 = require("../../../math/math");
+const StructuredEntity_1 = require("../../common/classes/StructuredEntity");
+const common_1 = require("../../common/common");
+const structuredEntityUtils_1 = require("../../common/functions/structuredEntityUtils");
+const errors_1 = require("../../errors");
+const Expression_1 = require("../expression/Expression");
+const shortcuts_1 = require("../expression/shortcuts");
+const constants_1 = require("../parser/constants");
+const Vector_1 = require("../vector/Vector");
+/**
+ * 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.
+ */
+class Matrix extends StructuredEntity_1.StructuredEntity {
+    /**
+     * Number of row swaps performed during the last toRightTriangular call.
+     * Used internally by determinant() to correct the sign.
+     */
+    _rowSwaps = 0;
+    dataType = constants_1.MATRIX;
+    elements;
+    isEnumerable = true;
+    precision;
+    /**
+     * 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) {
+        super();
+        this.elements = [];
+        let previousRowLength;
+        for (let i = 0; i < elements.length; i++) {
+            const rowInput = elements[i];
+            const row = Vector_1.Vector.isVector(rowInput) ? rowInput.elements : (0, structuredEntityUtils_1.toParserEntities)(rowInput);
+            // Matrices are numeric/algebraic objects; elements must be expressions.
+            const exprRow = row.map((v) => {
+                // Reject aggregate types inside a matrix (Vector/Matrix/Collection/ValuesSet/Equation).
+                return Expression_1.Expression.create(v);
+            });
+            if (exprRow.length > 0) {
+                if (previousRowLength !== undefined && previousRowLength !== exprRow.length) {
+                    throw new errors_1.MathError((0, errors_1.message)('cannotCreateMatrix'));
+                }
+                this.elements.push(exprRow);
+                previousRowLength = exprRow.length;
+            }
+        }
+    }
+    /** Creates a matrix whose cells are independent copies of `value`. */
+    static fill(rows, cols, value) {
+        const M = new Matrix([]);
+        for (let i = 0; i < rows; i++) {
+            const row = [];
+            for (let j = 0; j < cols; j++) {
+                row.push(value.copy());
+            }
+            M.elements.push(row);
+        }
+        return M;
+    }
+    /** Creates the `n` by `n` identity matrix. */
+    static identity(n) {
+        const M = new Matrix([]);
+        for (let i = 0; i < n; i++) {
+            const row = [];
+            for (let j = 0; j < n; j++) {
+                row.push(i === j ? (0, shortcuts_1.one)() : (0, shortcuts_1.zero)());
+            }
+            M.elements.push(row);
+        }
+        return M;
+    }
+    static isMatrix(obj) {
+        return (0, common_1.isNerdamerNativeType)(obj, constants_1.MATRIX);
+    }
+    /** Creates a matrix filled with symbolic zeros. */
+    static zeroMatrix(rows, cols) {
+        return Matrix.fill(rows, cols, (0, shortcuts_1.zero)());
+    }
+    /**
+     * 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) {
+        const row = indices[0];
+        if (row < 0 || row >= this.elements.length) {
+            throw new errors_1.MathError(`Row index ${row} out of bounds for Matrix with ${this.elements.length} rows`);
+        }
+        if (indices.length > 1) {
+            const col = indices[1];
+            if (col < 0 || col >= this.elements[row].length) {
+                throw new errors_1.MathError(`Column index ${col} out of bounds for Matrix with ${this.elements[row].length} columns`);
+            }
+            return this.elements[row][col];
+        }
+        return new Vector_1.Vector(this.elements[row]);
+    }
+    /**
+     * 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, value) {
+        if (typeof indices === 'string') {
+            throw new errors_1.MathError('Matrix does not support string key access');
+        }
+        const row = indices[0];
+        const col = indices.length > 1 ? indices[1] : undefined;
+        if (row < 0 || row >= this.elements.length) {
+            throw new errors_1.MathError(`Row index ${row} out of bounds for Matrix with ${this.elements.length} rows`);
+        }
+        if (col !== undefined) {
+            if (col < 0 || col >= this.elements[row].length) {
+                throw new errors_1.MathError(`Column index ${col} out of bounds for Matrix with ${this.elements[row].length} columns`);
+            }
+            this.elements[row][col] = Expression_1.Expression.create(value);
+        }
+        else {
+            if (!Vector_1.Vector.isVector(value)) {
+                throw new errors_1.UnexpectedDataType((0, errors_1.message)('vectorExpected', { type: constants_1.dataTypes[value.dataType] }));
+            }
+            if (value.elements.length !== this.cols()) {
+                throw new errors_1.MathError((0, errors_1.message)('mismatchedDimensions', { function: 'Matrix.__set__' }));
+            }
+            // Build the replacement before mutating so conversion errors leave the matrix unchanged.
+            const replacement = value.elements.map(e => Expression_1.Expression.create(e));
+            this.elements[row] = replacement;
+        }
+    }
+    /**
+     * Returns the horizontal augmentation `[this | matrix]` without mutating either input.
+     *
+     * @throws {@link core!MathError} If the row counts differ.
+     */
+    augment(matrix) {
+        const rows = this.rows();
+        if (rows !== matrix.rows()) {
+            throw new errors_1.MathError((0, errors_1.message)('rowsMustMatch'));
+        }
+        if (rows === 0) {
+            return this.copy();
+        }
+        const M = matrix.copy();
+        const T = this.copy();
+        const cols = T.cols();
+        let i = rows;
+        const nj = M.cols();
+        let j;
+        while (i--) {
+            j = nj;
+            while (j--) {
+                T.elements[i][cols + j] = M.elements[i][j];
+            }
+        }
+        return T;
+    }
+    canMultiplyFromLeft(M) {
+        return this.cols() === M.rows();
+    }
+    col(n) {
+        const col = [];
+        const rows = this.rows();
+        if (n > 0 && n <= this.cols()) {
+            for (let i = 0; i < rows; i++) {
+                col.push([this.elements[i][n - 1]]);
+            }
+        }
+        return new Matrix(...col);
+    }
+    cols() {
+        return this.elements.length === 0 ? 0 : this.elements[0].length;
+    }
+    /** Copies the matrix and every Expression element. */
+    copy() {
+        const copy = this.map(e => e.copy());
+        return this.copySymbolicAccessTo(copy);
+    }
+    /**
+     * 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() {
+        if (this.rows() === 0) {
+            return (0, shortcuts_1.one)();
+        }
+        if (!this.isSquare()) {
+            throw new errors_1.UnsupportedOperationError((0, errors_1.message)('squareMatrixRequired'));
+        }
+        const M = this.toRightTriangular();
+        const n = this.rows();
+        let det = M.elements[0][0];
+        for (let i = 1; i < n; i++) {
+            det = det.times(M.get(i, i));
+        }
+        // Each row swap negates the determinant
+        if (M._rowSwaps % 2 !== 0) {
+            det = det.neg();
+        }
+        return det;
+    }
+    dimensions() {
+        return [this.rows(), this.cols()];
+    }
+    dimensionsMatch(M) {
+        return Matrix.isMatrix(M) && this.cols() === M.cols() && this.rows() === M.rows();
+    }
+    /**
+     * Divides corresponding entries, or broadcasts a scalar divisor.
+     *
+     * @throws {@link core!DimensionError} If a Matrix divisor has different dimensions.
+     */
+    div(x) {
+        if (Matrix.isMatrix(x) && !this.dimensionsMatch(x)) {
+            throw new errors_1.DimensionError((0, errors_1.message)('mismatchedDimensions', { function: 'Matrix.div' }));
+        }
+        return super.div(x);
+    }
+    /**
+     * 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, j) {
+        return this.get(i - 1, j - 1);
+    }
+    /**
+     * 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) {
+        for (let i = 0; i < this.elements.length; i++) {
+            const row = this.elements[i];
+            for (let j = 0; j < row.length; j++) {
+                const result = fn(row[j], i, j);
+                if (result !== undefined) {
+                    row[j] = result;
+                }
+            }
+        }
+        return this;
+    }
+    eq(M) {
+        if (!Matrix.isMatrix(M) || !this.dimensionsMatch(M)) {
+            return false;
+        }
+        const rows = this.rows();
+        const cols = this.cols();
+        for (let i = 0; i < rows; i++) {
+            for (let j = 0; j < cols; j++) {
+                if (!this.elements[i][j].eq(M.elements[i][j])) {
+                    return false;
+                }
+            }
+        }
+        return true;
+    }
+    evaluate(values) {
+        let retval;
+        const symbolicAccess = Expression_1.Expression.fromSymbolicAccess(this);
+        if (symbolicAccess && values) {
+            retval = symbolicAccess.evaluate(values);
+        }
+        else {
+            const copy = this.copy();
+            copy.each(e => e.evaluate(values));
+            retval = copy;
+        }
+        return retval;
+    }
+    /** Expands a copied matrix, leaving this one unchanged. */
+    expand() {
+        const copy = this.copy();
+        copy.each(e => e.expand());
+        return copy;
+    }
+    /** Visits every cell without changing the matrix. */
+    forEach(callback) {
+        for (let i = 0; i < this.elements.length; i++) {
+            for (let j = 0; j < this.elements[i].length; j++) {
+                callback(this.elements[i][j], i, j);
+            }
+        }
+    }
+    /**
+     * Returns the stored Expression at a zero-based row and column.
+     *
+     * @throws {@link core!MathError} If either index is out of bounds.
+     */
+    get(row, col) {
+        return this.__get__([row, col]);
+    }
+    gt(M) {
+        if (!Matrix.isMatrix(M) || !this.dimensionsMatch(M)) {
+            return false;
+        }
+        const rows = this.rows();
+        const cols = this.cols();
+        for (let i = 0; i < rows; i++) {
+            for (let j = 0; j < cols; j++) {
+                if (!this.elements[i][j].gt(M.elements[i][j])) {
+                    return false;
+                }
+            }
+        }
+        return true;
+    }
+    gte(M) {
+        if (!Matrix.isMatrix(M) || !this.dimensionsMatch(M)) {
+            return false;
+        }
+        const rows = this.rows();
+        const cols = this.cols();
+        for (let i = 0; i < rows; i++) {
+            for (let j = 0; j < cols; j++) {
+                if (!this.elements[i][j].gte(M.elements[i][j])) {
+                    return false;
+                }
+            }
+        }
+        return true;
+    }
+    inspect() {
+        let text = '';
+        for (let i = 0; i < this.elements.length; i++) {
+            const row = this.elements[i];
+            text += `[${row.map(x => x.text()).join(', ')}]\n`;
+        }
+        return text;
+    }
+    /**
+     * 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() {
+        if (!this.isSquare()) {
+            throw new errors_1.UnsupportedOperationError((0, errors_1.message)('squareMatrixRequired'));
+        }
+        if (this.rows() === 0) {
+            return this.copy();
+        }
+        if (this.isSingular()) {
+            throw new errors_1.MathError((0, errors_1.message)('singularMatrix'));
+        }
+        const n = this.elements.length;
+        let i = n;
+        const M = this.augment(Matrix.identity(n)).toRightTriangular();
+        const inverseElements = [];
+        let j;
+        let p;
+        let els;
+        let divisor;
+        let newElement;
+        const np = M.elements[0].length;
+        const z = (0, shortcuts_1.zero)();
+        while (i--) {
+            els = [];
+            inverseElements[i] = [];
+            divisor = M.elements[i][i];
+            // Safety check: if the pivot is zero after triangularization,
+            // the matrix is singular (shouldn't reach here due to isSingular check above)
+            if (divisor.eq(z)) {
+                throw new errors_1.MathError((0, errors_1.message)('singularMatrix'));
+            }
+            for (p = 0; p < np; p++) {
+                newElement = M.elements[i][p].div(divisor);
+                els.push(newElement);
+                if (p >= n) {
+                    inverseElements[i].push(newElement);
+                }
+            }
+            M.elements[i] = els;
+            j = i;
+            while (j--) {
+                els = [];
+                for (p = 0; p < np; p++) {
+                    els.push(M.elements[j][p].minus(M.elements[i][p].times(M.elements[j][i])));
+                }
+                M.elements[j] = els;
+            }
+        }
+        return new Matrix(...inverseElements);
+    }
+    isSingular() {
+        return this.isSquare() && this.determinant().eq('0');
+    }
+    isSquare() {
+        return this.rows() === this.cols();
+    }
+    lt(M) {
+        if (!Matrix.isMatrix(M) || !this.dimensionsMatch(M)) {
+            return false;
+        }
+        const rows = this.rows();
+        const cols = this.cols();
+        for (let i = 0; i < rows; i++) {
+            for (let j = 0; j < cols; j++) {
+                if (!this.elements[i][j].lt(M.elements[i][j])) {
+                    return false;
+                }
+            }
+        }
+        return true;
+    }
+    lte(M) {
+        if (!Matrix.isMatrix(M) || !this.dimensionsMatch(M)) {
+            return false;
+        }
+        const rows = this.rows();
+        const cols = this.cols();
+        for (let i = 0; i < rows; i++) {
+            for (let j = 0; j < cols; j++) {
+                if (!this.elements[i][j].lte(M.elements[i][j])) {
+                    return false;
+                }
+            }
+        }
+        return true;
+    }
+    /** Returns a new matrix populated by callback results without mutating this matrix. */
+    map(callback) {
+        const M = new Matrix([]);
+        for (let i = 0; i < this.elements.length; i++) {
+            M.elements[i] = [];
+            for (let j = 0; j < this.elements[i].length; j++) {
+                M.elements[i][j] = callback(this.elements[i][j], i, j);
+            }
+        }
+        return M;
+    }
+    /**
+     * Subtracts corresponding entries, or broadcasts a scalar subtrahend.
+     *
+     * @throws {@link core!DimensionError} If a Matrix operand has different dimensions.
+     */
+    minus(x) {
+        if (Matrix.isMatrix(x) && !this.dimensionsMatch(x)) {
+            throw new errors_1.DimensionError((0, errors_1.message)('mismatchedDimensions', { function: 'Matrix.minus' }));
+        }
+        return super.minus(x);
+    }
+    multiply(x) {
+        return this.times(x);
+    }
+    /**
+     * 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) {
+        const p = prime === undefined ? undefined : Expression_1.Expression.create(prime);
+        const A = this.rref(prime);
+        const rows = A.rows();
+        const cols = A.cols();
+        const z = (0, shortcuts_1.zero)();
+        // Find pivot columns: for each row, the first nonzero entry is the pivot.
+        const pivotCols = new Set();
+        const rowPivot = new Array(rows).fill(-1);
+        for (let i = 0; i < rows; i++) {
+            for (let j = 0; j < cols; j++) {
+                if (!A.elements[i][j].eq(z)) {
+                    pivotCols.add(j);
+                    rowPivot[i] = j;
+                    break;
+                }
+            }
+        }
+        const freeCols = [];
+        for (let j = 0; j < cols; j++) {
+            if (!pivotCols.has(j)) {
+                freeCols.push(j);
+            }
+        }
+        const basis = [];
+        for (const free of freeCols) {
+            const vec = Array.from({ length: cols }, () => (0, shortcuts_1.zero)());
+            vec[free] = (0, shortcuts_1.one)();
+            for (let i = 0; i < rows; i++) {
+                const pivot = rowPivot[i];
+                if (pivot !== -1) {
+                    const value = (0, shortcuts_1.zero)().minus(A.elements[i][free]);
+                    vec[pivot] = p ? (0, math_1.mod)(value, p) : value;
+                }
+            }
+            basis.push(vec);
+        }
+        return basis;
+    }
+    /**
+     * Adds corresponding entries, or broadcasts a scalar addend.
+     *
+     * @throws {@link core!DimensionError} If a Matrix operand has different dimensions.
+     */
+    plus(x) {
+        if (Matrix.isMatrix(x) && !this.dimensionsMatch(x)) {
+            throw new errors_1.DimensionError((0, errors_1.message)('mismatchedDimensions', { function: 'Matrix.plus' }));
+        }
+        return super.plus(x);
+    }
+    /**
+     * 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) {
+        const exponent = Expression_1.Expression.create(x);
+        if (!exponent.isNUM() || !exponent.isInteger()) {
+            throw new errors_1.UnsupportedOperationError((0, errors_1.message)('unsupportedOperation'));
+        }
+        const n = exponent.getMultiplier().numerator;
+        let retval;
+        if (n === 1n) {
+            retval = this.copy();
+        }
+        else {
+            if (!this.isSquare()) {
+                throw new errors_1.UnsupportedOperationError((0, errors_1.message)('squareMatrixRequired'));
+            }
+            if (n === 0n) {
+                retval = Matrix.identity(this.rows());
+            }
+            else {
+                let remaining = n < 0n ? -n : n;
+                let base = n < 0n ? this.inverse() : this.copy();
+                retval = Matrix.identity(this.rows());
+                while (remaining > 0n) {
+                    if (remaining % 2n === 1n) {
+                        retval = retval.times(base);
+                    }
+                    remaining /= 2n;
+                    if (remaining > 0n) {
+                        base = base.times(base);
+                    }
+                }
+            }
+        }
+        return retval;
+    }
+    rank() {
+        const M = this.toRightTriangular();
+        let rank = 0;
+        let i = M.rows();
+        const cols = M.cols();
+        const z = (0, shortcuts_1.zero)();
+        let j;
+        while (i--) {
+            j = cols;
+            while (j--) {
+                if (!M.elements[i][j].eq(z)) {
+                    rank++;
+                    break;
+                }
+            }
+        }
+        return rank;
+    }
+    row(n) {
+        let retval;
+        if (n < 1 || n > this.rows()) {
+            retval = new Matrix([]);
+        }
+        else if (this.cols() === 0) {
+            retval = Matrix.zeroMatrix(1, 0);
+        }
+        else {
+            retval = new Matrix(this.elements[n - 1]);
+        }
+        return retval;
+    }
+    rows() {
+        return this.elements.length;
+    }
+    /**
+     * 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) {
+        const rows = this.rows();
+        const cols = this.cols();
+        let lead = 0;
+        const M = this.copy();
+        const z = (0, shortcuts_1.zero)();
+        const p = prime ? Expression_1.Expression.create(prime) : undefined;
+        // Pivot selection must use field representatives, so normalize before zero testing.
+        if (p) {
+            M.each(e => (0, math_1.mod)(e, p));
+        }
+        for (let r = 0; r < rows; r++) {
+            if (cols <= lead) {
+                break;
+            }
+            // Find a row with a nonzero entry in the lead column
+            let i = r;
+            while (M.elements[i][lead].eq(z)) {
+                i++;
+                if (rows === i) {
+                    i = r;
+                    lead++;
+                    if (cols === lead) {
+                        return M;
+                    }
+                }
+            }
+            // Swap rows i and r
+            [M.elements[i], M.elements[r]] = [M.elements[r], M.elements[i]];
+            if (p) {
+                const inv = (0, math_1.modInv)(M.elements[r][lead], p);
+                for (let j = 0; j < cols; j++) {
+                    M.elements[r][j] = (0, math_1.mod)(M.elements[r][j].times(inv), p);
+                }
+                for (let k = 0; k < rows; k++) {
+                    if (k !== r) {
+                        const factor = M.elements[k][lead];
+                        for (let j = 0; j < cols; j++) {
+                            M.elements[k][j] = (0, math_1.mod)(M.elements[k][j].minus(factor.times(M.elements[r][j])), p);
+                        }
+                    }
+                }
+            }
+            else {
+                const pivot = M.elements[r][lead];
+                // The pivot search has already established that this expression is nonzero,
+                // so RREF requires normalization regardless of its numeric magnitude.
+                for (let j = 0; j < cols; j++) {
+                    M.elements[r][j] = M.elements[r][j].div(pivot);
+                }
+                for (let k = 0; k < rows; k++) {
+                    if (k !== r) {
+                        const factor = M.elements[k][lead];
+                        // A zero factor means this row is already clear in the pivot column.
+                        // Skipping the no-op also avoids propagating numeric metadata through
+                        // multiplication by zero.
+                        if (factor.eq(z)) {
+                            continue;
+                        }
+                        for (let j = 0; j < cols; j++) {
+                            M.elements[k][j] = M.elements[k][j].minus(factor.times(M.elements[r][j]));
+                        }
+                    }
+                }
+            }
+            lead++;
+        }
+        M.elements.sort((rowA, rowB) => {
+            const isZeroA = rowA.every(val => val.eq(z));
+            const isZeroB = rowB.every(val => val.eq(z));
+            if (isZeroA && !isZeroB) {
+                return 1;
+            }
+            if (!isZeroA && isZeroB) {
+                return -1;
+            }
+            return 0;
+        });
+        return M;
+    }
+    /** Sets a zero-based cell after converting `value` to an Expression. */
+    set(row, col, value) {
+        this.__set__([row, col], value);
+        return this;
+    }
+    text() {
+        const textArray = [];
+        for (let i = 0; i < this.elements.length; i++) {
+            const row = this.elements[i];
+            const rowTextArray = [];
+            for (let j = 0; j < row.length; j++) {
+                rowTextArray.push(row[j].text());
+            }
+            textArray.push(`[${rowTextArray.join(', ')}]`);
+        }
+        const text = `matrix(${textArray.join(', ')})`;
+        return this.formatSymbolicAccess(text);
+    }
+    times(M) {
+        let retval;
+        // Scalar multiplication: scale every element.
+        if (Expression_1.Expression.isExpression(M)) {
+            retval = this.map(e => e.times(M));
+        }
+        else if (Vector_1.Vector.isVector(M)) {
+            if (this.cols() !== M.count()) {
+                throw new errors_1.MathError((0, errors_1.message)('mismatchedDimensions', { function: 'Matrix.times' }));
+            }
+            const elements = [];
+            for (let i = 0; i < this.rows(); i++) {
+                elements.push(new Vector_1.Vector(this.elements[i]).dot(M));
+            }
+            retval = new Vector_1.Vector(elements);
+        }
+        else {
+            if (!Matrix.isMatrix(M)) {
+                throw new errors_1.UnsupportedOperationError((0, errors_1.message)('unsupportedType', { type: constants_1.dataTypes[M.dataType] }));
+            }
+            if (!this.canMultiplyFromLeft(M)) {
+                throw new errors_1.MathError((0, errors_1.message)('mismatchedDimensions', { function: 'Matrix.times' }));
+            }
+            if (this.rows() === 0) {
+                retval = new Matrix([]);
+            }
+            else if (M.cols() === 0) {
+                retval = Matrix.zeroMatrix(this.rows(), 0);
+            }
+            else {
+                const e = this.elements;
+                const m = e.length;
+                const o = e[0].length;
+                const elements = [];
+                let i = m;
+                const n = M.cols();
+                let j;
+                let k;
+                let rowThis;
+                let rowElem;
+                let sum;
+                while (i--) {
+                    rowElem = [];
+                    rowThis = e[i];
+                    j = n;
+                    while (j--) {
+                        sum = (0, shortcuts_1.zero)();
+                        k = o;
+                        while (k--) {
+                            const x = rowThis[k];
+                            const y = M.elements[k][j];
+                            sum = sum.plus(x.times(y));
+                        }
+                        rowElem[j] = sum;
+                    }
+                    elements[i] = rowElem;
+                }
+                retval = new Matrix(...elements);
+            }
+        }
+        return retval;
+    }
+    /** Returns a row-echelon copy produced by forward elimination and row swaps. */
+    toRightTriangular() {
+        const M = this.copy();
+        const rows = M.rows();
+        const cols = M.cols();
+        const z = (0, shortcuts_1.zero)();
+        let pivotRow = 0;
+        // Track the number of row swaps for determinant sign correction.
+        M._rowSwaps = 0;
+        for (let lead = 0; lead < cols && pivotRow < rows; lead++) {
+            let pivot = pivotRow;
+            while (pivot < rows && M.elements[pivot][lead].eq(z)) {
+                pivot++;
+            }
+            // A column without a pivot does not consume a row.
+            if (pivot === rows) {
+                continue;
+            }
+            if (pivot !== pivotRow) {
+                [M.elements[pivot], M.elements[pivotRow]] = [
+                    M.elements[pivotRow],
+                    M.elements[pivot],
+                ];
+                M._rowSwaps++;
+            }
+            const pivotValue = M.elements[pivotRow][lead];
+            // Eliminate below the pivot.
+            for (let row = pivotRow + 1; row < rows; row++) {
+                if (!M.elements[row][lead].eq(z)) {
+                    const multiplier = M.elements[row][lead].div(pivotValue);
+                    const els = [];
+                    for (let col = 0; col < cols; col++) {
+                        els.push(col <= lead
+                            ? (0, shortcuts_1.zero)()
+                            : M.elements[row][col].minus(M.elements[pivotRow][col].times(multiplier)));
+                    }
+                    M.elements[row] = els;
+                }
+            }
+            pivotRow++;
+        }
+        return M;
+    }
+    toUpperTriangular() {
+        return this.toRightTriangular();
+    }
+    /**
+     * Returns the sum of the main diagonal. The empty matrix has trace zero.
+     * @throws {@link core!MathError} If the matrix is not square.
+     */
+    trace() {
+        if (!this.isSquare()) {
+            throw new errors_1.MathError('Unable to calculate trace for the matrix');
+        }
+        let tr = (0, shortcuts_1.zero)();
+        const n = this.elements.length;
+        for (let i = 0; i < n; i++) {
+            const e = this.elements[i][i];
+            if (!Expression_1.Expression.isExpression(e)) {
+                throw new errors_1.MathError('Unable to calculate trace for the matrix');
+            }
+            tr = tr.plus(e);
+        }
+        return tr;
+    }
+    /** Returns a transposed matrix. Existing elements are normalized by the constructor. */
+    transpose() {
+        const rows = this.rows();
+        const cols = this.cols();
+        if (rows > 0 && cols === 0) {
+            throw new errors_1.UnsupportedOperationError((0, errors_1.message)('unsupportedOperation'));
+        }
+        const elements = [];
+        let i = cols;
+        while (i--) {
+            let j = rows;
+            elements[i] = [];
+            while (j--) {
+                elements[i][j] = this.elements[j][i];
+            }
+        }
+        return new Matrix(...elements);
+    }
+    /** Returns elements as a column-major Vector. */
+    unroll() {
+        const v = [];
+        for (let i = 1; i <= this.cols(); i++) {
+            for (let j = 1; j <= this.rows(); j++) {
+                v.push(this.e(j, i));
+            }
+        }
+        return new Vector_1.Vector(v);
+    }
+}
+exports.Matrix = Matrix;