《游戏引擎实现原理》10.3 数值稳健：epsilon、饱和与除零

|a - b| <= epsilon

|a - b| <= epsilon * max(1, |a|, |b|)

// file: src/math/numerical-robustness.ts
// tier: L1
// verify: npx vitest run src/math/numerical-robustness.test.ts
//
// helio 内核：数值稳健工具。epsilon 比较、饱和、安全除法、NaN 净化。

/** 默认相对误差阈值。 */
export const EPS = 1e-6;

/** 相对 epsilon 比较：对大数宽容、对小数严格。 */
export function approxEqual(a: number, b: number, eps: number = EPS): boolean {
  const diff = Math.abs(a - b);
  const scale = Math.max(1, Math.abs(a), Math.abs(b));
  return diff <= eps * scale;
}

/** 绝对 epsilon 比较：适合「本该等于 0」的量。 */
export function approxZero(a: number, eps: number = EPS): boolean {
  return Math.abs(a) <= eps;
}

/** 饱和到 [0, 1]。 */
export function saturate(x: number): number {
  if (Number.isNaN(x)) return 0;
  if (x < 0) return 0;
  if (x > 1) return 1;
  return x;
}

/** 钳制到 [lo, hi]，并保证 lo <= hi。 */
export function clamp(x: number, lo: number, hi: number): number {
  if (Number.isNaN(x)) return lo;
  if (lo > hi) return lo;
  if (x < lo) return lo;
  if (x > hi) return hi;
  return x;
}

/** 安全除法：分母接近 0、非有限或结果非有限时返回 fallback。 */
export function safeDiv(a: number, b: number, fallback = 0, eps: number = EPS): number {
  if (!Number.isFinite(b) || Math.abs(b) < eps) return fallback;
  const r = a / b;
  return Number.isFinite(r) ? r : fallback;
}

/** NaN / Infinity 净化：非有限值一律换成 fallback。 */
export function sanitize(x: number, fallback = 0): number {
  return Number.isFinite(x) ? x : fallback;
}

/** 安全归一化：长度为 0 时返回零向量，而不是 NaN。 */
export function safeNormalize(x: number, y: number, z: number): [number, number, number] {
  const len = Math.sqrt(x * x + y * y + z * z);
  if (len < EPS) return [0, 0, 0];
  return [x / len, y / len, z / len];
}

// file: src/math/numerical-robustness.test.ts
// tier: L1
// verify: npx vitest run src/math/numerical-robustness.test.ts

import { describe, expect, it } from 'vitest';
import {
  EPS,
  approxEqual,
  approxZero,
  clamp,
  safeDiv,
  safeNormalize,
  sanitize,
  saturate,
} from './numerical-robustness.ts';

describe('epsilon 比较', () => {
  it('0.1+0.2 与 0.3 在相对阈值下相等', () => {
    expect(0.1 + 0.2 === 0.3).toBe(false);
    expect(approxEqual(0.1 + 0.2, 0.3)).toBe(true);
  });

  it('相对比较对大数宽容', () => {
    expect(approxEqual(1e8, 1e8 + 1)).toBe(true);
  });

  it('approxZero 判断「本该为零」', () => {
    expect(approxZero(1e-9)).toBe(true);
    expect(approxZero(1e-3)).toBe(false);
  });
});

describe('饱和与钳制', () => {
  it('saturate 把值压到 [0,1]', () => {
    expect(saturate(-0.5)).toBe(0);
    expect(saturate(1.5)).toBe(1);
    expect(saturate(0.3)).toBe(0.3);
    expect(saturate(Number.NaN)).toBe(0);
  });

  it('clamp 处理区间倒置', () => {
    expect(clamp(5, 0, 10)).toBe(5);
    expect(clamp(-1, 0, 10)).toBe(0);
    expect(clamp(11, 0, 10)).toBe(10);
    expect(clamp(5, 10, 0)).toBe(10); // lo > hi 时退化为 lo
  });
});

describe('除零与 NaN 防护', () => {
  it('分母接近 0 时返回 fallback', () => {
    expect(safeDiv(1, 0)).toBe(0);
    expect(safeDiv(1, 1e-12)).toBe(0);
    expect(safeDiv(1, 2)).toBe(0.5);
  });

  it('safeDiv 挡住非有限分母', () => {
    expect(safeDiv(1, Number.NaN, -1)).toBe(-1);
    expect(safeDiv(1, Number.POSITIVE_INFINITY, -1)).toBe(-1);
  });

  it('sanitize 把 NaN/Inf 换成 fallback', () => {
    expect(sanitize(Number.NaN, 7)).toBe(7);
    expect(sanitize(Number.POSITIVE_INFINITY, 7)).toBe(7);
    expect(sanitize(3.14, 7)).toBe(3.14);
  });

  it('safeNormalize 对零向量返回零而非 NaN', () => {
    expect(safeNormalize(0, 0, 0)).toEqual([0, 0, 0]);
    const [x, y, z] = safeNormalize(3, 0, 0);
    expect(x).toBe(1);
    expect(y).toBe(0);
    expect(z).toBe(0);
  });

  it('EPS 是默认阈值', () => {
    expect(EPS).toBe(1e-6);
  });
});

NaN+1 = NaN | NaN*0 = NaN | NaN===NaN = false
1/0 = Infinity | 0/0 = NaN | -1/0 = -Infinity
1/Infinity = 0 | isFinite(1/0) = false
Number.isNaN(NaN) = true