flkit 0.1.0__py3-none-any.whl

flkit/alg/inter/KrigingM.py

@@ -0,0 +1,262 @@
+import numpy as np
+from .BasePredictor import Predictor
+from .LossFuncs import ErrorMetrics
+
+
+class KrigingOpm(Predictor):
+    """
+    普通克里金插值（Ordinary Kriging），遵循 IDWOpm 的设计模式：
+    - 通过 __call__(data) 传入训练样本（list/tuple，每个元素为 [x, y, z]）
+    - 通过 predict(points) 预测多个查询点（list/tuple，每个元素为 [x, y]）
+    - 可使用 add_params(params) 设置变差函数参数：
+        {
+            "variogram": "spherical" | "exponential" | "gaussian",
+            "range": float,   # 影响范围 a
+            "sill": float,    # 基台 s
+            "nugget": float   # 块金 n（用于数值稳定，默认极小值）
+        }
+    """
+
+    class OKModel:
+        def __init__(self, x: list, y: list, value: list, params: dict | None = None):
+            self.x = np.asarray(x, dtype=float)
+            self.y = np.asarray(y, dtype=float)
+            self.value = np.asarray(value, dtype=float)
+            self.n = len(self.value)
+
+            # 读取参数
+            params = params or {}
+            self.variogram = params.get("variogram", "spherical")
+            # 经验设定：若未提供，range 取最大样本距离的一半，sill 取样本方差，nugget 给一个极小正数以稳定求逆
+            # 计算样本两两距离
+            pts = np.column_stack((self.x, self.y))
+            dmat = self._pairwise_dist(pts, pts)
+            max_d = float(np.max(dmat)) if self.n > 1 else 1.0
+            self.range = float(params.get("range", max(1e-8, 0.5 * max_d)))
+            var = float(np.var(self.value))
+            self.sill = float(params.get("sill", var if var > 0 else 1.0))
+            self.nugget = float(params.get("nugget", 1e-10))
+
+            # 构造普通克里金矩阵 K（n+1, n+1）: [Gamma 1; 1^T 0]
+            # 其中 Gamma_ij = gamma(|x_i - x_j|)
+            Gamma = self._gamma(dmat)
+            K = np.zeros((self.n + 1, self.n + 1), dtype=float)
+            K[: self.n, : self.n] = Gamma
+            K[: self.n, self.n] = 1.0
+            K[self.n, : self.n] = 1.0
+            # 预计算逆或伪逆，提高多点预测效率
+            # 为避免奇异情况，使用伪逆更鲁棒
+            self.K_inv = np.linalg.pinv(K)
+
+        def _pairwise_dist(self, A: np.ndarray, B: np.ndarray) -> np.ndarray:
+            # ||A_i - B_j|| 的矩阵
+            # 使用 (a-b)^2 = a^2 + b^2 - 2ab 加速计算
+            A2 = np.sum(A**2, axis=1, keepdims=True)
+            B2 = np.sum(B**2, axis=1, keepdims=True).T
+            d2 = A2 + B2 - 2 * (A @ B.T)
+            d2 = np.maximum(d2, 0.0)
+            return np.sqrt(d2)
+
+        def _structure(self, h: np.ndarray) -> np.ndarray:
+            a = self.range
+            if self.variogram == "spherical":
+                # spherical: s * (1.5*(h/a) - 0.5*(h/a)^3) for h<=a, else s
+                hr = np.clip(h / a, 0.0, None)
+                val = 1.5 * hr - 0.5 * (hr**3)
+                return np.where(h <= a, self.sill * val, self.sill)
+            elif self.variogram == "exponential":
+                # exponential: s * (1 - exp(-h/a))
+                return self.sill * (1.0 - np.exp(-h / a))
+            elif self.variogram == "gaussian":
+                # gaussian: s * (1 - exp(-(h/a)^2))
+                hr = h / a
+                return self.sill * (1.0 - np.exp(-(hr**2)))
+            else:
+                # 默认使用 exponential
+                return self.sill * (1.0 - np.exp(-h / a))
+
+        def _gamma(self, hmat: np.ndarray) -> np.ndarray:
+            # 半变异函数 gamma(h) = nugget + structure(h)
+            gamma = self.nugget + self._structure(hmat)
+            # 理论上 gamma(0) = nugget；已在式中体现
+            return gamma
+
+        def execute(self, point_x: float, point_y: float):
+            # 构造右端向量 k: [gamma(|x_i - x|); 1]
+            p = np.array([[point_x, point_y]], dtype=float)
+            pts = np.column_stack((self.x, self.y))
+            d = self._pairwise_dist(pts, p).ravel()  # shape (n,)
+            k = np.zeros(self.n + 1, dtype=float)
+            k[: self.n] = self.nugget + self._structure(d)
+            k[self.n] = 1.0
+
+            # 求权重
+            w_lambda = self.K_inv @ k
+            w = w_lambda[: self.n]
+            lam = w_lambda[self.n]
+
+            # 预测值
+            z_hat = float(np.dot(w, self.value))
+            # 克里金方差（近似公式）：sigma^2 = sum_i w_i * gamma(h_i) + lambda
+            sigma2 = float(np.dot(w, k[: self.n]) + lam)
+            return z_hat, sigma2
+
+    def fit(self, data: list | tuple):
+        x = [row[0] for row in data]
+        y = [row[1] for row in data]
+        z = [row[2] for row in data]
+        self.model = self.OKModel(x, y, z, self.params)
+        return self
+
+    def predict(self, points: list | tuple):
+        arr = np.asarray(points)
+        if arr.ndim == 1:
+            result, _ = self.model.execute(float(arr[0]), float(arr[1]))
+            return result
+        if arr.ndim == 2 and arr.shape[1] == 2:
+            z1 = np.zeros(arr.shape[0], dtype=float)
+            for i in range(arr.shape[0]):
+                result, _ = self.model.execute(float(arr[i, 0]), float(arr[i, 1]))
+                z1[i] = result
+            return z1
+        raise ValueError("预测点坐标必须是2列：[x, y] 或形状 (M, 2)")
+
+    def loss(self, data, res):
+        return ErrorMetrics.mse(data, res)
+
+
+class KrigingOpm3D(Predictor):
+    """
+    三维普通克里金插值（3D Ordinary Kriging），仿照 IDWOpm3D 的设计模式：
+    - 通过 __call__(data) 传入训练样本（list/tuple，每个元素为 [x, y, z, value]）
+    - 通过 predict(points) 预测多个查询点（list/tuple，每个元素为 [x, y, z]）
+    - 可使用 add_params(params) 设置变差函数参数：
+        {
+            "variogram": "spherical" | "exponential" | "gaussian",
+            "range": float,   # 影响范围 a
+            "sill": float,    # 基台 s
+            "nugget": float   # 块金 n（用于数值稳定，默认极小值）
+        }
+    """
+
+    class OK3DModel:
+        def __init__(
+            self, x: list, y: list, z: list, value: list, params: dict | None = None
+        ):
+            self.x = np.asarray(x, dtype=float)
+            self.y = np.asarray(y, dtype=float)
+            self.z = np.asarray(z, dtype=float)
+            self.value = np.asarray(value, dtype=float)
+            self.n = len(self.value)
+
+            # 读取参数
+            params = params or {}
+            self.variogram = params.get("variogram", "spherical")
+
+            # 计算三维样本两两距离
+            pts = np.column_stack((self.x, self.y, self.z))
+            dmat = self._pairwise_dist_3d(pts, pts)
+            max_d = float(np.max(dmat)) if self.n > 1 else 1.0
+            self.range = float(params.get("range", max(1e-8, 0.5 * max_d)))
+            var = float(np.var(self.value))
+            self.sill = float(params.get("sill", var if var > 0 else 1.0))
+            self.nugget = float(params.get("nugget", 1e-10))
+
+            # 构造普通克里金矩阵 K（n+1, n+1）: [Gamma 1; 1^T 0]
+            # 其中 Gamma_ij = gamma(|x_i - x_j|)
+            Gamma = self._gamma(dmat)
+            K = np.zeros((self.n + 1, self.n + 1), dtype=float)
+            K[: self.n, : self.n] = Gamma
+            K[: self.n, self.n] = 1.0
+            K[self.n, : self.n] = 1.0
+            # 预计算逆或伪逆，提高多点预测效率
+            # 为避免奇异情况，使用伪逆更鲁棒
+            self.K_inv = np.linalg.pinv(K)
+
+        def _pairwise_dist_3d(self, A: np.ndarray, B: np.ndarray) -> np.ndarray:
+            """计算三维点集A和B之间的欧几里得距离矩阵"""
+            # ||A_i - B_j|| 的矩阵
+            # 使用 (a-b)^2 = a^2 + b^2 - 2ab 加速计算
+            A2 = np.sum(A**2, axis=1, keepdims=True)
+            B2 = np.sum(B**2, axis=1, keepdims=True).T
+            d2 = A2 + B2 - 2 * (A @ B.T)
+            d2 = np.maximum(d2, 0.0)
+            return np.sqrt(d2)
+
+        def _structure(self, h: np.ndarray) -> np.ndarray:
+            """变差函数的结构部分"""
+            a = self.range
+            if self.variogram == "spherical":
+                # spherical: s * (1.5*(h/a) - 0.5*(h/a)^3) for h<=a, else s
+                hr = np.clip(h / a, 0.0, None)
+                val = 1.5 * hr - 0.5 * (hr**3)
+                return np.where(h <= a, self.sill * val, self.sill)
+            elif self.variogram == "exponential":
+                # exponential: s * (1 - exp(-h/a))
+                return self.sill * (1.0 - np.exp(-h / a))
+            elif self.variogram == "gaussian":
+                # gaussian: s * (1 - exp(-(h/a)^2))
+                hr = h / a
+                return self.sill * (1.0 - np.exp(-(hr**2)))
+            else:
+                # 默认使用 exponential
+                return self.sill * (1.0 - np.exp(-h / a))
+
+        def _gamma(self, hmat: np.ndarray) -> np.ndarray:
+            """半变异函数 gamma(h) = nugget + structure(h)"""
+            gamma = self.nugget + self._structure(hmat)
+            return gamma
+
+        def execute(self, point_x: float, point_y: float, point_z: float):
+            """执行三维克里金插值预测"""
+            # 构造右端向量 k: [gamma(|x_i - x|); 1]
+            p = np.array([[point_x, point_y, point_z]], dtype=float)
+            pts = np.column_stack((self.x, self.y, self.z))
+            d = self._pairwise_dist_3d(pts, p).ravel()  # shape (n,)
+            k = np.zeros(self.n + 1, dtype=float)
+            k[: self.n] = self.nugget + self._structure(d)
+            k[self.n] = 1.0
+
+            # 求权重
+            w_lambda = self.K_inv @ k
+            w = w_lambda[: self.n]
+            lam = w_lambda[self.n]
+
+            # 预测值
+            z_hat = float(np.dot(w, self.value))
+            # 克里金方差（近似公式）：sigma^2 = sum_i w_i * gamma(h_i) + lambda
+            sigma2 = float(np.dot(w, k[: self.n]) + lam)
+            return z_hat, sigma2
+
+    def fit(self, data: list | tuple):
+        """初始化模型，传入训练数据"""
+        x = [row[0] for row in data]
+        y = [row[1] for row in data]
+        z = [row[2] for row in data]
+        value = [row[3] for row in data]
+        self.model = self.OK3DModel(x, y, z, value, self.params)
+        return self
+
+    def predict(self, points: list | tuple):
+        """预测多个查询点的值"""
+        arr = np.asarray(points)
+        if arr.ndim == 1:
+            result, _ = self.model.execute(float(arr[0]), float(arr[1]), float(arr[2]))
+            return result
+        if arr.ndim == 2 and arr.shape[1] == 3:
+            z1 = np.zeros(arr.shape[0], dtype=float)
+            for i in range(arr.shape[0]):
+                result, _ = self.model.execute(
+                    float(arr[i, 0]), float(arr[i, 1]), float(arr[i, 2])
+                )
+                z1[i] = result
+            return z1
+        raise ValueError("预测点坐标必须是3列：[x, y, z] 或形状 (M, 3)")
+
+    def loss(self, data, res):
+        """计算损失函数"""
+        return ErrorMetrics.mse(data, res)
+
+    def add_params(self, params: dict):
+        """添加变差函数参数"""
+        self.params = params

