tensum 0.1.0

package/src/parameters.ts

@@ -0,0 +1,226 @@
+import {
+  angularFrequency,
+  assertFinite,
+  classifyDamping,
+  dampingRatio,
+} from './math.js';
+import { validateSpringParameters } from './solver.js';
+import type { SpringParameters, SpringRegime } from './types.js';
+
+const DEFAULT_MASS = 1;
+const TWO_PI = 2 * Math.PI;
+
+export interface ResponseSpringInput {
+  response: number;
+  dampingRatio: number;
+  mass?: number;
+}
+
+export interface PerceptualSpringInput {
+  duration: number;
+  bounce: number;
+  mass?: number;
+}
+
+export interface VisualSpringInput {
+  visualDuration: number;
+  bounce: number;
+  mass?: number;
+}
+
+export interface SettlingDurationSpringInput {
+  duration: number;
+  dampingRatio: number;
+  epsilon: number;
+  mass?: number;
+}
+
+export interface SpringCharacteristics {
+  angularFrequency: number;
+  dampingRatio: number;
+  regime: SpringRegime;
+  response: number;
+  bounce: number;
+  perceptualDuration: number;
+}
+
+export interface SpringParameterConverters {
+  fromPhysics(parameters: SpringParameters): Readonly<SpringParameters>;
+  fromResponse(input: ResponseSpringInput): Readonly<SpringParameters>;
+  fromPerceptualDuration(input: PerceptualSpringInput): Readonly<SpringParameters>;
+  fromSettlingDuration(input: SettlingDurationSpringInput): Readonly<SpringParameters>;
+  fromVisualDuration(input: VisualSpringInput): Readonly<SpringParameters>;
+}
+
+export interface SpringPresetOptions {
+  duration?: number;
+  extraBounce?: number;
+  mass?: number;
+}
+
+export type SpringPreset = (
+  options?: SpringPresetOptions,
+) => Readonly<SpringParameters>;
+
+export interface SpringPresets {
+  smooth: SpringPreset;
+  snappy: SpringPreset;
+  bouncy: SpringPreset;
+}
+
+function assertPositive(name: string, value: number): void {
+  assertFinite(name, value);
+  if (value <= 0) throw new RangeError(`${name} must be greater than 0`);
+}
+
+function assertNonNegative(name: string, value: number): void {
+  assertFinite(name, value);
+  if (value < 0) throw new RangeError(`${name} must be greater than or equal to 0`);
+}
+
+function resolvedMass(mass: number | undefined): number {
+  const value = mass === undefined ? DEFAULT_MASS : mass;
+  assertPositive('mass', value);
+  return value;
+}
+
+function freezeParameters(parameters: SpringParameters): Readonly<SpringParameters> {
+  validateSpringParameters(parameters);
+  const frequency = angularFrequency(parameters);
+  const ratio = dampingRatio(parameters);
+  assertPositive('angularFrequency', frequency);
+  assertFinite('dampingRatio', ratio);
+  return Object.freeze({ ...parameters });
+}
+
+function fromFrequency(
+  frequency: number,
+  ratio: number,
+  mass: number,
+): Readonly<SpringParameters> {
+  assertPositive('angularFrequency', frequency);
+  assertNonNegative('dampingRatio', ratio);
+  const stiffness = mass * frequency * frequency;
+  let damping = 2 * ratio * mass * frequency;
+  if (!Number.isFinite(damping) || damping === 0) {
+    const candidates = [
+      2 * mass * ratio * frequency,
+      2 * frequency * mass * ratio,
+      2 * mass * (ratio * frequency),
+    ];
+    const representable = candidates.find(
+      (candidate) => Number.isFinite(candidate) && candidate > 0,
+    );
+    if (representable !== undefined) damping = representable;
+  }
+  return freezeParameters({ mass, stiffness, damping });
+}
+
+function bounceToDampingRatio(bounce: number): number {
+  assertFinite('bounce', bounce);
+  if (bounce <= -1) {
+    throw new RangeError('bounce must be greater than -1 for finite spring parameters');
+  }
+  if (bounce >= 0) return 1 - Math.min(bounce, 1);
+  return 1 / (1 + bounce);
+}
+
+function dampingRatioToBounce(ratio: number): number {
+  return ratio <= 1 ? 1 - ratio : 1 / ratio - 1;
+}
+
+export function springCharacteristics(
+  parameters: SpringParameters,
+): Readonly<SpringCharacteristics> {
+  validateSpringParameters(parameters);
+  const frequency = angularFrequency(parameters);
+  const ratio = dampingRatio(parameters);
+  assertPositive('angularFrequency', frequency);
+  assertFinite('dampingRatio', ratio);
+  const response = TWO_PI / frequency;
+  assertPositive('response', response);
+
+  return Object.freeze({
+    angularFrequency: frequency,
+    dampingRatio: ratio,
+    regime: classifyDamping(ratio),
+    response,
+    bounce: dampingRatioToBounce(ratio),
+    perceptualDuration: response,
+  });
+}
+
+export const springParameters: SpringParameterConverters = Object.freeze({
+  fromPhysics(parameters: SpringParameters): Readonly<SpringParameters> {
+    return freezeParameters({
+      mass: parameters.mass,
+      stiffness: parameters.stiffness,
+      damping: parameters.damping,
+    });
+  },
+  fromResponse({
+    response,
+    dampingRatio: ratio,
+    mass,
+  }: ResponseSpringInput): Readonly<SpringParameters> {
+    assertPositive('response', response);
+    return fromFrequency(TWO_PI / response, ratio, resolvedMass(mass));
+  },
+  fromPerceptualDuration({
+    duration,
+    bounce,
+    mass,
+  }: PerceptualSpringInput): Readonly<SpringParameters> {
+    assertPositive('duration', duration);
+    return fromFrequency(
+      TWO_PI / duration,
+      bounceToDampingRatio(bounce),
+      resolvedMass(mass),
+    );
+  },
+  fromSettlingDuration({
+    duration,
+    dampingRatio: ratio,
+    epsilon,
+    mass,
+  }: SettlingDurationSpringInput): Readonly<SpringParameters> {
+    assertPositive('duration', duration);
+    assertPositive('dampingRatio', ratio);
+    assertFinite('epsilon', epsilon);
+    if (epsilon <= 0 || epsilon >= 1) {
+      throw new RangeError('epsilon must be greater than 0 and less than 1');
+    }
+    const frequency = -Math.log(epsilon) / (ratio * duration);
+    return fromFrequency(frequency, ratio, resolvedMass(mass));
+  },
+  fromVisualDuration({
+    visualDuration,
+    bounce,
+    mass,
+  }: VisualSpringInput): Readonly<SpringParameters> {
+    return springParameters.fromPerceptualDuration({
+      duration: visualDuration,
+      bounce,
+      ...(mass === undefined ? {} : { mass }),
+    });
+  },
+});
+
+function createPreset(baseBounce: number): SpringPreset {
+  return (options: SpringPresetOptions = {}): Readonly<SpringParameters> => {
+    const extraBounce =
+      options.extraBounce === undefined ? 0 : options.extraBounce;
+    assertFinite('extraBounce', extraBounce);
+    return springParameters.fromPerceptualDuration({
+      duration: options.duration === undefined ? 0.5 : options.duration,
+      bounce: baseBounce + extraBounce,
+      ...(options.mass === undefined ? {} : { mass: options.mass }),
+    });
+  };
+}
+
+export const springPresets: SpringPresets = Object.freeze({
+  smooth: createPreset(0),
+  snappy: createPreset(0.15),
+  bouncy: createPreset(0.3),
+});

