ootk 3.0.0 → 4.0.0-1

package/src/optimize/DownhillSimplex.ts

@@ -0,0 +1,212 @@
+/**
+ * @author @thkruz Theodore Kruczek
+ * @license AGPL-3.0-or-later
+ * @copyright (c) 2020-2024 Theodore Kruczek
+ *
+ * Orbital Object ToolKit is free software: you can redistribute it and/or modify it under the
+ * terms of the GNU Affero General Public License as published by the Free Software
+ * Foundation, either version 3 of the License, or (at your option) any later version.
+ *
+ * Orbital Object ToolKit is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
+ * without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+ * See the GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License along with
+ * Orbital Object ToolKit. If not, see <http://www.gnu.org/licenses/>.
+ */
+
+import { CostFunction, SimplexEntry } from './SimplexEntry';
+
+// / Derivative-free Nelder-Mead simplex optimizer.
+export class DownhillSimplex {
+  private constructor() {
+    // disable constructor
+  }
+
+  /**
+   * Compute the centroid from a list of [SimplexEntry] objects, using cost
+   * function [f].
+   * @param f Cost function
+   * @param xss Simplex entries
+   * @returns The centroid.
+   */
+  private static _centroid(f: CostFunction, xss: SimplexEntry[]): SimplexEntry {
+    const n = xss[0].points.length;
+    const m = xss.length - 1;
+    const output = new Float64Array(n);
+
+    for (let i = 0; i < m; i++) {
+      for (let j = 0; j < n; j++) {
+        output[j] += xss[i].points[j];
+      }
+    }
+    for (let i = 0; i < n; i++) {
+      output[i] /= m;
+    }
+
+    return new SimplexEntry(f, output);
+  }
+
+  private static _shrink(s: number, xss: SimplexEntry[]): void {
+    const x1 = xss[0];
+
+    for (let i = 1; i < xss.length; i++) {
+      const xi = xss[i];
+
+      xss[i] = x1.modify(s, xi, x1);
+    }
+  }
+
+  /**
+   * Generate a new simplex from initial guess [x0], and an optional
+   * simplex [step] value.
+   * @param x0 Initial guess
+   * @param step Simplex step
+   * @returns The simplex.
+   */
+  static generateSimplex(x0: Float64Array, step = 0.01): Float64Array[] {
+    const output: Float64Array[] = [x0.slice(0)];
+
+    for (let i = 0; i < x0.length; i++) {
+      const tmp = x0.slice(0);
+
+      tmp[i] += tmp[i] * step;
+      output.push(tmp);
+    }
+
+    return output;
+  }
+
+  /**
+   * Perform derivative-free Nelder-Mead simplex optimization to minimize the
+   * cost function [f] for the initial simplex [xs].
+   *
+   * Optional arguments:
+   *  - `xTolerance`: centroid delta termination criteria
+   * - `fTolerance`: cost function delta termination criteria
+   * - `maxIter`: maximum number of optimization iterations
+   * - `adaptive`: use adaptive coefficients if possible
+   * - `printIter`: print a debug statement after each iteration
+   * @param f Cost function
+   * @param xs Initial simplex
+   * @param root0 Root0
+   * @param root0.xTolerance Root0.xTolerance
+   * @param root0.fTolerance Root0.fTolerance
+   * @param root0.maxIter Root0.maxIter
+   * @param root0.adaptive Root0.adaptive
+   * @param root0.printIter Root0.printIter
+   * @returns The optimal input value.
+   */
+  static solveSimplex(
+    f: CostFunction,
+    xs: Float64Array[],
+    {
+      xTolerance = 1e-12,
+      fTolerance = 1e-12,
+      maxIter = 10000,
+      adaptive = false,
+      printIter = false,
+    }: {
+      xTolerance?: number;
+      fTolerance?: number;
+      maxIter?: number;
+      adaptive?: boolean;
+      printIter?: boolean;
+    },
+  ): Float64Array {
+    let a: number;
+    let g: number;
+    let p: number;
+    let s: number;
+    const n = xs.length - 1;
+
+    if (adaptive && n >= 2) {
+      a = 1.0;
+      g = 1.0 + 2.0 / n;
+      p = 0.75 - 1.0 / (2.0 * n);
+      s = 1.0 - 1.0 / n;
+    } else {
+      a = 1.0;
+      g = 2.0;
+      p = 0.5;
+      s = 0.5;
+    }
+    let iter = 0;
+    let action = 'init';
+    const ordered: SimplexEntry[] = [];
+
+    for (const x of xs) {
+      ordered.push(new SimplexEntry(f, x));
+    }
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+      ordered.sort((x, y) => x.score - y.score);
+      const x0 = DownhillSimplex._centroid(f, ordered);
+      // update exit criterea
+      let xd = 0.0;
+      let fd = 0.0;
+
+      for (let i = 1; i < ordered.length; i++) {
+        xd = Math.max(xd, x0.distance(ordered[i]));
+        fd = Math.max(fd, Math.abs(x0.score - ordered[i].score));
+      }
+      if (printIter) {
+        // eslint-disable-next-line no-console
+        console.log(`${iter}: score=${x0.score} xd=${xd} fd=${fd} [${action}]`);
+      }
+      if (iter !== 0 && (xd < xTolerance || fd < fTolerance)) {
+        return ordered[0].points;
+      }
+      if (iter >= maxIter) {
+        return ordered[0].points;
+      }
+      iter++;
+      // reflection
+      const xr = x0.modify(a, x0, ordered[ordered.length - 1]);
+
+      if (ordered[0].score <= xr.score && xr.score < ordered[ordered.length - 2].score) {
+        ordered[ordered.length - 1] = xr;
+        action = 'reflect';
+        continue;
+      }
+      // expansion
+      if (xr.score < ordered[0].score) {
+        const xe = x0.modify(g, xr, x0);
+
+        if (xe.score < xr.score) {
+          ordered[ordered.length - 1] = xe;
+        } else {
+          ordered[ordered.length - 1] = xr;
+        }
+        action = 'expand';
+        continue;
+      }
+      // contraction
+      if (xr.score < ordered[ordered.length - 1].score) {
+        const xc = x0.modify(p, xr, x0);
+
+        if (xc.score < xr.score) {
+          ordered[ordered.length - 1] = xc;
+          action = 'contract';
+          continue;
+        } else {
+          DownhillSimplex._shrink(s, ordered);
+          action = 'shrink';
+          continue;
+        }
+      } else if (xr.score >= ordered[ordered.length - 1].score) {
+        const xc = x0.modify(p, ordered[ordered.length - 1], x0);
+
+        if (xc.score < ordered[ordered.length - 1].score) {
+          ordered[ordered.length - 1] = xc;
+          action = 'contract';
+          continue;
+        } else {
+          DownhillSimplex._shrink(s, ordered);
+          action = 'shrink';
+          continue;
+        }
+      }
+    }
+  }
+}

