Futures#

The backtesting engine supports the following types of market data: snapshot, minute-level data, and daily-level data.

Engine Configuration#

Key	Description	Notes
“start_date”	start date	DATE type, required. e.g. “2020.01.01”.
“end_date”	end date	DATE type, required. e.g. “2020.01.01”.
“asset_type”	strategy type	required, must be “futures”
“cash”	initial capital	DOUBLE type, required.
“data_type”	market data type	INT type, required. Options: 1: snapshot; 3: minute-level; 4: daily data.
“frequency”	bar frequency for snapshot data	INT type, default = 0. Applicable only when `data_type = 1`. When `frequency = 0`, this parameter is ignored. When `data_type = 1` and `frequency > 0`, the engine internally calculates bars at the specified frequency and triggers the `on_bar` callback.
“msgAsTable”	market data format	BOOL type, default = `false`. false: dictionary format true: table.
“matchingMode”	order matching mode	INT type, options: 1: daily data: match at close minute-level data: orders will be matched with market data whose time is later than the order time 2: daily data: match at open. minute-level data: match when data time = order time, using the close price 3: match orders at the order price. Note: When `data_type = 1`, values 1 and 2 are invalid; orders are matched by the simulated matching engine by default.
“bench_mark”	benchmark instrument	STRING or SYMBOL type, e.g. “A2305”.
“latency”	order latency (ms)	INT type, the latency from order submission to execution.
“maintenance_margin”	maintenance margin ratio	DOUBLE type, default = 1.0. value range: 0–1.0.
“enable_algo_order”	enable algorithmic orders	true: enabled; false: disabled.
“futures_type”	futures category, e.g., index futures, commodity futures	STRING or SYMBOL type. Currently supports futures only
“enable_indicator_optimize”	enable indicator optimization	true: enabled; false (default): disabled.
“isBacktestMode”	backtest mode flag	true (default): backtest mode; false: simulated trading mode.
“dataRetentionWindow”	data retention policy for indicator optimization	STRING/INT type. Effecti ve only when both enable_indicator_optimize = true and isBacktestMode = true: ”None”(default): Retain no data. ”ALL”: Retain all data. Retain data by trading days, e.g., “20d” retains 20 trading days. Retain data by row count, e.g., “20” retains the latest 20 rows per symbol.
“add_time_column_in_indicator”	add time column to indicator subscription results	false (default): omit time column true: add time column
“context”	strategy context structure	A dictionary consisting of global strategy variables, for example: `context = {} context[“buySignalRSI”] = 30.0 config[“context”] = context`
“callback_for_snapshot”	snapshot callback mode	Available only for `data_type=1`. INT type, default `0`. 0: trigger `on_snapshot` only 1: trigger both `on_snapshot` and `on_bar` 2: trigger `on_bar` only If `frequency > 0`, must trigger `on_bar` (`callback_for_snapshot = 1 or 2`).
“orderbook_matching_ratio”	the proportion of an order that gets filled	DOUBLE type, default = 1.0, value range: 0–1.0. Applicable only when `data_type = 1`.
“matching_ratio”	matching ratio within price intervals	DOUBLE type, default 1.0, value range: 0–1.0. Applicable only when `data_type = 1`.

Note:

The available engine configuration parameters differ depending on the data type (data_type).

The parameters callback_for_snapshot, orderbook_matching_ratio, and matching_ratio are only applicable when data_type = 1.

Security Reference Table Description#

Field	Type	Description
symbol	SYMBOL or STRING	futures contract code
multiplier	DOUBLE	contract multiplier
marginRatio	DOUBLE	margin ratio
tradeUnit	DOUBLE	contract unit
priceUnit	DOUBLE	quotation unit
priceTick	DOUBLE	minimum price fluctuation
commission	DOUBLE	commission fee
deliveryCommissionMode	INT	commission calculation mode: 1: commission × number of contracts traded 2: commission × trade value

Snapshot Data#

Market Data Structure Description#

The data structure of the market snapshot table written via append_data is as follows:

message_table = sf.table(
    types={
        "symbol": "STRING",
        "symbolSource": "STRING",
        "timestamp": "TIMESTAMP",
        "tradingDay": "DATE",
        "lastPrice": "DOUBLE",
        "upLimitPrice": "DOUBLE",
        "downLimitPrice": "DOUBLE",
        "totalBidQty": "LONG",
        "totalOfferQty": "LONG",
        "bidPrice": "DOUBLE[]",
        "bidQty": "LONG[]",
        "offerPrice": "DOUBLE[]",
        "offerQty": "LONG[]",
        "highPrice": "DOUBLE",
        "lowPrice": "DOUBLE",
        "prevClosePrice": "DOUBLE",
        "settlementPrice": "DOUBLE",
        "prevSettlementPrice": "DOUBLE"
    },
    size=0,
    capacity=10000000
)

Notes:

The structure above applies to snapshot data (callback_for_snapshot = 0), i.e., not aggregated into bar data.
Column names must match exactly as listed. The order is flexible except the first column, which must be symbol.
Additional columns of types INT, DOUBLE, STRING, or an extended field signal of type DOUBLE ARRAY VECTOR are supported.

Required Fields for Snapshot Data Table#

Field	Type	Description
symbol	SYMBOL	futures contract code
symbolSource	STRING	exchange name
timestamp	TIMESTAMP	timestamp
tradingDay	DATE	trading day / settlement date
lastPrice	DOUBLE	latest traded price
upLimitPrice	DOUBLE	limit up price
downLimitPrice	DOUBLE	limit down price
totalBidQty	LONG	cumulative buy quantity
totalOfferQty	LONG	cumulative sell quantity
bidPrice	DOUBLE[]	bid prices
bidQty	LONG[]	bid quantities
offerPrice	DOUBLE[]	ask prices
offerQty	LONG[]	ask quantities
highPrice	DOUBLE	highest price
lowPrice	DOUBLE	lowest price
signal	DOUBLE[]	extended field list (required in JIT mode)
prevClosePrice	DOUBLE	previous closing price (required in JIT mode)
settlementPrice	DOUBLE	settlement price (required in JIT mode)
prevSettlementPrice	DOUBLE	previous settlement price (required in JIT mode)

When frequency > 0 and callback_for_snapshot = 1 or 2, the table structure is as follows:

message_table = sf.table(
    types={
        "symbol": "STRING",
        "symbolSource": "STRING",
        "timestamp": "TIMESTAMP",
        "tradingDay": "DATE",
        "lastPrice": "DOUBLE",
        "upLimitPrice": "DOUBLE",
        "downLimitPrice": "DOUBLE",
        "totalBidQty": "LONG",
        "totalOfferQty": "LONG",
        "bidPrice": "DOUBLE[]",
        "bidQty": "LONG[]",
        "offerPrice": "DOUBLE[]",
        "offerQty": "LONG[]",
        "highPrice": "DOUBLE",
        "lowPrice": "DOUBLE",
        "signal": "DOUBLE",
        "prevClosePrice": "DOUBLE",
        "settlementPrice": "DOUBLE",
        "prevSettlementPrice": "DOUBLE",
        "open": "DOUBLE",
        "close": "DOUBLE",
        "low": "DOUBLE",
        "high": "DOUBLE",
        "volume": "LONG"
    },
    size=0,
    capacity=10000000
)

Notes:

When snapshot is aggregated into bars (callback_for_snapshot = 1 or 2), five additional fields must be included: "open", "close", "low", "high", and "volume".
Column names must match exactly as listed. Column order is flexible except for the first column, which must be symbol.
Additional columns of types INT, DOUBLE, STRING, or an extended field signal of type DOUBLE ARRAY VECTOR are supported.

Required fields for snapshot data (aggregated into bar) table

