@pacem/pacem-numerical 1.0.0-bernoulli → 1.0.0-binet

package/dist/browser/pacem-numerical.js

@@ -1,5 +1,5 @@
 /*!
- * @pacem/pacem-numerical v1.0.0-bernoulli (https://js.pacem.it)
+ * @pacem/pacem-numerical v1.0.0-binet (https://js.pacem.it)
  * Pacem (https://pacem.it)
  * Licensed under Apache-2.0
  */
@@ -17,9 +17,17 @@
             this.normalize(clone);
             return clone;
         }
+        /**
+         * Returns the squared magnitude (length) of the vector. Cheaper than {@link mag} since it avoids the square root.
+         * @param v
+         */
         static magSqr(v) {
             return v.x * v.x + v.y * v.y;
         }
+        /**
+         * Returns the magnitude (length) of the vector.
+         * @param v
+         */
         static mag(v) {
             return Math.sqrt(Vector.magSqr(v));
         }
@@ -239,7 +247,32 @@
     // This implementation is self-contained, numerically robust (small epsilon), and works with floating-point coordinates.
     // It assumes general position (no four points exactly cocircular). For production use with degenerate cases,
     // you may want to add a tiny random jitter to the points if needed.
+    /**
+     * Computes the (unconstrained) 2D Delaunay triangulation of a set of points, using the
+     * incremental Bowyer-Watson algorithm.
+     *
+     * A Delaunay triangulation connects a set of points into triangles such that no point lies
+     * strictly inside the circumcircle of any triangle. Among all the ways a point set can be
+     * triangulated, this property makes it the one that maximizes the minimum angle of all the
+     * triangles, avoiding thin "sliver" triangles — which is why it's the standard choice for
+     * meshes, terrain modeling, and (via its dual) Voronoi diagrams.
+     *
+     * The Bowyer-Watson algorithm builds the triangulation incrementally: starting from a single
+     * "super triangle" that encloses every input point, each point is inserted one at a time by
+     * removing every existing triangle whose circumcircle contains it (which necessarily leaves a
+     * star-shaped polygonal hole around the new point) and re-triangulating that hole by connecting
+     * the new point to the hole's boundary edges. Once every point has been inserted, any triangle
+     * still touching a vertex of the initial super triangle is discarded, leaving the final
+     * triangulation of the original points.
+     */
     class Delaunay {
+        /**
+         * Computes the Delaunay triangulation of the given points.
+         * @param vertices Points to triangulate.
+         * @returns A flat array of triangle indices into {@link vertices} (each consecutive group of 3
+         * entries identifies one triangle), in the same "vertices + triangle indices" format used by
+         * most graphics/meshing libraries. Returns an empty array if fewer than 3 points are provided.
+         */
         static triangulate(vertices) {
             return delaunayTriangulation(vertices);
         }
@@ -256,6 +289,7 @@
         return s != null && Array.isArray(s) && s.length === 2
             && isPoint(s[0]) && isPoint(s[1]);
     }
+    /** Utility tools for 2D geometry: points, segments, polygons and their interactions. */
     let Utils$2 = class Utils {
         /**
          * Computes the slope (in radians) of the segment joining two points.
@@ -303,6 +337,11 @@
                 return null;
             }
         }
+        /**
+         * Computes the axis-aligned bounding box of a set of points.
+         * @param vertices Points to enclose.
+         * @returns The smallest rect containing all provided points.
+         */
         static boundingBox(vertices) {
             let xmin = Number.MAX_VALUE, ymin = Number.MAX_VALUE, xmax = -Number.MAX_VALUE, ymax = -Number.MAX_VALUE;
             vertices.length;
@@ -314,6 +353,15 @@
             }
             return { x: xmin, y: ymin, width: xmax - xmin, height: ymax - ymin };
         }
+        /**
+         * Combines two polygons using a boolean set operator (union, intersection or difference).
+         * Internally triangulates the merged vertex set (via {@link mesh}) and filters the resulting
+         * triangles by whether their barycenter falls inside either source polygon.
+         * @param polygon1 First polygon.
+         * @param polygon2 Second polygon.
+         * @param operator Boolean operator to apply.
+         * @returns The resulting polygon(s), plus the underlying triangulation mesh and triangles used to compute them; or `null` if the operation yields no polygon.
+         */
         static combinePolygons(polygon1, polygon2, operator) {
             return Utils._mergePolygons(polygon1, polygon2, operator);
         }
