@guinetik/gcanvas 1.0.0 → 1.0.1

package/types/math.d.ts

@@ -266,3 +266,364 @@ export function generatePenroseTilingPixels(
   height?: number,
   options?: PenroseTilingOptions
 ): Uint8ClampedArray;
+
+// ==========================================================================
+// Tensor (Rank-2 Tensor for General Relativity)
+// ==========================================================================
+
+/** Tensor creation options */
+export interface TensorOptions {
+  /** Name of the tensor (e.g., 'Schwarzschild') */
+  name?: string;
+  /** Metric signature (e.g., [-1, 1, 1, 1]) */
+  signature?: number[];
+  /** Coordinate names (e.g., ['t', 'r', 'θ', 'φ']) */
+  coordinates?: string[];
+}
+
+/**
+ * Rank-2 Tensor class for general relativity calculations.
+ * Provides immutable tensor operations following the Complex class pattern.
+ *
+ * @example
+ * const g = Tensor.schwarzschild(10, 2);
+ * console.log(g.get(0, 0)); // g_tt component
+ */
+export class Tensor {
+  /** Tensor dimension (n for n×n tensor) */
+  readonly dimension: number;
+  /** Tensor name */
+  readonly name: string;
+  /** Metric signature */
+  readonly signature: number[] | null;
+  /** Coordinate names */
+  readonly coordinates: string[] | null;
+
+  /**
+   * Create a new rank-2 tensor from a 2D array of components.
+   * @param components - 2D array of tensor components
+   * @param options - Optional metadata
+   */
+  constructor(components: number[][], options?: TensorOptions);
+
+  // Static Factory Methods
+  /** Create a Minkowski (flat spacetime) metric tensor */
+  static minkowski(): Tensor;
+
+  /**
+   * Create a Schwarzschild metric tensor at a given radial position.
+   * @param r - Radial coordinate (must be > rs)
+   * @param rs - Schwarzschild radius (2GM/c²)
+   * @param theta - Polar angle (default: equatorial plane)
+   */
+  static schwarzschild(r: number, rs: number, theta?: number): Tensor;
+
+  /** Create contravariant Schwarzschild metric */
+  static schwarzschildContravariant(r: number, rs: number, theta?: number): Tensor;
+
+  /**
+   * Create a Kerr metric tensor (rotating black hole).
+   * @param r - Radial coordinate
+   * @param theta - Polar angle
+   * @param M - Mass parameter
+   * @param a - Spin parameter (0 ≤ a ≤ M)
+   */
+  static kerr(r: number, theta: number, M: number, a: number): Tensor;
+
+  /** Create contravariant Kerr metric */
+  static kerrContravariant(r: number, theta: number, M: number, a: number): Tensor;
+
+  /** Calculate Kerr horizon radius */
+  static kerrHorizonRadius(M: number, a: number, inner?: boolean): number;
+
+  /** Calculate ergosphere radius */
+  static kerrErgosphereRadius(M: number, a: number, theta: number): number;
+
+  /** Calculate ISCO radius for Kerr metric */
+  static kerrISCO(M: number, a: number, prograde?: boolean): number;
+
+  /** Calculate frame-dragging angular velocity */
+  static kerrFrameDraggingOmega(r: number, theta: number, M: number, a: number): number;
+
+  /** Calculate Kerr effective potential */
+  static kerrEffectivePotential(M: number, a: number, E: number, L: number, r: number): number;
+
+  /** Create a diagonal tensor */
+  static diagonal(values: number[], options?: TensorOptions): Tensor;
+
+  /** Create an identity tensor */
+  static identity(n?: number): Tensor;
+
+  /** Create a zero tensor */
+  static zero(n?: number): Tensor;
+
+  // Component Access
+  /** Get a component at indices */
+  get(i: number, j: number): number;
+
+  /** Return new tensor with component changed */
+  set(i: number, j: number, value: number): Tensor;
+
+  /** Get diagonal components */
+  getDiagonal(): number[];
+
+  // Tensor Operations
+  /** Add another tensor */
+  add(other: Tensor): Tensor;
+
+  /** Subtract another tensor */
+  subtract(other: Tensor): Tensor;
+
+  /** Multiply by scalar */
+  scale(scalar: number): Tensor;
+
+  /** Matrix multiply with another tensor */
+  multiply(other: Tensor): Tensor;
+
+  /** Transpose tensor */
+  transpose(): Tensor;
+
+  /** Compute inverse */
+  inverse(): Tensor;
+
+  // Derived Quantities
+  /** Compute determinant */
+  determinant(): number;
+
+  /** Compute trace */
+  trace(): number;
+
+  /** Check if diagonal */
+  isDiagonal(tolerance?: number): boolean;
+
+  /** Check if symmetric */
+  isSymmetric(tolerance?: number): boolean;
+
+  // GR Utilities
+  /**
+   * Compute Christoffel symbols for a metric.
+   * @param metricFn - Function returning metric at position
+   * @param position - Position [t, r, θ, φ]
+   * @param delta - Step size for numerical differentiation
+   */
+  static christoffel(
+    metricFn: (position: number[]) => Tensor,
+    position: number[],
+    delta?: number
+  ): number[][][];
+
+  /** Analytical Christoffel symbols for Schwarzschild */
+  static schwarzschildChristoffel(r: number, rs: number, theta: number): number[][][];
+
+  /** Compute effective potential for Schwarzschild geodesics */
+  static effectivePotential(M: number, L: number, r: number): number;
+
+  /** ISCO radius for Schwarzschild */
+  static iscoRadius(rs: number): number;
+
+  /** Photon sphere radius */
+  static photonSphereRadius(rs: number): number;
+
+  // Display
+  /** Get flat array of components */
+  toArray(): number[];
+
+  /** Get 2D array copy */
+  toMatrix(): number[][];
+
+  /** String representation */
+  toString(precision?: number): string;
+
+  /** LaTeX representation */
+  toLatex(precision?: number): string;
+}
+
+// ==========================================================================
+// General Relativity (gr.js)
+// ==========================================================================
+
+/**
+ * Calculate gravitational lensing deflection.
+ * @param b - Impact parameter
+ * @param M - Mass
+ * @returns Deflection angle in radians
+ */
+export function gravitationalLensingAngle(b: number, M: number): number;
+
+/**
+ * Calculate time dilation factor.
+ * @param r - Radial coordinate
+ * @param rs - Schwarzschild radius
+ * @returns Time dilation factor (0-1)
+ */
+export function timeDilationFactor(r: number, rs: number): number;
+
+/**
+ * Calculate gravitational redshift.
+ * @param r - Radial coordinate
+ * @param rs - Schwarzschild radius
+ * @returns Redshift z
+ */
+export function gravitationalRedshift(r: number, rs: number): number;
+
+// ==========================================================================
+// Orbital Mechanics (orbital.js)
+// ==========================================================================
+
+/** Orbital state vector */
+export interface OrbitalState {
+  x: number;
+  y: number;
+  z: number;
+  vx: number;
+  vy: number;
+  vz: number;
+}
+
+/** Keplerian orbital elements */
+export interface OrbitalElements {
+  a: number;  // Semi-major axis
+  e: number;  // Eccentricity
+  i: number;  // Inclination
+  Omega: number;  // Right ascension of ascending node
+  omega: number;  // Argument of periapsis
+  nu: number;  // True anomaly
+}
+
+/**
+ * Calculate orbital velocity at radius.
+ * @param r - Orbital radius
+ * @param M - Central mass
+ * @returns Orbital velocity
+ */
+export function orbitalVelocity(r: number, M: number): number;
+
+/**
+ * Calculate orbital period.
+ * @param a - Semi-major axis
+ * @param M - Central mass
+ * @returns Orbital period
+ */
+export function orbitalPeriod(a: number, M: number): number;
+
+/**
+ * Convert Keplerian elements to state vector.
+ * @param elements - Orbital elements
+ * @param mu - Gravitational parameter
+ */
+export function elementsToState(elements: OrbitalElements, mu: number): OrbitalState;
+
+/**
+ * Propagate orbit using Runge-Kutta.
+ * @param state - Current state
+ * @param dt - Time step
+ * @param mu - Gravitational parameter
+ */
+export function propagateOrbit(state: OrbitalState, dt: number, mu: number): OrbitalState;
+
+// ==========================================================================
+// Quantum Mechanics (quantum.js)
+// ==========================================================================
+
+/**
+ * Gaussian wave packet.
+ * @param x - Position
+ * @param x0 - Center position
+ * @param k0 - Central wavenumber
+ * @param sigma - Width parameter
+ * @param t - Time
+ * @returns Complex amplitude {re, im}
+ */
+export function gaussianWavePacket(
+  x: number,
+  x0: number,
+  k0: number,
+  sigma: number,
+  t: number
+): { re: number; im: number };
+
+/**
+ * Probability density |Ψ|².
+ * @param psi - Wave function value {re, im}
+ */
+export function probabilityDensity(psi: { re: number; im: number }): number;
+
+/**
+ * Particle in a box wave function.
+ * @param x - Position (0 to L)
+ * @param L - Box length
+ * @param n - Quantum number
+ */
+export function particleInBox(x: number, L: number, n: number): number;
+
+/**
+ * Harmonic oscillator wave function.
+ * @param x - Position
+ * @param n - Energy level
+ * @param omega - Angular frequency
+ * @param m - Mass
+ */
+export function harmonicOscillator(x: number, n: number, omega: number, m: number): number;
+
+// ==========================================================================
+// Heat Transfer (heat.js)
+// ==========================================================================
+
+/**
+ * Calculate heat transfer between two objects.
+ * @param T1 - Temperature of object 1
+ * @param T2 - Temperature of object 2
+ * @param k - Thermal conductivity
+ * @param dt - Time step
+ */
+export function heatTransfer(T1: number, T2: number, k: number, dt: number): number;
+
+/**
+ * Calculate buoyancy force.
+ * @param temperature - Object temperature
+ * @param ambientTemp - Ambient temperature
+ * @param coefficient - Buoyancy coefficient
+ */
+export function buoyancyForce(temperature: number, ambientTemp: number, coefficient: number): number;
+
+/**
+ * Temperature decay toward ambient.
+ * @param temp - Current temperature
+ * @param ambientTemp - Ambient temperature
+ * @param rate - Decay rate
+ * @param dt - Time step
+ */
+export function temperatureDecay(temp: number, ambientTemp: number, rate: number, dt: number): number;
+
+// ==========================================================================
+// Fluid Dynamics (fluid.js)
+// ==========================================================================
+
+/**
+ * Calculate viscosity drag force.
+ * @param velocity - Velocity vector
+ * @param viscosity - Fluid viscosity
+ */
+export function viscosityDrag(velocity: { x: number; y: number }, viscosity: number): { x: number; y: number };
+
+/**
+ * Calculate surface tension force.
+ * @param curvature - Surface curvature
+ * @param tension - Surface tension coefficient
+ */
+export function surfaceTension(curvature: number, tension: number): number;
+
+/**
+ * Calculate Reynolds number.
+ * @param velocity - Flow velocity
+ * @param length - Characteristic length
+ * @param viscosity - Kinematic viscosity
+ */
+export function reynoldsNumber(velocity: number, length: number, viscosity: number): number;
+
+/**
+ * Navier-Stokes pressure term.
+ * @param density - Fluid density
+ * @param pressure - Pressure
+ */
+export function pressureGradient(density: number, pressure: number): number;

