akquant 0.2.47__tar.gz → 0.2.48__tar.gz

{akquant-0.2.47 → akquant-0.2.48}/CHANGELOG.md

@@ -7,7 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- `BacktestConfig` 新增 `days_per_year`（年化天数因子，默认 252；数字货币 24/7 市场可设 365）与 `risk_free_rate`（年化无风险利率，默认 0.0）两个字段，用于参数化 Sharpe/Sortino/波动率等风险指标的年化口径。`risk_free_rate` 默认 0 不改变任何现有数值。
+
 ### Changed
+- **回测指标口径变更（破坏性）**：Sharpe / Sortino 比率的分子改为「日收益算术均值 × `days_per_year`」做年化，替代原先的 CAGR（复合年化），与 pyfolio/empyrical/quantstats 等主流实现一致，并与分母 `√days_per_year` 的年化口径匹配。升级后历史报告的 Sharpe/Sortino 数值会变化，不可直接与旧版逐值对比；UPI 与 Calmar 仍沿用 CAGR 口径。
 - 策略交易日边界回调已硬切改名：`before_trading(trading_date, timestamp)` 更名为 `on_before_trading(trading_date, timestamp)`，`after_trading(trading_date, timestamp)` 更名为 `on_after_trading(trading_date, timestamp)`。
 - 旧回调名不再保留兼容别名；升级到当前版本后，若策略仍实现 `before_trading` / `after_trading`，将不会再被框架触发，请同步迁移到新名称。
 - 新增 `on_pre_open(event)` 框架回调，用于表达“盘前决策，本次 open 成交”；该回调默认下单语义会自动解析为 `price_basis=open, bar_offset=1, temporal=same_cycle`，不再要求用户自行用 `on_timer` 拼装开盘成交时序。
@@ -17,6 +21,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - 示例体系新增 `examples/52_pre_open_demo.py`，用于演示 `on_pre_open -> on_order/on_trade -> on_bar` 的触发顺序与当日 open 成交语义。
 
 ### Fixed
+- 修复短回测区间下 Sharpe/Sortino 因「分子用 CAGR、分母用日波动 × √252」口径不一致而出现异常巨大值（如期货场景 Sharpe 高达数千万）的问题；改用日收益算术均值年化后数值回归合理量级。
 - 修复 `on_timer` / `add_daily_timer` 场景下，订单级 `fill_policy={"price_basis":"close","bar_offset":0,"temporal":"same_cycle"}` 未在当日 timer 事件内生效的问题；相关卖单现在会按当日 timer 时间与当日 close 成交，不再延后到下一交易日。
 - 修复 framework 内部 `__framework_rebalance__` / `__framework_boundary__` timer 被误参与 same-cycle 撮合与终态统计的问题，避免出现 `+1ns` 的伪成交、partial fill 被过早补满，以及权益曲线尾部多出额外采样点。
 - 修复 `on_pre_open` 首个交易日可能因延迟注册 timer 而不触发的问题；相关 framework timer 现会在回测事件循环开始前直接注入引擎，从而保证首日也能按预期开盘语义执行。

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

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

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

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: akquant
-Version: 0.2.47
+Version: 0.2.48
 Classifier: Programming Language :: Rust
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Programming Language :: Python :: Implementation :: PyPy

{akquant-0.2.47 → akquant-0.2.48}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "akquant"
-version = "0.2.47"
+version = "0.2.48"
 description = "High-performance quantitative trading framework based on Rust and Python"
 readme = "README.md"
 license = {text = "MIT License"}

{akquant-0.2.47 → akquant-0.2.48}/python/akquant/__init__.py

@@ -8,7 +8,7 @@ try:
 except metadata.PackageNotFoundError:
     __version__ = "0.0.0+unknown"
 
-__engine_rule_version__ = "1.0.0"  # Increment on behavior-changing updates
+__engine_rule_version__ = "1.1.0"  # Increment on behavior-changing updates
 
 from . import akquant as _akquant
 from . import log as _log

{akquant-0.2.47 → akquant-0.2.48}/python/akquant/backtest/engine.py

@@ -3313,6 +3313,14 @@ def run_backtest(
             raise ValueError(f"Invalid timezone: {timezone}")
         offset = int(offset_delta.total_seconds())
         engine.set_timezone(offset)
+    if hasattr(engine, "set_days_per_year"):
+        cast(Any, engine).set_days_per_year(
+            getattr(config, "days_per_year", 252.0) if config else 252.0
+        )
+    if hasattr(engine, "set_risk_free_rate"):
+        cast(Any, engine).set_risk_free_rate(
+            getattr(config, "risk_free_rate", 0.0) if config else 0.0
+        )
     engine.set_cash(initial_cash)
     if hasattr(engine, "set_default_strategy_id"):
         cast(Any, engine).set_default_strategy_id(effective_strategy_id)

{akquant-0.2.47 → akquant-0.2.48}/python/akquant/config.py

@@ -631,6 +631,11 @@ class BacktestConfig:
     **Environment:**
     :param benchmark: Benchmark symbol for performance comparison.
     :param timezone: Exchange timezone. Default "Asia/Shanghai".
+    :param days_per_year: Annualization factor for risk metrics (Sharpe/Sortino/
+                          volatility). Traditional markets use 252; crypto 24/7
+                          markets use 365. Default 252.0.
+    :param risk_free_rate: Annualized risk-free rate subtracted from annualized
+                           return in Sharpe/Sortino/UPI. Default 0.0.
     :param show_progress: Show progress bar. Default True.
     :param history_depth: Auto-load N bars of history before strategy starts.
 
@@ -654,6 +659,8 @@ class BacktestConfig:
 
     benchmark: Optional[str] = None
     timezone: str = "Asia/Shanghai"
+    days_per_year: float = 252.0
+    risk_free_rate: float = 0.0
     show_progress: bool = True
     history_depth: int = 0
 

{akquant-0.2.47 → akquant-0.2.48}/src/analysis/result.rs

@@ -22,6 +22,10 @@ pub struct CalculatorInput {
     pub orders: Vec<Order>,
     pub executions: Vec<Trade>,
     pub liquidation_audits: Vec<LiquidationAudit>,
+    /// 年化天数因子。A 股等传统市场用 252，数字货币 24/7 市场用 365。
+    pub days_per_year: f64,
+    /// 年化无风险利率，默认 0.0。直接从年化收益分子里扣除。
+    pub risk_free_rate: f64,
 }
 
 #[gen_stub_pyclass]
@@ -250,12 +254,18 @@ impl BacktestResult {
         };
 
         let std_dev = variance.sqrt();
-        let annualized_volatility = std_dev * (252.0f64).sqrt();
+        let dpy = input.days_per_year;
+        let annualized_volatility = std_dev * dpy.sqrt();
+
+        // 口径说明：Sharpe / Sortino 的分子使用「日收益算术均值 × days_per_year」做年化，
+        // 与 pyfolio/empyrical/quantstats 等行业实现一致；与分母 √days_per_year 的算术年化口径匹配。
+        // 注意：UPI 与 Calmar 刻意沿用 CAGR（annualized_return），不要改成算术均值。
+        let annualized_mean_return = mean_return * dpy;
+        let risk_free_rate = input.risk_free_rate; // 年化无风险利率，默认 0.0
 
         // 5. Sharpe Ratio
-        let risk_free_rate = 0.0; // Assume 0 for simplicity or pass config
         let sharpe_ratio = if annualized_volatility != 0.0 {
-            (annualized_return - risk_free_rate) / annualized_volatility
+            (annualized_mean_return - risk_free_rate) / annualized_volatility
         } else {
             0.0
         };
@@ -268,15 +278,15 @@ impl BacktestResult {
             0.0
         };
         let downside_std_dev = downside_variance.sqrt();
-        let annualized_downside_volatility = downside_std_dev * (252.0f64).sqrt();
+        let annualized_downside_volatility = downside_std_dev * dpy.sqrt();
 
         let sortino_ratio = if annualized_downside_volatility != 0.0 {
-            (annualized_return - risk_free_rate) / annualized_downside_volatility
+            (annualized_mean_return - risk_free_rate) / annualized_downside_volatility
         } else {
             0.0
         };
 
-        // 7. UPI
+        // 7. UPI (Ulcer Performance Index) —— 沿用 CAGR 口径（与 quantstats 一致）
         let upi = if ulcer_index != 0.0 {
             (annualized_return - risk_free_rate) / ulcer_index
         } else {

{akquant-0.2.47 → akquant-0.2.48}/src/analysis/tests.rs

@@ -229,6 +229,8 @@ fn test_max_drawdown_logic() {
         orders: vec![],
         executions: vec![],
         liquidation_audits: vec![],
+        days_per_year: 252.0,
+        risk_free_rate: 0.0,
     });
     assert_eq!(result.metrics.max_drawdown, 0.25);
 
@@ -252,6 +254,8 @@ fn test_max_drawdown_logic() {
         orders: vec![],
         executions: vec![],
         liquidation_audits: vec![],
+        days_per_year: 252.0,
+        risk_free_rate: 0.0,
     });
     assert_eq!(result_2.metrics.max_drawdown, 0.0);
 
