fuzzytool 0.3.0__tar.gz → 0.5.0__tar.gz

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

@@ -6,6 +6,36 @@ 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
+
+- **turboswarm integration** (`fuzzytool.integrations.turboswarm`, extra
+  `[turboswarm]`): `tune` fits a system's built-in membership-function
+  parameters to data with the sibling library's gradient-free, global Particle
+  Swarm Optimization — the metaheuristic counterpart of the SciPy least-squares
+  tuner. Returns turboswarm's `PsoResult`.
+
+### Changed
+
+- Shared membership-function tuning helpers (`sanitize_mf_params`,
+  `tunable_terms`, `MF_PENALTY`) moved to `fuzzytool.integrations._util` and
+  reused by both the SciPy and turboswarm tuners.
+
 ## [0.3.0] - 2026-06-27
 
 ### Added

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

@@ -5,8 +5,8 @@ type: software
 authors:
   - family-names: Salmeron
     given-names: Jose L.
-version: 0.3.0
-date-released: 2026-06-27
+version: 0.5.0
+date-released: 2026-06-28
 doi: 10.5281/zenodo.20836712
 license: MIT
 repository-code: "https://github.com/fuzzytool/fuzzytool.github.io"

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fuzzytool
-Version: 0.3.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
@@ -53,6 +53,8 @@ Provides-Extra: sklearn
 Requires-Dist: scikit-learn>=1.0; extra == 'sklearn'
 Provides-Extra: torch
 Requires-Dist: torch>=1.12; extra == 'torch'
+Provides-Extra: turboswarm
+Requires-Dist: turboswarm>=0.7; extra == 'turboswarm'
 Provides-Extra: viz
 Requires-Dist: matplotlib>=3.4; extra == 'viz'
 Description-Content-Type: text/markdown
@@ -114,7 +116,20 @@ s-norm, `~` the complement.
 | 4 | **Fuzzy clustering**: fuzzy c-means, Gustafson-Kessel, possibilistic | ✅ |
 | 5 | **ANFIS** (trainable TSK) + **F-transform** (direct/inverse) | ✅ |
 | 6 | Notebooks, JOSS `paper.md`, Zenodo DOI, PyPI release | ✅ |
-| 7 | **Ecosystem integrations**: pandas, scikit-learn, PyTorch, SciPy, Optuna, Joblib/Dask, LLM agents | ✅ |
+| 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
+  membership functions with Particle Swarm Optimization
+  (`integrations.turboswarm.tune`) — the metaheuristic sibling of the SciPy tuner.
 
 ### v0.3.0
 

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

@@ -55,7 +55,20 @@ s-norm, `~` the complement.
 | 4 | **Fuzzy clustering**: fuzzy c-means, Gustafson-Kessel, possibilistic | ✅ |
 | 5 | **ANFIS** (trainable TSK) + **F-transform** (direct/inverse) | ✅ |
 | 6 | Notebooks, JOSS `paper.md`, Zenodo DOI, PyPI release | ✅ |
-| 7 | **Ecosystem integrations**: pandas, scikit-learn, PyTorch, SciPy, Optuna, Joblib/Dask, LLM agents | ✅ |
+| 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
+  membership functions with Particle Swarm Optimization
+  (`integrations.turboswarm.tune`) — the metaheuristic sibling of the SciPy tuner.
 
 ### v0.3.0
 

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

@@ -63,6 +63,8 @@ Each pulls its dependency in only on import, behind its own extra.
       `nn.Module` trainable by autograd and composable into a network.
 - [x] **SciPy** (`[scipy]`): `tune` MF parameters to data via
       `scipy.optimize.least_squares` (returns the `OptimizeResult`).
+- [x] **turboswarm** (`[turboswarm]`): `tune` MF parameters with gradient-free
+      Particle Swarm Optimization (the sibling PSO library; returns `PsoResult`).
 - [x] **Optuna** (`[optuna]`): `suggest_inference_spec`, `suggest_anfis` and a
       ready-made `tune_anfis` study.
 - [x] **Joblib / Dask** (`[parallel]`, `[dask]`): `parallel_predict`,
@@ -70,17 +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.
-- FIS tuning via metaheuristics (e.g. PSO).
+- 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.3.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
@@ -90,6 +94,10 @@ Generated from docstrings with `mkdocstrings`.
 
 ::: fuzzytool.integrations.scipy
 
+## Integrations — turboswarm (PSO)
+
+::: fuzzytool.integrations.turboswarm
+
 ## Integrations — Optuna
 
 ::: fuzzytool.integrations.optuna

{fuzzytool-0.3.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.3.0 → fuzzytool-0.5.0}/docs/integrations.md

