akquant 0.2.45__tar.gz → 0.2.47__tar.gz

{akquant-0.2.45 → akquant-0.2.47}/.gitignore

@@ -32,3 +32,4 @@ build/
 .cargo/config.toml
 /data_catalog/
 plans/
+CLAUDE.md

{akquant-0.2.45 → akquant-0.2.47}/CONTRIBUTING.md

@@ -45,7 +45,9 @@
     uv pip install -e ".[dev,ml,plot]"
 
     # 编译 Rust 扩展 (开发模式)
-    uv run maturin develop
+    # 注意：不要使用 `uv run maturin develop`，它会先尝试安装当前项目，
+    # 对于以 maturin 作为 build backend 的仓库可能卡在 Preparing packages。
+    uvx maturin develop
     ```
 
 ### 3. 开始开发 (Coding)
@@ -161,7 +163,7 @@
 
 在提交 PR 之前，请检查：
 
-- [ ] 代码可以通过 `uv run maturin develop` 编译成功。
+- [ ] 代码可以通过 `uvx maturin develop` 编译成功。
 - [ ] 运行了 `uv run ruff check .` 和 `uv run mypy .` 没有报错。
 - [ ] 运行了 `uv run python scripts/check_docs_links.py` 且通过。
 - [ ] 运行了 `uv run python scripts/check_docs_api_examples.py` 且通过。

{akquant-0.2.45 → akquant-0.2.47}/Cargo.lock

@@ -30,7 +30,7 @@ dependencies = [
 
 [[package]]
 name = "akquant"
-version = "0.2.45"
+version = "0.2.47"
 dependencies = [
  "anyhow",
  "chrono",

{akquant-0.2.45 → akquant-0.2.47}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "akquant"
-version = "0.2.45"
+version = "0.2.47"
 edition = "2024"
 description = "High-performance quantitative trading framework based on Rust and Python"
 license = "MIT"

{akquant-0.2.45 → akquant-0.2.47}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: akquant
-Version: 0.2.45
+Version: 0.2.47
 Classifier: Programming Language :: Rust
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Programming Language :: Python :: Implementation :: PyPy
@@ -349,7 +349,9 @@ AKQuant 采用严格的测试流程以确保回测引擎的准确性：
 uv sync
 
 # 2. 构建并绑定 Rust 扩展
-uv run maturin develop
+# 注意：不要使用 `uv run maturin develop`，它会先尝试安装当前项目，
+# 对于以 maturin 作为 build backend 的仓库可能卡在 Preparing packages。
+uvx maturin develop
 
 # 3. 运行所有测试
 uv run pytest

{akquant-0.2.45 → akquant-0.2.47}/README.md

@@ -294,7 +294,9 @@ AKQuant 采用严格的测试流程以确保回测引擎的准确性：
 uv sync
 
 # 2. 构建并绑定 Rust 扩展
-uv run maturin develop
+# 注意：不要使用 `uv run maturin develop`，它会先尝试安装当前项目，
+# 对于以 maturin 作为 build backend 的仓库可能卡在 Preparing packages。
+uvx maturin develop
 
 # 3. 运行所有测试
 uv run pytest

akquant-0.2.47/docs/zh/textbook/00_glossary.md

@@ -0,0 +1,104 @@
+# 术语表与符号约定
+
+本页汇总全书反复出现的**数学符号**与**核心术语**，供随时查阅。术语后标注了首次系统讲解所在的章节，便于回溯。术语遵循全书统一写法：一般写作 **AKShare**、**AKQuant**（代码块 `import` 除外）。
+
+## 数学符号约定
+
+全书数学记号尽量保持一致，常见符号含义如下：
+
+| 符号 | 含义 | 主要出处 |
+| :--- | :--- | :--- |
+| $R_p,\ R_f,\ R_m$ | 组合收益率、无风险收益率、市场收益率 | 第 1、10 章 |
+| $E(\cdot)$ | 期望（均值） | 第 1、10 章 |
+| $\alpha,\ \beta$ | 超额收益（Alpha）、市场敏感度（Beta） | 第 1、10 章 |
+| $\sigma,\ \sigma_d$ | 波动率（标准差）、下行波动率 | 第 10 章 |
+| $\mu,\ \Sigma$ | 资产预期收益向量、收益率协方差矩阵 | 第 9 章 |
+| $w = [w_1,\dots,w_N]^T$ | 组合权重向量 | 第 9 章 |
+| $N(\cdot),\ \Phi^{-1}(\cdot)$ | 标准正态分布的累积分布函数、其反函数 | 第 8、11 章 |
+| $\gamma_3,\ \gamma_4$ | 偏度、峰度 | 第 10 章 |
+| $S_t,\ F_t$ | $t$ 时刻现货价格、期货价格 | 第 7 章 |
+| $K,\ T,\ r$ | 行权价、到期时间、无风险利率 | 第 8 章 |
+| $u,\ y$ | 仓储成本、便利收益 | 第 7 章 |
+| $\Delta,\ \Gamma,\ \Theta,\ \nu$ | 期权希腊字母：Delta、Gamma、Theta、Vega | 第 8 章 |
+| $\widehat{SR}$ | 样本估计的夏普比率 | 第 10、11 章 |
+| $\theta,\ \Theta$（优化语境） | 策略参数向量、参数搜索空间 | 第 11 章 |
+
+> 提示：$\Theta$ 在第 8 章表示期权 Theta，在第 11 章表示参数搜索空间，二者按上下文区分。
+
+## 一、基础与理论
+
+- **量化投资 (Quantitative Investment)** —— 借助统计与数学方法，从历史数据中寻找大概率策略并纪律化执行的投资方式。（第 1 章）
+- **Alpha / Beta** —— Beta 是被动承担市场风险获得的收益，Alpha 是剔除市场因素后的主动超额收益。（第 1、10 章）
+- **CAPM（资本资产定价模型）** —— 将组合预期收益分解为无风险收益、市场风险补偿与 Alpha 的定价模型。（第 1 章）
+- **有效市场假说 (EMH)** —— 认为价格已反映可得信息的假说，分弱式、半强式、强式三档。（第 1 章）
+- **前景理论 (Prospect Theory)** —— Kahneman 与 Tversky 提出，揭示损失厌恶等行为偏误。（第 1 章）
+- **市场微观结构 (Market Microstructure)** —— 研究交易机制、价格形成与流动性的学科。（第 1、6 章）
+
+## 二、数据
+
+- **OHLCV** —— K 线的开、高、低、收、量五个字段。（第 3 章）
+- **复权 (Adjustment)** —— 消除分红配股拆细造成的价格断层，分前复权、后复权、不复权。（第 3 章）
+- **幸存者偏差 (Survivorship Bias)** —— 只用当前存续标的回测导致结果虚高的偏差。（第 3 章）
+- **前视偏差 (Look-ahead Bias)** —— 在决策时点使用了尚不可得的未来信息。（第 3、12 章）
+- **Point-in-Time (PIT)** —— 严格按信息可得时点对齐的数据组织方式。（第 3 章）
+
+## 三、引擎与撮合
+
+- **事件驱动回测 (Event-Driven Backtesting)** —— 按时间逐事件推进、逐 Bar 撮合的回测范式，对应向量化回测。（第 4 章）
+- **撮合引擎 (Matching Engine)** —— 根据行情判断订单是否成交及成交价的模块。（第 4 章）
+- **三轴成交语义 (`fill_policy`)** —— 由 `price_basis`、`bar_offset`、`temporal` 三个维度共同决定成交价与成交时点。（第 4 章）
+- **滑点与冲击成本 (Slippage / Market Impact)** —— 成交价劣于预期价的部分；冲击成本常用平方根法则刻画。（第 4 章）
+- **风控引擎 (RiskManager)** —— 引擎层独立于策略的预交易硬性风控。（第 4 章）
+
+## 四、订单与交易
+
+- **订单状态机** —— New → Submitted → Accepted → (Partially)Filled / Cancelled / Rejected 的状态流转。（第 4、15 章）
+- **`order_target_percent` / `order_target_positions`** —— 目标权重调仓接口与目标持仓数量调仓接口。（第 5 章）
+- **开平语义 (`position_effect`)** —— 方向（Buy/Sell）之外的 open / close / close_today 等开平标记。（第 5 章）
+- **T+1 制度** —— A 股当日买入次日方可卖出的交收规则，引擎以"可用持仓"建模。（第 6 章）
+
+## 五、风险与评价
+
+- **最大回撤 (Max Drawdown, MDD)** —— 从历史最高点到后续低点的最大跌幅。（第 1、10 章）
+- **夏普比率 / 索提诺比率 / 卡玛比率** —— 分别以总波动、下行波动、最大回撤为分母的风险调整后收益。（第 10 章）
+- **VaR / CVaR** —— 在险价值与条件在险价值（期望损失），后者具次可加性。（第 10 章）
+- **PSR / DSR** —— 概率夏普比率与收缩夏普比率，分别校正非正态性与多重试验偏差。（第 10、11 章）
+- **MAE / MFE** —— 持仓期间最大浮亏与最大浮盈，用于优化止损止盈。（第 10、13 章）
+- **归因分析 (Attribution)** —— 将收益分解为配置、选股、因子暴露等来源。（第 10 章）
+
+## 六、衍生品与期权
+
+- **保证金与杠杆 (Margin / Leverage)** —— 期货按比例缴纳保证金形成杠杆。（第 7 章）
+- **期限结构 (Term Structure)** —— 不同到期月合约的价格结构，分升水（Contango）与贴水（Backwardation）。（第 7 章）
+- **持有成本模型 (Cost of Carry)** —— $F_t = S_t e^{(r+u-y)(T-t)}$ 的定价框架。（第 7 章）
+- **BSM 模型** —— Black-Scholes-Merton 欧式期权定价模型。（第 8 章）
+- **希腊字母 (Greeks)** —— 期权价格对各变量的敏感度：Delta、Gamma、Theta、Vega 等。（第 8 章）
+- **隐含波动率 (IV)** —— 由市场期权价格反推的波动率。（第 8 章）
+
+## 七、组合与配置
+
+- **现代投资组合理论 (MPT)** —— Markowitz 的均值-方差分散化框架。（第 9 章）
+- **有效前沿 (Efficient Frontier)** —— 风险-收益平面上的最优组合曲线。（第 9 章）
+- **风险平价 (Risk Parity)** —— 追求各资产风险贡献相等而非资金等权。（第 9 章）
+- **Black-Litterman 模型** —— 以贝叶斯框架融合市场均衡先验与投资者观点。（第 9 章）
+- **分层风险平价 (HRP)** —— López de Prado 提出，用层次聚类替代协方差矩阵求逆。（第 9 章）
+
+## 八、机器学习与因子
+
+- **三重屏障法 (Triple Barrier)** —— 以止盈、止损、时间三条屏障定义标签。（第 12 章）
+- **元标签 (Meta-Labeling)** —— 用次级模型判断是否采纳初级模型信号的二次模型思想。（第 12 章）
+- **净化交叉验证 (Purged K-Fold CV)** —— 在训练集与测试集间净化、隔离以防信息泄露。（第 12 章）
+- **滚动回测 (Walk-Forward)** —— 定期重新优化、逐段拼接样本外结果的验证方法。（第 11、12 章）
+- **因子表达式引擎** —— 以 `Rank(Ts_Mean(Close, 5))` 之类表达式描述因子，区分 TS / CS / EL 算子。（第 14 章）
+
+## 九、实盘与运维
+
+- **网关 (Gateway)** —— 对接 CTP / MiniQMT / PTrade 等柜台的适配器接口。（第 15 章）
+- **OMS / RMS** —— 订单管理系统与风险管理系统。（第 15 章）
+- **TWAP / VWAP** —— 时间加权、成交量加权的算法执行方式。（第 15 章）
+- **热启动 (Warm Start)** —— 保存并恢复引擎状态以实现"断点续传"。（第 4、15 章）
+- **warmup（预热）** —— 指标窗口未满时输出空值或不稳定值的区段，发单前须剔除。（第 16 章）
+
+---
+
+> 需要某个术语的完整推导或代码用法时，请前往其标注章节；指标的输入/输出/参数口径请以 [AKQuant 指标全量说明](../guide/rust_indicator_reference.md) 为准。

{akquant-0.2.45 → akquant-0.2.47}/docs/zh/textbook/01_foundations.md

@@ -1,5 +1,18 @@
 # 第 1 章：量化投资概述与环境搭建
 
+> ⏱️ 预计阅读 ~25 分钟 ｜ 🎯 难度 ★★☆☆☆（入门）
+
+## 学习目标
+
+- 建立量化研究的基本闭环，理解“数据、策略、交易、风控”的关系。
+- 完成基于 uv 的 AKQuant 开发环境搭建，并能独立运行首个示例。
+- 建立 UTC 与本地时区分层处理的正确时间心智模型。
+
+## 前置知识
+
+- 具备基础的 Python 命令行使用能力。
+- 了解股票、收益率、回撤等入门金融概念即可。
+
 ## 本章实践入口
 
 - 主示例：[examples/textbook/ch01_quickstart.py](https://github.com/akfamily/akquant/blob/main/examples/textbook/ch01_quickstart.py)
@@ -23,12 +36,7 @@ python examples/textbook/ch01_quickstart.py
 
 **量化投资 (Quantitative Investment)** 是指借助现代统计学和数学方法，利用计算机技术从海量历史数据中寻找能够带来超额收益的多种“大概率”策略，并纪律严明地按照这些策略进行投资决策的过程。
 
-与定性投资（Fundamental Investing）相比，量化投资具有以下显著特征：
-
-1.  **纪律性 (Discipline)**：严格执行模型给出的信号，克服人性的贪婪与恐惧。
-2.  **系统性 (Systematic)**：多层次（资产配置、行业选择、个股选择）、多角度（宏观、估值、成长、技术）地观察市场。
-3.  **套利思想 (Arbitrage)**：寻找市场定价偏差，通过买入低估资产、卖出高估资产获利。
-4.  **概率取胜 (Probability)**：不追求单笔交易的暴利，而是追求在大概率获利的策略下，通过长期重复交易积累财富。
+与依赖个人判断的定性投资（Fundamental Investing）相比，量化投资的特征可以概括为四个相互支撑的方面。首先是**纪律性 (Discipline)**：策略一旦确定，就严格执行模型给出的信号，借此克服人性中的贪婪与恐惧。其次是**系统性 (Systematic)**：它从资产配置、行业选择到个股选择多个层次，又从宏观、估值、成长、技术多个角度同时观察市场，而不押注于单一视角。第三是**套利思想 (Arbitrage)**：量化的获利逻辑建立在发现市场定价偏差之上，通过买入被低估的资产、卖出被高估的资产来获取收益。最后是**概率取胜 (Probability)**：它并不追求单笔交易的暴利，而是依靠一个胜率占优的策略，通过长期、大量、重复的交易，把微弱的统计优势积累成可观的财富。
 
 ### 1.1.1 核心流程 (Workflow)
 
@@ -66,29 +74,19 @@ $$ E(R_p) = R_f + \beta_p (E(R_m) - R_f) + \alpha_p $$
 
 ### 1.1.3 有效市场假说 (EMH)
 
-尤金·法玛 (Eugene Fama) 提出的 **有效市场假说 (Efficient Market Hypothesis)** 认为，如果在一个证券市场中，价格完全反映了所有可以获得的信息，那么就称这样的市场为有效市场。
+尤金·法玛 (Eugene Fama) 提出的**有效市场假说 (Efficient Market Hypothesis)** 认为，如果证券价格已经完全反映了所有可以获得的信息，这样的市场就称为有效市场。按照”信息被反映的程度”，假说又分为递进的三档：**弱式有效**意味着价格已反映全部历史信息，因此单纯依赖历史走势的技术分析将会失效；**半强式有效**进一步认为价格已反映所有公开信息，于是基于财报、公告的基本面分析也难以获得超额收益；**强式有效**则是最极端的假设——价格连内幕信息都已反映，任何分析都无济于事。
 
-*   **弱式有效**：价格已反映所有历史信息（技术分析无效）。
-*   **半强式有效**：价格已反映所有公开信息（基本面分析无效）。
-*   **强式有效**：价格已反映所有信息，包括内幕信息（所有分析均无效）。
-
-**量化投资的前提是市场并非“强式有效”**。我们通过挖掘市场微观结构中的**非理性行为**或**信息不对称**，寻找定价偏差（Mispricing）并从中获利。
+**量化投资的前提是市场并非”强式有效”**。我们通过挖掘市场微观结构中的**非理性行为**或**信息不对称**，寻找定价偏差（Mispricing）并从中获利。
 
 ## 1.2 行为金融学 (Behavioral Finance)
 
-传统金融学假设投资者是理性的 (Rational)，但现实中，人是情感驱动的。行为金融学揭示了导致市场无效的心理学根源。
+传统金融学假设投资者是完全理性的 (Rational)，但现实中的人往往被情绪驱动。行为金融学的价值，正在于揭示市场之所以无效的心理学根源，其中有三种偏误对量化策略尤为重要。
 
-1.  **前景理论 (Prospect Theory)**：
-    *   由 Kahneman 和 Tversky 提出。人对损失的厌恶程度是对收益喜好程度的 2-2.5 倍。
-    *   **现象**：投资者倾向于过早止盈（落袋为安），但死扛亏损（不愿意承认错误）。这解释了为什么动量策略（追涨杀跌）长期有效。
+最具解释力的是 Kahneman 与 Tversky 提出的**前景理论 (Prospect Theory)**。它的核心发现是一种不对称：人对损失的痛苦，约是对等量收益喜悦的 2 到 2.5 倍。这种"损失厌恶"直接塑造了投资者最典型的行为——盈利时急于落袋为安、过早止盈，亏损时却死扛不放、迟迟不愿承认错误。正是这种"截断利润、放任亏损"的群体倾向，为动量策略（追涨杀跌）的长期有效提供了行为层面的根据。
 
-2.  **过度自信 (Overconfidence)**：
-    *   投资者往往高估自己的信息优势和预测能力。
-    *   **现象**：导致过度交易 (Over-trading)，推高了成交量和波动率，却降低了净收益。
+第二种是**过度自信 (Overconfidence)**。投资者常常高估自己的信息优势与预测能力，总觉得"这一次我看得准"。其后果是过度交易 (Over-trading)：频繁买卖推高了成交量与波动率，却因不断付出手续费和买卖价差而侵蚀了净收益。
 
-3.  **羊群效应 (Herd Behavior)**：
-    *   投资者倾向于模仿他人的行为，通过随大流来获得安全感。
-    *   **现象**：导致资产价格泡沫的形成和破裂。
+第三种是**羊群效应 (Herd Behavior)**。出于对安全感的需要，投资者倾向于模仿他人、随大流行动。当这种相互模仿不断自我强化时，便会推动资产价格脱离基本面，吹起泡沫，并在情绪逆转时加速其破裂。
 
 ## 1.3 市场微观结构基础 (Market Microstructure)
 
@@ -112,15 +110,9 @@ $$ E(R_p) = R_f + \beta_p (E(R_m) - R_f) + \alpha_p $$
 
 ## 1.4 量化与主观的融合 (Quantamental)
 
-**Quantamental = Quant + Fundamental**。
-
-*   **量化 (Quant)**：擅长广度。能同时扫描 5000 只股票，处理海量数据，纪律性强，但对突发事件（如战争、政策突变）反应迟钝。
-*   **主观 (Fundamental)**：擅长深度。能深入调研一家公司，理解商业模式和管理层，但覆盖面窄，易受情绪影响。
+**Quantamental** 是 Quant 与 Fundamental 的合成词，指量化与主观投资的融合。二者的长处恰好互补：**量化 (Quant)** 擅长广度，能同时扫描 5000 只股票、处理海量数据，且纪律性强，但对战争、政策突变这类突发事件反应迟钝；**主观 (Fundamental)** 擅长深度，能深入调研一家公司、理解其商业模式与管理层，却受限于覆盖面窄、易被情绪左右。
 
-未来的趋势是二者的融合：
-
-1.  **量化赋能主观**：用量化模型筛选出初选池，再由研究员深入调研。
-2.  **主观赋能量化**：将研究员的逻辑（如供应链关系、行业景气度）转化为量化因子，增强模型的可解释性和适应性。
+正因如此，未来的趋势是二者的双向赋能。一方面是**量化赋能主观**：先用量化模型从全市场筛出初选池，再交由研究员深入调研，把人的精力集中用在最值得研究的标的上；另一方面是**主观赋能量化**：把研究员的逻辑（如供应链关系、行业景气度）翻译成量化因子，从而增强模型的可解释性与对市场变化的适应性。
 
 ## 1.5 开发环境搭建
 
@@ -340,15 +332,61 @@ calmar_ratio                            -0.250393
 
 ## 本章小结
 
-1. 量化投资的核心是“数据、策略、交易、风控”四段闭环。
-2. `AKQuant` 通过 Python + Rust 混合架构兼顾研发效率与执行性能。
-3. 首个回测示例的重点不在收益高低，而在建立可复现的研究流程。
+### 必须掌握
+
+- 量化投资的核心不是“预测涨跌”，而是构建可复现的研究与执行闭环。
+- AKQuant 通过 Python + Rust 架构兼顾研发效率与执行性能。
+
+### 理解即可
+
+- 行为金融、市场微观结构与 Quantamental 是后续策略建模的重要背景。
+
+### 实践提醒
+
+- 先确保环境、示例、时间显示三件事全部跑通，再继续后续章节。
+
+## 主线推进
+
+本章为贯穿全书的课程项目埋下了起点。我们用一个经典的双均线（MA5/MA20）策略跑通了“数据 → 信号 → 下单 → 评估”的完整回测闭环，并读懂了 `total_return_pct`、`max_drawdown_pct`、`sharpe_ratio` 等核心指标的含义。这条最小策略本身在示例区间里收益为负，并不适合直接实盘，但它的价值在于成为后续每一章不断升级的同一个对象：第 2、3 章为它备齐编程工具与可复现数据，第 4、5 章把它改造成事件驱动的标准策略类，再往后则为它补上多资产、评价、优化、机器学习与实盘能力。建议你从现在起，就把这个策略和它的回测记录保存为课程项目的第一个版本。
+
+## 延伸阅读
+
+**经典著作**
+
+- Bodie, Z., Kane, A., & Marcus, A. J. *Investments*（《投资学》），McGraw-Hill —— 系统讲解 CAPM、有效市场假说与现代组合理论，可与本章 1.1 对照精读。
+- Kahneman, D. *Thinking, Fast and Slow*（《思考，快与慢》），Farrar, Straus and Giroux, 2011 —— 前景理论与各类行为偏误的权威通俗读物，延伸本章 1.2。
+- Grinold, R. C., & Kahn, R. N. *Active Portfolio Management*（第 2 版），McGraw-Hill, 2000 —— 主动管理与 Alpha/Beta 分解的奠基之作。
+
+**官方文档与工具**
+
+- [uv 官方文档](https://github.com/astral-sh/uv) —— 本章使用的 Python 环境与依赖管理工具。
+- [AKShare 官方文档](https://akshare.akfamily.xyz/) —— 后续各章数据获取的主要来源。
+
+**本书相关**
+
+- [AKQuant 的时间与时区](../guide/quant_basics.md)、[时区处理指南](../advanced/timezone.md) —— 巩固本章建立的 UTC / 本地时区心智模型。
 
 ## 课后练习
 
+### 基础题
+
 1. 将初始资金从 `100000` 改为 `500000`，比较回测指标变化。
-2. 更换一只股票重复运行，记录累计收益和最大回撤差异。
-3. 用一句话解释“夏普比率”和“最大回撤”各自解决什么问题。
+
+### 应用题
+
+1. 更换一只股票重复运行，记录累计收益和最大回撤差异。
+
+### 综合题
+
+1. 用一句话解释“夏普比率”和“最大回撤”各自解决什么问题。
+
+??? note "参考答案要点（先独立思考再展开）"
+
+    **基础题**：收益率、夏普、最大回撤等**比率类指标基本不变**（它们是相对值），变化的主要是绝对金额（如 `total_pnl`、`end_market_value` 按比例放大）。这说明评估策略应看比率而非绝对额。
+
+    **应用题**：换标的后累计收益与最大回撤往往明显不同，体现策略对标的与区间的敏感性——同一组参数在不同标的上并不一定稳健。
+
+    **综合题**：夏普比率衡量"每承担一单位风险能换多少超额收益"（性价比）；最大回撤衡量"最坏情况下资金从峰值缩水多少"（生存风险与持有体验）。
 
 ## 常见错误与排查
 

akquant-0.2.47/docs/zh/textbook/02_programming.md

@@ -0,0 +1,247 @@
+# 第 2 章：量化编程基础
+
+> ⏱️ 预计阅读 ~20 分钟 ｜ 🎯 难度 ★★☆☆☆（入门）
+
+量化投资是金融与计算机的交叉学科。对于金融背景的同学来说，编程往往是最大的拦路虎。本章不求把你培养成软件工程师，只求教给你在量化战场上**生存**所需的最小技能集。
+
+## 学习目标
+
+- 掌握量化开发最常用的 Pandas、NumPy 与 Matplotlib 基础操作。
+- 理解向量化、类型注解和最小工程规范在量化代码中的实际价值。
+- 形成调试、版本控制与并行计算的入门工程化意识。
+
+## 前置知识
+
+- 掌握 Python 基本语法、函数与列表/字典等数据结构。
+- 能读懂简单的 DataFrame 与数组示例。
+
+## 本章实践入口
+
+- 主示例：[examples/textbook/ch02_programming.py](https://github.com/akfamily/akquant/blob/main/examples/textbook/ch02_programming.py)
+- 进阶示例：[examples/17_readme_demo.py](https://github.com/akfamily/akquant/blob/main/examples/17_readme_demo.py)
+- 对应指南：[Python 基础](../guide/python_basics.md)
+
+## 快速运行与验收
+
+```bash
+python examples/textbook/ch02_programming.py
+```
+
+验收要点：
+
+1. 脚本完整运行，无语法错误或依赖错误。
+2. 输出包含 Pandas、NumPy 或类型注解相关演示结果。
+3. 能独立修改一段参数并重新运行验证结果变化。
+
+## 2.1 Python for Quant
+
+Python 之所以成为量化领域的霸主，归功于其强大的科学计算生态。你必须熟练掌握以下三个库：**Pandas**, **NumPy**, **Matplotlib**。
+
+### 2.1.1 Pandas：表格处理神器
+
+Pandas 是 Python 中的 Excel，但比 Excel 强大得多。它建立在两个核心数据结构之上：**Series** 是一列带索引的数据，而 **DataFrame** 则是一张表格，由多列数据组成，同时带有行索引和列索引。在量化中，我们通常将时间 (`datetime`) 作为索引，这样的 DataFrame 就被称为**时间序列 (Time Series)**。
+
+**核心操作**：
+
+1.  **索引与切片 (Slicing)**：
+    *   `df.loc["2023-01-01":"2023-01-31"]`: 获取一月的所有数据。
+    *   `df.iloc[-1]`: 获取最后一行数据。
+
+2.  **重采样 (Resampling)**：
+    *   `df.resample("1W").last()`: 将日线数据转换为周线数据（取每周最后一天）。
+    *   `df.resample("5min").ohlc()`: 将 Tick 数据聚合为 5分钟 K 线。
+
+3.  **滚动窗口 (Rolling)**：
+    *   `df["close"].rolling(20).mean()`: 计算 20 日移动平均线 (MA20)。
+    *   `df["close"].rolling(20).std()`: 计算 20 日波动率。
+
+4.  **缺失值处理 (Handling Missing Data)**：
+    *   `df.fillna(method="ffill")`: 前向填充（用昨天的数据填补今天的空缺），这是金融数据最常用的填充方式。
+    *   `df.dropna()`: 直接丢弃包含空值的行。
+
+### 2.1.2 NumPy：向量化思维
+
+向量化是初学者最难转变的思维定势。**人类思维 (Loop)** 习惯逐行读取数据、计算、再写入下一行；而**量化思维 (Vectorization)** 则直接操作整个向量（列）。以计算 100 万个数据的平方为例，前者要写一个 100 万次的循环，既慢又代码冗余，后者只需 `arr ** 2` 一行代码，底层由 C/Fortran 优化，速度比 Loop 快 10-100 倍。
+
+与向量化相辅相成的是**广播机制 (Broadcasting)**：NumPy 允许不同形状的数组进行数学运算，例如 `prices - 100`，会自动将 100 减去数组中的每一个元素。
+
+### 2.1.3 Matplotlib：数据可视化
+
+虽然现在有 Plotly 等交互式库，但 Matplotlib 依然是基础。
+`AKQuant` 的 `plot_result` 就是基于 Matplotlib 开发的。
+
+**常用功能**：
+
+*   `plt.plot(x, y)`: 绘制折线图。
+*   `plt.bar(x, y)`: 绘制柱状图。
+*   `plt.subplots()`: 创建多子图（例如上图画 K 线，下图画成交量）。
+
+## 2.2 Rust 概念入门 (Conceptual)
+
+`AKQuant` 的底层回测引擎是由 Rust 编写的。你不需要会写 Rust，但了解其核心概念有助于你理解报错信息和 API 设计。
+
+### 2.2.1 为什么是 Rust?
+
+选择 Rust 主要出于两点考量。其一是**速度**：Rust 与 C++ 相当，比 Python 快 10-100 倍，这对于遍历数百万根 K 线的回测至关重要。其二是**安全**：Rust 的编译器极其严格，杜绝了“空指针异常”和“内存泄漏”，这意味着 `AKQuant` 极其稳定，很难崩溃。
+
+### 2.2.2 内存安全与所有权 (Ownership)
+
+在 Python 中，不仅有垃圾回收 (GC)，变量还只是对象的引用；而在 Rust 中，每个值都有一个**所有者 (Owner)**。所有权主要通过两条规则体现：**Move** 指当你把值赋给另一个变量时，所有权就转移了，原来的变量随之失效，从而避免了“悬垂指针”；**Borrow** 则允许你“借用”数据（引用），但必须遵守规则，即同一时间只能有一个可变借用。这听起来很复杂，但在 `AKQuant` 的 Python 接口中，你通常感受不到它的存在，因为底层已经处理好了。
+
+### 2.2.3 类型系统 (Type System)
+
+Python 是动态类型（变量可以是任何东西），Rust 则是静态类型（变量类型必须确定）。在 Rust 的类型系统中，有两个泛型容器格外值得理解。其一是 **`Option<T>`**，它代表“可能有值，也可能为空”，对应 Python 的 `Optional[T]` 或 `None`——例如在策略中，`get_position(symbol)` 返回的可能就是 `Option`，如果没持仓就返回 `None`。其二是 **`Result<T, E>`**，它代表“成功返回 T，或失败返回错误 E”——例如下单函数可能会返回 `Result`，你需要检查是否下单成功。
+
+## 2.3 工程化思维 (Engineering Mindset)
+
+写策略不仅仅是写数学公式，更是构建一个软件系统。
+
+### 2.3.1 版本控制 (Git)
+
+永远不要把文件命名为 `strategy_final_v2_really_final.py`。
+学会使用 **Git** 来管理代码的历史版本。
+
+*   `git init`: 初始化仓库。
+*   `git add .` & `git commit -m "update strategy"`: 保存快照。
+*   `git checkout`: 回滚到之前的版本。
+
+### 2.3.2 调试技巧 (Debugging)
+
+*   **Print Debugging**：最简单但最有效。在关键位置打印变量值。
+*   **断点调试**：使用 VS Code 的调试功能，设置断点，单步执行，查看变量状态。这比 print 高效得多。
+
+## 2.4 向量化进阶 (Advanced Vectorization)
+
+在量化中，速度就是生命。除了基本的数组运算，你还需要掌握更高级的技巧。
+
+### 2.4.1 条件选择：`np.where`
+
+替代 Python 的 `if-else`。
+```python
+# 如果收益率 > 0，标记为 1 (Win)，否则为 0 (Loss)
+wins = np.where(returns > 0, 1, 0)
+```
+
+### 2.4.2 快速查找：`np.searchsorted`
+
+在一个有序数组中查找插入位置（二分查找），复杂度 $O(\log N)$。
+这在回测撮合引擎中非常有用：比如查找订单价格在 LOB 中的位置。
+
+### 2.4.3 表达式加速：`pd.eval`
+
+Pandas 在计算复杂表达式时会产生大量中间临时变量，占用内存且拖慢速度。`pd.eval` 使用 NumExpr 后端，一次性计算整个表达式。
+
+```python
+# 传统写法
+df['result'] = (df['A'] + df['B']) * (df['C'] - df['D'])
+
+# 加速写法
+df.eval('result = (A + B) * (C - D)', inplace=True)
+```
+
+## 2.5 设计模式 (Design Patterns)
+
+虽然量化代码不像企业级软件那么庞大，但良好的设计模式能让策略更易扩展。
+
+1.  **工厂模式 (Factory)**：用于创建不同类型的对象。
+    *   例如 `IndicatorFactory.create("RSI", period=14)`，根据字符串创建具体的指标对象，避免写一堆 `if type == "RSI": ... elif ...`。
+2.  **单例模式 (Singleton)**：确保全局只有一个实例。
+    *   例如 `GlobalConfig` 或 `Logger`，整个回测系统中只需要一份配置。
+3.  **观察者模式 (Observer)**：解耦事件源与处理逻辑。
+    *   `AKQuant` 的核心架构就是观察者模式。`EventBus` 是被观察者，`Strategy` 和 `RiskManager` 是观察者。当有新行情 (`MarketEvent`) 时，总线通知所有观察者，而不是硬编码调用 `strategy.on_bar()`。
+
+## 2.6 并行计算 (Parallel Computing)
+
+Python 的全局解释器锁 (GIL) 限制了多线程的 CPU 密集型任务。但在参数优化 (Grid Search) 时，我们可以利用多进程 (Multiprocessing) 跑满所有 CPU 核心。
+
+```python
+from multiprocessing import Pool
+
+def backtest_one_param(param):
+    # 回测逻辑...
+    return sharpe_ratio
+
+if __name__ == '__main__':
+    params = [10, 20, 30, ..., 100]
+    with Pool(processes=8) as pool:
+        results = pool.map(backtest_one_param, params)
+```
+
+`AKQuant` 的优化模块已内置了并行计算支持。
+
+## 2.7 代码演练
+
+下面的脚本演示了 Pandas 和 NumPy 的核心操作，以及如何在 Python 中使用 Type Hints 模拟强类型编程。
+
+```python
+--8<-- "examples/textbook/ch02_programming.py"
+```
+
+---
+
+## 本章小结
+
+### 必须掌握
+
+- 量化代码的核心能力是数据处理、数值计算与结果可视化。
+- 向量化思维、类型注解与最小工程规范能显著降低策略迭代成本。
+
+### 理解即可
+
+- Rust 的所有权与类型系统有助于理解 AKQuant 的接口设计与报错语义。
+
+### 实践提醒
+
+- 优先练熟索引、滚动窗口、缺失值处理与调试，再追求更复杂的模式。
+
+## 主线推进
+
+本章没有改写贯穿全书的最小双均线策略本身，而是为它备齐了“施工工具”。第 1 章跑通的那个 MA5/MA20 策略，在 `on_bar` 回调里通过 `get_history(count=self.long_window, field="close")` 取最近收盘价、计算两条均线并比较其大小来产生金叉/死叉信号——本章正是把这背后的通用能力逐一拆解：用 Pandas 的滚动窗口 `df["close"].rolling(20).mean()` 计算均线、用向量化思维一次性处理整列数据，都在 2.1 节得到系统讲解。理解了向量化、缺失值处理与时间序列索引，你才能在后续章节里读懂、修改并最终自己写出这条主线策略的信号逻辑；理解了 Rust 的所有权与 `Option`/`Result`，你也能在调用 `get_position`、下单等接口时正确处理“可能为空”和“可能失败”的返回值。至此，主线策略从“能跑通的示例”推进到了“看得懂每一行的可改造对象”。
+
+## 延伸阅读
+
+**经典著作**
+
+- McKinney, W. *Python for Data Analysis*（《利用 Python 进行数据分析》，第 3 版），O'Reilly Media, 2022 —— Pandas 作者亲笔，系统讲解 Series/DataFrame、索引切片、重采样与缺失值处理，可与本章 2.1 对照精读。
+- Hilpisch, Y. J. *Python for Finance: Mastering Data-Driven Finance*（第 2 版），O'Reilly Media, 2018 —— 以金融场景贯穿 NumPy 向量化与 pandas 数据处理，呼应本章 2.1 与 2.4 的向量化进阶。
+- Klabnik, S., & Nichols, C. *The Rust Programming Language*（第 2 版），No Starch Press, 2023 —— Rust 官方教程，权威讲解所有权、借用与 `Option`/`Result` 类型系统，对应本章 2.2 的概念。
+
+**官方文档与工具**
+
+- [pandas 官方文档](https://pandas.pydata.org/docs/) —— 本章 2.1 涉及的索引、重采样、滚动窗口与 `pd.eval` 的权威参考。
+- [NumPy 官方文档](https://numpy.org/doc/stable/) —— 配合本章 2.1.2 与 2.4 理解广播、`np.where`、`np.searchsorted` 等向量化操作。
+- [Matplotlib 官方文档](https://matplotlib.org/stable/) —— 对应本章 2.1.3 的可视化基础。
+- [Git 官方文档](https://git-scm.com/doc) —— 对应本章 2.3.1 的版本控制实践。
+
+**本书相关**
+
+- [Python 基础](../guide/python_basics.md) —— 巩固本章 2.1 的 Pandas/NumPy 入门操作。
+- [快速开始](../start/quickstart.md) —— 把本章工程化与向量化技能落到第一个可运行的 AKQuant 策略上。
+
+## 课后练习
+
+### 基础题
+
+1. 把示例中的滚动窗口从 `20` 改为 `10`，观察输出差异。
+
+### 应用题
+
+1. 给一个函数补充完整类型注解并运行静态检查。
+
+### 综合题
+
+1. 用 `multiprocessing.Pool` 改写一个小型参数扫描脚本。
+
+??? note "参考答案要点（先独立思考再展开）"
+
+    **基础题**：窗口从 20 改为 10，均线更敏感、对噪声反应更快，warmup 区段（前 N-1 个 NaN）也更短。
+
+    **应用题**：为参数与返回值补 `def f(x: int) -> float:` 之类注解，用 `mypy` / `ruff` 静态检查；注意 `Optional[...]` 与容器泛型（`list[int]` 等）。
+
+    **综合题**：把单次回测封装成函数，用 `with Pool(processes=N) as pool: pool.map(fn, params)` 并行；入口务必放在 `if __name__ == "__main__":` 下（Windows 的 spawn 必需）。
+
+## 常见错误与排查
+
+1. 切片结果异常：优先检查 `loc` 与 `iloc` 的使用场景是否混淆。
+2. 维度报错：确认 NumPy 向量形状一致后再计算。
+3. 进程卡死：把多进程入口放在 `if __name__ == "__main__":` 下。