@@ -275,6 +279,8 @@ fn test_max_drawdown_logic() {
         orders: vec![],
         executions: vec![],
         liquidation_audits: vec![],
+        days_per_year: 252.0,
+        risk_free_rate: 0.0,
     });
     assert_eq!(result_3.metrics.max_drawdown, 0.2);
 
@@ -301,6 +307,8 @@ fn test_max_drawdown_logic() {
         orders: vec![],
         executions: vec![],
         liquidation_audits: vec![],
+        days_per_year: 252.0,
+        risk_free_rate: 0.0,
     });
     assert_eq!(result_4.metrics.max_drawdown, 0.5);
 }
@@ -337,6 +345,8 @@ fn test_ulcer_index_logic() {
         orders: vec![],
         executions: vec![],
         liquidation_audits: vec![],
+        days_per_year: 252.0,
+        risk_free_rate: 0.0,
     });
     let expected_ui = 0.004f64.sqrt();
     assert!((result.metrics.ulcer_index - expected_ui).abs() < 1e-9);
@@ -364,6 +374,8 @@ fn test_calmar_uses_raw_drawdown_ratio_not_pct() {
         orders: vec![],
         executions: vec![],
         liquidation_audits: vec![],
+        days_per_year: 252.0,
+        risk_free_rate: 0.0,
     });
 
     let expected_raw_calmar = result.metrics.annualized_return / result.metrics.max_drawdown;
@@ -409,6 +421,8 @@ fn test_daily_metrics_resample_by_local_timezone_day() {
         orders: vec![],
         executions: vec![],
         liquidation_audits: vec![],
+        days_per_year: 252.0,
+        risk_free_rate: 0.0,
     });
 
     let expected_returns = [0.21_f64, 0.10_f64];
@@ -422,3 +436,83 @@ fn test_daily_metrics_resample_by_local_timezone_day() {
 
     assert!((result.metrics.volatility - expected_volatility).abs() < 1e-12);
 }
+
+/// 构造一段每日权益曲线（日收益 [0.21, 0.10]），用指定的 days_per_year / risk_free_rate 计算结果。
+fn build_sharpe_fixture(days_per_year: f64, risk_free_rate: f64) -> BacktestResult {
+    let empty_pnl = TradeTracker::new().calculate_pnl(None);
+    let day_ns = 86_400_000_000_000_i64;
+    let equity_curve = vec![
+        (0, Decimal::from(100)),
+        (day_ns, Decimal::from(121)),
+        (2 * day_ns, Decimal::from_str_exact("133.1").unwrap()),
+    ];
+
+    BacktestResult::calculate(crate::analysis::CalculatorInput {
+        equity_curve_decimal: equity_curve,
+        cash_curve_decimal: vec![],
+        margin_curve_decimal: vec![],
+        snapshots: vec![],
+        timezone_name: Some("UTC".to_string()),
+        timezone_offset: 0,
+        trade_pnl: empty_pnl,
+        trades: vec![],
+        initial_cash: Decimal::from(100),
+        orders: vec![],
+        executions: vec![],
+        liquidation_audits: vec![],
+        days_per_year,
+        risk_free_rate,
+    })
+}
+
+#[test]
+fn test_sharpe_uses_arithmetic_mean_not_cagr() {
+    let dpy = 252.0_f64;
+    let result = build_sharpe_fixture(dpy, 0.0);
+
+    // 期望：分子为日收益算术均值年化 (mean * dpy)，与分母 std * sqrt(dpy) 口径匹配。
+    let returns = [0.21_f64, 0.10_f64];
+    let mean = returns.iter().sum::<f64>() / returns.len() as f64;
+    let variance =
+        returns.iter().map(|r| (r - mean).powi(2)).sum::<f64>() / (returns.len() - 1) as f64;
+    let std = variance.sqrt();
+    let expected_sharpe = (mean * dpy) / (std * dpy.sqrt());
+
+    assert!((result.metrics.sharpe_ratio - expected_sharpe).abs() < 1e-9);
+
+    // 反向断言：旧的 CAGR 口径 (annualized_return / volatility) 在这种短回测下会爆炸，
+    // 新口径必须显著不同于它，以防回归到 PR #305 修复前的行为。
+    let old_cagr_sharpe = result.metrics.annualized_return / result.metrics.volatility;
+    assert!((result.metrics.sharpe_ratio - old_cagr_sharpe).abs() > 1.0);
+}
+
+#[test]
+fn test_days_per_year_scales_annualization() {
+    let sharpe_252 = build_sharpe_fixture(252.0, 0.0).metrics.sharpe_ratio;
+    let sharpe_365 = build_sharpe_fixture(365.0, 0.0).metrics.sharpe_ratio;
+
+    // sharpe = mean * sqrt(dpy) / std，故比值应为 sqrt(365/252)。
+    let expected_ratio = (365.0_f64 / 252.0_f64).sqrt();
+    assert!((sharpe_365 / sharpe_252 - expected_ratio).abs() < 1e-9);
+}
+
+#[test]
+fn test_risk_free_rate_lowers_sharpe() {
+    let dpy = 252.0_f64;
+    let rf = 0.5_f64; // 年化无风险利率
+    let base = build_sharpe_fixture(dpy, 0.0);
+    let with_rf = build_sharpe_fixture(dpy, rf);
+
+    // rf=0 与默认行为一致，保证基线不动。
+    let returns = [0.21_f64, 0.10_f64];
+    let mean = returns.iter().sum::<f64>() / returns.len() as f64;
+    let variance =
+        returns.iter().map(|r| (r - mean).powi(2)).sum::<f64>() / (returns.len() - 1) as f64;
+    let annualized_vol = variance.sqrt() * dpy.sqrt();
+
+    // Sharpe 下降量应恰为 rf / annualized_volatility。
+    let expected_drop = rf / annualized_vol;
+    assert!(
+        (base.metrics.sharpe_ratio - with_rf.metrics.sharpe_ratio - expected_drop).abs() < 1e-9
+    );
+}

