Epic: Row-oriented scalar functions

[connortsui20]

Yes, I did write this by hand. I actually had the LLM separate most of my writing out into tracking issues!

Right now, functions whose natural implementation operates on one row still have to own much of the machinery for executing that operation over columnar Vortex arrays.

This Epic tracks a RowFn definition that separates those concerns. A scalar function implementor can choose typed row elements and define the computation/operation, while the framework handles batch decoding, dtype validation, constants, null rows, output construction, and more.

Status

Proposed.

There is a working (albeit highly experimental) prototype with primitive, bytes, tensor, and geometry functions (see github or diffshub since there's 10k lines of AI-generated code). The remaining work is to settle the API and execution contracts and then split the implementation into reviewable changes.

Subissues

• Tracking Issue: Define the RowFn API #9129
• Tracking Issue: Execute RowFn over Vortex arrays #9130

Goal

A scalar function whose natural implementation operates on one typed row should be able to define that operation without also implementing the surrounding array machinery.

The goals are:

• Define a stable RowFn API for choosing typed inputs, preparing batch state, computing rows, and building outputs.
• Share validation, batch decoding, constant handling, null propagation, output allocation, and validity handling across row functions.
• Allow crates such as vortex-tensor and vortex-geo to add row representations without changing vortex-array.
• Preserve encoding-aware shortcuts for functions that have a better answer for a specific encoding.
• Avoid a performance penalty for already-efficient row kernels, while making commonly missed optimizations reusable.
• Support optional row outputs for strict functions that may return null from otherwise valid inputs.

Note that we will focus solely on strict functions. as the semantics around non-strict functions are complicated enough that it's probably not worth extending this already-somewhat-complicated API further.

RowFn is also not intended for columnar or zero-copy kernels (not, list_length), kernels with state shared across rows (like), or heterogeneous variadic kernels.

Motivation

We have a good number of scalar function implementations in the Vortex codebase, and because it is simply a trait implementation of ScalarFnVTable, anyone can add their own scalar function.

However, writing a good implementation is not exactly trivial. Suppose we want to add a scalar function Hypot to Vortex that is similar to hypot. This simply gets distance from the origin to the point (x, y) via sqrt(x^2 + y^2).

Even though this is arguably a "basic" scalar function, there are MANY things that the implementor needs to worry about w.r.t. correctness and performance.

• Depending on what the implementor wants, they might need to implement this for when x and y are arbitrary floating-point types such as f16, f32, and f64. Maybe they want to accept integers without an explicit cast!
• How should they deal with null values / validity? What should the result of hypot(null, 5.0) be?
• Depending on how they want their null semantics, they might want to do a bunch of stuff with validity up front before moving onto the compute (perhaps intersect the validity of the 2 inputs).
• This sqrt(x^2 + y^2) operation is small enough that the implementor would want to ensure auto-vectorization can happen, so they need to make sure there is no branching in hot loops.
• How do they pre-allocate memory correctly?
• If one or both columns of x and y are ConstantArray, then they definitely want to precompute x^2 and y^2 rather than doing it n times.

Note that in practice we would probably want to decompose hypot() into an expression that does sqrt(x^2 + y^2) as a tree of numeric expressions for better optimizations, but hopefully you get the idea that there are several things that many scalar function implementations have to worry about, even if the function is "simple".

More often than not, the scalar function implementor is only going to worry about a subset of these and leave potential performance optimizations on the table.

So this begs the question: Can scalar functions be defined in terms of their natural operation on a single typed row, without giving up Vortex’s array semantics, extension types, encoding-aware shortcuts, or performance?

RowFn rationale

Every row-oriented scalar function execution follows roughly the same execution pipeline:

1. Validate the input types.
2. Handle degenerate inputs, such as null constants or entirely constant arguments.
3. Decode each input column once.
4. Compute anything that is constant/static for the batch.
5. Read and compute one row at a time (hopefully in a vectorized manner).
6. Build the output and apply its validity.

Without a shared definition, every scalar function has to assemble this pipeline itself.

RowFn makes the owner of each step explicit:

1. InputElement validates each element dtype and ElementTuple validates arity.
2. Null constants and entirely constant inputs are handled automatically.
3. InputElement::decode prepares each column once, including stride-0 access for constants.
4. The prepare step of visit_prepared_into computes state derived from constant arguments once per batch.
5. ElementTuple::get reads each row and the function's closure performs the actual computation.
6. An OutputSink builds the result, after which the framework applies the input validity.

A blanket implementation turns every RowFn directly into a ScalarFnVTable, so there is no additional authoring layer between the row definition and the scalar function.

Preliminary performance

The previous shared-VM figures are superseded by the benchmark and codegen follow-up. It records the benchmark machinery, methodology, two-run results, control limitations, and representative generated LLVM IR/assembly in folded sections.

Unresolved questions

• Are nullable outputs from otherwise valid inputs required before the first version is complete? This is needed for strict but non-total functions such as list_sum and variant_get.
• Are InputElement, OutputElement, and OutputSink supported downstream extension points in the first stable API, or only cross-crate extension points within Vortex?

[connortsui20]

RowFn x86 AVX-512 re-measurement

Bottom line: the refreshed run still shows no general row-abstraction tax. The sink-only checked-add RowFn is 1.018–1.226× faster by median than its benchmark-local specialized control, and cosine is 1.40–30.13× faster than current develop depending on shape. The geo bbox diagnosis was correct: after widening the conservative constant-side bbox rejection, disjoint polygons return to parity and overlapping contains remains 8.60–8.77× faster by median. Two point/constant geo regressions remain real (8.6–14.2% and 10.9–13.2% higher median latency), and the x86 null-strategy sweep shows that one global 75% survivor threshold chooses the wrong strategy in both one- and two-nullable-input edge cases.

This replaces the stale measurements previously in this comment. l2_denorm is intentionally absent: it is now an encoding, not scalar-function parity evidence.

Host, revisions, and measurement protocol

• Date: 2026-08-04.
• Host: AMD Ryzen 9 7950X, 16 cores / 32 threads, x86-64 with AVX-512; Linux 7.1.5; rustc 1.91.0 / LLVM 21.1.2.
• Candidate: claude/strict-scalar-fn-abstraction-ah88x3 at d293d3cdd59e. Geo results additionally include the local bbox-widening patch described below.
• Baseline: current origin/develop at 876996fe7846, measured from a separate ../vortex2 worktree.
• The candidate merged develop through fae9da1ebb77; git merge-base --is-ancestor 2de0319312 HEAD passes, so both sides include geo perf(vortex-geo): short-circuit predicates with bounding boxes #9076 as required by the handoff.
• Timed runs were pinned to CPU 4 with taskset -c 4, Divan's TSC timer, and CPU 4's governor and EPP both set to performance.
• Cross-revision geo/cosine runs used ABBA ordering. Every reported range is from two sequential runs.
• Tensor, byte, and cosine: 100 samples, 2–4 seconds per arm. Geo and null-strategy diagnostics: 60 samples, 2–4 seconds per arm. Checked add: 100 samples, 1–2 seconds per arm.
• Tensor and public geo predicate batches have 16,384 rows. Checked add, byte length, and null-strategy batches have 65,536 rows.
• Ratios are control/develop ÷ candidate. Greater than 1× means the candidate is faster. F / M means the range of fastest times followed by the range of medians across the two runs.
• Wall-time binaries used the ordinary release benchmark configuration. The codegen audit was a separate release build with -C target-cpu=native -C codegen-units=1 and LLVM IR/assembly emission.

Executor, byte input element, and l2_norm

Workload	Candidate F / M	Control F / M	Control ÷ candidate F / M
checked add, two columns	128.4–129.6 / 129.5–130.9 µs	131.5–132.3 / 132.3–133.3 µs	1.021–1.024× / 1.018–1.022×
checked add, column + constant	13.82–13.85 / 14.04 µs	16.90–16.93 / 17.10–17.21 µs	1.222× / 1.218–1.226×
checked add, nullable columns	128.4–128.7 / 130.6–131.8 µs	133.8–134.8 / 136.1 µs	1.042–1.047× / 1.033–1.042×
byte length, long strings	168.2–168.5 / 169.0–169.2 µs	237.5 / 238.4–238.6 µs	1.409–1.412× / 1.410–1.411×
byte length, short strings	168.6 / 169.2–169.3 µs	184.9–185.3 / 185.6–185.8 µs	1.097–1.099× / 1.097×
l2_norm, width 2	32.67–32.69 / 34.59–34.60 µs	33.31–33.32 / 33.40 µs	1.019–1.020× / 0.965×
l2_norm, width 32	190.3–190.4 / 190.8–190.9 µs	196.5–196.9 / 198.0–198.1 µs	1.033–1.034× / 1.038×
l2_norm, width 256	2.425 / 2.438–2.440 ms	2.420–2.422 / 2.431–2.440 ms	0.998–0.999× / 0.996–1.001×

The checked-add “specialized” arm is a benchmark-local control, not a production scalar function. There is still no production deferred-error consumer; ERRORS_ARE_DEFERRED is exercised by this benchmark and row sink tests.

BytesLen avoids resolving a byte slice and reduces latency by about 29% for long strings and 9% for short/inlined strings. This is an input-element diagnostic, not a durable public-path develop comparison.

Nullable l2_norm has the same overall shape: width 32 is about 3.5% faster by median, width 256 is within 0.3%, and width 2 has a 4.4% median regression despite a slightly better fastest time. The width-2 fastest/median disagreement is repeatable, so both statistics should remain visible.

Cosine similarity against current develop

Shape / width	Candidate F / M	Develop F / M	Develop ÷ candidate F / M
column × column, 2	59.65–59.69 / 59.81–59.90 µs	343.8–344.8 / 345.3–346.6 µs	5.76–5.78× / 5.77–5.79×
column × column, 32	370.0–370.3 / 373.6–373.8 µs	711.9–713.4 / 721.4–818.3 µs	1.92–1.93× / 1.93–2.19×
column × column, 256	2.924–2.965 / 2.942–2.982 ms	7.539–7.570 / 7.564–7.593 ms	2.54–2.59× / 2.54–2.58×
column × constant, 2	65.37–65.39 / 65.56–65.58 µs	809.6–813.0 / 815.9–818.2 µs	12.38–12.44× / 12.44–12.48×
column × constant, 32	357.5–357.8 / 358.5–358.8 µs	10.33–10.34 / 10.35–10.39 ms	28.90× / 28.87–28.96×
column × constant, 256	2.823–2.827 / 2.839–2.840 ms	85.33–85.44 / 85.42–85.53 ms	30.22× / 30.08–30.13×
column × extension constant, 2	65.67–65.78 / 65.89–65.98 µs	198.8–199.6 / 200.8–201.5 µs	3.02–3.04× / 3.05×
column × extension constant, 32	358.2–358.3 / 359.2–360.0 µs	501.1–503.1 / 505.5–507.3 µs	1.40× / 1.40–1.41×
column × extension constant, 256	2.827–2.828 / 2.839–2.841 ms	5.022–5.029 / 5.039–5.053 ms	1.78× / 1.77–1.78×

The develop width-32 column/column median is bimodal, but its fastest ratio is stable at 1.92–1.93×. The win still comes from fusing dot/norm work and preparing a batch-constant norm rather than running develop's separate reductions and divide pass.

Geo diagnosis, bbox patch, and stabilized results

The first diagnostic run confirmed the handoff's prediction: after #9076, the candidate's narrower bbox gate made constant-point and disjoint-contains cases substantially worse than develop. I widened the candidate's conservative early-out before the final controlled run:

• contains caches each constant geometry's bounding_rect() and rejects whenever the container bbox cannot contain the contained bbox, for either constant arrangement.
• intersects now applies conservative disjoint-bbox rejection to every constant arrangement instead of only pairings where geo itself opens with that comparison.
• The exact direct/relate algorithm remains the fall-through.
• Prepared-versus-expanded agreement tests now include NaN point coordinates in both operand orders. NaN bounds do not cause a false rejection; unordered comparisons fall through to the exact predicate.

Final controlled results after that patch:

Case	Candidate median	Develop median	Develop ÷ candidate F / M
contains column × column points	2.774–2.792 ms	2.654–2.674 ms	0.947–0.960× / 0.951–0.964×
contains column × column polygons	4.831–4.849 ms	4.842–4.846 ms	0.996–1.003× / 0.999–1.003×
contains constant × points	1.516–1.525 ms	1.328–1.404 ms	0.867–0.916× / 0.876–0.921×
contains constant × disjoint polygons	2.444–2.453 ms	2.427–2.445 ms	0.980–0.995× / 0.993–0.997×
contains constant × overlapping polygons	37.64–38.08 ms	327.5–330.2 ms	8.70–8.79× / 8.60–8.77×
intersects column × column polygons	4.550–4.603 ms	4.525–4.526 ms	0.986–0.992× / 0.983–0.995×
intersects points × constant	1.511–1.513 ms	1.337–1.363 ms	0.918–0.919× / 0.884–0.902×
intersects disjoint polygons × constant	2.387–2.410 ms	2.432–2.437 ms	1.008–1.014× / 1.011–1.019×
intersects overlapping polygons × constant	6.019–6.078 ms	6.143–6.156 ms	1.006–1.014× / 1.011–1.023×

The patch restores disjoint polygon parity and retains the prepared-geometry win. The remaining point/constant regressions are settled rather than noise:

• contains constant × points: candidate median is 8.6–14.2% higher than develop.
• intersects points × constant: candidate median is 10.9–13.2% higher than develop.
• contains column × column points is also about 3.7–5.2% higher by median.

The separate predicate_bbox diagnostic measures the mechanism directly: disjoint bbox rejection is 33.4–33.5× faster by median than the exact predicate, while an overlapping bbox adds only 1.8–1.9% median overhead before exact evaluation.

Adaptive null-strategy sweep

The global BRANCH_MIN_SURVIVING_FRACTION = 0.75 rule does not pick the best strategy in all x86 cases.

Shape	Null density	Auto F / M	Branch F / M	Filter F / M
one nullable input	50%	5.962–6.014 / 5.999–6.050 ms	5.534–5.593 / 5.560–5.642 ms	5.989–6.015 / 6.026–6.049 ms
two nullable inputs	10%	10.35–10.43 / 10.40–10.48 ms	10.45–10.56 / 10.49–10.60 ms	10.15–10.26 / 10.20–10.34 ms
two nullable inputs	25%	7.451–7.609 / 7.502–7.678 ms	9.119–9.220 / 9.156–9.285 ms	7.537–7.696 / 7.588–7.749 ms
two nullable inputs	90%	274.3–274.6 / 277.1–277.4 µs	3.210–3.234 / 3.232–3.253 ms	274.7–275.6 / 277.7–278.5 µs

• With one nullable input at 50% nulls, auto follows filter, but branch has 6–8% lower median latency.
• With two independent nullable inputs at 10% nulls (about 81% combined survivors), auto follows branch, but filter has 2.5–2.8% lower median latency.
• At two-input/25%, filter is about 1.21–1.22× faster than branch and auto correctly follows the filtering side.
• At two-input/90%, filtering is about 11.6× faster than branch and auto is essentially identical to filter.

This is evidence for an element/arity-aware threshold or small cost model. A single threshold against the conjoined survivor fraction cannot capture both the cost of decoding one per-row element and the cost of decoding two.

Native LLVM IR and AVX-512 assembly audit

The current sink-only checked-add executor passes the intended codegen audit.

• The hot IR contains <8 x i64> output/error operations and llvm.vector.reduce.or.v8i64 reductions.
• The two-column main loop is four-way unrolled over AVX-512 zmm registers: four vpaddq operations produce 32 i64 results per iteration.
• Overflow/error bits accumulate with vector xor/ternary-OR operations and are horizontally reduced only after the loop.
• The only hot-loop branch is loop control; there is no per-row Result discriminant or error branch.

The current l2_norm audit also resolves an important scope issue in the old comment: it emits scalar vmulss/vsqrtss for strict ordered reduction and does not reproduce the old “four vmulps, 64 f32 coordinates per iteration” claim. That vector loop belonged to l2_denorm, which is now classified as the Normalized encoding. The old l2_denorm assembly remains valid evidence for that encoding implementation, but it must not be carried forward as scalar-function parity evidence.

The candidate byte_length native assembly comparison was not repeated here. The measured BytesLen versus byte-slice control establishes the input-element cost difference, not production codegen parity with develop's vectorized implementation.

Correctness and verification

The geo bbox widening remains an uncommitted local patch on top of d293d3cdd59e; it changes only vortex-geo/src/scalar_fn/contains.rs and intersects.rs.

Checks completed:

• focused prepared/expanded and NaN geo tests: 43 passed;
• cargo nextest run -p vortex-geo: 230 passed;
• cargo clippy -p vortex-geo --all-targets --all-features;
• cargo +nightly fmt --all;
• git diff --check in the candidate and benchmark-only develop worktrees;
• native release LLVM IR and assembly emission for row_fn_executor and l2_norm.

The develop worktree modifications are benchmark-only: portable binary_predicates and cosine_similarity bench registration/source plus the resulting lockfile update.

[connortsui20]

@mhk197 gave me the idea that this could potentially work for gpu execution too 👀