Rust backend documentation

vectorbtpro-rust

vectorbtpro-rust is the Rust compute backend for VectorBT PRO. It can be used in two ways:

As a regular Rust crate from a Rust project.
As the optional Python extension module vectorbtpro_rust, which VectorBT PRO can use through the jitting registry.

The same source code serves both users. Native Rust functions hold the actual algorithms. Python wrappers only prepare Python/NumPy inputs, call those native functions, and convert the result back to Python.

The Rust backend participates in VectorBT PRO globally. If the version-compatible package is not installed, supported jitted calls use Numba. If it is installed, supported calls prefer Rust automatically. Users do not need to change their code.

Architecture

The Rust source tree mirrors the VectorBT PRO Python package layout:

rust/Cargo.toml
rust/pyproject.toml
rust/src/lib.rs
rust/src/base/
rust/src/generic/
rust/src/portfolio/
rust/src/utils/
...
rust/tests/

The mirror covers the kernel layer of the Python package, not its wrapping or infrastructure layers. Top-level modules carry the names of the Python sub-packages that own kernels, and files map as follows:

Python	Rust
Flat `nb.py` in a sub-package	That module's `mod.rs`, for example `src/returns/mod.rs` for `vectorbtpro/returns/nb.py`
Module inside an `nb/` package	Same-named file, for example `src/generic/rolling.rs` for `vectorbtpro/generic/nb/rolling.py`
Kernel module outside `nb`	Same-named file, for example `src/base/reshaping.rs` for `vectorbtpro/base/reshaping.py`
`enums.py`	`enums.rs` in the matching module
Numba helpers in `vectorbtpro/utils/`	`src/utils/`, for example `src/utils/math.rs` for `vectorbtpro/utils/math_.py`

Modules without a Python counterpart serve only native Rust callers. They are described under Using from Rust.

Keep the versions in Cargo.toml, pyproject.toml, and the main VectorBT PRO package in sync. scripts/update_version.py updates all of them together. VectorBT PRO exposes vbt.rs only when the Python extension version matches the main package version.

The Cargo package is named vectorbtpro-rust, and Rust imports use the crate name vectorbtpro_rust. The crate exposes modules such as vectorbtpro_rust::base, vectorbtpro_rust::generic, and vectorbtpro_rust::portfolio. Cargo builds both an rlib for Rust users and a cdylib for the Python extension.

Regular Rust users do not need the python feature. That feature enables PyO3 and NumPy bindings and is used only for building vectorbtpro_rust as a Python extension.

The public API follows a small block pattern:

pub(crate) fn foo_impl(...) is the native serial implementation and validation boundary.
pub(crate) fn foo_parallel(...) is present when Rayon parallel execution is supported and owns any serial fallback.
#[bon::builder] pub fn foo(...) is the public Rust entry point. It owns Rust defaults and dispatches on the parallel flag only.
#[pyfunction] pub fn foo_rs(...) is the feature-gated Python wrapper. It keeps Python defaults and conversions, then calls _impl, _parallel, or a _py adapter directly.

For example, rust/src/returns/mod.rs defines the native implementation sharpe_ratio_1d_impl, the public builder vectorbtpro_rust::returns::sharpe_ratio_1d, and the Python wrapper sharpe_ratio_1d_rs. Rust users call the builder. Python users call the wrapper directly, as described under Direct calls, or more commonly through the registry with vectorbtpro.returns.nb.sharpe_ratio_1d_nb, which registers the Rust target with vectorbtpro.jitting.backends.rust.RustBackendSpec.

The crate is checked by API contract tests in rust/tests. Keep Rust ports as structural mirrors of their Numba functions. Function names, argument order, defaults, enum names, record names, and module order should stay searchable across both implementations.

For changes to portfolio internals, start with the module that owns the behavior:

Concern	Source
Order execution and fill accounting	portfolio/core.rs
Shared signal, limit, and stop resolution	portfolio/from_signals.rs
Dynamic group state and row accounting	simulator/engine.rs
Order and log buffers, cumulative IDs	simulator/recording.rs
Group ranges and segment activation	simulator/schedule.rs
Shared streaming configuration, buffers, and checkpoints	simulator/stream.rs

Read the owning module's rustdoc and implementation before changing it. Mode-specific strategy and stepper orchestration lives in simulator/order.rs and simulator/signal.rs.

Portfolio simulation axes

Portfolio simulators can be compared along two independent axes. The horizontal axis identifies how a strategy expresses decisions:

VBT can route compatible operations through its optional Rust extension while preserving the familiar Python interface. This section explains installation, automatic backend dispatch, interoperability with Numba, and direct access to native kernels when lower-level control is required.