quantnodes 3.0.0__py3-none-any.whl

QuantNodes/core/tools.py

@@ -0,0 +1,333 @@
+# coding=utf-8
+"""
+工具函数
+
+替代 QuantStudio.Tools 中的工具函数
+"""
+
+import multiprocessing as mp
+import tempfile
+import uuid
+from typing import Any, Callable, Iterator, List, Optional, TypeVar, Union
+
+import pandas as pd
+
+T = TypeVar("T")
+
+
+def gen_available_name(base: str = "Temp", used_names: Optional[set] = None) -> str:
+    """
+    生成唯一可用的名称
+
+    Args:
+        base: 名称基础前缀
+        used_names: 已使用的名称集合
+
+    Returns:
+        唯一的名称字符串
+    """
+    used = used_names or set()
+    while True:
+        name = f"{base}_{uuid.uuid4().hex[:8]}"
+        if name not in used:
+            used.add(name)
+            return name
+
+
+def partition_list(data: List[T], n_parts: int) -> List[List[T]]:
+    """
+    将列表分割为 n 个大致相等的部分
+
+    Args:
+        data: 要分割的列表
+        n_parts: 分割数量
+
+    Returns:
+        分割后的子列表
+    """
+    if n_parts <= 0:
+        return [data]
+    if n_parts >= len(data):
+        return [[x] for x in data]
+
+    part_size = len(data) // n_parts
+    remainder = len(data) % n_parts
+
+    result = []
+    start = 0
+    for i in range(n_parts):
+        end = start + part_size + (1 if i < remainder else 0)
+        result.append(data[start:end])
+        start = end
+
+    return result
+
+
+def partition_list_moving_sampling(
+    data: List[Any],
+    n_parts: int,
+    step: Optional[int] = None,
+) -> List[List[Any]]:
+    """
+    将列表分割为 n 个部分，支持移动采样
+
+    Args:
+        data: 要分割的列表
+        n_parts: 分割数量
+        step: 采样步长（可选）
+
+    Returns:
+        分割后的子列表
+    """
+    if n_parts <= 0:
+        return [data]
+    if n_parts >= len(data):
+        return [[x] for x in data]
+
+    if step is None:
+        step = max(1, len(data) // n_parts)
+
+    result = []
+    for i in range(n_parts):
+        start = i * step
+        end = min(start + step + (len(data) % n_parts if i < len(data) % n_parts else 0), len(data))
+        if start < len(data):
+            result.append(data[start:end])
+        else:
+            result.append([])
+
+    return result
+
+
+def start_multi_process(
+    func: Callable,
+    args_list: List[tuple],
+    n_processes: Optional[int] = None,
+    daemon: bool = True,
+) -> List[Any]:
+    """
+    启动多进程执行任务
+
+    Args:
+        func: 要执行的函数
+        args_list: 参数列表，每个元素是一个 tuple
+        n_processes: 进程数，None 则使用 CPU 核心数
+        daemon: 是否守护进程
+
+    Returns:
+        结果列表
+    """
+    if n_processes is None:
+        n_processes = mp.cpu_count()
+
+    n_processes = min(n_processes, len(args_list)) if args_list else 1
+
+    if n_processes == 1:
+        return [func(*args) for args in args_list]
+
+    with mp.Pool(processes=n_processes, maxtasksperchild=1) as pool:
+        results = pool.starmap(func, args_list)
+
+    return results
+
+
+def fill_na_by_lookback(
+    data: Union[pd.DataFrame, pd.Series],
+    lookback: int = 1,
+    method: str = "ffill",
+) -> Union[pd.DataFrame, pd.Series]:
+    """
+    通过回溯填充 NaN 值
+
+    Args:
+        data: 数据 DataFrame 或 Series
+        lookback: 回溯期数
+        method: 填充方法，"ffill"（前向填充）或 "bfill"（后向填充）
+
+    Returns:
+        填充后的数据
+    """
+    if lookback <= 0:
+        return data
+
+    if isinstance(data, pd.DataFrame):
+        result = data.copy()
+        for _ in range(lookback):
+            result = result.ffill()
+        return result
+    else:
+        result = data.copy()
+        for _ in range(lookback):
+            result = result.ffill()
+        return result
+
+
+def get_shelve_file_suffix() -> str:
+    """
+    获取 shelve 数据库文件后缀
+
+    Returns:
+        文件后缀字符串
+    """
+    return ".db"
+
+
+def compile_id_filter_str(
+    filter_str: str,
+    factor_names: List[str],
+) -> tuple:
+    """
+    测试并编译 ID 过滤字符串
+
+    Args:
+        filter_str: 过滤条件字符串
+        factor_names: 可用的因子名列表
+
+    Returns:
+        (编译后的字符串, 涉及的因子列表) 或 (None, None) 如果失败
+    """
+    if not filter_str:
+        return None, None
+
+    try:
+        valid_names = set(factor_names)
+        if "@" in filter_str:
+            factors = []
+            normalized = (
+                filter_str.replace("=", "==")
+                .replace(">", " > ")
+                .replace("<", " < ")
+                .replace("&", " & ")
+                .replace("|", " | ")
+            )
+            parts = normalized.split()
+            for part in parts:
+                part = part.strip()
+                if part.startswith("@") and part[1:] in valid_names:
+                    factors.append(part[1:])
+            return filter_str, list(set(factors))
+        return filter_str, []
+    except Exception:
+        return None, None
+
+
+def create_temp_dir(prefix: str = "quantnodes_") -> str:
+    """
+    创建临时目录
+
+    Args:
+        prefix: 目录名前缀
+
+    Returns:
+        临时目录路径
+    """
+    temp_dir = tempfile.mkdtemp(prefix=prefix)
+    return temp_dir
+
+
+def merge_data_frames(
+    dfs: List[pd.DataFrame],
+    how: str = "inner",
+    on: Optional[str] = None,
+    left_index: bool = False,
+    right_index: bool = False,
+) -> pd.DataFrame:
+    """
+    合并多个 DataFrame
+
+    Args:
+        dfs: DataFrame 列表
+        how: 合并方式 ("inner", "outer", "left", "right")
+        on: 合并键
+        left_index: 左侧使用索引
+        right_index: 右侧使用索引
+
+    Returns:
+        合并后的 DataFrame
+    """
+    if not dfs:
+        return pd.DataFrame()
+    if len(dfs) == 1:
+        return dfs[0]
+
+    result = dfs[0]
+    for df in dfs[1:]:
+        result = pd.merge(
+            result, df, how=how, on=on,
+            left_index=left_index, right_index=right_index,
+        )
+
+    return result
+
+
+def chunk_iterable(iterable: Iterator[T], chunk_size: int) -> Iterator[List[T]]:
+    """
+    将迭代器分块
+
+    Args:
+        iterable: 可迭代对象
+        chunk_size: 块大小
+
+    Yields:
+        块列表
+    """
+    chunk = []
+    for item in iterable:
+        chunk.append(item)
+        if len(chunk) >= chunk_size:
+            yield chunk
+            chunk = []
+    if chunk:
+        yield chunk
+
+
+__all__ = [
+    "gen_available_name",
+    "partition_list",
+    "partition_list_moving_sampling",
+    "start_multi_process",
+    "fill_na_by_lookback",
+    "get_shelve_file_suffix",
+    "compile_id_filter_str",
+    "create_temp_dir",
+    "merge_data_frames",
+    "chunk_iterable",
+    "timer",
+    "retry",
+]
+
+
+def timer(func):
+    """计时器装饰器"""
+    from functools import wraps
+    import time
+
+    @wraps(func)
+    def wrapper(*args, **kwargs):
+        start = time.time()
+        res = func(*args, **kwargs)
+        end = time.time()
+        print(f"{func.__name__} spend: {end - start:.4f}s")
+        return res
+
+    return wrapper
+
+
+def retry(max_attempts: int = 3, delay: float = 1.0):
+    """重试装饰器"""
+    from functools import wraps
+    import time
+
+    def decorator(func):
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            for attempt in range(max_attempts):
+                try:
+                    return func(*args, **kwargs)
+                except Exception:
+                    if attempt == max_attempts - 1:
+                        raise
+                    time.sleep(delay)
+            return None
+        return wrapper
+    return decorator

QuantNodes/core/trajectory/__init__.py

@@ -0,0 +1,25 @@
+"""TrajectoryPool — 演化轨迹池。
+
+公开 API:
+    - TrajectoryEntry (dataclass): 单条轨迹
+    - Operation (str Enum): 演化操作类型 (M1)
+    - TrajectoryPool (class): 池子 + CRUD + 过滤 + 谱系 + 双层持久化
+    - ParentSelector (class): 5 种选择策略
+    - SelectionStrategy (Enum): 5 种策略枚举
+    - children_of / lineage / descendants: 谱系工具函数
+"""
+from .entry import Operation, TrajectoryEntry
+from .pool import TrajectoryPool
+from .selector import ParentSelector, SelectionStrategy
+from .lineage import children_of, descendants, lineage
+
+__all__ = [
+    "TrajectoryEntry",
+    "Operation",
+    "TrajectoryPool",
+    "ParentSelector",
+    "SelectionStrategy",
+    "children_of",
+    "descendants",
+    "lineage",
+]

QuantNodes/core/trajectory/entry.py

@@ -0,0 +1,116 @@
+"""TrajectoryEntry — 单条演化轨迹。"""
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+from typing import Any
+
+import pandas as pd
+
+from ..constants import METRIC_KEYS as _METRIC_KEYS
+from ..feedback import FactorFeedback
+
+
+class Operation(str, Enum):
+    """M1: 演化操作类型 — 替代硬编码字符串 'original'/'mutation'/'crossover'。
+
+    str Enum 同时兼容 dataclass.field(default="original") 旧用法。
+    """
+    ORIGINAL = "original"
+    MUTATION = "mutation"
+    CROSSOVER = "crossover"
+
+
+@dataclass
+class TrajectoryEntry:
+    """单条演化轨迹 — QuantaAlpha `Trace.hist` 等价物。"""
+
+    entry_id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    round_idx: int = 0
+    operation: str = Operation.ORIGINAL  # M1: enum 默认值, 仍兼容 str
+    config_snapshot: dict = field(default_factory=dict)
+    context_subset: dict = field(default_factory=dict)
+    feedback: FactorFeedback | None = None
+    parent_ids: list[str] = field(default_factory=list)
+    metrics: dict = field(default_factory=dict)
+    timestamp: datetime = field(default_factory=datetime.now)
+
+    # ------------------------------------------------------------------
+    # Parquet 序列化 (元数据)
+    # ------------------------------------------------------------------
+
+    def to_parquet_row(self) -> dict:
+        """展平为单行 dict 供 Parquet 写入。"""
+        row = {
+            "entry_id": self.entry_id,
+            "round_idx": int(self.round_idx),
+            "operation": str(self.operation),
+            "parent_ids": ",".join(self.parent_ids),
+            "decision": bool(self.feedback.decision) if self.feedback else False,
+            "duration_ms": float(self.feedback.duration_ms) if self.feedback else 0.0,
+            "timestamp": self.timestamp.isoformat(),
+            "factor_name": str(self.feedback.factor_name) if self.feedback else "",
+            "summary": str(self.feedback.summary) if self.feedback else "",
+        }
+        for key in _METRIC_KEYS:
+            row[key] = self.metrics.get(key)
+        return row
+
+    # ------------------------------------------------------------------
+    # JSON 序列化 (完整记录)
+    # ------------------------------------------------------------------
+
+    def to_json_dict(self) -> dict:
+        """转为 JSON-safe dict。"""
+        return {
+            "entry_id": self.entry_id,
+            "round_idx": self.round_idx,
+            "operation": self.operation,
+            "config_snapshot": _jsonify(self.config_snapshot),
+            "context_subset": _jsonify(self.context_subset),
+            "feedback": self.feedback.to_dict() if self.feedback else None,
+            "parent_ids": list(self.parent_ids),
+            "metrics": _jsonify(self.metrics),
+            "timestamp": self.timestamp.isoformat(),
+        }
+
+    @classmethod
+    def from_json_dict(cls, d: dict) -> "TrajectoryEntry":
+        """从 JSON dict 还原。"""
+        return cls(
+            entry_id=d["entry_id"],
+            round_idx=int(d.get("round_idx", 0)),
+            operation=str(d.get("operation", "original")),
+            config_snapshot=d.get("config_snapshot", {}),
+            context_subset=d.get("context_subset", {}),
+            feedback=(
+                FactorFeedback.from_dict(d["feedback"])
+                if d.get("feedback") is not None
+                else None
+            ),
+            parent_ids=list(d.get("parent_ids", [])),
+            metrics=d.get("metrics", {}),
+            timestamp=datetime.fromisoformat(d["timestamp"]),
+        )
+
+
+def _jsonify(obj: Any) -> Any:
+    """把 pd.Timestamp / np.ndarray / datetime 等转为 JSON-safe 类型。"""
+    if isinstance(obj, dict):
+        return {k: _jsonify(v) for k, v in obj.items()}
+    if isinstance(obj, (list, tuple)):
+        return [_jsonify(v) for v in obj]
+    if isinstance(obj, datetime):
+        return obj.isoformat()
+    if isinstance(obj, pd.Timestamp):
+        return obj.isoformat()
+    if hasattr(obj, "isoformat"):
+        try:
+            return obj.isoformat()
+        except Exception:
+            return str(obj)
+    if isinstance(obj, (str, int, float, bool)) or obj is None:
+        return obj
+    return str(obj)

QuantNodes/core/trajectory/lineage.py

@@ -0,0 +1,67 @@
+"""谱系追踪: children_of + lineage (从原始到当前)。
+
+提供 stateless 工具函数, 接受 entries dict 或 list 操作。
+"""
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+
+from .entry import TrajectoryEntry
+
+
+def children_of(
+    entries: Mapping[str, TrajectoryEntry] | Iterable[TrajectoryEntry],
+    parent_id: str,
+) -> list[TrajectoryEntry]:
+    """返回指定父辈的所有子代。"""
+    items = entries.values() if isinstance(entries, Mapping) else entries
+    return [e for e in items if parent_id in e.parent_ids]
+
+
+def lineage(
+    entries: Mapping[str, TrajectoryEntry],
+    entry_id: str,
+) -> list[TrajectoryEntry]:
+    """返回完整谱系 (从原始到当前), 顺序: 最老 → 最新。
+
+    BFS 防环: 同一节点不重复访问, crossover 时只走第一个 parent。
+    """
+    if entry_id not in entries:
+        return []
+    chain: list[TrajectoryEntry] = []
+    current = entries[entry_id]
+    chain.append(current)
+    visited = {current.entry_id}
+    while current.parent_ids:
+        next_id = current.parent_ids[0]
+        if next_id in visited or next_id not in entries:
+            break
+        current = entries[next_id]
+        chain.append(current)
+        visited.add(current.entry_id)
+    chain.reverse()
+    return chain
+
+
+def descendants(
+    entries: Mapping[str, TrajectoryEntry],
+    entry_id: str,
+    max_depth: int | None = None,
+) -> list[TrajectoryEntry]:
+    """返回所有后代 (子代、孙代...), BFS。"""
+    if entry_id not in entries:
+        return []
+    seen: set[str] = {entry_id}
+    queue: list[tuple[TrajectoryEntry, int]] = [(entries[entry_id], 0)]
+    result: list[TrajectoryEntry] = []
+    while queue:
+        node, depth = queue.pop(0)
+        if max_depth is not None and depth >= max_depth:
+            continue
+        for child in children_of(entries, node.entry_id):
+            if child.entry_id in seen:
+                continue
+            seen.add(child.entry_id)
+            result.append(child)
+            queue.append((child, depth + 1))
+    return result