nerdamer 1.1.13 → 2.0.0-rc.1

package/output/core/classes/vector/Vector.js

@@ -0,0 +1,497 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Vector = void 0;
+const MathematicalAggregate_1 = require("../../common/classes/MathematicalAggregate");
+const common_1 = require("../../common/common");
+const structuredEntityUtils_1 = require("../../common/functions/structuredEntityUtils");
+const errors_1 = require("../../errors");
+const Collection_1 = require("../collection/Collection");
+const Expression_1 = require("../expression/Expression");
+const shortcuts_1 = require("../expression/shortcuts");
+const constants_1 = require("../parser/constants");
+const Polynomial_1 = require("../polynomial/Polynomial");
+/**
+ * An ordered, operable parser aggregate with heterogeneous {@link ParserEntity} elements.
+ *
+ * @remarks
+ * Vector is not restricted to numeric linear-algebra values. General arithmetic
+ * is element-wise: scalar operands are broadcast across the Vector, while Vector
+ * operands are paired by position and must have the same length. Vector-to-Vector
+ * {@link times} remains an element-wise product rather than an alias for {@link dot}.
+ * A Matrix operand interprets this Vector as a row vector for the standard
+ * `Vector * Matrix` product; orientation is supplied by operand position rather
+ * than stored on the Vector.
+ * Structural methods such as {@link append}, {@link insert}, {@link extend},
+ * {@link reverse}, and {@link trim} mutate this Vector.
+ *
+ * True linear-algebra operations ({@link dot}, {@link cross}, and {@link norm})
+ * require Expression elements. `dot` requires equal lengths, while `cross`
+ * requires two three-element Vectors. These operations throw rather than
+ * assigning arithmetic meaning to arbitrary aggregate elements.
+ *
+ * Construction from a Collection copies its elements. Construction from an
+ * array normalizes inputs but retains existing parser entities; {@link copy}
+ * deep-copies every element. Comparisons are component-wise predicates, not a
+ * total ordering, and return false for a type or length mismatch.
+ */
+class Vector extends MathematicalAggregate_1.MathematicalAggregate {
+    dataType = constants_1.VECTOR;
+    elements;
+    isEnumerable = true;
+    precision;
+    /** Creates a Vector from normalized input values or a copied Collection. */
+    constructor(elements) {
+        super();
+        if (Collection_1.Collection.isCollection(elements)) {
+            this.elements = elements.elements.map(e => e.copy());
+        }
+        else if (elements) {
+            this.elements = (0, structuredEntityUtils_1.toParserEntities)(elements);
+        }
+        else {
+            this.elements = [];
+        }
+    }
+    /** Creates an Expression-only Vector from expression-compatible inputs. */
+    static create(v) {
+        return new Vector(v.map(x => Expression_1.Expression.create(x)));
+    }
+    static isVector(obj) {
+        return (0, common_1.isNerdamerNativeType)(obj, constants_1.VECTOR);
+    }
+    getValuesArray() {
+        return [...this.elements];
+    }
+    setValuesArray(values) {
+        this.elements = values;
+    }
+    /**
+     * Returns the element at the given zero-based index.
+     * Used by the parser for bracket indexing, e.g. [a, b, c][1] returns b.
+     *
+     * @param indices - Zero-based parser indices after index-base adjustment.
+     * @returns The stored parser entity.
+     * @throws {@link core!UnexpectedDataType} If the index is out of bounds.
+     */
+    __get__(indices) {
+        const index = indices[0];
+        if (index < 0 || index >= this.elements.length) {
+            throw new errors_1.UnexpectedDataType(`Index ${index} out of bounds for Vector of length ${this.elements.length}`);
+        }
+        return this.elements[index];
+    }
+    /** Appends an existing parser entity by reference and returns this Vector. */
+    add(x) {
+        return this.append(x);
+    }
+    /**
+     * Appends an existing parser entity by reference.
+     * @param e - Element to append.
+     */
+    append(e) {
+        this.elements.push(e);
+        return this;
+    }
+    arrayMap(callback) {
+        const retval = [];
+        for (let i = 0; i < this.elements.length; i++) {
+            retval.push(callback(this.elements[i]));
+        }
+        return retval;
+    }
+    /**
+     * Returns the stored entity at a zero-based index without copying it.
+     * @param i - Zero-based index.
+     * @returns The entity, or `undefined` when the index is out of range.
+     */
+    at(i) {
+        return this.elements[i];
+    }
+    /**
+     * Removes all elements from the vector.
+     */
+    clear() {
+        this.elements = [];
+        return this;
+    }
+    /** Copies the Vector and every contained entity. */
+    copy() {
+        const copy = new Vector();
+        this.each((e, i) => {
+            copy.elements[i] = e.copy();
+            return e;
+        });
+        return this.copySymbolicAccessTo(copy);
+    }
+    /**
+     * Gets the number of current elements in the Vector.
+     * @returns Current length.
+     */
+    count() {
+        return this.elements.length;
+    }
+    /**
+     * Computes the three-dimensional cross product.
+     *
+     * @throws {@link core!DimensionError} Unless both Vectors have exactly three elements.
+     * @throws {@link core!UnexpectedDataType} If any required element is not an Expression.
+     */
+    cross(v) {
+        if (this.elements.length !== 3 || v.elements.length !== 3) {
+            throw new errors_1.DimensionError((0, errors_1.message)('incorrectCrossDimension'));
+        }
+        const a = this.getExpressionAt(0);
+        const b = this.getExpressionAt(1);
+        const c = this.getExpressionAt(2);
+        const d = v.getExpressionAt(0);
+        const e = v.getExpressionAt(1);
+        const f = v.getExpressionAt(2);
+        return Vector.create([
+            b.times(f).minus(c.times(e)),
+            c.times(d).minus(a.times(f)),
+            a.times(e).minus(b.times(d)),
+        ]);
+    }
+    delete(x) {
+        const index = this.indexOf(x);
+        if (index === -1) {
+            return false;
+        }
+        this.elements.splice(index, 1);
+        return true;
+    }
+    dimensions() {
+        return [this.elements.length];
+    }
+    /**
+     * Divides corresponding elements, or broadcasts a scalar divisor.
+     *
+     * @remarks
+     * Vector-to-Vector division is element-wise and requires equal lengths. This is
+     * distinct from scalar division, which applies the same divisor to every element.
+     *
+     * @throws {@link core!DimensionError} If a Vector divisor has a different length.
+     */
+    div(x) {
+        if (Vector.isVector(x) && !this.dimensionsMatch(x)) {
+            throw new errors_1.DimensionError((0, errors_1.message)('mismatchedDimensions', { function: 'Vector.div' }));
+        }
+        return super.div(x);
+    }
+    /**
+     * Computes the sum of pairwise products.
+     *
+     * @throws {@link core!DimensionError} If the Vector lengths differ.
+     * @throws {@link core!UnexpectedDataType} If a required element is not an Expression.
+     */
+    dot(v) {
+        if (this.elements.length !== v.elements.length) {
+            throw new errors_1.DimensionError((0, errors_1.message)('mismatchedDimensions', { function: 'Vector.dot' }));
+        }
+        let product = (0, shortcuts_1.zero)();
+        for (let i = 0; i < this.elements.length; i++) {
+            product = product.plus(this.getExpressionAt(i).times(v.getExpressionAt(i)));
+        }
+        return product;
+    }
+    /**
+     * Visits or replaces elements in ascending index order.
+     * Returning `void` leaves the current element unchanged.
+     */
+    each(callback) {
+        for (let i = 0; i < this.elements.length; i++) {
+            const result = callback(this.elements[i], i);
+            if (result !== undefined) {
+                this.elements[i] = result;
+            }
+        }
+        return this;
+    }
+    eq(V) {
+        if (!Vector.isVector(V) || V.elements.length !== this.elements.length) {
+            return false;
+        }
+        for (let i = 0; i < this.elements.length; i++) {
+            if (!this.elements[i].eq(V.elements[i])) {
+                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 => (Expression_1.Expression.isExpression(e) ? e.evaluate(values) : e.evaluate()));
+            retval = copy;
+        }
+        return retval;
+    }
+    /** Expands a copied Vector, leaving this one unchanged. */
+    expand() {
+        const copy = this.copy();
+        copy.each(e => e.expand());
+        return copy;
+    }
+    /**
+     * Appends another Vector's element references, mutating this Vector.
+     * @param v - Vector whose elements should be appended.
+     * @returns This Vector.
+     * @throws {@link core!UnexpectedDataType} If `v` is not a Vector.
+     */
+    extend(v) {
+        if (!Vector.isVector(v)) {
+            throw new errors_1.UnexpectedDataType((0, errors_1.message)('vectorExpected', { type: constants_1.dataTypes[v.dataType] }));
+        }
+        this.elements.push(...v.elements);
+        return this;
+    }
+    /**
+     * Returns an element after verifying that it is an Expression.
+     * @param n - Zero-based index.
+     * @returns The stored Expression reference.
+     * @throws {@link core!UnexpectedDataType} If the stored entity is not an Expression.
+     */
+    getExpressionAt(n) {
+        const e = this.elements[n];
+        if (!Expression_1.Expression.isExpression(e)) {
+            throw new errors_1.UnexpectedDataType((0, errors_1.message)('expressionExpected', { type: constants_1.dataTypes[e.dataType] }));
+        }
+        return e;
+    }
+    gt(V) {
+        if (!Vector.isVector(V) || V.elements.length !== this.elements.length) {
+            return false;
+        }
+        for (let i = 0; i < this.elements.length; i++) {
+            if (!this.elements[i].gt(V.elements[i])) {
+                return false;
+            }
+        }
+        return true;
+    }
+    gte(V) {
+        if (!Vector.isVector(V) || V.elements.length !== this.elements.length) {
+            return false;
+        }
+        for (let i = 0; i < this.elements.length; i++) {
+            if (!this.elements[i].gte(V.elements[i])) {
+                return false;
+            }
+        }
+        return true;
+    }
+    /**
+     * Gets the index of the first element structurally equal to `x`.
+     * @param x - Value to locate.
+     * @returns The zero-based index, or `-1` when absent.
+     */
+    indexOf(x) {
+        for (let i = 0; i < this.elements.length; i++) {
+            const e = this.elements[i];
+            if (e.eq(x)) {
+                return i;
+            }
+        }
+        return -1;
+    }
+    /**
+     * Inserts an entity by reference before the provided index.
+     * @param i - Zero-based insertion index.
+     * @param x - Entity to insert.
+     * @returns This mutated Vector.
+     */
+    insert(i, x) {
+        this.elements.splice(i, 0, x);
+        return this;
+    }
+    lt(V) {
+        if (!Vector.isVector(V) || V.elements.length !== this.elements.length) {
+            return false;
+        }
+        for (let i = 0; i < this.elements.length; i++) {
+            if (!this.elements[i].lt(V.elements[i])) {
+                return false;
+            }
+        }
+        return true;
+    }
+    lte(V) {
+        if (!Vector.isVector(V) || V.elements.length !== this.elements.length) {
+            return false;
+        }
+        for (let i = 0; i < this.elements.length; i++) {
+            if (!this.elements[i].lte(V.elements[i])) {
+                return false;
+            }
+        }
+        return true;
+    }
+    /**
+     * Subtracts corresponding elements, or broadcasts a scalar subtrahend.
+     *
+     * @throws {@link core!DimensionError} If a Vector operand has a different length.
+     */
+    minus(x) {
+        if (Vector.isVector(x) && !this.dimensionsMatch(x)) {
+            throw new errors_1.DimensionError((0, errors_1.message)('mismatchedDimensions', { function: 'Vector.minus' }));
+        }
+        return super.minus(x);
+    }
+    /**
+     * Returns the Euclidean norm `sqrt(sum(abs(element)^2))`.
+     * @throws {@link core!UnexpectedDataType} If any element is not an Expression.
+     */
+    norm() {
+        let sum = (0, shortcuts_1.zero)();
+        for (let i = 0; i < this.elements.length; i++) {
+            sum = sum.plus(this.getExpressionAt(i).abs().sq());
+        }
+        return sum.pow('1/2');
+    }
+    /**
+     * Adds corresponding elements, or broadcasts a scalar addend.
+     *
+     * @throws {@link core!DimensionError} If a Vector operand has a different length.
+     */
+    plus(x) {
+        if (Vector.isVector(x) && !this.dimensionsMatch(x)) {
+            throw new errors_1.DimensionError((0, errors_1.message)('mismatchedDimensions', { function: 'Vector.plus' }));
+        }
+        return super.plus(x);
+    }
+    /**
+     * Removes an element given an index. If none is provided it removes the last element.
+     * Indices are zero-based.
+     * @param index - Optional zero-based index.
+     * @returns The removed entity, or `undefined` when no entity is present.
+     */
+    pop(index) {
+        let removed;
+        if (typeof index !== 'undefined') {
+            removed = this.elements.splice(index, 1)[0];
+        }
+        else {
+            removed = this.elements.pop();
+        }
+        return removed;
+    }
+    /**
+     * Raises corresponding elements to powers, or broadcasts a scalar exponent.
+     *
+     * @throws {@link core!DimensionError} If a Vector exponent has a different length.
+     */
+    pow(x) {
+        if (Vector.isVector(x) && !this.dimensionsMatch(x)) {
+            throw new errors_1.DimensionError((0, errors_1.message)('mismatchedDimensions', { function: 'Vector.pow' }));
+        }
+        return super.pow(x);
+    }
+    /**
+     * Multiplies all Expression elements in order.
+     * @returns Their product, or one for an empty Vector.
+     * @throws {@link core!UnexpectedDataType} If an element is not an Expression.
+     */
+    prod() {
+        let retval = (0, shortcuts_1.one)();
+        this.each(e => {
+            retval = retval.times(Expression_1.Expression.create(e));
+        });
+        return retval;
+    }
+    /**
+     * Removes the first element equal to `x`, rather than matching by reference.
+     * @param x - Value to remove.
+     * @returns This Vector, whether or not a match was found.
+     */
+    remove(x) {
+        const index = this.indexOf(x);
+        if (index !== -1) {
+            this.elements.splice(index, 1);
+        }
+        return this;
+    }
+    /**
+     * Reverses the Vector in place.
+     * @returns This Vector.
+     */
+    reverse() {
+        this.elements.reverse();
+        return this;
+    }
+    /**
+     * Adds all Expression elements in order.
+     * @returns Their sum, or zero for an empty Vector.
+     * @throws {@link core!UnexpectedDataType} If an element is not an Expression.
+     */
+    sum() {
+        let retval = (0, shortcuts_1.zero)();
+        this.each(e => {
+            retval = retval.plus(Expression_1.Expression.create(e));
+        });
+        return retval;
+    }
+    text() {
+        const text = `[${this.elements.map(e => e.text()).join(', ')}]`;
+        return this.formatSymbolicAccess(text);
+    }
+    /**
+     * Multiplies corresponding Vector elements, broadcasts a scalar factor, or
+     * multiplies this Vector from the left of a Matrix.
+     *
+     * @remarks
+     * Vector-to-Vector multiplication is the element-wise (Hadamard) product. Use
+     * {@link dot} when a scalar inner product is intended. For a Matrix operand,
+     * this Vector is interpreted as a row vector. Nonzero-width products reuse the
+     * existing Matrix-vector product through the transpose; a compatible zero-width
+     * Matrix has the empty Vector as its result because its transpose cannot be represented.
+     *
+     * @throws {@link core!DimensionError} If Vector dimensions are incompatible.
+     * @throws {@link core!MathError} If Matrix dimensions are incompatible.
+     */
+    times(x) {
+        let retval;
+        if ((0, common_1.isNerdamerNativeType)(x, constants_1.MATRIX)) {
+            const matrix = x;
+            if (matrix.cols() === 0) {
+                if (this.count() !== matrix.rows()) {
+                    throw new errors_1.MathError((0, errors_1.message)('mismatchedDimensions', { function: 'Matrix.times' }));
+                }
+                retval = new Vector();
+            }
+            else {
+                retval = matrix.transpose().times(this);
+            }
+        }
+        else {
+            if (Vector.isVector(x) && !this.dimensionsMatch(x)) {
+                throw new errors_1.DimensionError((0, errors_1.message)('mismatchedDimensions', { function: 'Vector.times' }));
+            }
+            retval = super.times(x);
+        }
+        return retval;
+    }
+    /** Interprets ordered elements as ascending polynomial coefficients. */
+    toPolynomial(vars = ['x']) {
+        return Polynomial_1.Polynomial.fromArray(this.elements, vars);
+    }
+    /**
+     * Removes every element equal to zero.
+     * @returns This mutated Vector.
+     */
+    trim() {
+        const newElements = [];
+        for (const e of this.elements) {
+            if (!e.eq((0, shortcuts_1.zero)())) {
+                newElements.push(e);
+            }
+        }
+        this.elements = newElements;
+        return this;
+    }
+}
+exports.Vector = Vector;

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