Field	Type	Description
symbol	SYMBOL	futures contract code
symbolSource	STRING	exchange name
timestamp	TIMESTAMP	timestamp
tradingDay	DATE	trading day / settlement date
lastPrice	DOUBLE	latest traded price
upLimitPrice	DOUBLE	limit up price
downLimitPrice	DOUBLE	limit down price
totalBidQty	LONG	cumulative buy quantity
totalOfferQty	LONG	cumulative sell quantity
bidPrice	DOUBLE[]	bid prices
bidQty	LONG[]	bid quantities
offerPrice	DOUBLE[]	ask prices
offerQty	LONG[]	ask quantities
highPrice	DOUBLE	highest price
lowPrice	DOUBLE	lowest price
signal	DOUBLE[]	extended field list (required in JIT mode)
prevClosePrice	DOUBLE	previous closing price (required in JIT mode)
settlementPrice	DOUBLE	settlement price (required in JIT mode)
prevSettlementPrice	DOUBLE	previous settlement price (required in JIT mode)
open	DOUBLE	open price of the generated bar
close	DOUBLE	close price of the generated bar
low	DOUBLE	lowest price of the generated bar
high	DOUBLE	highest price of the generated bar
volume	LONG	trading volume of the generated bar

At the end of the backtest data replay, send a message with symbol = "END":

message_table = sf.sql(
    "SELECT TOP 1 * FROM messageTable",
    vars={
        'messageTable': message_table
    }
)

sf.sql(
    "UPDATE messageTable SET symbol = `END",
    vars={'messageTable': message_table}
)

backtester.append_data(message_table)

Callback Functions#

Snapshot callback on_snapshot: input parameter: msg

When msg is a dictionary, it is keyed by symbol, and each value contains the following fields:

Field	Type	Description
symbol	SYMBOL	futures contract code
symbolSource	STRING	exchange name
timestamp	TIMESTAMP	timestamp
tradingDay	DATE	trading day / settlement date
lastPrice	DOUBLE	latest traded price
upLimitPrice	DOUBLE	limit-up price
downLimitPrice	DOUBLE	limit-down price
totalBidQty	LONG	cumulative buy quantity
totalOfferQty	LONG	cumulative sell quantity
bidPrice	DOUBLE[]	bid prices
bidQty	LONG[]	bid quantities
offerPrice	DOUBLE[]	ask prices
offerQty	LONG[]	ask quantities
highPrice	DOUBLE	highest price
lowPrice	DOUBLE	lowest price
signal	DOUBLE[]	extended field list
prevClosePrice	DOUBLE	previous closing price
settlementPrice	DOUBLE	settlement price
prevSettlementPrice	DOUBLE	previous settlement price
open	DOUBLE	open price of the aggregated bar (only if `data_type = 1 or 2` and `callback_for_snapshot = 1 or 2`)
close	DOUBLE	close price of the aggregated bar (only if `data_type = 1 or 2` and `callback_for_snapshot = 1 or 2`)
low	DOUBLE	the lowest price of the aggregated bar (only if `data_type = 1 or 2` and `callback_for_snapshot = 1 or 2`)
high	DOUBLE	the highest price of the aggregated bar (only if `data_type = 1 or 2` and `callback_for_snapshot = 1 or 2`)
volume	LONG	trading volume of the aggregated bar (only if `data_type = 1 or 2` and `callback_for_snapshot = 1 or 2`)

Notes:

When snapshot data is aggregated into bars (frequency > 0 and callback_for_snapshot = 1 or 2), the msg object must include five additional fields: "open", "close", "low", "high", and "volume".
When callback_for_snapshot = 1, the on_bar function must also be triggered, and the input msg structure is as follows.

Bar callback function: on_bar: input parameter: msg

When msg is a dictionary, it is keyed by symbol, and each bar object contains the following fields:

Field	Type	Description
symbol	SYMBOL	futures contract code
symbolSource	STRING	exchange name
timestamp	TIMESTAMP	timestamp
tradingDay	DATE	trading day / settlement date
lastPrice	DOUBLE	latest traded price
upLimitPrice	DOUBLE	limit-up price
downLimitPrice	DOUBLE	limit-down price
totalBidQty	LONG	cumulative buy quantity
totalOfferQty	LONG	cumulative sell quantity
bidPrice	DOUBLE[]	bid prices
bidQty	LONG[]	bid quantities
offerPrice	DOUBLE[]	ask prices
offerQty	LONG[]	ask quantities
highPrice	DOUBLE	the highest price
lowPrice	DOUBLE	the lowest price
signal	DOUBLE[]	extended field list
prevClosePrice	DOUBLE	previous closing price
settlementPrice	DOUBLE	settlement price
prevSettlementPrice	DOUBLE	previous settlement price

Minute-Level or Daily Data#

Market Data Structure Description#

The market data table structure written via append_data is as follows:

message_table = sf.table(
    types={
        "symbol": "SYMBOL",
        "symbolSource": "SYMBOL",
        "tradeTime": "TIMESTAMP",
        "tradingDay": "DATE",
        "open": "DOUBLE",
        "low": "DOUBLE",
        "high": "DOUBLE",
        "close": "DOUBLE",
        "volume": "LONG",
        "amount": "DOUBLE",
        "upLimitPrice": "DOUBLE",
        "downLimitPrice": "DOUBLE",
        "prevClosePrice": "DOUBLE",
        "settlementPrice": "DOUBLE",
        "prevSettlementPrice": "DOUBLE"
    },
    size=0,
    capacity=10000000
)

Notes:

Column names must match exactly as listed.
The order of columns is flexible except that the first column must be symbol.
Additional columns of type INT, DOUBLE, or STRING are supported, as well as an extended field named signal of type DOUBLE ARRAY VECTOR.

Required Fields for Minute-level or Daily Data#

Field	Type	Description
symbol	SYMBOL	futures contract code
symbolSource	STRING	exchange name
tradeTime	TIMESTAMP	timestamp
tradingDay	DATE	trading day / settlement date
open	DOUBLE	opening price
low	DOUBLE	the lowest price
high	DOUBLE	the highest price
close	DOUBLE	closing price
volume	LONG	trading volume
amount	DOUBLE	trading amount (required in JIT mode only)
upLimitPrice	DOUBLE	limit-up price
downLimitPrice	DOUBLE	limit-down price
signal	DOUBLE[]	extended field list (required in JIT mode only)
prevClosePrice	DOUBLE	previous closing price (required in JIT mode only)
settlementPrice	DOUBLE	settlement price (required in JIT mode only)
prevSettlementPrice	DOUBLE	previous settlement price (required in JIT mode only)

At the end of the backtest data replay, send a message with symbol = "END":

message_table = sf.sql(
    "SELECT TOP 1 * FROM messageTable,
    vars={
        'messageTable': message_table
    }
)

sf.sql(
    "UPDATE messageTable SET symbol = `END",
    vars={'messageTable': message_table}
)

backtester.append_data(message_table)

Callback Function#

OHLC data callback function on_bar: input parameter msg

When msg is a dictionary, it is keyed by symbol, and each value contains a minute-level (or daily-level) object with the following fields:

Field	Type	Description
symbol	SYMBOL	futures contract code
symbolSource	STRING	exchange name
timestamp	TIMESTAMP	timestamp
tradingDay	DATE	trading day / settlement date
lastPrice	DOUBLE	latest traded price
upLimitPrice	DOUBLE	limit-up price
downLimitPrice	DOUBLE	limit-down price
totalBidQty	LONG	cumulative buy quantity
totalOfferQty	LONG	cumulative sell quantity
bidPrice	DOUBLE[]	bid prices
bidQty	LONG[]	bid quantities
offerPrice	DOUBLE[]	ask prices
offerQty	LONG[]	ask quantities
highPrice	DOUBLE	highest price
lowPrice	DOUBLE	lowest price
signal	DOUBLE[]	extended field list
prevClosePrice	DOUBLE	previous closing price
settlementPrice	DOUBLE	settlement price
prevSettlementPrice	DOUBLE	previous settlement price