ootk 3.0.0 → 4.0.0-1

package/src/observation/Observation.ts

@@ -0,0 +1,125 @@
+/**
+ * @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 { EpochUTC, J2000, Matrix, Vector, Vector3D } from 'ootk-core';
+import { Propagator } from '../propagator/Propagator';
+import { RandomGaussianSource } from './../operations/RandomGaussianSource';
+import { PropagatorPairs } from './PropagatorPairs';
+
+/* eslint-disable @typescript-eslint/no-unused-vars */
+/**
+ * Observation data.
+ */
+export abstract class Observation {
+  /** Observation epoch. */
+  abstract get epoch(): EpochUTC;
+
+  /** Inertial observer location. */
+  abstract get site(): J2000;
+
+  /** Observation noise matrix. */
+  abstract get noise(): Matrix;
+
+  /**
+   * Return range-normalized cross line-of-sight residual for the observation
+   * when compared against a nominal state propagator.
+   * @param propagator Propagator to compare against.
+   * @throws Not implemented.
+   */
+  clos(propagator: Propagator): number {
+    throw new Error('Not implemented');
+  }
+
+  /**
+   * Return relative state residual for the observation when compared against
+   * a nominal state propagator.
+   * @param propagator Propagator to compare against.
+   * @throws Not implemented.
+   */
+  ricDiff(propagator: Propagator): Vector3D {
+    throw new Error('Not implemented');
+  }
+
+  /**
+   * Convert this observation to vector form.
+   * @throws Not implemented.
+   */
+  toVector(): Vector {
+    throw new Error('Not implemented');
+  }
+
+  /**
+   * Compute the state derivative matrix for this observation.
+   * @param propPairs Propagator pairs to compare against.
+   * @throws Not implemented.
+   */
+  jacobian(propPairs: PropagatorPairs): Matrix {
+    throw new Error('Not implemented');
+  }
+
+  /**
+   * Compute the state residual matrix for this observation.
+   * @param propagator Propagator to compare against.
+   * @throws Not implemented.
+   */
+  residual(propagator: Propagator): Matrix {
+    throw new Error('Not implemented');
+  }
+
+  /**
+   * Convert this observation's noise matrix into a covariance matrix.
+   * @returns A matrix representing the noise covariance.
+   */
+  noiseCovariance(): Matrix {
+    return this.noise.reciprocal();
+  }
+
+  /**
+   * Generates a noise sample from the noise covariance matrix.
+   * @param sigma - The scaling factor for the noise covariance matrix.
+   * @returns A matrix representing the noise sample.
+   */
+  noiseSample_(sigma: number): Matrix {
+    return this.noiseCovariance().scale(sigma).cholesky();
+  }
+
+  /**
+   * Randomly sample this observation in vector form within the
+   * observation noise.
+   * @param random Random number generator.
+   * @param sigma Sigma value to scale the noise by.
+   * @returns Sampled observation.
+   */
+  sampleVector(random: RandomGaussianSource, sigma: number): Vector {
+    const chol = this.noiseSample_(sigma);
+    const gauss = random.gaussVector(this.noise.columns);
+    const meas = this.toVector();
+
+    return meas.add(chol.multiplyVector(gauss));
+  }
+
+  /**
+   * Randomly sample this observation within the observation noise, scaled to
+   * the provided sigma value.
+   * @param random Random number generator.
+   * @param sigma Sigma value to scale the noise by.
+   * @throws Not implemented.
+   */
+  sample(random: RandomGaussianSource, sigma = 1.0): Observation {
+    throw new Error('Not implemented');
+  }
+}

package/src/observation/ObservationOptical.ts

@@ -0,0 +1,146 @@
+/**
+ * @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 {
+  array2d,
+  DEG2RAD,
+  EpochUTC,
+  J2000,
+  KilometersPerSecond,
+  Matrix,
+  RadecTopocentric,
+  Radians,
+  RIC,
+  Vector,
+  Vector3D,
+} from 'ootk-core';
+import { RandomGaussianSource } from '../operations/RandomGaussianSource';
+import { Propagator } from '../propagator/Propagator';
+import { Observation } from './Observation';
+import { normalizeAngle, observationDerivative, observationNoiseFromSigmas } from './ObservationUtils';
+import { PropagatorPairs } from './PropagatorPairs';
+
+// / Optical observation data.
+export class ObservationOptical extends Observation {
+  // / Create a new [ObservationOptical] object.
+  constructor(
+    private _site: J2000,
+    public observation: RadecTopocentric,
+    private _noise: Matrix = ObservationOptical.defaultNoise,
+  ) {
+    super();
+  }
+
+  // / Inertial site location.
+  get site(): J2000 {
+    return this._site;
+  }
+
+  // / Noise matrix.
+  get noise(): Matrix {
+    return this._noise;
+  }
+
+  /**
+   * Default noise matrix _(right-ascension, declination)_.
+   * Based on the Maui Optical Site noise model.
+   */
+  static defaultNoise: Matrix = ObservationOptical.noiseFromSigmas(
+    0.0037 * DEG2RAD as Radians,
+    0.003 * DEG2RAD as Radians,
+  );
+
+  get epoch(): EpochUTC {
+    return this.observation.epoch;
+  }
+
+  toVector(): Vector {
+    return Vector.fromList([this.observation.rightAscension, this.observation.declination]);
+  }
+
+  clos(propagator: Propagator): number {
+    const position = propagator.propagate(this.epoch).position;
+    const offset = position.subtract(this.site.position);
+    const actual = this.observation.lineOfSight().normalize();
+    const expected = offset.normalize();
+    const slantRange = offset.magnitude();
+    const theta = actual.angle(expected);
+
+    if (isNaN(theta)) {
+      return 0.0;
+    }
+
+    return 2.0 * slantRange * Math.sin(theta * 0.5);
+  }
+
+  ricDiff(propagator: Propagator): Vector3D {
+    const r0 = this.site;
+    const r1 = propagator.propagate(this.epoch);
+    const r2 = this.observation.position(this.site, r1.position.distance(r0.position));
+
+    return RIC.fromJ2000(new J2000(this.epoch, r2, Vector3D.origin as Vector3D<KilometersPerSecond>), r1).position;
+  }
+
+  sample(random: RandomGaussianSource, sigma = 1.0): Observation {
+    const resultEl = this.sampleVector(random, sigma).elements as Radians[];
+
+    return new ObservationOptical(
+      this.site,
+      new RadecTopocentric(this.epoch, resultEl[0], resultEl[1]),
+      this.noise,
+    );
+  }
+
+  jacobian(propPairs: PropagatorPairs): Matrix {
+    const result = array2d(2, 6, 0.0);
+
+    for (let i = 0; i < 6; i++) {
+      const step = propPairs.step(i);
+      const [high, low] = propPairs.get(i);
+      const sl = low.propagate(this.epoch);
+      const sh = high.propagate(this.epoch);
+      const ol = RadecTopocentric.fromStateVector(sl, this.site);
+      const oh = RadecTopocentric.fromStateVector(sh, this.site);
+
+      result[0][i] = observationDerivative(oh.rightAscension, ol.rightAscension, step, true);
+      result[1][i] = observationDerivative(oh.declination, ol.declination, step, true);
+    }
+
+    return new Matrix(result);
+  }
+
+  residual(propagator: Propagator): Matrix {
+    const result = array2d(2, 1, 0.0);
+    const state = propagator.propagate(this.epoch);
+    const radec = RadecTopocentric.fromStateVector(state, this.site);
+
+    result[0][0] = normalizeAngle(this.observation.rightAscension, radec.rightAscension);
+    result[1][0] = normalizeAngle(this.observation.declination, radec.declination);
+
+    return new Matrix(result);
+  }
+
+  /**
+   * Create a noise matrix from right ascension and declination standard deviantions.
+   * @param raSigma Right ascension standard deviation
+   * @param decSigma Declination standard deviation
+   * @returns Noise matrix
+   */
+  static noiseFromSigmas(raSigma: Radians, decSigma: Radians): Matrix {
+    return observationNoiseFromSigmas([raSigma, decSigma]);
+  }
+}

package/src/observation/ObservationRadar.ts

