powerquant-cli 0.2.6__py3-none-any.whl

quant_core/app/factor/builtin/factor_recipe_catalog.py

@@ -0,0 +1,100 @@
+"""内置特征目录：配方只是候选规格，注册及入库必须经过显式发布。"""
+
+import hashlib
+import json
+from functools import lru_cache
+from pathlib import Path
+
+from quant_core.app.factor.computation.panel_evaluator import evaluate_panel
+from quant_core.app.factor.schema.factor_computation_schema import FactorComputationSpec
+from quant_core.app.factor.schema.factor_panel import FactorPanel
+from quant_core.app.factor.schema.factor_result_schema import PanelValues
+
+from .alpha101_recipe import ALPHA101_RECIPES
+from .alpha101_recipe import UNSUPPORTED_ALPHA101 as UNSUPPORTED_ALPHA101
+from .alpha158_recipe import ALPHA158_RECIPES
+
+REFERENCE_COMMIT = "fa5206fe63836f3f8cd1ebd7168fbd19a5e2ff09"
+RECIPES = {**ALPHA158_RECIPES, **ALPHA101_RECIPES}
+
+
+def run_recipe(name: str, panel: FactorPanel, expected_digest: str) -> PanelValues:
+    """按发布定义的实现摘要执行内置配方。"""
+    if expected_digest != implementation_digest():
+        raise ValueError("内置计算实现与发布定义摘要不一致，必须使用对应版本代码")
+    recipe, lookback, required = RECIPES[name]
+    return evaluate_panel(panel, recipe, lookback, required)
+
+
+@lru_cache(maxsize=1)
+def implementation_digest() -> str:
+    """固定算子和配方文件摘要，防止同一发布定义随代码升级静默漂移。"""
+    digest = hashlib.sha256()
+    for name in (
+        "computation/panel_expression.py",
+        "computation/universe_filter.py",
+        "computation/panel_evaluator.py",
+        "computation/python_factor_executor.py",
+        "computation/operators/time_series_operator.py",
+        "computation/operators/cross_section_operator.py",
+        "computation/operators/arithmetic_operator.py",
+        "builtin/alpha158_recipe.py",
+        "builtin/alpha101_recipe.py",
+        "builtin/factor_recipe_catalog.py",
+    ):
+        digest.update(name.encode())
+        digest.update(
+            (Path(__file__).parent.parent / name)
+            .read_text(encoding="utf-8")
+            .replace("\r\n", "\n")
+            .encode()
+        )
+    return digest.hexdigest()
+
+
+def recipe_specs(
+    family: str,
+    *,
+    universe_ref: str,
+    price_basis: str,
+    units: dict[str, str],
+    instrument_ids: tuple[str, ...] = (),
+) -> list[FactorComputationSpec]:
+    """将股票池政策、单位与价格口径绑定到不可变定义版本。"""
+    if family not in {"alpha158", "alpha101"} or not universe_ref or not price_basis:
+        raise ValueError("必须指定支持的特征集、历史股票池政策及价格口径")
+    contract = {"universe_ref": universe_ref, "price_basis": price_basis, "units": units}
+    implementation = implementation_digest()
+    version_payload = {"input_contract": contract, "implementation_digest": implementation}
+    digest = hashlib.sha256(json.dumps(version_payload, sort_keys=True).encode()).hexdigest()
+    specs = []
+    for name, (_, lookback, fields) in RECIPES.items():
+        if not name.startswith(family + "_"):
+            continue
+        if set(fields) - units.keys():
+            raise ValueError(f"特征 {name} 缺少输入单位声明")
+        specs.append(
+            FactorComputationSpec(
+                name=name,
+                version=f"vnpy-{REFERENCE_COMMIT[:12]}-{digest}",
+                description=f"{family} 固定参考版本配方；预热 {lookback} 期",
+                input_kind="panel",
+                inputs=["bar/1d", *fields],
+                lookback=lookback,
+                parameters={
+                    "input_contract": contract,
+                    "implementation_digest": implementation,
+                },
+                python_source=(
+                    "from quant_core.app.factor.builtin.factor_recipe_catalog import run_recipe\n\n"
+                    "def compute_panel(panel, parameters):\n"
+                    f"    return run_recipe({name!r}, panel, parameters['implementation_digest'])\n"
+                ),
+                metadata={
+                    "reference_commit": REFERENCE_COMMIT,
+                    "family": family,
+                    "universe_instruments": sorted(set(instrument_ids)),
+                },
+            )
+        )
+    return specs