{akquant-0.2.47 → akquant-0.2.48}/src/engine/core.rs

@@ -63,6 +63,10 @@ pub struct Engine {
     pub risk_manager: RiskManager,
     pub(crate) timezone_offset: i32,
     pub(crate) timezone_name: Option<String>,
+    /// 年化天数因子。传统市场 252，数字货币 24/7 用 365。
+    pub(crate) days_per_year: f64,
+    /// 年化无风险利率，默认 0.0。
+    pub(crate) risk_free_rate: f64,
     pub(crate) history_buffer: Arc<RwLock<HistoryBuffer>>,
     pub(crate) initial_cash: Decimal,
     #[pyo3(get, set)]

{akquant-0.2.47 → akquant-0.2.48}/src/engine/python.rs

@@ -519,6 +519,8 @@ impl Engine {
             risk_manager: RiskManager::new(),
             timezone_offset: 28800, // Default UTC+8
             timezone_name: Some("Asia/Shanghai".to_string()),
+            days_per_year: 252.0,
+            risk_free_rate: 0.0,
             history_buffer: Arc::new(RwLock::new(HistoryBuffer::new(10000))), // Default large capacity for MAE/MFE
             initial_cash,
             active_start_time_ns: None,
@@ -742,6 +744,20 @@ impl Engine {
         Ok(())
     }
 
+    /// 设置年化天数因子.
+    ///
+    /// :param days: 年化使用的天数。A 股等传统市场用 252，数字货币 24/7 市场用 365。
+    pub fn set_days_per_year(&mut self, days: f64) {
+        self.days_per_year = days;
+    }
+
+    /// 设置年化无风险利率.
+    ///
+    /// :param rate: 年化无风险利率 (例如 0.02 表示 2%)。默认 0.0。
+    pub fn set_risk_free_rate(&mut self, rate: f64) {
+        self.risk_free_rate = rate;
+    }
+
     /// 启用模拟执行 (回测模式)
     ///
     /// 默认模式。在内存中撮合订单。
@@ -1235,6 +1251,8 @@ impl Engine {
             self.terminal_result_timestamp(),
             self.timezone_name.clone(),
             self.timezone_offset,
+            self.days_per_year,
+            self.risk_free_rate,
         )
     }
 }

{akquant-0.2.47 → akquant-0.2.48}/src/statistics/mod.rs

