Backtest & Paper Trading Engine¶
Backtest execution, paper trading, scheduling functions and lifecycle callbacks.
run_strategy¶
All-in-one backtest + report generation.
run_strategy(initialize_func, start_date, end_date, starting_cash=100000,
benchmark='000300.XSHG', handle_data=None, securities=None,
report_dir='reports', use_local=False, max_memory_mb=1024,
selection_func=None, selection_rebalance='monthly:1')
Returns the backtest result as a dict.
run_backtest¶
Run a backtest (without generating a report).
run_backtest(initialize_func, start_date, end_date, starting_cash=100000.0,
frequency='daily', benchmark='000300.XSHG', securities=None,
use_local=False, max_memory_mb=1024,
selection_func=None, selection_rebalance='monthly:1',
handle_data=None, debug_mode=False)
handle_data: optional handle_data(context, data) callback, invoked once per bar. debug_mode=True prints extra diagnostics to help debug strategies with no trades, empty data, etc.
Returns {"context": Context, "trade_log": list, "recorded_values": dict, "benchmark": str}.
run_portfolio_backtest¶
High-level backtest interface for multi-stock portfolios.
StrategyConfig¶
| Parameter | Type | Default | Description |
|---|---|---|---|
securities |
list[str] |
Required | Stock universe |
start_date |
str/date |
Required | Start date |
end_date |
str/date |
Required | End date |
starting_cash |
float |
100000 |
Initial capital |
benchmark |
str |
"000300.XSHG" |
Benchmark index |
position_pct |
float |
0.33 |
Maximum position size per stock |
position_amount |
int |
0 |
Fixed share count per buy |
report_suffix |
str |
"" |
Report filename suffix |
frequency |
str |
"daily" |
"daily" or "minute" |
estimate_memory_mb¶
Estimate the memory footprint of preloaded data. Returns a dict (panel_mb, close_dict_mb, bar_cache_mb, total_mb).
run_paper_trade¶
Paper trading session; runs continuously until terminated with Ctrl+C.
record¶
Record custom data points within a strategy.
Scheduling Functions¶
| API | Description |
|---|---|
run_daily(func, time='every_bar') |
Execute daily at a fixed time |
run_weekly(func, day_of_week=1, time='09:30') |
Execute weekly on a given day |
run_monthly(func, day_of_month=1, time='09:30') |
Execute monthly on a given day |
run_selection(func, rebalance='monthly:1') |
Register a stock selection function and run it on a schedule |
rebalance format: "monthly:N" (Nth day of each month), "weekly:N" (day of week, 0=Monday), "daily" (every trading day).
Lifecycle Callbacks¶
| API | Description |
|---|---|
before_trading_start(func) |
Register a pre-market callback |
after_trading_end(func) |
Register a post-market callback |
Cache API¶
| API | Description |
|---|---|
set_cache_dir(path) |
Set the disk cache directory |
fetch_cached(security, start_date, end_date, adjust='qfq') |
Retrieve data with cache-first priority |
Data source integration recommendation: keep API input/output signatures unchanged, persist data in a unified format before entering the backtest, and use primary-standby data source switching with cross-validation.
Logging API¶
Basic Logging¶
Structured Logging¶
| API | Description |
|---|---|
log.section(title, **fields) |
Mark a high-level stage |
log.step(name, status='RUN', **fields) |
Record a step status |
log.progress(current, total, label='Progress') |
Display progress |
log.action(name, target=None, **fields) |
Record an action |
log.set_level(level) |
Control verbosity |
log.set_quiet(enabled=True) |
Output only WARNING/ERROR |
Utility API¶
| API | Description |
|---|---|
engine.get_context() |
Get the current backtest context |
engine.get_g() |
Get the global object |
engine.get_trade_log() |
Get the trade log |
engine.get_recorded_values() |
Get values recorded by record() |
Parameterization & Optimization Conventions¶
The eqlib API works with any Python workflow (scripts, notebooks, scheduled tasks). A typical call chain: run_backtest() → analyze_returns() → brinson_attribution() → analyze results → modify parameters → re-run backtest.
Strategy files define PARAMS (current values) and PARAM_RANGES (search space), which are read and updated by the optimization script. After each change, verify that: new parameters fall within range, cross-parameter constraints are satisfied, and no look-ahead bias is introduced.
Support/resistance risk-budget strategy [EXPERIMENTAL]¶
from eqlib.strategies import SRRiskConfig, make_sr_risk_budget_strategy
initialize = make_sr_risk_budget_strategy(
universe=["601398", "601318"], config=SRRiskConfig(),
benchmark="000300.XSHG", order_cost=None, eligible=None,
)
SRRiskConfig defines planned risk and signal conditions. The factory returns a daily initialize callback. Supply eligible(code, date) for point-in-time membership/ST eligibility; otherwise the watchlist is static. See full rules and limitations.
New strictly boolean switches allow_breakout=False, require_market_slope=True and exit_on_market_filter=True control direct breakouts, benchmark slope confirmation and failed-filter exits. Defaults are preserved. None of 11 configurations passed validation; see the research record.