quant_core/app/factor/computation/factor_batch_evaluator.py

@@ -0,0 +1,141 @@
+"""本地批量公式求值，共用基础字段与子表达式，不改变已有 Alpha 算子口径。"""
+
+import hashlib
+import json
+from dataclasses import asdict, dataclass
+from datetime import datetime
+from decimal import Decimal
+
+import polars as pl
+
+from quant_core.app.factor.computation.factor_expression import FactorExpression
+from quant_core.app.factor.computation.panel_expression import PanelExpression
+from quant_core.app.factor.schema.factor_panel import FactorPanel
+
+
+@dataclass(frozen=True)
+class FactorBatchResult:
+    """结果及输入、公式证据；本入口不持久化或发布因子。"""
+
+    values: dict[str, dict[tuple[datetime, str], Decimal | None]]
+    input_digest: str
+    definition_digest: str
+    lookback: int
+
+
+def execute_factors(
+    factors: dict[str, FactorExpression],
+    panel: FactorPanel,
+    *,
+    start: datetime,
+    end: datetime,
+    output_instruments: tuple[str, ...] | None = None,
+) -> FactorBatchResult:
+    """先在完整参与面板计算，再裁剪输出；缺少交易时间网格时拒绝压缩窗口。"""
+    if not factors or start.utcoffset() is None or end.utcoffset() is None or start > end:
+        raise ValueError("因子或输出时间范围非法")
+    fields = set().union(*(factor.required_fields for factor in factors.values()))
+    if not fields.issubset(panel.units):
+        raise ValueError(f"面板缺少字段: {sorted(fields - panel.units.keys())}")
+    rows = sorted(panel.rows, key=lambda row: (row.as_of, row.instrument_id))
+    instruments = sorted({row.instrument_id for row in rows})
+    timestamps = sorted({row.as_of for row in rows})
+    if not rows or len(rows) != len(instruments) * len(timestamps):
+        raise ValueError("面板必须保留完整日期×证券网格，缺失行情以空值表示")
+    if output_instruments is not None and not set(output_instruments).issubset(instruments):
+        raise ValueError("输出证券不属于参与计算的面板")
+    frame = pl.DataFrame(
+        {
+            "datetime": [row.as_of for row in rows],
+            "vt_symbol": [row.instrument_id for row in rows],
+            "eligible": [row.eligible for row in rows],
+            **{
+                field: [
+                    float(value) if (value := row.fields.get(field)) is not None else None
+                    for row in rows
+                ]
+                for field in fields
+            },
+        },
+        schema_overrides={field: pl.Float64 for field in fields},
+    )
+    memo: dict[FactorExpression, PanelExpression] = {}
+
+    def evaluate(node: FactorExpression) -> PanelExpression:
+        if node in memo:
+            return memo[node]
+        if node.operation == "field":
+            result = PanelExpression(frame.select("datetime", "vt_symbol", node.field))
+        elif node.operation == "constant":
+            result = PanelExpression(
+                frame.select("datetime", "vt_symbol").with_columns(pl.lit(node.value).alias("data"))
+            )
+        else:
+            arguments = [evaluate(argument) for argument in node.arguments]
+            left = arguments[0]
+            if node.operation in {"add", "sub", "mul", "div"}:
+                right = arguments[1]
+                result = {
+                    "add": PanelExpression.__add__,
+                    "sub": PanelExpression.__sub__,
+                    "mul": PanelExpression.__mul__,
+                    "div": PanelExpression.__truediv__,
+                }[node.operation](left, right)
+            else:
+                value = pl.col("data")
+                if node.operation == "ref":
+                    expression = value.shift(node.window).over("vt_symbol")
+                elif node.operation == "mean":
+                    expression = value.rolling_mean(node.window, min_samples=node.window).over(
+                        "vt_symbol"
+                    )
+                elif node.operation == "std":
+                    expression = value.rolling_std(
+                        node.window, min_samples=node.window, ddof=0
+                    ).over("vt_symbol")
+                elif node.operation == "rank":
+                    left = PanelExpression(
+                        left.df.with_columns(
+                            pl.when(frame["eligible"]).then(value).otherwise(None).alias("data")
+                        )
+                    )
+                    expression = value.rank(method="average").over("datetime") / value.count().over(
+                        "datetime"
+                    )
+                else:
+                    raise ValueError(f"不支持的算子: {node.operation}")
+                result = PanelExpression(
+                    left.df.select("datetime", "vt_symbol", expression.alias("data"))
+                )
+        result = PanelExpression(
+            result.df.with_columns(
+                pl.when(pl.col("data").is_finite())
+                .then(pl.col("data"))
+                .otherwise(None)
+                .alias("data")
+            )
+        )
+        memo[node] = result
+        return result
+
+    values = {}
+    allowed = set(output_instruments or instruments)
+    for name, factor in factors.items():
+        result = evaluate(factor)
+        values[name] = {
+            (row.as_of, row.instrument_id): Decimal(str(value))
+            if value is not None and row.eligible
+            else None
+            for row, value in zip(rows, result.df["data"], strict=True)
+            if start <= row.as_of <= end and row.instrument_id in allowed
+        }
+    return FactorBatchResult(
+        values=values,
+        input_digest=panel.input_digest,
+        definition_digest=hashlib.sha256(
+            json.dumps(
+                {key: asdict(value) for key, value in sorted(factors.items())}, sort_keys=True
+            ).encode()
+        ).hexdigest(),
+        lookback=max(factor.lookback for factor in factors.values()),
+    )

