fuzzytool 0.1.0__py3-none-any.whl

fuzzytool/ftransform.py

@@ -0,0 +1,79 @@
+"""F-transform — the fuzzy transform of Perfilieva.
+
+The F-transform projects a function onto a *fuzzy partition* of its domain. Over
+a uniform partition by triangular basis functions ``A_1..A_n`` that satisfy the
+Ruspini condition (they sum to 1 everywhere on ``[a, b]``):
+
+* the **direct** transform reduces the data to ``n`` components, each a
+  membership-weighted average of the samples falling under one basis function;
+* the **inverse** transform reconstructs an approximation
+  ``f̂(x) = Σ_k F_k · A_k(x)``.
+
+With few components the round trip smooths/denoises a signal; with many it
+approximates it closely. Pure NumPy.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+_EPS = 1e-12
+
+
+class FTransform:
+    """A triangular F-transform over a uniform fuzzy partition of ``[a, b]``.
+
+    Args:
+        a: left end of the domain.
+        b: right end of the domain (``b > a``).
+        n_basis: number of basis functions / components (``>= 2``).
+    """
+
+    def __init__(self, a: float, b: float, n_basis: int) -> None:
+        if b <= a:
+            raise ValueError(f"need a < b, got ({a}, {b})")
+        if n_basis < 2:
+            raise ValueError("need n_basis >= 2")
+        self.a, self.b = float(a), float(b)
+        self.nodes = np.linspace(a, b, n_basis)            # basis centers
+        self.h = self.nodes[1] - self.nodes[0]             # uniform spacing
+        self.components_: np.ndarray | None = None
+
+    def basis(self, x) -> np.ndarray:
+        """Triangular basis matrix ``A`` of shape ``(len(x), n_basis)``.
+
+        Columns form a partition of unity on ``[a, b]`` (each row sums to 1).
+        """
+        x = np.asarray(x, dtype=float)
+        return np.clip(1.0 - np.abs(x[:, None] - self.nodes[None, :]) / self.h, 0.0, 1.0)
+
+    def direct(self, x, y) -> np.ndarray:
+        """Direct F-transform: the ``n_basis`` components from samples ``(x, y)``."""
+        x = np.asarray(x, dtype=float)
+        y = np.asarray(y, dtype=float).ravel()
+        a = self.basis(x)
+        comp = (a.T @ y) / np.fmax(a.sum(axis=0), _EPS)
+        self.components_ = comp
+        return comp
+
+    def inverse(self, x, components: np.ndarray | None = None) -> np.ndarray:
+        """Inverse F-transform: reconstruct values at ``x`` from components."""
+        comp = self.components_ if components is None else np.asarray(components, float)
+        if comp is None:
+            raise RuntimeError("no components; call direct first or pass them in")
+        return self.basis(x) @ comp
+
+    def fit(self, x, y) -> FTransform:
+        """Compute and store the direct transform of ``(x, y)``; returns ``self``."""
+        self.direct(x, y)
+        return self
+
+    def smooth(self, x) -> np.ndarray:
+        """Convenience: direct-then-inverse at ``x`` (requires a prior fit)."""
+        return self.inverse(x)
+
+    def __repr__(self) -> str:
+        return f"FTransform([{self.a}, {self.b}], n_basis={len(self.nodes)})"
+
+
+__all__ = ["FTransform"]

fuzzytool/inference/__init__.py

@@ -0,0 +1,6 @@
+"""Fuzzy inference engines."""
+
+from .mamdani import Mamdani
+from .tsk import TSK
+
+__all__ = ["Mamdani", "TSK"]

fuzzytool/inference/mamdani.py

@@ -0,0 +1,93 @@
+"""Mamdani fuzzy inference.
+
+The engine knows nothing about specific membership functions, connectives, or
+defuzzifiers: t-norm, s-norm, implication, aggregation and defuzzification are
+all resolved by name (or supplied as callables) and applied uniformly. Adding a
+behavior means registering a function in :mod:`fuzzytool.norms` or
+:mod:`fuzzytool.defuzz`, never editing this loop.
+
+Pipeline per call: evaluate each rule's antecedent to a firing strength →
+shape its consequent term over the output universe via the *implication*
+operator → *aggregate* the shaped sets per output variable → *defuzzify*.
+"""
+
+from __future__ import annotations
+
+from typing import Callable
+
+import numpy as np
+
+from ..defuzz import get_defuzzifier
+from ..norms import get_snorm, get_tnorm
+from ..rules import Rule
+from ..sets import Antecedent, Proposition, Variable
+
+
+class Mamdani:
+    """A Mamdani inference system.
+
+    Args:
+        tnorm: t-norm for AND in antecedents (default ``"min"``).
+        snorm: s-norm for OR in antecedents (default ``"max"``).
+        implication: how a firing strength shapes its consequent set —
+            ``"min"`` (clip) or ``"prod"`` (scale).
+        aggregation: s-norm combining shaped sets per output (default ``"max"``).
+        defuzz: defuzzification method (default ``"centroid"``).
+    """
+
+    def __init__(
+        self,
+        tnorm: str | Callable = "min",
+        snorm: str | Callable = "max",
+        implication: str = "min",
+        aggregation: str | Callable = "max",
+        defuzz: str | Callable = "centroid",
+    ) -> None:
+        self.tnorm = get_tnorm(tnorm)
+        self.snorm = get_snorm(snorm)
+        if implication not in ("min", "prod"):
+            raise ValueError("implication must be 'min' or 'prod'")
+        self.implication = implication
+        self.aggregation = get_snorm(aggregation)
+        self.defuzz = get_defuzzifier(defuzz)
+        self.rules: list[Rule] = []
+        self._outputs: dict[str, Variable] = {}
+
+    def rule(self, antecedent: Antecedent, consequent: Proposition,
+             weight: float = 1.0) -> Mamdani:
+        """Add ``IF antecedent THEN output is term`` and return ``self``."""
+        if not isinstance(consequent, Proposition):
+            raise TypeError("Mamdani consequent must be a `variable[term]` proposition")
+        self.rules.append(Rule(antecedent, consequent, weight))
+        self._outputs[consequent.variable.name] = consequent.variable
+        return self
+
+    def __call__(self, **inputs: float):
+        """Run inference. Returns a float for one output, else a dict by name."""
+        if not self.rules:
+            raise RuntimeError("no rules defined")
+        # Aggregated output membership over each output variable's universe.
+        agg = {name: np.zeros_like(var.universe)
+               for name, var in self._outputs.items()}
+
+        for r in self.rules:
+            firing = float(r.antecedent.eval(inputs, self.tnorm, self.snorm)) * r.weight
+            if firing <= 0.0:
+                continue
+            var = r.consequent.variable
+            shape = var.terms[r.consequent.term](var.universe)
+            if self.implication == "min":
+                shaped = np.minimum(firing, shape)
+            else:  # prod
+                shaped = firing * shape
+            agg[var.name] = self.aggregation(agg[var.name], shaped)
+
+        crisp = {name: self.defuzz(self._outputs[name].universe, y)
+                 for name, y in agg.items()}
+        return next(iter(crisp.values())) if len(crisp) == 1 else crisp
+
+    def __repr__(self) -> str:
+        return f"Mamdani(rules={len(self.rules)}, outputs={sorted(self._outputs)})"
+
+
+__all__ = ["Mamdani"]

fuzzytool/inference/tsk.py

@@ -0,0 +1,77 @@
+"""Takagi-Sugeno-Kang (TSK) fuzzy inference.
+
+Consequents are crisp functions of the inputs rather than fuzzy sets, so there
+is no defuzzification: the output is the firing-weighted average of the rule
+consequents. A consequent may be
+
+* a number — zero-order (Sugeno constant), e.g. ``5.0``;
+* a mapping ``{"const": b0, "x": b1, ...}`` — first-order linear in the inputs;
+* any callable ``f(**inputs) -> float`` — arbitrary.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from numbers import Real
+from typing import Callable
+
+from ..norms import get_snorm, get_tnorm
+from ..rules import Rule
+from ..sets import Antecedent
+
+
+def _as_consequent_fn(consequent) -> Callable[..., float]:
+    if isinstance(consequent, Real):
+        return lambda **_: float(consequent)
+    if isinstance(consequent, Mapping):
+        bias = float(consequent.get("const", 0.0))
+        coefs = {k: float(v) for k, v in consequent.items() if k != "const"}
+        return lambda **xs: bias + sum(c * xs[k] for k, c in coefs.items())
+    if callable(consequent):
+        return consequent
+    raise TypeError("TSK consequent must be a number, a coefficient mapping, "
+                    "or a callable")
+
+
+class TSK:
+    """A (zero- or first-order) Takagi-Sugeno inference system.
+
+    Args:
+        tnorm: t-norm for AND in antecedents (default ``"min"``).
+        snorm: s-norm for OR in antecedents (default ``"max"``).
+    """
+
+    def __init__(self, tnorm: str | Callable = "min",
+                 snorm: str | Callable = "max") -> None:
+        self.tnorm = get_tnorm(tnorm)
+        self.snorm = get_snorm(snorm)
+        self.rules: list[Rule] = []
+        self._fns: list[Callable[..., float]] = []
+
+    def rule(self, antecedent: Antecedent, consequent, weight: float = 1.0) -> TSK:
+        """Add ``IF antecedent THEN output = consequent`` and return ``self``."""
+        self.rules.append(Rule(antecedent, consequent, weight))
+        self._fns.append(_as_consequent_fn(consequent))
+        return self
+
+    def __call__(self, **inputs: float) -> float:
+        """Run inference, returning the firing-weighted average output."""
+        if not self.rules:
+            raise RuntimeError("no rules defined")
+        num = 0.0
+        den = 0.0
+        for r, fn in zip(self.rules, self._fns):
+            w = float(r.antecedent.eval(inputs, self.tnorm, self.snorm)) * r.weight
+            if w <= 0.0:
+                continue
+            num += w * fn(**inputs)
+            den += w
+        if den == 0.0:
+            raise ValueError("no rule fired for the given inputs")
+        return num / den
+
+    def __repr__(self) -> str:
+        return f"TSK(rules={len(self.rules)})"
+
+
+__all__ = ["TSK"]

