Skip to main content

vortex_array/scalar_fn/fns/zip/
kernel.rs

1// SPDX-License-Identifier: Apache-2.0
2// SPDX-FileCopyrightText: Copyright the Vortex contributors
3
4use vortex_error::VortexExpect;
5use vortex_error::VortexResult;
6
7use crate::ArrayRef;
8use crate::ExecutionCtx;
9use crate::array::ArrayView;
10use crate::array::VTable;
11use crate::arrays::ScalarFn;
12use crate::arrays::scalar_fn::ExactScalarFn;
13use crate::arrays::scalar_fn::ScalarFnArrayExt;
14use crate::arrays::scalar_fn::ScalarFnArrayView;
15use crate::builtins::ArrayBuiltins;
16use crate::kernel::ExecuteParentKernel;
17use crate::optimizer::rules::ArrayParentReduceRule;
18use crate::scalar_fn::fns::zip::Zip as ZipExpr;
19
20/// Zip two arrays using a mask without reading buffers.
21///
22/// This trait is for zip implementations that can operate purely on array metadata
23/// and structure without needing to read or execute on the underlying buffers.
24/// Implementations should return `None` if the operation requires buffer access.
25///
26/// Dispatch supports either value branch. The adaptor normalizes the inputs so
27/// `array` is selected where `mask` is true, and `if_false` everywhere else.
28pub trait ZipReduce: VTable {
29    fn zip(
30        array: ArrayView<'_, Self>,
31        if_false: &ArrayRef,
32        mask: &ArrayRef,
33    ) -> VortexResult<Option<ArrayRef>>;
34}
35
36/// Zip two arrays using a mask, potentially reading buffers.
37///
38/// Unlike [`ZipReduce`], this trait is for zip implementations that may need
39/// to read and execute on the underlying buffers to produce the result.
40///
41/// Dispatch supports either value branch. The adaptor normalizes the inputs so
42/// `array` is selected where `mask` is true, and `if_false` everywhere else.
43pub trait ZipKernel: VTable {
44    fn zip(
45        array: ArrayView<'_, Self>,
46        if_false: &ArrayRef,
47        mask: &ArrayRef,
48        ctx: &mut ExecutionCtx,
49    ) -> VortexResult<Option<ArrayRef>>;
50}
51
52/// Adaptor that wraps a [`ZipReduce`] impl as an [`ArrayParentReduceRule`].
53#[derive(Default, Debug)]
54pub struct ZipReduceAdaptor<V>(pub V);
55
56impl<V> ArrayParentReduceRule<V> for ZipReduceAdaptor<V>
57where
58    V: ZipReduce,
59{
60    type Parent = ExactScalarFn<ZipExpr>;
61
62    fn reduce_parent(
63        &self,
64        array: ArrayView<'_, V>,
65        parent: ScalarFnArrayView<'_, ZipExpr>,
66        child_idx: usize,
67    ) -> VortexResult<Option<ArrayRef>> {
68        let Some((if_false, mask)) = normalized_zip_inputs(parent, child_idx)? else {
69            return Ok(None);
70        };
71        <V as ZipReduce>::zip(array, &if_false, &mask)
72    }
73}
74
75/// Adaptor that wraps a [`ZipKernel`] impl as an [`ExecuteParentKernel`].
76#[derive(Default, Debug)]
77pub struct ZipExecuteAdaptor<V>(pub V);
78
79impl<V> ExecuteParentKernel<V> for ZipExecuteAdaptor<V>
80where
81    V: ZipKernel,
82{
83    type Parent = ExactScalarFn<ZipExpr>;
84
85    fn execute_parent(
86        &self,
87        array: ArrayView<'_, V>,
88        parent: ScalarFnArrayView<'_, ZipExpr>,
89        child_idx: usize,
90        ctx: &mut ExecutionCtx,
91    ) -> VortexResult<Option<ArrayRef>> {
92        let Some((if_false, mask)) = normalized_zip_inputs(parent, child_idx)? else {
93            return Ok(None);
94        };
95        <V as ZipKernel>::zip(array, &if_false, &mask, ctx)
96    }
97}
98
99fn normalized_zip_inputs(
100    parent: ScalarFnArrayView<'_, ZipExpr>,
101    child_idx: usize,
102) -> VortexResult<Option<(ArrayRef, ArrayRef)>> {
103    let scalar_fn_array = parent
104        .as_opt::<ScalarFn>()
105        .vortex_expect("ExactScalarFn matcher confirmed ScalarFnArray");
106    let mask = scalar_fn_array.get_child(2);
107    match child_idx {
108        0 => Ok(Some((scalar_fn_array.get_child(1).clone(), mask.clone()))),
109        1 => {
110            // Null mask rows select the original if_false branch, so they must
111            // become true when that branch is passed to the kernel as if_true.
112            let mask = mask.fill_null(false)?.not()?;
113            Ok(Some((scalar_fn_array.get_child(0).clone(), mask)))
114        }
115        _ => Ok(None),
116    }
117}
118
119#[cfg(test)]
120mod tests {
121    use rstest::rstest;
122    use vortex_session::VortexSession;
123
124    use super::*;
125    use crate::IntoArray;
126    use crate::VortexSessionExecute;
127    use crate::arrays::Bool;
128    use crate::arrays::BoolArray;
129    use crate::assert_arrays_eq;
130
131    // A metadata-only reduction exposes the inputs passed by the adaptor.
132    impl ZipReduce for Bool {
133        fn zip(
134            array: ArrayView<'_, Self>,
135            if_false: &ArrayRef,
136            mask: &ArrayRef,
137        ) -> VortexResult<Option<ArrayRef>> {
138            mask.zip(array.array().clone(), if_false.clone()).map(Some)
139        }
140    }
141
142    #[rstest]
143    #[case::if_true(0)]
144    #[case::if_false(1)]
145    #[case::mask(2)]
146    fn adaptors_preserve_branch_and_null_mask_semantics(
147        #[case] child_idx: usize,
148    ) -> VortexResult<()> {
149        let mut ctx = VortexSession::empty().create_execution_ctx();
150        let children = [
151            BoolArray::from_iter([Some(true), Some(false), None, Some(true)]).into_array(),
152            BoolArray::from_iter([Some(false), Some(true), Some(true), None]).into_array(),
153            BoolArray::from_iter([Some(true), Some(false), None, None]).into_array(),
154        ];
155        let parent = ZipExpr::try_new(
156            children[0].clone(),
157            children[1].clone(),
158            children[2].clone(),
159        )?
160        .into_array();
161        let child = children[child_idx].as_opt::<Bool>().unwrap();
162        let reduced = ZipReduceAdaptor(Bool).reduce_parent(
163            child,
164            parent.as_opt::<ExactScalarFn<ZipExpr>>().unwrap(),
165            child_idx,
166        )?;
167        let executed = ZipExecuteAdaptor(Bool).execute_parent(
168            child,
169            parent.as_opt::<ExactScalarFn<ZipExpr>>().unwrap(),
170            child_idx,
171            &mut ctx,
172        )?;
173
174        for result in [reduced, executed] {
175            if child_idx == 2 {
176                assert!(result.is_none(), "the mask is not a value branch");
177            } else {
178                let result = result.expect("both value branches dispatch to their kernel");
179                let expected = BoolArray::from_iter([Some(true), Some(true), Some(true), None]);
180                assert_arrays_eq!(result, expected, &mut ctx);
181            }
182        }
183        Ok(())
184    }
185}