fuzzytool 0.1.0__py3-none-any.whl

fuzzytool/__init__.py

@@ -0,0 +1,55 @@
+"""fuzzytool — a clean, extensible fuzzy-logic toolkit in pure Python + NumPy.
+
+Quick start (a credit-risk premium system):
+
+    >>> import fuzzytool as fz
+    >>> score = fz.Variable("score", (300, 850), terms=["poor", "fair", "good", "excellent"])
+    >>> dti = fz.Variable("dti", (0, 50), terms=["low", "moderate", "high"])
+    >>> premium = fz.Variable("premium", (0, 12), terms=["low", "medium", "high"])
+    >>> sys = fz.Mamdani()
+    >>> _ = sys.rule(score["poor"] | dti["high"], premium["high"])
+    >>> _ = sys.rule(score["fair"] & dti["moderate"], premium["medium"])
+    >>> _ = sys.rule(score["good"] | score["excellent"], premium["low"])
+    >>> sys(score=800, dti=10) < sys(score=520, dti=42)
+    True
+
+Everything is pluggable behind small Protocols (membership functions,
+t-/s-norms, defuzzifiers): a new variant is a new callable, never a change to
+the inference loop.
+"""
+
+from . import cluster, datasets, defuzz, membership, norms, type2
+from .anfis import ANFIS
+from .cluster import fuzzy_cmeans, gustafson_kessel, possibilistic_cmeans
+from .ftransform import FTransform
+from .inference import TSK, Mamdani
+from .membership import gauss, gbell, sigmoid, trap, tri
+from .sets import Variable
+from .type2 import (
+    IT2TSK,
+    IT2Mamdani,
+    it2,
+    it2_gauss_uncertain_mean,
+    it2_gauss_uncertain_std,
+    it2_scale,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    "Variable",
+    "Mamdani",
+    "TSK",
+    # membership shortcuts
+    "tri", "trap", "gauss", "gbell", "sigmoid",
+    # interval type-2
+    "IT2Mamdani", "IT2TSK",
+    "it2", "it2_scale", "it2_gauss_uncertain_mean", "it2_gauss_uncertain_std",
+    # fuzzy clustering
+    "fuzzy_cmeans", "gustafson_kessel", "possibilistic_cmeans",
+    # learning & approximation
+    "ANFIS", "FTransform",
+    # submodules
+    "membership", "norms", "defuzz", "datasets", "type2", "cluster",
+]

fuzzytool/anfis.py

