Internals

Read this to find where a concern lives and which sub-packages may depend on which.

For a known feature or error, start with the concern map and read the owning module's docstring. Before adding an import or moving code, check layers and dependency rules. Use recurring file kinds to find the kernel, wrapper, or preparer within that owner.

Repository layout

Design in one paragraph

VectorBT PRO represents time series as columns in two-dimensional arrays, so that many assets or strategy instances can be computed at once. Grouped columns can interact, for example by sharing cash. The code has three main parts. Kernels are Numba-compiled or Rust functions that operate on arrays, scalars, and structured state. Some also accept compiled callbacks. Wrapping objects are Python objects whose wrapper carries Pandas metadata (index, columns, grouping, frequency) next to raw arrays and translates between the two worlds. Infrastructure decides how a kernel runs: which backend, whether it is split into chunks, whether its result is cached, and whether a progress bar is shown. Each sub-package contributes some of each, and the layers below keep them pointing in one direction.

Layers

Solid arrows are module-level imports and dotted arrows are call-time imports. A double arrow means the two sides import each other at module level but stay acyclic at module granularity. Only informative edges are drawn: every layer may also import any layer below it.

Foundation

vectorbtpro.utils, the infrastructure sub-packages (vectorbtpro.caching, vectorbtpro.jitting, vectorbtpro.chunking, vectorbtpro.pbar, vectorbtpro.benchmarks), and the settings modules form one layer that knows nothing about Pandas wrapping, time series, or trading at import time. Its parts are interleaved at module level. The domain-free utils modules sit at the bottom, and infrastructure and vectorbtpro._settings build on them. Among the infrastructure sub-packages, vectorbtpro.caching, vectorbtpro.jitting, and vectorbtpro.pbar import none of the others, vectorbtpro.chunking builds on jitting, and vectorbtpro.benchmarks builds on jitting and pbar. Some utils modules build on infrastructure in turn: configs are cacheable, Numba helpers register with the jitting registry, and execution engines use progress bars.

vectorbtpro._typing and vectorbtpro._version sit below everything and import nothing from the package at runtime. _typing imports package modules only under tp.TYPE_CHECKING, for annotations.

Core

vectorbtpro.base is the non-computational core. It converts between NumPy arrays and Pandas objects: broadcasting, reshaping, indexing, grouping, resampling, and the array wrapper. It depends only on the foundation.

vectorbtpro.generic is the computational core, and vectorbtpro.records provides the sparse event representation. The two packages import each other, but at module granularity the order is strict:

1. The generic kernels, enums, and vectorbtpro.generic.analyzable load first.
2. records builds on them.
3. The record-based classes in generic and the generic accessor build on records.

A module that needs vectorbtpro.records.base.Records therefore belongs to the upper part of generic, and records must not import from that upper part.

Domain

Domain sub-packages specialize the core for one kind of data. Their order: