fuzzytool 0.4.0__tar.gz → 0.5.0__tar.gz

{fuzzytool-0.4.0 → fuzzytool-0.5.0}/CHANGELOG.md

@@ -6,6 +6,20 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-06-28
+
+### Added
+
+- **General type-2 (GT2) fuzzy sets** via the zSlices / alpha-plane
+  representation (`fuzzytool.type2.general`):
+  - `GeneralType2MF` — a GT2 set as a stack of IT2 z-slices; also exposes the
+    overall FOU (`lower`/`upper`), so it can stand in for its IT2 footprint.
+  - Constructors `gt2_from_it2`, `gt2_gauss_uncertain_mean`, `gt2_scale`
+    (triangular secondary membership peaking at the principal MF).
+  - `GeneralType2Mamdani` — inference as a z-weighted stack of IT2 Mamdani
+    runs, reusing the Karnik-Mendel machinery.
+  - `centroid_gt2` — zSlices type reduction of a single GT2 set.
+
 ## [0.4.0] - 2026-06-28
 
 ### Added

{fuzzytool-0.4.0 → fuzzytool-0.5.0}/CITATION.cff

@@ -5,7 +5,7 @@ type: software
 authors:
   - family-names: Salmeron
     given-names: Jose L.
-version: 0.4.0
+version: 0.5.0
 date-released: 2026-06-28
 doi: 10.5281/zenodo.20836712
 license: MIT