package/src/optimize/GoldenSection.ts

@@ -0,0 +1,71 @@
+/**
+ * @author @thkruz Theodore Kruczek
+ * @license AGPL-3.0-or-later
+ * @copyright (c) 2020-2024 Theodore Kruczek
+ *
+ * Orbital Object ToolKit is free software: you can redistribute it and/or modify it under the
+ * terms of the GNU Affero General Public License as published by the Free Software
+ * Foundation, either version 3 of the License, or (at your option) any later version.
+ *
+ * Orbital Object ToolKit is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
+ * without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+ * See the GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License along with
+ * Orbital Object ToolKit. If not, see <http://www.gnu.org/licenses/>.
+ */
+
+import { DifferentiableFunction } from '../main';
+
+// / Golden Section bounded single value optimizer.
+export class GoldenSection {
+  private static readonly _grInv: number = 1.0 / (0.5 * (Math.sqrt(5) + 1));
+
+  private static _check(fc: number, fd: number, solveMax: boolean): boolean {
+    return solveMax ? fc > fd : fc < fd;
+  }
+
+  /**
+   * Search for an optimal input value for function [f] that minimizes the
+   * output value.
+   *
+   * Takes [lower] and [upper] input search bounds, and an optional
+   * search [tolerance].
+   * @param f Function to optimize
+   * @param lower Lower bound
+   * @param upper Upper bound
+   * @param root0 Root0
+   * @param root0.tolerance Root0.tolerance
+   * @param root0.solveMax Root0.solveMax
+   * @returns The optimal input value.
+   */
+  static search(
+    f: DifferentiableFunction,
+    lower: number,
+    upper: number,
+    {
+      tolerance = 1e-5,
+      solveMax = false,
+    }: {
+      tolerance?: number;
+      solveMax?: boolean;
+    },
+  ): number {
+    let a = lower;
+    let b = upper;
+    let c = b - (b - a) * GoldenSection._grInv;
+    let d = a + (b - a) * GoldenSection._grInv;
+
+    while (Math.abs(b - a) > tolerance) {
+      if (GoldenSection._check(f(c), f(d), solveMax)) {
+        b = d;
+      } else {
+        a = c;
+      }
+      c = b - (b - a) * GoldenSection._grInv;
+      d = a + (b - a) * GoldenSection._grInv;
+    }
+
+    return 0.5 * (b + a);
+  }
+}

package/src/optimize/PolynomialRegression.ts

@@ -0,0 +1,109 @@
+/**
+ * @author @thkruz Theodore Kruczek
+ * @license AGPL-3.0-or-later
+ * @copyright (c) 2020-2024 Theodore Kruczek
+ *
+ * Orbital Object ToolKit is free software: you can redistribute it and/or modify it under the
+ * terms of the GNU Affero General Public License as published by the Free Software
+ * Foundation, either version 3 of the License, or (at your option) any later version.
+ *
+ * Orbital Object ToolKit is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
+ * without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+ * See the GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License along with
+ * Orbital Object ToolKit. If not, see <http://www.gnu.org/licenses/>.
+ */
+
+/* eslint-disable require-jsdoc */
+/* eslint-disable func-style */
+import { evalPoly } from 'ootk-core';
+import { DownhillSimplex } from './DownhillSimplex';
+import { PolynomicalRegressionResult } from './PolynomicalRegressionResult';
+// / Polynomial regression optimizer.
+export class PolynomialRegression {
+  private constructor() {
+    // disable constructor
+  }
+
+  private static _bayesInformationCriterea(n: number, k: number, sse: number): number {
+    return n * Math.log(sse) + k * Math.log(n);
+  }
+
+  /**
+   * Optimize polynomial coefficients to fit data series [xs] and [ys] for the
+   * provided polynomial [order].
+   * @param xs x values
+   * @param ys y values
+   * @param order Polynomial order
+   * @param root0 Root0
+   * @param root0.printIter Root0.printIter
+   * @returns The optimal input value.
+   */
+  static solve(
+    xs: Float64Array,
+    ys: Float64Array,
+    order: number,
+    { printIter = false }: { printIter?: boolean } = {},
+  ): PolynomicalRegressionResult {
+    const simplex = DownhillSimplex.generateSimplex(Float64Array.from(Array(order + 1).fill(1.0)));
+
+    /**
+     * Sum of squared errors.
+     * @param coeffs Polynomial coefficients
+     * @returns Sum of squared errors
+     */
+    function f(coeffs: Float64Array): number {
+      let sse = 0.0;
+
+      for (let i = 0; i < xs.length; i++) {
+        const diff = ys[i] - evalPoly(xs[i], coeffs);
+
+        sse += diff * diff;
+      }
+
+      return sse;
+    }
+
+    const result = DownhillSimplex.solveSimplex(f, simplex, {
+      adaptive: true,
+      printIter,
+    });
+    const sse = f(result);
+
+    return new PolynomicalRegressionResult(
+      result,
+      Math.sqrt(sse),
+      PolynomialRegression._bayesInformationCriterea(xs.length, order, sse),
+    );
+  }
+
+  /**
+   * Optimize polynomial coefficients to fit data series [xs] and [ys], and
+   * attempt to find an optimal order within the [minOrder] and
+   * [maxOrder] bounds.
+   * @param xs x values
+   * @param ys y values
+   * @param minOrder Minimum polynomial order
+   * @param maxOrder Maximum polynomial order
+   * @param root0 Root0
+   * @param root0.printIter Root0.printIter
+   * @returns The optimal input value.
+   */
+  static solveOrder(
+    xs: Float64Array,
+    ys: Float64Array,
+    minOrder: number,
+    maxOrder: number,
+    { printIter = false }: { printIter?: boolean } = {},
+  ): PolynomicalRegressionResult {
+    const cache: PolynomicalRegressionResult[] = [];
+
+    for (let order = minOrder; order <= maxOrder; order++) {
+      cache.push(PolynomialRegression.solve(xs, ys, order, { printIter }));
+    }
+    cache.sort((a, b) => a.bic - b.bic);
+
+    return cache[0];
+  }
+}