@@ -0,0 +1,141 @@
+"""ANFIS — an adaptive network-based fuzzy inference system (Jang, 1993).
+
+ANFIS is a first-order Takagi-Sugeno system whose parameters are learned from
+data. With a grid partition, each of the ``p`` inputs carries ``n_mf`` Gaussian
+membership functions, giving ``n_mf ** p`` rules; rule ``i`` fires with the
+product of its inputs' memberships and emits an affine function of the inputs.
+
+Training uses Jang's **hybrid** scheme, one pass per epoch:
+
+1. with the premise (Gaussian) parameters fixed, the consequent (affine)
+   parameters are solved in closed form by least squares — the output is linear
+   in them;
+2. with the consequents fixed, the premise centers and widths take a
+   gradient-descent step on the mean squared error.
+
+Pure NumPy; intended for low-dimensional problems (the rule count grows as
+``n_mf ** p``).
+"""
+
+from __future__ import annotations
+
+import itertools
+
+import numpy as np
+
+_EPS = 1e-12
+
+
+class ANFIS:
+    """A trainable first-order Sugeno system over a grid partition.
+
+    Args:
+        n_inputs: number of input features ``p``.
+        n_mf: Gaussian membership functions per input (rules = ``n_mf ** p``).
+        learning_rate: step size for the premise gradient updates.
+    """
+
+    def __init__(self, n_inputs: int, n_mf: int = 3,
+                 learning_rate: float = 0.05) -> None:
+        if n_inputs < 1 or n_mf < 2:
+            raise ValueError("need n_inputs >= 1 and n_mf >= 2")
+        self.p = int(n_inputs)
+        self.n_mf = int(n_mf)
+        self.lr = float(learning_rate)
+        # Rule -> per-input MF index, shape (R, p); R = n_mf ** p.
+        self.rule_mf = np.array(list(itertools.product(range(n_mf), repeat=n_inputs)))
+        self.R = self.rule_mf.shape[0]
+        self.centers_: np.ndarray | None = None     # (p, n_mf)
+        self.sigmas_: np.ndarray | None = None       # (p, n_mf)
+        self.coeffs_: np.ndarray | None = None        # (R, p + 1)
+        self.history_: list[float] = []               # RMSE per epoch
+
+    # --- internals --------------------------------------------------------
+
+    def _init_premise(self, X: np.ndarray) -> None:
+        lo, hi = X.min(axis=0), X.max(axis=0)
+        span = np.where(hi > lo, hi - lo, 1.0)
+        self.centers_ = np.linspace(lo, hi, self.n_mf).T              # (p, n_mf)
+        self.sigmas_ = np.tile((span / (self.n_mf - 1))[:, None], (1, self.n_mf))
+
+    def _firing(self, X: np.ndarray):
+        """Return ``(mu, mu_sel, w, wn, W)`` for a batch ``X`` (n, p)."""
+        c, s = self.centers_, self.sigmas_
+        mu = np.exp(-0.5 * ((X[:, :, None] - c[None]) / s[None]) ** 2)  # (n, p, M)
+        j = np.broadcast_to(np.arange(self.p), (self.R, self.p))
+        mu_sel = mu[:, j, self.rule_mf]                                 # (n, R, p)
+        w = mu_sel.prod(axis=2)                                         # (n, R)
+        W = w.sum(axis=1, keepdims=True) + _EPS
+        return mu, mu_sel, w, w / W, W
+
+    def _lse_consequents(self, X: np.ndarray, y: np.ndarray, wn: np.ndarray) -> None:
+        n = X.shape[0]
+        xc = np.hstack([X, np.ones((n, 1))])                           # (n, p+1)
+        phi = (wn[:, :, None] * xc[:, None, :]).reshape(n, self.R * (self.p + 1))
+        theta, *_ = np.linalg.lstsq(phi, y, rcond=None)
+        self.coeffs_ = theta.reshape(self.R, self.p + 1)
+
+    def _outputs(self, X: np.ndarray, wn: np.ndarray):
+        xc = np.hstack([X, np.ones((X.shape[0], 1))])
+        f = xc @ self.coeffs_.T                                         # (n, R)
+        return f, (wn * f).sum(axis=1)                                  # (n, R), (n,)
+
+    # --- public API -------------------------------------------------------
+
+    def fit(self, X, y, epochs: int = 100) -> ANFIS:
+        """Train on ``X`` (n, p) and targets ``y`` (n,) for ``epochs`` epochs."""
+        X = np.asarray(X, dtype=float)
+        y = np.asarray(y, dtype=float).ravel()
+        if X.ndim != 2 or X.shape[1] != self.p:
+            raise ValueError(f"X must be 2-D with {self.p} columns")
+        if X.shape[0] != y.shape[0]:
+            raise ValueError("X and y have inconsistent lengths")
+        n = X.shape[0]
+        self._init_premise(X)
+        self.history_ = []
+
+        for _ in range(epochs):
+            mu, mu_sel, w, wn, W = self._firing(X)
+            self._lse_consequents(X, y, wn)              # closed-form consequents
+            f, y_pred = self._outputs(X, wn)
+            err = y_pred - y
+            self.history_.append(float(np.sqrt(np.mean(err ** 2))))
+
+            # Backprop the MSE to the premise Gaussians.
+            dL_dw = (err[:, None] * (f - y_pred[:, None]) / W) / n      # (n, R)
+            ratio = w[:, :, None] / (mu_sel + _EPS)                     # (n, R, p)
+            g = dL_dw[:, :, None] * ratio                              # (n, R, p)
+            grad_mu = np.zeros_like(mu)                                # (n, p, M)
+            for jj in range(self.p):
+                kj = self.rule_mf[:, jj]
+                for k in range(self.n_mf):
+                    mask = kj == k
+                    if mask.any():
+                        grad_mu[:, jj, k] = g[:, mask, jj].sum(axis=1)
+
+            diff = X[:, :, None] - self.centers_[None]                  # (n, p, M)
+            grad_c = (grad_mu * mu * diff / self.sigmas_ ** 2).sum(axis=0)
+            grad_s = (grad_mu * mu * diff ** 2 / self.sigmas_ ** 3).sum(axis=0)
+            self.centers_ = self.centers_ - self.lr * grad_c
+            self.sigmas_ = np.maximum(self.sigmas_ - self.lr * grad_s, 1e-3)
+
+        # Refit consequents to the final premise parameters.
+        *_, wn, _ = self._firing(X)
+        self._lse_consequents(X, y, wn)
+        return self
+
+    def predict(self, X) -> np.ndarray:
+        """Predict outputs for ``X`` (n, p). Requires a prior :meth:`fit`."""
+        if self.coeffs_ is None:
+            raise RuntimeError("call fit before predict")
+        X = np.asarray(X, dtype=float)
+        if X.ndim != 2 or X.shape[1] != self.p:
+            raise ValueError(f"X must be 2-D with {self.p} columns")
+        *_, wn, _ = self._firing(X)
+        return self._outputs(X, wn)[1]
+
+    def __repr__(self) -> str:
+        return f"ANFIS(n_inputs={self.p}, n_mf={self.n_mf}, rules={self.R})"
+
+
+__all__ = ["ANFIS"]

