quant_engine

量化研究引擎 —— alpha 因子库 + 执行仿真 + 技术指标 + 数据适配 + 回测工具

从 research_results 抽出的纯回测能力库（v1.2.0 重构）。

角色

quant_engine 是 researchhub_workspace 的引擎层：

仓库	角色
quant_engine	纯回测核心（alpha + execution + indicators + data_adapter + backtest + metrics）
research_results	业务集成（47 个 proj 调度 + 注册 + 平台对接）
tushare2db_pro_aoge	数据层（行情 ELT）
research_platform	展示层（FastAPI + Next.js）
edb_data_core	数据层（经济数据）

模块

• alpha_factors — 158 alpha 公式 + 24 基础算子（移植自 qlib alpha158）
• execution — 执行仿真（成本/滑点/T+1/涨跌停/部分成交/价差）+ 多日 NAV + PnL 拆解（借鉴 hikyuu 部件化思想）
• indicators — 50+ 技术指标（MACD / KDJ / 布林 / ATR / ADX / 等）
• data_adapter — 桥接 qtdb_pro 长表与新模块（rename / long-wide / 复权 / vwap 代理）
• backtest — weight-based 多日仿真（rebalance_table / compute_nav / compare_to_benchmark）
• portfolio_construction — 多期因子分数 → Top-K → 等权目标权重表
• metrics — 绩效（年化收益 / 波动率 / Sharpe / 最大回撤 / Calmar）
• factor_library — 通用方法（turnover / winsorize / IC / OLS / jb_test）
• portfolio_decomp — 组合分解（risk_parity / mean_variance / 因子归因）
• risk — 风险指标（边际 / 风险贡献）
• perf_stats — 详细绩效（与 metrics 并存）
• logging — 统一 logger（标准库 + 可选 loguru）

依赖

• 必需：numpy / pandas / scipy（标准量化栈）
• 可选：loguru（logback，标准库 logging 兜底）

零重型依赖 —— 不引入 torch / lightgbm / hikyuu 等。

安装

cd quant_engine
pip install -e ".[dev]"

测试

pytest                    # 单元测试
pytest --cov=src          # 覆盖率
mypy --strict src/        # 类型检查
ruff check src/ tests/    # lint

使用

from quant_engine.alpha_factors import alpha_001, alpha_005, ALPHA158_REGISTRY
from quant_engine.execution import (
    ExecutionConfig, simulate_with_daily_data, compute_realized_pnl,
)
from quant_engine.backtest import run_weight_backtest
from quant_engine.portfolio_construction import scores_to_weight_table
from quant_engine.indicators import macd, bollinger, kdj
from quant_engine.data_adapter import (
    long_to_wide, wide_to_long, rename_tushare_columns,
    add_vwap_proxy, apply_adj_factor,
    prepare_stock_series, prepare_execution_inputs,
    load_qtdb_daily,
)

# 端到端：qtdb_pro 长表 → 适配 → alpha158 → execution
df = load_qtdb_daily(["000001.SZ"], "2024-01-01", with_adj=True)
prices, volumes = prepare_execution_inputs(df)
result = simulate_with_daily_data(prices, initial_cash=1_000_000.0)

# 多期因子分数 → Top-K 等权组合 → 稳定回测结果
rebalance_weights = scores_to_weight_table(
    factor_scores,
    top_k=20,
    gross_exposure=1.0,
)
backtest = run_weight_backtest(
    weights=rebalance_weights,
    stock_returns=daily_returns,
    initial_capital=1_000_000.0,
    benchmark_nav=benchmark_nav,
)
print(backtest.stats())
print(backtest.benchmark_report())

与 research_results 的关系

research_results 依赖 quant_engine（通过 re-export 保持向后兼容）：

# research_results/src/shared/alpha_factors.py 现在是：
from quant_engine.alpha_factors import *  # re-export

47 个 proj 的 import 路径暂时不变（from src.shared.alpha_factors import ... 仍可用）——后续逐步迁移到 from quant_engine.alpha_factors import ...。