bulanik 0.3.0__py3-none-any.whl

bulanik/__init__.py

@@ -0,0 +1,66 @@
+"""bulanik: easy-to-use fuzzy numbers, fuzzy inference and fuzzy MCDM.
+
+The package root re-exports the fuzzy number types of [`bulanik.numbers`][bulanik.numbers]
+so that the most common objects are one import away:
+
+- [`TFN`][bulanik.numbers.TFN], [`TrFN`][bulanik.numbers.TrFN]: triangular and trapezoidal numbers.
+- [`IFN`][bulanik.numbers.IFN], [`PFN`][bulanik.numbers.PFN], [`FFN`][bulanik.numbers.FFN],
+  [`QROFN`][bulanik.numbers.QROFN]: orthopair numbers (q = 1, 2, 3, any q).
+- [`IVIFN`][bulanik.numbers.IVIFN], [`IVPFN`][bulanik.numbers.IVPFN], [`IVFFN`][bulanik.numbers.IVFFN],
+  [`IVQROFN`][bulanik.numbers.IVQROFN]: their interval-valued versions.
+- [`SphericalFN`][bulanik.numbers.SphericalFN], [`PictureFN`][bulanik.numbers.PictureFN],
+  [`NeutrosophicFN`][bulanik.numbers.NeutrosophicFN]: three-part numbers.
+- [`IVNeutrosophicFN`][bulanik.numbers.IVNeutrosophicFN]: interval neutrosophic numbers.
+- [`IT2TrFN`][bulanik.numbers.IT2TrFN]: interval type-2 trapezoidal numbers.
+
+Inference, MCDM, aggregation, sets, scales and the optional LumiX / sezgi bridges
+live in submodules (`bulanik.inference`, `bulanik.mcdm`, `bulanik.aggregate`,
+`bulanik.sets`, `bulanik.scales`, `bulanik.lumix`, `bulanik.sezgi`).
+
+Attributes:
+    __version__: The installed package version string.
+
+Examples:
+    >>> import bulanik
+    >>> bulanik.TFN(1, 2, 4).score()
+    2.3333
+"""
+
+from .numbers import (
+    FFN,
+    IFN,
+    IT2TrFN,
+    IVFFN,
+    IVIFN,
+    IVNeutrosophicFN,
+    IVPFN,
+    IVQROFN,
+    PFN,
+    QROFN,
+    TFN,
+    NeutrosophicFN,
+    PictureFN,
+    SphericalFN,
+    TrFN,
+)
+
+__version__ = "0.3.0"
+
+__all__ = [
+    "TFN",
+    "TrFN",
+    "QROFN",
+    "IFN",
+    "PFN",
+    "FFN",
+    "IVQROFN",
+    "IVIFN",
+    "IVPFN",
+    "IVFFN",
+    "SphericalFN",
+    "PictureFN",
+    "NeutrosophicFN",
+    "IVNeutrosophicFN",
+    "IT2TrFN",
+    "__version__",
+]

bulanik/_linalg.py

