feat: add graph representation, csv and n-tripples readers, one-hop reachability example algo

Author: VanyaGlazunov

Cargo.toml

@@ -4,3 +4,8 @@ version = "0.1.0"
 edition = "2024"
 
 [dependencies]
+csv = "1.4.0"
+oxrdf = "0.3.3"
+oxttl = "0.2.3"
+thiserror = "1.0"
+suitesparse_graphblas_sys = "0.4.3"

src/algo/mod.rs

@@ -0,0 +1,5 @@
+//! Graph algorithms for pathrex.
+
+pub mod one_hop;
+
+pub use one_hop::one_hop_reachability;

src/algo/one_hop.rs

@@ -0,0 +1,167 @@
+//! One-hop reachability algorithm.
+
+use suitesparse_graphblas_sys::{
+    GrB_Index, GrB_LOR_LAND_SEMIRING_BOOL, GrB_Vector_extractTuples_BOOL, GrB_Vector_nvals,
+    GrB_Vector_setElement_BOOL, GrB_vxm,
+};
+
+use crate::graph::{GraphDecomposition, GraphError, GraphblasVector, grb_ok};
+
+/// Returns all nodes reachable from `source` via one hop.
+/// # Example
+///
+/// ```
+/// use pathrex::graph::{InMemoryBuilder, GraphBuilder, Edge};
+/// use pathrex::algo::one_hop_reachability;
+///
+/// let mut builder = InMemoryBuilder::new();
+/// builder.push_edge(Edge { source: "A".into(), target: "B".into(), label: "knows".into() }).unwrap();
+/// builder.push_edge(Edge { source: "A".into(), target: "C".into(), label: "knows".into() }).unwrap();
+/// let graph = builder.build().unwrap();
+///
+/// let mut neighbours = one_hop_reachability(&graph, "A", "knows").unwrap();
+/// neighbours.sort();
+/// assert_eq!(neighbours, vec!["B", "C"]);
+/// ```
+pub fn one_hop_reachability<G>(
+    graph: &G,
+    source: &str,
+    label: &str,
+) -> Result<Vec<String>, GraphError>
+where
+    G: GraphDecomposition<Error = GraphError>,
+{
+    let src_idx = match graph.get_node_id(source) {
+        Some(id) => id as GrB_Index,
+        None => return Ok(Vec::new()),
+    };
+
+    let matrix = graph.get_matrix(label, false)?;
+    let n = graph.num_nodes() as GrB_Index;
+
+    unsafe {
+        let src_vec = GraphblasVector::new_bool(n)?;
+        grb_ok(GrB_Vector_setElement_BOOL(src_vec.inner, true, src_idx))?;
+
+        let result_vec = GraphblasVector::new_bool(n)?;
+        grb_ok(GrB_vxm(
+            result_vec.inner,
+            std::ptr::null_mut(),
+            std::ptr::null_mut(),
+            GrB_LOR_LAND_SEMIRING_BOOL,
+            src_vec.inner,
+            matrix.inner,
+            std::ptr::null_mut(),
+        ))?;
+
+        let mut nvals: GrB_Index = 0;
+        grb_ok(GrB_Vector_nvals(&mut nvals, result_vec.inner))?;
+
+        if nvals == 0 {
+            return Ok(Vec::new());
+        }
+
+        let mut indices: Vec<GrB_Index> = vec![0; nvals as usize];
+        let mut values: Vec<bool> = vec![false; nvals as usize];
+        let mut nvals_out = nvals;
+        grb_ok(GrB_Vector_extractTuples_BOOL(
+            indices.as_mut_ptr(),
+            values.as_mut_ptr(),
+            &mut nvals_out,
+            result_vec.inner,
+        ))?;
+
+        Ok(indices[..nvals_out as usize]
+            .iter()
+            .filter_map(|&idx| graph.get_node_name(idx as usize))
+            .collect())
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::graph::{Edge, GraphBuilder, GraphError, InMemoryBuilder, InMemoryGraph};
+
+    fn make_graph(edges: &[(&str, &str, &str)]) -> InMemoryGraph {
+        let mut builder = InMemoryBuilder::new();
+        for &(src, tgt, lbl) in edges {
+            builder
+                .push_edge(Edge {
+                    source: src.to_owned(),
+                    target: tgt.to_owned(),
+                    label: lbl.to_owned(),
+                })
+                .unwrap();
+        }
+        builder.build().unwrap()
+    }
+
+    #[test]
+    fn test_single_neighbour() {
+        let graph = make_graph(&[("A", "B", "knows")]);
+        assert_eq!(
+            one_hop_reachability(&graph, "A", "knows").unwrap(),
+            vec!["B"]
+        );
+    }
+
+    #[test]
+    fn test_multiple_neighbours() {
+        let graph = make_graph(&[
+            ("A", "B", "knows"),
+            ("A", "C", "knows"),
+            ("A", "D", "knows"),
+        ]);
+        let mut result = one_hop_reachability(&graph, "A", "knows").unwrap();
+        result.sort();
+        assert_eq!(result, vec!["B", "C", "D"]);
+    }
+
+    #[test]
+    fn test_no_outgoing_edges() {
+        let graph = make_graph(&[("A", "B", "knows")]);
+        assert!(
+            one_hop_reachability(&graph, "B", "knows")
+                .unwrap()
+                .is_empty()
+        );
+    }
+
+    #[test]
+    fn test_unknown_source_returns_empty() {
+        let graph = make_graph(&[("A", "B", "knows")]);
+        assert!(
+            one_hop_reachability(&graph, "Z", "knows")
+                .unwrap()
+                .is_empty()
+        );
+    }
+
+    #[test]
+    fn test_unknown_label_returns_error() {
+        let graph = make_graph(&[("A", "B", "knows")]);
+        assert!(matches!(
+            one_hop_reachability(&graph, "A", "likes"),
+            Err(GraphError::LabelNotFound(_))
+        ));
+    }
+
+    #[test]
+    fn test_self_loop() {
+        let graph = make_graph(&[("A", "A", "self")]);
+        assert_eq!(
+            one_hop_reachability(&graph, "A", "self").unwrap(),
+            vec!["A"]
+        );
+    }
+
+    #[test]
+    fn test_label_isolation() {
+        let graph = make_graph(&[("A", "B", "knows"), ("A", "C", "likes")]);
+        assert_eq!(
+            one_hop_reachability(&graph, "A", "knows").unwrap(),
+            vec!["B"]
+        );
+    }
+}