{fuzzytool-0.4.0 → fuzzytool-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fuzzytool
-Version: 0.4.0
+Version: 0.5.0
 Summary: A clean, extensible fuzzy-logic toolkit in pure Python + NumPy
 Project-URL: Homepage, https://fuzzytool.github.io
 Project-URL: Documentation, https://fuzzytool.github.io
@@ -118,6 +118,13 @@ s-norm, `~` the complement.
 | 6 | Notebooks, JOSS `paper.md`, Zenodo DOI, PyPI release | ✅ |
 | 7 | **Ecosystem integrations**: pandas, scikit-learn, PyTorch, SciPy, turboswarm, Optuna, Joblib/Dask, LLM agents | ✅ |
 
+### v0.5.0
+
+- **General type-2 (GT2) fuzzy sets** via the zSlices / alpha-plane
+  representation: `GeneralType2MF`, the `gt2_*` constructors,
+  `GeneralType2Mamdani` inference and `centroid_gt2` type reduction — reusing
+  the existing interval type-2 / Karnik-Mendel machinery.
+
 ### v0.4.0
 
 - **turboswarm integration:** gradient-free, global tuning of a fuzzy system's

{fuzzytool-0.4.0 → fuzzytool-0.5.0}/README.md

@@ -57,6 +57,13 @@ s-norm, `~` the complement.
 | 6 | Notebooks, JOSS `paper.md`, Zenodo DOI, PyPI release | ✅ |
 | 7 | **Ecosystem integrations**: pandas, scikit-learn, PyTorch, SciPy, turboswarm, Optuna, Joblib/Dask, LLM agents | ✅ |
 
+### v0.5.0
+
+- **General type-2 (GT2) fuzzy sets** via the zSlices / alpha-plane
+  representation: `GeneralType2MF`, the `gt2_*` constructors,
+  `GeneralType2Mamdani` inference and `centroid_gt2` type reduction — reusing
+  the existing interval type-2 / Karnik-Mendel machinery.
+
 ### v0.4.0
 
 - **turboswarm integration:** gradient-free, global tuning of a fuzzy system's

{fuzzytool-0.4.0 → fuzzytool-0.5.0}/ROADMAP.md

@@ -72,16 +72,26 @@ Each pulls its dependency in only on import, behind its own extra.
 - [x] **Agents (LangChain/LangGraph)** (`[agents]`): `explain` plus an
       `inference_tool` LangChain tool that reports which rules fired.
 
+## ✅ General type-2 (zSlices)
+
+- [x] `GeneralType2MF` via the zSlices / alpha-plane representation (a stack of
+      IT2 slices; also exposes the overall FOU, so it degrades to IT2).
+- [x] Constructors `gt2_from_it2`, `gt2_gauss_uncertain_mean`, `gt2_scale`
+      (triangular secondary MF).
+- [x] `GeneralType2Mamdani` (z-weighted stack of IT2 Mamdani inferences) and
+      `centroid_gt2` zSlices type reduction.
+
 ## Ideas for later
 
 - Fuzzy cognitive maps (+ grey FCM).
-- General (non-interval) type-2; more defuzzifiers.
+- More defuzzifiers; non-triangular GT2 secondary MFs.
 
 ## ⏳ Phase 6 — Release (v0.1.0)
 
 - [x] Example notebooks (`notebooks/`) and a comparison page vs scikit-fuzzy.
 - [x] JOSS `paper.md`; Zenodo metadata (`.zenodo.json`) and a citing/releasing page.
 - [x] GitHub Pages live (`https://fuzzytool.github.io`).
-- [ ] Register the PyPI trusted publisher, then tag `v0.1.0` to publish (the
-      `release-pypi.yml` workflow is ready).
-- [ ] Enable the Zenodo GitHub integration and cut a release to mint a DOI.
+- [x] PyPI trusted publisher registered; tagging a version runs `release-pypi.yml`
+      (published 0.1.0 → 0.4.0 via OIDC, no stored token).
+- [x] Zenodo GitHub integration; each GitHub release is archived with a DOI
+      (`10.5281/zenodo.20836712`).

{fuzzytool-0.4.0 → fuzzytool-0.5.0}/docs/api/python.md

@@ -62,6 +62,10 @@ Generated from docstrings with `mkdocstrings`.
 
 ::: fuzzytool.type2.reduction
 
+## General type-2 (zSlices)
+
+::: fuzzytool.type2.general
+
 ## Fuzzy clustering
 
 ::: fuzzytool.cluster

{fuzzytool-0.4.0 → fuzzytool-0.5.0}/docs/guide/type2.md

@@ -82,3 +82,49 @@ plt.show()
 ```
 
 ![IT2 score variable: each term's LMF and UMF with a shaded footprint of uncertainty](../images/it2_score.png)
+
+## General type-2 (zSlices)
+
+An IT2 set treats every point inside its FOU as equally possible. A **general
+type-2** set adds a *secondary* membership that weights those possibilities —
+the third dimension IT2 discards. fuzzytool represents a GT2 set with the
+**zSlices / alpha-plane** decomposition: slicing the secondary domain at levels
+`z` turns the GT2 set into a stack of ordinary IT2 sets, so inference and type
+reduction reuse the IT2 machinery and combine the slices weighted by `z`.
+
+Each constructor builds a GT2 set from an IT2 footprint plus a **triangular
+secondary** peaking at the principal (mid) MF — narrow at `z = 1`, the full FOU
+at `z → 0`:
+
+```python
+import fuzzytool as fz
+
+score = fz.Variable("score", (300, 850))
+score["good"] = fz.gt2_gauss_uncertain_mean(740, 780, 50, n_slices=5)
+score["poor"] = fz.gt2_gauss_uncertain_mean(420, 480, 70, n_slices=5)
+premium = fz.Variable("premium", (0, 12))
+premium["low"]  = fz.gt2_gauss_uncertain_mean(1.5, 2.5, 1.5)
+premium["high"] = fz.gt2_gauss_uncertain_mean(9.5, 10.5, 1.5)
+
+sys = fz.GeneralType2Mamdani()
+sys.rule(score["good"], premium["low"])
+sys.rule(score["poor"], premium["high"])
+sys(score=780)    # -> 2.31  (z-weighted average of per-slice IT2 results)
+```
+
+![A general type-2 set as nested z-slices (alpha-planes) over its footprint of uncertainty](../images/gt2_zslices.png)
+
+A GT2 term also exposes `lower`/`upper` (its overall FOU), so it can stand in for
+its IT2 footprint inside an `IT2Mamdani` if you want the cheaper approximation.
+Build a GT2 set from *any* IT2 footprint with
+[`gt2_from_it2`][fuzzytool.type2.general.gt2_from_it2], and type-reduce a single
+GT2 set with `centroid_gt2`:
+
+```python
+import numpy as np
+from fuzzytool.type2 import centroid_gt2
+
+good = fz.gt2_gauss_uncertain_mean(740, 780, 50, n_slices=6)
+universe = np.linspace(300, 850, 400)
+centroid_gt2(good, universe)   # -> ~754.7  (z-weighted centroid)
+```

{fuzzytool-0.4.0 → fuzzytool-0.5.0}/fuzzytool/__init__.py

@@ -29,14 +29,19 @@ from .serialize import load, save
 from .sets import Variable
 from .type2 import (
     IT2TSK,
+    GeneralType2Mamdani,
+    GeneralType2MF,
     IT2Mamdani,
+    gt2_from_it2,
+    gt2_gauss_uncertain_mean,
+    gt2_scale,
     it2,
     it2_gauss_uncertain_mean,
     it2_gauss_uncertain_std,
     it2_scale,
 )
 
-__version__ = "0.4.0"
+__version__ = "0.5.0"
 
 __all__ = [
     "__version__",
@@ -51,6 +56,9 @@ __all__ = [
     # interval type-2
     "IT2Mamdani", "IT2TSK",
     "it2", "it2_scale", "it2_gauss_uncertain_mean", "it2_gauss_uncertain_std",
+    # general type-2
+    "GeneralType2Mamdani", "GeneralType2MF",
+    "gt2_from_it2", "gt2_gauss_uncertain_mean", "gt2_scale",
     # fuzzy clustering
     "fuzzy_cmeans", "gustafson_kessel", "possibilistic_cmeans",
     # learning & approximation

{fuzzytool-0.4.0 → fuzzytool-0.5.0}/fuzzytool/type2/__init__.py

@@ -9,6 +9,14 @@ IT2 rules reuse the very same operator syntax as type-1 rules (``|``, ``&``,
 tree and collapse the result with Karnik-Mendel type reduction.
 """
 
+from .general import (
+    GeneralType2Mamdani,
+    GeneralType2MF,
+    centroid_gt2,
+    gt2_from_it2,
+    gt2_gauss_uncertain_mean,
+    gt2_scale,
+)
 from .inference import IT2TSK, IT2Mamdani
 from .reduction import centroid_it2, karnik_mendel, km_endpoint
 from .sets import (
@@ -24,4 +32,6 @@ __all__ = [
     "it2", "it2_scale", "it2_gauss_uncertain_mean", "it2_gauss_uncertain_std",
     "IT2Mamdani", "IT2TSK",
     "karnik_mendel", "km_endpoint", "centroid_it2",
+    "GeneralType2MF", "GeneralType2Mamdani", "centroid_gt2",
+    "gt2_from_it2", "gt2_gauss_uncertain_mean", "gt2_scale",
 ]

fuzzytool-0.5.0/fuzzytool/type2/general.py

@@ -0,0 +1,211 @@
+"""General type-2 (GT2) fuzzy sets via the zSlices / alpha-plane representation.
+
+An interval type-2 set treats every point inside its footprint of uncertainty
+(FOU) as equally possible. A **general** type-2 set adds a *secondary* membership
+that weights those possibilities — the third dimension IT2 throws away.
+
+A practical, exact way to handle that third dimension is the **zSlices** (alpha
+-plane) decomposition (Wagner & Hagras): slice the secondary domain at levels
+``z`` and, at each level, the GT2 set reduces to an ordinary IT2 set whose FOU is
+the ``z``-cut. Inference and type reduction then run the existing IT2 machinery
+on each slice and combine the results, weighted by ``z``.
+
+Here a GT2 set is built from an IT2 footprint plus a **triangular secondary**
+peaking at the FOU's principal (mid) MF: at ``z -> 0`` a slice is the full FOU,
+at ``z = 1`` it collapses to the principal MF.
+
+* :class:`GeneralType2MF` — a stack of IT2 z-slices (also exposes the overall
+  FOU via ``lower``/``upper``, so it degrades gracefully to IT2).
+* :func:`gt2_from_it2`, :func:`gt2_gauss_uncertain_mean`, :func:`gt2_scale` —
+  constructors.
+* :class:`GeneralType2Mamdani` — z-weighted stack of IT2 Mamdani inferences.
+* :func:`centroid_gt2` — zSlices centroid of a single GT2 set.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from ..sets import Variable
+from .inference import IT2Mamdani
+from .reduction import centroid_it2
+from .sets import IntervalType2MF, it2
+
+
+class GeneralType2MF:
+    """A general type-2 set represented as a stack of IT2 ``z``-slices.
+
+    Args:
+        slices: IT2 sets, one per ``z`` level, narrowing toward the principal MF
+            as ``z`` increases.
+        zlevels: the secondary levels (in ``(0, 1]``), ascending, aligned with
+            ``slices``.
+        footprint: the overall FOU as an IT2 set (used for ``lower``/``upper`` so
+            the GT2 set can stand in for its IT2 footprint).
+    """
+
+    def __init__(self, slices: list[IntervalType2MF], zlevels: np.ndarray,
+                 footprint: IntervalType2MF) -> None:
+        self.slices = list(slices)
+        self.zlevels = np.asarray(zlevels, dtype=float)
+        self._footprint = footprint
+
+    @property
+    def n_slices(self) -> int:
+        return len(self.slices)
+
+    def slice(self, i: int) -> IntervalType2MF:
+        """The IT2 set at ``z``-level index ``i``."""
+        return self.slices[i]
+
+    def lower(self, x):
+        return self._footprint.lower(x)
+
+    def upper(self, x):
+        return self._footprint.upper(x)
+
+    def __call__(self, x):
+        return self._footprint(x)
+
+    def __repr__(self) -> str:
+        return f"GeneralType2MF(n_slices={self.n_slices})"
+
+
+def gt2_from_it2(footprint: IntervalType2MF, n_slices: int = 5) -> GeneralType2MF:
+    """Build a GT2 set from an IT2 FOU with a triangular secondary MF.
+
+    The secondary membership peaks at the principal MF (the midline of the FOU)
+    and falls linearly to 0 at the LMF/UMF. The ``z``-slice at level ``z`` is the
+    IT2 set whose FOU is narrowed from the full footprint toward that midline by
+    a factor ``(1 - z)``.
+
+    Args:
+        footprint: the IT2 set describing the full footprint of uncertainty.
+        n_slices: number of ``z`` levels (``z = 1/n .. 1``). More slices = a finer
+            secondary, at proportional cost.
+    """
+    if n_slices < 1:
+        raise ValueError("n_slices must be >= 1")
+    zlevels = np.linspace(1.0 / n_slices, 1.0, n_slices)
+
+    def mid(x):
+        return (footprint.lower(x) + footprint.upper(x)) / 2.0
+
+    slices = []
+    for z in zlevels:
+        # Default-arg binding captures the current z in each closure.
+        def lower(x, z=z):
+            m = mid(x)
+            return m - (1.0 - z) * (m - footprint.lower(x))
+
+        def upper(x, z=z):
+            m = mid(x)
+            return m + (1.0 - z) * (footprint.upper(x) - m)
+
+        slices.append(it2(lower, upper))
+    return GeneralType2MF(slices, zlevels, footprint)
+
+
+def gt2_gauss_uncertain_mean(c1: float, c2: float, sigma: float,
+                             n_slices: int = 5) -> GeneralType2MF:
+    """GT2 Gaussian with an uncertain mean in ``[c1, c2]`` (triangular secondary)."""
+    from .sets import it2_gauss_uncertain_mean
+    return gt2_from_it2(it2_gauss_uncertain_mean(c1, c2, sigma), n_slices)
+
+
+def gt2_scale(mf, scale: float, n_slices: int = 5) -> GeneralType2MF:
+    """GT2 set from a height-uncertainty FOU (UMF ``mf``, LMF ``scale * mf``)."""
+    from .sets import it2_scale
+    return gt2_from_it2(it2_scale(mf, scale), n_slices)
+
+
+def centroid_gt2(gt2mf: GeneralType2MF, universe) -> float:
+    """zSlices centroid of a GT2 set: ``z``-weighted mean of per-slice IT2 centroids."""
+    z = gt2mf.zlevels
+    mids = np.array([sum(centroid_it2(gt2mf.slice(i), universe)) / 2.0
+                     for i in range(gt2mf.n_slices)])
+    return float(np.sum(z * mids) / np.sum(z))
+
+
+def _antecedent_variables(node, out: dict) -> None:
+    if hasattr(node, "variable"):
+        out.setdefault(id(node.variable), node.variable)
+    if hasattr(node, "left"):
+        _antecedent_variables(node.left, out)
+        _antecedent_variables(node.right, out)
+    if hasattr(node, "operand"):
+        _antecedent_variables(node.operand, out)
+
+
+class GeneralType2Mamdani:
+    """General type-2 Mamdani inference via the zSlices decomposition.
+
+    At each ``z`` level the GT2 terms collapse to their IT2 ``z``-slice and the
+    existing :class:`~fuzzytool.type2.inference.IT2Mamdani` engine
+    (center-of-sets type reduction) produces a crisp output ``y(z)``. The final
+    result is the ``z``-weighted average ``Σ z·y(z) / Σ z`` — the centroid of the
+    type-reduced general type-2 output.
+
+    Variables may mix GT2 and IT2/type-1 terms; only the GT2 terms are sliced.
+    All GT2 terms must share the same ``z`` levels (same ``n_slices``).
+    """
+
+    def __init__(self, tnorm="min", snorm="max") -> None:
+        self._it2 = IT2Mamdani(tnorm, snorm)
+
+    def rule(self, antecedent, consequent, weight: float = 1.0) -> GeneralType2Mamdani:
+        """Add ``IF antecedent THEN output is term`` and return ``self``."""
+        self._it2.rule(antecedent, consequent, weight)
+        return self
+
+    @property
+    def rules(self):
+        return self._it2.rules
+
+    def _gt2_variables(self) -> list[Variable]:
+        found: dict[int, Variable] = {}
+        for r in self._it2.rules:
+            _antecedent_variables(r.antecedent, found)
+            found.setdefault(id(r.consequent.variable), r.consequent.variable)
+        return [v for v in found.values()
+                if any(isinstance(t, GeneralType2MF) for t in v.terms.values())]
+
+    def __call__(self, **inputs: float):
+        """Run inference. Returns a float for one output, else a dict by name."""
+        if not self._it2.rules:
+            raise RuntimeError("no rules defined")
+        variables = self._gt2_variables()
+        if not variables:
+            raise RuntimeError("no general type-2 terms found; use IT2Mamdani instead")
+        zlevels = next(t.zlevels for v in variables for t in v.terms.values()
+                       if isinstance(t, GeneralType2MF))
+
+        z_acc, y_acc = [], []
+        for i, z in enumerate(zlevels):
+            saved = {id(v): v.terms for v in variables}
+            try:
+                for v in variables:
+                    v.terms = {name: (t.slice(i) if isinstance(t, GeneralType2MF) else t)
+                               for name, t in v.terms.items()}
+                self._it2._centroids.clear()
+                y = self._it2(**inputs)
+            finally:
+                for v in variables:
+                    v.terms = saved[id(v)]
+            z_acc.append(float(z))
+            y_acc.append(y)
+
+        z = np.asarray(z_acc)
+        if isinstance(y_acc[0], dict):
+            return {k: float(np.sum(z * np.array([y[k] for y in y_acc])) / np.sum(z))
+                    for k in y_acc[0]}
+        return float(np.sum(z * np.asarray(y_acc)) / np.sum(z))
+
+    def __repr__(self) -> str:
+        return f"GeneralType2Mamdani(rules={len(self._it2.rules)})"
+
+
+__all__ = [
+    "GeneralType2MF", "gt2_from_it2", "gt2_gauss_uncertain_mean", "gt2_scale",
+    "centroid_gt2", "GeneralType2Mamdani",
+]

{fuzzytool-0.4.0 → fuzzytool-0.5.0}/pyproject.toml

@@ -8,7 +8,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "fuzzytool"
-version = "0.4.0"
+version = "0.5.0"
 description = "A clean, extensible fuzzy-logic toolkit in pure Python + NumPy"
 readme = "README.md"
 requires-python = ">=3.9"

{fuzzytool-0.4.0 → fuzzytool-0.5.0}/tests/test_type2.py

@@ -75,3 +75,59 @@ def test_type1_and_it2_terms_mix_in_one_antecedent():
     lo, hi = (a["hi"] & b["hi"]).eval_interval({"a": 0.8, "b": 1.0},
                                                fz.norms.t_min, fz.norms.s_max)
     assert lo <= hi
+
+
+# --- general type-2 (zSlices) -----------------------------------------------
+
+def test_gt2_exposes_footprint_and_slices():
+    g = fz.gt2_gauss_uncertain_mean(740, 780, 50, n_slices=5)
+    x = np.linspace(300, 850, 200)
+    # degrades to its IT2 footprint via lower/upper
+    assert np.all(g.lower(x) <= g.upper(x) + 1e-12)
+    assert g.n_slices == 5 and len(g.zlevels) == 5
+    # the z=1 slice (last) collapses toward the principal MF: near-zero FOU
+    top = g.slice(g.n_slices - 1)
+    assert np.max(top.upper(x) - top.lower(x)) < 1e-9
+    # the lowest slice spans (almost) the full footprint
+    bottom = g.slice(0)
+    assert np.max(bottom.upper(x) - bottom.lower(x)) > 0.0
+
+
+def test_gt2_mamdani_runs_and_is_bounded():
+    score = fz.Variable("score", (300, 850))
+    score["good"] = fz.gt2_gauss_uncertain_mean(740, 780, 50)
+    score["poor"] = fz.gt2_gauss_uncertain_mean(420, 480, 70)
+    premium = fz.Variable("premium", (0, 12))
+    premium["low"] = fz.gt2_gauss_uncertain_mean(1.5, 2.5, 1.5)
+    premium["high"] = fz.gt2_gauss_uncertain_mean(9.5, 10.5, 1.5)
+
+    sys = fz.GeneralType2Mamdani()
+    sys.rule(score["good"], premium["low"])
+    sys.rule(score["poor"], premium["high"])
+    # a good score gives a low premium, a poor score a high one
+    assert sys(score=780) < sys(score=450)
+    assert 0.0 <= sys(score=780) <= 12.0
+
+
+def test_gt2_does_not_mutate_terms_after_call():
+    score = fz.Variable("score", (300, 850))
+    score["good"] = fz.gt2_gauss_uncertain_mean(740, 780, 50)
+    premium = fz.Variable("premium", (0, 12))
+    premium["low"] = fz.gt2_gauss_uncertain_mean(1.5, 2.5, 1.5)
+    sys = fz.GeneralType2Mamdani()
+    sys.rule(score["good"], premium["low"])
+    sys(score=760)
+    # terms are restored to the original GT2 objects (not left as a slice)
+    from fuzzytool.type2 import GeneralType2MF
+    assert isinstance(score.terms["good"], GeneralType2MF)
+    assert isinstance(premium.terms["low"], GeneralType2MF)
+
+
+def test_centroid_gt2_matches_it2_order():
+    from fuzzytool.type2 import centroid_gt2
+    g = fz.gt2_gauss_uncertain_mean(740, 780, 50, n_slices=6)
+    uni = np.linspace(300, 850, 400)
+    c_gt2 = centroid_gt2(g, uni)
+    c_it2 = sum(centroid_it2(g, uni)) / 2.0
+    assert 700 < c_gt2 < 820
+    assert abs(c_gt2 - c_it2) < 20          # close, but GT2 weights the principal MF