@@ -0,0 +1,135 @@
+r"""Small pure-Python dense linear algebra: Cholesky solve and ridge least squares.
+
+Private helpers of [`ANFIS`][bulanik.anfis.ANFIS] training (not public API, no
+dependency on NumPy): `solve_spd` solves a symmetric positive definite system by
+Cholesky factorisation, `normal_equations` forms $A^T A$ and $A^T y$ for a
+design matrix, and `lstsq` combines them into a ridge least-squares solve,
+$(A^T A + \lambda I)\theta = A^T y$.
+"""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Sequence
+
+__all__ = ["inverse", "lstsq", "normal_equations", "solve_spd"]
+
+
+def inverse(a: Sequence[Sequence[float]]) -> list[list[float]]:
+    """Inverse of a square matrix by Gauss-Jordan elimination with partial pivoting.
+
+    Raises ValueError when ``a`` is not square or not finite, or is singular,
+    i.e. a pivot satisfies ``|pivot| <= 1e-12 * max|a_ij|``.
+    """
+    n = len(a)
+    if n == 0 or any(len(row) != n for row in a):
+        raise ValueError("inverse needs a non-empty square matrix")
+    m = [[float(v) for v in row] + [1.0 if i == j else 0.0 for j in range(n)] for i, row in enumerate(a)]
+    if not all(math.isfinite(v) for row in m for v in row):
+        raise ValueError("inverse needs finite entries")
+    scale = max(abs(v) for row in m for v in row[:n])
+    for c in range(n):
+        p = max(range(c, n), key=lambda r: abs(m[r][c]))
+        if abs(m[p][c]) <= 1e-12 * scale:
+            raise ValueError("matrix is singular")
+        m[c], m[p] = m[p], m[c]
+        piv = m[c][c]
+        m[c] = [v / piv for v in m[c]]
+        for r in range(n):
+            if r != c and m[r][c] != 0.0:
+                f = m[r][c]
+                m[r] = [v - f * w for v, w in zip(m[r], m[c])]
+    return [row[n:] for row in m]
+
+
+def solve_spd(a: Sequence[Sequence[float]], b: Sequence[float]) -> list[float]:
+    """Solve ``a x = b`` for a symmetric positive definite ``a`` (Cholesky).
+
+    Raises ValueError when ``a`` is not square, not symmetric, not finite or
+    not (numerically) positive definite, i.e. a Cholesky pivot is <= 0.
+    """
+    n = len(a)
+    if n == 0 or any(len(row) != n for row in a):
+        raise ValueError("solve_spd needs a non-empty square matrix")
+    if len(b) != n:
+        raise ValueError(f"right-hand side has {len(b)} entries, matrix is {n}x{n}")
+    m = [[float(v) for v in row] for row in a]
+    rhs = [float(v) for v in b]
+    if not all(math.isfinite(v) for row in m for v in row) or not all(map(math.isfinite, rhs)):
+        raise ValueError("solve_spd needs finite entries")
+    for i in range(n):
+        for j in range(i):
+            if abs(m[i][j] - m[j][i]) > 1e-12 * max(1.0, abs(m[i][j]), abs(m[j][i])):
+                raise ValueError("solve_spd needs a symmetric matrix")
+    # In-place lower Cholesky factor L (row-major), a = L L^T.
+    low = [[0.0] * n for _ in range(n)]
+    for j in range(n):
+        lj = low[j]
+        d = m[j][j] - sum(v * v for v in lj[:j])
+        if not d > 0.0:
+            raise ValueError("matrix is not positive definite (Cholesky pivot <= 0)")
+        ljj = math.sqrt(d)
+        lj[j] = ljj
+        for i in range(j + 1, n):
+            li = low[i]
+            li[j] = (m[i][j] - sum(li[k] * lj[k] for k in range(j))) / ljj
+    # Forward substitution L z = b, then back substitution L^T x = z.
+    z = [0.0] * n
+    for i in range(n):
+        li = low[i]
+        z[i] = (rhs[i] - sum(li[k] * z[k] for k in range(i))) / li[i]
+    x = [0.0] * n
+    for i in range(n - 1, -1, -1):
+        x[i] = (z[i] - sum(low[k][i] * x[k] for k in range(i + 1, n))) / low[i][i]
+    return x
+
+
+def normal_equations(
+    rows: Sequence[Sequence[float]], y: Sequence[float]
+) -> tuple[list[list[float]], list[float]]:
+    """``(A^T A, A^T y)`` for the design matrix ``A`` given by ``rows``."""
+    if not rows:
+        raise ValueError("lstsq needs at least one row")
+    if len(rows) != len(y):
+        raise ValueError(f"lstsq got {len(rows)} rows but {len(y)} targets")
+    p = len(rows[0])
+    gram = [[0.0] * p for _ in range(p)]
+    aty = [0.0] * p
+    for row, target in zip(rows, y):
+        if len(row) != p:
+            raise ValueError("lstsq rows must all have the same length")
+        r = [float(v) for v in row]
+        t = float(target)
+        if not math.isfinite(t) or not all(map(math.isfinite, r)):
+            raise ValueError("lstsq needs finite rows and targets")
+        for i in range(p):
+            ri = r[i]
+            if ri == 0.0:
+                continue
+            aty[i] += ri * t
+            gi = gram[i]
+            for j in range(i, p):
+                gi[j] += ri * r[j]
+    for i in range(p):
+        for j in range(i):
+            gram[i][j] = gram[j][i]
+    return gram, aty
+
+
+def lstsq(
+    rows: Sequence[Sequence[float]], y: Sequence[float], ridge: float = 1e-8
+) -> list[float]:
+    """Ridge least squares: solve ``(A^T A + ridge I) theta = A^T y``.
+
+    A positive ``ridge`` makes rank-deficient designs (a constant column,
+    duplicate rows) solvable; the solution then tends to the minimum-norm
+    least-squares solution as ``ridge -> 0``. ``ridge=0`` is the plain normal
+    equation and raises ValueError when ``A^T A`` is singular.
+    """
+    ridge = float(ridge)
+    if not (math.isfinite(ridge) and ridge >= 0.0):
+        raise ValueError(f"ridge must be finite and >= 0, got {ridge}")
+    gram, aty = normal_equations(rows, y)
+    for i in range(len(gram)):
+        gram[i][i] += ridge
+    return solve_spd(gram, aty)

