implement singleton sets to take their special needs into account

Author: amogorkon

src/fuzzylogic/classes.py

@@ -438,6 +438,47 @@ def __hash__(self) -> int:
         return id(self)
 
 
+class SingletonSet(Set):
+    def __init__(self, c: float, no_m: float = 0, c_m: float = 1, domain: Domain | None = None):
+        super().__init__(self._singleton_fn(c, no_m, c_m), domain=domain)
+        self.c = c
+        self.no_m = no_m
+        self.c_m = c_m
+        self.domain = domain
+
+        self._cached_array: np.ndarray | None = None
+
+    @staticmethod
+    def _singleton_fn(c: float, no_m: float = 0, c_m: float = 1) -> Membership:
+        return lambda x: c_m if x == c else no_m
+
+    def center_of_gravity(self) -> float:
+        """Directly return singleton position"""
+        return self.c
+
+    def plot(self) -> None:
+        """Graph the singleton set in the given domain,
+        ensuring that the singleton's coordinate is included.
+        """
+        assert self.domain is not None, "NO_DOMAIN"
+        if not plt:
+            raise ImportError(
+                "matplotlib not available. Please re-install with 'pip install fuzzylogic[plotting]'"
+            )
+
+        R = self.domain.range
+        if self.c not in R:
+            R = sorted(set(R).union({self.c}))
+        V = [self.func(x) for x in R]
+        plt.plot(R, V, label=f"Singleton {self.c}")
+        plt.title("Singleton Membership Function")
+        plt.xlabel("Domain Value")
+        plt.ylabel("Membership")
+        plt.legend()
+        plt.grid(True)
+        plt.show()
+
+
 class Rule:
     """
     Collection of bound sets spanning a multi-dimensional space of their domains, mapping to a target domain.

src/fuzzylogic/functions.py

@@ -26,12 +26,18 @@
 In a fuzzy set with one and only one m == 1, this element is called 'prototype'.
 """
 
+from __future__ import annotations
+
 from collections.abc import Callable
 from math import exp, isinf, isnan, log
-from typing import Any
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from .classes import SingletonSet
 
 type Membership = Callable[[float], float]
 
+
 try:
     # from numba import njit # still not ready for prime time :(
     raise ImportError
@@ -146,21 +152,20 @@ def f(x: float) -> float:
 ########################
 
 
-def singleton(p: float, *, no_m: float = 0, c_m: float = 1) -> Membership:
-    """A single spike.
+def singleton(c: float, no_m: float = 0, c_m: float = 1) -> SingletonSet:
+    """A singleton function.
 
-    >>> f = singleton(2)
-    >>> f(1)
-    0
-    >>> f(2)
-    1
-    """
-    assert 0 <= no_m < c_m <= 1
+    This is unusually tricky because the CoG sums up all values and divides by the number of values, which
+    may result in 0 due to rounding errors.
+    Additionally and more significantly, a singleton well within domain range but not within
+    its resolution will never be found and considered. Thus, singletons need special treatment.
 
-    def f(x: float) -> float:
-        return c_m if x == p else no_m
+    We solve this issue by returning a special subclass (which must be imported here due to circular import),
+    which overrides the normal CoG implementation, but still works with the rest of the code.
+    """
+    from .classes import SingletonSet
 
-    return f
+    return SingletonSet(c, no_m=no_m, c_m=c_m)
 
 
 def linear(m: float = 0, b: float = 0) -> Membership:

tests/test_singleton.py

@@ -0,0 +1,133 @@
+from __future__ import annotations
+
+import math
+
+import numpy as np
+import pytest
+from hypothesis import given
+from hypothesis import strategies as st
+
+from fuzzylogic.classes import Domain
+from fuzzylogic.functions import singleton
+
+# ---------------------------------------------------------------------------
+# Basic Unit Tests
+# ---------------------------------------------------------------------------
+
+
+def test_singleton_membership():
+    """Test that a singleton returns 1.0 exactly at its specified location and 0 elsewhere."""
+    s = singleton(500)
+    # Exact hit yields 1.0
+    assert s(500) == 1.0
+    # Any other value yields 0.0
+    assert s(499.999) == 0.0
+    assert s(500.1) == 0.0
+
+
+def test_singleton_center_of_gravity():
+    """Test that the center_of_gravity always returns the singleton’s location."""
+    for c in [0, 250, 500, 750, 1000]:
+        s = singleton(c)
+        assert s.center_of_gravity() == c, f"Expected COG {c}, got {s.center_of_gravity()}"
+
+
+# ---------------------------------------------------------------------------
+# Domain Integration Tests
+# ---------------------------------------------------------------------------
+
+
+def test_singleton_with_domain():
+    """
+    Test that a SingletonSet assigned to a domain yields the expected membership
+    array, containing a spike at the correct position.
+    """
+    D = Domain("D", 0, 1000)
+    s = singleton(500)
+    s.domain = D
+
+    arr = s.array()
+    points = D.range
+
+    assert 500 in points, "Domain should contain 500 exactly."
+    idx = points[500]
+
+    np.testing.assert_almost_equal(arr[idx], 1.0)
+    np.testing.assert_almost_equal(arr.sum(), 1.0)
+
+
+@given(c=st.integers(min_value=0, max_value=1000))
+def test_singleton_property_center(c: int):
+    """
+    Property-based test: For any integer c in [0, 1000], a singleton defined at c
+    (and assigned to an appropriately discretized Domain) has a center-of-gravity equal to c.
+    """
+    D = Domain("D", 0, 1000)
+    s = singleton(c)
+    s.domain = D
+    assert s.center_of_gravity() == c
+
+
+# ---------------------------------------------------------------------------
+# Fuzzy Operation Integration Tests
+# ---------------------------------------------------------------------------
+
+
+def test_singleton_union():
+    """
+    Test that the fuzzy union (OR) of two disjoint singleton sets creates a fuzzy set
+    containing two spikes – one at each singleton location.
+    """
+    D = Domain("D", 0, 1000)
+    s1 = singleton(500)
+    s2 = singleton(600)
+    s1.domain = D
+    s2.domain = D
+
+    union_set = s1 | s2
+    union_set.domain = D
+
+    arr = union_set.array()
+    points = D.range
+
+    assert 500 in points and 600 in points
+    idx_500 = points[500]
+    idx_600 = points[600]
+    np.testing.assert_almost_equal(arr[idx_500], 1.0)
+    np.testing.assert_almost_equal(arr[idx_600], 1.0)
+
+    np.testing.assert_almost_equal(arr.sum(), 2.0)
+
+
+# ---------------------------------------------------------------------------
+# Differential / Regression Testing with Defuzzification
+# ---------------------------------------------------------------------------
+
+
+def test_singleton_defuzzification():
+    """
+    Test that when a singleton is used in defuzzification (via center_of_gravity),
+    the exact spike value is returned regardless of discrete sampling issues.
+    """
+    s = singleton(500.1)
+    assert math.isclose(s.center_of_gravity(), 500.1, rel_tol=1e-9)
+
+
+# ---------------------------------------------------------------------------
+# Performance
+# ---------------------------------------------------------------------------
+
+
+def test_singleton_performance():
+    """
+    A basic performance test to ensure that evaluating a singleton over a large domain
+    remains efficient.
+    """
+    D = Domain("D", 0, 1000, res=0.0001)  # A large domain
+    D.s = singleton(500)
+    time_taken = pytest.importorskip("timeit").timeit(lambda: D.s.array(), number=10)
+    assert time_taken < 1, "Performance slowed down unexpectedly."
+
+
+if __name__ == "__main__":
+    pytest.main([__file__, "-v"])