quant_core/app/factor/computation/factor_expression.py

@@ -0,0 +1,106 @@
+"""量价公式树：声明字段和组合窗口，计算阶段不访问外部数据。"""
+
+import math
+from dataclasses import dataclass
+from typing import Literal
+
+Operation = Literal["field", "constant", "add", "sub", "mul", "div", "ref", "mean", "std", "rank"]
+
+
+@dataclass(frozen=True)
+class FactorExpression:
+    """不可变公式；窗口长度包含当前行，复合窗口沿依赖链累加。"""
+
+    operation: Operation
+    arguments: tuple["FactorExpression", ...] = ()
+    field: str = ""
+    value: float = 0.0
+    window: int = 1
+
+    @property
+    def required_fields(self) -> frozenset[str]:
+        if self.operation == "field":
+            return frozenset({self.field})
+        return frozenset().union(*(argument.required_fields for argument in self.arguments))
+
+    @property
+    def lookback(self) -> int:
+        history = max((argument.lookback for argument in self.arguments), default=1)
+        if self.operation == "ref":
+            return history + self.window
+        if self.operation in {"mean", "std"}:
+            return history + self.window - 1
+        return history
+
+    def __add__(self, other: "FactorExpression | float") -> "FactorExpression":
+        return FactorExpression("add", (self, _expression(other)))
+
+    def __sub__(self, other: "FactorExpression | float") -> "FactorExpression":
+        return FactorExpression("sub", (self, _expression(other)))
+
+    def __mul__(self, other: "FactorExpression | float") -> "FactorExpression":
+        return FactorExpression("mul", (self, _expression(other)))
+
+    def __truediv__(self, other: "FactorExpression | float") -> "FactorExpression":
+        return FactorExpression("div", (self, _expression(other)))
+
+    def __radd__(self, other: float) -> "FactorExpression":
+        return _expression(other) + self
+
+    def __rsub__(self, other: float) -> "FactorExpression":
+        return _expression(other) - self
+
+    def __rmul__(self, other: float) -> "FactorExpression":
+        return _expression(other) * self
+
+    def __rtruediv__(self, other: float) -> "FactorExpression":
+        return _expression(other) / self
+
+    def __neg__(self) -> "FactorExpression":
+        return self * -1.0
+
+
+def _expression(value: FactorExpression | float) -> FactorExpression:
+    if isinstance(value, FactorExpression):
+        return value
+    if not isinstance(value, (float, int)) or not math.isfinite(value):
+        raise ValueError("公式常量必须为有限数值")
+    return FactorExpression("constant", value=float(value))
+
+
+def Factor(field: str) -> FactorExpression:
+    """引用输入面板字段；单位及可见性由面板契约校验。"""
+    if not field or not field.isidentifier():
+        raise ValueError("因子字段名非法")
+    return FactorExpression("field", field=field)
+
+
+def _window(operation: Operation, factor: FactorExpression, window: int) -> FactorExpression:
+    if isinstance(window, bool) or not isinstance(window, int) or window < 1:
+        raise ValueError("时序窗口必须为正整数")
+    return FactorExpression(operation, (factor,), window=window)
+
+
+def REF(factor: FactorExpression, window: int) -> FactorExpression:
+    """沿输入的完整交易时间轴延迟指定期数。"""
+    return _window("ref", factor, window)
+
+
+def MA(factor: FactorExpression, window: int) -> FactorExpression:
+    """完整窗口均值；窗口内缺值不做自动填充。"""
+    return _window("mean", factor, window)
+
+
+def STD(factor: FactorExpression, window: int) -> FactorExpression:
+    """完整窗口总体标准差，ddof=0。"""
+    return _window("std", factor, window)
+
+
+def PCT_CHANGE(factor: FactorExpression, window: int = 1) -> FactorExpression:
+    """期末值与延迟值之比减一；零分母在计算时成为缺值。"""
+    return factor / REF(factor, window) - 1.0
+
+
+def RANK(factor: FactorExpression) -> FactorExpression:
+    """默认升序平均名次 / 非空参与数量；只支持这个明确的首批语义。"""
+    return FactorExpression("rank", (factor,))

