fuzzytool 0.1.0__py3-none-any.whl

fuzzytool/sets.py

@@ -0,0 +1,210 @@
+"""Fuzzy sets, linguistic variables, and the rule-antecedent expression tree.
+
+A :class:`Variable` is a linguistic variable: a named universe of discourse plus
+a dictionary of *terms* (named membership functions). Indexing a variable with a
+term name (``score["good"]``) returns a :class:`Proposition`, the atom of a
+rule antecedent. Propositions compose with Python operators:
+
+    score["poor"] | dti["high"]         # OR  (s-norm)
+    score["good"] & dti["low"]          # AND (t-norm)
+    ~dti["high"]                        # NOT (complement)
+
+The result is a small expression tree that the inference engine evaluates
+against crisp inputs to get a firing strength. The same atom doubles as a rule
+*consequent* (``premium["high"]``), so there is a single concept to learn.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+
+import numpy as np
+
+from . import membership as mf
+from .norms import complement
+
+_KINDS = {"triangular": "tri", "tri": "tri", "gauss": "gauss", "gaussian": "gauss"}
+
+
+def _is_it2(term) -> bool:
+    """An IT2 term exposes ``.lower`` and ``.upper`` (duck-typed to avoid an import)."""
+    return hasattr(term, "lower") and hasattr(term, "upper")
+
+
+class Antecedent:
+    """Base node of a rule-antecedent expression tree."""
+
+    def __and__(self, other: Antecedent) -> And:
+        return And(self, other)
+
+    def __or__(self, other: Antecedent) -> Or:
+        return Or(self, other)
+
+    def __invert__(self) -> Not:
+        return Not(self)
+
+    def eval(self, inputs: Mapping[str, float], tnorm, snorm) -> np.ndarray:
+        """Return the (type-1) firing strength given crisp ``inputs``."""
+        raise NotImplementedError
+
+    def eval_interval(self, inputs: Mapping[str, float], tnorm, snorm):
+        """Return the firing *interval* ``(lower, upper)`` for IT2 inference.
+
+        Type-1 terms collapse to a degenerate interval ``(d, d)``, so type-1 and
+        IT2 terms may be mixed freely in the same antecedent.
+        """
+        raise NotImplementedError
+
+
+class Proposition(Antecedent):
+    """An atomic ``variable is term`` clause; also used as a consequent."""
+
+    def __init__(self, variable: Variable, term: str) -> None:
+        if term not in variable.terms:
+            raise KeyError(
+                f"variable {variable.name!r} has no term {term!r}; "
+                f"known terms: {sorted(variable.terms)}"
+            )
+        self.variable = variable
+        self.term = term
+
+    def eval(self, inputs, tnorm, snorm) -> np.ndarray:
+        try:
+            x = inputs[self.variable.name]
+        except KeyError:
+            raise KeyError(f"missing input for variable {self.variable.name!r}") from None
+        term = self.variable.terms[self.term]
+        if _is_it2(term):  # collapse an IT2 term to its mean membership
+            lo, hi = term.lower(x), term.upper(x)
+            return np.asarray((lo + hi) / 2.0, dtype=float)
+        return np.asarray(term(x), dtype=float)
+
+    def eval_interval(self, inputs, tnorm, snorm):
+        try:
+            x = inputs[self.variable.name]
+        except KeyError:
+            raise KeyError(f"missing input for variable {self.variable.name!r}") from None
+        term = self.variable.terms[self.term]
+        if _is_it2(term):
+            return float(term.lower(x)), float(term.upper(x))
+        d = float(np.asarray(term(x), dtype=float))
+        return d, d
+
+    def __repr__(self) -> str:
+        return f"{self.variable.name} is {self.term}"
+
+
+class And(Antecedent):
+    def __init__(self, left: Antecedent, right: Antecedent) -> None:
+        self.left, self.right = left, right
+
+    def eval(self, inputs, tnorm, snorm):
+        return tnorm(self.left.eval(inputs, tnorm, snorm),
+                     self.right.eval(inputs, tnorm, snorm))
+
+    def eval_interval(self, inputs, tnorm, snorm):
+        ll, lu = self.left.eval_interval(inputs, tnorm, snorm)
+        rl, ru = self.right.eval_interval(inputs, tnorm, snorm)
+        return tnorm(ll, rl), tnorm(lu, ru)
+
+    def __repr__(self) -> str:
+        return f"({self.left} and {self.right})"
+
+
+class Or(Antecedent):
+    def __init__(self, left: Antecedent, right: Antecedent) -> None:
+        self.left, self.right = left, right
+
+    def eval(self, inputs, tnorm, snorm):
+        return snorm(self.left.eval(inputs, tnorm, snorm),
+                     self.right.eval(inputs, tnorm, snorm))
+
+    def eval_interval(self, inputs, tnorm, snorm):
+        ll, lu = self.left.eval_interval(inputs, tnorm, snorm)
+        rl, ru = self.right.eval_interval(inputs, tnorm, snorm)
+        return snorm(ll, rl), snorm(lu, ru)
+
+    def __repr__(self) -> str:
+        return f"({self.left} or {self.right})"
+
+
+class Not(Antecedent):
+    def __init__(self, operand: Antecedent) -> None:
+        self.operand = operand
+
+    def eval(self, inputs, tnorm, snorm):
+        return complement(self.operand.eval(inputs, tnorm, snorm))
+
+    def eval_interval(self, inputs, tnorm, snorm):
+        # The complement is order-reversing, so the bounds swap.
+        lo, hi = self.operand.eval_interval(inputs, tnorm, snorm)
+        return complement(hi), complement(lo)
+
+    def __repr__(self) -> str:
+        return f"(not {self.operand})"
+
+
+class Variable:
+    """A linguistic variable: a named universe with named fuzzy-set terms.
+
+    Args:
+        name: identifier; rule inputs are matched to variables by this name.
+        universe: ``(low, high)`` range of the universe of discourse.
+        terms: optional list of term names to auto-generate evenly across the
+            universe, or a mapping ``{name: MembershipFunction}``.
+        kind: shape used by auto-generation (``"triangular"`` or ``"gauss"``).
+        resolution: number of samples used to discretize the universe for
+            Mamdani defuzzification.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        universe: tuple[float, float],
+        terms: Iterable[str] | Mapping[str, mf.MembershipFunction] | None = None,
+        kind: str = "triangular",
+        resolution: int = 501,
+    ) -> None:
+        self.name = name
+        self.low, self.high = float(universe[0]), float(universe[1])
+        if self.high <= self.low:
+            raise ValueError(f"universe must have low < high, got {universe}")
+        self.terms: dict[str, mf.MembershipFunction] = {}
+        self.universe = np.linspace(self.low, self.high, resolution)
+        if isinstance(terms, Mapping):
+            for n, m in terms.items():
+                self[n] = m
+        elif terms is not None:
+            self.auto_terms(list(terms), kind=kind)
+
+    def __getitem__(self, term: str) -> Proposition:
+        return Proposition(self, term)
+
+    def __setitem__(self, term: str, membership: mf.MembershipFunction) -> None:
+        if not callable(membership):
+            raise TypeError("a term must be a callable membership function")
+        self.terms[term] = membership
+
+    def auto_terms(self, names: list[str], kind: str = "triangular") -> Variable:
+        """Generate evenly-spaced terms named ``names`` across the universe."""
+        kind = _KINDS.get(kind)
+        if kind is None:
+            raise ValueError("kind must be 'triangular' or 'gauss'")
+        n = len(names)
+        if n < 2:
+            raise ValueError("need at least two terms")
+        centers = np.linspace(self.low, self.high, n)
+        step = (self.high - self.low) / (n - 1)
+        for name, c in zip(names, centers):
+            if kind == "tri":
+                self[name] = mf.tri(c - step, c, c + step)
+            else:  # gauss
+                self[name] = mf.gauss(c, step / 2.0)
+        return self
+
+    def __repr__(self) -> str:
+        return (f"Variable({self.name!r}, ({self.low}, {self.high}), "
+                f"terms={sorted(self.terms)})")
+
+
+__all__ = ["Variable", "Proposition", "Antecedent", "And", "Or", "Not"]

