Add optimizers for RPQ-matrix algortihm

.gitignore

@@ -1,3 +1,5 @@
+.vscode
+Cargo.lock
 # Generated by Cargo
 # will have compiled files and executables
 debug

README.md

@@ -97,6 +97,12 @@ Subcommands:
 | `-q`, `--queries <FILE>` | Queries file (see format below). |
 | `-a`, `--algo <nfarpq\|rpqmatrix>` | Algorithm(s). Repeat to run several. |
 | `-b`, `--base-iri [<IRI>]` | Optional `BASE <iri>` to prepend to each query. Bare `--base-iri` uses `http://example.org/`. |
+| `-p`, `--rpqmatrix-optimizer <NAME>` | RPQMatrix optimizer: `none`, `cardinality`, `metaac`, `hybrid`, `rpq-static`, `rpq-sampling`, or `row-sampling` (MatrixMarket only). |
+
+Sampling parameters can be adjusted with `RPQ_SAMPLE_SIZE` and
+`RPQ_SAMPLE_SEED`, or with `ROW_SAMPLE_SIZE`, `ROW_SAMPLE_SEED`, and
+`ROW_SAMPLE_MAX_STAR_ITERS`. Defaults are respectively `10`, `0`, `64`, `0`,
+and `64`.
 
 `query` adds `-o, --output <FILE>` to write JSON.
 

pathrex-sys/build.rs

@@ -52,6 +52,7 @@ fn main() {
 
     let lagraph_src = manifest_dir.join(LAGRAPH_REL_PATH);
     assert_lagraph_submodule_present(&lagraph_src);
+    watch_lagraph_sources(&lagraph_src);
 
     let graphblas_src = fetch_graphblas(&out_dir);
     let graphblas_install = build_graphblas_static(&graphblas_src);
@@ -77,6 +78,44 @@ fn assert_lagraph_submodule_present(lagraph_src: &Path) {
     }
 }
 
+fn watch_lagraph_sources(lagraph_src: &Path) {
+    println!(
+        "cargo:rerun-if-changed={}",
+        lagraph_src.join("CMakeLists.txt").display()
+    );
+
+    for rel_dir in ["Config", "cmake_modules", "include", "src", "experimental"] {
+        let dir = lagraph_src.join(rel_dir);
+        if dir.exists() {
+            watch_files_with_extensions(&dir, &["c", "h", "cmake", "in", "txt"]);
+        }
+    }
+}
+
+fn watch_files_with_extensions(dir: &Path, extensions: &[&str]) {
+    let entries = std::fs::read_dir(dir)
+        .unwrap_or_else(|e| panic!("failed to read directory {}: {e}", dir.display()));
+
+    for entry in entries {
+        let path = entry
+            .unwrap_or_else(|e| panic!("failed to read entry in {}: {e}", dir.display()))
+            .path();
+
+        if path.is_dir() {
+            watch_files_with_extensions(&path, extensions);
+            continue;
+        }
+
+        let Some(ext) = path.extension().and_then(|ext| ext.to_str()) else {
+            continue;
+        };
+
+        if extensions.contains(&ext) {
+            println!("cargo:rerun-if-changed={}", path.display());
+        }
+    }
+}
+
 /// Clone SuiteSparse:GraphBLAS at [`GRAPHBLAS_TAG`] into
 /// `$OUT_DIR/graphblas-src/`. Returns the path to the source tree.
 ///