quant_core/app/factor/computation/factor_source_loader.py

@@ -0,0 +1,24 @@
+"""可信因子源码加载，不读取文件或连接存储。"""
+
+import re
+
+from quant_core.app.factor.computation.factor_expression import FactorExpression
+
+
+def load_formulas(source: str, parameters: dict | None = None) -> dict[str, FactorExpression]:
+    """加载可信 Python 定义；约定 factors 字典，不提供代码沙箱。"""
+    namespace: dict = {"__name__": "factor_user_code", "parameters": dict(parameters or {})}
+    exec(compile(source, "<factors>", "exec"), namespace)
+    factors = namespace.get("factors")
+    if (
+        not isinstance(factors, dict)
+        or not factors
+        or any(
+            not isinstance(name, str)
+            or re.fullmatch(r"[a-z][a-z0-9_]*", name) is None
+            or not isinstance(value, FactorExpression)
+            for name, value in factors.items()
+        )
+    ):
+        raise ValueError("源码必须定义非空 factors: dict[str, FactorExpression]")
+    return factors

quant_core/app/factor/computation/operators/arithmetic_operator.py

@@ -0,0 +1,182 @@
+# Derived from vn.py fa5206fe63836f3f8cd1ebd7168fbd19a5e2ff09.
+# Copyright (c) 2015-present, Xiaoyou Chen. MIT; see app/factor/LICENSE.vnpy.
+"""
+Math Functions
+"""
+
+import polars as pl
+
+from quant_core.app.factor.computation.panel_expression import PanelExpression
+
+
+def less(feature1: PanelExpression, feature2: PanelExpression | float) -> PanelExpression:
+    """Return the minimum value between two features"""
+    if isinstance(feature2, PanelExpression):
+        df_merged: pl.DataFrame = feature1.df.join(feature2.df, on=["datetime", "vt_symbol"])
+    else:
+        df_merged = feature1.df.with_columns(pl.lit(feature2).alias("data_right"))
+
+    df: pl.DataFrame = df_merged.select(
+        pl.col("datetime"),
+        pl.col("vt_symbol"),
+        pl.min_horizontal("data", "data_right").over("vt_symbol").alias("data"),
+    )
+
+    return PanelExpression(df)
+
+
+def greater(feature1: PanelExpression, feature2: PanelExpression | float) -> PanelExpression:
+    """Return the maximum value between two features"""
+    if isinstance(feature2, PanelExpression):
+        df_merged: pl.DataFrame = feature1.df.join(feature2.df, on=["datetime", "vt_symbol"])
+
+    else:
+        df_merged = feature1.df.with_columns(pl.lit(feature2).alias("data_right"))
+
+    df: pl.DataFrame = df_merged.select(
+        pl.col("datetime"),
+        pl.col("vt_symbol"),
+        pl.max_horizontal("data", "data_right").over("vt_symbol").alias("data"),
+    )
+
+    return PanelExpression(df)
+
+
+def log(feature: PanelExpression) -> PanelExpression:
+    """Calculate the natural logarithm of the feature"""
+    df: pl.DataFrame = feature.df.select(
+        pl.col("datetime"), pl.col("vt_symbol"), pl.col("data").log().over("vt_symbol")
+    )
+    return PanelExpression(df)
+
+
+def abs(feature: PanelExpression) -> PanelExpression:
+    """Calculate the absolute value of the feature"""
+    df: pl.DataFrame = feature.df.select(
+        pl.col("datetime"), pl.col("vt_symbol"), pl.col("data").abs().over("vt_symbol")
+    )
+    return PanelExpression(df)
+
+
+def sign(feature: PanelExpression) -> PanelExpression:
+    """Calculate the sign of the feature"""
+    df: pl.DataFrame = feature.df.select(
+        pl.col("datetime"),
+        pl.col("vt_symbol"),
+        pl.when(pl.col("data") > 0)
+        .then(1)
+        .when(pl.col("data") < 0)
+        .then(-1)
+        .otherwise(0)
+        .alias("data"),
+    )
+    return PanelExpression(df)
+
+
+def quesval(
+    threshold: float,
+    feature1: PanelExpression,
+    feature2: PanelExpression | float | int,
+    feature3: PanelExpression | float | int,
+) -> PanelExpression:
+    """Return feature2 if threshold < feature1, otherwise feature3"""
+    df_merged = feature1.df
+
+    if isinstance(feature2, PanelExpression):
+        df_merged = df_merged.join(feature2.df, on=["datetime", "vt_symbol"], suffix="_true")
+    else:
+        df_merged = df_merged.with_columns(pl.lit(feature2).alias("data_true"))
+
+    if isinstance(feature3, PanelExpression):
+        df_merged = df_merged.join(feature3.df, on=["datetime", "vt_symbol"], suffix="_false")
+    else:
+        df_merged = df_merged.with_columns(pl.lit(feature3).alias("data_false"))
+
+    df: pl.DataFrame = df_merged.with_columns(
+        pl.when(threshold < pl.col("data"))
+        .then(pl.col("data_true"))
+        .otherwise(pl.col("data_false"))
+        .alias("data")
+    ).select(["datetime", "vt_symbol", "data"])
+
+    return PanelExpression(df)
+
+
+def quesval2(
+    threshold: PanelExpression,
+    feature1: PanelExpression,
+    feature2: PanelExpression | float | int,
+    feature3: PanelExpression | float | int,
+) -> PanelExpression:
+    """Return feature2 if threshold < feature1, otherwise feature3."""
+    df_merged: pl.DataFrame = threshold.df.join(
+        feature1.df, on=["datetime", "vt_symbol"], suffix="_cond"
+    )
+
+    if isinstance(feature2, PanelExpression):
+        df_merged = df_merged.join(feature2.df, on=["datetime", "vt_symbol"], suffix="_true")
+    else:
+        df_merged = df_merged.with_columns(pl.lit(feature2).alias("data_true"))
+
+    if isinstance(feature3, PanelExpression):
+        df_merged = df_merged.join(feature3.df, on=["datetime", "vt_symbol"], suffix="_false")
+    else:
+        df_merged = df_merged.with_columns(pl.lit(feature3).alias("data_false"))
+
+    df: pl.DataFrame = df_merged.with_columns(
+        pl.when(pl.col("data_cond") < pl.col("data"))
+        .then(pl.col("data_true"))
+        .otherwise(pl.col("data_false"))
+        .alias("data")
+    ).select(["datetime", "vt_symbol", "data"])
+
+    return PanelExpression(df)
+
+
+def pow1(base: PanelExpression, exponent: float) -> PanelExpression:
+    """Safe power operation for PanelExpression (handles negative base values)"""
+    df: pl.DataFrame = base.df.with_columns(
+        pl.when(pl.col("data") > 0)
+        .then(pl.col("data").pow(exponent))
+        .when(pl.col("data") < 0)
+        .then(pl.lit(-1) * pl.col("data").abs().pow(exponent))
+        .otherwise(0)
+        .alias("data")
+    )
+
+    return PanelExpression(df)
+
+
+def pow2(base: PanelExpression, exponent: PanelExpression) -> PanelExpression:
+    """Power operation between two PanelExpression objects (base^exponent)
+
+    handle logic:
+    - base > 0: calculate base^exponent
+    - base < 0 and exponent is integer: calculate -1 * |base|^exponent
+    - other cases (base = 0, exponent is NaN, negative base and non-integer exponent): return 0
+
+    用 floor 判断整数幂，避免将 NaN 强制转换为整数导致异常。
+    """
+    base_renamed = base.df.rename({"data": "base_data"})
+    exp_renamed = exponent.df.rename({"data": "exp_data"})
+
+    df_merged: pl.DataFrame = base_renamed.join(
+        exp_renamed, on=["datetime", "vt_symbol"], how="left"
+    )
+
+    df: pl.DataFrame = df_merged.with_columns(
+        pl.when(pl.col("base_data") > 0)
+        .then(pl.col("base_data").pow(pl.col("exp_data")))
+        .when(
+            (pl.col("base_data") < 0)
+            & (~pl.col("exp_data").is_nan())
+            & (pl.col("exp_data").floor() == pl.col("exp_data"))
+        )
+        .then((-1) * pl.col("base_data").abs().pow(pl.col("exp_data")))
+        .otherwise(pl.lit(None))
+        .fill_nan(None)
+        .fill_null(0)
+        .alias("data")
+    ).select(["datetime", "vt_symbol", "data"])
+
+    return PanelExpression(df)