fuzzytool/cluster.py

@@ -0,0 +1,231 @@
+"""Fuzzy clustering.
+
+Unlike crisp k-means, fuzzy clustering lets each sample belong to several
+clusters with graded membership. This module provides three algorithms and a
+small set of validity metrics, all on plain NumPy arrays of shape
+``(n_samples, n_features)``:
+
+* :func:`fuzzy_cmeans` — Bezdek's FCM (spherical clusters, Euclidean norm).
+* :func:`gustafson_kessel` — GK, an adaptive norm per cluster that captures
+  ellipsoidal shapes.
+* :func:`possibilistic_cmeans` — PCM, which drops the "memberships sum to 1"
+  constraint so outliers get low typicality in every cluster.
+
+Each returns a :class:`ClusterResult`. Every algorithm accepts a ``seed`` for
+reproducibility.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+import numpy as np
+
+_EPS = 1e-12
+
+
+@dataclass
+class ClusterResult:
+    """Outcome of a fuzzy clustering run.
+
+    Attributes:
+        centers: cluster prototypes, shape ``(c, n_features)``.
+        u: membership/typicality matrix, shape ``(c, n_samples)``.
+        n_iter: iterations run until convergence.
+        objective: final value of the algorithm's objective function.
+        labels: hard assignment ``argmax`` over ``u``, shape ``(n_samples,)``.
+    """
+
+    centers: np.ndarray
+    u: np.ndarray
+    n_iter: int
+    objective: float
+    labels: np.ndarray = field(init=False)
+
+    def __post_init__(self) -> None:
+        self.labels = self.u.argmax(axis=0)
+
+
+def _check(X: np.ndarray, c: int, m: float) -> np.ndarray:
+    X = np.asarray(X, dtype=float)
+    if X.ndim != 2:
+        raise ValueError("X must be 2-D (n_samples, n_features)")
+    if not 1 <= c <= X.shape[0]:
+        raise ValueError(f"need 1 <= c <= n_samples, got c={c}, n={X.shape[0]}")
+    if m <= 1.0:
+        raise ValueError(f"fuzziness m must be > 1, got {m}")
+    return X
+
+
+def _init_u(c: int, n: int, rng: np.random.Generator) -> np.ndarray:
+    u = rng.random((c, n))
+    return u / u.sum(axis=0, keepdims=True)
+
+
+def _centers(X: np.ndarray, u: np.ndarray, m: float) -> np.ndarray:
+    um = u ** m
+    return (um @ X) / np.fmax(um.sum(axis=1, keepdims=True), _EPS)
+
+
+def _dist2(X: np.ndarray, centers: np.ndarray) -> np.ndarray:
+    """Squared Euclidean distance, shape ``(c, n)``."""
+    return np.sum((centers[:, None, :] - X[None, :, :]) ** 2, axis=2)
+
+
+def _update_u(d2: np.ndarray, m: float) -> np.ndarray:
+    d2 = np.fmax(d2, _EPS)
+    inv = d2 ** (-1.0 / (m - 1.0))
+    return inv / inv.sum(axis=0, keepdims=True)
+
+
+def fuzzy_cmeans(X: np.ndarray, c: int, m: float = 2.0, max_iter: int = 150,
+                 tol: float = 1e-5, seed: int | None = None) -> ClusterResult:
+    """Bezdek's fuzzy c-means.
+
+    Args:
+        X: data, shape ``(n_samples, n_features)``.
+        c: number of clusters.
+        m: fuzziness exponent (``> 1``; ``2.0`` is standard).
+        max_iter: maximum iterations.
+        tol: stop when the membership matrix changes by less than this (max-norm).
+        seed: RNG seed for the membership initialization.
+    """
+    X = _check(X, c, m)
+    rng = np.random.default_rng(seed)
+    u = _init_u(c, X.shape[0], rng)
+    centers = _centers(X, u, m)
+    j = np.inf
+    it = 0
+    while it < max_iter:
+        it += 1
+        centers = _centers(X, u, m)
+        d2 = _dist2(X, centers)
+        u_new = _update_u(d2, m)
+        j = float((u_new ** m * d2).sum())
+        if np.abs(u_new - u).max() < tol:
+            u = u_new
+            break
+        u = u_new
+    return ClusterResult(centers, u, it, j)
+
+
+def gustafson_kessel(X: np.ndarray, c: int, m: float = 2.0, max_iter: int = 150,
+                     tol: float = 1e-5, seed: int | None = None,
+                     reg: float = 1e-10) -> ClusterResult:
+    """Gustafson-Kessel clustering (adaptive per-cluster Mahalanobis norm).
+
+    Each cluster learns a covariance-shaped, unit-determinant norm, so GK fits
+    ellipsoidal clusters that FCM (fixed spherical norm) cannot.
+
+    Args:
+        X: data, shape ``(n_samples, n_features)``.
+        c: number of clusters.
+        m: fuzziness exponent (``> 1``).
+        max_iter: maximum iterations.
+        tol: convergence threshold on the membership matrix (max-norm).
+        seed: RNG seed for initialization.
+        reg: ridge added to each fuzzy covariance for numerical stability.
+    """
+    X = _check(X, c, m)
+    n, p = X.shape
+    rng = np.random.default_rng(seed)
+    u = _init_u(c, n, rng)
+    centers = _centers(X, u, m)
+    eye = np.eye(p)
+    j = np.inf
+    it = 0
+    while it < max_iter:
+        it += 1
+        centers = _centers(X, u, m)
+        um = u ** m
+        d2 = np.empty((c, n))
+        for i in range(c):
+            diff = X - centers[i]                                   # (n, p)
+            cov = np.einsum("k,kp,kq->pq", um[i], diff, diff) / max(um[i].sum(), _EPS)
+            cov = cov + reg * eye
+            det = np.linalg.det(cov)
+            if det <= 0 or not np.isfinite(det):
+                a = eye                                             # fall back to Euclidean
+            else:
+                a = (det ** (1.0 / p)) * np.linalg.inv(cov)
+            d2[i] = np.einsum("kp,pq,kq->k", diff, a, diff)
+        u_new = _update_u(d2, m)
+        j = float((u_new ** m * d2).sum())
+        if np.abs(u_new - u).max() < tol:
+            u = u_new
+            break
+        u = u_new
+    return ClusterResult(centers, u, it, j)
+
+
+def possibilistic_cmeans(X: np.ndarray, c: int, m: float = 2.0, max_iter: int = 150,
+                         tol: float = 1e-5, seed: int | None = None,
+                         k: float = 1.0) -> ClusterResult:
+    """Possibilistic c-means (Krishnapuram-Keller).
+
+    PCM drops the probabilistic constraint that memberships sum to 1: each value
+    is a *typicality* in ``[0, 1]``, so noise points score low everywhere. It is
+    initialized from an FCM run, which also fixes each cluster's scale ``eta``.
+
+    Args:
+        X: data, shape ``(n_samples, n_features)``.
+        c: number of clusters.
+        m: fuzziness exponent (``> 1``).
+        max_iter: maximum iterations.
+        tol: convergence threshold on the typicality matrix (max-norm).
+        seed: RNG seed (passed to the initializing FCM).
+        k: scale multiplier for the bandwidth ``eta`` (``1.0`` is standard).
+    """
+    X = _check(X, c, m)
+    init = fuzzy_cmeans(X, c, m=m, max_iter=max_iter, tol=tol, seed=seed)
+    centers, u = init.centers, init.u
+    d2 = _dist2(X, centers)
+    um = u ** m
+    eta = k * (um * d2).sum(axis=1) / np.fmax(um.sum(axis=1), _EPS)   # (c,)
+    eta = np.fmax(eta, _EPS)
+    j = np.inf
+    it = 0
+    while it < max_iter:
+        it += 1
+        d2 = _dist2(X, centers)
+        t = 1.0 / (1.0 + (d2 / eta[:, None]) ** (1.0 / (m - 1.0)))
+        centers_new = _centers(X, t, m)
+        j = float((t ** m * d2).sum() + (eta[:, None] * (1.0 - t) ** m).sum())
+        if np.abs(centers_new - centers).max() < tol:
+            centers = centers_new
+            u = t
+            break
+        centers, u = centers_new, t
+    return ClusterResult(centers, u, it, j)
+
+
+# --- validity metrics ------------------------------------------------------
+
+def partition_coefficient(u: np.ndarray) -> float:
+    """Bezdek's partition coefficient in ``(1/c, 1]``; higher = crisper."""
+    u = np.asarray(u, dtype=float)
+    return float((u ** 2).sum() / u.shape[1])
+
+
+def partition_entropy(u: np.ndarray) -> float:
+    """Partition entropy in ``[0, log c)``; lower = crisper."""
+    u = np.asarray(u, dtype=float)
+    return float(-(u * np.log(np.fmax(u, _EPS))).sum() / u.shape[1])
+
+
+def xie_beni(X, centers: np.ndarray, u: np.ndarray, m: float = 2.0) -> float:
+    """Xie-Beni index (compactness / separation); lower is better."""
+    X = np.asarray(X, dtype=float)
+    centers = np.asarray(centers, dtype=float)
+    u = np.asarray(u, dtype=float)
+    compactness = (u ** m * _dist2(X, centers)).sum()
+    cc = _dist2(centers, centers)
+    sep = cc[~np.eye(centers.shape[0], dtype=bool)].min()
+    return float(compactness / (X.shape[0] * np.fmax(sep, _EPS)))
+
+
+__all__ = [
+    "ClusterResult",
+    "fuzzy_cmeans", "gustafson_kessel", "possibilistic_cmeans",
+    "partition_coefficient", "partition_entropy", "xie_beni",
+]

