algobench-sdk 2.0.2__tar.gz → 2.0.4__tar.gz

{algobench_sdk-2.0.2 → algobench_sdk-2.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: algobench-sdk
-Version: 2.0.2
+Version: 2.0.4
 Summary: AlgoBench - 算法基准测试分析工具的 Python SDK 与 CLI
 Author: DuanxiangLiu
 License-Expression: AGPL-3.0-only

{algobench_sdk-2.0.2 → algobench_sdk-2.0.4}/algobench/__init__.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-__version__ = "2.0.2"
+__version__ = "2.0.4"
 
 from algobench.api import analyze, compute_statistics_only as compute_statistics
 from algobench.models import (

algobench_sdk-2.0.4/algobench/optimization/__init__.py

@@ -0,0 +1,16 @@
+"""AlgoBench optimization module - parameter optimization algorithms."""
+
+from .knee_point import detect_knee_point
+from .feature_importance import compute_feature_importance, get_overall_param_ranking
+from .decision_tree import extract_decision_rules, format_rule_conditions
+from .response_surface import fit_response_surface, select_top_params
+
+__all__ = [
+    'detect_knee_point',
+    'compute_feature_importance',
+    'get_overall_param_ranking',
+    'extract_decision_rules',
+    'format_rule_conditions',
+    'fit_response_surface',
+    'select_top_params',
+]

algobench_sdk-2.0.4/algobench/optimization/decision_tree.py

@@ -0,0 +1,365 @@
+"""决策树规则提取（Decision Tree Rule Extraction）。
+
+使用简单 CART（Classification And Regression Tree）算法，
+从帕雷托前沿成员中提取参数规则。
+
+方法：
+1. 将每个数据点标记为 is_frontier (true/false)
+2. 用 Gini 不纯度作为分裂准则训练决策树
+3. 从根到每个叶节点提取规则路径
+4. 每条规则标注覆盖样本数、前沿概率
+
+限制：
+- 最大深度：3（避免过拟合）
+- 叶节点最少样本数：5
+- 仅支持数值型参数
+
+对应 JS: src/services/optimization/decisionTree.js
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Any
+
+
+def gini_impurity(samples: list[dict[str, Any]]) -> float:
+    """计算 Gini 不纯度。
+
+    Args:
+        samples: 样本数组，每个样本含 is_frontier
+
+    Returns:
+        Gini 不纯度（0=纯，0.5=最不纯）
+    """
+    if len(samples) == 0:
+        return 0
+    front_count = sum(1 for s in samples if s["is_frontier"])
+    back_count = len(samples) - front_count
+    p_front = front_count / len(samples)
+    p_back = back_count / len(samples)
+    return 1 - p_front * p_front - p_back * p_back
+
+
+def _is_valid_number(v: Any) -> bool:
+    """判断值是否为有效数字（非 None、非 NaN）。"""
+    if v is None:
+        return False
+    try:
+        n = float(v)
+    except (TypeError, ValueError):
+        return False
+    return not math.isnan(n)
+
+
+def find_best_split_for_param(
+    samples: list[dict[str, Any]], param: str
+) -> dict[str, Any] | None:
+    """找到最佳分裂点（单个参数）。
+
+    Args:
+        samples: 样本数组
+        param: 参数名
+
+    Returns:
+        { threshold, gini, left_samples, right_samples } 或 None
+    """
+    if len(samples) < 2:
+        return None
+
+    # 提取该参数的所有值并排序
+    values = sorted(
+        float(s["params"][param])
+        for s in samples
+        if _is_valid_number(s["params"].get(param))
+    )
+
+    if len(values) < 2:
+        return None
+
+    # 候选分裂点：相邻值的中点
+    candidates: list[float] = []
+    for i in range(len(values) - 1):
+        if values[i] != values[i + 1]:
+            candidates.append((values[i] + values[i + 1]) / 2)
+
+    if len(candidates) == 0:
+        return None
+
+    best_split: dict[str, Any] | None = None
+    best_gini = float("inf")
+
+    for threshold in candidates:
+        left = [s for s in samples if float(s["params"][param]) <= threshold]
+        right = [s for s in samples if float(s["params"][param]) > threshold]
+
+        if len(left) == 0 or len(right) == 0:
+            continue
+
+        # 加权 Gini
+        gini = (
+            len(left) * gini_impurity(left) + len(right) * gini_impurity(right)
+        ) / len(samples)
+
+        if gini < best_gini:
+            best_gini = gini
+            best_split = {
+                "threshold": threshold,
+                "gini": gini,
+                "left_samples": left,
+                "right_samples": right,
+            }
+
+    return best_split
+
+
+def find_best_split(
+    samples: list[dict[str, Any]], param_columns: list[str]
+) -> dict[str, Any] | None:
+    """找到所有参数中的最佳分裂。
+
+    Args:
+        samples: 样本数组
+        param_columns: 参数列名
+
+    Returns:
+        { param, threshold, gini, left_samples, right_samples } 或 None
+    """
+    best: dict[str, Any] | None = None
+
+    for param in param_columns:
+        split = find_best_split_for_param(samples, param)
+        if split is not None and (best is None or split["gini"] < best["gini"]):
+            best = {**split, "param": param}
+
+    return best
+
+
+def build_tree(
+    samples: list[dict[str, Any]],
+    param_columns: list[str],
+    depth: int,
+    max_depth: int,
+    min_samples_leaf: int,
+    conditions: list[dict[str, Any]],
+) -> list[dict[str, Any]]:
+    """递归构建决策树。
+
+    Args:
+        samples: 当前节点的样本
+        param_columns: 参数列名
+        depth: 当前深度
+        max_depth: 最大深度
+        min_samples_leaf: 叶节点最少样本数
+        conditions: 从根到当前节点的条件路径
+
+    Returns:
+        叶节点列表（每个叶节点是一个规则）
+    """
+    # 终止条件 1：样本太少
+    if len(samples) < min_samples_leaf * 2:
+        return [{"conditions": list(conditions), "samples": samples}]
+
+    # 终止条件 2：达到最大深度
+    if depth >= max_depth:
+        return [{"conditions": list(conditions), "samples": samples}]
+
+    # 终止条件 3：节点已纯（全是前沿或全非前沿）
+    front_count = sum(1 for s in samples if s["is_frontier"])
+    if front_count == 0 or front_count == len(samples):
+        return [{"conditions": list(conditions), "samples": samples}]
+
+    # 寻找最佳分裂
+    split = find_best_split(samples, param_columns)
+    if (
+        split is None
+        or len(split["left_samples"]) < min_samples_leaf
+        or len(split["right_samples"]) < min_samples_leaf
+    ):
+        return [{"conditions": list(conditions), "samples": samples}]
+
+    # 递归分裂
+    left_conditions = list(conditions) + [
+        {"param": split["param"], "op": "<=", "value": split["threshold"]}
+    ]
+    right_conditions = list(conditions) + [
+        {"param": split["param"], "op": ">", "value": split["threshold"]}
+    ]
+
+    left_leaves = build_tree(
+        split["left_samples"],
+        param_columns,
+        depth + 1,
+        max_depth,
+        min_samples_leaf,
+        left_conditions,
+    )
+    right_leaves = build_tree(
+        split["right_samples"],
+        param_columns,
+        depth + 1,
+        max_depth,
+        min_samples_leaf,
+        right_conditions,
+    )
+
+    return left_leaves + right_leaves
+
+
+def _to_number(v: Any) -> float | None:
+    """将值转为数字，无法转换或为 NaN 时返回 None。"""
+    if v is None:
+        return None
+    try:
+        n = float(v)
+    except (TypeError, ValueError):
+        return None
+    if math.isnan(n):
+        return None
+    return n
+
+
+def extract_decision_rules(
+    parsed_data: list[dict[str, Any]] | None,
+    param_columns: list[str] | None,
+    frontier_case_names: set[str] | None,
+    options: dict[str, Any] | None = None,
+) -> list[dict[str, Any]]:
+    """提取决策规则。
+
+    Args:
+        parsed_data: 解析后的数据（含 raw、meta、Case）
+        param_columns: 参数列名
+        frontier_case_names: 前沿点的 case 名集合
+        options: 选项
+            - max_depth: 最大树深度，默认 3
+            - min_samples_leaf: 叶节点最少样本数，默认 5
+            - min_frontier_prob: 最小前沿概率（低于此值视为负向规则），默认 0.1
+            - selected_cases: 选中的 case（完整参数化名），空表示全部
+
+    Returns:
+        规则列表 [{ conditions, samples, frontier_prob, is_positive,
+                  front_count, total_count }]
+    """
+    if (
+        not parsed_data
+        or not param_columns
+        or not frontier_case_names
+        or len(param_columns) == 0
+    ):
+        return []
+
+    opts = options or {}
+    max_depth = opts.get("max_depth", 3)
+    min_samples_leaf = opts.get("min_samples_leaf", 5)
+    selected_cases = opts.get("selected_cases")
+
+    # 过滤数据
+    filtered = parsed_data
+    if selected_cases and len(selected_cases) > 0:
+        filtered = [d for d in parsed_data if d.get("Case") in selected_cases]
+
+    # 构建样本数组
+    samples: list[dict[str, Any]] = []
+    for d in filtered:
+        meta = d.get("meta") or {}
+        params: dict[str, float] = {}
+        has_all_params = True
+        for col in param_columns:
+            v = meta.get(col)
+            n = _to_number(v)
+            if n is None:
+                has_all_params = False
+            else:
+                params[col] = n
+
+        if not has_all_params:
+            continue
+
+        case_name = d.get("Case")
+        samples.append(
+            {
+                "case_name": case_name,
+                "params": params,
+                "is_frontier": case_name in frontier_case_names,
+            }
+        )
+
+    if len(samples) < min_samples_leaf * 2:
+        return []
+
+    # 构建决策树
+    leaves = build_tree(
+        samples, param_columns, 0, max_depth, min_samples_leaf, []
+    )
+
+    # 转换为规则
+    rules: list[dict[str, Any]] = []
+    for leaf in leaves:
+        total_count = len(leaf["samples"])
+        front_count = sum(1 for s in leaf["samples"] if s["is_frontier"])
+        frontier_prob = front_count / total_count if total_count > 0 else 0
+
+        rules.append(
+            {
+                "conditions": leaf["conditions"],
+                "samples": leaf["samples"],
+                "total_count": total_count,
+                "front_count": front_count,
+                "frontier_prob": frontier_prob,
+                "is_positive": frontier_prob >= 0.5,
+            }
+        )
+
+    rules = [rule for rule in rules if rule["total_count"] > 0]
+
+    # 按前沿概率降序排序（正向规则优先）
+    rules.sort(key=lambda r: r["frontier_prob"], reverse=True)
+
+    return rules
+
+
+def _format_number(v: float) -> str:
+    """简单的数字格式化（避免依赖外部 utils）。"""
+    if v is None or (isinstance(v, float) and math.isnan(v)):
+        return "-"
+    abs_v = abs(v)
+    if abs_v >= 1000:
+        return f"{v:.0f}"
+    if abs_v >= 1:
+        return f"{v:.3f}"
+    if abs_v >= 0.01:
+        return f"{v:.4f}"
+    return f"{v:.2e}"
+
+
+def format_rule_conditions(conditions: list[dict[str, Any]] | None) -> str:
+    """格式化规则条件为可读字符串。
+
+    Args:
+        conditions: 条件数组 [{ param, op, value }]
+
+    Returns:
+        格式化的条件字符串，如 "lr ≤ 0.15 AND momentum > 0.85"
+    """
+    if not conditions or len(conditions) == 0:
+        return "无条件（全部样本）"
+
+    parts: list[str] = []
+    for c in conditions:
+        param_label = c["param"]
+        if param_label.startswith("p_"):
+            param_label = param_label[2:]
+        value = c["value"]
+        # 对应 JS Number.isInteger：int 或值为整数的 float 都视为整数
+        is_integer = isinstance(value, int) or (
+            isinstance(value, float) and value.is_integer()
+        )
+        if is_integer:
+            value_str = str(int(value))
+        else:
+            value_str = _format_number(value)
+        op = "≤" if c["op"] == "<=" else ">"
+        parts.append(f"{param_label} {op} {value_str}")
+
+    return " AND ".join(parts)

algobench_sdk-2.0.4/algobench/optimization/feature_importance.py

@@ -0,0 +1,373 @@
+"""参数重要性分析（Feature Importance）。
+
+使用多元线性回归的标准化系数来衡量各参数对指标值的影响程度。
+
+方法：
+1. 对参数列做 z-score 标准化（减均值除标准差）
+2. 构建回归模型：metric = β0 + β1·p1 + β2·p2 + ...
+3. 用最小二乘法求解：β = (XᵀX)⁻¹Xᵀy
+4. 标准化系数绝对值 = 参数重要性
+
+解读：
+- 系数为正：增大该参数 → 指标值增大
+- 系数为负：增大该参数 → 指标值减小
+- |系数|越大：该参数对指标影响越强
+- R² 越接近 1：模型拟合越好
+
+对应 JS: src/services/optimization/featureImportance.js
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Any
+
+
+def transpose(m: list[list[float]]) -> list[list[float]]:
+    """矩阵转置。
+
+    Args:
+        m: 矩阵
+
+    Returns:
+        转置矩阵
+    """
+    if not m or len(m) == 0:
+        return []
+    return [[row[j] for row in m] for j in range(len(m[0]))]
+
+
+def multiply(a: list[list[float]], b: list[list[float]]) -> list[list[float]]:
+    """矩阵乘法。
+
+    Args:
+        a: 矩阵 a (n×m)
+        b: 矩阵 b (m×p)
+
+    Returns:
+        结果矩阵 (n×p)
+    """
+    if not a or not b or len(a) == 0 or len(b) == 0:
+        return []
+    n = len(a)
+    m = len(b)
+    p = len(b[0])
+    result = [[0.0 for _ in range(p)] for _ in range(n)]
+    for i in range(n):
+        for k in range(m):
+            aik = a[i][k]
+            if aik == 0:
+                continue
+            for j in range(p):
+                result[i][j] += aik * b[k][j]
+    return result
+
+
+def inverse(m: list[list[float]]) -> list[list[float]] | None:
+    """矩阵求逆（高斯-约旦消元法）。
+
+    Args:
+        m: 方阵
+
+    Returns:
+        逆矩阵，奇异矩阵返回 None
+    """
+    n = len(m)
+    if n == 0 or len(m[0]) != n:
+        return None
+
+    # 构造增广矩阵 [m | I]
+    aug: list[list[float]] = []
+    for i, row in enumerate(m):
+        identity = [0.0] * n
+        identity[i] = 1.0
+        aug.append(list(row) + identity)
+
+    # 前向消元 + 后向消元（部分主元选取）
+    for col in range(n):
+        # 找到当前列绝对值最大的行
+        max_row = col
+        max_val = abs(aug[col][col])
+        for row in range(col + 1, n):
+            if abs(aug[row][col]) > max_val:
+                max_val = abs(aug[row][col])
+                max_row = row
+
+        if max_val < 1e-12:
+            return None  # 奇异矩阵
+
+        # 交换行
+        if max_row != col:
+            aug[col], aug[max_row] = aug[max_row], aug[col]
+
+        # 归一化主元行
+        pivot = aug[col][col]
+        for j in range(2 * n):
+            aug[col][j] /= pivot
+
+        # 消去其他行
+        for row in range(n):
+            if row == col:
+                continue
+            factor = aug[row][col]
+            if factor == 0:
+                continue
+            for j in range(2 * n):
+                aug[row][j] -= factor * aug[col][j]
+
+    # 提取逆矩阵
+    return [row[n:] for row in aug]
+
+
+def mean(arr: list[float]) -> float:
+    """计算均值。"""
+    if len(arr) == 0:
+        return 0
+    return sum(arr) / len(arr)
+
+
+def std(arr: list[float]) -> float:
+    """计算标准差（总体标准差，ddof=0）。"""
+    if len(arr) == 0:
+        return 0
+    m = mean(arr)
+    variance = sum((v - m) ** 2 for v in arr) / len(arr)
+    return math.sqrt(variance)
+
+
+def standardize(values: list[float]) -> list[float]:
+    """Z-score 标准化。
+
+    Args:
+        values: 数值列表
+
+    Returns:
+        标准化后的值（均值为 0，标准差为 1）
+    """
+    m = mean(values)
+    s = std(values)
+    if s < 1e-12:
+        return [0.0 for _ in values]  # 常量列
+    return [(v - m) / s for v in values]
+
+
+def linear_regression(
+    X: list[list[float]], y: list[float]
+) -> dict[str, Any] | None:
+    """计算单个指标的多元线性回归（最小二乘法）。
+
+    Args:
+        X: 设计矩阵 (n×(k+1))，第一列为 1（截距项），后续为标准化参数
+        y: 响应变量
+
+    Returns:
+        { coefficients, r_squared } 或 None
+    """
+    n = len(X)
+    if n == 0:
+        return None
+
+    Xt = transpose(X)
+    XtX = multiply(Xt, X)
+    XtX_inv = inverse(XtX)
+    if XtX_inv is None:
+        return None  # 奇异矩阵
+
+    # y 转为列向量
+    y_col = [[v] for v in y]
+    Xty = multiply(Xt, y_col)
+    beta = multiply(XtX_inv, Xty)
+
+    coefficients = [row[0] for row in beta]
+
+    # 计算 R²
+    y_mean = mean(y)
+    ss_total = 0.0
+    ss_residual = 0.0
+    for i in range(n):
+        y_pred = 0.0
+        for j in range(len(coefficients)):
+            y_pred += coefficients[j] * X[i][j]
+        ss_total += (y[i] - y_mean) ** 2
+        ss_residual += (y[i] - y_pred) ** 2
+    r_squared = 0 if ss_total < 1e-12 else 1 - ss_residual / ss_total
+
+    return {"coefficients": coefficients, "r_squared": r_squared}
+
+
+def _to_number(v: Any) -> float | None:
+    """将值转为数字，无法转换或为 NaN 时返回 None。"""
+    if v is None:
+        return None
+    try:
+        n = float(v)
+    except (TypeError, ValueError):
+        return None
+    if math.isnan(n):
+        return None
+    return n
+
+
+def compute_feature_importance(
+    parsed_data: list[dict[str, Any]] | None,
+    param_columns: list[str] | None,
+    metrics: list[str] | None,
+    algo: str | None,
+    selected_cases: set[str] | None = None,
+) -> dict[str, Any]:
+    """计算参数重要性。
+
+    Args:
+        parsed_data: 解析后的数据（含 raw、meta）
+        param_columns: 参数列名
+        metrics: 要分析的指标列表
+        algo: 算法名
+        selected_cases: 可选，选中的 case 名（完整参数化名），空表示全部
+
+    Returns:
+        { [metric]: { params, r_squared, sample_count } }
+    """
+    if not parsed_data or not param_columns or not metrics or not algo:
+        return {}
+
+    # 过滤数据
+    filtered = parsed_data
+    if selected_cases and len(selected_cases) > 0:
+        filtered = [d for d in parsed_data if d.get("Case") in selected_cases]
+
+    if len(filtered) < 2 or len(param_columns) == 0:
+        return {}
+
+    result: dict[str, Any] = {}
+
+    for metric in metrics:
+        # 收集样本：(参数值数组, 指标值)
+        samples: list[dict[str, Any]] = []
+        for d in filtered:
+            raw = d.get("raw") or {}
+            metric_raw = raw.get(metric) or {}
+            y = metric_raw.get(algo)
+            y_num = _to_number(y)
+            if y_num is None:
+                continue
+
+            meta = d.get("meta") or {}
+            params: list[float | None] = []
+            for col in param_columns:
+                v = meta.get(col)
+                n = _to_number(v)
+                params.append(n)
+
+            # 任意参数缺失则跳过
+            if any(p is None for p in params):
+                continue
+
+            samples.append({"params": params, "y": y_num})
+
+        if len(samples) < len(param_columns) + 1:
+            # 样本不足
+            result[metric] = {
+                "params": [
+                    {"name": name, "coef": 0, "importance": 0, "direction": "none"}
+                    for name in param_columns
+                ],
+                "r_squared": 0,
+                "sample_count": len(samples),
+                "error": "样本不足",
+            }
+            continue
+
+        # 标准化每个参数列
+        param_arrays = [
+            [s["params"][j] for s in samples] for j in range(len(param_columns))
+        ]
+        standardized_params = [standardize(col) for col in param_arrays]
+
+        # 构建设计矩阵 X：第一列 1（截距），后续为标准化参数
+        X: list[list[float]] = []
+        for i in range(len(samples)):
+            row = [1.0]
+            for j in range(len(param_columns)):
+                row.append(standardized_params[j][i])
+            X.append(row)
+
+        y = [s["y"] for s in samples]
+
+        regression = linear_regression(X, y)
+        if regression is None:
+            result[metric] = {
+                "params": [
+                    {"name": name, "coef": 0, "importance": 0, "direction": "none"}
+                    for name in param_columns
+                ],
+                "r_squared": 0,
+                "sample_count": len(samples),
+                "error": "矩阵奇异",
+            }
+            continue
+
+        # coefficients[0] 是截距，后续是各参数的标准化系数
+        coefficients = regression["coefficients"]
+        r_squared = regression["r_squared"]
+        params = []
+        for j, name in enumerate(param_columns):
+            coef = coefficients[j + 1]
+            params.append(
+                {
+                    "name": name,
+                    "coef": coef,
+                    "importance": abs(coef),
+                    "direction": (
+                        "positive" if coef > 0 else ("negative" if coef < 0 else "none")
+                    ),
+                }
+            )
+
+        # 按重要性降序排序
+        params.sort(key=lambda p: p["importance"], reverse=True)
+
+        result[metric] = {
+            "params": params,
+            "r_squared": max(0, min(1, r_squared)),
+            "sample_count": len(samples),
+        }
+
+    return result
+
+
+def get_overall_param_ranking(
+    importance_result: dict[str, Any] | None,
+) -> list[dict[str, Any]]:
+    """获取所有指标中最重要的参数排名（综合排名）。
+
+    Args:
+        importance_result: compute_feature_importance 的返回值
+
+    Returns:
+        [{ name, avg_importance, rank }] 按平均重要性降序
+    """
+    if not importance_result:
+        return []
+
+    param_stats: dict[str, dict[str, float]] = {}
+
+    for metric_data in importance_result.values():
+        if not metric_data or not metric_data.get("params"):
+            continue
+        for p in metric_data["params"]:
+            name = p["name"]
+            if name not in param_stats:
+                param_stats[name] = {"sum": 0.0, "count": 0}
+            param_stats[name]["sum"] += p["importance"]
+            param_stats[name]["count"] += 1
+
+    ranking = [
+        {"name": name, "avg_importance": stats["sum"] / stats["count"]}
+        for name, stats in param_stats.items()
+    ]
+
+    ranking.sort(key=lambda p: p["avg_importance"], reverse=True)
+    for i, p in enumerate(ranking):
+        p["rank"] = i + 1
+
+    return ranking

algobench_sdk-2.0.4/algobench/optimization/knee_point.py

@@ -0,0 +1,113 @@
+"""拐点检测（Knee Point Detection）。
+
+在帕雷托前沿上找到"拐点"——即在此点附近，某目标的轻微改进
+需要另一目标大幅退化。拐点通常是决策者偏好的自然折中解。
+
+方法：最大距离法
+1. 将前沿点按 X 排序
+2. 连接两个极端点（X 最小和 X 最大）成一条线
+3. 找到离这条线最远的前沿点 = knee point
+
+对应 JS: src/services/optimization/kneePoint.js
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Any
+
+
+def point_to_line_distance(
+    px: float,
+    py: float,
+    x1: float,
+    y1: float,
+    x2: float,
+    y2: float,
+) -> float:
+    """计算点到线段的垂直距离。
+
+    Args:
+        px: 点 X
+        py: 点 Y
+        x1: 线段起点 X
+        y1: 线段起点 Y
+        x2: 线段终点 X
+        y2: 线段终点 Y
+
+    Returns:
+        垂直距离
+    """
+    dx = x2 - x1
+    dy = y2 - y1
+    length_sq = dx * dx + dy * dy
+    if length_sq == 0:
+        # 线段退化为点
+        ddx = px - x1
+        ddy = py - y1
+        return math.sqrt(ddx * ddx + ddy * ddy)
+    # 垂直距离 = |(y2-y1)*x0 - (x2-x1)*y0 + x2*y1 - y2*x1| / sqrt((y2-y1)^2 + (x2-x1)^2)
+    numerator = abs(dy * px - dx * py + x2 * y1 - y2 * x1)
+    return numerator / math.sqrt(length_sq)
+
+
+def detect_knee_point(
+    frontier_points: list[dict[str, Any]] | None,
+    options: dict[str, Any] | None = None,
+) -> dict[str, Any] | None:
+    """检测帕雷托前沿的拐点。
+
+    Args:
+        frontier_points: 前沿点数组，每个点包含 { x, y, caseName, raw, algo }
+        options: 选项
+            - x_reversed: X 轴是否反转（higher is better）
+            - y_reversed: Y 轴是否反转（higher is better）
+
+    Returns:
+        拐点信息 { point, index, distance, extremes, sorted_frontier } 或 None
+    """
+    if not frontier_points or len(frontier_points) < 3:
+        return None
+
+    opts = options or {}
+    x_reversed = opts.get("x_reversed", False)
+    # y_reversed 在 JS 中存在但未影响本算法逻辑，保持参数一致性
+    # y_reversed = opts.get("y_reversed", False)
+
+    # 按 X 排序（考虑方向：如果反转，则降序）
+    sorted_points = sorted(
+        frontier_points,
+        key=lambda p: p["x"],
+        reverse=x_reversed,
+    )
+
+    # 两个极端点
+    first = sorted_points[0]
+    last = sorted_points[-1]
+
+    # 计算每个点到极端点连线的距离
+    max_distance = -1.0
+    knee_index = -1
+    knee_point = None
+
+    for i, p in enumerate(sorted_points):
+        dist = point_to_line_distance(
+            p["x"], p["y"], first["x"], first["y"], last["x"], last["y"]
+        )
+        if dist > max_distance:
+            max_distance = dist
+            knee_index = i
+            knee_point = p
+
+    if not knee_point or max_distance <= 0:
+        return None
+
+    return {
+        "point": knee_point,
+        "index": knee_index,
+        "distance": max_distance,
+        # 前沿的两端点信息
+        "extremes": {"first": first, "last": last},
+        # 排序后的前沿（用于参考）
+        "sorted_frontier": sorted_points,
+    }

algobench_sdk-2.0.4/algobench/optimization/response_surface.py

@@ -0,0 +1,255 @@
+"""响应面方法（Response Surface Methodology, RSM）。
+
+通过二次多项式回归拟合参数与指标的关系曲面，
+并在参数空间中寻找最优参数组合。
+
+模型：y = β0 + β1·x1 + β2·x2 + β11·x1² + β22·x2² + β12·x1·x2
+
+步骤：
+1. 收集样本 (x1, x2, y)
+2. 构建设计矩阵并求解最小二乘
+3. 在参数空间生成网格，预测响应值
+4. 根据指标方向（lower/higher）寻找极值点
+
+对应 JS: src/services/optimization/responseSurface.js
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Any
+
+# 复用 feature_importance 中的矩阵运算和重要性分析（避免重复代码）
+from algobench.optimization.feature_importance import (
+    compute_feature_importance,
+    get_overall_param_ranking,
+    inverse,
+    multiply,
+    transpose,
+)
+
+
+def build_design_row(x1: float, x2: float) -> list[float]:
+    """构建二次响应面设计矩阵的一行。
+
+    Returns:
+        [1, x1, x2, x1², x2², x1·x2]
+    """
+    return [1.0, x1, x2, x1 * x1, x2 * x2, x1 * x2]
+
+
+def predict_response(
+    coefficients: list[float] | None, x1: float, x2: float
+) -> float:
+    """预测给定参数下的响应值。
+
+    Args:
+        coefficients: 回归系数 [β0, β1, β2, β11, β22, β12]
+        x1: 参数 A 值
+        x2: 参数 B 值
+
+    Returns:
+        预测值
+    """
+    if not coefficients or len(coefficients) < 6:
+        return 0
+    row = build_design_row(x1, x2)
+    y = 0.0
+    for i in range(len(coefficients)):
+        y += coefficients[i] * row[i]
+    return y
+
+
+def _to_number(v: Any) -> float | None:
+    """将值转为数字，无法转换或为 NaN 时返回 None。"""
+    if v is None:
+        return None
+    try:
+        n = float(v)
+    except (TypeError, ValueError):
+        return None
+    if math.isnan(n):
+        return None
+    return n
+
+
+def fit_response_surface(
+    parsed_data: list[dict[str, Any]] | None,
+    param_a: str | None,
+    param_b: str | None,
+    metric: str | None,
+    algo: str | None,
+    direction: str,
+    selected_cases: set[str] | None = None,
+) -> dict[str, Any] | None:
+    """拟合响应面。
+
+    Args:
+        parsed_data: 解析后的数据
+        param_a: 参数 A 列名
+        param_b: 参数 B 列名
+        metric: 指标名
+        algo: 算法名
+        direction: 指标方向 'lower' | 'higher'
+        selected_cases: 选中的 case
+
+    Returns:
+        { coefficients, r_squared, optimal_point, grid_data, param_ranges,
+          sample_count }
+    """
+    if not parsed_data or not param_a or not param_b or not metric or not algo:
+        return None
+
+    # 过滤数据
+    filtered = parsed_data
+    if selected_cases and len(selected_cases) > 0:
+        filtered = [d for d in parsed_data if d.get("Case") in selected_cases]
+
+    # 收集样本
+    samples: list[dict[str, float]] = []
+    for d in filtered:
+        raw = d.get("raw") or {}
+        metric_raw = raw.get(metric) or {}
+        y = _to_number(metric_raw.get(algo))
+        if y is None:
+            continue
+
+        meta = d.get("meta") or {}
+        x1 = _to_number(meta.get(param_a))
+        x2 = _to_number(meta.get(param_b))
+        if x1 is None or x2 is None:
+            continue
+
+        samples.append({"x1": x1, "x2": x2, "y": y})
+
+    # 二次模型有 6 个未知数，需 ≥ 7 个样本
+    if len(samples) < 7:
+        return {
+            "coefficients": None,
+            "r_squared": 0,
+            "optimal_point": None,
+            "grid_data": [],
+            "param_ranges": None,
+            "sample_count": len(samples),
+            "error": "样本不足（需 ≥ 7 个）",
+        }
+
+    # 构建设计矩阵 X 和响应向量 y
+    X = [build_design_row(s["x1"], s["x2"]) for s in samples]
+    y = [s["y"] for s in samples]
+
+    # 最小二乘：β = (XᵀX)⁻¹Xᵀy
+    Xt = transpose(X)
+    XtX = multiply(Xt, X)
+    XtX_inv = inverse(XtX)
+
+    if XtX_inv is None:
+        return {
+            "coefficients": None,
+            "r_squared": 0,
+            "optimal_point": None,
+            "grid_data": [],
+            "param_ranges": None,
+            "sample_count": len(samples),
+            "error": "矩阵奇异（参数可能共线性）",
+        }
+
+    y_col = [[v] for v in y]
+    Xty = multiply(Xt, y_col)
+    beta = multiply(XtX_inv, Xty)
+    coefficients = [row[0] for row in beta]
+
+    # 计算 R²
+    y_mean = sum(y) / len(y)
+    ss_total = 0.0
+    ss_residual = 0.0
+    for i in range(len(samples)):
+        y_pred = predict_response(coefficients, samples[i]["x1"], samples[i]["x2"])
+        ss_total += (y[i] - y_mean) ** 2
+        ss_residual += (y[i] - y_pred) ** 2
+    r_squared = 0 if ss_total < 1e-12 else 1 - ss_residual / ss_total
+
+    # 参数范围
+    x1_vals = [s["x1"] for s in samples]
+    x2_vals = [s["x2"] for s in samples]
+    x1_min = min(x1_vals)
+    x1_max = max(x1_vals)
+    x2_min = min(x2_vals)
+    x2_max = max(x2_vals)
+    param_ranges = {
+        "param_a": {"name": param_a, "min": x1_min, "max": x1_max},
+        "param_b": {"name": param_b, "min": x2_min, "max": x2_max},
+    }
+
+    # 生成网格数据（20×20）
+    grid_size = 20
+    grid_data: list[dict[str, float]] = []
+    x1_step = (x1_max - x1_min) / (grid_size - 1)
+    x2_step = (x2_max - x2_min) / (grid_size - 1)
+
+    optimal_point: dict[str, float] | None = None
+    optimal_value = float("-inf") if direction == "higher" else float("inf")
+
+    for i in range(grid_size):
+        for j in range(grid_size):
+            x1 = x1_min + i * x1_step
+            x2 = x2_min + j * x2_step
+            z = predict_response(coefficients, x1, x2)
+            grid_data.append({"x": x1, "y": x2, "z": z})
+
+            # 寻找极值
+            if direction == "higher":
+                if z > optimal_value:
+                    optimal_value = z
+                    optimal_point = {"x": x1, "y": x2, "value": z}
+            else:
+                if z < optimal_value:
+                    optimal_value = z
+                    optimal_point = {"x": x1, "y": x2, "value": z}
+
+    return {
+        "coefficients": coefficients,
+        "r_squared": max(0, min(1, r_squared)),
+        "optimal_point": optimal_point,
+        "grid_data": grid_data,
+        "param_ranges": param_ranges,
+        "sample_count": len(samples),
+    }
+
+
+def select_top_params(
+    parsed_data: list[dict[str, Any]] | None,
+    param_columns: list[str] | None,
+    metrics: list[str] | None,
+    algo: str | None,
+    selected_cases: set[str] | None = None,
+) -> dict[str, str] | None:
+    """自动选择最重要的 2 个参数。
+
+    Args:
+        parsed_data: 解析后的数据
+        param_columns: 参数列名
+        metrics: 指标列表
+        algo: 算法名
+        selected_cases: 选中的 case
+
+    Returns:
+        { param_a, param_b } 或 None
+    """
+    if not param_columns or len(param_columns) < 2:
+        return None
+
+    # 如果只有 2 个参数，直接使用
+    if len(param_columns) == 2:
+        return {"param_a": param_columns[0], "param_b": param_columns[1]}
+
+    # 使用 feature_importance 计算重要性排名
+    importance = compute_feature_importance(
+        parsed_data, param_columns, metrics, algo, selected_cases
+    )
+    ranking = get_overall_param_ranking(importance)
+
+    if len(ranking) < 2:
+        return None
+
+    return {"param_a": ranking[0]["name"], "param_b": ranking[1]["name"]}

{algobench_sdk-2.0.2 → algobench_sdk-2.0.4}/algobench_sdk.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: algobench-sdk
-Version: 2.0.2
+Version: 2.0.4
 Summary: AlgoBench - 算法基准测试分析工具的 Python SDK 与 CLI
 Author: DuanxiangLiu
 License-Expression: AGPL-3.0-only

{algobench_sdk-2.0.2 → algobench_sdk-2.0.4}/algobench_sdk.egg-info/SOURCES.txt

@@ -12,6 +12,11 @@ algobench/config/business.py
 algobench/config/metric_keywords.py
 algobench/config/metrics.py
 algobench/config/thresholds.py
+algobench/optimization/__init__.py
+algobench/optimization/decision_tree.py
+algobench/optimization/feature_importance.py
+algobench/optimization/knee_point.py
+algobench/optimization/response_surface.py
 algobench/parsers/__init__.py
 algobench/parsers/csv_parser.py
 algobench/stats/__init__.py

{algobench_sdk-2.0.2 → algobench_sdk-2.0.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "algobench-sdk"
-version = "2.0.2"
+version = "2.0.4"
 description = "AlgoBench - 算法基准测试分析工具的 Python SDK 与 CLI"
 readme = "README.md"
 license = "AGPL-3.0-only"