@@ -720,6 +768,12 @@
             const minx = Math.min(segment[0].x, segment[1].x), maxx = Math.max(segment[0].x, segment[1].x), miny = Math.min(segment[0].y, segment[1].y), maxy = Math.max(segment[0].y, segment[1].y);
             return p.x >= minx && p.x <= maxx && p.y >= miny && p.y <= maxy && Utils.inLine(p, segment, precision);
         }
+        /**
+         * Checks whether a point lies inside (or on the boundary of) a triangle, by verifying that it
+         * is on the same rotational side of all three edges.
+         * @param p Point to test.
+         * @param triangle Triangle vertices.
+         */
         static inTriangle(p, triangle) {
             let last;
             for (let j = 0; j < 3; j++) {
@@ -850,24 +904,52 @@
             && (vertices = obj.vertices).length >= 3
             && vertices.every(i => pacemFoundation.Point.isPoint(i));
     }
+    /** Utility tools to build and inspect {@link Polygon}s. */
     class Polygon {
         static { this._eps = 1e-12; }
+        /**
+         * Type guard checking whether the provided value is a valid {@link Polygon} (has at least 3 point vertices).
+         * @param obj
+         */
         static isPolygon(obj) {
             return isPolygon(obj);
         }
+        /**
+         * Builds a polygon from the provided vertices, in order.
+         * @param points Vertices of the polygon.
+         */
         static from(...points) {
             return { vertices: Array.from(points) };
         }
+        /**
+         * Checks whether a point lies inside the polygon.
+         * @param polygon
+         * @param p Point to test.
+         */
         static contains(polygon, p) {
             return Utils$2.inPolygon(p, polygon.vertices, 12);
         }
+        /**
+         * Returns the center of the polygon's bounding box.
+         * Note: this is not the geometric centroid (center of mass) for non-symmetric polygons.
+         * @param polygon
+         */
         static centroid(polygon) {
             const bbox = Polygon.boundingBox(polygon);
             return { x: bbox.x + bbox.width / 2, y: bbox.y + bbox.height / 2 };
         }
+        /**
+         * Computes the axis-aligned bounding box of the polygon.
+         * @param polygon
+         */
         static boundingBox(polygon) {
             return Utils$2.boundingBox(polygon.vertices);
         }
+        /**
+         * Returns the polygon's edges as an ordered list of segments, each joining a vertex to the next
+         * (the last one wrapping back to the first).
+         * @param polygon
+         */
         static sides(polygon) {
             const { vertices } = polygon;
             const retval = [];
@@ -877,6 +959,10 @@
             }
             return retval;
         }
+        /**
+         * Checks whether the polygon is convex, i.e. all its interior angles turn in the same rotational direction.
+         * @param polygon
+         */
         static isConvex(polygon) {
             const { vertices } = polygon, l = vertices.length;
             if (l <= 3) {
@@ -965,6 +1051,12 @@
         static area(polygon) {
             return Utils$2.area(polygon.vertices);
         }
+        /**
+         * Computes the intersection area(s) between two polygons.
+         * @param polygon1
+         * @param polygon2
+         * @returns The overlapping area(s) as one or more polygons.
+         */
         static intersect(polygon1, polygon2) {
             return Utils$2.intersect(polygon1, polygon2);
         }
@@ -983,7 +1075,13 @@
     // namespace Pacem.Geometry.LinearAlgebra {
     const RAD2DEG = 180.0 / Math.PI;
     const DEG2RAD = 1.0 / RAD2DEG;
+    /** 3D vector utils. */
     class Vector3D {
+        /**
+         * Builds a {@link Vector3D} from its x, y, z components, in that order.
+         * @param args Exactly 3 numbers: x, y, z.
+         * @throws If the number of arguments is not exactly 3.
+         */
         static from(...args) {
             const l = 3;
             if (args.length !== l) {
@@ -991,6 +1089,11 @@
             }
             return { x: args[0], y: args[1], z: args[2] };
         }
+        /**
+         * Parses a string representation (e.g. `"1 2 3"` or `"1,2,3"`) into a {@link Vector3D}.
+         * @param input String to parse.
+         * @throws If the input cannot be parsed as exactly 3 numbers.
+         */
         static parse(input) {
             const arr = pacemFoundation.parseAsNumericalArray(input);
             if (arr && arr.length === 3) {
@@ -999,15 +1102,19 @@
             throw new Error(`Cannot parse "${input}" as a valid Vector3D.`);
         }
         // notable vectors
+        /** Returns the unit vector along the x axis: `(1, 0, 0)`. */
         static i() {
             return { x: 1, y: 0, z: 0 };
         }
+        /** Returns the unit vector along the y axis: `(0, 1, 0)`. */
         static j() {
             return { x: 0, y: 1, z: 0 };
         }
+        /** Returns the unit vector along the z axis: `(0, 0, 1)`. */
         static k() {
             return { x: 0, y: 0, z: 1 };
         }
+        /** Returns the zero vector: `(0, 0, 0)`. */
         static zero() {
             return { x: 0, y: 0, z: 0 };
         }
@@ -1055,6 +1162,10 @@
         static scale(v, fx, fy = fx, fz = fx) {
             return { x: v.x * fx, y: v.y * fy, z: v.z * fz };
         }
+        /**
+         * Returns the squared magnitude (length) of the vector. Cheaper than {@link mag} since it avoids the square root.
+         * @param v
+         */
         static magSqr(v) {
             return v.x * v.x + v.y * v.y + v.z * v.z;
         }
@@ -1069,9 +1180,17 @@
                 && (v2.y - v1.y).isCloseTo(0)
                 && (v2.z - v1.z).isCloseTo(0);
         }
+        /**
+         * Returns the magnitude (length) of the vector.
+         * @param v
+         */
         static mag(v) {
             return Math.sqrt(Vector3D.magSqr(v));
         }
+        /**
+         * Returns the opposite vector (each component negated).
+         * @param v
+         */
         static negate(v) {
             return { x: -v.x, y: -v.y, z: -v.z };
         }
@@ -1121,6 +1240,10 @@
             return RAD2DEG * num;
         }
     }
+    /**
+     * Utilities to convert between spherical coordinates (radial distance `rho`, azimuth `theta` and
+     * polar angle `phi`) and their cartesian ({@link Vector3D}) or rotation-matrix ({@link Matrix3D}) equivalents.
+     */
     class Spherical {
         /**
          * Creates a new {@link Spherical} object.
@@ -1143,6 +1266,10 @@
             const theta = Math.atan2(v.x, v.z), phi = Math.acos((v.y / rho).clamp(-1, 1));
             return Spherical.from(rho, theta * RAD2DEG, phi * RAD2DEG);
         }
+        /**
+         * Converts {@link Spherical} coordinates back into cartesian {@link Vector3D} coordinates.
+         * @param coords
+         */
         static toVector(coords) {
             const { rho, theta: thetaDeg, phi: phiDeg } = coords;
             const phi = phiDeg * DEG2RAD;
@@ -1202,6 +1329,7 @@
             return Matrix3D.from((((m1.m11 * m2.m11) + (m1.m12 * m2.m21)) + (m1.m13 * m2.m31)) + (m1.m14 * m2.offsetX), (((m1.m11 * m2.m12) + (m1.m12 * m2.m22)) + (m1.m13 * m2.m32)) + (m1.m14 * m2.offsetY), (((m1.m11 * m2.m13) + (m1.m12 * m2.m23)) + (m1.m13 * m2.m33)) + (m1.m14 * m2.offsetZ), (((m1.m11 * m2.m14) + (m1.m12 * m2.m24)) + (m1.m13 * m2.m34)) + (m1.m14 * m2.m44), (((m1.m21 * m2.m11) + (m1.m22 * m2.m21)) + (m1.m23 * m2.m31)) + (m1.m24 * m2.offsetX), (((m1.m21 * m2.m12) + (m1.m22 * m2.m22)) + (m1.m23 * m2.m32)) + (m1.m24 * m2.offsetY), (((m1.m21 * m2.m13) + (m1.m22 * m2.m23)) + (m1.m23 * m2.m33)) + (m1.m24 * m2.offsetZ), (((m1.m21 * m2.m14) + (m1.m22 * m2.m24)) + (m1.m23 * m2.m34)) + (m1.m24 * m2.m44), (((m1.m31 * m2.m11) + (m1.m32 * m2.m21)) + (m1.m33 * m2.m31)) + (m1.m34 * m2.offsetX), (((m1.m31 * m2.m12) + (m1.m32 * m2.m22)) + (m1.m33 * m2.m32)) + (m1.m34 * m2.offsetY), (((m1.m31 * m2.m13) + (m1.m32 * m2.m23)) + (m1.m33 * m2.m33)) + (m1.m34 * m2.offsetZ), (((m1.m31 * m2.m14) + (m1.m32 * m2.m24)) + (m1.m33 * m2.m34)) + (m1.m34 * m2.m44), (((m1.offsetX * m2.m11) + (m1.offsetY * m2.m21)) + (m1.offsetZ * m2.m31)) + (m1.m44 * m2.offsetX), (((m1.offsetX * m2.m12) + (m1.offsetY * m2.m22)) + (m1.offsetZ * m2.m32)) + (m1.m44 * m2.offsetY), (((m1.offsetX * m2.m13) + (m1.offsetY * m2.m23)) + (m1.offsetZ * m2.m33)) + (m1.m44 * m2.offsetZ), (((m1.offsetX * m2.m14) + (m1.offsetY * m2.m24)) + (m1.offsetZ * m2.m34)) + (m1.m44 * m2.m44));
         }
     }
+    /** Utilities to build, combine and invert 4x4 transformation matrices ({@link Matrix3D}) in 3D space. */
     class Matrix3D {
         //#region notable matrices
         /**
@@ -1217,6 +1345,11 @@
             };
         }
         //#endregion
+        /**
+         * Builds a {@link Matrix3D} from its 16 components, in row-major order.
+         * @param args Exactly 16 numbers.
+         * @throws If the number of arguments is not exactly 16.
+         */
         static from(...args) {
             const l = 16;
             if (args.length !== l) {
@@ -1241,9 +1374,17 @@
                 m44: args[15]
             };
         }
+        /**
+         * Returns the transpose of the given matrix (rows and columns swapped).
+         * @param m
+         */
         static transpose(m) {
             return Matrix3D.from(m.m11, m.m21, m.m31, m.offsetX, m.m12, m.m22, m.m32, m.offsetY, m.m13, m.m23, m.m33, m.offsetZ, m.m14, m.m24, m.m34, m.m44);
         }
+        /**
+         * Flattens the matrix into a 16-number array, in row-major order (the same order accepted by {@link from}).
+         * @param m
+         */
         static toArray(m) {
             return [m.m11, m.m12, m.m13, m.m14,
                 m.m21, m.m22, m.m23, m.m24,
@@ -1269,6 +1410,11 @@
                 s.m33 *= z;
             });
         }
+        /**
+         * Returns a copy of the matrix translated (offset) by the given vector.
+         * @param m
+         * @param offset
+         */
         static translate(m, offset) {
             return Matrix3DUtils.modify(m, s => {
                 s.offsetX += offset.x;
@@ -1276,6 +1422,11 @@
                 s.offsetZ += offset.z;
             });
         }
+        /**
+         * Parses a string representation of a matrix (16 numbers) into a {@link Matrix3D}.
+         * @param input String to parse.
+         * @throws If the input cannot be parsed as exactly 16 numbers.
+         */
         static parse(input) {
             const arr = pacemFoundation.parseAsNumericalArray(input);
             if (arr && arr.length === 16) {
@@ -1283,15 +1434,28 @@
             }
             throw new Error(`Cannot parse "${input}" as a valid Matrix3D.`);
         }
+        /**
+         * Checks whether the matrix is the identity matrix.
+         * @param m
+         */
         static isIdentity(m) {
             return m.m11 == 1.0 && m.m12 == .0 && m.m13 == .0 && m.m14 == .0
                 && m.m21 == .0 && m.m22 == 1.0 && m.m23 == .0 && m.m24 == .0
                 && m.m31 == .0 && m.m32 == .0 && m.m33 == 1.0 && m.m34 == .0
                 && m.offsetX == .0 && m.offsetY == .0 && m.offsetZ == .0 && m.m44 == 1.0;
         }
+        /**
+         * Checks whether the matrix represents a pure affine transform, i.e. it has no perspective
+         * component (its 4th column is `(0, 0, 0, 1)`).
+         * @param m
+         */
         static isAffine(m) {
             return m.m14 == .0 && m.m24 == .0 && m.m34 == .0 && m.m44 == 1.0;
         }
+        /**
+         * Computes the determinant of the matrix.
+         * @param m
+         */
         static determinant(m) {
             if (Matrix3D.isIdentity(m)) {
                 return 1.0;
@@ -1332,6 +1496,12 @@
             }
             return m;
         }
+        /**
+         * Computes the inverse of the matrix, using the cofactor/adjugate method (with a specialized,
+         * cheaper path for affine matrices).
+         * @param m
+         * @returns The inverse matrix, or `null` if the matrix is singular (determinant is 0).
+         */
         static invert(m) {
             if (Matrix3D.isAffine(m)) {
                 // normalize affine invert
@@ -1436,10 +1606,17 @@
             return pt;
         }
     }
+    /** Utilities to build, combine and convert {@link Quaternion} rotations. */
     class Quaternion {
+        /** Returns the identity quaternion (no rotation). */
         static identity() {
             return Quaternion.from(0, 0, 0, 1);
         }
+        /**
+         * Builds a {@link Quaternion} from its x, y, z, w components, in that order.
+         * @param args Exactly 4 numbers: x, y, z, w.
+         * @throws If the number of arguments is not exactly 4.
+         */
         static from(...args) {
             const l = 4;
             if (args.length !== l) {
@@ -1452,6 +1629,11 @@
                 w: args[3],
             };
         }
+        /**
+         * Parses a string representation of a quaternion (4 numbers) into a {@link Quaternion}.
+         * @param input String to parse.
+         * @throws If the input cannot be parsed as exactly 4 numbers.
+         */
         static parse(input) {
             const arr = pacemFoundation.parseAsNumericalArray(input);
             if (arr && arr.length === 4) {
@@ -1459,6 +1641,12 @@
             }
             throw new Error(`Cannot parse "${input}" as a valid Quaternion.`);
         }
+        /**
+         * Builds the (shortest-arc) quaternion representing the rotation that takes one unit vector onto another.
+         * Normalizes both input vectors in place as a side effect.
+         * @param from Source direction.
+         * @param to Target direction.
+         */
         static fromVectors(from, to) {
             // setup
             Vector3D.normalize(from);
@@ -1566,6 +1754,11 @@
                 }
             }
         }
+        /**
+         * Returns the conjugate of the quaternion (vector part negated). For a unit quaternion, this
+         * represents the inverse rotation.
+         * @param q
+         */
         static conjugate(q) {
             return Quaternion.from(-q.x, -q.y, -q.z, q.w);
         }
@@ -1576,15 +1769,29 @@
         static mag(q) {
             return Math.sqrt(q.x * q.x + q.y * q.y + q.z * q.z + q.w * q.w);
         }
+        /**
+         * Returns the squared magnitude of the vector (imaginary) part of the quaternion.
+         * @param q
+         */
         static norm(q) {
             return (q.x * q.x + q.y * q.y + q.z * q.z);
         }
+        /**
+         * Returns the (unit) rotation axis represented by the quaternion, defaulting to the y axis
+         * when the quaternion has no vector part (i.e. represents no rotation).
+         * @param q
+         */
         static axis(q) {
             if (q.x == .0 && q.y == .0 && q.z == .0) {
                 return Vector3D.j();
             }
             return Vector3D.unit(q);
         }
+        /**
+         * Rotates a vector by the given quaternion (normalizes the quaternion in place as a side effect).
+         * @param v Vector to rotate.
+         * @param q Rotation quaternion.
+         */
         static transform(v, q) {
             Quaternion.normalize(q);
             const cross = Vector3D.cross(q, v);
@@ -1613,6 +1820,10 @@
             }
             return (Math.atan2(y, x) * 114.59155902616465);
         }
