Rust

vectorbtpro-rust

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

1. As a regular Rust crate from a Rust project.
2. 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.

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:

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:

1. pub(crate) fn foo_impl(...) is the native serial implementation and validation boundary.
2. pub(crate) fn foo_parallel(...) is present when Rayon parallel execution is supported and owns any serial fallback.
3. #[bon::builder] pub fn foo(...) is the public Rust entry point. It owns Rust defaults and dispatches on the parallel flag only.
4. #[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:

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: