zsb/fidc-backtest-engine
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Expose partial fill denial reasons

Browse Source
This commit is contained in:
boris
2026-04-23 00:26:54 -07:00
parent c7a5bedf02
commit 406cb05146
2 changed files with 251 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files

126
crates/fidc-core/src/broker.rs
View File

@@ -24,6 +24,7 @@ struct ExecutionFill {
price: f64,
quantity: u32,
next_cursor: NaiveDateTime,
unfilled_reason: Option<&'static str>,
}
#[derive(Debug, Clone)]
@@ -914,6 +915,11 @@ where
}
let sellable = position.sellable_qty(date);
let mut partial_fill_reason = if sellable < requested_qty {
Some("sellable quantity limit".to_string())
} else {
None
};
let market_limited_qty = self.market_fillable_quantity(
snapshot,
OrderSide::Sell,
@@ -924,7 +930,16 @@ where
requested_qty >= position.quantity && sellable >= position.quantity,
);
let filled_qty = match market_limited_qty {
Ok(quantity) => quantity.min(sellable),
Ok(quantity) => {
let quantity = quantity.min(sellable);
if quantity < requested_qty {
partial_fill_reason = merge_partial_fill_reason(
partial_fill_reason,
Some("market liquidity or volume limit"),
);
}
quantity
}
Err(limit_reason) => {
report.order_events.push(OrderEvent {
date,
@@ -975,6 +990,8 @@ where
if self.uses_serial_execution_cursor(reason) {
*global_execution_cursor = Some(fill.next_cursor);
}
partial_fill_reason =
merge_partial_fill_reason(partial_fill_reason, fill.unfilled_reason);
(fill.quantity, fill.price)
} else {
(filled_qty, self.sell_price(snapshot))
@@ -1002,6 +1019,17 @@ where
} else {
OrderStatus::Filled
};
let order_reason = if status == OrderStatus::PartiallyFilled {
let detail = partial_fill_reason
.as_deref()
.unwrap_or("remaining quantity could not be filled");
report.diagnostics.push(format!(
"order_partial_fill symbol={symbol} side=sell requested={requested_qty} filled={filled_qty} reason={detail}"
));
format!("{reason}: partial fill due to {detail}")
} else {
reason.to_string()
};
report.order_events.push(OrderEvent {
date,
@@ -1011,7 +1039,7 @@ where
requested_quantity: requested_qty,
filled_quantity: filled_qty,
status,
reason: reason.to_string(),
reason: order_reason,
});
report.fill_events.push(FillEvent {
date,
@@ -1279,6 +1307,7 @@ where
return Ok(());
}
let mut partial_fill_reason = None;
let market_limited_qty = self.market_fillable_quantity(
snapshot,
OrderSide::Buy,
@@ -1289,7 +1318,12 @@ where
false,
);
let constrained_qty = match market_limited_qty {
Ok(quantity) => quantity,
Ok(quantity) => {
if quantity < requested_qty {
partial_fill_reason = Some("market liquidity or volume limit".to_string());
}
quantity
}
Err(limit_reason) => {
report.order_events.push(OrderEvent {
date,
@@ -1326,6 +1360,8 @@ where
if self.uses_serial_execution_cursor(reason) {
*global_execution_cursor = Some(fill.next_cursor);
}
partial_fill_reason =
merge_partial_fill_reason(partial_fill_reason, fill.unfilled_reason);
(fill.quantity, fill.price)
} else {
let execution_price = self.snapshot_execution_price(snapshot, OrderSide::Buy);
@@ -1338,6 +1374,18 @@ where
self.minimum_order_quantity(data, symbol),
self.order_step_size(data, symbol),
);
if filled_qty < constrained_qty {
partial_fill_reason = merge_partial_fill_reason(
partial_fill_reason,
self.buy_reduction_reason(
portfolio.cash(),
value_budget.map(|budget| budget + 400.0),
execution_price,
constrained_qty,
filled_qty,
),
);
}
(filled_qty, execution_price)
};
if filled_qty == 0 {
@@ -1349,7 +1397,12 @@ where
requested_quantity: requested_qty,
filled_quantity: 0,
status: OrderStatus::Rejected,
reason: format!("{reason}: insufficient cash after fees"),
reason: format!(
"{reason}: {}",
partial_fill_reason
.as_deref()
.unwrap_or("insufficient cash after fees")
),
});
return Ok(());
}
@@ -1376,6 +1429,17 @@ where
} else {
OrderStatus::Filled
};
let order_reason = if status == OrderStatus::PartiallyFilled {
let detail = partial_fill_reason
.as_deref()
.unwrap_or("remaining quantity could not be filled");
report.diagnostics.push(format!(
"order_partial_fill symbol={symbol} side=buy requested={requested_qty} filled={filled_qty} reason={detail}"
));
format!("{reason}: partial fill due to {detail}")
} else {
reason.to_string()
};
report.order_events.push(OrderEvent {
date,
@@ -1385,7 +1449,7 @@ where
requested_quantity: requested_qty,
filled_quantity: filled_qty,
status,
reason: reason.to_string(),
reason: order_reason,
});
report.fill_events.push(FillEvent {
date,
@@ -1547,6 +1611,26 @@ where
0
}
fn buy_reduction_reason(
&self,
cash_limit: f64,
gross_limit: Option<f64>,
price: f64,
requested_qty: u32,
filled_qty: u32,
) -> Option<&'static str> {
if filled_qty >= requested_qty {
return None;
}
if gross_limit.is_some_and(|limit| price * requested_qty as f64 > limit + 1e-6) {
Some("value budget limit")
} else if cash_limit.is_finite() {
Some("insufficient cash after fees")
} else {
None
}
}
fn market_fillable_quantity(
&self,
snapshot: &crate::data::DailyMarketSnapshot,
@@ -1653,6 +1737,13 @@ where
price: execution_price,
quantity,
next_cursor,
unfilled_reason: self.buy_reduction_reason(
cash_limit.unwrap_or(f64::INFINITY),
gross_limit,
execution_price,
requested_qty,
quantity,
),
});
}
@@ -1702,11 +1793,14 @@ where
let mut filled_qty = 0_u32;
let mut gross_amount = 0.0_f64;
let mut last_timestamp = None;
let mut budget_block_reason = None;
let mut saw_quote_after_cursor = false;
for quote in quotes {
if start_cursor.is_some_and(|cursor| quote.timestamp < cursor) {
continue;
}
saw_quote_after_cursor = true;
// Approximate JoinQuant market-order fills with the evolving L1 book after
// the decision time instead of trade VWAP. This keeps quantities/prices
@@ -1745,6 +1839,7 @@ where
while take_qty > 0 {
let candidate_gross = gross_amount + quote_price * take_qty as f64;
if gross_limit.is_some_and(|limit| candidate_gross > limit + 1e-6) {
budget_block_reason = Some("value budget limit");
take_qty = self.decrement_order_quantity(
take_qty,
minimum_order_quantity,
@@ -1755,6 +1850,7 @@ where
if candidate_gross <= cash + 1e-6 {
break;
}
budget_block_reason = Some("insufficient cash after fees");
take_qty = self.decrement_order_quantity(
take_qty,
minimum_order_quantity,
@@ -1783,6 +1879,15 @@ where
price: gross_amount / filled_qty as f64,
quantity: filled_qty,
next_cursor: last_timestamp.unwrap() + Duration::seconds(1),
unfilled_reason: if filled_qty < requested_qty {
budget_block_reason.or(if saw_quote_after_cursor {
Some("intraday quote liquidity exhausted")
} else {
Some("no execution quotes after start")
})
} else {
None
},
})
}
@@ -1792,6 +1897,17 @@ where
}
}
fn merge_partial_fill_reason(current: Option<String>, next: Option<&str>) -> Option<String> {
match (current, next) {
(Some(existing), Some(next_reason)) if !existing.contains(next_reason) => {
Some(format!("{existing}; {next_reason}"))
}
(Some(existing), _) => Some(existing),
(None, Some(next_reason)) => Some(next_reason.to_string()),
(None, None) => None,
}
}
fn price_field_name(field: PriceField) -> &'static str {
match field {
PriceField::DayOpen => "day_open",

131
crates/fidc-core/tests/explicit_order_flow.rs
View File

@@ -2,7 +2,8 @@ use chrono::NaiveDate;
use fidc_core::{
BenchmarkSnapshot, BrokerSimulator, CandidateEligibility, ChinaAShareCostModel,
ChinaEquityRuleHooks, DailyFactorSnapshot, DailyMarketSnapshot, DataSet, Instrument,
OrderIntent, PortfolioState, PriceField, SlippageModel, StrategyDecision,
IntradayExecutionQuote, OrderIntent, PortfolioState, PriceField, SlippageModel,
StrategyDecision,
};
use std::collections::{BTreeMap, BTreeSet};
@@ -509,6 +510,134 @@ fn broker_applies_tick_size_slippage_on_intraday_last_fills() {
assert!((report.fill_events[0].price - 10.02).abs() < 1e-9);
}
#[test]
fn broker_emits_partial_fill_reason_when_intraday_quote_liquidity_exhausted() {
let date = NaiveDate::from_ymd_opt(2024, 1, 10).unwrap();
let data = DataSet::from_components_with_actions_and_quotes(
vec![Instrument {
symbol: "000002.SZ".to_string(),
name: "Test".to_string(),
board: "SZ".to_string(),
round_lot: 100,
listed_at: None,
delisted_at: None,
status: "active".to_string(),
}],
vec![DailyMarketSnapshot {
date,
symbol: "000002.SZ".to_string(),
timestamp: Some("2024-01-10 10:18:00".to_string()),
day_open: 10.0,
open: 10.0,
high: 10.2,
low: 9.8,
close: 10.0,
last_price: 10.0,
bid1: 9.99,
ask1: 10.01,
prev_close: 10.0,
volume: 100_000,
tick_volume: 100_000,
bid1_volume: 80_000,
ask1_volume: 80_000,
trading_phase: Some("continuous".to_string()),
paused: false,
upper_limit: 11.0,
lower_limit: 9.0,
price_tick: 0.01,
}],
vec![DailyFactorSnapshot {
date,
symbol: "000002.SZ".to_string(),
market_cap_bn: 50.0,
free_float_cap_bn: 45.0,
pe_ttm: 15.0,
turnover_ratio: Some(2.0),
effective_turnover_ratio: Some(1.8),
extra_factors: BTreeMap::new(),
}],
vec![CandidateEligibility {
date,
symbol: "000002.SZ".to_string(),
is_st: false,
is_new_listing: false,
is_paused: false,
allow_buy: true,
allow_sell: true,
is_kcb: false,
is_one_yuan: false,
}],
vec![BenchmarkSnapshot {
date,
benchmark: "000300.SH".to_string(),
open: 100.0,
close: 100.0,
prev_close: 99.0,
volume: 1_000_000,
}],
Vec::new(),
vec![IntradayExecutionQuote {
date,
symbol: "000002.SZ".to_string(),
timestamp: date.and_hms_opt(10, 18, 3).unwrap(),
last_price: 10.02,
bid1: 10.01,
ask1: 10.03,
bid1_volume: 2,
ask1_volume: 2,
volume_delta: 1,
amount_delta: 0.0,
trading_phase: Some("continuous".to_string()),
}],
)
.expect("dataset");
let mut portfolio = PortfolioState::new(1_000_000.0);
let broker = BrokerSimulator::new_with_execution_price(
ChinaAShareCostModel::default(),
ChinaEquityRuleHooks::default(),
PriceField::Last,
);
let report = broker
.execute(
date,
&mut portfolio,
&data,
&StrategyDecision {
rebalance: false,
target_weights: BTreeMap::new(),
exit_symbols: BTreeSet::new(),
order_intents: vec![OrderIntent::Value {
symbol: "000002.SZ".to_string(),
value: 5_100.0,
reason: "intraday_quote_partial".to_string(),
}],
notes: Vec::new(),
diagnostics: Vec::new(),
},
)
.expect("broker execution");
assert_eq!(report.fill_events.len(), 1);
assert_eq!(report.fill_events[0].quantity, 200);
assert_eq!(report.order_events.len(), 1);
assert_eq!(
report.order_events[0].status,
fidc_core::OrderStatus::PartiallyFilled
);
assert!(
report.order_events[0]
.reason
.contains("partial fill due to intraday quote liquidity exhausted")
);
assert!(
report
.diagnostics
.iter()
.any(|item| item.contains("order_partial_fill symbol=000002.SZ side=buy"))
);
}
#[test]
fn rebalance_optimizer_skips_unfunded_buy_when_existing_position_cannot_sell() {
let prev_date = NaiveDate::from_ymd_opt(2024, 1, 9).unwrap();