akquant 0.2.48__tar.gz → 0.2.49__tar.gz

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

@@ -8,6 +8,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Added
+- `get_account()` 账户快照新增 `free_margin` 字段（= `equity - used_margin`），表示真正可用于新开仓的可用保证金，与下单因保证金不足被拒时日志里的 `Available` 口径一致；期货保证金账户下 `cash`（现金余额）通常大于 `free_margin`，股票现金账户下二者相等。同时修正了 `cash` 在文档与 docstring 中「可用资金」的误导性表述，明确其为「现金余额」。
 - `BacktestConfig` 新增 `days_per_year`（年化天数因子，默认 252；数字货币 24/7 市场可设 365）与 `risk_free_rate`（年化无风险利率，默认 0.0）两个字段，用于参数化 Sharpe/Sortino/波动率等风险指标的年化口径。`risk_free_rate` 默认 0 不改变任何现有数值。
 
 ### Changed

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

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

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

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

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

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

{akquant-0.2.48 → akquant-0.2.49}/docs/en/guide/strategy.md

@@ -761,6 +761,7 @@ If the strategy is running with futures margin semantics, these fields become es
 
 - `snap["equity"]`: current account equity.
 - `snap["used_margin"]` / `snap["margin"]`: current margin in use.
+- `snap["free_margin"]`: available margin (`equity - used_margin`), i.e. the amount usable to open new positions; the `Available` value in the rejection log refers to this field, so do not compare it against `cash`.
 - `snap["notional_value"]`: current futures notional exposure.
 - `snap["unrealized_pnl"]`: current floating PnL.
 

{akquant-0.2.48 → akquant-0.2.49}/docs/en/reference/api.md

@@ -875,9 +875,10 @@ Note: if you do not pass an explicit `fill_policy` here, the framework defaults
 *   `ctx.get_position_entry_price(symbol) -> float`: Get the current average entry price for one symbol.
 *   `ctx.get_position_entry_prices() -> Dict[str, float]`: Get current average entry prices for all symbols.
 *   `get_cash() -> float`: Get current available cash.
-*   `get_account() -> Dict[str, float]`: Get an account snapshot. Common fields include `cash`, `equity`, `market_value`, `notional_value`, `frozen_cash`, `margin`, `used_margin`, `unrealized_pnl`, `borrowed_cash`, `short_market_value`, `maintenance_ratio`, `account_mode`, `accrued_interest`, and `daily_interest`.
+*   `get_account() -> Dict[str, float]`: Get an account snapshot. Common fields include `cash`, `equity`, `market_value`, `notional_value`, `frozen_cash`, `margin`, `used_margin`, `free_margin`, `unrealized_pnl`, `borrowed_cash`, `short_market_value`, `maintenance_ratio`, `account_mode`, `accrued_interest`, and `daily_interest`.
     *   In cash / spot-style accounts, `market_value` usually represents marked position value.
     *   In futures margin accounts, `equity` is account equity, `used_margin` is margin in use, `notional_value` is futures notional exposure, and `unrealized_pnl` is marked floating PnL. Futures trades do not deduct full notional from `cash` the way spot buys do, and notional exposure is not mirrored into `market_value` as if it were spot inventory.
+    *   `cash` is the cash balance; `free_margin` (= `equity - used_margin`) is the amount actually available to open new positions and matches the `Available` value shown in the rejection log when an order is rejected. In futures margin accounts, opening a position does not deduct margin from `cash`, so `cash` is usually larger than `free_margin`; in stock cash accounts the two are equal.
     *   Inside strategy callbacks, prefer `get_portfolio_value()` when you only need current total equity; it is aligned with `get_account()["equity"]`.
 *   `get_order(order_id) -> Order`: Get details of a specific order.
 *   `get_open_orders(symbol) -> List[Order]`: Get list of open orders.

{akquant-0.2.48 → akquant-0.2.49}/docs/en/textbook/07_futures.md

@@ -57,6 +57,10 @@ Under AKQuant's futures margin-account semantics, read `get_account()` and
   the way a spot buy does; cash mainly reflects fees and realized cash flows.
 - `equity`: account equity. `get_portfolio_value()` is aligned with this field.
 - `used_margin` / `margin`: margin currently in use.
+- `free_margin`: available margin (`equity - used_margin`), i.e. the amount
+  actually usable to open new positions. When an order is rejected for
+  insufficient margin, the `Available` value in the log refers to this field —
+  do not compare it against `cash`.
 - `notional_value`: current futures notional exposure.
 - `unrealized_pnl`: floating PnL marked with the latest price.
 - `market_value`: mainly a spot-style marked-value field and should not be read

{akquant-0.2.48 → akquant-0.2.49}/docs/zh/guide/strategy.md

