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 and implementation supporting bool(T, T) signatures.
• Extended OpenCL program builder to handle OpSelectBinary code generation.

New primitives: v_assign_bslct_masked / m_assign_bslct_masked

• Implemented vector and matrix masked assignment operations on both CPU and OpenCL backends.
• 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[row, col], value) only if op_select_bin(mask[row], mask[col]) is true.

Bug fixes

• Fixed TScalar<Pair>: added missing override keywords, removed invalid const specifier, and corrected as_pair() to return m_value properly (restoring host<->device scalar readback).
• Fixed missing T_PAIR type support.
• Removed legacy needs_pair_override hack that caused macro redefinition conflicts.
• Added CLProgram initialization on cache miss.
• Fixed uninitialized n_sort in MtxLoader for weighted matrices (previously caused out-of-bounds access).
• Fixed OpenCL source generation for Pair operations (IDENTITY_PAIR, MUL_PAIR, MIN_PAIR, SECOND_PAIR, ALWAYS_PAIR).
• m_extract_row: fixed row vector initialization and moved range bounds calculation directly into the OpenCL kernel.
• Added --run-cpu mode to mst utility
• Fixed MtxLoader::save to preserve matrix weights when writing to file.
• Fixed cycle formation in MST by adding directed component merge condition.

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.
• Performance measurements are attached in mst_benchmark.pdf.

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.
• All tests pass on both CPU and OpenCL backends.

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.