Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:
VectorBT is a high-performance Python library designed for backtesting and analyzing trading strategies at scale. Its architecture is characterized by a "matrix-thinking" approach, where instead of iterating through time steps for a single configuration, it processes thousands of strategy configurations simultaneously using vectorized operations. The system leverages Pandas and NumPy for its data structures and achieves computational efficiency through Numba-accelerated kernels and an optional precompiled Rust engine.
The core design centers around wrapping data in specialized classes that provide high-performance accessors for technical analysis, signal generation, and portfolio backtesting. By decoupling the calculation logic (kernels) from the data management layer (wrappers and accessors), the library allows for rapid experimentation and large-scale parameter sweeps.
Sources: README.md:1-55, pyproject.toml:23-45
Core Computational Engines
The architecture utilizes a multi-tiered execution strategy to ensure maximum performance across different hardware and use cases. The system transparently dispatches calls to the most efficient engine available.
Numba and Rust Integration
While Numba provides Just-In-Time (JIT) compilation for Python kernels, the optional Rust engine provides high-performance, precompiled alternatives that avoid JIT overhead.
| Engine | Description | Use Case |
|---|---|---|
| Numba | Default JIT-accelerated engine using LLVM. | General vectorized operations and legacy random streams. |
| Rust | Precompiled engine via vectorbt-rust. | Maximum performance, deterministic array-oriented kernels. |
| Auto | Shared resolver logic in _engine.py. | Uses Rust if available and compatible; otherwise falls back to Numba. |
Sources: rust/README.md:12-45, README.md:58-62
Execution Flow
The following diagram illustrates how the library dispatches a computational request (e.g., calculating a Moving Average) based on the configured engine.
The shared resolver ensures that public APIs remain consistent regardless of the underlying backend.
Sources: rust/README.md:46-59, vectorbt/init.py:10-25
Data Structure Hierarchy
VectorBT's data management is built on top of the Wrapping class, which integrates ArrayWrapper to handle metadata like indices, columns, and frequency.
The Wrapping Mechanism
Most high-level objects in the library inherit from Wrapping, which provides the foundation for indexing, regrouping, and metadata propagation.
ArrayWrapper: Manages Pandas-like metadata (index, columns, freq) for underlying NumPy arrays.MappedArray: A specialized structure for working with arrays mapped to specific records (e.g., trades or signals). It allows reducing or expanding sparse data into dense DataFrames.
Sources: vectorbt/records/mapped_array.py:270-320, vectorbt/generic/stats_builder.py:33-40
Component Relationship Diagram
This diagram shows the relationship between the base metadata management and the specialized analysis mixins.
Analysis and Visualization Modules
The library employs a "Builder" pattern for generating statistics and interactive visualizations, allowing components to be highly configurable via a Config system.
Stats and Plots Builders
The StatsBuilderMixin and PlotsBuilderMixin provide the stats() and plots() methods found across the library. These methods use a centralized configuration to resolve metrics and subplots dynamically.
StatsBuilderMixin.stats(): Calculates a series of metrics (e.g., Mean, Sharpe, Max Drawdown) based on a provided configuration. It supports regrouping, filtering, and template-based settings.PlotsBuilderMixin.plots(): Generates complex multi-panel Plotly figures by resolving subplot functions and arranging them in a grid.
Sources: vectorbt/generic/stats_builder.py:84-150, vectorbt/generic/plots_builder.py:83-160
MappedArray Operations
MappedArray is a critical architectural component for handling sparse record data. It supports several high-level operations:
- Reducing: Aggregating values by column or group (e.g.,
ma.mean()). - Mapping: Applying functions per column/group (e.g.,
ma.apply()). - Expansion: Converting sparse records back into a dense Pandas representation (e.g.,
ma.to_pd()).
Sources: vectorbt/records/mapped_array.py:15-110
Project Configuration and Dependencies
The project's environment and build system are defined in pyproject.toml, highlighting its heavy reliance on the scientific Python stack.
| Dependency Type | Key Packages |
|---|---|
| Core | numpy, pandas, scipy, numba |
| Visualization | plotly, matplotlib, ipywidgets, anywidget |
| Utilities | tqdm, dill, requests, pytz |
| Optional (Full) | TA-Lib, yfinance, ccxt, pandas-ta-classic |
Sources: pyproject.toml:23-55, README.md:65-85
Summary
The VectorBT architecture is optimized for high-throughput financial analysis by combining the ease of use of Pandas with the performance of Numba and Rust. By representing multiple strategy configurations as dimensions in a matrix rather than discrete iterations, the system minimizes Python overhead. The modular design—separating metadata management (Wrapping), computational kernels (Numba/Rust), and analysis builders (Stats/Plots)—creates a flexible framework capable of scaling from simple backtests to massive parameter optimizations.