hikyuu

README

<p align="center">
  <img src="https://web-code-img.oss-cn-shanghai.aliyuncs.com/readme/2399fb0fe2e1fa47c5198c51.png" width="200" alt="title">
</p>

<p align="center">
  基于 C++/Python 的开源量化研究框架 —— 金融与交易正确性优先，策略与组合同构、可任意深度嵌套，部件自由替换的高性能量化引擎
</p>

<p align="center">
  <img src="https://github.com/fasiondog/hikyuu/workflows/win-build/badge.svg" alt="Windows build">
  <img src="https://github.com/fasiondog/hikyuu/workflows/ubuntu-build/badge.svg" alt="Ubuntu build">
  <img src="https://img.shields.io/github/license/fasiondog/hikyuu.svg" alt="License">
  <img src="https://static.pepy.tech/badge/hikyuu" alt="Downloads">
</p>

<p align="center">
  <a href="https://gitee.com/fasiondog/hikyuu/blob/master/readme.md">English</a> | <b>简体中文</b>
</p>

**Hikyuu 的内核是「交易理论与金融语义的完整与正确」**：一笔交易在金融上该怎样成立——何时成交、成本由哪几项构成、除权时持仓与现金如何变化、绩效用什么口径、空值与非有限值怎么传播——在框架里都是**完整且显式**的：环节不缺、规则被真正执行、可被逐项校验，而不是留给使用者自己保证。

**立意只有一句：不让一个「能跑通」却不成立的策略，被当成结论。**

两个手段服务于这个内核：**按理论问题切分结构**——一个策略必须回答市场状态、条件、信号、仓位、退出与成交价，一个组合必须回答选谁、分多少钱、按什么评分，每一类都是理论上的一个必答问题，而不是工程意义上的模块；**组合即策略**——把组合做成一等公民（`SE` / `AF` / `MF`），内核才能从单策略延伸到多资产多策略。于是每一环可独立替换与评估，每一笔都记在可查询的账本里；框架的价值不在穷举，而在**每个位置都留对、替换后契约仍然成立**（见下文「🏛️ 交易理论与金融语义」与「🧬 组合即策略」）。

> ⚠️ **免责声明**：本项目为开源金融技术研究工具，仅供个人学习、学术研究与数据分析使用，不构成任何投资建议与交易指导，不提供、不内置证券交易服务。用户自主新增、对接各类交易接口、开发拓展功能以及对应的实操行为，均由用户自行承担全部风险与法律责任，严禁对接非法交易通道、用于违规交易场景。

---

## 📊 关键数据

<p align="center">
  <table>
    <tr>
      <td align="center" width="25%">
        <strong><code>⚡ 6s / 166ms</code></strong><br>
        <sub>1913 万日 K 线加载 + 20 日均线求和：首次 / 预热后（AMD 7950x，<a href="https://mp.weixin.qq.com/s?__biz=MzkwMzY1NzYxMA==&mid=2247483768&idx=1&sn=33e40aa9633857fa7b4c7ded51c95ae7">实测详情</a>）</sub>
      </td>
      <td align="center" width="25%">
        <strong><code>🏛️ 3 层</code></strong><br>
        <sub>内建金融语义（交易理论 / 交易规则 / 计算）</sub>
      </td>
      <td align="center" width="25%">
        <strong><code>🧬 3 种</code></strong><br>
        <sub>组合运行模式（A 信号聚合 / B 资金分配 / C 共享账户）</sub>
      </td>
      <td align="center" width="25%">
        <strong><code>💾 4 种</code></strong><br>
        <sub>存储方式（HDF5 / MySQL / ClickHouse / SQLite）</sub>
      </td>
    </tr>
  </table>
</p>

---

## 🔗 快速导航

