You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardexpand all lines: docs/concepts/backtesting.md
+37-30
Original file line number
Diff line number
Diff line change
@@ -154,9 +154,9 @@ Even when you provide bar data, Nautilus maintains an internal order book for ea
154
154
When backtesting with different types of data, Nautilus implements specific handling for slippage and spread simulation:
155
155
156
156
For L2 (market-by-price) or L3 (market-by-order) data, slippage is simulated with high accuracy by:
157
-
- Filling orders against actual order book levels
158
-
- Matching available size at each price level sequentially
159
-
- Maintaining realistic order book depth impact (per order fill)
157
+
- Filling orders against actual order book levels.
158
+
- Matching available size at each price level sequentially.
159
+
- Maintaining realistic order book depth impact (per order fill).
160
160
161
161
For L1 data types (e.g., L1 orderbook, trades, quotes, bars), slippage is handled through:
162
162
@@ -209,48 +209,54 @@ engine = BacktestEngine(
209
209
```
210
210
211
211
**prob_fill_on_limit** (default: `1.0`)
212
+
212
213
- Purpose:
213
214
- Simulates the probability of a limit order getting filled when its price level is reached in the market.
214
215
- Details:
215
216
- Simulates your position in the order queue at a given price level.
216
217
- Applies to all data types (e.g., L3/L2/L1 orderbook, quotes, trades, bars).
217
218
- New random probability check occurs each time market price touches your order price (but does not move through it).
218
219
- On successful probability check, fills entire remaining order quantity.
219
-
- Examples:
220
+
221
+
**Examples**:
222
+
220
223
- With `prob_fill_on_limit=0.0`:
221
-
- Limit BUY orders never fill when best ask reaches the limit price
222
-
- Limit SELL orders never fill when best bid reaches the limit price
223
-
- This simulates being at the very back of the queue and never reaching the front
224
+
- Limit BUY orders never fill when best ask reaches the limit price.
225
+
- Limit SELL orders never fill when best bid reaches the limit price.
226
+
- This simulates being at the very back of the queue and never reaching the front.
224
227
- With `prob_fill_on_limit=0.5`:
225
-
- Limit BUY orders have 50% chance of filling when best ask reaches the limit price
226
-
- Limit SELL orders have 50% chance of filling when best bid reaches the limit price
227
-
- This simulates being in the middle of the queue
228
+
- Limit BUY orders have 50% chance of filling when best ask reaches the limit price.
229
+
- Limit SELL orders have 50% chance of filling when best bid reaches the limit price.
230
+
- This simulates being in the middle of the queue.
228
231
- With `prob_fill_on_limit=1.0` (default):
229
-
- Limit BUY orders always fill when best ask reaches the limit price
230
-
- Limit SELL orders always fill when best bid reaches the limit price
231
-
- This simulates being at the front of the queue with guaranteed fills
232
+
- Limit BUY orders always fill when best ask reaches the limit price.
233
+
- Limit SELL orders always fill when best bid reaches the limit price.
234
+
- This simulates being at the front of the queue with guaranteed fills.
232
235
233
236
**prob_slippage** (default: `0.0`)
237
+
234
238
- Purpose:
235
239
- Simulates the probability of experiencing price slippage when executing market orders.
236
240
- Details:
237
241
- Only applies to L1 data types (e.g., quotes, trades, bars).
238
242
- When triggered, moves fill price one tick against your order direction.
239
243
- Affects all market-type orders (`MARKET`, `MARKET_TO_LIMIT`, `MARKET_IF_TOUCHED`, `STOP_MARKET`).
240
244
- Not utilized with L2/L3 data where order book depth can determine slippage.
241
-
- Example:
245
+
246
+
**Examples**:
247
+
242
248
- With `prob_slippage=0.0` (default):
243
-
- No artificial slippage is applied, representing an idealized scenario where you always get filled at the current market price
249
+
- No artificial slippage is applied, representing an idealized scenario where you always get filled at the current market price.
244
250
- With `prob_slippage=0.5`:
245
-
- Market BUY orders have 50% chance of filling one tick above the best ask price, and 50% chance at the best ask price
246
-
- Market SELL orders have 50% chance of filling one tick below the best bid price, and 50% chance at the best bid price
251
+
- Market BUY orders have 50% chance of filling one tick above the best ask price, and 50% chance at the best ask price.
252
+
- Market SELL orders have 50% chance of filling one tick below the best bid price, and 50% chance at the best bid price.
247
253
- With `prob_slippage=1.0`:
248
-
- Market BUY orders always fill one tick above the best ask price
249
-
- Market SELL orders always fill one tick below the best bid price
250
-
- This simulates consistent adverse price movement against your orders
254
+
- Market BUY orders always fill one tick above the best ask price.
255
+
- Market SELL orders always fill one tick below the best bid price.
256
+
- This simulates consistent adverse price movement against your orders.
251
257
252
258
**prob_fill_on_stop** (default: `1.0`)
253
-
- Stop order is just shorter name for stop-market order, that convert to market orders when market-price touches the stop-price
259
+
- Stop order is just shorter name for stop-market order, that convert to market orders when market-price touches the stop-price.
254
260
- That means, stop order order-fill mechanics is simply market-order mechanics, that is controlled by the `prob_slippage` parameter.
255
261
256
262
:::warning
@@ -263,31 +269,32 @@ The behavior of the `FillModel` adapts based on the order book type being used:
263
269
264
270
**L2/L3 Orderbook data**
265
271
266
-
With full order book depth, the `FillModel` focuses purely on simulating queue position for limit orders through `prob_fill_on_limit`. The order book itself handles slippage naturally based on available liquidity at each price level.
272
+
With full order book depth, the `FillModel` focuses purely on simulating queue position for limit orders through `prob_fill_on_limit`.
273
+
The order book itself handles slippage naturally based on available liquidity at each price level.
267
274
268
-
-`prob_fill_on_limit` is active - simulates queue position
269
-
-`prob_slippage` is not used - real order book depth determines price impact
275
+
-`prob_fill_on_limit` is active - simulates queue position.
276
+
-`prob_slippage` is not used - real order book depth determines price impact.
270
277
271
278
**L1 Orderbook data**
272
279
273
280
With only best bid/ask prices available, the `FillModel` provides additional simulation:
274
281
275
-
-`prob_fill_on_limit` is active - simulates queue position
276
-
-`prob_slippage` is active - simulates basic price impact since we lack real depth information
282
+
-`prob_fill_on_limit` is active - simulates queue position.
283
+
-`prob_slippage` is active - simulates basic price impact since we lack real depth information.
277
284
278
285
**Bar/Quote/Trade data**
279
286
280
287
When using less granular data, the same behaviors apply as L1:
281
288
282
-
-`prob_fill_on_limit` is active - simulates queue position
283
-
-`prob_slippage` is active - simulates basic price impact
289
+
-`prob_fill_on_limit` is active - simulates queue position.
290
+
-`prob_slippage` is active - simulates basic price impact.
284
291
285
292
#### Important Considerations
286
293
287
294
The `FillModel` has certain limitations to keep in mind:
288
295
289
-
- Partial fills are not simulated - orders either fill completely or not at all
290
-
- With L1 data, slippage is limited to a fixed 1-tick, at which entire order's quantity is filled
296
+
- Partial fills are not simulated - orders either fill completely or not at all.
297
+
- With L1 data, slippage is limited to a fixed 1-tick, at which entire order's quantity is filled.
291
298
292
299
:::note
293
300
As the `FillModel` continues to evolve, future versions may introduce more sophisticated simulation of order execution dynamics, including:
0 commit comments