@@ -292,9 +331,12 @@ fn regenerate_bindings(graphblas_install: &Path) {
         .allowlist_item("GrB_Info")
         .allowlist_function("GrB_Matrix_new")
         .allowlist_function("GrB_Matrix_nvals")
+        .allowlist_function("GrB_Matrix_nrows")
+        .allowlist_function("GrB_Matrix_ncols")
         .allowlist_function("GrB_Matrix_dup")
         .allowlist_function("GrB_Matrix_free")
         .allowlist_function("GrB_Matrix_extractElement_BOOL")
+        .allowlist_function("GrB_Matrix_extractTuples_BOOL")
         .allowlist_function("GrB_Matrix_build_BOOL")
         .allowlist_function("GrB_Vector_new")
         .allowlist_function("GrB_Vector_free")
@@ -304,6 +346,7 @@ fn regenerate_bindings(graphblas_install: &Path) {
         .allowlist_function("GrB_vxm")
         .allowlist_item("LAGRAPH_MSG_LEN")
         .allowlist_item("RPQMatrixOp")
+        .allowlist_item("RPQMatrixStorage")
         .allowlist_type("RPQMatrixPlan")
         .allowlist_type("LAGraph_Graph")
         .allowlist_type("LAGraph_Kind")
@@ -317,7 +360,13 @@ fn regenerate_bindings(graphblas_install: &Path) {
         .allowlist_function("LAGraph_Cached_AT")
         .allowlist_function("LAGraph_MMRead")
         .allowlist_function("LAGraph_RPQMatrix")
+        .allowlist_function("LAGraph_RPQMatrix_SetGlobalStorageOrientation")
+        .allowlist_function("LAGraph_RPQMatrix_SetStorageOrientation")
+        .allowlist_function("LAGraph_RPQMatrix_DupWithStorageOrientation")
         .allowlist_function("LAGraph_RPQMatrix_reduce")
+        .allowlist_function("LAGraph_RPQMatrix_sample_.*")
+        .allowlist_function("LAGraph_RPQMatrix_reduce_count_vector")
+        .allowlist_function("LAGraph_RPQMatrix_count_vector_.*")
         .allowlist_function("LAGraph_DestroyRpqMatrixPlan")
         .allowlist_function("LAGraph_RPQMatrix_label")
         .allowlist_function("LAGraph_RPQMatrix_Free")

pathrex-sys/src/lagraph_sys_generated.rs

@@ -158,6 +158,12 @@ unsafe extern "C" {
 unsafe extern "C" {
     pub fn GrB_Matrix_dup(C: *mut GrB_Matrix, A: GrB_Matrix) -> GrB_Info;
 }
+unsafe extern "C" {
+    pub fn GrB_Matrix_nrows(nrows: *mut GrB_Index, A: GrB_Matrix) -> GrB_Info;
+}
+unsafe extern "C" {
+    pub fn GrB_Matrix_ncols(ncols: *mut GrB_Index, A: GrB_Matrix) -> GrB_Info;
+}
 unsafe extern "C" {
     pub fn GrB_Matrix_nvals(nvals: *mut GrB_Index, A: GrB_Matrix) -> GrB_Info;
 }
@@ -179,6 +185,15 @@ unsafe extern "C" {
         j: GrB_Index,
     ) -> GrB_Info;
 }
+unsafe extern "C" {
+    pub fn GrB_Matrix_extractTuples_BOOL(
+        I_: *mut GrB_Index,
+        J: *mut GrB_Index,
+        X: *mut bool,
+        nvals: *mut GrB_Index,
+        A: GrB_Matrix,
+    ) -> GrB_Info;
+}
 unsafe extern "C" {
     pub fn GrB_vxm(
         w: GrB_Vector,
@@ -320,6 +335,28 @@ pub struct RPQMatrixPlan {
     pub mat: GrB_Matrix,
     pub res_mat: GrB_Matrix,
 }
+#[repr(u32)]
+#[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
+pub enum RPQMatrixStorage {
+    RPQ_MATRIX_STORAGE_CSC = 1,
+    RPQ_MATRIX_STORAGE_CSR = 2,
+}
+unsafe extern "C" {
+    pub fn LAGraph_RPQMatrix_SetGlobalStorageOrientation(storage: RPQMatrixStorage) -> GrB_Info;
+}
+unsafe extern "C" {
+    pub fn LAGraph_RPQMatrix_SetStorageOrientation(
+        mat: GrB_Matrix,
+        storage: RPQMatrixStorage,
+    ) -> GrB_Info;
+}
+unsafe extern "C" {
+    pub fn LAGraph_RPQMatrix_DupWithStorageOrientation(
+        dst: *mut GrB_Matrix,
+        src: GrB_Matrix,
+        storage: RPQMatrixStorage,
+    ) -> GrB_Info;
+}
 unsafe extern "C" {
     pub fn LAGraph_RPQMatrix(
         nnz: *mut GrB_Index,
@@ -341,10 +378,86 @@ unsafe extern "C" {
 unsafe extern "C" {
     pub fn LAGraph_RPQMatrix_Free(mat: *mut GrB_Matrix) -> GrB_Info;
 }
+unsafe extern "C" {
+    pub fn LAGraph_RPQMatrix_sample_seed(
+        seed: *mut GrB_Matrix,
+        sources: *const GrB_Index,
+        nsources: GrB_Index,
+        n: GrB_Index,
+    ) -> GrB_Info;
+}
+unsafe extern "C" {
+    pub fn LAGraph_RPQMatrix_sample_apply(
+        result: *mut GrB_Matrix,
+        seed: GrB_Matrix,
+        relation: GrB_Matrix,
+        transpose_relation: bool,
+    ) -> GrB_Info;
+}
+unsafe extern "C" {
+    pub fn LAGraph_RPQMatrix_sample_union(
+        result: *mut GrB_Matrix,
+        lhs: GrB_Matrix,
+        rhs: GrB_Matrix,
+    ) -> GrB_Info;
+}
+unsafe extern "C" {
+    pub fn LAGraph_RPQMatrix_sample_dup(result: *mut GrB_Matrix, source: GrB_Matrix) -> GrB_Info;
+}
+unsafe extern "C" {
+    pub fn LAGraph_RPQMatrix_sample_stats(
+        nvals: *mut GrB_Index,
+        active_rows: *mut GrB_Index,
+        active_cols: *mut GrB_Index,
+        sample: GrB_Matrix,
+    ) -> GrB_Info;
+}
 unsafe extern "C" {
     pub fn LAGraph_RPQMatrix_reduce(
         res: *mut GrB_Index,
         mat: GrB_Matrix,
         reduce_type: u8,
     ) -> GrB_Info;
 }
+unsafe extern "C" {
+    pub fn LAGraph_RPQMatrix_reduce_count_vector(
+        res: *mut GrB_Vector,
+        mat: GrB_Matrix,
+        reduce_type: u8,
+    ) -> GrB_Info;
+}
+unsafe extern "C" {
+    pub fn LAGraph_RPQMatrix_count_vector_dot(
+        res: *mut f64,
+        lhs: GrB_Vector,
+        rhs: GrB_Vector,
+    ) -> GrB_Info;
+}
+unsafe extern "C" {
+    pub fn LAGraph_RPQMatrix_count_vector_sum(res: *mut f64, vector: GrB_Vector) -> GrB_Info;
+}
+unsafe extern "C" {
+    pub fn LAGraph_RPQMatrix_count_vector_nvals(
+        res: *mut GrB_Index,
+        vector: GrB_Vector,
+    ) -> GrB_Info;
+}
+unsafe extern "C" {
+    pub fn LAGraph_RPQMatrix_count_vector_scale(
+        res: *mut GrB_Vector,
+        vector: GrB_Vector,
+        scale: f64,
+        cap: f64,
+    ) -> GrB_Info;
+}
+unsafe extern "C" {
+    pub fn LAGraph_RPQMatrix_count_vector_add(
+        res: *mut GrB_Vector,
+        lhs: GrB_Vector,
+        rhs: GrB_Vector,
+        cap: f64,
+    ) -> GrB_Info;
+}
+unsafe extern "C" {
+    pub fn LAGraph_RPQMatrix_count_vector_free(vector: *mut GrB_Vector) -> GrB_Info;
+}

pathrex/Cargo.toml

@@ -38,13 +38,15 @@ serde_json = { version = "1", optional = true }
 chrono = { version = "0.4", features = ["serde"], optional = true }
 criterion = { version = "0.5", optional = true }
 tempfile = { version = "3", optional = true }
+rand = "0.10.2"
 
 [features]
 default = []
 bench = ["clap", "serde", "serde_json", "chrono", "criterion", "tempfile"]
 
 [dev-dependencies]
 tempfile = "3"
+expect-test = "1.5.1"
 
 [[bin]]
 name = "pathrex"