ferro-ta/docs/guides/simd.md

SIMD acceleration

ferro-ta accelerates hot reductions with runtime CPU-feature dispatch via the multiversion crate. Each dispatched function is compiled into several variants — baseline, SSE, AVX2/FMA, AVX-512 on x86_64; NEON on aarch64 — and the fastest one the current CPU supports is chosen at load time via CPUID.

Why dispatch instead of -C target-cpu

A static RUSTFLAGS=-C target-cpu=x86-64-v3 build requires AVX2 on the running CPU; on an older chip it crashes with an illegal instruction (SIGILL). Runtime dispatch instead ships every code path in one binary and picks at runtime, so a single artifact:

• runs on any CPU of the target architecture (no SIGILL on pre-AVX2 hardware), and
• still uses wide vector units where the hardware has them.

That property is what lets the same wheel / Docker image / crate run across a heterogeneous fleet.

When it helps

SIMD helps indicators whose inner loop is a reduction over contiguous f64 data — e.g. the initial window sum that seeds SMA, the (T, S) seed for WMA, and similar fixed-window reductions. It does not help:

• The O(n) streaming recurrences (window_sum += new - old): each step depends on the previous one, so they are inherently sequential.
• Branchy inner loops (SAR, candlestick patterns).
• Streaming classes (a single-bar update is one or two ops).

The shared primitives live in crates/ferro_ta_core/src/simd.rs (sum, wma_seed). They accumulate into independent lanes before a final horizontal combine — that lane independence is what allows the optimizer to vectorize each CPU-feature variant. A consequence is that results differ from a strict left-to-right sum by a few ULPs, well inside every indicator's documented tolerance.

The simd feature

Dispatch is gated behind the simd Cargo feature, which is on by default:

# default build — runtime dispatch enabled
cargo build -p ferro_ta_core --release

# pure-scalar build (debugging / baseline benchmarking)
cargo build -p ferro_ta_core --release --no-default-features

For Python, wheels published to PyPI are built with the default features, so pip install ferro-ta ships the dispatched fast path with no action on your part. To build a pure-scalar extension from source:

maturin develop --release --no-default-features

Measured speedups

The nightly benchmarks/bench_simd.py job (see .github/workflows/nightly-bench.yml) builds the extension twice — once with --no-default-features (pure scalar) and once with --features simd (dispatch) — and reports the per-indicator delta. Numbers are regenerated on every run and vary with hardware; treat any table in a PR as a snapshot, not a contract. The dispatched kernels here target correctness-preserving reductions, so gains are modest on the sliding-window indicators and larger on full-array reductions.

Adding a SIMD-optimized indicator

1. Write and test the scalar implementation first — it is the ground truth.
2. If the hot path is a contiguous f64 reduction, route it through a crate::simd primitive, or wrap a new helper in #[multiversion::multiversion(targets = "simd")] with the loop body accumulating into independent lanes.
3. Add a parity test comparing the dispatched result against the strict scalar reference within tolerance (see simd.rs tests for the pattern).
4. Benchmark scalar vs dispatch via bench_simd.py. Only keep the SIMD path if it wins — alignment and tail-handling overhead can make a naive vectorization lose to scalar.

See also

• crates/ferro_ta_core/src/simd.rs — dispatched primitives and tests.
• benches/indicators.rs — criterion suite.
• crates/ferro_ta_core/Cargo.toml [features] simd = ["dep:multiversion"] — the gate (default-on).