@@ -0,0 +1,28 @@
+import { Expression } from '../expression/Expression';
+import { Vector } from './Vector';
+import type { ParserEntity } from '../../types';
+/**
+ * Computes the dot product of two Vectors or preserves two symbolic operands.
+ *
+ * @param a - First Vector, or a symbolic Expression operand.
+ * @param b - Second Vector, or a symbolic Expression operand.
+ * @returns The scalar dot product for Vectors, or an unevaluated `dot(a, b)`
+ * Expression when both operands are Expressions.
+ * @throws {@link core!UnexpectedDataType} If exactly one operand is not a Vector or
+ * the two operands are of incompatible parser types.
+ * @throws {@link core!DimensionError} If Vector lengths differ.
+ */
+export declare function dot(a: ParserEntity, b: ParserEntity): Expression;
+/**
+ * Computes a three-dimensional cross product or preserves symbolic operands.
+ *
+ * @param a - First Vector, or a symbolic Expression operand.
+ * @param b - Second Vector, or a symbolic Expression operand.
+ * @returns The Vector cross product, or an unevaluated `cross(a, b)` Expression
+ * when both operands are Expressions.
+ * @throws {@link core!UnexpectedDataType} For incompatible parser operand types.
+ * @throws {@link core!DimensionError} Unless both Vectors have exactly three elements.
+ */
+export declare function cross(a: Vector, b: Vector): Vector;
+export declare function cross(a: Expression, b: Expression): Expression;
+export declare function cross(a: ParserEntity, b: ParserEntity): Vector | Expression;

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

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dot = dot;
+exports.cross = cross;
+const errors_1 = require("../../errors");
+const Expression_1 = require("../expression/Expression");
+const constants_1 = require("../parser/constants");
+const Vector_1 = require("./Vector");
+/**
+ * Computes the dot product of two Vectors or preserves two symbolic operands.
+ *
+ * @param a - First Vector, or a symbolic Expression operand.
+ * @param b - Second Vector, or a symbolic Expression operand.
+ * @returns The scalar dot product for Vectors, or an unevaluated `dot(a, b)`
+ * Expression when both operands are Expressions.
+ * @throws {@link core!UnexpectedDataType} If exactly one operand is not a Vector or
+ * the two operands are of incompatible parser types.
+ * @throws {@link core!DimensionError} If Vector lengths differ.
+ */
+function dot(a, b) {
+    let retval;
+    if (Vector_1.Vector.isVector(a) && Vector_1.Vector.isVector(b)) {
+        retval = a.dot(b);
+    }
+    else if (Expression_1.Expression.isExpression(a) && Expression_1.Expression.isExpression(b)) {
+        retval = Expression_1.Expression.toFunction(constants_1.DOT_PRODUCT, [a, b]);
+    }
+    else {
+        const operand = Vector_1.Vector.isVector(a) ? b : a;
+        throw new errors_1.UnexpectedDataType((0, errors_1.message)('vectorExpected', { type: constants_1.dataTypes[operand.dataType] }));
+    }
+    return retval;
+}
+function cross(a, b) {
+    let retval;
+    if (Vector_1.Vector.isVector(a) && Vector_1.Vector.isVector(b)) {
+        retval = a.cross(b);
+    }
+    else if (Expression_1.Expression.isExpression(a) && Expression_1.Expression.isExpression(b)) {
+        retval = Expression_1.Expression.toFunction(constants_1.CROSS, [a, b]);
+    }
+    else {
+        const operand = Vector_1.Vector.isVector(a) ? b : a;
+        throw new errors_1.UnexpectedDataType((0, errors_1.message)('vectorExpected', { type: constants_1.dataTypes[operand.dataType] }));
+    }
+    return retval;
+}

