Implement OpSelectBinary and v/m_assign_bslct_masked operations

[b08lsoai]

Short description

This PR introduces a new core operation to the library: the binary selector (OpSelectBinary). Based on this, vector and matrix assignment operations (v_assign_bslct_masked, m_assign_bslct_masked) have been implemented on both the CPU and OpenCL backends.

Additionally, Boruvka’s MST algorithm has been optimized by offloading heavy host-side loops to the new OpenCL kernels, and critical bugs have been resolved.

List of changes

New operation type

• Added OpSelectBinary interface (op.hpp) and TOpSelectBinary<T> implementation (top.hpp) supporting bool(T, T) signatures.
• Extended CLProgramBuilder::add_op to handle OpSelectBinary code generation.

New primitives: v_assign_bslct_masked / m_assign_bslct_masked

• Implemented exec_v/m_assign_bslct_masked public API (exec.hpp) and integrated ScheduleTask_v/m_assign_bslct_masked.
• Added OpenCL kernels inside vector_assign_bslct.cl (for dense/sparse masks) and m_assign_bslct.cl (for CSR matrix).
• CPU reference implementations for both.
• Signatures:

  Status exec_v_assign_bslct_masked(
            ref_ptr<Vector>         r,
            ref_ptr<Vector>         mask,
            ref_ptr<Scalar>         mask_value,
            ref_ptr<Scalar>         value,
            ref_ptr<OpBinary>       op_assign,
            ref_ptr<OpSelectBinary> op_select_bin,
            ref_ptr<Descriptor>     desc     = ref_ptr<Descriptor>(),
            ref_ptr<ScheduleTask>*  task_hnd = nullptr);
  
  Status exec_m_assign_bslct_masked(
            ref_ptr<Matrix>         r,
            ref_ptr<Vector>         mask,
            ref_ptr<Scalar>         value,
            ref_ptr<OpBinary>       op_assign,
            ref_ptr<OpSelectBinary> op_select_bin,
            ref_ptr<Descriptor>     desc     = ref_ptr<Descriptor>(),
            ref_ptr<ScheduleTask>*  task_hnd = nullptr);

• Logic:
  • v_assign_bslct_masked: Updates vector elements r[i] = op_assign(r[i], value) only if op_select_bin(mask[i], mask_value) is true.
  • m_assign_bslct_masked: For each matrix element at position [row, col], it updates the element's value as r[row, col] = op_assign(r[ow, col], value) only if op_select_bin(mask[row], mask[col]) is true.

Bug fixes

• Added missing override keywords to get_pair/set_pair and removed an invalid const specifier in TScalar<Pair>. Fixed as_pair() to correctly return m_value instead of throwing an error, restoring host<->device scalar readback.
• Fixed missing T_PAIR type support.
• Removed the legacy needs_pair_override hack that hardcoded macro definitions for Pair, which previously caused macro redefinition conflicts and broke any new operations.
• Added CLProgram initialization on cache miss.
• Resolved a vector out-of-bounds crash.
• Corrected OpenCL source string formats for IDENTITY_PAIR, MUL_PAIR, MIN_PAIR, SECOND_PAIR, and ALWAYS_PAIR in op.cpp.
• m_extract_row: Added initialization of row and moved the calculation of range bounds directly into the OpenCL kernel code.

Boruvka's MST optimization

• Step 5 (row-wise minimum edge search) and step 6 (matrix filtering) previously did O(n) / O(n²) get_pair/set_pair host<->device round-trips per iteration. Replaced with exec_v_assign_bslct_masked + existing exec_v_reduce, and exec_m_assign_bslct_masked, respectively.

Type of changes

• bug-fix (change which fixes some issue)
• new-feature (change which proposes new feature or functionality)
• breaking-change (change which brakes compatibility of api or etc.)

Changes aspect

• unit-tests for C/C++ code added
• benchmark for C/C++ code added
• workflow tests to .github scripts added
• C bindings to C++ code added
• Python bindings to C code added
• documentation to C/C++ code added
• documentation to Python code added

Testing strategy

Unit Tests

• Added the files tests/test_v_assign_bslct.cpp and tests/test_m_assign_bslct.cpp: these test the corresponding operations for the Pair and Int types.

Background

This PR is based on two PRs:

• Add Pair type and Boruvka's MST algorithm #241: implement Pair type with semiring operations and the Boruvka algorithm for MST construction.
• implement m_extract_row and v_emult for OpenCL backend #238: implement extract_row on CSR matrices for the OpenCL backend.