@higher.archi/boe 1.0.0

package/src/engines/fuzzy/fuzzy.defuzzify.ts

@@ -0,0 +1,564 @@
+/**
+ * Fuzzy Engine Defuzzification
+ *
+ * Aggregation, defuzzification, and transform methods.
+ * Self-contained within the fuzzy engine.
+ */
+
+import {
+  AggregationMethod,
+  DefuzzifyMethod,
+  TransformMethod,
+  DefuzzifyStage,
+  DefuzzifyConfig,
+  VariableMemberships,
+  CompiledFuzzyVariable,
+  expandDefuzzifyPreset
+} from './fuzzy.types';
+import { evaluateMembership } from './fuzzy.membership';
+
+// ========================================
+// Aggregation Methods
+// ========================================
+
+/**
+ * Aggregate multiple activation degrees for the same output term
+ * Called when multiple rules fire for the same output
+ */
+
+/**
+ * Maximum (standard fuzzy OR)
+ */
+export function aggregateMax(degrees: number[]): number {
+  return Math.max(...degrees);
+}
+
+/**
+ * Sum (can exceed 1.0)
+ */
+export function aggregateSum(degrees: number[]): number {
+  return degrees.reduce((a, b) => a + b, 0);
+}
+
+/**
+ * Probabilistic OR: a + b - ab (for two), generalized for n
+ * Result is always in [0, 1]
+ */
+export function aggregateProbor(degrees: number[]): number {
+  return degrees.reduce((acc, d) => acc + d - acc * d, 0);
+}
+
+/**
+ * Bounded sum: min(1, a + b)
+ */
+export function aggregateBound(degrees: number[]): number {
+  return Math.min(1, degrees.reduce((a, b) => a + b, 0));
+}
+
+/**
+ * Minimum (intersection - rare for aggregation)
+ */
+export function aggregateMin(degrees: number[]): number {
+  return Math.min(...degrees);
+}
+
+/**
+ * Apply aggregation method
+ */
+export function aggregate(method: AggregationMethod, degrees: number[]): number {
+  if (degrees.length === 0) return 0;
+  if (degrees.length === 1) return degrees[0];
+
+  switch (method) {
+    case 'max': return aggregateMax(degrees);
+    case 'sum': return aggregateSum(degrees);
+    case 'probor': return aggregateProbor(degrees);
+    case 'bound': return aggregateBound(degrees);
+    case 'min': return aggregateMin(degrees);
+    default:
+      throw new Error(`Unknown aggregation method: ${method}`);
+  }
+}
+
+// ========================================
+// Defuzzification Methods
+// ========================================
+
+/**
+ * Defuzzification input: aggregated memberships for an output variable
+ */
+export type DefuzzifyInput = {
+  variable: CompiledFuzzyVariable;
+  memberships: VariableMemberships;  // { 'low': 0.3, 'medium': 0.7, 'high': 0.2 }
+};
+
+/**
+ * Centroid (Center of Gravity)
+ * Most common defuzzification method - finds the balance point
+ *
+ * Uses numerical integration with term centers weighted by membership
+ */
+export function defuzzifyCentroid(input: DefuzzifyInput): number {
+  const { variable, memberships } = input;
+  const [min, max] = variable.domain;
+
+  // Sample points for numerical integration
+  const samples = 100;
+  const step = (max - min) / samples;
+
+  let numerator = 0;
+  let denominator = 0;
+
+  for (let i = 0; i <= samples; i++) {
+    const x = min + i * step;
+
+    // Find maximum membership at this point (aggregated output)
+    let maxMembership = 0;
+    for (const term of variable.terms) {
+      const termMembership = memberships[term.name] || 0;
+      if (termMembership > 0) {
+        // Clip the membership function at the activation level
+        const funcMembership = getMembershipAt(x, term, variable);
+        const clipped = Math.min(termMembership, funcMembership);
+        maxMembership = Math.max(maxMembership, clipped);
+      }
+    }
+
+    numerator += x * maxMembership;
+    denominator += maxMembership;
+  }
+
+  if (denominator === 0) {
+    // No membership - return domain midpoint
+    return (min + max) / 2;
+  }
+
+  return numerator / denominator;
+}
+
+/**
+ * Bisector - finds the x value that divides the area in half
+ */
+export function defuzzifyBisector(input: DefuzzifyInput): number {
+  const { variable, memberships } = input;
+  const [min, max] = variable.domain;
+
+  const samples = 100;
+  const step = (max - min) / samples;
+
+  // First, calculate total area
+  let totalArea = 0;
+  const heights: number[] = [];
+
+  for (let i = 0; i <= samples; i++) {
+    const x = min + i * step;
+    let maxMembership = 0;
+
+    for (const term of variable.terms) {
+      const termMembership = memberships[term.name] || 0;
+      if (termMembership > 0) {
+        const funcMembership = getMembershipAt(x, term, variable);
+        const clipped = Math.min(termMembership, funcMembership);
+        maxMembership = Math.max(maxMembership, clipped);
+      }
+    }
+
+    heights.push(maxMembership);
+    totalArea += maxMembership * step;
+  }
+
+  // Find the point where cumulative area equals half
+  const halfArea = totalArea / 2;
+  let cumulative = 0;
+
+  for (let i = 0; i <= samples; i++) {
+    cumulative += heights[i] * step;
+    if (cumulative >= halfArea) {
+      return min + i * step;
+    }
+  }
+
+  return (min + max) / 2;
+}
+
+/**
+ * Mean of Maximum (MoM)
+ * Average of all x values with maximum membership
+ */
+export function defuzzifyMom(input: DefuzzifyInput): number {
+  const { variable, memberships } = input;
+  const [min, max] = variable.domain;
+
+  const samples = 100;
+  const step = (max - min) / samples;
+
+  // Find the maximum membership value
+  let maxValue = 0;
+  for (let i = 0; i <= samples; i++) {
+    const x = min + i * step;
+    let membership = 0;
+
+    for (const term of variable.terms) {
+      const termMembership = memberships[term.name] || 0;
+      if (termMembership > 0) {
+        const funcMembership = getMembershipAt(x, term, variable);
+        const clipped = Math.min(termMembership, funcMembership);
+        membership = Math.max(membership, clipped);
+      }
+    }
+
+    maxValue = Math.max(maxValue, membership);
+  }
+
+  if (maxValue === 0) {
+    return (min + max) / 2;
+  }
+
+  // Find all x values with maximum membership
+  const maxPoints: number[] = [];
+  const tolerance = 0.001;
+
+  for (let i = 0; i <= samples; i++) {
+    const x = min + i * step;
+    let membership = 0;
+
+    for (const term of variable.terms) {
+      const termMembership = memberships[term.name] || 0;
+      if (termMembership > 0) {
+        const funcMembership = getMembershipAt(x, term, variable);
+        const clipped = Math.min(termMembership, funcMembership);
+        membership = Math.max(membership, clipped);
+      }
+    }
+
+    if (Math.abs(membership - maxValue) < tolerance) {
+      maxPoints.push(x);
+    }
+  }
+
+  // Return mean of maximum points
+  return maxPoints.reduce((a, b) => a + b, 0) / maxPoints.length;
+}
+
+/**
+ * Smallest of Maximum (SoM)
+ * Leftmost x value with maximum membership - conservative
+ */
+export function defuzzifySom(input: DefuzzifyInput): number {
+  const { variable, memberships } = input;
+  const [min, max] = variable.domain;
+
+  const samples = 100;
+  const step = (max - min) / samples;
+
+  let maxValue = 0;
+  let somPoint = min;
+
+  for (let i = 0; i <= samples; i++) {
+    const x = min + i * step;
+    let membership = 0;
+
+    for (const term of variable.terms) {
+      const termMembership = memberships[term.name] || 0;
+      if (termMembership > 0) {
+        const funcMembership = getMembershipAt(x, term, variable);
+        const clipped = Math.min(termMembership, funcMembership);
+        membership = Math.max(membership, clipped);
+      }
+    }
+
+    if (membership > maxValue) {
+      maxValue = membership;
+      somPoint = x;
+    }
+  }
+
+  return somPoint;
+}
+
+/**
+ * Largest of Maximum (LoM)
+ * Rightmost x value with maximum membership - aggressive
+ */
+export function defuzzifyLom(input: DefuzzifyInput): number {
+  const { variable, memberships } = input;
+  const [min, max] = variable.domain;
+
+  const samples = 100;
+  const step = (max - min) / samples;
+
+  let maxValue = 0;
+  let lomPoint = max;
+
+  for (let i = samples; i >= 0; i--) {
+    const x = min + i * step;
+    let membership = 0;
+
+    for (const term of variable.terms) {
+      const termMembership = memberships[term.name] || 0;
+      if (termMembership > 0) {
+        const funcMembership = getMembershipAt(x, term, variable);
+        const clipped = Math.min(termMembership, funcMembership);
+        membership = Math.max(membership, clipped);
+      }
+    }
+
+    if (membership > maxValue) {
+      maxValue = membership;
+      lomPoint = x;
+    }
+  }
+
+  return lomPoint;
+}
+
+/**
+ * Weighted Average (fast approximation)
+ * Uses term centers weighted by activation degree
+ */
+export function defuzzifyWtaver(input: DefuzzifyInput): number {
+  const { variable, memberships } = input;
+
+  let numerator = 0;
+  let denominator = 0;
+
+  for (const term of variable.terms) {
+    const degree = memberships[term.name] || 0;
+    if (degree > 0) {
+      // Get term center from membership params
+      const center = getTermCenter(term.membership.shape, term.membership.params);
+      numerator += center * degree;
+      denominator += degree;
+    }
+  }
+
+  if (denominator === 0) {
+    const [min, max] = variable.domain;
+    return (min + max) / 2;
+  }
+
+  return numerator / denominator;
+}
+
+/**
+ * Helper: get term center point from membership params
+ */
+function getTermCenter(shape: string, params: number[]): number {
+  switch (shape) {
+    case 'triangle':
+      return params[1];  // center
+    case 'trapezoid':
+      return (params[1] + params[2]) / 2;  // midpoint of plateau
+    case 'gaussian':
+      return params[0];  // center
+    case 'shoulder':
+      return (params[0] + params[1]) / 2;  // midpoint
+    case 'block':
+      return (params[0] + params[1]) / 2;  // midpoint
+    default:
+      return (params[0] + params[params.length - 1]) / 2;
+  }
+}
+
+/**
+ * Helper: get membership at a specific x for a term
+ */
+function getMembershipAt(
+  x: number,
+  term: { name: string; membership: { shape: string; params: number[] } },
+  variable: CompiledFuzzyVariable
+): number {
+  const { shape, params } = term.membership;
+
+  // For shoulder, infer edge from position
+  if (shape === 'shoulder') {
+    const [min, max] = variable.domain;
+    const mid = (min + max) / 2;
+    const termCenter = (params[0] + params[1]) / 2;
+    const edge = termCenter < mid ? 'open-left' : 'open-right';
+    return evaluateMembership(x, term.membership as any, edge);
+  }
+
+  return evaluateMembership(x, term.membership as any);
+}
+
+/**
+ * Apply defuzzification method
+ */
+export function defuzzify(method: DefuzzifyMethod, input: DefuzzifyInput): number {
+  switch (method) {
+    case 'centroid': return defuzzifyCentroid(input);
+    case 'bisector': return defuzzifyBisector(input);
+    case 'mom': return defuzzifyMom(input);
+    case 'som': return defuzzifySom(input);
+    case 'lom': return defuzzifyLom(input);
+    case 'wtaver': return defuzzifyWtaver(input);
+    default:
+      throw new Error(`Unknown defuzzification method: ${method}`);
+  }
+}
+
+// ========================================
+// Transform Methods
+// ========================================
+
+/**
+ * Clamp to output domain bounds
+ */
+export function transformClamp(value: number, domain: [number, number]): number {
+  const [min, max] = domain;
+  return Math.max(min, Math.min(max, value));
+}
+
+/**
+ * Round to integer
+ */
+export function transformRound(value: number): number {
+  return Math.round(value);
+}
+
+/**
+ * Deadband - zero out small values to reduce chatter
+ * Default threshold is 5% of domain range
+ */
+export function transformDeadband(
+  value: number,
+  domain: [number, number],
+  threshold?: number
+): number {
+  const [min, max] = domain;
+  const range = max - min;
+  const deadband = threshold ?? range * 0.05;
+
+  // If value is within deadband of domain minimum, return minimum
+  if (Math.abs(value - min) < deadband) {
+    return min;
+  }
+
+  return value;
+}
+
+/**
+ * Scale to a different output range
+ */
+export function transformScale(
+  value: number,
+  fromDomain: [number, number],
+  toDomain: [number, number]
+): number {
+  const [fromMin, fromMax] = fromDomain;
+  const [toMin, toMax] = toDomain;
+
+  const normalized = (value - fromMin) / (fromMax - fromMin);
+  return toMin + normalized * (toMax - toMin);
+}
+
+/**
+ * Quantize to discrete steps
+ */
+export function transformQuantize(
+  value: number,
+  domain: [number, number],
+  steps: number = 10
+): number {
+  const [min, max] = domain;
+  const range = max - min;
+  const stepSize = range / steps;
+
+  const normalized = (value - min) / range;
+  const stepIndex = Math.round(normalized * steps);
+
+  return min + stepIndex * stepSize;
+}
+
+/**
+ * Apply transform method
+ */
+export function transform(
+  method: TransformMethod,
+  value: number,
+  domain: [number, number]
+): number {
+  switch (method) {
+    case 'clamp': return transformClamp(value, domain);
+    case 'round': return transformRound(value);
+    case 'deadband': return transformDeadband(value, domain);
+    case 'scale': return value;  // Scale requires target domain - handled in pipeline
+    case 'quantize': return transformQuantize(value, domain);
+    default:
+      throw new Error(`Unknown transform method: ${method}`);
+  }
+}
+
+// ========================================
+// Pipeline Execution
+// ========================================
+
+/**
+ * Check if a stage is an aggregation method
+ */
+function isAggregationMethod(stage: string): stage is AggregationMethod {
+  return ['max', 'sum', 'probor', 'bound', 'min'].includes(stage);
+}
+
+/**
+ * Check if a stage is a defuzzify method
+ */
+function isDefuzzifyMethod(stage: string): stage is DefuzzifyMethod {
+  return ['centroid', 'bisector', 'mom', 'som', 'lom', 'wtaver'].includes(stage);
+}
+
+/**
+ * Check if a stage is a transform method
+ */
+function isTransformMethod(stage: string): stage is TransformMethod {
+  return ['clamp', 'round', 'deadband', 'scale', 'quantize'].includes(stage);
+}
+
+/**
+ * Defuzzification pipeline context
+ */
+export type PipelineContext = {
+  variable: CompiledFuzzyVariable;
+  memberships: VariableMemberships;
+  aggregationMethod: AggregationMethod;
+};
+
+/**
+ * Execute the defuzzification pipeline
+ */
+export function executePipeline(
+  config: DefuzzifyConfig,
+  context: PipelineContext
+): number {
+  // Expand preset if needed
+  const stages: DefuzzifyStage[] = typeof config === 'string'
+    ? expandDefuzzifyPreset(config)
+    : config;
+
+  const { variable, memberships } = context;
+  let defuzzifyMethod: DefuzzifyMethod = 'centroid';
+  const transforms: TransformMethod[] = [];
+
+  // Categorize stages
+  for (const stage of stages) {
+    if (isAggregationMethod(stage)) {
+      // Aggregation is handled at a higher level, skip here
+    } else if (isDefuzzifyMethod(stage)) {
+      defuzzifyMethod = stage;
+    } else if (isTransformMethod(stage)) {
+      transforms.push(stage);
+    }
+  }
+
+  // Execute defuzzification
+  const input: DefuzzifyInput = { variable, memberships };
+  let result = defuzzify(defuzzifyMethod, input);
+
+  // Apply transforms in order
+  for (const t of transforms) {
+    result = transform(t, result, variable.domain);
+  }
+
+  return result;
+}