Runtime Config Guide

This page explains how to control strategy runtime behavior from backtest entry points, without editing strategy class code.

1. What It Solves

strategy_runtime_config lets you inject runtime switches at call-site:

• Error handling mode (error_mode)
• Portfolio update threshold (portfolio_update_eps)
• Precise day-boundary hooks (enable_precise_day_boundary_hooks)
• Legacy fallback flag (re_raise_on_error)

It works for both:

• run_backtest(...)
• run_warm_start(...)

2. Basic Usage

from akquant import StrategyRuntimeConfig, run_backtest

result = run_backtest(
    data=data,
    strategy=MyStrategy,
    strategy_runtime_config=StrategyRuntimeConfig(
        error_mode="continue",
        portfolio_update_eps=1.0,
    ),
)

You can also pass a dict:

result = run_backtest(
    data=data,
    strategy=MyStrategy,
    strategy_runtime_config={"error_mode": "continue"},
)

3. Parameter Matrix

Field	Type	Default	Typical Use	Invalid Input Behavior
error_mode	"raise" \| "continue" \| "legacy"	"raise"	Control callback exception policy	Raises ValueError
portfolio_update_eps	float (>= 0)	0.0	Skip tiny equity/cash update noise	Raises ValueError
enable_precise_day_boundary_hooks	bool	False	Enable strict before/after trading by boundary timers	Coerced by bool conversion
re_raise_on_error	bool	True	Legacy fallback when error_mode="legacy"	Coerced by bool conversion

4. Conflict Priority

When strategy-side config and external config conflict, behavior is controlled by runtime_config_override:

• runtime_config_override=True (default): apply external config
• runtime_config_override=False: keep strategy-side config

Identical conflict warnings are deduplicated per strategy instance.

5. Common Pitfalls

• Passing unknown keys in strategy_runtime_config fails fast with field-level error.
• Passing negative portfolio_update_eps fails fast with validation error.
• Repeated runs on the same strategy instance may not repeat identical warnings due to deduplication.
• runtime_config_override=False preserves strategy-side config even if external values are provided.

6. Warm Start Injection

You can override runtime behavior when resuming from snapshot:

result = run_warm_start(
    checkpoint_path="snapshot.pkl",
    data=new_data,
    symbol="TEST",
    strategy_runtime_config={"error_mode": "continue"},
)

Conflict rules are exactly the same as run_backtest.

7. End-to-End Demo

See runnable demo:

• examples/22_strategy_runtime_config_demo.py

Expected output markers:

• scenario1_done
• scenario2_exception=...
• scenario3_done

8. Troubleshooting Cheat Sheet

Symptom / Error	Likely Cause	Fast Fix
strategy_runtime_config contains unknown fields: ...	Unknown key in injected dict	Remove unsupported keys and keep only documented fields
invalid strategy_runtime_config: portfolio_update_eps must be >= 0	Negative portfolio_update_eps	Set portfolio_update_eps to 0 or a positive float
Runtime config passed but strategy behavior unchanged	runtime_config_override=False is enabled	Set runtime_config_override=True or remove the flag
Conflict warning appears only once	Warning dedup is per strategy instance and conflict payload	This is expected; create a new strategy instance if you need repeated warning output
Warm-start resume still raises callback exceptions	Restored strategy config remains active and override not applied	Pass strategy_runtime_config={"error_mode": "continue"} with runtime_config_override=True