@agentic-qe/v3 3.0.0-alpha.5 → 3.0.0-alpha.7

package/src/time-crystal/oscillator.ts

@@ -1,425 +0,0 @@
-/**
- * Agentic QE v3 - Oscillator Neuron
- * ADR-032: Kuramoto CPG oscillators for self-sustaining scheduling
- *
- * Implements the Kuramoto model for phase synchronization:
- *   dφ/dt = ω + K * Σ sin(φⱼ - φᵢ)
- *
- * Where:
- *   φ = phase angle
- *   ω = natural frequency
- *   K = coupling strength
- */
-
-import { OscillatorState } from './types';
-
-/**
- * Oscillator Neuron implementing Kuramoto dynamics
- *
- * Models a single oscillator in the CPG network.
- * Uses cosine activation for activity level.
- */
-export class OscillatorNeuron {
-  private id: number;
-  private phase: number;           // Current phase angle (0 to 2π)
-  private omega: number;           // Natural angular frequency (rad/ms)
-  private amplitude: number;
-  private activity: number;
-
-  /**
-   * Create a new oscillator neuron
-   *
-   * @param id - Unique oscillator identifier
-   * @param frequencyHz - Natural frequency in Hz
-   * @param phaseOffset - Initial phase offset in radians
-   * @param amplitude - Oscillation amplitude (default 1.0)
-   */
-  constructor(
-    id: number,
-    frequencyHz: number,
-    phaseOffset: number = 0,
-    amplitude: number = 1.0
-  ) {
-    this.id = id;
-    // Convert Hz to rad/ms: ω = 2π * f / 1000
-    this.omega = (2 * Math.PI * frequencyHz) / 1000;
-    this.phase = this.normalizePhase(phaseOffset);
-    this.amplitude = amplitude;
-    this.activity = this.amplitude * Math.cos(this.phase);
-  }
-
-  /**
-   * Integrate oscillator dynamics over one time step
-   *
-   * Implements Kuramoto-like dynamics:
-   *   dφ/dt = ω + coupling_input
-   *
-   * Where coupling_input is the sum of:
-   *   K * sin(φⱼ - φᵢ) for all coupled oscillators j
-   *
-   * @param dt - Time step in milliseconds
-   * @param couplingInput - Sum of coupling forces from other oscillators
-   */
-  integrate(dt: number, couplingInput: number): void {
-    // Compute phase change: dφ = (ω + coupling) * dt
-    const dPhase = (this.omega + couplingInput) * dt;
-    this.phase += dPhase;
-
-    // Normalize phase to [0, 2π)
-    this.phase = this.normalizePhase(this.phase);
-
-    // Update activity using cosine function
-    // Activity ranges from -amplitude to +amplitude
-    this.activity = this.amplitude * Math.cos(this.phase);
-  }
-
-  /**
-   * Integrate with external phase forcing
-   *
-   * Allows modulating the natural frequency with quality feedback
-   *
-   * @param dt - Time step in milliseconds
-   * @param couplingInput - Sum of coupling forces
-   * @param frequencyModulation - Modulation to natural frequency (-1 to 1)
-   */
-  integrateWithModulation(
-    dt: number,
-    couplingInput: number,
-    frequencyModulation: number = 0
-  ): void {
-    // Modulate frequency: slow down on poor quality, speed up on good
-    const modulatedOmega = this.omega * (1 + frequencyModulation * 0.5);
-    const dPhase = (modulatedOmega + couplingInput) * dt;
-    this.phase += dPhase;
-    this.phase = this.normalizePhase(this.phase);
-    this.activity = this.amplitude * Math.cos(this.phase);
-  }
-
-  /**
-   * Get the current phase angle
-   *
-   * @returns Phase in radians [0, 2π)
-   */
-  getPhase(): number {
-    return this.phase;
-  }
-
-  /**
-   * Get the current activity level
-   *
-   * @returns Activity level [-amplitude, +amplitude]
-   */
-  getActivity(): number {
-    return this.activity;
-  }
-
-  /**
-   * Get the oscillator's unique identifier
-   */
-  getId(): number {
-    return this.id;
-  }
-
-  /**
-   * Get the natural angular frequency
-   *
-   * @returns Angular frequency in rad/ms
-   */
-  getOmega(): number {
-    return this.omega;
-  }
-
-  /**
-   * Get the oscillation amplitude
-   */
-  getAmplitude(): number {
-    return this.amplitude;
-  }
-
-  /**
-   * Set the oscillation amplitude
-   *
-   * @param amplitude - New amplitude value
-   */
-  setAmplitude(amplitude: number): void {
-    this.amplitude = amplitude;
-    this.activity = this.amplitude * Math.cos(this.phase);
-  }
-
-  /**
-   * Set the natural frequency
-   *
-   * @param frequencyHz - New frequency in Hz
-   */
-  setFrequency(frequencyHz: number): void {
-    this.omega = (2 * Math.PI * frequencyHz) / 1000;
-  }
-
-  /**
-   * Reset the oscillator to a specific phase
-   *
-   * @param phase - Phase angle in radians
-   */
-  reset(phase: number): void {
-    this.phase = this.normalizePhase(phase);
-    this.activity = this.amplitude * Math.cos(this.phase);
-  }
-
-  /**
-   * Get the complete state of the oscillator
-   */
-  getState(): OscillatorState {
-    return {
-      id: this.id,
-      phase: this.phase,
-      omega: this.omega,
-      amplitude: this.amplitude,
-      activity: this.activity,
-    };
-  }
-
-  /**
-   * Restore oscillator from state
-   *
-   * @param state - State to restore
-   */
-  restoreState(state: OscillatorState): void {
-    if (state.id !== this.id) {
-      throw new Error(`State id mismatch: expected ${this.id}, got ${state.id}`);
-    }
-    this.phase = state.phase;
-    this.omega = state.omega;
-    this.amplitude = state.amplitude;
-    this.activity = state.activity;
-  }
-
-  /**
-   * Compute Kuramoto coupling input from another oscillator
-   *
-   * @param other - The other oscillator
-   * @param couplingStrength - Coupling strength K
-   * @returns Coupling force: K * sin(φⱼ - φᵢ)
-   */
-  computeCouplingFrom(other: OscillatorNeuron, couplingStrength: number): number {
-    const phaseDiff = other.getPhase() - this.phase;
-    return couplingStrength * Math.sin(phaseDiff);
-  }
-
-  /**
-   * Check if this oscillator is in phase with another
-   *
-   * @param other - The other oscillator
-   * @param tolerance - Phase difference tolerance in radians
-   * @returns True if oscillators are in phase
-   */
-  isInPhaseWith(other: OscillatorNeuron, tolerance: number = 0.1): boolean {
-    const phaseDiff = Math.abs(this.phase - other.getPhase());
-    // Account for wrap-around
-    const normalizedDiff = Math.min(phaseDiff, 2 * Math.PI - phaseDiff);
-    return normalizedDiff <= tolerance;
-  }
-
-  /**
-   * Check if this oscillator is anti-phase with another
-   *
-   * @param other - The other oscillator
-   * @param tolerance - Phase difference tolerance in radians
-   * @returns True if oscillators are anti-phase
-   */
-  isAntiPhaseWith(other: OscillatorNeuron, tolerance: number = 0.1): boolean {
-    const phaseDiff = Math.abs(this.phase - other.getPhase());
-    const normalizedDiff = Math.min(phaseDiff, 2 * Math.PI - phaseDiff);
-    return Math.abs(normalizedDiff - Math.PI) <= tolerance;
-  }
-
-  /**
-   * Normalize phase to [0, 2π) range
-   */
-  private normalizePhase(phase: number): number {
-    const TWO_PI = 2 * Math.PI;
-    while (phase >= TWO_PI) {
-      phase -= TWO_PI;
-    }
-    while (phase < 0) {
-      phase += TWO_PI;
-    }
-    return phase;
-  }
-
-  /**
-   * Create a copy of this oscillator
-   */
-  clone(): OscillatorNeuron {
-    const clone = new OscillatorNeuron(
-      this.id,
-      0, // Frequency will be set via state
-      0,
-      this.amplitude
-    );
-    clone.restoreState(this.getState());
-    return clone;
-  }
-}
-
-/**
- * Compute the Kuramoto order parameter for a set of oscillators
- *
- * The order parameter r measures synchronization:
- *   r * e^(iψ) = (1/N) * Σ e^(iφⱼ)
- *
- * Where:
- *   r = magnitude (0 = desynchronized, 1 = fully synchronized)
- *   ψ = mean phase
- *
- * @param oscillators - Array of oscillator neurons
- * @returns Object containing order parameter r and mean phase psi
- */
-export function computeOrderParameter(oscillators: OscillatorNeuron[]): {
-  r: number;
-  psi: number;
-} {
-  if (oscillators.length === 0) {
-    return { r: 0, psi: 0 };
-  }
-
-  // Compute complex mean: (1/N) * Σ e^(iφⱼ)
-  let sumCos = 0;
-  let sumSin = 0;
-
-  for (const osc of oscillators) {
-    const phase = osc.getPhase();
-    sumCos += Math.cos(phase);
-    sumSin += Math.sin(phase);
-  }
-
-  const n = oscillators.length;
-  const meanCos = sumCos / n;
-  const meanSin = sumSin / n;
-
-  // r = magnitude, psi = angle
-  const r = Math.sqrt(meanCos * meanCos + meanSin * meanSin);
-  const psi = Math.atan2(meanSin, meanCos);
-
-  return { r, psi };
-}
-
-/**
- * Compute phase coherence between oscillators
- *
- * Coherence measures how consistent the phase differences are over time
- *
- * @param phases - Array of phase arrays (one per oscillator)
- * @returns Coherence value (0 = incoherent, 1 = perfectly coherent)
- */
-export function computePhaseCoherence(phases: number[][]): number {
-  if (phases.length < 2 || phases[0].length < 2) {
-    return 0;
-  }
-
-  const numOscillators = phases.length;
-  const numSamples = phases[0].length;
-
-  // Compute mean phase difference variance
-  let totalVariance = 0;
-  let pairCount = 0;
-
-  for (let i = 0; i < numOscillators; i++) {
-    for (let j = i + 1; j < numOscillators; j++) {
-      // Compute phase differences for this pair
-      const diffs: number[] = [];
-      for (let t = 0; t < numSamples; t++) {
-        let diff = phases[i][t] - phases[j][t];
-        // Normalize to [-π, π]
-        while (diff > Math.PI) diff -= 2 * Math.PI;
-        while (diff < -Math.PI) diff += 2 * Math.PI;
-        diffs.push(diff);
-      }
-
-      // Compute variance of phase differences
-      const mean = diffs.reduce((a, b) => a + b, 0) / diffs.length;
-      const variance = diffs.reduce((a, b) => a + (b - mean) ** 2, 0) / diffs.length;
-      totalVariance += variance;
-      pairCount++;
-    }
-  }
-
-  // Normalize: high variance = low coherence
-  const avgVariance = pairCount > 0 ? totalVariance / pairCount : 0;
-  // Max variance for uniform distribution is π²/3 ≈ 3.29
-  const normalizedVariance = avgVariance / (Math.PI * Math.PI / 3);
-  const coherence = Math.max(0, 1 - normalizedVariance);
-
-  return coherence;
-}
-
-/**
- * Create evenly spaced oscillators for a CPG
- *
- * @param count - Number of oscillators
- * @param frequencyHz - Oscillation frequency in Hz
- * @returns Array of oscillators with evenly distributed initial phases
- */
-export function createEvenlySpacedOscillators(
-  count: number,
-  frequencyHz: number
-): OscillatorNeuron[] {
-  const oscillators: OscillatorNeuron[] = [];
-
-  for (let i = 0; i < count; i++) {
-    const phaseOffset = (2 * Math.PI * i) / count;
-    oscillators.push(new OscillatorNeuron(i, frequencyHz, phaseOffset));
-  }
-
-  return oscillators;
-}
-
-/**
- * Build a ring coupling matrix for nearest-neighbor coupling
- *
- * @param count - Number of oscillators
- * @param couplingStrength - Coupling strength K
- * @returns 2D coupling matrix
- */
-export function buildRingCouplingMatrix(
-  count: number,
-  couplingStrength: number
-): number[][] {
-  const matrix: number[][] = Array(count)
-    .fill(null)
-    .map(() => Array(count).fill(0));
-
-  for (let i = 0; i < count; i++) {
-    const prev = (i + count - 1) % count;
-    const next = (i + 1) % count;
-    matrix[i][prev] = couplingStrength;
-    matrix[i][next] = couplingStrength;
-  }
-
-  return matrix;
-}
-
-/**
- * Build an all-to-all coupling matrix
- *
- * @param count - Number of oscillators
- * @param couplingStrength - Coupling strength K
- * @returns 2D coupling matrix
- */
-export function buildAllToAllCouplingMatrix(
-  count: number,
-  couplingStrength: number
-): number[][] {
-  const matrix: number[][] = Array(count)
-    .fill(null)
-    .map(() => Array(count).fill(0));
-
-  for (let i = 0; i < count; i++) {
-    for (let j = 0; j < count; j++) {
-      if (i !== j) {
-        matrix[i][j] = couplingStrength / (count - 1); // Normalize
-      }
-    }
-  }
-
-  return matrix;
-}