fuzzytool/datasets.py

@@ -0,0 +1,104 @@
+"""Ready-made example systems."""
+
+from __future__ import annotations
+
+import numpy as np
+
+from . import membership as mf
+from .inference import Mamdani
+from .sets import Variable
+from .type2 import IT2Mamdani, it2_gauss_uncertain_mean
+
+
+def credit_risk() -> tuple[Mamdani, Variable, Variable, Variable]:
+    """A credit-risk-premium Mamdani system.
+
+    Given a borrower's credit ``score`` (300-850) and ``dti`` (debt-to-income
+    ratio, 0-50%), recommend the ``premium`` (risk points, 0-12) a lender should
+    add on top of its base interest rate. Returns ``(system, score, dti,
+    premium)`` so callers can inspect the variables (e.g. for plotting).
+
+    >>> sys, score, dti, premium = credit_risk()
+    >>> safe = sys(score=800, dti=10)      # great score, low leverage
+    >>> risky = sys(score=520, dti=42)     # poor score, high leverage
+    >>> safe < risky
+    True
+    """
+    score = Variable("score", (300, 850))
+    score["poor"] = mf.trap(300, 300, 500, 600)
+    score["fair"] = mf.tri(560, 660, 730)
+    score["good"] = mf.tri(690, 760, 810)
+    score["excellent"] = mf.trap(780, 830, 850, 850)
+
+    dti = Variable("dti", (0, 50))
+    dti["low"] = mf.trap(0, 0, 15, 25)
+    dti["moderate"] = mf.tri(20, 30, 40)
+    dti["high"] = mf.trap(35, 45, 50, 50)
+
+    premium = Variable("premium", (0, 12))
+    premium["low"] = mf.tri(0, 1.5, 4)
+    premium["medium"] = mf.tri(3, 6, 9)
+    premium["high"] = mf.tri(8, 10.5, 12)
+
+    sys = Mamdani()
+    sys.rule(score["poor"] | dti["high"], premium["high"])
+    sys.rule(score["fair"] & dti["moderate"], premium["medium"])
+    sys.rule(score["good"] | score["excellent"], premium["low"])
+    return sys, score, dti, premium
+
+
+def credit_risk_it2() -> tuple[IT2Mamdani, Variable, Variable, Variable]:
+    """An interval type-2 version of :func:`credit_risk`.
+
+    The score and premium terms carry a footprint of uncertainty (uncertain
+    Gaussian means), modeling vagueness in how a "good" score or a "low" premium
+    is defined. Returns ``(system, score, dti, premium)``.
+
+    >>> sys, score, dti, premium = credit_risk_it2()
+    >>> sys(score=800, dti=10) < sys(score=520, dti=42)
+    True
+    """
+    score = Variable("score", (300, 850))
+    score["poor"] = it2_gauss_uncertain_mean(420, 480, 70)
+    score["fair"] = it2_gauss_uncertain_mean(630, 680, 60)
+    score["good"] = it2_gauss_uncertain_mean(740, 780, 50)
+    score["excellent"] = it2_gauss_uncertain_mean(810, 840, 40)
+
+    dti = Variable("dti", (0, 50))
+    dti["low"] = it2_gauss_uncertain_mean(6, 12, 8)
+    dti["moderate"] = it2_gauss_uncertain_mean(27, 33, 7)
+    dti["high"] = it2_gauss_uncertain_mean(42, 48, 7)
+
+    premium = Variable("premium", (0, 12))
+    premium["low"] = it2_gauss_uncertain_mean(1.5, 2.5, 1.5)
+    premium["medium"] = it2_gauss_uncertain_mean(5.5, 6.5, 1.5)
+    premium["high"] = it2_gauss_uncertain_mean(9.5, 10.5, 1.5)
+
+    sys = IT2Mamdani()
+    sys.rule(score["poor"] | dti["high"], premium["high"])
+    sys.rule(score["fair"] & dti["moderate"], premium["medium"])
+    sys.rule(score["good"] | score["excellent"], premium["low"])
+    return sys, score, dti, premium
+
+
+def make_blobs(
+    centers=((0.0, 0.0), (6.0, 6.0), (0.0, 6.0)),
+    n_per: int = 60,
+    spread: float = 0.7,
+    seed: int | None = 0,
+) -> np.ndarray:
+    """Synthetic isotropic Gaussian blobs for clustering demos and tests.
+
+    Returns the stacked data ``X`` of shape ``(len(centers) * n_per, n_features)``.
+
+    >>> X = make_blobs(seed=0)
+    >>> X.shape
+    (180, 2)
+    """
+    rng = np.random.default_rng(seed)
+    centers = np.asarray(centers, dtype=float)
+    blobs = [rng.normal(c, spread, size=(n_per, centers.shape[1])) for c in centers]
+    return np.vstack(blobs)
+
+
+__all__ = ["credit_risk", "credit_risk_it2", "make_blobs"]