package/src/optimize/PolynomicalRegressionResult.ts

@@ -0,0 +1,32 @@
+/**
+ * @author @thkruz Theodore Kruczek
+ * @license AGPL-3.0-or-later
+ * @copyright (c) 2020-2024 Theodore Kruczek
+ *
+ * Orbital Object ToolKit is free software: you can redistribute it and/or modify it under the
+ * terms of the GNU Affero General Public License as published by the Free Software
+ * Foundation, either version 3 of the License, or (at your option) any later version.
+ *
+ * Orbital Object ToolKit is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
+ * without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+ * See the GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License along with
+ * Orbital Object ToolKit. If not, see <http://www.gnu.org/licenses/>.
+ */
+
+// / Polynomial regression optimization result.
+export class PolynomicalRegressionResult {
+  /**
+   * Create a new [PolynomicalRegressionResult] object, containing the
+   * polynomial [coefficients], root-sum-squared error [rss], and Bayes
+   * information criterea [bic].
+   * @param coefficients  The polynomial coefficients.
+   * @param rss The root-sum-squared error.
+   * @param bic The Bayes information criterea.
+   * @returns The optimal input value.
+   */
+  constructor(public coefficients: Float64Array, public rss: number, public bic: number) {
+    // Nothing to do here.
+  }
+}

package/src/optimize/SimpleLinearRegression.ts