fuzzytool/membership.py

@@ -0,0 +1,149 @@
+"""Membership functions.
+
+Every membership function (MF) is a *callable* mapping a crisp value (scalar or
+NumPy array) to a membership degree in ``[0, 1]``. The :class:`MembershipFunction`
+Protocol is the only contract the rest of the library relies on: the inference
+engine never inspects a concrete MF type, so a new shape = a new callable, with
+no changes to the core (mirroring the "one variant = one impl" design of the
+sibling project ``turboswarm``).
+
+The lowercase factory functions (:func:`tri`, :func:`trap`, :func:`gauss`,
+:func:`gbell`, :func:`sigmoid`) are the public API; they return small classes so
+the parameters stay introspectable for visualization and serialization.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+import numpy as np
+
+
+@runtime_checkable
+class MembershipFunction(Protocol):
+    """A callable ``x -> degree`` with membership degrees in ``[0, 1]``."""
+
+    def __call__(self, x: np.ndarray) -> np.ndarray: ...
+
+
+class Triangular:
+    """Triangular MF with feet at ``a``/``c`` and peak at ``b``."""
+
+    def __init__(self, a: float, b: float, c: float) -> None:
+        if not a <= b <= c:
+            raise ValueError(f"triangular requires a <= b <= c, got {(a, b, c)}")
+        self.a, self.b, self.c = float(a), float(b), float(c)
+
+    def __call__(self, x):
+        x = np.asarray(x, dtype=float)
+        left = np.divide(x - self.a, self.b - self.a, out=np.zeros_like(x),
+                         where=self.b != self.a)
+        right = np.divide(self.c - x, self.c - self.b, out=np.zeros_like(x),
+                          where=self.c != self.b)
+        # Degenerate edges: a flat shoulder where two points coincide.
+        left = np.where(self.b == self.a, (x >= self.a).astype(float), left)
+        right = np.where(self.c == self.b, (x <= self.c).astype(float), right)
+        return np.clip(np.minimum(left, right), 0.0, 1.0)
+
+    def __repr__(self) -> str:
+        return f"tri({self.a}, {self.b}, {self.c})"
+
+
+class Trapezoidal:
+    """Trapezoidal MF; flat top between ``b`` and ``c``."""
+
+    def __init__(self, a: float, b: float, c: float, d: float) -> None:
+        if not a <= b <= c <= d:
+            raise ValueError(f"trapezoid requires a <= b <= c <= d, got {(a, b, c, d)}")
+        self.a, self.b, self.c, self.d = map(float, (a, b, c, d))
+
+    def __call__(self, x):
+        x = np.asarray(x, dtype=float)
+        left = np.divide(x - self.a, self.b - self.a, out=np.ones_like(x),
+                         where=self.b != self.a)
+        right = np.divide(self.d - x, self.d - self.c, out=np.ones_like(x),
+                          where=self.d != self.c)
+        return np.clip(np.minimum.reduce([left, np.ones_like(x), right]), 0.0, 1.0)
+
+    def __repr__(self) -> str:
+        return f"trap({self.a}, {self.b}, {self.c}, {self.d})"
+
+
+class Gaussian:
+    """Gaussian MF centered at ``c`` with spread ``sigma``."""
+
+    def __init__(self, c: float, sigma: float) -> None:
+        if sigma <= 0:
+            raise ValueError(f"gauss requires sigma > 0, got {sigma}")
+        self.c, self.sigma = float(c), float(sigma)
+
+    def __call__(self, x):
+        x = np.asarray(x, dtype=float)
+        return np.exp(-0.5 * ((x - self.c) / self.sigma) ** 2)
+
+    def __repr__(self) -> str:
+        return f"gauss({self.c}, {self.sigma})"
+
+
+class GeneralizedBell:
+    """Generalized bell MF: ``1 / (1 + |(x - c) / a|^(2b))``."""
+
+    def __init__(self, a: float, b: float, c: float) -> None:
+        if a == 0:
+            raise ValueError("gbell requires a != 0")
+        self.a, self.b, self.c = float(a), float(b), float(c)
+
+    def __call__(self, x):
+        x = np.asarray(x, dtype=float)
+        return 1.0 / (1.0 + np.abs((x - self.c) / self.a) ** (2.0 * self.b))
+
+    def __repr__(self) -> str:
+        return f"gbell({self.a}, {self.b}, {self.c})"
+
+
+class Sigmoid:
+    """Sigmoidal MF: ``1 / (1 + exp(-a (x - c)))``."""
+
+    def __init__(self, a: float, c: float) -> None:
+        self.a, self.c = float(a), float(c)
+
+    def __call__(self, x):
+        x = np.asarray(x, dtype=float)
+        return 1.0 / (1.0 + np.exp(-self.a * (x - self.c)))
+
+    def __repr__(self) -> str:
+        return f"sigmoid({self.a}, {self.c})"
+
+
+# --- factory shortcuts (public API) ---------------------------------------
+
+def tri(a: float, b: float, c: float) -> Triangular:
+    """Triangular MF: feet at ``a``/``c``, peak at ``b``."""
+    return Triangular(a, b, c)
+
+
+def trap(a: float, b: float, c: float, d: float) -> Trapezoidal:
+    """Trapezoidal MF: shoulders ``a``/``d``, flat top ``b``..``c``."""
+    return Trapezoidal(a, b, c, d)
+
+
+def gauss(c: float, sigma: float) -> Gaussian:
+    """Gaussian MF: center ``c``, spread ``sigma``."""
+    return Gaussian(c, sigma)
+
+
+def gbell(a: float, b: float, c: float) -> GeneralizedBell:
+    """Generalized bell MF: width ``a``, slope ``b``, center ``c``."""
+    return GeneralizedBell(a, b, c)
+
+
+def sigmoid(a: float, c: float) -> Sigmoid:
+    """Sigmoidal MF: slope ``a``, inflection ``c``."""
+    return Sigmoid(a, c)
+
+
+__all__ = [
+    "MembershipFunction",
+    "Triangular", "Trapezoidal", "Gaussian", "GeneralizedBell", "Sigmoid",
+    "tri", "trap", "gauss", "gbell", "sigmoid",
+]

fuzzytool/norms.py

@@ -0,0 +1,105 @@
+"""Fuzzy connectives: t-norms (AND) and s-norms / t-conorms (OR).
+
+Connectives are plain vectorized callables ``(a, b) -> result`` operating
+elementwise on membership degrees. They are pluggable: the inference engines
+look them up by name through :func:`get_tnorm` / :func:`get_snorm`, so adding a
+connective means registering one function — the engine never changes.
+"""
+
+from __future__ import annotations
+
+from typing import Callable, Protocol, runtime_checkable
+
+import numpy as np
+
+Degree = np.ndarray
+
+
+@runtime_checkable
+class Norm(Protocol):
+    """A binary connective on membership degrees."""
+
+    def __call__(self, a: Degree, b: Degree) -> Degree: ...
+
+
+# --- t-norms (fuzzy AND) ---------------------------------------------------
+
+def t_min(a, b):
+    """Minimum (Gödel) t-norm."""
+    return np.minimum(a, b)
+
+
+def t_prod(a, b):
+    """Product (algebraic) t-norm."""
+    return np.asarray(a) * np.asarray(b)
+
+
+def t_lukasiewicz(a, b):
+    """Łukasiewicz t-norm: ``max(0, a + b - 1)``."""
+    return np.maximum(0.0, np.asarray(a) + np.asarray(b) - 1.0)
+
+
+# --- s-norms / t-conorms (fuzzy OR) ---------------------------------------
+
+def s_max(a, b):
+    """Maximum (Gödel) s-norm."""
+    return np.maximum(a, b)
+
+
+def s_probor(a, b):
+    """Probabilistic OR (algebraic sum): ``a + b - a*b``."""
+    a, b = np.asarray(a), np.asarray(b)
+    return a + b - a * b
+
+
+def s_lukasiewicz(a, b):
+    """Łukasiewicz s-norm: ``min(1, a + b)``."""
+    return np.minimum(1.0, np.asarray(a) + np.asarray(b))
+
+
+_TNORMS: dict[str, Callable] = {
+    "min": t_min,
+    "prod": t_prod,
+    "product": t_prod,
+    "lukasiewicz": t_lukasiewicz,
+}
+
+_SNORMS: dict[str, Callable] = {
+    "max": s_max,
+    "probor": s_probor,
+    "sum": s_probor,
+    "lukasiewicz": s_lukasiewicz,
+}
+
+
+def get_tnorm(name: str | Callable) -> Callable:
+    """Resolve a t-norm by name (or pass a callable through unchanged)."""
+    if callable(name):
+        return name
+    try:
+        return _TNORMS[name]
+    except KeyError:
+        raise ValueError(f"unknown t-norm {name!r}; options: {sorted(_TNORMS)}") from None
+
+
+def get_snorm(name: str | Callable) -> Callable:
+    """Resolve an s-norm by name (or pass a callable through unchanged)."""
+    if callable(name):
+        return name
+    try:
+        return _SNORMS[name]
+    except KeyError:
+        raise ValueError(f"unknown s-norm {name!r}; options: {sorted(_SNORMS)}") from None
+
+
+def complement(a):
+    """Standard fuzzy complement (NOT): ``1 - a``."""
+    return 1.0 - np.asarray(a)
+
+
+__all__ = [
+    "Norm",
+    "t_min", "t_prod", "t_lukasiewicz",
+    "s_max", "s_probor", "s_lukasiewicz",
+    "get_tnorm", "get_snorm", "complement",
+]

fuzzytool/rules.py

@@ -0,0 +1,34 @@
+"""Fuzzy rules shared by the inference engines.
+
+A :class:`Rule` pairs an antecedent expression with a consequent and an optional
+weight. The *consequent* is interpreted by the engine: Mamdani expects a
+:class:`~fuzzytool.sets.Proposition` (``output is term``); TSK expects a
+constant or a linear coefficient vector.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from .sets import Antecedent
+
+
+@dataclass
+class Rule:
+    """``IF antecedent THEN consequent`` with an optional firing ``weight``."""
+
+    antecedent: Antecedent
+    consequent: Any
+    weight: float = 1.0
+
+    def __post_init__(self) -> None:
+        if not 0.0 <= self.weight <= 1.0:
+            raise ValueError(f"rule weight must be in [0, 1], got {self.weight}")
+
+    def __repr__(self) -> str:
+        w = "" if self.weight == 1.0 else f" (w={self.weight})"
+        return f"IF {self.antecedent} THEN {self.consequent}{w}"
+
+
+__all__ = ["Rule"]