ADR-0004: Vectorized NumPy over Python loops
- Date: 2026-06-26
- Status: Accepted
Context
Generators often produce many samples at once. Per-row RNG calls and per-column pandas .iloc
accesses inside Python loops were orders of magnitude slower than batched NumPy operations. A
concrete case: random_spherical_coordinate used an O(d²) np.prod(sin_phis[:i]) pattern.
Decision
All generator implementations must prefer batched/vectorized NumPy operations over Python-level
for loops, especially when n_samples can be large.
Three canonical patterns:
- Per-row RNG → batched RNG. Replace
[rng.exponential(size=d) for _ in range(n)]withrng.exponential(size=(n, d)). - Per-column
.iloc/.choice→ integer array indexing. Replacenp.stack([rng.choice(X.iloc[:, i], ...) for i in range(d)])withX.values[row_idx, np.arange(d)]. - Batch variants for utilities. When a utility operates on a single sample (e.g.
random_spherical_coordinate), also provide a batch version (random_spherical_coordinates) accepting arrays withaxis=parameters.
When not to vectorize: small n_samples (≤ 10), and algorithms requiring sequential state
(e.g. rejection sampling with an unknown iteration count).
Consequences
- Large speedups on the common path.
- Two APIs to maintain for some utilities (single-sample and batch).
DataFrame.iloc[:, i]inside a loop is treated as a code smell in review.- The O(d²) spherical-coordinate pattern was fixed to O(d) via
np.cumprod.