| 项目                   | 链接                                                                                                                                              |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| 🏠**项目首页**   | [https://hikyuu.org/](https://hikyuu.org/)                                                                                                         |
| 📚**帮助文档**   | [https://hikyuu.readthedocs.io/zh-cn/latest/index.html](https://hikyuu.readthedocs.io/zh-cn/latest/index.html)                                     |
| 🚀**入门示例**   | [Jupyter Notebook 系列教程](https://nbviewer.org/github/fasiondog/hikyuu/blob/master/hikyuu/examples/notebook/zh/000-Index.ipynb?flush_cache=True) |
| 🧰**策略部件库** | [https://gitee.com/fasiondog/hikyuu_hub](https://gitee.com/fasiondog/hikyuu_hub)                                                                   |

---

## 🧭 入门之前：它是什么，不是什么

> **它不是自动交易工具，也不是订单执行系统**：不内置券商对接、不承诺自动下单，也不做 tick 级撮合或低延迟执行；`OrderBroker` 只是一个可插拔的接口，是否对接、对接什么通道由你自己决定并承担合规责任。它按 K 线推进，把一笔交易的金融语义按真实规则完整执行；决策仍然是你的事。撮合的微观结构（部分成交、撤单、订单队列）与现代组合优化（均值方差、风险平价）也不例外：框架不替你选定这类算法，但把它们的位置留好了——撮合经 `OrderBroker` 与成交模型接入，组合优化写一个 `AF` 子类即可，`SE` / `MF` / `MM` / `ST` 同理。**框架的意义不是把算法写全，而是把位置留对：每个位置可替换，且替换后结算与校验仍然成立。**

**门槛是有意保留的**：框架不会用一条漂亮的曲线，替你补上那些你没想到的前提。这些环节必须自己懂——否则得到的只是一个能跑的错觉。

换个角度看，它更像一张地图：把做策略该考虑的环节逐项列出（环境 → 条件 → 信号 → 仓位 → 退出 → 滑点 → 成本；组合层：选样 → 资金分配 → 风控），照着这张图逐项填，路径本身就是入门路径。**它适合想把系统化交易认真学一遍的人**——包括自学者与学生——而不是想两天跑出一条收益曲线的人。

> 「不敢下注就赢不了；把筹码输光，就没法再下注。」—— 拉里·海特

给初入者与自学者的几条忠告：

- **先跑通流程，再谈收益**：回测收益率不是能力证明，能解释每一笔为什么成交才是。
- **一次只改一个部件**：其他环节固定不动做对照，否则无法知道收益变化来自哪里。
- **先有成本与权息，再调参数**：没有成本约束下的最优参数，往往只是拟合噪声。
- **关心「什么环境下失效」**：比关心「历史赚了多少」更有用；用样本外与走步验证（`SYS_WalkForward`）检验，而不是在同一个区间反复调参。
- **默认关掉的要慎用**：杠杆、做空默认关闭是刻意的，先弄清保证金、强平与借券成本，再显式打开。

---

## ⚡ 快速开始（跑通第一个回测）

### 环境要求

- **Python 3.10+**（官方包仅面向 3.10 ~ 3.13 构建）
- 支持 Windows / Linux / macOS（Linux 需 Ubuntu 24.04+）

### 第 1 步：安装

```bash
pip install hikyuu
```

国内用户若下载缓慢，可换用镜像源：

```bash
pip install hikyuu -i https://pypi.tuna.tsinghua.edu.cn/simple
```

### 第 2 步：导入行情数据

任选一种方式导入 A 股历史行情数据：

```bash
# 图形界面（推荐首次使用，会自动生成配置文件）
HikyuuTDX

# 命令行（需先运行过一次 HikyuuTDX 生成配置）
importdata
```

### 第 3 步：跑通第一个回测

```python
from hikyuu.interactive import *

# 创建模拟交易账户进行回测，初始资金 30 万
my_tm = crtTM(init_cash=300000)

# 创建信号指示器（以 5 日 EMA 为快线，其 10 日 EMA 为慢线）
# 快线向上穿越慢线时买入，反之卖出
my_sg = SG_Flex(EMA(CLOSE(), n=5), slow_n=10)

# 固定每次买入 1000 股
my_mm = MM_FixedCount(1000)

# 创建交易系统并运行
sys = SYS_Simple(tm=my_tm, sg=my_sg, mm=my_mm)
sys.run(sm['sz000001'], Query(-150))
```

<p align="center">
  <img src="https://web-code-img.oss-cn-shanghai.aliyuncs.com/readme/b95c3ef30f5899671dcadca4.png" alt="回测结果示意" width="900">
</p>

> 📖 完整示例参见 [Jupyter Notebook 系列教程](https://nbviewer.org/github/fasiondog/hikyuu/blob/master/hikyuu/examples/notebook/zh/000-Index.ipynb?flush_cache=True)
>
> 跑通单系统之后，下一步就是把多个策略组成一个组合：见下文「🧬 组合即策略」。

---

## 🏛️ 交易理论与金融语义的完整与正确

> 三层，各管一件事，缺一层就不成立：**交易理论**——环节不能缺，缺了组合层，多策略就只是并行回测；**交易规则**——规则不能错，缺了权息与分项成本，除权日与跨年收益就会失真，缺了成交时机约束，信号当根成交就是前视；**计算**——空值语义必须一致，若由各指标自行处置，一个 `inf` 就会污染下游所有窗口聚合。这三层在框架里都是显式对象与全局约定——不靠文档提醒，而靠框架执行与入口守卫。

| 层面 | 回答什么 |
| :--- | :--- |
| 交易理论 | 一个策略该由哪些部分组成，一个组合该由哪些层组织 |
| 交易规则 | 一笔交易在市场上该如何成交、扣费、除权与计价 |
| 计算 | 空值与数值在整条计算链上如何保持一致 |

**交易理论**：按理论结构而非代码职责划分——策略必须回答市场状态（`EV`）、条件（`CN`）、信号（`SG`）、仓位（`MM`）、退出（`ST` / `TP` / `PG`）与成交价（`SP`）；组合必须回答选谁（`SE`）、分多少钱（`AF` 的 L1 权重 / L2 换算 / L3 风控）、按什么评分（`MF`）。每一类都是理论上的一个必答问题，缺一环策略就是残缺的。

**交易规则**：成交默认延迟到下一根开盘（`buy_delay` / `sell_delay`），一价板或停牌时顺延、超过 `max_delay_count` 放弃，滑点价钳制在当日 `[low, high]`；成本按 `CostRecord` 分项（佣金 / 印花税 / 过户费），买卖分别计算；`updateWithWeight` 按权息调整持仓与现金；融资融券默认关闭；绩效按净资产与自然日年化（`duration / 365`）。

**计算**：未定义状态（除零 / 零方差 / 全