package/src/settling.ts

@@ -0,0 +1,141 @@
+import { assertFinite } from './math.js';
+import type { AnalyticalSolver } from './solver.js';
+import type {
+  SettlingResult,
+  SpringSettleInput,
+  SpringSettlingOptions,
+} from './types.js';
+
+export const DEFAULT_SETTLING_OPTIONS: Readonly<SpringSettlingOptions> = {
+  positionEpsilon: 0.1,
+  velocityEpsilon: 0.1,
+  maxDuration: 60,
+  refinementIterations: 48,
+};
+
+export function resolveSettlingOptions(
+  input: SpringSettleInput = {},
+): Readonly<SpringSettlingOptions> {
+  if (typeof input !== 'object' || input === null || Array.isArray(input)) {
+    throw new TypeError('settle must be an object when provided');
+  }
+  const options: SpringSettlingOptions = {
+    positionEpsilon:
+      input.position === undefined
+        ? DEFAULT_SETTLING_OPTIONS.positionEpsilon
+        : input.position,
+    velocityEpsilon:
+      input.velocity === undefined
+        ? DEFAULT_SETTLING_OPTIONS.velocityEpsilon
+        : input.velocity,
+    maxDuration:
+      input.maxDuration === undefined
+        ? DEFAULT_SETTLING_OPTIONS.maxDuration
+        : input.maxDuration,
+    refinementIterations:
+      input.refinementIterations === undefined
+        ? DEFAULT_SETTLING_OPTIONS.refinementIterations
+        : input.refinementIterations,
+  };
+  validateSettlingOptions(options);
+  return Object.freeze(options);
+}
+
+export function validateSettlingOptions(options: SpringSettlingOptions): void {
+  assertFinite('positionEpsilon', options.positionEpsilon);
+  assertFinite('velocityEpsilon', options.velocityEpsilon);
+  assertFinite('maxDuration', options.maxDuration);
+  assertFinite('refinementIterations', options.refinementIterations);
+
+  if (options.positionEpsilon <= 0) {
+    throw new RangeError('positionEpsilon must be greater than 0');
+  }
+  if (options.velocityEpsilon <= 0) {
+    throw new RangeError('velocityEpsilon must be greater than 0');
+  }
+  if (options.maxDuration <= 0) {
+    throw new RangeError('maxDuration must be greater than 0');
+  }
+  if (!Number.isInteger(options.refinementIterations)) {
+    throw new RangeError('refinementIterations must be an integer');
+  }
+  if (options.refinementIterations <= 0) {
+    throw new RangeError('refinementIterations must be greater than 0');
+  }
+}
+
+function boundsMeetThresholds(
+  solver: AnalyticalSolver,
+  time: number,
+  options: SpringSettlingOptions,
+): boolean {
+  const bounds = solver.tailBoundsAt(time);
+  return (
+    bounds.position <= options.positionEpsilon && bounds.velocity <= options.velocityEpsilon
+  );
+}
+
+/**
+ * Finds the first time at which analytical tail envelopes are below both
+ * tolerances. The envelopes bound every future position error and velocity,
+ * so an underdamped zero-crossing cannot be mistaken for settlement.
+ */
+export function getSettlingResult(
+  solver: AnalyticalSolver,
+  options: SpringSettlingOptions,
+): SettlingResult {
+  validateSettlingOptions(options);
+  const { maxDuration, refinementIterations } = options;
+
+  const initialBounds = solver.tailBoundsAt(0);
+  if (initialBounds.position === 0 && initialBounds.velocity === 0) {
+    return { duration: 0, iterations: 0, settled: true };
+  }
+
+  if (boundsMeetThresholds(solver, 0, options) && solver.tailBoundsMonotonicAfter === 0) {
+    return { duration: 0, iterations: 0, settled: true };
+  }
+
+  // An undamped non-equilibrium oscillator has a constant analytical envelope.
+  if (solver.dampingRatio === 0) {
+    return { duration: maxDuration, iterations: 0, settled: false };
+  }
+
+  if (solver.tailBoundsMonotonicAfter > maxDuration) {
+    return { duration: maxDuration, iterations: 0, settled: false };
+  }
+
+  let iterations = 0;
+  let lower = solver.tailBoundsMonotonicAfter;
+  let upper = Math.max(
+    lower,
+    Math.min(maxDuration, Math.max(1 / solver.angularFrequency, 1 / 120)),
+  );
+
+  if (boundsMeetThresholds(solver, lower, options)) {
+    // Critical-damping polynomial envelopes can grow before this point. Using
+    // the monotonic boundary is conservative and avoids an invalid binary
+    // search across that non-monotonic interval.
+    return { duration: lower, iterations, settled: true };
+  } else {
+    while (upper < maxDuration && !boundsMeetThresholds(solver, upper, options)) {
+      lower = upper;
+      upper = Math.min(maxDuration, upper * 2);
+      iterations += 1;
+    }
+  }
+
+  if (!boundsMeetThresholds(solver, upper, options)) {
+    return { duration: maxDuration, iterations, settled: false };
+  }
+
+  for (let index = 0; index < refinementIterations; index += 1) {
+    const midpoint = lower + (upper - lower) / 2;
+    if (midpoint === lower || midpoint === upper) break;
+    if (boundsMeetThresholds(solver, midpoint, options)) upper = midpoint;
+    else lower = midpoint;
+    iterations += 1;
+  }
+
+  return { duration: upper, iterations, settled: true };
+}