flkit/alg/inter/LossFuncs.py

@@ -0,0 +1,164 @@
+"""
+损失函数
+提供常用的损失函数计算方法，如均方误差(MSE)、均方根误差(RMSE)、平均绝对误差(MAE)和平均相对误差(RE)。
+"""
+
+import numpy as np
+from typing import Union, List
+
+
+class ErrorMetrics:
+    """
+    常用误差计算工具类（静态方法）
+    支持输入类型：列表、NumPy数组等可迭代对象
+    """
+
+    @staticmethod
+    def _convert_to_array(data: Union[List, np.ndarray]) -> np.ndarray:
+        """将输入数据统一转换为NumPy数组"""
+        if not isinstance(data, np.ndarray):
+            data = np.array(data)
+        return data.astype(float)
+
+    @staticmethod
+    def _validate_input_length(data: np.ndarray, pred: np.ndarray):
+        """检查输入数据长度一致性"""
+        if len(data) != len(pred):
+            raise ValueError("输入数据长度不一致")
+
+    @staticmethod
+    def mse(data: Union[List, np.ndarray], pred: Union[List, np.ndarray]) -> float:
+        """
+        计算均方误差(Mean Squared Error)
+        公式: MSE = 1/n * Σ(y_true - y_pred)^2
+        """
+        y_true = ErrorMetrics._convert_to_array(data)
+        y_pred = ErrorMetrics._convert_to_array(pred)
+        if len(y_true) != len(y_pred):
+            raise ValueError("输入数据长度不一致")
+        return np.mean((y_true - y_pred) ** 2)
+
+    @staticmethod
+    def rmse(data: Union[List, np.ndarray], pred: Union[List, np.ndarray]) -> float:
+        """
+        计算均方根误差(Root Mean Squared Error)
+        公式: RMSE = sqrt(MSE)
+        """
+        mse = ErrorMetrics.mse(data, pred)
+        return np.sqrt(mse)
+
+    @staticmethod
+    def mae(data: Union[List, np.ndarray], pred: Union[List, np.ndarray]) -> float:
+        """
+        计算平均绝对误差(Mean Absolute Error)
+        公式: MAE = 1/n * Σ|y_true - y_pred|
+        """
+        y_true = ErrorMetrics._convert_to_array(data)
+        y_pred = ErrorMetrics._convert_to_array(pred)
+        if len(y_true) != len(y_pred):
+            raise ValueError("输入数据长度不一致")
+        return np.mean(np.abs(y_true - y_pred))
+
+    @staticmethod
+    def relative_error(
+        data: Union[List, np.ndarray], pred: Union[List, np.ndarray]
+    ) -> float:
+        """
+        计算平均相对误差(Relative Error)
+        公式: RE = 1/n * Σ(|y_true - y_pred| / |y_true|)
+        """
+        y_true = ErrorMetrics._convert_to_array(data)
+        y_pred = ErrorMetrics._convert_to_array(pred)
+        if len(y_true) != len(y_pred):
+            raise ValueError("输入数据长度不一致")
+        if np.any(y_true == 0):
+            raise ValueError("真实值包含0，无法计算相对误差")
+        return np.mean(np.abs((y_true - y_pred) / y_true))
+
+    @staticmethod
+    def r2_score(data: Union[List, np.ndarray], pred: Union[List, np.ndarray]) -> float:
+        """
+        计算R平方决定系数(R-squared)
+        公式: R² = 1 - (Σ(y_true - y_pred)^2 / Σ(y_true - y_mean)^2)
+        """
+        y_true = ErrorMetrics._convert_to_array(data)
+        y_pred = ErrorMetrics._convert_to_array(pred)
+        if len(y_true) != len(y_pred):
+            raise ValueError("输入数据长度不一致")
+        ss_res = np.sum((y_true - y_pred) ** 2)
+        ss_tot = np.sum((y_true - np.mean(y_true)) ** 2)
+        return 1 - (ss_res / ss_tot)
+
+    @staticmethod
+    def cross_entropy(
+        data: Union[List, np.ndarray],
+        pred: Union[List, np.ndarray],
+        epsilon: float = 1e-12,
+    ) -> float:
+        """
+        计算交叉熵损失(Cross-Entropy Loss)
+        适用于分类任务的概率输出
+        公式: CE = -Σ[y_true * log(y_pred) + (1-y_true)*log(1-y_pred)]
+        """
+        y_true = ErrorMetrics._convert_to_array(data)
+        y_pred = ErrorMetrics._convert_to_array(pred)
+        if len(y_true) != len(y_pred):
+            raise ValueError("输入数据长度不一致")
+        y_pred = np.clip(y_pred, epsilon, 1.0 - epsilon)
+        return -np.sum(
+            y_true * np.log(y_pred) + (1 - y_true) * np.log(1 - y_pred)
+        ) / len(y_true)
+
+    @staticmethod
+    def nrmse(
+        data: Union[List, np.ndarray],
+        pred: Union[List, np.ndarray],
+        normalization: str = "range",
+    ) -> float:
+        """
+        归一化均方根误差（Normalized RMSE）
+
+        参数:
+            normalization: 归一化方法，可选 'range'（最大值-最小值）或 'std'（标准差）[2,12](@ref)
+        """
+        y_true = ErrorMetrics._convert_to_array(data)
+        y_pred = ErrorMetrics._convert_to_array(pred)
+        ErrorMetrics._validate_input_length(y_true, y_pred)
+
+        rmse = ErrorMetrics.rmse(y_true, y_pred)
+
+        if normalization == "range":
+            norm_factor = np.max(y_true) - np.min(y_true)
+            if norm_factor == 0:
+                raise ValueError("数据范围为零，无法使用range归一化")
+        elif normalization == "std":
+            norm_factor = np.std(y_true)
+            if norm_factor == 0:
+                raise ValueError("数据标准差为零，无法使用std归一化")
+        else:
+            raise ValueError("归一化方法仅支持 'range' 或 'std'")
+
+        return rmse / norm_factor
+
+    @staticmethod
+    def peak_error(
+        data: Union[List, np.ndarray], pred: Union[List, np.ndarray], mode: str = "max"
+    ) -> float:
+        """
+        极值误差（Peak Error）
+
+        参数:
+            mode: 计算模式，可选 'max'（最大绝对误差）或 'min'（最小绝对误差）[11](@ref)
+        """
+        y_true = ErrorMetrics._convert_to_array(data)
+        y_pred = ErrorMetrics._convert_to_array(pred)
+        ErrorMetrics._validate_input_length(y_true, y_pred)
+
+        abs_errors = np.abs(y_true - y_pred)
+
+        if mode == "max":
+            return np.max(abs_errors)
+        elif mode == "min":
+            return np.min(abs_errors)
+        else:
+            raise ValueError("模式仅支持 'max' 或 'min'")