package/output/core/common/classes/MathematicalAggregate.d.ts

@@ -0,0 +1,53 @@
+import { StructuredEntity } from './StructuredEntity';
+import type { ParserEntity } from '../../types';
+/**
+ * MathematicalAggregate
+ *
+ * Base class for linear iterable parser entities (Vector, ValuesSet, SolutionSet, ...).
+ *
+ * Elements are ParserEntity values at this shared level. Concrete subclasses may
+ * narrow their public element storage where their own method guarantees it.
+ */
+export declare abstract class MathematicalAggregate<TSelf extends MathematicalAggregate<TSelf>> extends StructuredEntity<TSelf> {
+    abstract elements: ParserEntity[];
+    /**
+     * Returns the element at the given index.
+     * @param indices A single-element array [i]
+     */
+    __get__(indices: number[]): ParserEntity;
+    /**
+     * Sets the element at the given index.
+     * @param indices A single-element array [i]
+     * @param value The value to set
+     */
+    __set__(indices: number[], value: ParserEntity): void;
+    clear(): this;
+    /**
+     * Gets the number of current elements.
+     */
+    count(): number;
+    dimensions(): number[];
+    /**
+     * Visits or replaces elements in place.
+     * Returning `void` leaves the current element unchanged.
+     */
+    each(this: TSelf, callback: (e: ParserEntity, i?: string | number, j?: string | number) => ParserEntity | void): TSelf;
+    eq(other: ParserEntity): boolean;
+    /**
+     * Visits every current element without changing the aggregate.
+     *
+     * This is the observation-only counterpart to {@link each}. Concrete subclasses may
+     * narrow the callback element type when their membership method guarantees a more
+     * specific entity.
+     */
+    forEach(callback: (e: ParserEntity, index: number) => void): void;
+    gt(other: ParserEntity): boolean;
+    gte(other: ParserEntity): boolean;
+    lt(other: ParserEntity): boolean;
+    lte(other: ParserEntity): boolean;
+    sort(compareFn?: (a: ParserEntity, b: ParserEntity) => number): this;
+    /** Returns an iterator over the aggregate's current public element view. */
+    [Symbol.iterator](): Iterator<ParserEntity>;
+    /** Returns a new array containing the aggregate's current public element view. */
+    toArray(): ParserEntity[];
+}