fuzzytool/type2/__init__.py

@@ -0,0 +1,27 @@
+"""Interval type-2 (IT2) fuzzy sets, inference, and type reduction.
+
+An IT2 set is bounded by two type-1 membership functions — an upper (UMF) and a
+lower (LMF) — whose gap is the *footprint of uncertainty* (FOU). Membership at a
+point is therefore an interval ``[LMF(x), UMF(x)]`` rather than a single number.
+
+IT2 rules reuse the very same operator syntax as type-1 rules (``|``, ``&``,
+``~``); the engines here propagate membership *intervals* through the antecedent
+tree and collapse the result with Karnik-Mendel type reduction.
+"""
+
+from .inference import IT2TSK, IT2Mamdani
+from .reduction import centroid_it2, karnik_mendel, km_endpoint
+from .sets import (
+    IntervalType2MF,
+    it2,
+    it2_gauss_uncertain_mean,
+    it2_gauss_uncertain_std,
+    it2_scale,
+)
+
+__all__ = [
+    "IntervalType2MF",
+    "it2", "it2_scale", "it2_gauss_uncertain_mean", "it2_gauss_uncertain_std",
+    "IT2Mamdani", "IT2TSK",
+    "karnik_mendel", "km_endpoint", "centroid_it2",
+]

fuzzytool/type2/inference.py