flkit/alg/inter/__init__.py

@@ -0,0 +1,178 @@
+"""
+插值方法
+
+- IDW: 反距离加权插值
+- 最近邻插值
+- RBF: 径向基函数插值
+- 三线性插值
+- 普通克里金插值
+- 优化克里金插值
+"""
+
+from .idw import IDW2D, IDW3D, IDW
+
+from .nearest_neighbor import (
+    NearestNeighbor2D,
+    NearestNeighbor3D,
+    KNearestNeighbor,
+)
+
+from .rbf import RBF2D, RBF3D
+
+from .trilinear import (
+    Trilinear3D,
+    BilinearInterpolator,
+    LinearInterpolator,
+)
+
+from .Kriging import Kriging2D, Kriging3D, Kriging3DUn
+
+from .midw import IDW as MIDW, IDWOpm, IDWOpm3D
+
+from .KrigingM import KrigingOpm, KrigingOpm3D
+
+INTER_METHODS = [
+    {
+        "name": "midw",
+        "desc": "反距离加权插值",
+    },
+    {
+        "name": "idw",
+        "desc": "反距离权重插值",
+    },
+    {
+        "name": "idw_m",
+        "desc": "优化反距离权重插值",
+    },
+    {
+        "name": "kriging",
+        "desc": "普通克里金插值",
+    },
+    {
+        "name": "kriging_m",
+        "desc": "优化克里金插值",
+    },
+    {
+        "name": "rbf",
+        "desc": "径向基函数插值",
+    },
+    {
+        "name": "nearest",
+        "desc": "最近邻插值",
+    },
+    {
+        "name": "knearest",
+        "desc": "K最近邻插值",
+    },
+    {
+        "name": "linear",
+        "desc": "线性插值",
+    },
+    {
+        "name": "bilinear",
+        "desc": "双线性插值",
+    },
+    {
+        "name": "trilinear",
+        "desc": "三线性插值",
+    },
+]
+
+# region 插值器
+def make_interpolator(method: str, dim: int):
+    """工厂：根据方法名和维度返回插值器实例"""
+    if method == "midw":
+        return IDW3D() if dim == 3 else IDW2D()
+
+    # IDW (反距离权重插值)
+    if method == "idw":
+        return IDW3D() if dim == 3 else IDW2D()
+
+    if method == "idw_m":
+        print("IDW-MT")
+        return IDWOpm3D() if dim == 3 else IDWOpm()
+
+    # Kriging (克里金插值)
+    if method == "kriging":
+        return Kriging3D() if dim == 3 else Kriging2D()
+
+    if method == "kriging_m":
+        return KrigingOpm3D() if dim == 3 else KrigingOpm()
+
+    # RBF (径向基函数插值)
+    if method == "rbf":
+        return RBF3D() if dim == 3 else RBF2D()
+
+    # 最近邻插值
+    if method == "nearest":
+        return NearestNeighbor3D() if dim == 3 else NearestNeighbor2D()
+
+    # K最近邻插值
+    if method == "knearest":
+        return KNearestNeighbor()
+
+    # 线性插值系列
+    if method == "linear":
+        if dim == 1:
+            return LinearInterpolator()
+        elif dim == 2:
+            return BilinearInterpolator()
+        elif dim == 3:
+            return Trilinear3D()
+        else:
+            raise ValueError(f"线性插值不支持 {dim} 维")
+
+    # 双线性插值 (2D专用)
+    if method == "bilinear":
+        if dim != 2:
+            raise ValueError("双线性插值只支持2D数据")
+        return BilinearInterpolator()
+
+    # 三线性插值 (3D专用)
+    if method == "trilinear":
+        if dim != 3:
+            raise ValueError("三线性插值只支持3D数据")
+        return Trilinear3D()
+
+    # 可用的方法列表
+    available_methods = [
+        "idw",
+        "idw_m",
+        "kriging",
+        "kriging_m",
+        "rbf",
+        "nearest",
+        "knearest",
+        "linear",
+        "bilinear",
+        "trilinear",
+    ]
+
+    raise ValueError(
+        f"不支持的方法: {method}。当前可用的方法: {', '.join(available_methods)}"
+    )
+
+
+# endregion 插值器
+
+__all__ = [
+    "IDW2D",
+    "IDW3D",
+    "IDW",
+    "NearestNeighbor2D",
+    "NearestNeighbor3D",
+    "KNearestNeighbor",
+    "RBF2D",
+    "RBF3D",
+    "Trilinear3D",
+    "BilinearInterpolator",
+    "LinearInterpolator",
+    "Kriging2D",
+    "Kriging3D",
+    "Kriging3DUn",
+    "MIDW",
+    "IDWOpm",
+    "IDWOpm3D",
+    "KrigingOpm",
+    "KrigingOpm3D",
+]