fuzzytool 0.3.0__tar.gz → 0.4.0__tar.gz

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

@@ -6,6 +6,22 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
+## [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.4.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.4.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.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fuzzytool
-Version: 0.3.0
+Version: 0.4.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,13 @@ 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.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.4.0}/README.md

@@ -55,7 +55,13 @@ 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.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.4.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`,
@@ -74,7 +76,6 @@ Each pulls its dependency in only on import, behind its own extra.
 
 - Fuzzy cognitive maps (+ grey FCM).
 - General (non-interval) type-2; more defuzzifiers.
-- FIS tuning via metaheuristics (e.g. PSO).
 
 ## ⏳ Phase 6 — Release (v0.1.0)
 

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

@@ -90,6 +90,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.4.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.4.0}/fuzzytool/__init__.py

@@ -36,7 +36,7 @@ from .type2 import (
     it2_scale,
 )
 
-__version__ = "0.3.0"
+__version__ = "0.4.0"
 
 __all__ = [
     "__version__",

fuzzytool-0.4.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.4.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.4.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.4.0}/pyproject.toml

@@ -8,7 +8,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "fuzzytool"
-version = "0.3.0"
+version = "0.4.0"
 description = "A clean, extensible fuzzy-logic toolkit in pure Python + NumPy"
 readme = "README.md"
 requires-python = ">=3.9"
@@ -35,6 +35,7 @@ optuna = ["optuna>=3.0"]
 parallel = ["joblib>=1.0"]
 dask = ["dask>=2022.0"]
 agents = ["langchain-core>=0.1"]
+turboswarm = ["turboswarm>=0.7"]
 dev = ["pytest>=7", "pytest-cov", "ruff", "pandas>=1.3", "scikit-learn>=1.0",
        "scipy>=1.7", "optuna>=3.0", "joblib>=1.0", "langchain-core>=0.1"]
 docs = ["mkdocs-material", "mkdocstrings[python]"]

{fuzzytool-0.3.0 → fuzzytool-0.4.0}/tests/test_integrations.py

@@ -177,6 +177,26 @@ def test_scipy_tune_reduces_error():
     assert hasattr(res, "x") and hasattr(res, "cost")
 
 
+def test_turboswarm_tune_reduces_error():
+    pytest.importorskip("turboswarm")
+    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]).ravel()
+    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)
+
+    before = np.sqrt(np.nanmean((sys.predict(x=X[:, 0]) - y) ** 2))
+    res = tune(sys, X, y, columns=["x"], n_particles=20, max_iter=40, seed=0)
+    after = np.sqrt(np.nanmean((sys.predict(x=X[:, 0]) - y) ** 2))
+    assert after < before
+    assert hasattr(res, "best_position") and hasattr(res, "best_value")
+
+
 def test_scipy_tune_keeps_membership_valid():
     pytest.importorskip("scipy")
     from fuzzytool import membership as mf

fuzzytool-0.3.0/fuzzytool/integrations/_util.py

@@ -1,39 +0,0 @@
-"""Shared helpers for the integration submodules."""
-
-from __future__ import annotations
-
-
-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