@@ -0,0 +1,122 @@
+"""Interval type-2 inference engines.
+
+Both engines evaluate each rule's antecedent to a firing *interval*
+``[f_low, f_high]`` (via :meth:`Antecedent.eval_interval`) and then collapse the
+rule base with Karnik-Mendel type reduction, returning the midpoint of the
+type-reduced interval ``[y_l, y_r]``.
+
+* :class:`IT2Mamdani` uses **center-of-sets** type reduction: each consequent
+  IT2 set is summarized by its centroid interval (computed once and cached), and
+  KM combines those centroids weighted by the firing intervals.
+* :class:`IT2TSK` has crisp consequents (numbers, coefficient mappings, or
+  callables) and applies KM directly to them.
+"""
+
+from __future__ import annotations
+
+from typing import Callable
+
+import numpy as np
+
+from ..inference.tsk import _as_consequent_fn
+from ..norms import get_snorm, get_tnorm
+from ..rules import Rule
+from ..sets import Antecedent, Proposition, Variable
+from .reduction import centroid_it2, karnik_mendel, km_endpoint
+
+
+class IT2Mamdani:
+    """Interval type-2 Mamdani inference (center-of-sets type reduction).
+
+    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._outputs: dict[str, Variable] = {}
+        self._centroids: dict[tuple[int, str], tuple[float, float]] = {}
+
+    def rule(self, antecedent: Antecedent, consequent: Proposition,
+             weight: float = 1.0) -> IT2Mamdani:
+        """Add ``IF antecedent THEN output is term`` and return ``self``."""
+        if not isinstance(consequent, Proposition):
+            raise TypeError("IT2Mamdani consequent must be a `variable[term]` proposition")
+        self.rules.append(Rule(antecedent, consequent, weight))
+        self._outputs[consequent.variable.name] = consequent.variable
+        return self
+
+    def _centroid(self, var: Variable, term: str) -> tuple[float, float]:
+        key = (id(var), term)
+        if key not in self._centroids:
+            self._centroids[key] = centroid_it2(var.terms[term], var.universe)
+        return self._centroids[key]
+
+    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")
+        out: dict[str, float] = {}
+        for name, var in self._outputs.items():
+            cl, cr, f_low, f_high = [], [], [], []
+            for r in self.rules:
+                if r.consequent.variable.name != name:
+                    continue
+                lo, hi = r.antecedent.eval_interval(inputs, self.tnorm, self.snorm)
+                c_l, c_r = self._centroid(var, r.consequent.term)
+                cl.append(c_l)
+                cr.append(c_r)
+                f_low.append(float(lo) * r.weight)
+                f_high.append(float(hi) * r.weight)
+            y_l = km_endpoint(np.array(cl), np.array(f_low), np.array(f_high), side="l")
+            y_r = km_endpoint(np.array(cr), np.array(f_low), np.array(f_high), side="r")
+            out[name] = (y_l + y_r) / 2.0
+        return next(iter(out.values())) if len(out) == 1 else out
+
+    def __repr__(self) -> str:
+        return f"IT2Mamdani(rules={len(self.rules)}, outputs={sorted(self._outputs)})"
+
+
+class IT2TSK:
+    """Interval type-2 Takagi-Sugeno inference (KM over crisp consequents).
+
+    Consequents follow the same convention as the type-1 :class:`~fuzzytool.inference.tsk.TSK`
+    engine: a number, a coefficient mapping ``{"const": b0, "x": b1, ...}``, or a
+    callable ``f(**inputs) -> float``.
+    """
+
+    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) -> IT2TSK:
+        """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 midpoint of the type-reduced interval."""
+        if not self.rules:
+            raise RuntimeError("no rules defined")
+        pts, f_low, f_high = [], [], []
+        for r, fn in zip(self.rules, self._fns):
+            lo, hi = r.antecedent.eval_interval(inputs, self.tnorm, self.snorm)
+            pts.append(fn(**inputs))
+            f_low.append(float(lo) * r.weight)
+            f_high.append(float(hi) * r.weight)
+        y_l, y_r = karnik_mendel(pts, f_low, f_high)
+        return (y_l + y_r) / 2.0
+
+    def __repr__(self) -> str:
+        return f"IT2TSK(rules={len(self.rules)})"
+
+
+__all__ = ["IT2Mamdani", "IT2TSK"]

fuzzytool/type2/reduction.py

@@ -0,0 +1,83 @@
+"""Karnik-Mendel type reduction.
+
+Type reduction turns the interval-valued output of an IT2 system into a crisp
+interval ``[y_l, y_r]`` (typically defuzzified as its midpoint). The
+Karnik-Mendel (KM) algorithm finds each endpoint by locating the *switch point*
+where the per-point weight flips between its lower and upper bound.
+
+The single primitive :func:`km_endpoint` is reused everywhere: for an IT2 set's
+centroid (points = universe samples, weights = the FOU) and for an IT2 rule base
+(points = consequent centroids, weights = rule firing intervals).
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+
+def _weighted_mean(points: np.ndarray, w: np.ndarray) -> float:
+    total = w.sum()
+    if total == 0:
+        return float(points.mean())  # nothing fired: neutral fallback
+    return float((w * points).sum() / total)
+
+
+def km_endpoint(points: np.ndarray, lower: np.ndarray, upper: np.ndarray,
+                side: str = "l", max_iter: int = 100) -> float:
+    """One endpoint of the type-reduced interval via Karnik-Mendel.
+
+    Args:
+        points: the y-values (e.g. consequent centroids or universe samples).
+        lower: per-point weight lower bounds (same shape as ``points``).
+        upper: per-point weight upper bounds (same shape as ``points``).
+        side: ``"l"`` for the left endpoint ``y_l``, ``"r"`` for the right ``y_r``.
+        max_iter: safeguard on the Karnik-Mendel iteration count.
+
+    Left endpoint uses the *upper* weights to the left of the switch and the
+    *lower* weights to its right; the right endpoint mirrors this.
+    """
+    points = np.asarray(points, dtype=float)
+    lower = np.asarray(lower, dtype=float)
+    upper = np.asarray(upper, dtype=float)
+    if points.size == 0:
+        raise ValueError("no points to type-reduce")
+    if side not in ("l", "r"):
+        raise ValueError("side must be 'l' or 'r'")
+
+    order = np.argsort(points)
+    p, lo, up = points[order], lower[order], upper[order]
+    n = p.size
+    if n == 1:
+        return float(p[0])
+
+    idx = np.arange(n)
+    w = (lo + up) / 2.0
+    y = _weighted_mean(p, w)
+    for _ in range(max_iter):
+        k = int(np.searchsorted(p, y, side="right")) - 1
+        k = min(max(k, 0), n - 2)
+        if side == "l":
+            w = np.where(idx <= k, up, lo)
+        else:
+            w = np.where(idx <= k, lo, up)
+        y_new = _weighted_mean(p, w)
+        if np.isclose(y_new, y):
+            return y_new
+        y = y_new
+    return y
+
+
+def karnik_mendel(points, lower, upper) -> tuple[float, float]:
+    """Type-reduce to the interval ``(y_l, y_r)`` over a shared set of points."""
+    y_l = km_endpoint(points, lower, upper, side="l")
+    y_r = km_endpoint(points, lower, upper, side="r")
+    return y_l, y_r
+
+
+def centroid_it2(it2mf, universe) -> tuple[float, float]:
+    """Centroid interval ``(c_l, c_r)`` of an IT2 set over ``universe``."""
+    x = np.asarray(universe, dtype=float)
+    return karnik_mendel(x, it2mf.lower(x), it2mf.upper(x))
+
+
+__all__ = ["km_endpoint", "karnik_mendel", "centroid_it2"]