package/src/solver.ts

@@ -0,0 +1,262 @@
+import {
+  angularFrequency,
+  assertFinite,
+  assertNonNegativeTime,
+  classifyDamping,
+  dampingDecayRate,
+  dampingRatio,
+} from './math.js';
+import type {
+  SpringInitialState,
+  SpringParameters,
+  SpringRegime,
+  SpringState,
+} from './types.js';
+
+export interface AnalyticalSolver {
+  readonly angularFrequency: number;
+  readonly dampingRatio: number;
+  readonly regime: SpringRegime;
+  stateAt(time: number): SpringState;
+  tailBoundsAt(time: number): SpringState;
+  tailBoundsMonotonicAfter: number;
+}
+
+export function validateSpringParameters(parameters: SpringParameters): void {
+  assertFinite('mass', parameters.mass);
+  assertFinite('stiffness', parameters.stiffness);
+  assertFinite('damping', parameters.damping);
+
+  if (parameters.mass <= 0) throw new RangeError('mass must be greater than 0');
+  if (parameters.stiffness <= 0) throw new RangeError('stiffness must be greater than 0');
+  if (parameters.damping < 0) throw new RangeError('damping must be greater than or equal to 0');
+}
+
+export function validateInitialState(initial: SpringInitialState): void {
+  assertFinite('position', initial.position);
+  assertFinite('velocity', initial.velocity);
+  assertFinite('target', initial.target);
+}
+
+function finiteState(
+  position: number,
+  velocity: number,
+  suffix = '',
+): SpringState {
+  assertFinite(`position${suffix}`, position);
+  assertFinite(`velocity${suffix}`, velocity);
+  return { position, velocity };
+}
+
+function multiplyDivide(
+  first: number,
+  second: number,
+  divisor: number,
+): number {
+  const firstQuotient = (first / divisor) * second;
+  const secondQuotient = first * (second / divisor);
+  if (Number.isFinite(firstQuotient)) {
+    if (firstQuotient !== 0 || secondQuotient === 0) return firstQuotient;
+  }
+  return secondQuotient;
+}
+
+/**
+ * Solves m·x″ + c·x′ + k·(x - target) = 0 in closed form.
+ * Every sample is calculated from the initial conditions and absolute time.
+ */
+export function createAnalyticalSolver(
+  parameters: SpringParameters,
+  initial: SpringInitialState,
+): AnalyticalSolver {
+  validateSpringParameters(parameters);
+  validateInitialState(initial);
+
+  // Keep the public solver deterministic if the caller later reuses and
+  // mutates its input object.
+  const initialPosition = initial.position;
+  const initialVelocity = initial.velocity;
+  const target = initial.target;
+
+  const omega0 = angularFrequency(parameters);
+  const alpha = dampingDecayRate(parameters);
+  const zeta = dampingRatio(parameters);
+
+  assertFinite('angularFrequency', omega0);
+  assertFinite('dampingDecayRate', alpha);
+  assertFinite('dampingRatio', zeta);
+  if (omega0 <= 0) {
+    throw new RangeError('spring parameters must produce a positive angularFrequency');
+  }
+
+  const regime = classifyDamping(zeta);
+  const y0 = initialPosition - target;
+  const v0 = initialVelocity;
+
+  assertFinite('initial displacement', y0);
+
+  if (regime === 'underdamped') {
+    const omegaD =
+      omega0 * Math.sqrt(Math.max(0, (1 - zeta) * (1 + zeta)));
+    const a = y0;
+    const b = (v0 + alpha * y0) / omegaD;
+    const velocityCos = -alpha * a + omegaD * b;
+    const velocitySin = -alpha * b - omegaD * a;
+    const positionAmplitude = Math.hypot(a, b);
+    const velocityAmplitude = Math.hypot(velocityCos, velocitySin);
+
+    for (const [name, value] of [
+      ['dampedAngularFrequency', omegaD],
+      ['positionCoefficient', b],
+      ['velocityCosCoefficient', velocityCos],
+      ['velocitySinCoefficient', velocitySin],
+      ['positionAmplitude', positionAmplitude],
+      ['velocityAmplitude', velocityAmplitude],
+    ] as const) {
+      assertFinite(name, value);
+    }
+
+    return {
+      angularFrequency: omega0,
+      dampingRatio: zeta,
+      regime,
+      stateAt(time) {
+        assertNonNegativeTime(time);
+        if (time === 0) {
+          return { position: initialPosition, velocity: initialVelocity };
+        }
+        const decay = Math.exp(-alpha * time);
+        if (decay === 0) return { position: target, velocity: 0 };
+        const rawPhase = omegaD * time;
+        const phase = Number.isFinite(rawPhase)
+          ? rawPhase
+          : (time % ((2 * Math.PI) / omegaD)) * omegaD;
+        const cosine = Math.cos(phase);
+        const sine = Math.sin(phase);
+
+        return finiteState(
+          target + decay * (a * cosine + b * sine),
+          decay * (velocityCos * cosine + velocitySin * sine),
+        );
+      },
+      tailBoundsAt(time) {
+        assertNonNegativeTime(time);
+        const decay = Math.exp(-alpha * time);
+        return finiteState(
+          decay * positionAmplitude,
+          decay * velocityAmplitude,
+          ' bound',
+        );
+      },
+      tailBoundsMonotonicAfter: 0,
+    };
+  }
+
+  if (regime === 'critical') {
+    const a = y0;
+    const b = v0 + omega0 * y0;
+    const velocityConstant = b - omega0 * a;
+    const velocityLinear = -omega0 * b;
+
+    for (const [name, value] of [
+      ['positionCoefficient', b],
+      ['velocityConstant', velocityConstant],
+      ['velocityLinear', velocityLinear],
+    ] as const) {
+      assertFinite(name, value);
+    }
+
+    return {
+      angularFrequency: omega0,
+      dampingRatio: zeta,
+      regime,
+      stateAt(time) {
+        assertNonNegativeTime(time);
+        if (time === 0) {
+          return { position: initialPosition, velocity: initialVelocity };
+        }
+        const decay = Math.exp(-omega0 * time);
+        if (decay === 0) return { position: target, velocity: 0 };
+        const timeDecay = time * decay;
+        return finiteState(
+          target + decay * a + timeDecay * b,
+          decay * velocityConstant + timeDecay * velocityLinear,
+        );
+      },
+      tailBoundsAt(time) {
+        assertNonNegativeTime(time);
+        const decay = Math.exp(-omega0 * time);
+        if (decay === 0) return { position: 0, velocity: 0 };
+        const timeDecay = time * decay;
+        return finiteState(
+          decay * Math.abs(a) + timeDecay * Math.abs(b),
+          decay * Math.abs(velocityConstant) +
+            timeDecay * Math.abs(velocityLinear),
+          ' bound',
+        );
+      },
+      // Every t·exp(-ωt) term decreases after t = 1/ω.
+      tailBoundsMonotonicAfter: 1 / omega0,
+    };
+  }
+
+  const normalizedFrequency = omega0 / alpha;
+  const normalizedOffset = Math.sqrt(
+    Math.max(0, (1 - normalizedFrequency) * (1 + normalizedFrequency)),
+  );
+  const rootFastMagnitude = alpha * (1 + normalizedOffset);
+  const rootFast = -rootFastMagnitude;
+  // Vieta's relation avoids subtracting two almost equal values in
+  // -alpha + sqrt(alpha² - omega0²).
+  const rootSlow = -omega0 * (omega0 / rootFastMagnitude);
+  const rootSeparation = rootSlow - rootFast;
+  const normalizedVelocity = v0 / rootSeparation;
+  const coefficientSlow =
+    normalizedVelocity - multiplyDivide(rootFast, y0, rootSeparation);
+  const coefficientFast =
+    multiplyDivide(rootSlow, y0, rootSeparation) - normalizedVelocity;
+
+  for (const [name, value] of [
+    ['overdampedSlowRoot', rootSlow],
+    ['overdampedFastRoot', rootFast],
+    ['overdampedRootSeparation', rootSeparation],
+    ['slowModeCoefficient', coefficientSlow],
+    ['fastModeCoefficient', coefficientFast],
+  ] as const) {
+    assertFinite(name, value);
+  }
+  if (rootSlow >= 0 || rootFast >= 0 || rootSeparation <= 0) {
+    throw new RangeError('overdamped roots must be distinct negative finite numbers');
+  }
+
+  return {
+    angularFrequency: omega0,
+    dampingRatio: zeta,
+    regime,
+    stateAt(time) {
+      assertNonNegativeTime(time);
+      if (time === 0) {
+        return { position: initialPosition, velocity: initialVelocity };
+      }
+      const slow = coefficientSlow * Math.exp(rootSlow * time);
+      const fast = coefficientFast * Math.exp(rootFast * time);
+      return finiteState(
+        target + slow + fast,
+        rootSlow * slow + rootFast * fast,
+      );
+    },
+    tailBoundsAt(time) {
+      assertNonNegativeTime(time);
+      const slowDecay = Math.exp(rootSlow * time);
+      const fastDecay = Math.exp(rootFast * time);
+      return finiteState(
+        Math.abs(coefficientSlow) * slowDecay +
+          Math.abs(coefficientFast) * fastDecay,
+        Math.abs(rootSlow * coefficientSlow) * slowDecay +
+          Math.abs(rootFast * coefficientFast) * fastDecay,
+        ' bound',
+      );
+    },
+    tailBoundsMonotonicAfter: 0,
+  };
+}