Simulator Engine¶
Warning
This module is not meant to be used directly. Just included in the documentation for reference of implementation details. See Run Modes for direct usage.
Module: simulator @ simulator/simulator_core.py
Provides the core functionality for running trading simulations using Tradeforce. It defines the main entry point, run(), which takes a Tradeforce instance as input, preprocesses the market history data, and performs trading simulations using Numba JIT-compiled functions. The module includes functions to iterate through market history within specified subsets, perform buy and sell operations, update budgets based on transactions, and calculate the score based on the mean profit corrected by standard deviation of profits across all subsets. The module also provides utility functions to sanitize subset parameters, calculate and print simulation details, and convert data structures to numpy arrays for use with Numba.
The np.array “buybag” contains the details of all buy transactions and is used to store asset attributes, such as amount and profit ratio. Those attributes also help to determine the elapsed time since buy or keep track of the available budget.
The np.array “soldbag” contains the details of all sell transactions, which also include all the details from the buybag. The “soldbag” is used to calculate the actual profit of each of the sold assets and stores sell relevant attributes, like sell price and time.
- Index reference for the buybag and soldbag arrays:
# Only buybag: [0] idx of asset row -> symbol of asset [1] buy_signal_score [2] row_idx at buy time [3] price buy [4] price including profit [5] amount of fiat invested, fee included [6] amount of asset invested, fee included [7] amount fee buy order in fiat (probably taker fee) [8] budget to invest
# soldbag also includes: [9] row_idx of sell opportunity [10] price sell [11] amount of fiat sold, fee included [12] amount of asset sold, fee included [13] amount fee sell order in fiat (probably maker fee) [14] amount profit in fiat
- tradeforce.simulator.simulator_core.iterate_market_history(params, subset_bounds, asset_prices, asset_prices_pct, buy_signals)¶
Iterate through the market history within a specified subset
performing trading operations based on the given parameters.
- Parameters:
params (
dict) – Dict containing simulation parameters.subset_bounds (
tuple[int,int]) – Tuple with the start and end indices of the current subset.asset_prices (
ndarray) – Array with the asset prices.asset_prices_pct (
ndarray) – Array with the asset prices percentage.buy_signals (
ndarray) – Array containing the buy signals.
- Return type:
tuple[ndarray,ndarray]- Returns:
A tuple with two numpy arrays, soldbag and buybag, representing the transactions.
- tradeforce.simulator.simulator_core.perform_trading_simulations(params, asset_prices, asset_prices_pct, buy_signals)¶
Perform trading simulations
using the given parameters and market data: Iterate over all subsets of the provided market data and simulate trading within those subsets based on the specified trading strategy and parameters.
Finally calculate the score, also gather trades history and buy log for the entire simulation.
- Parameters:
params (
dict) – Dict containing simulation parameters, such as trading strategy, investment amount, and trading fees.asset_prices (
ndarray) – Array containing the asset prices for each trading day.asset_prices_pct (
ndarray) – Array containing the asset price percentage changes for each trading day.buy_signals (
ndarray) – Array containing the buy signals.
- Returns:
- Score: The mean profit across all subsets, adjusted by subtracting the
standard deviation of the profits.
- Array containing the trading history across all subsets,
including buy and sell events.
- Array containing the buy log,
which records the details of each buy event.
- Return type:
A tuple with three elements
- tradeforce.simulator.simulator_core.print_simulation_details(root, asset_prices, dataset_type)¶
Print simulation details.
- Parameters:
root (
Tradeforce) – The Tradeforce instance containing the configuration.asset_prices (
DataFrame) – A DataFrame containing the asset prices.
- Return type:
None
- tradeforce.simulator.simulator_core.run(root, dataset_type, train_val_split_idx)¶
Run the trading simulation using the configuration provided in the Tradeforce instance. This function is the main entry point for simulations. It preprocesses the market history data, converts relevant data structures to numpy arrays for usage in Numba, and then performs the trading simulations to calculate the score, which is defined as:
mean(profit subset) - std(profit subset)The standard deviation is subtracted from the mean profit to penalize simulations with high variance of profit among subsets. This prevents overfitting to some specific market conditions which are not representative of the overall market (the total sum of subsets).
Warning
This function is not meant to be used directly. See Run Modes for direct usage.
- Parameters:
root – The Tradeforce instance containing the necessary configuration and market history data.
- Returns:
score(int): The score. See explanation of calculation above.trades(np.array): Array representing the trading history, including buy and sell events.buy_log(np.array): Array representing the buy log, containing the details of each buy event.
- Return type:
Dictionary containing the simulation results
- tradeforce.simulator.simulator_core.update_budget_from_last_transaction(row_idx, budget, bag, bag_type)¶
Update the budget
based on the last transaction in the bag if the row_idx of the last transaction matches the current row_idx. Ensures that the budget accurately reflects the latest transaction within the same row index in the given bag (buy or sell).
- Parameters:
row_idx (
int) – The current row index representing the position in the market history. This is used to determine whether the budget should be updated based on the last transaction.budget (
float) – The current budget, which represents the amount of funds available for trading.bag (
ndarray) – The transaction bag (buy or sell), a numpy array containing the details of each transaction.bag_type (
str) – The type of bag, either “buybag” or “soldbag”, indicating if the bag contains buy or sell transactions.
- Return type:
float- Returns:
The updated budget, which may be the same as the input budget if the last transaction’s row index does not match the current row index.