bulanik/_validate.py

@@ -0,0 +1,93 @@
+"""Shared validation helpers (private).
+
+Argument checking used across the package: finite numbers, values in
+$[0, 1]$ (with a tolerance of $10^{-12}$ for rounding), method-name resolution
+and weight vectors. Nothing here is public API; the helpers define the error
+messages that the public functions raise.
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Sequence
+
+TOL = 1e-12
+
+
+def _num(v: float) -> str:
+    """Short form of ``v`` that still round-trips (``%g`` when exact, else repr)."""
+    short = f"{v:g}"
+    return short if float(short) == v else repr(v)
+
+
+def finite(x: float, name: str) -> float:
+    """Return ``x`` as a float; raise ValueError on NaN or infinity."""
+    if isinstance(x, (bool, str)):
+        raise TypeError(f"{name} must be a number, got {type(x).__name__} {x!r}")
+    x = float(x)
+    if not math.isfinite(x):
+        raise ValueError(f"{name} must be finite, got {x}")
+    return x
+
+
+def unit(x: float, name: str) -> float:
+    """Return ``x`` clamped into [0, 1] when it is outside by at most TOL."""
+    x = finite(x, name)
+    if x < 0.0:
+        if x < -TOL:
+            raise ValueError(f"{name} must be in [0, 1], got {x}")
+        return 0.0
+    if x > 1.0:
+        if x > 1.0 + TOL:
+            raise ValueError(f"{name} must be in [0, 1], got {x}")
+        return 1.0
+    return x
+
+
+def choose(
+    name: str | None,
+    valid: Sequence[str],
+    what: str,
+    owner: str,
+    default: str | None = None,
+) -> str:
+    """Resolve a method name, defaulting when None; list valid names on error."""
+    if name is None:
+        if default is None:
+            raise ValueError(f"no {what} given for {owner}; valid: {', '.join(valid)}")
+        return default
+    if name not in valid:
+        raise ValueError(
+            f"unknown {what} '{name}' for {owner}; valid: {', '.join(valid)}"
+        )
+    return name
+
+
+def check_weights(
+    weights: Sequence[float] | None, n: int, normalize: bool = False
+) -> list[float]:
+    """Validate ``n`` weights (None means equal weights 1/n).
+
+    Without ``normalize`` the weights must sum to 1 within 1e-9; the weights
+    are returned as given (callers such as :func:`bulanik.aggregate.wa` rescale
+    them to sum to exactly 1). With ``normalize`` they are divided by their sum.
+    """
+    if n < 1:
+        raise ValueError("need at least one weight")
+    if weights is None:
+        return [1.0 / n] * n
+    if len(weights) != n:
+        raise ValueError(f"expected {n} weights, got {len(weights)}")
+    w = [finite(x, "weight") for x in weights]
+    if any(x < 0 for x in w):
+        raise ValueError("weights must be non-negative")
+    total = sum(w)
+    if not math.isfinite(total):  # each weight is finite but their sum overflowed
+        raise ValueError("weights are too large: their sum overflows a float")
+    if normalize:
+        if total <= 0:
+            raise ValueError("weights must not all be zero")
+        return [x / total for x in w]
+    if abs(total - 1.0) > 1e-9:
+        raise ValueError(f"weights must sum to 1, got {total}")
+    return w

bulanik/aggregate.py

@@ -0,0 +1,226 @@
+r"""Weighted aggregation: weighted average (WA), weighted geometric (WG), experts.
+
+[`wa`][bulanik.aggregate.wa] and [`wg`][bulanik.aggregate.wg] combine fuzzy numbers
+of one type with non-negative weights summing to 1, using the type's own
+operators (`scale` / `add` for the average, `power` / `mul` for the geometric
+mean). [`aggregate_experts`][bulanik.aggregate.aggregate_experts] applies one of
+them to a stack of expert rating matrices, cell by cell.
+
+All functions require the inputs to be of one class (and rung, for orthopair
+numbers); mixing types raises `TypeError`.
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Sequence
+
+from ._validate import check_weights, choose
+from .numbers import FuzzyNumber, PictureFN
+from .numbers.threepart import _picture_aggregate
+
+
+def _prepare(
+    values: Sequence[FuzzyNumber],
+    weights: Sequence[float] | None,
+    ops: str,
+    normalize: bool,
+) -> tuple[list[FuzzyNumber], list[float]]:
+    """Validate, then return the inputs with a positive weight and those weights."""
+    values = list(values)
+    if not values:
+        raise ValueError("cannot aggregate an empty list of values")
+    first = values[0]
+    if not isinstance(first, FuzzyNumber):
+        raise TypeError(f"cannot aggregate {type(first).__name__}; need fuzzy numbers")
+    for v in values[1:]:
+        first.same_kind(v)
+    first._check_ops(ops)
+    w = check_weights(weights, len(values), normalize)
+    total = math.fsum(w)  # within 1e-9 of 1 already; make it exactly 1
+    pairs = [(v, x / total) for v, x in zip(values, w) if x > 0.0]
+    return [v for v, _ in pairs], [x for _, x in pairs]
+
+
+def _fold(
+    values: Sequence[FuzzyNumber],
+    weights: Sequence[float] | None,
+    ops: str,
+    normalize: bool,
+    kind: str,
+) -> FuzzyNumber:
+    vals, w = _prepare(values, weights, ops, normalize)
+    if not vals:  # unreachable for valid weights; kept as a guard
+        raise ValueError("weights must not all be zero")  # pragma: no cover
+    if isinstance(vals[0], PictureFN):
+        return _picture_aggregate(vals, w, kind)  # scale(k < 1) is not closed for pictures
+    if kind == "wa":
+        out = vals[0].scale(w[0], ops)
+        for v, x in zip(vals[1:], w[1:]):
+            out = out.add(v.scale(x, ops), ops)
+    else:
+        out = vals[0].power(w[0], ops)
+        for v, x in zip(vals[1:], w[1:]):
+            out = out.mul(v.power(x, ops), ops)
+    return out
+
+
+def wa(
+    values: Sequence[FuzzyNumber],
+    weights: Sequence[float] | None = None,
+    *,
+    ops: str = "algebraic",
+    normalize: bool = False,
+) -> FuzzyNumber:
+    r"""Weighted average $\sum_i w_i A_i$ with the type's own operators.
+
+    Computed as `scale` of each number by its weight, folded with `add`. For
+    triangular numbers this is the componentwise weighted mean of the points;
+    for intuitionistic numbers it is the classic IFWA operator
+    $\left(1 - \prod_i (1 - \mu_i)^{w_i},\; \prod_i \nu_i^{w_i}\right)$.
+    Picture numbers use the closed form
+    $\left(1 - \prod_i (1 - \mu_i)^{w_i},\; \prod_i \eta_i^{w_i},\; \prod_i \nu_i^{w_i}\right)$,
+    because scaling by a weight below 1 is not closed for them.
+
+    `weights=None` means equal weights $1/n$. Weights must be non-negative and
+    sum to 1 unless `normalize=True` (then they are divided by their sum);
+    weights that sum to 1 only within $10^{-9}$ are accepted and silently
+    rescaled to sum to exactly 1. Inputs with a weight of 0 are ignored.
+
+    Args:
+        values: Fuzzy numbers of one type (and rung).
+        weights: One weight per value, or `None` for equal weights.
+        ops: Operator set of the type, `"algebraic"` or (orthopair) `"einstein"`.
+        normalize: Divide the weights by their sum instead of requiring sum 1.
+
+    Returns:
+        The aggregated number, of the type of the inputs.
+
+    Raises:
+        ValueError: If `values` is empty, the number of weights differs, a
+            weight is negative or not finite, the weights do not sum to 1 (and
+            `normalize` is false) or are all zero (with `normalize`), or `ops`
+            is unsupported.
+        TypeError: If the values are not fuzzy numbers or differ in type.
+
+    References:
+        Xu (2007), IEEE Transactions on Fuzzy Systems 15(6): intuitionistic
+        fuzzy aggregation operators. Wei (2017) for the picture closed forms
+        (retracted by the publisher in 2025; the closed forms are tested
+        against the code, not the paper).
+
+    Examples:
+        >>> from bulanik import TFN, IFN
+        >>> from bulanik.aggregate import wa
+        >>> wa([TFN(1, 2, 4), TFN(2, 3, 5)])
+        TFN(l=1.5, m=2.5, u=4.5)
+        >>> r = wa([IFN(0.6, 0.3), IFN(0.5, 0.4)], [2, 1], normalize=True)
+        >>> round(r.mu, 4), round(r.nu, 4)
+        (0.5691, 0.3302)
+        >>> wa([TFN(1, 2, 4), TFN(2, 3, 5)], [0.5, 0.2])
+        Traceback (most recent call last):
+        ...
+        ValueError: weights must sum to 1, got 0.7
+    """
+    return _fold(values, weights, ops, normalize, "wa")
+
+
+def wg(
+    values: Sequence[FuzzyNumber],
+    weights: Sequence[float] | None = None,
+    *,
+    ops: str = "algebraic",
+    normalize: bool = False,
+) -> FuzzyNumber:
+    r"""Weighted geometric mean $\prod_i A_i^{w_i}$ with the type's own operators.
+
+    Computed as `power` of each number by its weight, folded with `mul`. For
+    positive triangular numbers this is the componentwise weighted geometric
+    mean of the points. Weights, `normalize` and `ops` behave as in
+    [`wa`][bulanik.aggregate.wa]. Picture numbers use closed forms
+    $\left(\prod_i (\mu_i + \eta_i)^{w_i} - \prod_i \eta_i^{w_i},\;
+    \prod_i \eta_i^{w_i},\; 1 - \prod_i (1 - \nu_i)^{w_i}\right)$.
+
+    Args:
+        values: Fuzzy numbers of one type (and rung).
+        weights: One weight per value, or `None` for equal weights.
+        ops: Operator set of the type, `"algebraic"` or (orthopair) `"einstein"`.
+        normalize: Divide the weights by their sum instead of requiring sum 1.
+
+    Returns:
+        The aggregated number, of the type of the inputs.
+
+    Raises:
+        ValueError: As for [`wa`][bulanik.aggregate.wa]; additionally, for
+            triangular numbers with a negative lowest point.
+        TypeError: If the values are not fuzzy numbers or differ in type.
+
+    References:
+        Xu and Yager (2006), International Journal of General Systems 35(4):
+        intuitionistic fuzzy geometric aggregation operators.
+
+    Examples:
+        >>> from bulanik import TFN
+        >>> from bulanik.aggregate import wg
+        >>> r = wg([TFN(1, 2, 4), TFN(2, 3, 5)])
+        >>> round(r.l, 4), round(r.m, 4), round(r.u, 4)
+        (1.4142, 2.4495, 4.4721)
+    """
+    return _fold(values, weights, ops, normalize, "wg")
+
+
+def aggregate_experts(
+    ratings: Sequence[Sequence[Sequence[FuzzyNumber]]],
+    weights: Sequence[float] | None = None,
+    *,
+    method: str = "wa",
+    ops: str = "algebraic",
+    normalize: bool = False,
+) -> list[list[FuzzyNumber]]:
+    """Aggregate expert ratings indexed ``[expert][alternative][criterion]``.
+
+    For every alternative-criterion cell the experts' numbers are combined with
+    [`wa`][bulanik.aggregate.wa] or [`wg`][bulanik.aggregate.wg] using the
+    expert weights.
+
+    Args:
+        ratings: One matrix per expert; each is a list (alternatives) of lists
+            (criteria) of fuzzy numbers, all of the same shape and type.
+        weights: One weight per expert, or `None` for equal weights.
+        method: `"wa"` (default) or `"wg"`.
+        ops: Operator set of the number type.
+        normalize: Divide the expert weights by their sum instead of requiring sum 1.
+
+    Returns:
+        The `[alternative][criterion]` matrix of aggregated numbers.
+
+    Raises:
+        ValueError: If `method` is unknown, there are no experts, the matrices
+            differ in shape, or the weights are invalid (see
+            [`wa`][bulanik.aggregate.wa]).
+        TypeError: If the numbers differ in type.
+
+    Examples:
+        >>> from bulanik import TFN
+        >>> from bulanik.aggregate import aggregate_experts
+        >>> a, b = TFN(1, 2, 4), TFN(2, 3, 5)
+        >>> experts = [[[a, b]], [[b, a]]]  # 2 experts, 1 alternative, 2 criteria
+        >>> aggregate_experts(experts)
+        [[TFN(l=1.5, m=2.5, u=4.5), TFN(l=1.5, m=2.5, u=4.5)]]
+    """
+    method = choose(method, ("wa", "wg"), "method", "aggregate_experts")
+    fn = wa if method == "wa" else wg
+    if not ratings:
+        raise ValueError("need at least one expert")
+    check_weights(weights, len(ratings), normalize)  # also when there are no cells
+    n_alt, n_crit = len(ratings[0]), len(ratings[0][0]) if ratings[0] else 0
+    for r in ratings:
+        if len(r) != n_alt or any(len(row) != n_crit for row in r):
+            raise ValueError("expert rating matrices must all have the same shape")
+    return [
+        [
+            fn([r[i][j] for r in ratings], weights, ops=ops, normalize=normalize)
+            for j in range(n_crit)
+        ]
+        for i in range(n_alt)
+    ]