quant_core/app/factor/computation/operators/cross_section_operator.py

@@ -0,0 +1,66 @@
+# Derived from vn.py fa5206fe63836f3f8cd1ebd7168fbd19a5e2ff09.
+# Copyright (c) 2015-present, Xiaoyou Chen. MIT; see app/factor/LICENSE.vnpy.
+"""
+Cross Section Operators
+"""
+
+import polars as pl
+
+from quant_core.app.factor.computation.panel_expression import PanelExpression
+from quant_core.app.factor.computation.universe_filter import mask_cross_section
+
+
+def cs_rank(feature: PanelExpression) -> PanelExpression:
+    """Perform cross-sectional ranking"""
+    feature = mask_cross_section(feature)
+    df: pl.DataFrame = feature.df.select(
+        pl.col("datetime"), pl.col("vt_symbol"), pl.col("data").rank().over("datetime")
+    )
+    return PanelExpression(df)
+
+
+def cs_mean(feature: PanelExpression) -> PanelExpression:
+    """Calculate cross-sectional mean"""
+    feature = mask_cross_section(feature)
+    df: pl.DataFrame = feature.df.select(
+        pl.col("datetime"), pl.col("vt_symbol"), pl.col("data").mean().over("datetime")
+    )
+    return PanelExpression(df)
+
+
+def cs_std(feature: PanelExpression) -> PanelExpression:
+    """Calculate cross-sectional standard deviation"""
+    feature = mask_cross_section(feature)
+    df: pl.DataFrame = feature.df.select(
+        pl.col("datetime"), pl.col("vt_symbol"), pl.col("data").std().over("datetime")
+    )
+    return PanelExpression(df)
+
+
+def cs_sum(feature: PanelExpression) -> PanelExpression:
+    """Calculate cross-sectional sum"""
+    feature = mask_cross_section(feature)
+    df: pl.DataFrame = feature.df.select(
+        pl.col("datetime"), pl.col("vt_symbol"), pl.col("data").sum().over("datetime")
+    )
+    return PanelExpression(df)
+
+
+def cs_scale(feature: PanelExpression) -> PanelExpression:
+    """Scale the feature by the sum of absolute values in the cross section"""
+    feature = mask_cross_section(feature)
+    abs_feature = abs(feature)
+    sum_abs = cs_sum(abs_feature)
+
+    df_merged: pl.DataFrame = feature.df.join(
+        sum_abs.df, on=["datetime", "vt_symbol"], suffix="_sum"
+    )
+
+    df: pl.DataFrame = df_merged.with_columns(
+        pl.when(pl.col("data_sum") != 0)
+        .then(pl.col("data") / pl.col("data_sum"))
+        .otherwise(0)
+        .alias("data")
+    ).select(["datetime", "vt_symbol", "data"])
+
+    return PanelExpression(df)