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/

Keep the versions in Cargo.toml, pyproject.toml, and the main VectorBT PRO package in sync. VectorBT PRO exposes vbt.rs only when the Python extension version matches the main package version.

The Cargo package is named vectorbtpro-rust; Rust imports use the crate name vectorbtpro_rust. The crate exposes modules such as base, generic, and 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 native implementation sharpe_ratio_1d_impl, public builder sharpe_ratio_1d, and Python wrapper sharpe_ratio_1d_rs. Rust users call sharpe_ratio_1d as a builder. Python users normally reach sharpe_ratio_1d_rs directly through sharpe_ratio_1d_rs, or through the registry with sharpe_ratio_1d_nb, which registers the Rust target with 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.

Portfolio simulation axes

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

The vertical axis identifies which engine executes those decisions:

Together, the two axes describe the common simulation contract: accounting and order semantics, global rows and record IDs, continuation state, and terminal output. The diagrams group related interfaces and engines. They do not imply a call sequence or performance ranking.

Along the horizontal axis, from_orders consumes precomputed order fields and from_signals converts directional signals into orders while managing conflicts, limits, and stops. Order functions ask a strategy callback for one decision per call. Flexible order functions can emit multiple decisions and choose their columns.

Along the vertical axis, static Numba runs fixed kernels and dynamic Numba invokes user callbacks during simulation. Static Rust provides structural ports of supported fixed kernels. The native Rust simulators execute typed strategies over complete input arrays, while their streaming counterparts process one row at a time and retain simulation state.