8.9 KiB
05 — Configuration & Input Rules
Every input to a backtest comes from one of four declared sources, never scattered through the code. This is what makes runs reproducible and the engine reusable. The four:
- Instrument config — everything about the symbol/broker.
- Search space — every tunable parameter, its range, its step.
- Wizard answers — the run settings for this run (period, profile, trials, deposit, …).
- Frozen baseline — the parameters you are not optimizing, pinned to known values.
Keep these separate and you can always answer "what produced this number?" exactly.
1. Instrument config — the symbol as data
One object describes a symbol under one broker. The engine reads everything about the instrument from here; nothing about ticks, spread, or swap is ever hard-coded elsewhere.
Fields you need
| Field | Meaning | Where to find it |
|---|---|---|
name, symbol |
human label + broker symbol code | your broker |
point |
smallest price increment (e.g. 0.01) |
MT5 symbol spec |
digits |
price decimal places | MT5 symbol spec |
tick_size, tick_value |
price step and money per lot per point | MT5 symbol spec |
contract_size |
units per lot | MT5 symbol spec |
volume_min, volume_step, volume_max |
lot rounding/clamping | MT5 symbol spec |
spread_mode |
bar_column (real per-bar) | fixed_points | annual_avg |
your choice per data quality |
spread_fixed_points |
used only with fixed_points |
broker typical spread |
swap_mode |
fixed_per_lot | annual_pct |
broker / your model |
swap_long, swap_short |
per-lot-per-day rates (fixed mode) | MT5 symbol spec |
swap_annual_pct |
annual rate on notional (percent mode) | your model |
triple_swap_weekday |
the day swap is charged ×3 (often Wed) | broker |
Get these from MT5's symbol specification (
Market Watch → right-click symbol → Specification), not from memory. A wrongtick_valueorcontract_sizescales every PnL by a constant and makes the whole backtest meaningless.
Real / worst / best profiles
Keep three variants of each instrument config:
real— your broker's actual conditions. The default for ranking.worst_case— wider spread, harsher swap. A finalist that survives this is robust to cost.best_case— tighter spread. Shows the ceiling.
Cost-stress every finalist across all three; if the edge only exists in best_case, it isn't real.
Two instrument traps (both have bitten real labs)
- Quote currency ≠ account currency. For a pair quoted in a non-account currency (e.g. a JPY-quoted pair on a USD account), an EA's "money mode" lot formula can mis-scale the lot by ~the exchange rate. Fix: generate that pair's presets with an explicit fixed lot equal to the intended cash amount ÷ contract size, and set the money-amount input to zero. Always check the first trade's lot against an MT5 run before trusting the series.
- Unreliable historical spread. For some instruments (notably crypto) the recorded per-bar spread
is garbage. Use
fixed_pointswith a realistic value (and a widerworst_case) instead ofbar_column.
2. Search space — declare every tunable parameter in one place
The parameters Optuna is allowed to vary live in one declared structure, with an explicit range and step for each. Nothing tunable is hidden in the strategy body.
A search space is a mapping of name → (low, high, step), plus a note of which names are integers:
SEARCH_SPACE = {
"open_distance": (0.1, 1.0, 0.05), # float
"grid_step": (0.8, 3.0, 0.10), # float
"grid_mult": (0.5, 1.3, 0.10), # float
"grid_count": (2, 9, 1), # int
"break_even": (0.0, 0.3, 0.05), # float
"trailing_stop": (0.1, 0.5, 0.05), # float
...
}
INT_PARAMS = {"grid_count"}
The optimizer turns each entry into an Optuna suggest_float / suggest_int (doc 06). Document the
same space in a human-readable parameter-space.md next to the strategy, with the reasoning for
each range — why this floor, why this ceiling, what you expect. That note is half the value: it stops
you (or your assistant) from re-litigating ranges every iteration and makes overfit ranges obvious.
Rules for the search space
- Ranges encode priors, not hope. A range should bracket where the answer plausibly is, informed by the instrument's character. Absurdly wide ranges waste trials and invite overfit corners.
- Step matters. Too fine a step explodes the space; too coarse misses optima. Match the step to what's meaningful (e.g. a 0.05% grid step, a 1-unit count).
- What is NOT in the space is a decision. Explicitly list parameters you deliberately exclude (because prior tests showed ~0 impact, or because changing them is a different hypothesis). An empty exclusion list usually means you haven't thought about it.
- Timeframe is usually fixed per iteration. Searching across timeframes in one study is "timeframe-shopping" and overfits; pick the primary timeframe in the stats phase (doc 08) and lock it.
3. Frozen baseline — pin what you don't optimize
The parameters outside the search space still need values. Pin them to the validated baseline (your known-good preset) so the optimizer varies only the few things under test, against an otherwise-known configuration. The run script merges sampled parameters onto this frozen baseline before building the engine params. This keeps each study small and interpretable — you're measuring the effect of the few tuned knobs, not drowning in a 30-dimensional search.
4. Lot / money mode — the input that silently breaks results
Position sizing deserves its own section because it is the most common source of "my Python and MT5 disagree by a constant factor" bugs. Expose money-based sizing through two inputs, plus the fixed-lot guard:
| Input | Meaning |
|---|---|
*_LotAmount |
the cash base. Lot = LotAmount / open_price / contract_size. |
*_LotBalance |
the account balance this base is calibrated for (the scaling window). |
*_Lot |
a fixed lot in lots. Must be 0 to enable money mode — otherwise the EA uses the fixed lot and ignores LotAmount. |
Behavior:
LotAmount |
LotBalance |
Mode | Result |
|---|---|---|---|
| X | 0 | static (default for testing) | lot always sized from cash X, independent of balance |
| X | Y | dynamic | lot = base × (current_balance / Y) — grows/shrinks with the account |
Rules
- Test with the static lot by default (
LotBalance = 0). Compounding (dynamic) is a production choice; for research you want a clean, balance-independent measurement. - Always confirm
*_Lot = 0when you intend money mode. A stray non-zero fixed lot is a classic silent bug — the run "works" but sizes every trade wrong. - For a grid, levels multiply from the base lot via the grid multiplier (or ATR/other); the base comes from the money rule above.
- Mirror whatever mode you choose identically in the Python engine and the generated
.set, or the two tiers won't agree.
5. Wizard — capture run settings once, save them for reproducibility
Before a run, a small interactive wizard asks the handful of settings that change run-to-run and
writes them to wizard-answers.yaml. That YAML is the reproducibility record: anyone (including
future-you) can see exactly what produced an iteration's numbers.
Common wizard questions:
period_start / period_end # the backtest window
instrument_profile # real / worst_case / best_case
trials # Optuna trial budget (e.g. 300 / 1000 / 5000)
max_dd_ccy # hard drawdown cap for the constraint
top_n_verify # how many finalists to send to MT5
fixed_lot / initial_deposit # sizing context
Design notes:
- Give every question a sensible default so a fast run is just pressing Enter.
- Make the wizard extensible: a base set of common questions plus a per-strategy hook for extra ones (e.g. a grid wizard adds depth/multiplier defaults).
- Write the answers to disk next to the iteration. A run with no saved settings is not reproducible and shouldn't be promoted.
Putting it together
A single run is fully specified by: which instrument config (symbol + profile), which search space (the tunable parameters), which frozen baseline (the pinned rest), and which wizard answers (the window, trials, deposit). Four declared sources, each in its own place. That is the whole "separate inputs" discipline — and it's why any run in this lab can be explained and reproduced exactly.
Next: 06-optimization-and-robustness.md — turning the search
space into an Optuna study and not fooling yourself with the result.