Profiles¶
The profiles and parity tutorial runs a one-setting comparison and explains the supported evidence boundaries.
Profiles are pre-configured BacktestConfig settings for framework-specific execution semantics.
The retained evidence on this page identifies supported framework comparisons, their input settings, and their stated tolerances.
Examples using prices and strategy assume those inputs already exist. The linked profiles tutorial supplies both and compares one setting at a time.
Available Profiles¶
Core Profiles¶
| Profile | Description |
|---|---|
default |
Sensible defaults for general use with integer-share execution |
fast |
Zero-cost, integer-share settings for iteration; performance depends on the workload |
backtrader |
Settings used for the documented Backtrader comparisons |
vectorbt |
Settings used for the documented VectorBT comparisons, including fractional shares |
zipline |
Match the documented Zipline comparison protocol |
lean |
Match the frozen LEAN daily US-equity comparison protocol |
realistic |
Conservative settings for production |
Broker Presets¶
| Profile | Description |
|---|---|
ibkr_us_stocks_fixed |
Interactive Brokers US stocks fixed commission schedule |
The broker preset also supports a modular alias:
| Alias | Resolves To |
|---|---|
ibkr:us:stocks:fixed |
ibkr_us_stocks_fixed |
The lean profile is scoped to daily US equities submitted from OnData with
DefaultBrokerageModel, a margin account, and 2x security leverage. LEAN delegates fees,
slippage, margin, and fills to selected brokerage and security models, so this profile is not a
claim about every LEAN asset class, resolution, or brokerage model.
Strict Profiles¶
Strict variants are the names used by retained comparison commands:
| Profile | Base | Additional Tuning |
|---|---|---|
backtrader_strict |
backtrader | Submission precheck, simple cash check |
vectorbt_strict |
vectorbt | Same settings as vectorbt |
zipline_strict |
zipline | Same settings as zipline |
Aliases¶
| Alias | Resolves To |
|---|---|
vectorbt_pro |
vectorbt |
vectorbt_oss |
vectorbt |
quantconnect |
lean |
ibkr:us:stocks:fixed |
ibkr_us_stocks_fixed |
Usage¶
from ml4t.backtest import BacktestConfig
# Load a profile
config = BacktestConfig.from_preset("backtrader")
# Or build from structured broker assumptions
config = BacktestConfig.from_assumptions(
broker="ibkr",
region="us",
asset_class="stocks",
plan="fixed",
)
# Use with run_backtest
from ml4t.backtest import run_backtest
result = run_backtest(prices, strategy, config="zipline")
# Override specific settings
config = BacktestConfig.from_preset("backtrader")
config.commission_rate = 0.002
config.initial_cash = 500_000
Profiles define behavioral defaults. Quote-aware feeds layer on top of them: you can start from a preset, then override execution_price, mark_price, and the feed's price_col / quote columns without changing the rest of the profile.
Profile Comparison¶
These tables report configured values. A profile value is not automatically an equivalence claim. The behavior coverage map identifies which field groups have both a native oracle and a cross-engine comparison. Target sizing, insufficient-cash boundaries, competing same-session orders, partial fills, missing bars, and late assets remain excluded from scenario-level equivalence where the map marks them unpublished.
Execution¶
| Setting | default | backtrader | vectorbt | zipline | lean | realistic |
|---|---|---|---|---|---|---|
| Execution mode | next_bar | next_bar | same_bar | next_bar | next_bar | next_bar |
| Execution price | open | open | close | open | open | open |
Stops¶
| Setting | default | backtrader | vectorbt | zipline | lean | realistic |
|---|---|---|---|---|---|---|
| Fill mode | stop_price | stop_price | stop_price | next_bar_open | stop_price* | next_bar_open |
| Level basis | fill_price | signal_price | fill_price | fill_price | fill_price* | fill_price |
| Trail HWM | close | close | bar_extreme | bar_extreme | close* | close |
| Trail timing | lagged | lagged | intrabar | intrabar | lagged* | lagged |
* The LEAN stop settings are ML4T profile fallbacks. The current native LEAN oracle does not
claim stop-order parity.
Account¶
| Setting | default | backtrader | vectorbt | zipline | lean | realistic |
|---|---|---|---|---|---|---|
| Short selling | No | Yes | Yes | Yes | Yes | No |
| Leverage | No | No | No | Cash validation disabled | Yes, 2x | No |
| Share type | integer | integer | fractional | integer | integer | integer |
Costs¶
| Setting | default | backtrader | vectorbt | zipline | lean | realistic |
|---|---|---|---|---|---|---|
| Commission | none | none | none | none | $0.005/share | 0.2% |
| Slippage | none | none | none | none | none | 0.2% |
| Stop slippage | 0 | 0 | 0 | 0 | 0 | 0.1% |
| Cash buffer | 0% | 0% | 0% | 0% | 0% | 2% |
| Target-weight multiplier | 100% | 100% | 100% | 100% | 99.75% | 100% |
Order Processing¶
| Setting | default | backtrader | vectorbt | zipline | lean | realistic |
|---|---|---|---|---|---|---|
| Fill ordering | exit_first | fifo | exit_first | fifo | sequential | exit_first |
| Reject insuff. | yes | yes | no | no | yes | yes |
| Partial fills | no | no | yes | no | no | no |
| Rebalance mode | incremental | snapshot | hybrid | snapshot | snapshot | incremental |
Parity Validation¶
Framework profiles are validated on the workloads each retained artifact declares:
-
Real strategies: Complete canonical fill streams, every shared equity timestamp, and terminal values for supported pairs drawn from ETF allocation, CME futures, and crypto perpetual-funding case studies. Frozen model-derived targets are shared by both engines.
-
Synthetic scenarios: Exact ordered trade and fill matching on the required matrix for VectorBT, Backtrader, and Zipline. Capability declarations identify reconstructed and unavailable result surfaces.
-
Synthetic stress: Exact target-intent, native-fill, fill-derived closed-trade, and terminal-state comparison on a reconstructable 250-asset, 5,040-session workload. Each framework row states the surface it exposes; the claim does not include unavailable order-lifecycle fields.
LEAN has separate native-behavior and Chapter 16 case-study evidence. The frozen engine produced
47,652 fills across three case studies; ML4T matched every canonical fill and each terminal value
at the declared $0.0001 quantum. See validation/native/evidence/lean-18001.json and
validation/lean/case_study_evidence.json.
Real-strategy audit¶
17/17 required pairs pass; 8 pairs are declared unsupported. The audit uses five real-data strategy workloads with frozen historical market data and model-derived targets. A pass requires identical valuation timestamp coverage, complete fill streams with quantities equal at 1e-5 and prices equal at 1e-8, and account monetary values that round to the same cent. The FX workload uses the USD-quoted pairs in its frozen target stream so every required engine uses native USD valuation.
The parity protocol disables transaction costs and position rules on both sides. It tests target sizing, order sequencing, fills, cash and margin behavior, funding where applicable, and valuation. It does not claim to reproduce each selected case-study production result with its original costs and risk overlays.
| Real strategy | Pinned framework | Current result | Evidence |
|---|---|---|---|
| ETF allocation | VectorBT Pro 2026.6.27 | fills equal at declared field precision; 1,995 valuations and terminal exact at 1e-8 | real-strategy evidence |
| ETF allocation | VectorBT OSS 1.1.0 | fills equal at declared field precision; 1,995 valuations and terminal exact at 1e-8 | real-strategy evidence |
| ETF allocation | Backtrader 1.9.78.123 | fills equal at declared field precision; 1,995 valuations and terminal exact at 1e-8 | real-strategy evidence |
| ETF allocation | Zipline Reloaded 3.1.1 | fills equal at declared field precision; 1,995 valuations and terminal exact at 1e-8 | real-strategy evidence |
| ETF allocation | LEAN 18001 | fills equal at declared field precision; 1,995 valuations and terminal exact at 1e-8 | real-strategy evidence |
| CME futures | VectorBT Pro 2026.6.27 | fills equal at declared field precision; 1,595 valuations within $0.01 (max raw gap $0.00000010); terminal within $0.01 (raw gap $0.00000007) | real-strategy evidence |
| CME futures | Backtrader 1.9.78.123 | fills equal at declared field precision; 1,595 valuations within $0.01 (max raw gap $0.00000015); terminal within $0.01 (raw gap $0.00000015) | real-strategy evidence |
| Crypto perpetual funding | LEAN 18001 | fills equal at declared field precision; 2,426 valuations and terminal exact at 1e-8 | real-strategy evidence |
| FX allocation (USD-quoted pairs) | VectorBT Pro 2026.6.27 | fills equal at declared field precision; 2,108 valuations and terminal exact at 1e-8 | real-strategy evidence |
| FX allocation (USD-quoted pairs) | VectorBT OSS 1.1.0 | fills equal at declared field precision; 2,108 valuations and terminal exact at 1e-8 | real-strategy evidence |
| FX allocation (USD-quoted pairs) | Backtrader 1.9.78.123 | fills equal at declared field precision; 2,108 valuations and terminal exact at 1e-8 | real-strategy evidence |
| FX allocation (USD-quoted pairs) | LEAN 18001 | fills equal at declared field precision; 2,108 valuations and terminal exact at 1e-8 | real-strategy evidence |
| US equity panel | VectorBT Pro 2026.6.27 | fills equal at declared field precision; 4,146 valuations within $0.01 (max raw gap $0.00001950); terminal within $0.01 (raw gap $0.00001880) | real-strategy evidence |
| US equity panel | VectorBT OSS 1.1.0 | fills equal at declared field precision; 4,146 valuations within $0.01 (max raw gap $0.00001910); terminal within $0.01 (raw gap $0.00001870) | real-strategy evidence |
| US equity panel | Backtrader 1.9.78.123 | fills equal at declared field precision; 4,146 valuations within $0.01 (max raw gap $0.00000170); terminal within $0.01 (raw gap $0.00000160) | real-strategy evidence |
| US equity panel | Zipline Reloaded 3.1.1 | fills equal at declared field precision; 4,027 valuations within $0.01 (max raw gap $0.00000190); terminal within $0.01 (raw gap $0.00000030) | real-strategy evidence |
| US equity panel | LEAN 18001 | fills equal at declared field precision; 4,027 valuations within $0.01 (max raw gap $0.00000460); terminal within $0.01 (raw gap $0.00000420) | real-strategy evidence |
Real-strategy engine performance¶
The table reports engine-call wall time for all 17 correctness-passing pairs. The ratio is framework median / ML4T median; values above 1 mean ML4T completed the engine call faster.
| Real strategy | Pinned framework | Framework median (95% CI), s | ML4T median (95% CI), s | Framework / ML4T median |
|---|---|---|---|---|
| ETF allocation | VectorBT Pro 2026.6.27 | 0.293 (0.290-0.298) | 0.424 (0.421-0.434) | 0.691x |
| ETF allocation | VectorBT OSS 1.1.0 | 0.192 (0.176-0.493) | 0.414 (0.413-0.417) | 0.462x |
| ETF allocation | Backtrader 1.9.78.123 | 9.631 (9.428-9.710) | 0.439 (0.434-0.444) | 21.954x |
| ETF allocation | Zipline Reloaded 3.1.1 | 3.888 (3.878-3.959) | 0.621 (0.618-0.626) | 6.256x |
| ETF allocation | LEAN 18001 | 2.638 (2.516-2.707) | 0.750 (0.743-0.757) | 3.520x |
| CME futures | VectorBT Pro 2026.6.27 | 0.290 (0.289-0.294) | 0.410 (0.406-0.958) | 0.708x |
| CME futures | Backtrader 1.9.78.123 | 6.639 (5.831-8.332) | 0.428 (0.422-1.235) | 15.504x |
| Crypto perpetual funding | LEAN 18001 | 2.828 (2.737-2.952) | 1.327 (0.657-2.183) | 2.131x |
| FX allocation (USD-quoted pairs) | VectorBT Pro 2026.6.27 | 0.288 (0.286-0.294) | 0.148 (0.147-0.149) | 1.947x |
| FX allocation (USD-quoted pairs) | VectorBT OSS 1.1.0 | 0.144 (0.142-0.146) | 0.145 (0.145-0.146) | 0.988x |
| FX allocation (USD-quoted pairs) | Backtrader 1.9.78.123 | 0.434 (0.430-0.440) | 0.147 (0.146-0.149) | 2.947x |
| FX allocation (USD-quoted pairs) | LEAN 18001 | 0.953 (0.936-1.164) | 0.158 (0.155-0.164) | 6.033x |
| US equity panel | VectorBT Pro 2026.6.27 | 3.806 (3.336-4.341) | 23.306 (21.906-25.833) | 0.163x |
| US equity panel | VectorBT OSS 1.1.0 | 17.116 (17.069-17.633) | 25.738 (24.983-27.163) | 0.665x |
| US equity panel | Backtrader 1.9.78.123 | 668.611 (642.993-718.202) | 26.887 (26.406-29.406) | 24.868x |
| US equity panel | Zipline Reloaded 3.1.1 | 117.445 (116.308-118.391) | 26.821 (25.473-27.644) | 4.379x |
| US equity panel | LEAN 18001 | 48.436 (48.221-48.986) | 27.688 (27.575-27.796) | 1.749x |
Measured 2026-09-24 on Linux-6.8.0-139-generic-x86_64-with-glibc2.39 with 24 logical CPUs. Each side used one isolated warm-up process and ten isolated measured processes. The timer includes only the engine call; it excludes input loading, model inference, target construction, adapter preparation, result extraction, serialization, reporting. These measurements apply only to the named strategy, framework version, frozen input bundle, and machine. Raw samples and bootstrap intervals are retained in real-strategy performance evidence.
Synthetic diagnostic scenarios¶
The scenario matrix contains synthetic conformance tests. "Exact" means terminal values, ordered closed trades, and ordered fills match after 1e-8 quantization. Each record declares whether a surface is native, reconstructed, aggregate-only, input-only, or unavailable. These results test isolated conventions, not realistic strategy equivalence.
| Profile | Pinned framework | Required scenarios | Evidence |
|---|---|---|---|
vectorbt_strict |
VectorBT Pro 2026.6.27 | 17/17 exact | scenario evidence |
vectorbt_oss_strict |
VectorBT OSS 1.1.0 | 16/16 exact | scenario evidence |
backtrader_strict |
Backtrader 1.9.78.123 | 17/17 exact | scenario evidence |
zipline_strict |
Zipline Reloaded 3.1.1 | 16/16 exact | scenario evidence |
The synthetic stress workload contains 250 assets and 5,040 daily sessions (1,260,000 bars). Every row has zero canonical gap for target intents, native fills, closed trades reconstructed from those fills, and terminal state reconstructed from the fill ledger and final marks. Fill records use 1e-8 precision; monetary totals use cent precision.
| Profile | Current framework | Target intents | Native fills | Fill-derived closed trades | Terminal value | Evidence |
|---|---|---|---|---|---|---|
vectorbt_strict |
VectorBT Pro 2026.6.27 | 427,790 | 423,313 | 222,751 | 1,285,886.320000 | scale evidence |
vectorbt_oss_strict |
VectorBT OSS 1.1.0 | 427,790 | 417,941 | 211,322 | 1,345,348.850000 | scale evidence |
backtrader_strict |
Backtrader 1.9.78.123 | 427,790 | 343,813 | 182,019 | -9,166,273.560000 | scale evidence |
zipline_strict |
Zipline Reloaded 3.1.1 | 427,790 | 427,696 | 226,434 | 10,504,095.900000 | scale evidence |
lean |
LEAN 18001 | 427,790 | 361,297 | 191,297 | 184,538.130000 | scale evidence |
Performance¶
ML4T-only regression evidence is defined in validation/performance_baselines.json. The separate
controlled cross-framework artifact uses one warm-up and ten process-isolated measurements per
runner, with raw samples, median and 95% intervals, process-tree peak RSS, exact output checksums,
and an idiomatic view that makes no equivalence claim.
The table above publishes engine-only timings for all 17 real-strategy pairs that passed correctness. It excludes data loading, inference, target construction, adapter preparation, extraction, and reporting. The ratios apply only to the named versions, frozen input bundles, measurement date, and machine.
Listing Profiles¶
from ml4t.backtest.profiles import list_profiles
print(list_profiles())
# ['backtrader', 'default', 'lean', 'realistic', 'vectorbt', 'zipline']
In the book¶
Chapter 16, Section 16.3, Engine divergence anatomy changes one setting at a time; Case-study LEAN parity reports the bounded comparison audit. The profile tables here identify the configuration used for each retained library workload.
Next Steps¶
- Configuration -- understand each parameter
- Execution Semantics -- why these settings produce different results