package/types/motion.d.ts

@@ -676,3 +676,274 @@ export class Motion {
     state?: MotionState | null
   ): MotionResult;
 }
+
+// ==========================================================================
+// Standalone Motion Functions (V1 API)
+// ==========================================================================
+
+/**
+ * Standalone bezier curve motion animation.
+ * @see Motion.bezier for class method equivalent
+ */
+export function bezierV1(
+  p0: [number, number],
+  p1: [number, number],
+  p2: [number, number],
+  p3: [number, number],
+  elapsedTime: number,
+  duration: number,
+  loop?: boolean,
+  yoyo?: boolean,
+  easingFn?: EasingFunction | null,
+  callbacks?: MotionCallbacks,
+  state?: MotionState | null
+): MotionPositionResult;
+
+/**
+ * Standalone bounce animation.
+ * @see Motion.bounce for class method equivalent
+ */
+export function bounceV1(
+  maxHeight: number,
+  groundY: number,
+  bounceCount: number,
+  elapsedTime: number,
+  duration: number,
+  loop?: boolean,
+  easingFn?: EasingFunction | null,
+  callbacks?: MotionCallbacks,
+  state?: MotionState | null
+): MotionValueResult;
+
+/**
+ * Standalone floating motion animation.
+ * @see Motion.float for class method equivalent
+ */
+export function floatV1(
+  target: PositionTarget,
+  elapsedTime: number,
+  duration: number,
+  speed: number,
+  randomness: number,
+  radius: number,
+  loop?: boolean,
+  easingFn?: EasingFunction | null,
+  callbacks?: MotionCallbacks,
+  state?: MotionState | null
+): MotionPositionResult;
+
+/**
+ * Standalone path following animation.
+ * @see Motion.follow for class method equivalent
+ */
+export function followPath(
+  points: [number, number][],
+  closed: boolean,
+  elapsedTime: number,
+  duration: number,
+  loop?: boolean,
+  easingFn?: EasingFunction | null,
+  callbacks?: MotionCallbacks,
+  state?: MotionState | null
+): MotionPositionResult;
+
+/**
+ * Standalone orbital motion animation.
+ * @see Motion.orbit for class method equivalent
+ */
+export function orbitV1(
+  centerX: number,
+  centerY: number,
+  radiusX: number,
+  radiusY: number,
+  startAngle: number,
+  elapsedTime: number,
+  duration: number,
+  loop?: boolean,
+  clockwise?: boolean,
+  easingFn?: EasingFunction | null,
+  callbacks?: MotionCallbacks,
+  state?: MotionState | null
+): MotionPositionResult;
+
+/**
+ * Standalone oscillation animation.
+ * @see Motion.oscillate for class method equivalent
+ */
+export function oscillateV1(
+  min: number,
+  max: number,
+  elapsedTime: number,
+  duration: number,
+  loop?: boolean,
+  easingFn?: EasingFunction | null,
+  callbacks?: MotionCallbacks,
+  state?: MotionState | null
+): MotionValueResult;
+
+/**
+ * Standalone parabolic arc animation.
+ * @see Motion.parabolic for class method equivalent
+ */
+export function parabolicV1(
+  start: number,
+  peak: number,
+  end: number,
+  elapsedTime: number,
+  duration: number,
+  loop?: boolean,
+  yoyo?: boolean,
+  easingFn?: EasingFunction | null,
+  callbacks?: MotionCallbacks,
+  state?: MotionState | null
+): MotionValueResult;
+
+/**
+ * Standalone patrol animation.
+ * @see Motion.patrol for class method equivalent
+ */
+export function patrolV1(
+  initialX: number,
+  initialY: number,
+  elapsedTime: number,
+  moveTime: number,
+  waitTime: number,
+  radius: number,
+  loop?: boolean,
+  state?: MotionState | null
+): MotionPositionResult;
+
+/**
+ * Standalone pendulum animation.
+ * @see Motion.pendulum for class method equivalent
+ */
+export function pendulumV1(
+  originAngle: number,
+  amplitude: number,
+  elapsedTime: number,
+  duration: number,
+  loop?: boolean,
+  damped?: boolean,
+  easingFn?: EasingFunction | null,
+  callbacks?: MotionCallbacks,
+  state?: MotionState | null
+): MotionValueResult;
+
+/**
+ * Standalone pulse animation.
+ * @see Motion.pulse for class method equivalent
+ */
+export function pulseV1(
+  min: number,
+  max: number,
+  elapsedTime: number,
+  duration: number,
+  loop?: boolean,
+  yoyo?: boolean,
+  easingFn?: EasingFunction | null,
+  callbacks?: MotionCallbacks
+): MotionValueResult;
+
+/**
+ * Standalone hop/jump animation.
+ * @see Motion.hop for class method equivalent
+ */
+export function hopV1(
+  startX: number,
+  startY: number,
+  endX: number,
+  endY: number,
+  height: number,
+  elapsedTime: number,
+  duration: number,
+  loop?: boolean,
+  easingFn?: EasingFunction | null,
+  callbacks?: MotionCallbacks,
+  state?: MotionState | null
+): MotionPositionResult;
+
+/**
+ * Standalone shake animation.
+ * @see Motion.shake for class method equivalent
+ */
+export function shakeV1(
+  centerX: number,
+  centerY: number,
+  maxOffsetX: number,
+  maxOffsetY: number,
+  frequency: number,
+  decay: number,
+  elapsedTime: number,
+  duration: number,
+  loop?: boolean,
+  easingFn?: EasingFunction | null,
+  callbacks?: MotionCallbacks,
+  state?: MotionState | null
+): MotionPositionResult;
+
+/**
+ * Standalone spiral animation.
+ * @see Motion.spiral for class method equivalent
+ */
+export function spiralV1(
+  centerX: number,
+  centerY: number,
+  startRadius: number,
+  endRadius: number,
+  startAngle: number,
+  revolutions: number,
+  elapsedTime: number,
+  duration: number,
+  loop?: boolean,
+  yoyo?: boolean,
+  easingFn?: EasingFunction | null,
+  callbacks?: MotionCallbacks,
+  state?: MotionState | null
+): MotionPositionResult;
+
+/**
+ * Standalone spring animation.
+ * @see Motion.spring for class method equivalent
+ */
+export function springV1(
+  initial: number,
+  target: number,
+  elapsedTime: number,
+  duration: number,
+  loop?: boolean,
+  yoyo?: boolean,
+  springParams?: SpringParams,
+  callbacks?: MotionCallbacks
+): SpringResult;
+
+/**
+ * Standalone swing animation.
+ * @see Motion.swing for class method equivalent
+ */
+export function swingV1(
+  centerX: number,
+  centerY: number,
+  maxAngle: number,
+  elapsedTime: number,
+  duration: number,
+  loop?: boolean,
+  yoyo?: boolean,
+  easingFn?: EasingFunction | null,
+  callbacks?: MotionCallbacks,
+  state?: MotionState | null
+): MotionPositionResult;
+
+/**
+ * Standalone waypoint animation.
+ * @see Motion.waypoint for class method equivalent
+ */
+export function waypointV1(
+  target: PositionTarget,
+  elapsedTime: number,
+  waypoints: [number, number][],
+  speed: number,
+  waitTime: number,
+  loop?: boolean,
+  callbacks?: MotionCallbacks,
+  state?: MotionState | null
+): WaypointResult;