fuzzytool/type2/sets.py

@@ -0,0 +1,96 @@
+"""Interval type-2 (IT2) membership functions.
+
+An :class:`IntervalType2MF` carries a lower (LMF) and an upper (UMF) type-1
+membership function. Calling it returns the membership *interval*
+``(lower, upper)``; the engines also call ``.lower(x)`` / ``.upper(x)`` directly.
+
+The constructors cover the standard ways of building an FOU from a type-1 set:
+
+* :func:`it2` — explicit LMF/UMF;
+* :func:`it2_scale` — height uncertainty (LMF is a scaled-down UMF);
+* :func:`it2_gauss_uncertain_mean` — a Gaussian with mean in ``[c1, c2]``;
+* :func:`it2_gauss_uncertain_std` — a Gaussian with uncertain spread.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from ..membership import Gaussian, MembershipFunction
+
+
+class IntervalType2MF:
+    """An IT2 set defined by a lower (LMF) and an upper (UMF) type-1 MF.
+
+    The UMF must dominate the LMF everywhere (``LMF(x) <= UMF(x)``); this is not
+    enforced at construction (it would require sampling the universe) but holds
+    for every set built through the constructors below.
+    """
+
+    def __init__(self, lower: MembershipFunction, upper: MembershipFunction) -> None:
+        if not callable(lower) or not callable(upper):
+            raise TypeError("lower and upper must be callable membership functions")
+        self._lower = lower
+        self._upper = upper
+
+    def lower(self, x):
+        return np.asarray(self._lower(x), dtype=float)
+
+    def upper(self, x):
+        return np.asarray(self._upper(x), dtype=float)
+
+    def __call__(self, x):
+        return self.lower(x), self.upper(x)
+
+    def __repr__(self) -> str:
+        return f"IT2(lower={self._lower!r}, upper={self._upper!r})"
+
+
+def it2(lower: MembershipFunction, upper: MembershipFunction) -> IntervalType2MF:
+    """An IT2 set from explicit lower and upper type-1 membership functions."""
+    return IntervalType2MF(lower, upper)
+
+
+def it2_scale(mf: MembershipFunction, scale: float) -> IntervalType2MF:
+    """Height-uncertainty FOU: UMF is ``mf``, LMF is ``scale * mf`` (0 < scale ≤ 1)."""
+    if not 0.0 < scale <= 1.0:
+        raise ValueError(f"scale must be in (0, 1], got {scale}")
+    lower = lambda x: scale * np.asarray(mf(x), dtype=float)  # noqa: E731
+    return IntervalType2MF(lower, mf)
+
+
+def it2_gauss_uncertain_mean(c1: float, c2: float, sigma: float) -> IntervalType2MF:
+    """Gaussian with an *uncertain mean* spanning ``[c1, c2]`` (c1 < c2).
+
+    The UMF is the upper envelope of all Gaussians with mean in ``[c1, c2]``
+    (flat-topped at 1 between the means); the LMF is their lower envelope.
+    """
+    if c1 >= c2:
+        raise ValueError(f"need c1 < c2, got ({c1}, {c2})")
+    if sigma <= 0:
+        raise ValueError("sigma must be > 0")
+    g1, g2 = Gaussian(c1, sigma), Gaussian(c2, sigma)
+    mid = (c1 + c2) / 2.0
+
+    def upper(x):
+        x = np.asarray(x, dtype=float)
+        return np.where(x < c1, g1(x), np.where(x > c2, g2(x), 1.0))
+
+    def lower(x):
+        x = np.asarray(x, dtype=float)
+        return np.where(x <= mid, g2(x), g1(x))
+
+    return IntervalType2MF(lower, upper)
+
+
+def it2_gauss_uncertain_std(c: float, sigma_lo: float, sigma_hi: float) -> IntervalType2MF:
+    """Gaussian with an *uncertain spread*: UMF uses the wider σ, LMF the narrower."""
+    if not 0 < sigma_lo < sigma_hi:
+        raise ValueError(f"need 0 < sigma_lo < sigma_hi, got ({sigma_lo}, {sigma_hi})")
+    return IntervalType2MF(Gaussian(c, sigma_lo), Gaussian(c, sigma_hi))
+
+
+__all__ = [
+    "IntervalType2MF",
+    "it2", "it2_scale", "it2_gauss_uncertain_mean", "it2_gauss_uncertain_std",
+]

fuzzytool/viz.py

@@ -0,0 +1,118 @@
+"""Matplotlib visualization helpers.
+
+Importing this module requires ``matplotlib`` (an optional dependency; install
+with ``pip install fuzzytool[viz]``). Visualization is a first-class priority of
+the project, mirroring its sibling ``turboswarm``.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+if TYPE_CHECKING:  # pragma: no cover
+    from .sets import Variable
+
+
+def _require_mpl():
+    try:
+        import matplotlib.pyplot as plt  # noqa: F401
+    except ImportError as exc:  # pragma: no cover
+        raise ImportError(
+            "visualization needs matplotlib; install with `pip install fuzzytool[viz]`"
+        ) from exc
+    return plt
+
+
+def plot_variable(variable: Variable, ax=None):
+    """Plot every term's membership function over the variable's universe."""
+    plt = _require_mpl()
+    if ax is None:
+        _, ax = plt.subplots(figsize=(6, 3))
+    x = variable.universe
+    for name, m in variable.terms.items():
+        ax.plot(x, m(x), label=name)
+    ax.set_title(variable.name)
+    ax.set_xlabel(variable.name)
+    ax.set_ylabel("membership")
+    ax.set_ylim(-0.05, 1.05)
+    ax.legend(loc="best", fontsize="small")
+    return ax
+
+
+def plot_it2_variable(variable: Variable, ax=None):
+    """Plot an IT2 variable: each term's lower/upper MF with a shaded FOU.
+
+    Type-1 terms (if any are mixed in) are drawn as a single line.
+    """
+    plt = _require_mpl()
+    if ax is None:
+        _, ax = plt.subplots(figsize=(6, 3))
+    x = variable.universe
+    for name, term in variable.terms.items():
+        if hasattr(term, "lower") and hasattr(term, "upper"):
+            lo, up = term.lower(x), term.upper(x)
+            line, = ax.plot(x, up, label=name)
+            ax.plot(x, lo, color=line.get_color(), alpha=0.7)
+            ax.fill_between(x, lo, up, color=line.get_color(), alpha=0.2)
+        else:
+            ax.plot(x, term(x), label=name)
+    ax.set_title(variable.name)
+    ax.set_xlabel(variable.name)
+    ax.set_ylabel("membership")
+    ax.set_ylim(-0.05, 1.05)
+    ax.legend(loc="best", fontsize="small")
+    return ax
+
+
+def control_surface(system, x_var: Variable, y_var: Variable,
+                    n: int = 41, ax=None):
+    """Plot a system's output as a surface over two input variables.
+
+    ``system`` must be callable as ``system(**{x_var.name: x, y_var.name: y})``
+    and return a scalar (single-output Mamdani or TSK).
+    """
+    plt = _require_mpl()
+    from mpl_toolkits.mplot3d import Axes3D  # noqa: F401  (registers 3d proj)
+
+    xs = np.linspace(x_var.low, x_var.high, n)
+    ys = np.linspace(y_var.low, y_var.high, n)
+    zz = np.empty((n, n))
+    for i, yv in enumerate(ys):
+        for j, xv in enumerate(xs):
+            zz[i, j] = system(**{x_var.name: float(xv), y_var.name: float(yv)})
+    xx, yy = np.meshgrid(xs, ys)
+
+    if ax is None:
+        fig = plt.figure(figsize=(7, 5))
+        ax = fig.add_subplot(111, projection="3d")
+    ax.plot_surface(xx, yy, zz, cmap="viridis", linewidth=0, antialiased=True)
+    ax.set_xlabel(x_var.name)
+    ax.set_ylabel(y_var.name)
+    ax.set_zlabel("output")
+    return ax
+
+
+def plot_clusters(X, result, ax=None):
+    """Scatter 2-D data colored by hard label, with cluster centers marked.
+
+    ``result`` is a :class:`~fuzzytool.cluster.ClusterResult`. Point opacity
+    encodes the top membership, so fuzzy/boundary points appear fainter.
+    """
+    plt = _require_mpl()
+    X = np.asarray(X, dtype=float)
+    if X.shape[1] != 2:
+        raise ValueError("plot_clusters needs 2-D data")
+    if ax is None:
+        _, ax = plt.subplots(figsize=(5, 5))
+    top = result.u.max(axis=0)
+    ax.scatter(X[:, 0], X[:, 1], c=result.labels, cmap="tab10",
+               alpha=np.clip(top, 0.25, 1.0), s=25)
+    ax.scatter(result.centers[:, 0], result.centers[:, 1],
+               marker="X", c="black", s=160, edgecolors="white", zorder=3)
+    ax.set_title("fuzzy clusters")
+    return ax
+
+
+__all__ = ["plot_variable", "plot_it2_variable", "control_surface", "plot_clusters"]