@@ -0,0 +1,127 @@
+/**
+ * @author @thkruz Theodore Kruczek
+ * @license AGPL-3.0-or-later
+ * @copyright (c) 2020-2024 Theodore Kruczek
+ *
+ * Orbital Object ToolKit is free software: you can redistribute it and/or modify it under the
+ * terms of the GNU Affero General Public License as published by the Free Software
+ * Foundation, either version 3 of the License, or (at your option) any later version.
+ *
+ * Orbital Object ToolKit is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
+ * without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+ * See the GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License along with
+ * Orbital Object ToolKit. If not, see <http://www.gnu.org/licenses/>.
+ */
+
+// / Simple linear regression _(y = mx + b)_.
+export class SimpleLinearRegression {
+  /**
+   * Create a new [SimpleLinearRegression] object from lists of x and y
+   * values.
+   * @param xs x values
+   * @param ys y values
+   */
+  constructor(public xs: number[], public ys: number[]) {
+    this.update();
+  }
+
+  // / Line slope
+  private _slope = 0.0;
+
+  // / Y-axis intercept
+  private _intercept = 0.0;
+
+  private _error = 0.0;
+
+  // / Line slope
+  get slope(): number {
+    return this._slope;
+  }
+
+  // / Y-axis intercept
+  get intercept(): number {
+    return this._intercept;
+  }
+
+  // / Linear regression standard deviation
+  get error(): number {
+    return this._error;
+  }
+
+  // / Data length
+  get length(): number {
+    return Math.min(this.xs.length, this.ys.length);
+  }
+
+  private _calcError(): void {
+    let total = 0.0;
+
+    for (let i = 0; i < this.length; i++) {
+      const delta = this.ys[i] - this.evaluate(this.xs[i]);
+
+      total += delta * delta;
+    }
+    this._error = Math.sqrt(total / (this.length - 1));
+  }
+
+  // / Update the linear fit with this object's current [xs] and [ys] values.
+  update(): void {
+    const n = Math.min(this.xs.length, this.ys.length);
+    let xMu = 0.0;
+    let yMu = 0.0;
+
+    for (let i = 0; i < n; i++) {
+      xMu += this.xs[i];
+      yMu += this.ys[i];
+    }
+    xMu /= n;
+    yMu /= n;
+    let pa = 0.0;
+    let xSig = 0.0;
+    let ySig = 0.0;
+
+    for (let i = 0; i < n; i++) {
+      const xd = this.xs[i] - xMu;
+      const yd = this.ys[i] - yMu;
+
+      pa += xd * yd;
+      xSig += xd * xd;
+      ySig += yd * yd;
+    }
+    const p = pa / (Math.sqrt(xSig) * Math.sqrt(ySig));
+
+    xSig = Math.sqrt(xSig / (n - 1));
+    ySig = Math.sqrt(ySig / (n - 1));
+    this._slope = p * (ySig / xSig);
+    this._intercept = yMu - this._slope * xMu;
+    this._calcError();
+  }
+
+  // / Evaluate this linear fit for y, given an [x] value.
+  evaluate(x: number): number {
+    return this._slope * x + this._intercept;
+  }
+
+  /**
+   * Create a new [SimpleLinearRegression] object with outliers above the
+   * provided standard deviation [sigma] value removed.
+   * @param sigma standard deviation
+   * @returns new [SimpleLinearRegression] object
+   */
+  filterOutliers(sigma = 1.0): SimpleLinearRegression {
+    const limit = this.error * sigma;
+    const xsOut: number[] = [];
+    const ysOut: number[] = [];
+
+    for (let i = 0; i < this.length; i++) {
+      if (Math.abs(this.ys[i] - this.evaluate(this.xs[i])) < limit) {
+        xsOut.push(this.xs[i]);
+        ysOut.push(this.ys[i]);
+      }
+    }
+
+    return new SimpleLinearRegression(xsOut, ysOut);
+  }
+}

package/src/optimize/SimplexEntry.ts

@@ -0,0 +1,50 @@
+/**
+ * @author @thkruz Theodore Kruczek
+ * @license AGPL-3.0-or-later
+ * @copyright (c) 2020-2024 Theodore Kruczek
+ *
+ * Orbital Object ToolKit is free software: you can redistribute it and/or modify it under the
+ * terms of the GNU Affero General Public License as published by the Free Software
+ * Foundation, either version 3 of the License, or (at your option) any later version.
+ *
+ * Orbital Object ToolKit is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
+ * without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+ * See the GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License along with
+ * Orbital Object ToolKit. If not, see <http://www.gnu.org/licenses/>.
+ */
+
+import { Vector } from 'ootk-core';
+
+/**
+ * Optimization cost function that takes in parameter array [xs] and returns
+ * a score.
+ */
+export type CostFunction = (points: Float64Array) => number;
+
+export class SimplexEntry {
+  score: number;
+  private _x: Vector;
+
+  constructor(private _f: CostFunction, public points: Float64Array) {
+    this._x = new Vector(points);
+    this.score = this._f(points);
+  }
+
+  getPoints(): Float64Array {
+    return this._x.toArray();
+  }
+
+  getScore(): number {
+    return this.score;
+  }
+
+  modify(n: number, xa: SimplexEntry, xb: SimplexEntry): SimplexEntry {
+    return new SimplexEntry(this._f, this._x.add(xa._x.subtract(xb._x).scale(n)).toArray());
+  }
+
+  distance(se: SimplexEntry): number {
+    return this._x.distance(se._x);
+  }
+}