Similarity Calculator Architecture

Use this skill when working with similarity calculators, understanding calculator registration order, debugging calculator selection issues, or adding new similarity calculators.

Calculator Registration Order

Registration List (MPNUtils.java lines 37-51)

Calculators are registered in specific order. First applicable calculator wins and returns immediately - no fallthrough.

private static final List<ComponentSimilarityCalculator> calculators = Arrays.asList(
    new VoltageRegulatorSimilarityCalculator(),  // 1st priority
    new LEDSimilarityCalculator(),
    new OpAmpSimilarityCalculator(),
    new LogicICSimilarityCalculator(),
    new MemorySimilarityCalculator(),
    new DiodeSimilarityCalculator(),
    new SensorSimilarityCalculator(),
    new MosfetSimilarityCalculator(),
    new TransistorSimilarityCalculator(),
    new MicrocontrollerSimilarityCalculator(),
    new ResistorSimilarityCalculator(),
    new CapacitorSimilarityCalculator(),
    new ConnectorSimilarityCalculator()          // Last priority
);

Execution Flow

for (ComponentSimilarityCalculator calculator : calculators) {
    if (calculator.isApplicable(type1) || calculator.isApplicable(type2)) {
        double similarity = calculator.calculateSimilarity(mpn1, mpn2, registry);
        logger.debug("  Returning similarity: {}", similarity);
        return similarity;  // ← FIRST match wins, NO FALLTHROUGH!
    }
}
// Only reaches here if NO calculator claimed the types
return calculateDefaultSimilarity(mpn1, mpn2, type1, type2);

Critical properties:

1. First-applicable wins: No fallthrough to other calculators
2. Trusts calculator result: Even 0.0 is returned immediately (fixed in PR #114)
3. OR logic: If EITHER type1 OR type2 is applicable, calculator is used
4. No second chances: Once a calculator claims a type, its result is final

---

The OpAmp IC Interception Bug (PR #115)

Overview

• Discovered: January 14, 2026
• Impact: Logic ICs (CD4001, 74HC00) returned 0.0 similarity instead of 0.9
• Root cause: OpAmpSimilarityCalculator claimed ALL ICs but only handled op-amps
• Severity: CRITICAL - LogicICSimilarityCalculator never executed for logic ICs

The Bug

BEFORE (OpAmpSimilarityCalculator.java):

@Override
public boolean isApplicable(ComponentType type) {
    // ❌ BUG: This intercepted ALL ICs
    if (type == ComponentType.IC || type == ComponentType.ANALOG_IC) {
        return true;
    }
    return type == ComponentType.OPAMP || type.name().startsWith("OPAMP_");
}

@Override
public double calculateSimilarity(String mpn1, String mpn2, PatternRegistry registry) {
    // Check if both are actually op-amps
    if (!isOpAmp(mpn1) || !isOpAmp(mpn2)) {
        return 0.0;  // ← Returns 0.0 for logic ICs like CD4001!
    }
    // ... op-amp comparison logic (never executes for logic ICs)
}

Calculator registration order:

new OpAmpSimilarityCalculator(),   // ← Claims IC type first
new LogicICSimilarityCalculator(), // ← Never executes for ICs!

What happened:

1. CD4001 (logic IC) → ComponentType.IC
2. OpAmpSimilarityCalculator.isApplicable(IC) → true (claimed it!)
3. calculateSimilarity() → checks

   isOpAmp(CD4001)

   → false
4. Returns 0.0
5. LogicICSimilarityCalculator never executes (first-applicable-wins rule)

Impact Table

MPN1	MPN2	Expected	Actual (Bug)	Actual (Fixed)
CD4001	CD4001BE	0.9 (same chip)	0.0 ❌	0.9 ✅
74HC00	74HCT00	0.9 (equivalent)	0.0 ❌	0.9 ✅
LM358	LM358N	0.9 (same op-amp)	0.9 ✅	0.9 ✅
LM358	LM324	0.3 (different config)	0.3 ✅	0.3 ✅

The Fix

AFTER (Fixed - PR #115):

@Override
public boolean isApplicable(ComponentType type) {
    if (type == null) {
        return false;
    }

    // ✅ FIX: Only handle specific op-amp types
    // Don't intercept generic IC, ANALOG_IC, or other IC subtypes
    return type == ComponentType.OPAMP ||
           type == ComponentType.OPAMP_TI ||
           type.name().startsWith("OPAMP_");
}

Now logic ICs work correctly:

1. CD4001 → ComponentType.IC
2. OpAmpSimilarityCalculator.isApplicable(IC) → false (doesn't claim it)
3. LogicICSimilarityCalculator.isApplicable(IC) → true (claims it!)
4. LogicICSimilarityCalculator.calculateSimilarity() → 0.9 ✅

Test Updates

BEFORE (Incorrect test - validated the bug!):

@Test
void shouldBeApplicableForICTypes() {
    assertTrue(calculator.isApplicable(ComponentType.IC));
    assertTrue(calculator.isApplicable(ComponentType.ANALOG_IC));
}

AFTER (Fixed test):

@Test
void shouldNotBeApplicableForGenericICTypes() {
    // OpAmpSimilarityCalculator should only handle specific OPAMP types
    assertFalse(calculator.isApplicable(ComponentType.IC));
    assertFalse(calculator.isApplicable(ComponentType.ANALOG_IC));
}

@Test
void shouldBeApplicableForOpAmpTypes() {
    assertTrue(calculator.isApplicable(ComponentType.OPAMP));
    assertTrue(calculator.isApplicable(ComponentType.OPAMP_TI));
}

Lessons Learned

1. Calculator Order Matters

First applicable calculator wins. OpAmpSimilarityCalculator was before LogicICSimilarityCalculator, so it intercepted all ICs.

2. Be Specific in isApplicable()

Rule: Only claim types you can FULLY handle.

// ❌ WRONG: Claiming generic type but only handling subset
public boolean isApplicable(ComponentType type) {
    return type == ComponentType.IC;  // Claims ALL ICs!
}
public double calculateSimilarity(...) {
    if (!isOpAmp(mpn1)) return 0.0;  // But only handles op-amps
}

// ✅ CORRECT: Only claim what you handle
public boolean isApplicable(ComponentType type) {
    return type == ComponentType.OPAMP || type.name().startsWith("OPAMP_");
}

3. Test Ordering Matters

Bug only appeared in full test suite, not individual calculator tests. This is because:

• Individual test: Only one calculator exists in memory
• Full suite: All calculators compete, registration order matters

4. Domain Ownership Principle

Each calculator should own its specific domain:

• OpAmpSimilarityCalculator: OPAMP, OPAMP_* only
• LogicICSimilarityCalculator: IC (but checks if logic IC), LOGIC_IC, LOGIC_IC_*
• MemorySimilarityCalculator: MEMORY, MEMORY_* only

---

Calculator Ordering Strategy

Current Order Rationale

1. VoltageRegulatorSimilarityCalculator  ← Specific component type
2. LEDSimilarityCalculator               ← Specific component type
3. OpAmpSimilarityCalculator             ← Specific IC subtype (FIXED: no longer claims IC)
4. LogicICSimilarityCalculator           ← IC subtype (checks isLogicIC)
5. MemorySimilarityCalculator            ← Specific IC subtype
6. DiodeSimilarityCalculator             ← Specific semiconductor
7. SensorSimilarityCalculator            ← Specific component type
8. MosfetSimilarityCalculator            ← Specific semiconductor
9. TransistorSimilarityCalculator        ← Specific semiconductor
10. MicrocontrollerSimilarityCalculator  ← Specific IC subtype
11. ResistorSimilarityCalculator         ← Passive component
12. CapacitorSimilarityCalculator        ← Passive component
13. ConnectorSimilarityCalculator        ← Mechanical component

Ordering principles:

• Specific before generic: Voltage regulators before general ICs
• IC subtypes together: OpAmp, Logic, Memory, MCU grouped
• Semiconductors together: Diode, MOSFET, Transistor grouped
• Passives together: Resistor, Capacitor
• Connectors last: Most mechanical, least electrical

Ordering Bugs to Watch For

Bug Pattern	Example	Solution
Generic before specific	DefaultCalculator before OpAmpCalculator	Move specific calculators first
Claiming types you don't handle	OpAmp claims IC but only handles op-amps	Only claim types you fully handle
Overlapping domains	Two calculators claim MOSFET	Define clear ownership
No calculator for type	New GYROSCOPE type but no calculator	Add specific calculator or update default

---

Two Interface Types

1. SimilarityCalculator (Simple Interface)

Package:

no.cantara.electronic.component.lib

Purpose: Simple similarity calculation without type awareness.

public interface SimilarityCalculator {
    /**
     * Calculate similarity between two MPNs.
     *
     * @param mpn1 First MPN
     * @param mpn2 Second MPN
     * @return Similarity score [0.0, 1.0]
     */
    double calculateSimilarity(String mpn1, String mpn2);
}

Implementations:

• DefaultSimilarityCalculator

  - String-based similarity (Levenshtein, prefix matching)

• LevenshteinCalculator

  - Pure edit distance

Use when:

• Don't need component type information
• Comparing MPNs as strings
• Fallback/default comparison

---

2. ComponentSimilarityCalculator (Type-Aware Interface)

Package:

no.cantara.electronic.component.lib

Purpose: Type-aware similarity calculation with component-specific logic.

public interface ComponentSimilarityCalculator {
    /**
     * Check if this calculator is applicable for the given component type.
     *
     * @param type Component type to check
     * @return true if this calculator can handle this type
     */
    boolean isApplicable(ComponentType type);

    /**
     * Calculate similarity between two MPNs.
     *
     * @param mpn1 First MPN
     * @param mpn2 Second MPN
     * @param registry Pattern registry for component detection
     * @return Similarity score [0.0, 1.0]
     */
    double calculateSimilarity(String mpn1, String mpn2, PatternRegistry registry);
}

Implementations (17 total):

• ResistorSimilarityCalculator
• CapacitorSimilarityCalculator
• DiodeSimilarityCalculator
• MosfetSimilarityCalculator
• TransistorSimilarityCalculator
• OpAmpSimilarityCalculator
• VoltageRegulatorSimilarityCalculator
• LEDSimilarityCalculator
• MemorySimilarityCalculator
• SensorSimilarityCalculator
• LogicICSimilarityCalculator
• ConnectorSimilarityCalculator
• MicrocontrollerSimilarityCalculator
• MCUSimilarityCalculator
• PassiveComponentCalculator
• DefaultSimilarityCalculator (implements both)
• LevenshteinCalculator (implements both)

Use when:

• Need component-specific comparison logic
• Electrical specs matter (voltage, capacitance, resistance, etc.)
• Type-specific equivalent groups (e.g., 2N2222 ≈ PN2222)

---

Metadata-Driven Migration Status

12 of 17 calculators converted (71% complete)

Calculator	Status	PR	Conversion Date	Specs	Critical Specs
ResistorSimilarityCalculator	✅	Pre-existing	-	resistance, package, tolerance	resistance
CapacitorSimilarityCalculator	✅	Pre-existing	-	capacitance, voltage, dielectric, package	capacitance, voltage
TransistorSimilarityCalculator	✅	Pre-existing	-	polarity, voltageRating, currentRating, hfe, package	polarity, voltageRating, currentRating
DiodeSimilarityCalculator	✅	Pre-existing	-	type, voltageRating, currentRating, package	type, voltageRating, currentRating
MosfetSimilarityCalculator	✅	Pre-existing	-	channel, voltageRating, currentRating, rdsOn, package	channel, voltageRating, currentRating
VoltageRegulatorSimilarityCalculator	✅	Pre-existing	-	regulatorType, outputVoltage, polarity, currentRating, package	regulatorType, outputVoltage, polarity
OpAmpSimilarityCalculator	✅	#116	2026-01-08	configuration, family, package	configuration
MemorySimilarityCalculator	✅	#117	2026-01-09	memoryType, capacity, interface, package	memoryType, capacity
LEDSimilarityCalculator	✅	#118	2026-01-10	color, family, brightness, package	color
ConnectorSimilarityCalculator	✅	Pre-existing	-	pinCount, pitch, family, mountingType	pinCount, pitch
LogicICSimilarityCalculator	✅	#119	2026-01-11	function, series, technology, package	function
SensorSimilarityCalculator	✅	#120	2026-01-12	sensorType, family, interface, package	sensorType
MCUSimilarityCalculator	⏳	-	-	family, series, features	-
MicrocontrollerSimilarityCalculator	⏳	-	-	manufacturer, series, package	-
PassiveComponentCalculator	⏳	-	-	value, sizeCode, tolerance	-
DefaultSimilarityCalculator	⏳	-	-	-	-
LevenshteinCalculator	⏳	-	-	-	-

For metadata-driven migration details, see:

/similarity-metadata

and

/metadata-driven-similarity-conversion

skills.

---

Testing Strategy

isApplicable() Positive Tests

@Test
void shouldBeApplicableForOpAmpTypes() {
    assertTrue(calculator.isApplicable(ComponentType.OPAMP));
    assertTrue(calculator.isApplicable(ComponentType.OPAMP_TI));
    assertTrue(calculator.isApplicable(ComponentType.OPAMP_ANALOG_DEVICES));
}

isApplicable() Negative Tests (Critical!)

@Test
void shouldNotBeApplicableForGenericICTypes() {
    // OpAmpSimilarityCalculator should NOT claim generic IC types
    assertFalse(calculator.isApplicable(ComponentType.IC));
    assertFalse(calculator.isApplicable(ComponentType.ANALOG_IC));
}

@Test
void shouldNotBeApplicableForOtherComponentTypes() {
    assertFalse(calculator.isApplicable(ComponentType.RESISTOR));
    assertFalse(calculator.isApplicable(ComponentType.CAPACITOR));
    assertFalse(calculator.isApplicable(ComponentType.MOSFET));
}

Why negative tests are critical: They prevent the OpAmp IC interception bug from recurring. Explicitly test that calculators DON'T claim types they can't handle.

Integration Tests for Ordering

@Test
void logicICsShouldUseLogicCalculatorNotOpAmpCalculator() {
    // CD4001 is a logic IC, not an op-amp
    double similarity = MPNUtils.calculateSimilarity("CD4001", "CD4001BE");
    assertTrue(similarity >= 0.9, "Logic ICs should be highly similar");
    // If this fails, check if OpAmpSimilarityCalculator is claiming IC type
}

@Test
void opAmpsShouldUseOpAmpCalculator() {
    double similarity = MPNUtils.calculateSimilarity("LM358", "LM358N");
    assertTrue(similarity >= 0.9, "Same op-amp variants should be highly similar");
}

---

Learnings & Quirks

Calculator Selection is Deterministic

Given the same MPNs, the same calculator always wins (no randomness or concurrency issues).

0.0 is a Valid Result

PR #114 fixed MPNUtils to trust 0.0 results. Previously, 0.0 caused fallthrough to default calculator.

OR Logic in Selection

if (calculator.isApplicable(type1) || calculator.isApplicable(type2))

If EITHER component type is applicable, calculator is used. This allows cross-type comparisons (e.g., comparing OPAMP to OPAMP_TI).

No Fallback Chain

Unlike traditional strategy pattern with fallback chain, this implementation returns immediately on first match. There is no "try calculator A, then B, then C" logic.

isApplicable() vs calculateSimilarity() Consistency

Rule: If isApplicable() returns true, calculateSimilarity() MUST be able to handle those types.

OpAmp bug violated this rule:

• isApplicable(IC) → true
• calculateSimilarity(CD4001, ...) → 0.0 (can't handle logic ICs)

Prevention: Add validation in tests or runtime:

if (calculator.isApplicable(type) && similarity == 0.0) {
    logger.warn("Calculator {} claimed type {} but returned 0.0",
                calculator.getClass().getSimpleName(), type);
}

---

See Also

• /similarity

  - Main similarity system documentation

• /similarity-metadata

  - Metadata-driven similarity framework

• /metadata-driven-similarity-conversion

  - Migration guide for converting calculators

• .docs/history/BUG_FIX_ANALYSIS.md

  - Detailed bug analysis

• MPNUtils.java

  (lines 37-51) - Calculator registration

• OpAmpSimilarityCalculator.java

  - Example of fixed isApplicable()

• LogicICSimilarityCalculator.java

  - Handles logic ICs correctly