@higher.archi/boe 1.0.0

package/src/engines/fuzzy/fuzzy.membership.ts

@@ -0,0 +1,604 @@
+/**
+ * Fuzzy Engine Membership Functions
+ *
+ * Membership function implementations, compilation, and evaluation.
+ * Self-contained within the fuzzy engine.
+ */
+
+import {
+  MembershipShape,
+  CompiledMembershipFunction,
+  SemanticFuzzyTerm,
+  ExplicitFuzzyTerm,
+  FuzzyTerm,
+  CompiledFuzzyTerm,
+  FuzzyVariable,
+  CompiledFuzzyVariable,
+  isSemanticTerm,
+  POSITION_VALUES,
+  WIDTH_VALUES,
+  WidthSemantic
+} from './fuzzy.types';
+
+// ========================================
+// Membership Function Implementations
+// ========================================
+
+/**
+ * Triangle membership function
+ * params: [left, center, right]
+ *
+ *        1 ┤    /\
+ *          │   /  \
+ *          │  /    \
+ *        0 ┼─/──────\──
+ *           left center right
+ */
+export function triangleMembership(x: number, params: number[]): number {
+  const [left, center, right] = params;
+
+  if (x <= left || x >= right) return 0;
+  if (x === center) return 1;
+  if (x < center) return (x - left) / (center - left);
+  return (right - x) / (right - center);
+}
+
+/**
+ * Trapezoid membership function
+ * params: [left, leftTop, rightTop, right]
+ *
+ *        1 ┤   ┌────┐
+ *          │  /      \
+ *          │ /        \
+ *        0 ┼/──────────\─
+ *          left      right
+ */
+export function trapezoidMembership(x: number, params: number[]): number {
+  const [left, leftTop, rightTop, right] = params;
+
+  if (x <= left || x >= right) return 0;
+  if (x >= leftTop && x <= rightTop) return 1;
+  if (x < leftTop) return (x - left) / (leftTop - left);
+  return (right - x) / (right - rightTop);
+}
+
+/**
+ * Gaussian membership function
+ * params: [center, sigma]
+ *
+ *        1 ┤    ∩
+ *          │   / \
+ *          │  /   \
+ *        0 ┼─/─────\─
+ *             center
+ */
+export function gaussianMembership(x: number, params: number[]): number {
+  const [center, sigma] = params;
+  const exponent = -0.5 * Math.pow((x - center) / sigma, 2);
+  return Math.exp(exponent);
+}
+
+/**
+ * Shoulder membership function (left or right open)
+ * params: [inflectionStart, inflectionEnd]
+ *
+ * Left shoulder (open-left):     Right shoulder (open-right):
+ *        1 ┤────┐                       1 ┤      ┌────
+ *          │    \                         │     /
+ *          │     \                        │    /
+ *        0 ┼──────\──                   0 ┼───/─────
+ *
+ * For open-left: full membership from -∞ to inflectionStart, ramps down to 0 at inflectionEnd
+ * For open-right: 0 until inflectionStart, ramps up to full at inflectionEnd, stays 1 to +∞
+ */
+export function shoulderMembership(x: number, params: number[], edge: 'open-left' | 'open-right'): number {
+  const [inflectionStart, inflectionEnd] = params;
+
+  if (edge === 'open-left') {
+    // Full membership up to inflectionStart, ramps down to inflectionEnd
+    if (x <= inflectionStart) return 1;
+    if (x >= inflectionEnd) return 0;
+    return (inflectionEnd - x) / (inflectionEnd - inflectionStart);
+  } else {
+    // Zero until inflectionStart, ramps up to inflectionEnd, full after
+    if (x <= inflectionStart) return 0;
+    if (x >= inflectionEnd) return 1;
+    return (x - inflectionStart) / (inflectionEnd - inflectionStart);
+  }
+}
+
+/**
+ * Block (crisp/rectangular) membership function
+ * params: [left, right]
+ *
+ *        1 ┤  ┌────┐
+ *          │  │    │
+ *          │  │    │
+ *        0 ┼──┘────└──
+ *           left right
+ */
+export function blockMembership(x: number, params: number[]): number {
+  const [left, right] = params;
+  return (x >= left && x <= right) ? 1 : 0;
+}
+
+// ========================================
+// Membership Evaluation
+// ========================================
+
+/**
+ * Evaluate membership for a compiled membership function
+ */
+export function evaluateMembership(
+  x: number,
+  membership: CompiledMembershipFunction,
+  edge?: 'open-left' | 'open-right'
+): number {
+  switch (membership.shape) {
+    case 'triangle':
+      return triangleMembership(x, membership.params);
+    case 'trapezoid':
+      return trapezoidMembership(x, membership.params);
+    case 'gaussian':
+      return gaussianMembership(x, membership.params);
+    case 'shoulder':
+      if (!edge) throw new Error('Shoulder membership requires edge parameter');
+      return shoulderMembership(x, membership.params, edge);
+    case 'block':
+      return blockMembership(x, membership.params);
+    default:
+      throw new Error(`Unknown membership shape: ${membership.shape}`);
+  }
+}
+
+// ========================================
+// Semantic Term Compilation
+// ========================================
+
+/**
+ * Compile a semantic fuzzy term to explicit numeric parameters
+ */
+export function compileSemanticTerm(
+  term: SemanticFuzzyTerm,
+  domain: [number, number]
+): CompiledMembershipFunction {
+  const [min, max] = domain;
+  const range = max - min;
+
+  // Get position center point
+  const centerRatio = POSITION_VALUES[term.position];
+  const center = min + (range * centerRatio);
+
+  // Get width spread
+  const widthRatio = WIDTH_VALUES[term.width];
+  const spread = range * widthRatio;
+
+  switch (term.shape) {
+    case 'triangle':
+      return {
+        shape: 'triangle',
+        params: [center - spread, center, center + spread]
+      };
+
+    case 'trapezoid': {
+      // Plateau is 40% of total width
+      const plateau = spread * 0.4;
+      return {
+        shape: 'trapezoid',
+        params: [center - spread, center - plateau, center + plateau, center + spread]
+      };
+    }
+
+    case 'gaussian':
+      return {
+        shape: 'gaussian',
+        params: [center, spread / 2]  // sigma = half the spread
+      };
+
+    case 'shoulder': {
+      const edge = term.edge || 'open-left';
+      if (edge === 'open-left') {
+        // Ramps down from center to center + spread
+        return {
+          shape: 'shoulder',
+          params: [center, center + spread]
+        };
+      } else {
+        // Ramps up from center - spread to center
+        return {
+          shape: 'shoulder',
+          params: [center - spread, center]
+        };
+      }
+    }
+
+    case 'block':
+      return {
+        shape: 'block',
+        params: [center - spread, center + spread]
+      };
+
+    default:
+      throw new Error(`Unknown shape: ${term.shape}`);
+  }
+}
+
+/**
+ * Compile an explicit term (just validate and pass through)
+ */
+export function compileExplicitTerm(term: ExplicitFuzzyTerm): CompiledMembershipFunction {
+  // Validate params count for shape
+  const expectedParams: Record<MembershipShape, number> = {
+    'triangle': 3,
+    'trapezoid': 4,
+    'gaussian': 2,
+    'shoulder': 2,
+    'block': 2
+  };
+
+  const expected = expectedParams[term.shape];
+  if (term.params.length !== expected) {
+    throw new Error(
+      `${term.shape} membership requires ${expected} params, got ${term.params.length}`
+    );
+  }
+
+  return {
+    shape: term.shape,
+    params: term.params
+  };
+}
+
+/**
+ * Compile any fuzzy term (semantic or explicit)
+ */
+export function compileFuzzyTerm(
+  term: FuzzyTerm,
+  domain: [number, number]
+): CompiledFuzzyTerm {
+  const membership = isSemanticTerm(term)
+    ? compileSemanticTerm(term, domain)
+    : compileExplicitTerm(term);
+
+  return {
+    name: term.name,
+    membership
+  };
+}
+
+/**
+ * Compile a fuzzy variable with all its terms
+ */
+export function compileFuzzyVariable(variable: FuzzyVariable): CompiledFuzzyVariable {
+  const terms = variable.terms.map(term => compileFuzzyTerm(term, variable.domain));
+
+  // Build term index for fast lookup
+  const termIndex = new Map<string, CompiledFuzzyTerm>();
+  for (const term of terms) {
+    termIndex.set(term.name, term);
+  }
+
+  return {
+    name: variable.name,
+    domain: variable.domain,
+    terms,
+    termIndex
+  };
+}
+
+// ========================================
+// Variable Lookup Helpers
+// ========================================
+
+/**
+ * Parse a term reference like 'temperature.hot' into [variable, term]
+ */
+export function parseTermRef(ref: string): [string, string] {
+  const parts = ref.split('.');
+  if (parts.length !== 2) {
+    throw new Error(`Invalid term reference '${ref}', expected 'variable.term' format`);
+  }
+  return [parts[0], parts[1]];
+}
+
+/**
+ * Get membership degree for a value against a specific term
+ */
+export function getMembershipDegree(
+  value: number,
+  variable: CompiledFuzzyVariable,
+  termName: string
+): number {
+  const term = variable.termIndex.get(termName);
+  if (!term) {
+    throw new Error(`Term '${termName}' not found in variable '${variable.name}'`);
+  }
+
+  // For shoulder shapes, we need to determine edge from the term definition
+  // This info is lost in compilation, so we infer from params
+  if (term.membership.shape === 'shoulder') {
+    const [start, end] = term.membership.params;
+    const mid = (variable.domain[0] + variable.domain[1]) / 2;
+    const termCenter = (start + end) / 2;
+    const edge = termCenter < mid ? 'open-left' : 'open-right';
+    return evaluateMembership(value, term.membership, edge);
+  }
+
+  return evaluateMembership(value, term.membership);
+}
+
+/**
+ * Get all membership degrees for a value across all terms of a variable
+ */
+export function fuzzifyValue(
+  value: number,
+  variable: CompiledFuzzyVariable
+): Record<string, number> {
+  const result: Record<string, number> = {};
+
+  for (const term of variable.terms) {
+    result[term.name] = getMembershipDegree(value, variable, term.name);
+  }
+
+  return result;
+}
+
+// ========================================
+// Coverage Analysis & Auto-Adjustment
+// ========================================
+
+/**
+ * Coverage analysis result for a fuzzy variable
+ */
+export type CoverageAnalysis = {
+  /** Minimum coverage found (0-1, ideally > 0) */
+  minCoverage: number;
+  /** Average coverage across domain */
+  avgCoverage: number;
+  /** Maximum coverage (can exceed 1 with overlapping terms) */
+  maxCoverage: number;
+  /** Points where coverage drops below threshold */
+  gaps: Array<{ position: number; coverage: number }>;
+  /** Coverage values sampled across domain */
+  samples: Array<{ position: number; coverage: number }>;
+};
+
+/**
+ * Analyze coverage of a compiled fuzzy variable
+ * Returns statistics about how well the terms cover the domain
+ *
+ * @param variable - Compiled fuzzy variable to analyze
+ * @param resolution - Number of sample points (default 100)
+ * @param threshold - Coverage below this is considered a gap (default 0.1)
+ */
+export function analyzeCoverage(
+  variable: CompiledFuzzyVariable,
+  resolution: number = 100,
+  threshold: number = 0.1
+): CoverageAnalysis {
+  const [min, max] = variable.domain;
+  const step = (max - min) / resolution;
+
+  const samples: Array<{ position: number; coverage: number }> = [];
+  const gaps: Array<{ position: number; coverage: number }> = [];
+
+  let minCoverage = Infinity;
+  let maxCoverage = 0;
+  let totalCoverage = 0;
+
+  for (let i = 0; i <= resolution; i++) {
+    const position = min + (i * step);
+    const memberships = fuzzifyValue(position, variable);
+    const coverage = Object.values(memberships).reduce((sum, v) => sum + v, 0);
+
+    samples.push({ position, coverage });
+
+    if (coverage < minCoverage) minCoverage = coverage;
+    if (coverage > maxCoverage) maxCoverage = coverage;
+    totalCoverage += coverage;
+
+    if (coverage < threshold) {
+      gaps.push({ position, coverage });
+    }
+  }
+
+  return {
+    minCoverage,
+    maxCoverage,
+    avgCoverage: totalCoverage / (resolution + 1),
+    gaps,
+    samples
+  };
+}
+
+/**
+ * Options for auto-adjusting fuzzy variable coverage
+ */
+export type AutoAdjustOptions = {
+  /** Target minimum coverage (default 0.3) */
+  targetMinCoverage?: number;
+  /** Maximum width multiplier to apply (default 2.0) */
+  maxWidthMultiplier?: number;
+  /** Resolution for coverage analysis (default 100) */
+  resolution?: number;
+};
+
+/**
+ * Auto-adjust semantic term widths to ensure minimum coverage
+ * Returns a new variable definition with adjusted widths
+ *
+ * This works by:
+ * 1. Analyzing current coverage
+ * 2. Finding gaps where coverage < target
+ * 3. Expanding widths of terms to fill gaps
+ * 4. Repeating until coverage is adequate or terms can't expand further
+ *
+ * @param variable - Original fuzzy variable definition
+ * @param options - Adjustment options
+ * @returns Adjusted variable with expanded widths, or original if no adjustment needed
+ */
+export function autoAdjustCoverage(
+  variable: FuzzyVariable,
+  options: AutoAdjustOptions = {}
+): FuzzyVariable {
+  const {
+    targetMinCoverage = 0.3,
+    resolution = 100
+  } = options;
+
+  let currentVariable = variable;
+  const maxIterations = 5;  // Enough to go tight -> narrow -> medium -> wide -> very-wide
+
+  for (let iteration = 0; iteration < maxIterations; iteration++) {
+    // Compile and analyze current coverage
+    const compiled = compileFuzzyVariable(currentVariable);
+    const analysis = analyzeCoverage(compiled, resolution, targetMinCoverage);
+
+    // If coverage is adequate, we're done
+    if (analysis.minCoverage >= targetMinCoverage) {
+      return currentVariable;
+    }
+
+    // Check if all semantic terms are already at max width
+    const allMaxed = currentVariable.terms.every(term => {
+      if (isSemanticTerm(term)) {
+        return term.width === 'very-wide';
+      }
+      return false;  // Explicit terms can keep expanding
+    });
+
+    if (allMaxed) {
+      return currentVariable;  // Can't expand further
+    }
+
+    // Expand each term by one level
+    const adjustedTerms = currentVariable.terms.map(term => {
+      if (isSemanticTerm(term)) {
+        // Always jump one semantic level per iteration
+        const expandedWidth = expandWidthByOne(term.width);
+        return { ...term, width: expandedWidth };
+      }
+      // For explicit terms, multiply params
+      return expandExplicitTerm(term, 1.5, currentVariable.domain);
+    });
+
+    currentVariable = {
+      ...currentVariable,
+      terms: adjustedTerms
+    };
+  }
+
+  return currentVariable;
+}
+
+/**
+ * Expand a semantic width by exactly one level
+ */
+function expandWidthByOne(width: WidthSemantic): WidthSemantic {
+  const widthOrder: WidthSemantic[] = ['tight', 'narrow', 'medium', 'wide', 'very-wide'];
+  const currentIndex = widthOrder.indexOf(width);
+  const newIndex = Math.min(widthOrder.length - 1, currentIndex + 1);
+  return widthOrder[newIndex];
+}
+
+
+/**
+ * Expand an explicit term's parameters
+ */
+function expandExplicitTerm(
+  term: ExplicitFuzzyTerm,
+  multiplier: number,
+  domain: [number, number]
+): ExplicitFuzzyTerm {
+  const [min, max] = domain;
+
+  switch (term.shape) {
+    case 'triangle': {
+      // params: [left, center, right]
+      const [left, center, right] = term.params;
+      const leftSpread = (center - left) * multiplier;
+      const rightSpread = (right - center) * multiplier;
+      return {
+        ...term,
+        params: [
+          Math.max(min, center - leftSpread),
+          center,
+          Math.min(max, center + rightSpread)
+        ]
+      };
+    }
+
+    case 'trapezoid': {
+      // params: [left, leftTop, rightTop, right]
+      const [left, leftTop, rightTop, right] = term.params;
+      const leftSpread = (leftTop - left) * multiplier;
+      const rightSpread = (right - rightTop) * multiplier;
+      return {
+        ...term,
+        params: [
+          Math.max(min, leftTop - leftSpread),
+          leftTop,
+          rightTop,
+          Math.min(max, rightTop + rightSpread)
+        ]
+      };
+    }
+
+    case 'gaussian': {
+      // params: [center, sigma]
+      const [center, sigma] = term.params;
+      return {
+        ...term,
+        params: [center, sigma * multiplier]
+      };
+    }
+
+    case 'shoulder': {
+      // params: [inflectionStart, inflectionEnd]
+      const [start, end] = term.params;
+      const spread = Math.abs(end - start) * multiplier;
+      if (start < end) {
+        // open-left: expand end
+        return { ...term, params: [start, Math.min(max, start + spread)] };
+      } else {
+        // open-right: expand start
+        return { ...term, params: [Math.max(min, end - spread), end] };
+      }
+    }
+
+    case 'block': {
+      // params: [left, right]
+      const [left, right] = term.params;
+      const center = (left + right) / 2;
+      const halfWidth = ((right - left) / 2) * multiplier;
+      return {
+        ...term,
+        params: [
+          Math.max(min, center - halfWidth),
+          Math.min(max, center + halfWidth)
+        ]
+      };
+    }
+
+    default:
+      return term;
+  }
+}
+
+/**
+ * Compile a fuzzy variable with automatic coverage adjustment
+ *
+ * @param variable - Fuzzy variable definition
+ * @param options - Auto-adjust options (or false to disable)
+ * @returns Compiled variable with guaranteed minimum coverage
+ */
+export function compileFuzzyVariableWithCoverage(
+  variable: FuzzyVariable,
+  options: AutoAdjustOptions | false = {}
+): CompiledFuzzyVariable {
+  const adjusted = options === false
+    ? variable
+    : autoAdjustCoverage(variable, options);
+
+  return compileFuzzyVariable(adjusted);
+}