nerdamer 1.1.13 → 2.0.0-rc.1

package/output/core/classes/valuesSet/ValuesSet.js

@@ -0,0 +1,381 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ValuesSet = void 0;
+const MathematicalAggregate_1 = require("../../common/classes/MathematicalAggregate");
+const common_1 = require("../../common/common");
+const errors_1 = require("../../errors");
+const constants_1 = require("../parser/constants");
+/**
+ * A finite mathematical set of Nerdamer parser values.
+ *
+ * @remarks
+ * Membership and uniqueness use each element's `eq()` method rather than JavaScript
+ * reference identity. Two members are considered equal only when both directional equality
+ * checks agree, which keeps mixed-type membership independent of insertion order. This treatment is
+ * conservative for symbolic values: if Nerdamer cannot establish that two
+ * elements are equal, they remain distinct. Values whose entity types cannot be compared are
+ * likewise treated as distinct members. In particular, set membership does not attempt theorem
+ * proving beyond the equality semantics of the stored values.
+ *
+ * `ValuesSet` owns its elements. Values passed to the constructor or {@link add} are copied,
+ * and {@link elements}, {@link at}, and indexed reads return copies. This prevents a caller
+ * from changing a stored mutable object behind the set and silently violating uniqueness.
+ * Mutation therefore goes through the set methods, which re-establish set uniqueness
+ * after every supported change.
+ *
+ * Iteration order is deterministic insertion order so text output and direct traversal are
+ * reproducible, but that order has no mathematical meaning. Equality and subset/superset
+ * comparisons are membership-based and ignore order.
+ *
+ * The arithmetic methods inherited by other structured entities are rejected
+ * here. Pairing two sets by insertion index would make arithmetic depend on a non-mathematical
+ * ordering. Use the explicit finite-set operations on this class instead.
+ */
+class ValuesSet extends MathematicalAggregate_1.MathematicalAggregate {
+    _elements = [];
+    dataType = constants_1.SET;
+    isEnumerable = true;
+    precision;
+    constructor(values) {
+        super();
+        if (values) {
+            for (const v of values) {
+                this.add(v);
+            }
+        }
+    }
+    /**
+     * Tests whether a value is a `ValuesSet` or a specialized `ValuesSet` subtype such as
+     * `SolutionSet`.
+     */
+    static isValuesSet(obj) {
+        return ((0, common_1.isNerdamerNativeType)(obj, constants_1.SET) || (0, common_1.isNerdamerNativeType)(obj, constants_1.SOLUTIONS_SET));
+    }
+    getValuesArray() {
+        return this.elements;
+    }
+    setValuesArray(values) {
+        this.clear();
+        for (const v of values) {
+            this.add(v);
+        }
+    }
+    indexOf(x) {
+        for (let i = 0; i < this._elements.length; i++) {
+            if (this.membersEqual(this._elements[i], x)) {
+                return i;
+            }
+        }
+        return -1;
+    }
+    membersEqual(a, b) {
+        let retval = false;
+        try {
+            // Parser-entity equality is not guaranteed to be symmetric across different
+            // entity types. A set must not deduplicate values based on insertion direction,
+            // so require both entities to agree that they represent the same member.
+            retval = a.eq(b) && b.eq(a);
+        }
+        catch (e) {
+            if (!(e instanceof errors_1.UnexpectedDataType)) {
+                throw e;
+            }
+        }
+        return retval;
+    }
+    /**
+     * Reads an element for parser indexing.
+     *
+     * @throws A `RangeError` if the index is outside the current set size.
+     */
+    __get__(indices) {
+        const index = indices[0];
+        if (index < 0 || index >= this._elements.length) {
+            throw new RangeError(`Index ${index} out of bounds for ${this.dataType} of length ${this._elements.length}`);
+        }
+        return this._elements[index].copy();
+    }
+    /**
+     * Replaces the insertion-order element at an index while preserving uniqueness.
+     *
+     * @remarks
+     * If the replacement is already present elsewhere in the set, the indexed element is
+     * removed instead of creating a duplicate. Indexed mutation is provided for parser
+     * compatibility; the index is not part of the mathematical identity of a set.
+     *
+     * @throws A `RangeError` if the index is outside the current set size.
+     */
+    __set__(indices, value) {
+        const index = indices[0];
+        if (index < 0 || index >= this._elements.length) {
+            throw new RangeError(`Index ${index} out of bounds for ${this.dataType} of length ${this._elements.length}`);
+        }
+        const replacement = value.copy();
+        const duplicateIndex = this.indexOf(replacement);
+        if (duplicateIndex !== -1 && duplicateIndex !== index) {
+            this._elements.splice(index, 1);
+        }
+        else {
+            this._elements[index] = replacement;
+        }
+    }
+    /** Adds an element if no semantically equal member is already present. */
+    add(x) {
+        if (!this.has(x)) {
+            this._elements.push(x.copy());
+        }
+        return this;
+    }
+    /** Adds every value in the iterable while preserving set uniqueness. */
+    addMany(x) {
+        for (const e of x) {
+            this.add(e);
+        }
+        return this;
+    }
+    /**
+     * Returns a copy of the element at the requested insertion-order index.
+     *
+     * @returns A copy of the stored value, or `undefined` when the index is out of range.
+     */
+    at(i) {
+        const value = this._elements[i];
+        return value ? value.copy() : undefined;
+    }
+    /** Removes every member from the set. */
+    clear() {
+        this._elements.length = 0;
+        return this;
+    }
+    /** Returns an independent set containing independent copies of all members. */
+    copy() {
+        return new ValuesSet(this._elements);
+    }
+    /** Returns the current number of set members. */
+    count() {
+        return this._elements.length;
+    }
+    /** Removes the member semantically equal to `x`, if one is present. */
+    delete(x) {
+        const i = this.indexOf(x);
+        if (i === -1) {
+            return false;
+        }
+        this._elements.splice(i, 1);
+        return true;
+    }
+    /** Returns a new set containing members of this set that are absent from `other`. */
+    difference(other) {
+        const retval = new ValuesSet();
+        for (const value of this._elements) {
+            if (!other.has(value)) {
+                retval.add(value);
+            }
+        }
+        return retval;
+    }
+    /** Returns the one-dimensional storage size used by parser indexing. */
+    dimensions() {
+        return [this._elements.length];
+    }
+    /**
+     * Rejects binary division because finite sets do not define elementwise quotients.
+     *
+     * @throws {@link core!UnsupportedOperationError} Always.
+     */
+    div(_x) {
+        throw new errors_1.UnsupportedOperationError((0, errors_1.message)('unsupportedOperation'));
+    }
+    /**
+     * Visits or maps the current members in insertion order.
+     *
+     * Duplicate mapped values collapse to their first occurrence. The callback receives a
+     * copy of each stored member, so mutating an input inside the callback cannot alter the
+     * set unless that value is returned. Returning `void` leaves the current member unchanged.
+     */
+    each(callback) {
+        const next = [];
+        for (let i = 0; i < this._elements.length; i++) {
+            const current = this._elements[i].copy();
+            const mapped = callback(current, i);
+            const value = mapped === undefined ? this._elements[i] : mapped;
+            // Preserve insertion order for first occurrences only.
+            let exists = false;
+            for (let k = 0; k < next.length; k++) {
+                if (this.membersEqual(next[k], value)) {
+                    exists = true;
+                    break;
+                }
+            }
+            if (!exists) {
+                next.push(value.copy());
+            }
+        }
+        this._elements = next;
+        return this;
+    }
+    /**
+     * Returns a deep-copied snapshot of the set's current elements.
+     *
+     * Mutating the returned array or its members does not change this set. Use the set's
+     * mutation methods when the stored membership should change.
+     */
+    get elements() {
+        return this._elements.map(e => e.copy());
+    }
+    /** Tests set equality by membership, independent of insertion order. */
+    eq(other) {
+        if (!ValuesSet.isValuesSet(other)) {
+            return false;
+        }
+        if (other.count() !== this.count()) {
+            return false;
+        }
+        return this.isSubsetOf(other);
+    }
+    /** Evaluates every member and returns a new set, collapsing equal results. */
+    evaluate() {
+        return this.copy().each(e => e.evaluate());
+    }
+    /** Expands every member and returns a new set, collapsing equal results. */
+    expand() {
+        return this.copy().each(e => e.expand());
+    }
+    /**
+     * Returns the proper-superset relation for compatibility with parser comparison syntax.
+     * Prefer {@link isProperSupersetOf} in direct set-oriented code.
+     */
+    gt(other) {
+        return ValuesSet.isValuesSet(other) && this.isProperSupersetOf(other);
+    }
+    /**
+     * Returns the superset relation for compatibility with parser comparison syntax.
+     * Prefer {@link isSupersetOf} in direct set-oriented code.
+     */
+    gte(other) {
+        return ValuesSet.isValuesSet(other) && this.isSupersetOf(other);
+    }
+    /** Tests whether a semantically equal member is present. */
+    has(x) {
+        return this.indexOf(x) !== -1;
+    }
+    /** Returns a new set containing only members present in both sets. */
+    intersection(other) {
+        const retval = new ValuesSet();
+        for (const value of this._elements) {
+            if (other.has(value)) {
+                retval.add(value);
+            }
+        }
+        return retval;
+    }
+    /** Returns `true` when this set has no member in common with `other`. */
+    isDisjointFrom(other) {
+        for (const value of this._elements) {
+            if (other.has(value)) {
+                return false;
+            }
+        }
+        return true;
+    }
+    /** Returns `true` when this set is a strict subset of `other`. */
+    isProperSubsetOf(other) {
+        return this.count() < other.count() && this.isSubsetOf(other);
+    }
+    /** Returns `true` when this set is a strict superset of `other`. */
+    isProperSupersetOf(other) {
+        return this.count() > other.count() && this.isSupersetOf(other);
+    }
+    /** Returns `true` when every member of this set is present in `other`. */
+    isSubsetOf(other) {
+        for (const value of this._elements) {
+            if (!other.has(value)) {
+                return false;
+            }
+        }
+        return true;
+    }
+    /** Returns `true` when every member of `other` is present in this set. */
+    isSupersetOf(other) {
+        return other.isSubsetOf(this);
+    }
+    /**
+     * Returns the proper-subset relation for compatibility with parser comparison syntax.
+     * Prefer {@link isProperSubsetOf} in direct set-oriented code.
+     */
+    lt(other) {
+        return ValuesSet.isValuesSet(other) && this.isProperSubsetOf(other);
+    }
+    /**
+     * Returns the subset relation for compatibility with parser comparison syntax.
+     * Prefer {@link isSubsetOf} in direct set-oriented code.
+     */
+    lte(other) {
+        return ValuesSet.isValuesSet(other) && this.isSubsetOf(other);
+    }
+    /**
+     * Rejects binary subtraction because finite sets do not define elementwise subtraction.
+     *
+     * @throws {@link core!UnsupportedOperationError} Always.
+     */
+    minus(_x) {
+        throw new errors_1.UnsupportedOperationError((0, errors_1.message)('unsupportedOperation'));
+    }
+    /**
+     * Binary addition is not defined for finite sets. Use {@link union} for set union.
+     *
+     * @throws {@link core!UnsupportedOperationError} Always.
+     */
+    plus(_x) {
+        throw new errors_1.UnsupportedOperationError((0, errors_1.message)('unsupportedOperation'));
+    }
+    /**
+     * Rejects binary exponentiation because finite sets do not define elementwise powers.
+     *
+     * @throws {@link core!UnsupportedOperationError} Always.
+     */
+    pow(_x) {
+        throw new errors_1.UnsupportedOperationError((0, errors_1.message)('unsupportedOperation'));
+    }
+    /**
+     * Sorts the deterministic iteration order without changing mathematical membership.
+     * A custom comparator receives copies so it cannot mutate stored members as a side effect.
+     */
+    sort(compareFn) {
+        if (compareFn) {
+            this._elements.sort((a, b) => compareFn(a.copy(), b.copy()));
+        }
+        else {
+            this._elements.sort((a, b) => {
+                const ta = a && typeof a.text === 'function' ? a.text() : String(a);
+                const tb = b && typeof b.text === 'function' ? b.text() : String(b);
+                return ta < tb ? -1 : ta > tb ? 1 : 0;
+            });
+        }
+        return this;
+    }
+    /** Returns a new set containing members present in exactly one of the two sets. */
+    symmetricDifference(other) {
+        const retval = this.difference(other);
+        retval.addMany(other.difference(this)._elements);
+        return retval;
+    }
+    text() {
+        return `{${this._elements.map(e => e.text()).join(', ')}}`;
+    }
+    /**
+     * Rejects binary multiplication because finite sets do not define elementwise products.
+     *
+     * @throws {@link core!UnsupportedOperationError} Always.
+     */
+    times(_x) {
+        throw new errors_1.UnsupportedOperationError((0, errors_1.message)('unsupportedOperation'));
+    }
+    /** Returns a new set containing members present in either set. */
+    union(other) {
+        const retval = new ValuesSet(this._elements);
+        retval.addMany(other._elements);
+        return retval;
+    }
+}
+exports.ValuesSet = ValuesSet;

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

@@ -0,0 +1,222 @@
+import { MathematicalAggregate } from '../../common/classes/MathematicalAggregate';
+import { Collection } from '../collection/Collection';
+import { Expression } from '../expression/Expression';
+import { VECTOR } from '../parser/constants';
+import { Polynomial } from '../polynomial/Polynomial';
+import type { ParserEntity, ExpressionInput, NerdamerInput } from '../../types';
+import type { ParserValuesObject } from '../parser/types';
+/**
+ * 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.
+ */
+export declare class Vector extends MathematicalAggregate<Vector> {
+    dataType: typeof VECTOR;
+    elements: ParserEntity[];
+    isEnumerable: boolean;
+    precision?: number | undefined;
+    /** Creates a Vector from normalized input values or a copied Collection. */
+    constructor(elements?: NerdamerInput[] | Collection);
+    /** Creates an Expression-only Vector from expression-compatible inputs. */
+    static create(v: ExpressionInput[]): Vector;
+    static isVector(obj: unknown): obj is Vector;
+    protected getValuesArray(): ParserEntity[];
+    protected setValuesArray(values: ParserEntity[]): void;
+    /**
+     * 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: number[]): ParserEntity;
+    /** Appends an existing parser entity by reference and returns this Vector. */
+    add(x: ParserEntity): this;
+    /**
+     * Appends an existing parser entity by reference.
+     * @param e - Element to append.
+     */
+    append(e: ParserEntity): this;
+    arrayMap(callback: (e: ParserEntity) => unknown): unknown[];
+    /**
+     * 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: number): ParserEntity | undefined;
+    /**
+     * Removes all elements from the vector.
+     */
+    clear(): this;
+    /** Copies the Vector and every contained entity. */
+    copy(): Vector;
+    /**
+     * Gets the number of current elements in the Vector.
+     * @returns Current length.
+     */
+    count(): number;
+    /**
+     * 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: Vector): Vector;
+    delete(x: ParserEntity): boolean;
+    dimensions(): number[];
+    /**
+     * 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: NerdamerInput): Vector;
+    /**
+     * 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: Vector): Expression;
+    /**
+     * Visits or replaces elements in ascending index order.
+     * Returning `void` leaves the current element unchanged.
+     */
+    each(callback: (e: ParserEntity, i: number) => ParserEntity | void): this;
+    eq(V: ParserEntity): boolean;
+    /** Evaluates a copied Vector, resolving symbolic bracket access when values are supplied. */
+    evaluate(): Vector;
+    evaluate(values: ParserValuesObject): ParserEntity;
+    /** Expands a copied Vector, leaving this one unchanged. */
+    expand(): Vector;
+    /**
+     * 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: ParserEntity): 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: number): Expression;
+    gt(V: ParserEntity): boolean;
+    gte(V: ParserEntity): boolean;
+    /**
+     * 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: ParserEntity): number;
+    /**
+     * 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: number, x: ParserEntity): this;
+    lt(V: ParserEntity): boolean;
+    lte(V: ParserEntity): boolean;
+    /**
+     * Subtracts corresponding elements, or broadcasts a scalar subtrahend.
+     *
+     * @throws {@link core!DimensionError} If a Vector operand has a different length.
+     */
+    minus(x: NerdamerInput): Vector;
+    /**
+     * Returns the Euclidean norm `sqrt(sum(abs(element)^2))`.
+     * @throws {@link core!UnexpectedDataType} If any element is not an Expression.
+     */
+    norm(): Expression;
+    /**
+     * Adds corresponding elements, or broadcasts a scalar addend.
+     *
+     * @throws {@link core!DimensionError} If a Vector operand has a different length.
+     */
+    plus(x: NerdamerInput): Vector;
+    /**
+     * 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?: number): ParserEntity | undefined;
+    /**
+     * Raises corresponding elements to powers, or broadcasts a scalar exponent.
+     *
+     * @throws {@link core!DimensionError} If a Vector exponent has a different length.
+     */
+    pow(x: NerdamerInput): Vector;
+    /**
+     * 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(): Expression;
+    /**
+     * 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: ParserEntity): this;
+    /**
+     * Reverses the Vector in place.
+     * @returns This Vector.
+     */
+    reverse(): 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(): Expression;
+    text(): string;
+    /**
+     * 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: NerdamerInput): Vector;
+    /** Interprets ordered elements as ascending polynomial coefficients. */
+    toPolynomial(vars?: string[]): Polynomial;
+    /**
+     * Removes every element equal to zero.
+     * @returns This mutated Vector.
+     */
+    trim(): this;
+}