@@ -324,6 +324,7 @@ print(
 
 - `snap["equity"]`: 当前账户权益。
 - `snap["used_margin"]` / `snap["margin"]`: 当前已占用保证金。
+- `snap["free_margin"]`: 可用保证金（`equity - used_margin`），即可用于新开仓的资金；下单因保证金不足被拒时日志里的 `Available` 就是此值，不要用 `cash` 去比较。
 - `snap["notional_value"]`: 当前期货名义敞口。
 - `snap["unrealized_pnl"]`: 当前浮动盈亏。
 

{akquant-0.2.48 → akquant-0.2.49}/docs/zh/reference/api.md

@@ -899,9 +899,10 @@ def on_pre_open(self, event: Dict[str, Any]) -> None:
 *   `ctx.get_position_entry_prices() -> Dict[str, float]`: 获取所有标的当前持仓均价。
 *   `hold_bar(symbol) -> int`: 获取当前持仓持有的 Bar 数量。
 *   `get_cash() -> float`: 获取当前可用资金。
-*   `get_account() -> Dict[str, float]`: 获取账户详情快照。常见字段包括 `cash`、`equity`、`market_value`、`notional_value`、`frozen_cash`、`margin`、`used_margin`、`unrealized_pnl`、`borrowed_cash`、`short_market_value`、`maintenance_ratio`、`account_mode`、`accrued_interest`、`daily_interest`。
+*   `get_account() -> Dict[str, float]`: 获取账户详情快照。常见字段包括 `cash`、`equity`、`market_value`、`notional_value`、`frozen_cash`、`margin`、`used_margin`、`free_margin`、`unrealized_pnl`、`borrowed_cash`、`short_market_value`、`maintenance_ratio`、`account_mode`、`accrued_interest`、`daily_interest`。
     *   现金账户 / 现货账户下，`market_value` 通常表示持仓市值。
     *   期货保证金账户下，`equity` 表示账户权益，`used_margin` 表示已占用保证金，`notional_value` 表示期货名义敞口，`unrealized_pnl` 表示浮动盈亏；期货持仓不会像股票那样把全额名义本金直接计入 `cash` 扣减，也不会把名义敞口直接映射为 `market_value`。
+    *   `cash` 是现金余额，`free_margin`（= `equity - used_margin`）才是可用于新开仓的资金，与下单被拒时日志里的 `Available` 口径一致。期货保证金账户下开仓不从 `cash` 扣减保证金，因此 `cash` 通常大于 `free_margin`；股票现金账户下二者相等。
     *   在策略回调内，如果你只想读取“当前账户总权益”，优先使用 `get_portfolio_value()`；其口径与 `get_account()["equity"]` 对齐。
 *   `get_order(order_id) -> Order`: 获取指定订单详情。
 *   `get_open_orders(symbol) -> List[Order]`: 获取当前未完成订单列表。

{akquant-0.2.48 → akquant-0.2.49}/docs/zh/textbook/07_futures.md

@@ -224,6 +224,7 @@ rb_config = InstrumentConfig(
 - `cash`: 账户现金余额。开仓期货时不会像股票买入那样扣减全额名义本金，只会反映手续费、已实现盈亏等现金流。
 - `equity`: 账户权益，是期货保证金账户最重要的总资产口径；`get_portfolio_value()` 与它保持一致。
 - `used_margin` / `margin`: 当前已占用保证金。
+- `free_margin`: 可用保证金（`equity - used_margin`），即真正可用于新开仓的资金。下单因保证金不足被拒时，日志里的 `Available` 就是这个口径——不要拿 `cash` 去和它比较。
 - `notional_value`: 当前期货名义敞口，用于观察杠杆暴露。
 - `unrealized_pnl`: 按最新价格计算的浮动盈亏。
 - `market_value`: 主要用于现货/持仓市值语义；对期货保证金账户，不应把它理解为“名义本金”。

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

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

{akquant-0.2.48 → akquant-0.2.49}/python/akquant/strategy.py

@@ -1717,11 +1717,15 @@ class Strategy:
 
         Returns:
             Dict: 包含以下字段:
-                - cash: 可用资金
-                - equity: 总权益 (现金 + 持仓市值)
+                - cash: 现金余额 (期货保证金账户下, 开仓不从此扣减保证金,
+                  故并非可用于新开仓的资金; 请改用 free_margin)
+                - equity: 总权益 (现金 + 持仓市值 + 浮动盈亏)
                 - market_value: 持仓总市值 (equity - cash)
                 - frozen_cash: 当前未完成订单预占资金
                 - margin: 当前仓位占用保证金
+                - used_margin: 同 margin
+                - free_margin: 可用保证金 (equity - margin), 即可用于新开仓的资金;
+                  与拒单信息中的 Available 口径一致
                 - borrowed_cash: 融资负债 (现金为负时)
                 - short_market_value: 空头市值
                 - maintenance_ratio: 维持担保比例

{akquant-0.2.48 → akquant-0.2.49}/python/akquant/strategy_trading_api.py

@@ -1351,6 +1351,11 @@ def get_account(strategy: Any) -> Dict[str, Any]:
     else:
         accrued_interest = float(getattr(strategy.ctx, "margin_accrued_interest", 0.0))
         daily_interest = float(getattr(strategy.ctx, "margin_daily_interest", 0.0))
+    # 可用保证金 = 总权益 - 已占用保证金.
+    # 与开仓资金校验(拒单信息中的 Available)口径一致.
+    # 期货保证金账户下, cash 仅为现金余额(开仓不扣保证金).
+    # 真正可用于新开仓的是 free_margin.
+    free_margin = equity - margin
     return {
         "cash": cash,
         "equity": equity,
@@ -1359,6 +1364,7 @@ def get_account(strategy: Any) -> Dict[str, Any]:
         "frozen_cash": frozen_cash,
         "margin": margin,
         "used_margin": margin,
+        "free_margin": free_margin,
         "unrealized_pnl": float(unrealized_pnl),
         "borrowed_cash": borrowed_cash,
         "short_market_value": float(short_market_value),