@@ -10,6 +10,7 @@ third-party dependency **only when imported**, so the base install stays light.
 | scikit-learn | `fuzzytool.integrations.sklearn` | `pip install fuzzytool[sklearn]` |
 | PyTorch | `fuzzytool.integrations.torch` | `pip install fuzzytool[torch]` |
 | SciPy | `fuzzytool.integrations.scipy` | `pip install fuzzytool[scipy]` |
+| turboswarm | `fuzzytool.integrations.turboswarm` | `pip install fuzzytool[turboswarm]` |
 | Optuna | `fuzzytool.integrations.optuna` | `pip install fuzzytool[optuna]` |
 | Joblib / Dask | `fuzzytool.integrations.parallel` | `pip install fuzzytool[parallel]` / `[dask]` |
 | LLM agents | `fuzzytool.integrations.agents` | `pip install fuzzytool[agents]` |
@@ -199,6 +200,38 @@ Only built-in shapes (`tri`, `trap`, `gauss`, `gbell`, `sigmoid`, `ramp_up`,
 `tune_outputs=False` to keep a Mamdani's output sets fixed, and forward any
 `least_squares` keyword (e.g. `max_nfev=200`).
 
+## turboswarm
+
+[turboswarm](https://pypi.org/project/turboswarm/) is fuzzytool's sibling
+Particle Swarm Optimization library. Its `tune` is the **gradient-free, global**
+counterpart of the SciPy one: slower, but it escapes poor local optima and needs
+no derivatives — a good fit for the rugged error surfaces fuzzy rule bases
+produce. Same call shape, returns turboswarm's `PsoResult`:
+
+```python
+import numpy as np
+import fuzzytool as fz
+from fuzzytool.integrations.turboswarm import tune
+
+rng = np.random.default_rng(0)
+X = rng.uniform(0, 10, size=(150, 1))
+y = np.sin(X[:, 0]) + 0.1 * X[:, 0]
+
+x = fz.Variable("x", (0, 10), terms=["lo", "mid", "hi"])
+sys = fz.TSK()
+sys.rule(x["lo"], 0.0)
+sys.rule(x["mid"], 0.5)
+sys.rule(x["hi"], 1.0)
+
+result = tune(sys, X, y, columns=["x"], n_particles=20, max_iter=40, seed=0)
+result.best_value     # PsoResult; the system now fits the data better
+```
+
+Each parameter is searched within `±margin × universe` around its current value
+(`margin=0.5` by default); shape validity is enforced every evaluation. Any
+`turboswarm.minimize` keyword (`topology`, `patience`, `max_time`, …) is
+forwarded.
+
 ## Optuna
 
 Fuzzy systems have many discrete/continuous knobs. These helpers turn an Optuna

{fuzzytool-0.3.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.3.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.5.0/fuzzytool/integrations/_util.py

@@ -0,0 +1,96 @@
+"""Shared helpers for the integration submodules."""
+
+from __future__ import annotations
+
+from .. import membership as mf
+
+# Returned in place of a non-finite residual so tuners avoid degenerate regions.
+MF_PENALTY = 1e6
+
+
+def input_variable_names(system) -> list[str]:
+    """Ordered, de-duplicated names of the input variables a system reads.
+
+    Walks every rule's antecedent tree of a :class:`~fuzzytool.inference.Mamdani`
+    or :class:`~fuzzytool.inference.TSK` system and collects the variables its
+    propositions reference, in first-seen order. This is the natural column
+    order for feeding a 2-D array or a DataFrame to the system.
+    """
+    names: list[str] = []
+    seen: set[str] = set()
+
+    def walk(node) -> None:
+        if hasattr(node, "variable"):            # Proposition (atom)
+            name = node.variable.name
+            if name not in seen:
+                seen.add(name)
+                names.append(name)
+        if hasattr(node, "left"):                # And / Or
+            walk(node.left)
+            walk(node.right)
+        if hasattr(node, "operand"):             # Not
+            walk(node.operand)
+
+    for rule in getattr(system, "rules", []):
+        walk(rule.antecedent)
+    return names
+
+
+def output_name(system, default: str = "output") -> str:
+    """Best-effort name for a single-output system (Mamdani tracks it; TSK does not)."""
+    outputs = getattr(system, "_outputs", None)
+    if outputs:
+        return next(iter(outputs))
+    return default
+
+
+def sanitize_mf_params(kind: str, params) -> list[float]:
+    """Repair a membership-function parameter slice so it is always a valid shape.
+
+    Keeps breakpoints ordered and widths positive, so a tuner (SciPy least-squares
+    or turboswarm PSO) can explore freely without producing degenerate sets.
+    """
+    p = [float(v) for v in params]
+    if kind in ("tri", "trap", "ramp_up", "ramp_down"):
+        return sorted(p)                       # keep breakpoints ordered
+    if kind == "gauss":
+        return [p[0], abs(p[1]) or 1e-6]       # sigma > 0
+    if kind == "gbell":
+        return [abs(p[0]) or 1e-6, abs(p[1]) or 1e-6, p[2]]  # width, slope > 0
+    return p
+
+
+def tunable_terms(system, tune_outputs: bool = True):
+    """Collect ``(variable, term_name, kind, params)`` for every tunable MF.
+
+    Walks the rules' propositions (and, if ``tune_outputs``, the Mamdani output
+    variables), keeping only terms backed by a built-in membership shape; custom
+    callables are skipped.
+    """
+    seen: dict[int, object] = {}
+
+    def walk(node):
+        if hasattr(node, "variable"):
+            seen.setdefault(id(node.variable), node.variable)
+        if hasattr(node, "left"):
+            walk(node.left)
+            walk(node.right)
+        if hasattr(node, "operand"):
+            walk(node.operand)
+
+    for rule in getattr(system, "rules", []):
+        walk(rule.antecedent)
+    variables = dict(seen)
+    if tune_outputs:
+        for out in getattr(system, "_outputs", {}).values():
+            variables.setdefault(id(out), out)
+
+    terms = []
+    for var in variables.values():
+        for term_name, membership in var.terms.items():
+            try:
+                spec = mf.to_dict(membership)
+            except TypeError:
+                continue                       # custom callable: skip
+            terms.append((var, term_name, spec["type"], list(spec["params"])))
+    return terms

{fuzzytool-0.3.0 → fuzzytool-0.5.0}/fuzzytool/integrations/scipy.py

@@ -20,27 +20,18 @@ from typing import TYPE_CHECKING
 import numpy as np
 
 from .. import membership as mf
-from ._util import input_variable_names
+from ._util import (
+    MF_PENALTY,
+    input_variable_names,
+    sanitize_mf_params,
+    tunable_terms,
+)
 
 if TYPE_CHECKING:
     from scipy.optimize import OptimizeResult
 
     from ..inference import TSK, Mamdani
 
-# Per-shape repair applied before rebuilding, so every candidate is a valid MF.
-_PENALTY = 1e6
-
-
-def _sanitize(kind: str, params: list[float]) -> list[float]:
-    p = [float(v) for v in params]
-    if kind in ("tri", "trap", "ramp_up", "ramp_down"):
-        return sorted(p)                       # keep breakpoints ordered
-    if kind == "gauss":
-        return [p[0], abs(p[1]) or 1e-6]       # sigma > 0
-    if kind == "gbell":
-        return [abs(p[0]) or 1e-6, abs(p[1]) or 1e-6, p[2]]  # width, slope > 0
-    return p
-
 
 def _require_scipy():
     try:
@@ -53,38 +44,6 @@ def _require_scipy():
     return least_squares
 
 
-def _tunable_terms(system, tune_outputs: bool):
-    """Variables and term names whose membership functions can be tuned."""
-    # Collect the Variable instances behind the rules' propositions.
-    seen: dict[int, object] = {}
-
-    def walk(node):
-        if hasattr(node, "variable"):
-            seen.setdefault(id(node.variable), node.variable)
-        if hasattr(node, "left"):
-            walk(node.left)
-            walk(node.right)
-        if hasattr(node, "operand"):
-            walk(node.operand)
-
-    for rule in system.rules:
-        walk(rule.antecedent)
-    variables = dict(seen)
-    if tune_outputs:
-        for out in getattr(system, "_outputs", {}).values():
-            variables.setdefault(id(out), out)
-
-    terms = []
-    for var in variables.values():
-        for term_name, membership in var.terms.items():
-            try:
-                spec = mf.to_dict(membership)
-            except TypeError:
-                continue                       # custom callable: skip
-            terms.append((var, term_name, spec["type"], list(spec["params"])))
-    return terms
-
-
 def tune(
     system: Mamdani | TSK,
     X: np.ndarray,
@@ -115,7 +74,7 @@ def tune(
     names = list(columns) if columns is not None else input_variable_names(system)
     inputs = {name: X[:, j] for j, name in enumerate(names)}
 
-    terms = _tunable_terms(system, tune_outputs)
+    terms = tunable_terms(system, tune_outputs)
     if not terms:
         raise ValueError("the system has no tunable built-in membership functions")
 
@@ -130,13 +89,13 @@ def tune(
     def apply(p):
         for (var, term_name, kind, _params), (start, size) in zip(terms, slices):
             var[term_name] = mf.from_dict(
-                {"type": kind, "params": _sanitize(kind, p[start:start + size])})
+                {"type": kind, "params": sanitize_mf_params(kind, p[start:start + size])})
 
     def residual(p):
         apply(p)
         pred = np.asarray(system.predict(**inputs), dtype=float)
         r = pred - y
-        return np.where(np.isfinite(r), r, _PENALTY)
+        return np.where(np.isfinite(r), r, MF_PENALTY)
 
     result = least_squares(residual, p0, **least_squares_kwargs)
     apply(result.x)                            # leave the system at the best fit

fuzzytool-0.5.0/fuzzytool/integrations/turboswarm.py

@@ -0,0 +1,120 @@
+"""turboswarm integration: tune a fuzzy system with Particle Swarm Optimization.
+
+Install with ``pip install fuzzytool[turboswarm]``. :func:`tune` fits the
+parameters of a system's built-in membership functions to data with
+`turboswarm <https://pypi.org/project/turboswarm/>`_'s PSO — a **gradient-free,
+global** optimizer. It is the metaheuristic sibling of
+:func:`fuzzytool.integrations.scipy.tune` (local least-squares): slower, but it
+escapes poor local optima and needs no derivatives, which suits the rugged,
+non-smooth error surfaces fuzzy rule bases often produce.
+
+Each parameter is searched within a box of ``±margin × universe`` around its
+current value; shape validity (ordered breakpoints, positive widths) is enforced
+every evaluation, so the swarm explores freely. The system is mutated in place
+with the best parameters found and the turboswarm ``PsoResult`` is returned.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+from .. import membership as mf
+from ._util import (
+    MF_PENALTY,
+    input_variable_names,
+    sanitize_mf_params,
+    tunable_terms,
+)
+
+if TYPE_CHECKING:
+    from turboswarm import PsoResult
+
+    from ..inference import TSK, Mamdani
+
+
+def _require_turboswarm():
+    try:
+        from turboswarm import minimize
+    except ImportError as exc:  # pragma: no cover
+        raise ImportError(
+            "the turboswarm integration needs turboswarm; install with "
+            "`pip install fuzzytool[turboswarm]`"
+        ) from exc
+    return minimize
+
+
+def tune(
+    system: Mamdani | TSK,
+    X: np.ndarray,
+    y: np.ndarray,
+    columns: list[str] | None = None,
+    tune_outputs: bool = True,
+    margin: float = 0.5,
+    n_particles: int = 30,
+    max_iter: int = 100,
+    seed: int | None = None,
+    **minimize_kwargs,
+) -> PsoResult:
+    """Fit a system's membership-function parameters to data with PSO.
+
+    Extra keyword arguments are forwarded to :func:`turboswarm.minimize`
+    (e.g. ``topology``, ``patience``, ``max_time``).
+
+    Args:
+        system: a Mamdani or TSK system (mutated in place with the best params).
+        X: inputs, shape ``(n_samples, n_inputs)``.
+        y: targets, shape ``(n_samples,)``.
+        columns: input variable names matching ``X``'s columns, in order.
+            Defaults to the variables the rules reference.
+        tune_outputs: also tune the output variables' MFs (Mamdani only).
+        margin: search half-width per parameter as a fraction of its variable's
+            universe span (``0.5`` searches ±50% of the span around each value).
+        n_particles: swarm size.
+        max_iter: PSO iterations.
+        seed: PSO seed for reproducibility.
+
+    Returns:
+        The turboswarm ``PsoResult`` (``.best_position``, ``.best_value``, …).
+    """
+    minimize = _require_turboswarm()
+    X = np.asarray(X, dtype=float)
+    y = np.asarray(y, dtype=float)
+    names = list(columns) if columns is not None else input_variable_names(system)
+    inputs = {name: X[:, j] for j, name in enumerate(names)}
+
+    terms = tunable_terms(system, tune_outputs)
+    if not terms:
+        raise ValueError("the system has no tunable built-in membership functions")
+
+    # Flatten parameters; each gets a search box of ±(margin * span) around p0.
+    slices, p0, bounds = [], [], []
+    for var, _term, _kind, params in terms:
+        delta = margin * (var.high - var.low)
+        start = len(p0)
+        for value in params:
+            p0.append(value)
+            bounds.append((value - delta, value + delta))
+        slices.append((start, len(params)))
+
+    def apply(position):
+        for (var, term_name, kind, _params), (start, size) in zip(terms, slices):
+            var[term_name] = mf.from_dict(
+                {"type": kind,
+                 "params": sanitize_mf_params(kind, position[start:start + size])})
+
+    def objective(position):
+        apply(position)
+        pred = np.asarray(system.predict(**inputs), dtype=float)
+        r = pred - y
+        r = np.where(np.isfinite(r), r, MF_PENALTY)
+        return float(np.mean(r * r))           # mean squared error
+
+    result = minimize(objective, bounds=bounds, n_particles=n_particles,
+                      max_iter=max_iter, seed=seed, **minimize_kwargs)
+    apply(result.best_position)                # leave the system at the best fit
+    return result
+
+
+__all__ = ["tune"]

{fuzzytool-0.3.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",
 ]