@@ -0,0 +1,131 @@
+/**
+ * @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 {
+  array2d,
+  DEG2RAD,
+  EpochUTC,
+  J2000,
+  Kilometers,
+  KilometersPerSecond,
+  Matrix,
+  Radians,
+  RAE,
+  RIC,
+  Vector,
+  Vector3D,
+} from 'ootk-core';
+import { RandomGaussianSource } from '../operations/RandomGaussianSource';
+import { Propagator } from '../propagator/Propagator';
+import { Observation } from './Observation';
+import { normalizeAngle, observationDerivative, observationNoiseFromSigmas } from './ObservationUtils';
+import { PropagatorPairs } from './PropagatorPairs';
+
+// / Radar observation data.
+export class ObservationRadar extends Observation {
+  // / Create a new [ObservationRadar] object.
+  constructor(private _site: J2000, public observation: RAE, private _noise: Matrix = ObservationRadar.defaultNoise) {
+    super();
+  }
+
+  // / Default noise matrix.
+  private static defaultNoise: Matrix =
+    ObservationRadar.noiseFromSigmas(0.32 as Kilometers, 0.015 * DEG2RAD as Radians, 0.015 * DEG2RAD as Radians);
+
+  get epoch(): EpochUTC {
+    return this.observation.epoch;
+  }
+
+  get site(): J2000 {
+    return this._site;
+  }
+
+  get noise(): Matrix {
+    return this._noise;
+  }
+
+  toVector(): Vector {
+    return Vector.fromList([this.observation.rng, this.observation.azRad, this.observation.elRad]);
+  }
+
+  clos(propagator: Propagator): number {
+    const ri = propagator.propagate(this.epoch).position.subtract(this.site.position);
+
+    return Math.abs(this.observation.rng - ri.magnitude());
+  }
+
+  ricDiff(propagator: Propagator): Vector3D {
+    const r0 = propagator.propagate(this.epoch);
+    const r1 = RAE.fromStateVector(r0, this.site);
+    const r2 = this.observation.position(this.site, r1.azRad, r1.elRad);
+
+    return RIC.fromJ2000(new J2000(this.epoch, r2, Vector3D.origin as Vector3D<KilometersPerSecond>), r0).position;
+  }
+
+  sample(random: RandomGaussianSource, sigma = 1.0): Observation {
+    const result = this.sampleVector(random, sigma).elements;
+
+    return new ObservationRadar(
+      this.site,
+      new RAE(this.observation.epoch, result[0] as Kilometers, result[1] as Radians, result[2] as Radians),
+      this.noise,
+    );
+  }
+
+  jacobian(propPairs: PropagatorPairs): Matrix {
+    const result = array2d(3, 6, 0.0);
+
+    for (let i = 0; i < 6; i++) {
+      const step = propPairs.step(i);
+      const [high, low] = propPairs.get(i);
+      const sl = low.propagate(this.epoch);
+      const sh = high.propagate(this.epoch);
+      const ol = RAE.fromStateVector(sl, this.site);
+      const oh = RAE.fromStateVector(sh, this.site);
+
+      result[0][i] = observationDerivative(oh.rng, ol.rng, step);
+      result[1][i] = observationDerivative(oh.azRad, ol.azRad, step, true);
+      result[2][i] = observationDerivative(oh.elRad, ol.elRad, step, true);
+    }
+
+    return new Matrix(result);
+  }
+
+  residual(propagator: Propagator): Matrix {
+    const result = array2d(3, 1, 0.0);
+    const state = propagator.propagate(this.epoch);
+    const razel = RAE.fromStateVector(state, this.site);
+
+    result[0][0] = this.observation.rng - razel.rng;
+    result[1][0] = normalizeAngle(this.observation.azRad, razel.azRad);
+    result[2][0] = normalizeAngle(this.observation.elRad, razel.elRad);
+
+    return new Matrix(result);
+  }
+
+  /**
+   * Create a noise matrix from the range, azimuth, and elevation standard
+   * deviations _(kilometers/radians)_.
+   * @param rngSigma - The range standard deviation _(kilometers)_.
+   * @param azSigma - The azimuth standard deviation _(radians)_.
+   * @param elSigma - The elevation standard deviation _(radians)_.
+   * @returns The noise matrix.
+   */
+  static noiseFromSigmas(rngSigma: Kilometers, azSigma: Radians, elSigma: Radians): Matrix {
+    return observationNoiseFromSigmas([rngSigma, azSigma, elSigma]);
+  }
+}