@@ -165,6 +165,8 @@ impl StatisticsManager {
         now_ns: Option<i64>,
         timezone_name: Option<String>,
         timezone_offset: i32,
+        days_per_year: f64,
+        risk_free_rate: f64,
     ) -> BacktestResult {
         // Calculate final PnL
         let trade_pnl = order_manager
@@ -217,6 +219,8 @@ impl StatisticsManager {
             orders: order_manager.get_all_orders(),
             executions: order_manager.trades.clone(),
             liquidation_audits: self.liquidation_audits.clone(),
+            days_per_year,
+            risk_free_rate,
         })
     }
 

{akquant-0.2.47/tests/golden/current → akquant-0.2.48/tests/golden/baselines}/futures_margin/metrics.json

@@ -1,10 +1,10 @@
 {
   "total_return_pct": 22.44825,
-  "sharpe_ratio": 49116247.924969286,
+  "sharpe_ratio": 6.79796016372159,
   "max_drawdown_pct": 7.55175,
   "total_commission": 103.5,
   "net_pnl": -103.5,
   "end_market_value": 244896.5,
-  "engine_rule_version": "1.0.0",
-  "akquant_version": "0.2.45"
+  "engine_rule_version": "1.1.0",
+  "akquant_version": "0.2.47"
 }

{akquant-0.2.47 → akquant-0.2.48}/tests/golden/baselines/option_basic/metrics.json

@@ -1,10 +1,10 @@
 {
   "total_return_pct": -40.0,
-  "sharpe_ratio": -0.3149703941743559,
+  "sharpe_ratio": -7.93725393319377,
   "max_drawdown_pct": 40.0,
   "total_commission": 0.0,
   "net_pnl": 0.0,
   "end_market_value": 6000.0,
-  "engine_rule_version": "1.0.0",
-  "akquant_version": "0.1.52"
+  "engine_rule_version": "1.1.0",
+  "akquant_version": "0.2.47"
 }

{akquant-0.2.47/tests/golden/current → akquant-0.2.48/tests/golden/baselines}/stock_t1/metrics.json

@@ -1,10 +1,10 @@
 {
   "total_return_pct": -0.05811444,
-  "sharpe_ratio": -4.8254367091354355,
+  "sharpe_ratio": -3.416410456188606,
   "max_drawdown_pct": 0.11702244,
   "total_commission": 16.11444,
   "net_pnl": -88.11444,
   "end_market_value": 99941.88556,
-  "engine_rule_version": "1.0.0",
-  "akquant_version": "0.2.45"
+  "engine_rule_version": "1.1.0",
+  "akquant_version": "0.2.47"
 }

{akquant-0.2.47/tests/golden/baselines → akquant-0.2.48/tests/golden/current}/futures_margin/metrics.json

@@ -1,10 +1,10 @@
 {
   "total_return_pct": 22.44825,
-  "sharpe_ratio": 49116247.924969286,
+  "sharpe_ratio": 6.79796016372159,
   "max_drawdown_pct": 7.55175,
   "total_commission": 103.5,
   "net_pnl": -103.5,
   "end_market_value": 244896.5,
-  "engine_rule_version": "1.0.0",
-  "akquant_version": "0.1.52"
+  "engine_rule_version": "1.1.0",
+  "akquant_version": "0.2.47"
 }

{akquant-0.2.47 → akquant-0.2.48}/tests/golden/current/option_basic/metrics.json

@@ -1,10 +1,10 @@
 {
   "total_return_pct": -40.0,
-  "sharpe_ratio": -0.3149703941743559,
+  "sharpe_ratio": -7.93725393319377,
   "max_drawdown_pct": 40.0,
   "total_commission": 0.0,
   "net_pnl": 0.0,
   "end_market_value": 6000.0,
-  "engine_rule_version": "1.0.0",
-  "akquant_version": "0.2.45"
+  "engine_rule_version": "1.1.0",
+  "akquant_version": "0.2.47"
 }

{akquant-0.2.47/tests/golden/baselines → akquant-0.2.48/tests/golden/current}/stock_t1/metrics.json

@@ -1,10 +1,10 @@
 {
   "total_return_pct": -0.05811444,
-  "sharpe_ratio": -4.8254367091354355,
+  "sharpe_ratio": -3.416410456188606,
   "max_drawdown_pct": 0.11702244,
   "total_commission": 16.11444,
   "net_pnl": -88.11444,
   "end_market_value": 99941.88556,
-  "engine_rule_version": "1.0.0",
-  "akquant_version": "0.1.52"
+  "engine_rule_version": "1.1.0",
+  "akquant_version": "0.2.47"
 }