Merge pull request #185 from akfamily/dev

docs: 补充并行优化日志回传与严格参数校验的文档与测试

Author: albertandking

Cargo.lock

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

Cargo.toml

@@ -142,6 +142,12 @@ results = run_grid_search(
 *   `result_filter`: (Optional) Callback function to filter results based on metrics.
 *   `warmup_calc`: (Optional) Callback function for dynamic warmup period calculation.
 *   `constraint`: (Optional) Callback function for parameter constraints to filter invalid combinations.
+*   `forward_worker_logs`: (Optional) Whether to forward worker-process `self.log()` output to the main process during parallel optimization.
+    *   `False` (default): Better throughput, worker logs may not be visible in main process output.
+    *   `True`: Main process aggregates worker logs, useful for debugging and teaching.
+*   `strict_strategy_params`: (default `True`, injected by `run_grid_search` into `run_backtest`).
+    *   Enforces strict validation between `param_grid` keys and strategy constructor signature.
+    *   Raises fast on unknown parameters to avoid silent fallback and distorted optimization results.
 
 ### Resource Control & Error Handling
 
@@ -187,6 +193,14 @@ if __name__ == "__main__":
     main()
 ```
 
+### Parallel Log Visibility & Warning Rules
+
+When `max_workers > 1`, warning behavior is tied to `forward_worker_logs`:
+
+*   `forward_worker_logs=False`: warns that worker logs may not be visible in the main process.
+*   `forward_worker_logs=True` with active main-process logger handlers: log forwarding is enabled and visibility warning is suppressed.
+*   `forward_worker_logs=True` without active main-process handlers: warns that forwarding was requested but no handler is available.
+
 ### Persistence & Resume
 
 For scenarios with extremely large parameter sets (e.g., > 10,000 combinations), running on a single machine might take days. AKQuant supports real-time result persistence to SQLite, enabling breakpoint resume.
@@ -245,7 +259,10 @@ wfo_results = run_walk_forward(
     metric="sharpe_ratio", # Optimization target
     initial_cash=100_000.0,
     warmup_calc=warmup_calc, # Support dynamic warmup
-    constraint=param_constraint # Support parameter constraints
+    constraint=param_constraint, # Support parameter constraints
+    max_workers=4,
+    forward_worker_logs=True,    # Forward in-sample worker logs
+    strict_strategy_params=True, # Keep strict constructor validation
 )
 
 # wfo_results contains the concatenated equity curve and parameters used for each segment
@@ -257,6 +274,10 @@ print(wfo_results)
 *   `train_period`: Training window length (number of Bars). Longer windows mean more stable parameters; shorter windows adapt faster to changes.
 *   `test_period`: Test window length (number of Bars). Usually also the rolling step size.
 *   `metric`: The metric used to select optimal parameters on the training set (e.g., `sharpe_ratio`, `total_return`).
+*   `kwargs` passthrough rules:
+    *   forwarded to `run_grid_search` during in-sample optimization;
+    *   forwarded to `run_backtest` during out-of-sample validation;
+    *   therefore `forward_worker_logs` and `strict_strategy_params` remain available in WFO.
 
 ---
 

docs/en/guide/optimization.md

@@ -60,6 +60,7 @@ def run_backtest(
     broker_profile: Optional[str] = None,
     timer_execution_policy: Literal["same_cycle", "next_event"] = "same_cycle",
     fill_policy: Optional[Dict[str, str]] = None,
+    strict_strategy_params: bool = True,
     **kwargs: Any,
 ) -> BacktestResult
 ```
@@ -82,6 +83,9 @@ def run_backtest(
     *   `price_basis`: `next_open`, `current_close`, `ohlc4` (OHLC average), or `hl2` (high-low midpoint).
     *   Reserved (not implemented yet): `mid_quote`, `vwap_window`, `twap_window` (currently raises `NotImplementedError`).
     *   `temporal`: `same_cycle` or `next_event`.
+*   `strict_strategy_params`: Whether to strictly validate strategy constructor parameters (default `True`).
+    *   Raises immediately if unsupported constructor parameters are provided.
+    *   Recommended to keep enabled to avoid silent parameter mismatch and distorted backtest results.
 *   `t_plus_one`: Enable T+1 trading rule (Default False). If enabled, it forces usage of China Market Model.
 *   `slippage`: Global slippage (Default 0.0). E.g., 0.0001 means 1bp (0.01%) slippage, using percent model.
 *   `volume_limit_pct`: Volume limit percentage (Default 0.25). Limits single trade to not exceed this percentage of the bar's total volume.
@@ -112,6 +116,70 @@ def run_backtest(
 | `execution_mode="next_average"` | `fill_policy={"price_basis":"ohlc4","temporal":"same_cycle"}` |
 | `execution_mode="next_high_low_mid"` | `fill_policy={"price_basis":"hl2","temporal":"same_cycle"}` |
 
+### `akquant.run_grid_search`
+
+Grid-search entry for batch backtesting and metric-based parameter ranking.
+
+```python
+def run_grid_search(
+    strategy: Type[Strategy],
+    param_grid: Dict[str, Sequence[Any]],
+    data: Union[pd.DataFrame, Dict[str, pd.DataFrame], List[Bar]],
+    sort_by: Union[str, List[str]] = "sharpe_ratio",
+    ascending: Union[bool, List[bool]] = False,
+    return_df: bool = True,
+    result_filter: Optional[Callable[[Dict[str, Any]], bool]] = None,
+    constraint: Optional[Callable[[Dict[str, Any]], bool]] = None,
+    max_workers: Optional[int] = None,
+    show_progress: bool = True,
+    timeout: Optional[float] = None,
+    max_tasks_per_child: Optional[int] = None,
+    db_path: Optional[str] = None,
+    forward_worker_logs: bool = False,
+    **kwargs: Any,
+) -> Union[pd.DataFrame, List[OptimizationResult]]
+```
+
+**Key parameter notes:**
+
+*   `forward_worker_logs`: Whether to forward worker-process strategy logs to the main process during parallel optimization.
+    *   `False`: throughput-first; worker logs may be invisible in main-process output.
+    *   `True`: enables log aggregation for debugging.
+*   `strict_strategy_params`: Passed via `**kwargs` into `run_backtest` (defaulted to `True` inside `run_grid_search`).
+    *   Enforces strict match between `param_grid` keys and strategy constructor parameters.
+    *   Fails fast on mismatch to avoid silent fallback.
+
+### `akquant.run_walk_forward`
+
+Walk-forward entry. Executes rolling "in-sample optimization + out-of-sample validation" and concatenates OOS equity curves.
+
+```python
+def run_walk_forward(
+    strategy: Type[Strategy],
+    param_grid: Mapping[str, Sequence[Any]],
+    data: pd.DataFrame,
+    train_period: int,
+    test_period: int,
+    metric: Union[str, List[str]] = "sharpe_ratio",
+    ascending: Union[bool, List[bool]] = False,
+    initial_cash: float = 100_000.0,
+    warmup_period: int = 0,
+    warmup_calc: Optional[Any] = None,
+    constraint: Optional[Any] = None,
+    result_filter: Optional[Any] = None,
+    compounding: bool = False,
+    timeout: Optional[float] = None,
+    max_tasks_per_child: Optional[int] = None,
+    **kwargs: Any,
+) -> pd.DataFrame
+```
+
+**Key parameter notes:**
+
+*   `**kwargs` are forwarded to both `run_grid_search` (in-sample optimization) and `run_backtest` (out-of-sample validation).
+*   Therefore, `forward_worker_logs` controls worker-log forwarding during in-sample parallel optimization.
+*   `strict_strategy_params` stays effective across optimization and validation phases (strict by default).
+
 ### `akquant.run_warm_start`
 
 Resume a backtest from snapshot state and continue execution.

docs/en/reference/api.md

@@ -9,6 +9,33 @@ This chapter is currently maintained in Chinese first.
   - Extended example: [examples/02_parameter_optimization.py](https://github.com/akfamily/akquant/blob/main/examples/02_parameter_optimization.py)
   - Guide: [Optimization Guide](../guide/optimization.md)
 
+Key optimization parameters (new):
+
+- `forward_worker_logs` in `run_grid_search`:
+  - `False` (default): better throughput; worker `self.log()` may not be visible in main process output.
+  - `True`: forwards worker logs to the main process for debugging and teaching.
+- `strict_strategy_params` in `run_backtest` (default `True`):
+  - enforces strict constructor parameter validation;
+  - fails fast on unknown strategy parameters to avoid silent fallback and misleading optimization results.
+- `run_walk_forward` accepts these options via `**kwargs` passthrough:
+  - `forward_worker_logs` applies to in-sample optimization (`run_grid_search`);
+  - `strict_strategy_params` stays effective in both optimization and OOS validation.
+
+WFO passthrough example:
+
+```python
+wfo_results = run_walk_forward(
+    strategy=TailTradingStrategy,
+    param_grid=param_grid,
+    data=all_data,
+    train_period=250,
+    test_period=60,
+    max_workers=4,
+    forward_worker_logs=True,
+    strict_strategy_params=True,
+)
+```
+
 Windows note for parallel optimization (`max_workers > 1`):
 
 - Define strategy classes in an importable module, not in `__main__`.

docs/en/textbook/11_optimization.md

@@ -142,6 +142,12 @@ results = run_grid_search(
 *   `result_filter`: (可选) 结果筛选回调函数，用于过滤不符合条件的组合。
 *   `warmup_calc`: (可选) 动态计算预热期的回调函数。
 *   `constraint`: (可选) 参数约束回调函数，用于过滤无效组合。
+*   `forward_worker_logs`: (可选) 并行优化时是否将子进程 `self.log()` 回传到主进程日志。
+    *   `False` (默认): 性能更优，日志可能在主进程不可见。
+    *   `True`: 主进程可聚合子进程日志，适合排障与教学演示。
+*   `strict_strategy_params`: (默认 `True`，由 `run_grid_search` 注入到 `run_backtest`)。
+    *   启用后会严格校验 `param_grid` 是否与策略构造函数参数匹配；
+    *   发现未知参数时立即抛错，避免“静默回退”导致优化结果失真。
 
 ### 资源控制与异常处理 (Resource Control & Error Handling)
 
@@ -187,6 +193,14 @@ if __name__ == "__main__":
     main()
 ```
 
+### 并行日志可见性与提示规则
+
+在 `max_workers > 1` 场景下，日志提示与 `forward_worker_logs` 的关系如下：
+
+*   `forward_worker_logs=False`：会提示“子进程日志可能在主进程不可见”。
+*   `forward_worker_logs=True` 且主进程存在有效 logger handler：启用日志回传，不再显示“不可见”提示。
+*   `forward_worker_logs=True` 但主进程无有效 logger handler：会提示“请求了日志回传但主进程无可用 handler”。
+
 ### 持久化与断点续传 (Persistence & Resume)
 
 对于参数组合极多（如 > 10,000 组）的场景，单机运行可能需要数小时甚至数天。如果中途断电或程序崩溃，重新运行将非常耗时。AKQuant 支持将优化结果实时写入 SQLite 数据库，并支持断点续传。
@@ -245,7 +259,10 @@ wfo_results = run_walk_forward(
     metric="sharpe_ratio", # 优化目标
     initial_cash=100_000.0,
     warmup_calc=warmup_calc, # 支持动态预热
-    constraint=param_constraint # 支持参数约束
+    constraint=param_constraint, # 支持参数约束
+    max_workers=4,
+    forward_worker_logs=True,    # 样本内并行优化日志回传
+    strict_strategy_params=True, # 严格参数校验（推荐保持开启）
 )
 
 # wfo_results 包含拼接后的资金曲线和每段使用的参数
@@ -259,6 +276,10 @@ print(wfo_results)
 *   `metric`: 在训练集上选择最优参数的依据指标。支持单个字符串 (如 `"sharpe_ratio"`) 或字符串列表 (如 `["sharpe_ratio", "total_return"]`)。
 *   `ascending`: 排序方向，与 `metric` 对应。支持布尔值或布尔值列表 (默认 `False`，即降序)。
 *   `result_filter`: (可选) 结果筛选回调函数，在每个训练窗口中过滤不符合条件的参数组合。
+*   `kwargs` 透传规则：
+    *   样本内优化阶段透传给 `run_grid_search`；
+    *   样本外验证阶段透传给 `run_backtest`；
+    *   因此可在 WFO 中继续使用 `forward_worker_logs` 与 `strict_strategy_params`。
 
 ---
 

docs/zh/guide/optimization.md

@@ -47,10 +47,75 @@ def run_backtest(
     broker_profile: Optional[str] = None,
     timer_execution_policy: Literal["same_cycle", "next_event"] = "same_cycle",
     fill_policy: Optional[Dict[str, str]] = None,
+    strict_strategy_params: bool = True,
     **kwargs: Any,
 ) -> BacktestResult
 ```
 
+### `akquant.run_grid_search`
+
+参数网格搜索入口，用于批量回测并按指标排序返回最优参数组合。
+
+```python
+def run_grid_search(
+    strategy: Type[Strategy],
+    param_grid: Dict[str, Sequence[Any]],
+    data: Union[pd.DataFrame, Dict[str, pd.DataFrame], List[Bar]],
+    sort_by: Union[str, List[str]] = "sharpe_ratio",
+    ascending: Union[bool, List[bool]] = False,
+    return_df: bool = True,
+    result_filter: Optional[Callable[[Dict[str, Any]], bool]] = None,
+    constraint: Optional[Callable[[Dict[str, Any]], bool]] = None,
+    max_workers: Optional[int] = None,
+    show_progress: bool = True,
+    timeout: Optional[float] = None,
+    max_tasks_per_child: Optional[int] = None,
+    db_path: Optional[str] = None,
+    forward_worker_logs: bool = False,
+    **kwargs: Any,
+) -> Union[pd.DataFrame, List[OptimizationResult]]
+```
+
+**关键参数补充:**
+
+*   `forward_worker_logs`: 并行优化时是否将子进程策略日志回传到主进程。
+    *   `False`：吞吐优先，日志可能在主进程不可见。
+    *   `True`：启用日志聚合，便于排障。
+*   `strict_strategy_params`: 通过 `**kwargs` 传递给 `run_backtest`（默认在 `run_grid_search` 内为 `True`）。
+    *   严格校验 `param_grid` 与策略构造参数匹配关系；
+    *   参数不匹配时快速失败，避免静默回退。
+
+### `akquant.run_walk_forward`
+
+滚动优化入口。按窗口执行“样本内参数优化 + 样本外验证”，并拼接样本外资金曲线。
+
+```python
+def run_walk_forward(
+    strategy: Type[Strategy],
+    param_grid: Mapping[str, Sequence[Any]],
+    data: pd.DataFrame,
+    train_period: int,
+    test_period: int,
+    metric: Union[str, List[str]] = "sharpe_ratio",
+    ascending: Union[bool, List[bool]] = False,
+    initial_cash: float = 100_000.0,
+    warmup_period: int = 0,
+    warmup_calc: Optional[Any] = None,
+    constraint: Optional[Any] = None,
+    result_filter: Optional[Any] = None,
+    compounding: bool = False,
+    timeout: Optional[float] = None,
+    max_tasks_per_child: Optional[int] = None,
+    **kwargs: Any,
+) -> pd.DataFrame
+```
+
+**关键参数补充:**
+
+*   `**kwargs` 会透传到 `run_grid_search`（样本内优化阶段）与 `run_backtest`（样本外验证阶段）。
+*   因此，`forward_worker_logs` 可用于控制样本内并行优化日志回传。
+*   同时，`strict_strategy_params` 会在优化与回测阶段保持严格参数校验语义（默认严格）。
+
 ### `akquant.run_warm_start`
 
 从快照恢复并继续运行回测（支持多策略 slot 执行）。
@@ -102,6 +167,9 @@ def run_warm_start(
     *   `price_basis`: `next_open`、`current_close`、`ohlc4`（OHLC 平均价）或 `hl2`（高低中价）。
     *   预留（暂未实现）: `mid_quote`、`vwap_window`、`twap_window`（当前会抛出 `NotImplementedError`）。
     *   `temporal`: `same_cycle` 或 `next_event`。
+*   `strict_strategy_params`: 是否严格校验策略构造参数（默认 `True`）。
+    *   当传入策略不接受的参数时会立即抛错；
+    *   推荐保持默认值，避免参数错配被静默忽略导致回测结果偏差。
 *   `t_plus_one`: 是否启用 T+1 交易规则 (默认 False)。如果启用，将强制使用中国市场模型。
 *   `slippage`: 全局滑点 (默认 0.0)。例如 0.0001 代表 1bp (0.01%) 的滑点，采用百分比模型。
 *   `volume_limit_pct`: 成交量限制比例 (默认 0.25)。限制单笔成交不超过该 Bar 总成交量的百分比。

docs/zh/reference/api.md

@@ -157,6 +157,47 @@ class SmaStrategy(Strategy):
 --8<-- "examples/textbook/ch11_optimization.py"
 ```
 
+### 11.4.2A 新参数（并行日志与严格参数校验）
+
+为提升优化可观测性与结果可靠性，推荐关注以下参数：
+
+*   `forward_worker_logs`（`run_grid_search`）：
+    *   `False`（默认）：性能优先，子进程日志可能在主进程不可见；
+    *   `True`：将子进程 `self.log()` 聚合回主进程，适合排障与教学演示。
+*   `strict_strategy_params`（`run_backtest`，默认 `True`）：
+    *   严格校验策略构造参数；
+    *   当 `param_grid` 中存在策略不接受的参数时，立即抛错，避免静默回退导致“看似跑完但结果无效”。
+*   `run_walk_forward` 也支持通过 `**kwargs` 透传这两个参数：
+    *   `forward_worker_logs` 作用于样本内优化阶段（内部 `run_grid_search`）；
+    *   `strict_strategy_params` 在样本内优化与样本外验证阶段都生效。
+
+示例：
+
+```python
+results = run_grid_search(
+    strategy=TailTradingStrategy,
+    param_grid=param_grid,
+    data=all_data,
+    max_workers=4,
+    forward_worker_logs=True,
+)
+```
+
+WFO 传导示例：
+
+```python
+wfo_results = run_walk_forward(
+    strategy=TailTradingStrategy,
+    param_grid=param_grid,
+    data=all_data,
+    train_period=250,
+    test_period=60,
+    max_workers=4,
+    forward_worker_logs=True,
+    strict_strategy_params=True,
+)
+```
+
 ### 11.4.3 结果分析
 
 运行上述代码后，我们会得到一个按夏普比率排序的参数表。

docs/zh/textbook/11_optimization.md

@@ -75,10 +75,6 @@
     *   因子表达式的原理与优势
     *   Polars 高性能计算架构
     *   案例：Alpha101 因子实战 ([examples/textbook/ch14_factor.py](https://github.com/akfamily/akquant/blob/main/examples/textbook/ch14_factor.py))
-*   **[第 16 章：AKQuant 指标全景与工程化使用](16_rust_indicators.md)**
-    *   AKQuant 支持的 103 个指标分类、解释与 warmup 口径
-    *   指标词典与教学脚手架联动（见 [AKQuant 指标全量说明](../guide/rust_indicator_reference.md)）
-
 ### 第五部分：从回测到实盘 (Live Trading)
 
 *   **[第 15 章：实盘交易系统与运维](15_live_trading.md)**
@@ -87,6 +83,12 @@
     *   进阶示例：动态策略加载与运行时注入 ([examples/textbook/ch15_strategy_loader.py](https://github.com/akfamily/akquant/blob/main/examples/textbook/ch15_strategy_loader.py))
     *   风控与熔断机制
 
+### 第六部分：指标工程与工具链 (Indicator Engineering)
+
+*   **[第 16 章：AKQuant 指标全景与工程化使用](16_rust_indicators.md)**
+    *   AKQuant 支持的 103 个指标分类、解释与 warmup 口径
+    *   指标词典与教学脚手架联动（见 [AKQuant 指标全量说明](../guide/rust_indicator_reference.md)）
+
 ## 章节示例映射（主示例 / 进阶示例 / 对应指南）
 
 | 章节 | 主示例 | 进阶示例 | 对应指南 |