+        /**
+         * Builds the rotation matrix equivalent to the given quaternion.
+         * @param q
+         */
         static toRotationMatrix(q) {
             var m = Matrix3D.identity();
             var X = q.x;
@@ -1630,6 +1841,10 @@
             m.m33 = 1.0 - 2.0 * X * X - 2.0 * Y * Y;
             return m;
         }
+        /**
+         * Returns the inverse rotation of the given quaternion (the conjugate of its normalized form).
+         * @param q
+         */
         static invert(q) {
             const n = Quaternion.unit(q);
             return Quaternion.conjugate(n);
@@ -1657,6 +1872,7 @@
 
     //namespace Pacem.Geometry {
     //#region Utils
+    /** Utility tools for 3D geometry: rays, triangles and their interactions. */
     class Utils3D {
         /**
          * Computes the intersection between a ray and a triangle in the 3D space - if any - using the Möller–Trumbore algorithm.
@@ -1731,6 +1947,7 @@
     function nac() {
         return NOT_A_COMPLEX || (NOT_A_COMPLEX = buildComplex(Number.NaN, Number.NaN));
     }
+    /** Utility tools to build and operate on {@link Complex} numbers. */
     class Complex {
         static build(real, img) {
             if (this.isComplex(real)) {
@@ -1742,20 +1959,41 @@
             }
             return buildComplex(real, img || 0);
         }
+        /**
+         * Adds two complex numbers (real numbers are treated as having a zero imaginary part).
+         * @param a First addend.
+         * @param b Second addend.
+         */
         static add(a, b) {
             const ac = complex(a), bc = complex(b);
             return buildComplex(ac.real + bc.real, ac.img + bc.img);
         }
+        /**
+         * Subtracts one complex number from another.
+         * @param from Minuend.
+         * @param what Subtrahend.
+         */
         static subtract(from, what) {
             const ac = complex(from), bc = complex(what);
             return buildComplex(ac.real - bc.real, ac.img - bc.img);
         }
+        /**
+         * Multiplies two complex numbers.
+         * @param a First factor.
+         * @param b Second factor.
+         */
         static multiply(a, b) {
             const ac = complex(a), bc = complex(b);
             return buildComplex(
             /* real*/ ac.real * bc.real - ac.img * bc.img, 
             /* img */ ac.real * bc.img + ac.img * bc.real);
         }
+        /**
+         * Divides one complex number by another.
+         * @param a Dividend.
+         * @param b Divisor.
+         * @returns The quotient, or {@link Complex.NaC} if the divisor is (close to) zero.
+         */
         static divide(a, b) {
             const ac = complex(a), bc = complex(b);
             const div = this.absSquare(bc).roundoff();
@@ -1767,20 +2005,42 @@
             /* real*/ inv_div * (ac.real * bc.real + ac.img * bc.img), 
             /* img */ inv_div * (ac.img * bc.real - ac.real * bc.img));
         }
+        /**
+         * Returns the squared modulus (|z|²) of the complex number, i.e. real² + img².
+         * Cheaper than {@link modulus} since it avoids the square root.
+         * @param c
+         */
         static absSquare(c) {
             const ac = complex(c);
             return Math.pow(ac.real, 2) + Math.pow(ac.img, 2);
         }
+        /**
+         * Returns the modulus (magnitude) of the complex number.
+         * @param c
+         */
         static modulus(c) {
             return Math.sqrt(this.absSquare(c));
         }
+        /**
+         * Type guard checking whether the provided value is a {@link Complex} number.
+         * @param c
+         */
         static isComplex(c) {
             return c != null && typeof c === 'object' && 'real' in c && 'img' in c && typeof c.real === 'number' && typeof c.img === 'number';
         }
+        /**
+         * Returns the complex conjugate: same real part, negated imaginary part.
+         * @param a
+         */
         static conjugate(a) {
             a = complex(a);
             return buildComplex(a.real, Math.abs(a.img) == 0 ? 0 : -a.img);
         }
+        /**
+         * Checks whether two complex numbers have the same real and imaginary parts.
+         * @param c1
+         * @param c2
+         */
         static equals(c1, c2) {
             const c_1 = this.build(c1), c_2 = this.build(c2);
             if (!this.isComplex(c1) || !this.isComplex(c2)) {
@@ -1800,6 +2060,7 @@
         //            if (!this.isComplex(  c)
         //    }
         //}
+        /** The "Not a Complex" sentinel value (`NaN + NaNi`), returned by operations on invalid input. */
         static get NaC() { return nac(); }
     }
     //}
@@ -1840,6 +2101,7 @@
         }
         return retval;
     }
+    /** Discrete Fourier Transform (DFT) utilities, including a Cooley-Tukey FFT fast path for power-of-two inputs. */
     class Fourier {
         /**
          * Checks the input vector and outputs a frequency vector using the best performing algo.
@@ -1913,12 +2175,19 @@
                 t * (-0.82215223 + t * 0.17087277)))))))));
         return x >= 0.0 ? ans : 2.0 - ans;
     }
+    /** Represents a Gaussian (normal) distribution and exposes its density and cumulative probability functions. */
     class Gaussian {
+        /**
+         * Creates a new {@link Gaussian} distribution with the given mean and standard deviation.
+         * @param mean Mean (μ) of the distribution.
+         * @param stdev Standard deviation (σ) of the distribution (its absolute value is used).
+         */
         constructor(mean, stdev) {
             this.mean = mean;
             this.stdev = Math.abs(stdev);
             this.variance = Math.pow(stdev, 2);
         }
+        /** The standard normal distribution (mean 0, standard deviation 1). */
         static get normal() {
             return _normal;
         }
@@ -1955,7 +2224,13 @@
     const _normal = new Gaussian(0, 1);
     //}
 
+    /**
+     * Lagrange polynomial interpolation, evaluated using the numerically stable barycentric form.
+     * Given a set of `(x, y)` points, builds the unique polynomial of minimal degree passing through
+     * all of them and evaluates it at arbitrary x values.
+     */
     class Lagrange {
+        /** Use {@link Lagrange.create} to build an instance. */
         constructor(points) {
             this.#set = points;
         }
@@ -2031,6 +2306,11 @@
         }
         // Iterative/global Lagrange computation removed — barycentric is used
         // exclusively for interpolation.
+        /**
+         * Evaluates the Lagrange interpolating polynomial at the given x, using barycentric weights.
+         * @param x Input value.
+         * @returns The interpolated y value (the exact node y if x coincides with a node).
+         */
         interpolate(x) {
             return this._computeBarycentric(x);
         }
@@ -2052,7 +2332,14 @@
     const Lagrangian = {
         create: Lagrange.create
     };
+    /**
+     * Piecewise Cubic Hermite Interpolating Polynomial (PCHIP).
+     * Builds a shape-preserving (monotonicity-respecting) piecewise-cubic curve through a set of
+     * `(x, y)` points: unlike {@link Lagrange}, it does not overshoot between nodes, at the cost of
+     * only being C¹ (continuous first derivative, not second).
+     */
     class Pchip {
+        /** Use {@link Pchip.create} to build an instance. */
         constructor(points) {
             if (!points || points.length < 2)
                 throw new Error('Need at least 2 points');
@@ -2104,6 +2391,12 @@
             }
             return m;
         }
+        /**
+         * Evaluates the PCHIP curve at the given x, using cubic Hermite interpolation on the enclosing segment.
+         * Values outside the node range are linearly extrapolated using the boundary derivative.
+         * @param x Input value.
+         * @returns The interpolated y value.
+         */
         interpolate(x) {
             const xs = this.xs, ys = this.ys, ms = this.ms;
             const n = xs.length;
@@ -2148,7 +2441,14 @@
             return new Pchip(points);
         }
     }
+    /**
+     * Newton's divided-difference polynomial interpolation.
+     * Builds the same interpolating polynomial as {@link Lagrange} but represents it in Newton form
+     * (a nested/Horner-like product of divided differences), which is efficient to evaluate and to
+     * extend incrementally as new points are added.
+     */
     class Newton {
+        /** Use {@link Newton.create} to build an instance. */
         constructor(points) {
             if (!points || points.length === 0)
                 throw new Error('Need at least 1 point');
@@ -2167,6 +2467,11 @@
             }
             this.coeffs = a;
         }
+        /**
+         * Evaluates the Newton form of the interpolating polynomial at the given x, via nested multiplication.
+         * @param x Input value.
+         * @returns The interpolated y value (`NaN` if the interpolator has no points).
+         */
         interpolate(x) {
             const xs = this.xs, a = this.coeffs;
             const n = a.length;
@@ -2386,6 +2691,7 @@
         const fn = searchFnFactory(minAssigner, maxAssigner);
         return fn(left, right, weight, tolerance);
     };
+    /** Ready-made {@link SearchFunction} implementations for unimodal minimum-search over an interval. */
     const SearchFunctions = {
         /**
          * Creates a linear search function.
@@ -2416,6 +2722,12 @@
     const OUT_OF_RANGE = `Radix out of range: possible values go between positive 1 exclusive and ${ALPHABET.length} inclusive`;
     /** Utility tools about number theory, 'diophantine' stuff... */
     class Utils {
+        /**
+         * Computes the least common multiple (LCM) of the given numbers (each rounded to the nearest integer).
+         * @param args Two or more numbers.
+         * @returns The least common multiple.
+         * @throws If fewer than two numbers are provided.
+         */
         static lcd(...args) {
             if (pacemFoundation.NullChecker.isNullOrEmpty(args) || args.length <= 1) {
                 throw 'Insufficient set of numbers.';
@@ -2434,6 +2746,12 @@
             }
             return result;
         }
+        /**
+         * Computes the greatest common divisor (GCD) of two numbers (each rounded to the nearest integer)
+         * using the Euclidean algorithm.
+         * @param a
+         * @param b
+         */
         static gcd(a, b) {
             // force integers
             a = Math.round(a),
@@ -2443,9 +2761,26 @@
             }
             return Utils.gcd(b % a, a);
         }
+        /**
+         * Converts an integer value from one numeric base (radix) to another.
+         * @param v Value to convert, in the source radix.
+         * @param from Source radix.
+         * @param to Target radix.
+         * @returns The value re-expressed in the target radix, as a string.
+         */
         static rebaseInt(v, from, to) {
             return pacemFoundation.Numbers.rebase(v, from, to);
         }
+        /**
+         * Converts a (possibly fractional) numeric value from one radix to another, dispatching to the
+         * appropriate specialized conversion routine depending on whether base-10 is the source, the
+         * target, or neither.
+         * @param v Value to convert, in the source radix.
+         * @param fromRadix Source radix.
+         * @param toRadix Target radix.
+         * @param precision Maximum number of digits to compute for the fractional part (default 12).
+         * @returns The converted value: a number when converting to base 10, otherwise a string.
+         */
         static rebaseFloat(v, fromRadix, toRadix, precision = 12) {
             const from10 = Utils.rebaseFloat10ToN, to10 = Utils.rebaseFloatNTo10;
             if (fromRadix === 10) {
@@ -2461,6 +2796,14 @@
             const _10 = to10(v.toString(), fromRadix, precision + 1);
             return from10(_10, toRadix, precision);
         }
+        /**
+         * Converts a numeric string expressed in the given radix into its base-10 (decimal) value.
+         * @param v Value to convert, expressed in the source radix (digits from `0-9a-z`).
+         * @param radix Source radix (must be greater than 1 and no larger than the size of the digit alphabet).
+         * @param precision Unused for the integer part; reserved for symmetry with the sibling conversion methods.
+         * @returns The base-10 numeric value, or `NaN` if the input contains invalid digits.
+         * @throws If radix is out of range.
+         */
         static rebaseFloatNTo10(v, radix, precision = 12) {
             const alphabet = ALPHABET;
             if (radix <= 1 || radix > alphabet.length) {
@@ -2486,6 +2829,14 @@
             }
             return sign * retval;
         }
+        /**
+         * Converts a base-10 number into its representation in another **integer** radix.
+         * @param v Base-10 value to convert.
+         * @param radix Target integer radix (must be greater than 1 and no larger than the size of the digit alphabet).
+         * @param precision Maximum number of digits to compute for the fractional part (default 12).
+         * @returns The value re-expressed in the target radix, as a string.
+         * @throws If radix is out of range.
+         */
         static rebaseFloat10ToNIntBase(v, radix, precision = 12) {
             const alphabet = ALPHABET;
             if (radix <= 1 || radix > alphabet.length) {
@@ -2540,6 +2891,14 @@
             }
             return (Math.sign(v) < 0 ? '-' : '') + output + '.' + rebasedFrac.replace(/0+$/, '');
         }
+        /**
+         * Converts a base-10 number into its representation in another (possibly non-integer) radix.
+         * @param v Base-10 value to convert.
+         * @param radix Target radix, possibly fractional (must be greater than 1 and no larger than the size of the digit alphabet).
+         * @param precision Maximum number of digits to compute for the fractional part (default 12).
+         * @returns The value re-expressed in the target radix, as a string.
+         * @throws If radix is out of range.
+         */
         static rebaseFloat10ToN(v, radix, precision = 12) {
             const alphabet = ALPHABET;
             if (radix <= 1 || radix > alphabet.length) {