Quick Start Guide#

This guide provides a streamlined path to setting up the Backtest Engine and executing your first portfolio simulation. The engine uses a high-performance PyArrow-based architecture to handle data processing and backtesting.

Environment Configuration#

The Backtest Engine requires Python 3.12 or 3.13. It is recommended to use a virtual environment to manage dependencies and avoid conflicts.

  1. Create and Activate Environment:

    Using Conda:

    conda create --name backtest_engine python=3.12
conda activate backtest_engine

    Using venv:

    python -m venv .venv

    # Windows
.venv\Scripts\activate

    # Linux / macOS
source .venv/bin/activate

  2. Install the Backtest Engine:

    Run the pip install command from your license welcome email:

    pip install kaxanuk-backtest-engine --extra-index-url https://license:{YOUR_LICENSE_KEY}@{SERVER}/simple/

    Note

    The full command with your license key is included ready to copy in the welcome email you receive after purchase.

  3. Initialize Project Folders:

    Generate the required directory structure and the Excel configuration template.

    kaxanuk.backtest_engine init excel

  4. Set your license key:

    Open Config/.env and replace the placeholder with your actual license key:

    KNPC_API_KEY_KAXANUK=LIC-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

    This is loaded automatically by the entry script — no terminal environment variables needed.

Environment Structure#

The initialization process creates the following essential folders:

  • Config/: Contains backtest_engine_parameters.xlsx for defining simulation parameters and column mappings.

  • Input/Data/: Directory for market data files (CSV or Parquet).

  • Input/Portfolios/: Directory for portfolio weight files (CSV or Excel).

  • Output/: Directory where generated backtest results are stored.

Data Preparation#

Portfolio Files#

The engine supports both horizontal and vertical layouts. The PortfolioConfigurationService automatically detects the format based on the first column name.

  • Horizontal: First column must be named “Ticker”. Subsequent columns represent rebalancing dates.

  • Vertical: First column must be named “date”. Subsequent columns represent ticker symbols.

Market Data#

Market data files must include a date column and at least three price columns. Column names are fully configurable — you map them to their roles (commission price, trade execution price, mark-to-market price) in the configuration file. One file per ticker, named {TICKER}.csv or {TICKER}.parquet.

Execution#

Once your data is placed in the Input folders and parameters are configured in the Config Excel file, you can run the backtest using one of the following methods.

Command Line Interface#

The most direct way to execute the engine is through the CLI:

python -m kaxanuk.backtest_engine.services.cli autorun

Python Script#

You can also run the engine programmatically using the main entry point:

import kaxanuk.backtest_engine.backtest_engine
from kaxanuk.backtest_engine.config_handlers.excel_configurator import ExcelConfigurator
from kaxanuk.backtest_engine.input_handlers.csv_input import CsvInput
from kaxanuk.backtest_engine.input_handlers.csv_portfolio_input_handler import CsvPortfolioInputHandler
from kaxanuk.backtest_engine.services.env_loader import load_config_env

# Load Config/.env (license key)
load_config_env()

# 1. Load configuration from the Excel template
configurator = ExcelConfigurator(file_path='Config/backtest_engine_parameters.xlsx')
configuration = configurator.get_configuration()

# 2. Set up data handlers
market_data_handler = CsvInput(input_dir=configuration.input_market_data_directory)
portfolio_handler = CsvPortfolioInputHandler(base_dir=configuration.input_portfolio_directory)

# 3. Run the backtest
results = kaxanuk.backtest_engine.backtest_engine.main(
    configuration=configuration,
    input_handlers=[market_data_handler],
    portfolio_handlers=[portfolio_handler],
)

Pre-Execution Checklist#

Before running the backtest, ensure:

  • Portfolio files are correctly formatted and placed in Input/Portfolios.

  • Market data files are available in Input/Data with the proper column structure.

  • The configuration file backtest_engine_parameters.xlsx is completed.

  • All rebalancing dates in portfolio files exist within the market data date range.

  • No null values are present in any input files.