fuzzytool/defuzz.py

@@ -0,0 +1,84 @@
+"""Defuzzification: collapse an aggregated output set into a crisp value.
+
+Each defuzzifier takes the discretized universe ``x`` and the aggregated
+membership ``y`` (same shape) and returns a scalar. They are looked up by name
+through :func:`get_defuzzifier`, so adding a method = registering a function.
+"""
+
+from __future__ import annotations
+
+from typing import Callable
+
+import numpy as np
+
+# np.trapz was renamed to np.trapezoid in NumPy 2.0; support both.
+_trapezoid = np.trapezoid if hasattr(np, "trapezoid") else np.trapz
+
+
+def centroid(x: np.ndarray, y: np.ndarray) -> float:
+    """Center of gravity of the area under ``y`` (the most common choice)."""
+    total = _trapezoid(y, x)
+    if total == 0:
+        return float(x[len(x) // 2])  # no rule fired: fall back to mid-universe
+    return float(_trapezoid(x * y, x) / total)
+
+
+def bisector(x: np.ndarray, y: np.ndarray) -> float:
+    """Abscissa that splits the area under ``y`` into two equal halves."""
+    # Cumulative area via the trapezoidal rule.
+    dx = np.diff(x)
+    seg = (y[:-1] + y[1:]) / 2.0 * dx
+    total = seg.sum()
+    if total == 0:
+        return float(x[len(x) // 2])
+    cum = np.concatenate([[0.0], np.cumsum(seg)])
+    idx = int(np.searchsorted(cum, total / 2.0))
+    return float(x[min(idx, len(x) - 1)])
+
+
+def mom(x: np.ndarray, y: np.ndarray) -> float:
+    """Mean of maxima."""
+    peak = y.max()
+    if peak == 0:
+        return float(x[len(x) // 2])
+    return float(x[np.isclose(y, peak)].mean())
+
+
+def som(x: np.ndarray, y: np.ndarray) -> float:
+    """Smallest of maxima."""
+    peak = y.max()
+    if peak == 0:
+        return float(x[len(x) // 2])
+    return float(x[np.isclose(y, peak)].min())
+
+
+def lom(x: np.ndarray, y: np.ndarray) -> float:
+    """Largest of maxima."""
+    peak = y.max()
+    if peak == 0:
+        return float(x[len(x) // 2])
+    return float(x[np.isclose(y, peak)].max())
+
+
+_METHODS: dict[str, Callable[[np.ndarray, np.ndarray], float]] = {
+    "centroid": centroid,
+    "bisector": bisector,
+    "mom": mom,
+    "som": som,
+    "lom": lom,
+}
+
+
+def get_defuzzifier(name: str | Callable) -> Callable:
+    """Resolve a defuzzifier by name (or pass a callable through unchanged)."""
+    if callable(name):
+        return name
+    try:
+        return _METHODS[name]
+    except KeyError:
+        raise ValueError(
+            f"unknown defuzzifier {name!r}; options: {sorted(_METHODS)}"
+        ) from None
+
+
+__all__ = ["centroid", "bisector", "mom", "som", "lom", "get_defuzzifier"]