package/src/observation/ObservationUtils.ts

@@ -0,0 +1,40 @@
+/**
+ * @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 { Matrix } from 'ootk-core';
+
+export const normalizeAngle = (a: number, b: number): number => {
+  const x = a - b;
+
+  return Math.atan2(Math.sin(x), Math.cos(x));
+};
+
+export const observationDerivative = (xh: number, xl: number, step: number, isAngle = false): number =>
+  (isAngle ? normalizeAngle(xh, xl) : xh - xl) / step;
+
+export const observationNoiseFromSigmas = (sigmas: number[]): Matrix => {
+  const n = sigmas.length;
+  const result = Array.from({ length: n }, () => Array(n).fill(0.0));
+
+  for (let i = 0; i < n; i++) {
+    const s = sigmas[i];
+
+    result[i][i] = 1 / (s * s);
+  }
+
+  return new Matrix(result);
+};

package/src/observation/PropagatorPairs.ts

@@ -0,0 +1,45 @@
+/**
+ * @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 { Propagator } from '../propagator/Propagator';
+
+export class PropagatorPairs {
+  constructor(private _posStep: number, private _velStep: number) {
+    // Do nothing.
+  }
+
+  private _high: (Propagator | null)[] = Array(6).fill(null);
+  private _low: (Propagator | null)[] = Array(6).fill(null);
+
+  set(index: number, high: Propagator, low: Propagator): void {
+    this._high[index] = high;
+    this._low[index] = low;
+  }
+
+  get(index: number): [Propagator, Propagator] {
+    return [this._high[index]!, this._low[index]!];
+  }
+
+  /**
+   * Get the step size at the provided index.
+   * @param index The index.
+   * @returns The step size.
+   */
+  step(index: number): number {
+    return index < 3 ? this._posStep : this._velStep;
+  }
+}

package/src/operations/BoxMuller.ts

@@ -0,0 +1,87 @@
+/**
+ * @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 { Random, TAU, Vector } from 'ootk-core';
+
+// / Box-Muller random Gaussian number generator.
+export class BoxMuller {
+  private _index = 0;
+  private _cache = new Float64Array(2);
+  // / Mean value.
+  mu: number;
+  // / Standard deviation.
+  sigma: number;
+  // / Uniform random number generator.
+  rand: Random;
+
+  /**
+   * Create a new [BoxMuller] object with mean [mu], standard deviation
+   * [sigma], and [seed] number.
+   * @param mu Mean value.
+   * @param sigma Standard deviation.
+   * @param seed Random seed.
+   */
+  constructor(mu: number, sigma: number, seed = 0) {
+    this.mu = mu;
+    this.sigma = sigma;
+    this.rand = new Random(seed);
+    this._generate();
+  }
+
+  // / Refill the cache with random Gaussian numbers.
+  _generate() {
+    this._index = 0;
+    const u1 = this.rand.nextFloat();
+    const u2 = this.rand.nextFloat();
+    const mag = this.sigma * Math.sqrt(-2.0 * Math.log(u1));
+
+    this._cache[0] = mag * Math.cos(TAU * u2) + this.mu;
+    this._cache[1] = mag * Math.sin(TAU * u2) + this.mu;
+  }
+
+  /**
+   * Generate a gaussian number, with mean [mu] and standard
+   * deviation [sigma].
+   * @returns A gaussian number.
+   */
+  nextGauss(): number {
+    if (this._index > 1) {
+      this._generate();
+    }
+    const result = this._cache[this._index];
+
+    this._index++;
+
+    return result;
+  }
+
+  /**
+   * Generate a [Vector] of gaussian numbers, with mean [mu] and standard
+   * deviation [sigma].
+   * @param n Number of gaussian numbers to generate.
+   * @returns A [Vector] of gaussian numbers.
+   */
+  gaussVector(n: number): Vector {
+    const result = new Float64Array(n);
+
+    for (let i = 0; i < n; i++) {
+      result[i] = this.nextGauss();
+    }
+
+    return new Vector(result);
+  }
+}