Better code org and documentation.

Author: neoblizz

README.md

@@ -12,7 +12,7 @@ Single-Source Shortest Path (SSSP) implementation in modern C++ for 2022 IPDPS w
 - `tbb` library for execution policies (automatically fetched using cmake).
 
 ## Quick Start Guide
-Before building this project, make sure your system/compiler supports **C++20** and **cmake** (see `CMakeLists.txt` for the version).
+Before building this project, make sure your system/compiler supports **C++20** and **cmake**.
 
 ```bash
 git clone https://github.com/owensgroup/sssp.git

include/datastructs.hxx

@@ -0,0 +1,124 @@
+/**
+ * @file datastructs.hxx
+ * @author Muhammad Osama (mosama@ucdavis.edu)
+ * @brief
+ * @version 0.1
+ *
+ * @copyright Copyright (c) 2022
+ *
+ */
+
+#pragma once
+
+#include <vector>
+#include <algorithm>
+#include <execution>
+#include <mutex>
+#include <utility>
+#include <ranges>
+
+namespace essentials {
+
+/**
+ * @brief Example frontier data structure.
+ *
+ * @tparam type_t
+ */
+template <typename type_t>
+struct frontier_t {
+  // Underlying representation of frontier.
+  std::vector<type_t> active_vertices;
+
+  // Get the number of active vertices.
+  int size() { return active_vertices.size(); }
+  // Get the active vertex at a given index.
+  type_t get_active_vertex(type_t const& i) { return active_vertices[i]; }
+  // Add a vertex to the frontier.
+  void add_vertex(type_t const& v) { active_vertices.push_back(v); }
+};
+
+/**
+ * @brief Compressed-Sparse Row (CSR) matrix.
+ *
+ * @tparam index_t Type of index.
+ * @tparam offset_t Type of offset.
+ * @tparam value_t Type of value.
+ */
+template <typename index_t, typename offset_t, typename value_t>
+struct csr_t {
+  index_t rows;
+  index_t cols;
+  offset_t nnzs;
+  std::vector<offset_t>& row_offsets;
+  std::vector<index_t>& column_indices;
+  std::vector<value_t>& values;
+
+  /**
+   * @brief Construct a new csr_t object.
+   *
+   * @param _rows Number of rows.
+   * @param _cols Number of columns.
+   * @param _nnzs Number of non-zeros.
+   * @param _row_offsets Row offsets.
+   * @param _column_indices Column indices.
+   * @param _values Values of non-zeros.
+   */
+  csr_t(index_t& _rows,
+        index_t& _cols,
+        offset_t& _nnzs,
+        std::vector<offset_t>& _row_offsets,
+        std::vector<index_t>& _column_indices,
+        std::vector<value_t>& _values)
+      : rows(_rows),
+        cols(_cols),
+        nnzs(_nnzs),
+        row_offsets(_row_offsets),
+        column_indices(_column_indices),
+        values(_values) {}
+};
+
+/**
+ * @brief Graph data structure based on CSR format.
+ *
+ * @tparam vertex_t Type of vertex.
+ * @tparam edge_t Type of edge.
+ * @tparam weight_t Type of weight.
+ */
+template <typename vertex_t, typename edge_t, typename weight_t>
+struct graph_t : public csr_t<vertex_t, edge_t, weight_t> {
+  using csr_type = csr_t<vertex_t, edge_t, weight_t>;
+  using vertex_type = vertex_t;
+  using edge_type = edge_t;
+  using weight_type = weight_t;
+
+  /**
+   * @brief Construct a new graph_t object.
+   *
+   * @param rows Number of rows.
+   * @param cols Number of columns.
+   * @param nnzs Number of non-zeros.
+   * @param row_offsets Row offsets.
+   * @param column_indices Column indices.
+   * @param values Values of non-zeros.
+   */
+  graph_t(vertex_t& rows,
+          vertex_t& cols,
+          edge_t& nnzs,
+          std::vector<edge_t>& row_offsets,
+          std::vector<vertex_t>& column_indices,
+          std::vector<weight_t>& values)
+      : csr_type(rows, cols, nnzs, row_offsets, column_indices, values) {}
+
+  weight_t get_edge_weight(edge_t const& e) { return csr_type::values[e]; }
+  vertex_t get_num_vertices() { return csr_type::rows; }
+  vertex_t get_dest_vertex(edge_t const& e) {
+    return csr_type::column_indices[e];
+  }
+  auto get_edges(const vertex_t& v) {
+    return std::ranges::iota_view{csr_type::row_offsets[v],
+                                  csr_type::row_offsets[v + 1]};
+  }
+  auto get_vertices() { return std::ranges::iota_view{0, get_num_vertices()}; }
+};
+
+}  // namespace essentials

include/load.hxx

@@ -1,7 +1,7 @@
 /**
  * @file load.hxx
  * @author Muhammad Osama (mosama@ucdavis.edu)
- * @brief
+ * @brief Matrix Market file loader.
  * @version 0.1
  *
  * @copyright Copyright (c) 2022
@@ -14,7 +14,7 @@
 #include <assert.h>
 #include <externals/mmio.hxx>
 
-namespace sssp {
+namespace essentials {
 
 /**
  * @brief Matrix Market format supports two kind of formats, a sparse coordinate
@@ -71,10 +71,12 @@ struct matrix_market_t {
 
   int num_rows, num_columns, num_nonzeros;
 
+  // COO vectors
   std::vector<vertex_t> row_indices;
   std::vector<vertex_t> column_indices;
   std::vector<weight_t> values;
 
+  // CSR vectors
   std::vector<edge_t> Ap;
   std::vector<vertex_t> Aj;
   std::vector<weight_t> Ax;
@@ -86,15 +88,12 @@ struct matrix_market_t {
   matrix_market_storage_scheme_t scheme;  // Storage scheme
 
   /**
-   * @brief Loads the given .mtx file into a coordinate format, and returns the
-   * coordinate array. This needs to be further extended to support dense
-   * arrays, those are the only two formats mtx are written in.
+   * @brief Loads the given .mtx file into a coordinate (COO) and
+   * compressed-sparse row (CSR) formats.
    *
    * @param _filename input file name (.mtx)
    */
-  matrix_market_t(std::string _filename) {
-    filename = _filename;
-
+  matrix_market_t(std::string _filename) : filename(_filename) {
     file_t file;
 
     // Load MTX information
@@ -238,4 +237,4 @@ struct matrix_market_t {
   }
 };
 
-}  // namespace sssp
+}  // namespace essentials

include/operators.hxx

@@ -0,0 +1,65 @@
+/**
+ * @file operators.hxx
+ * @author Muhammad Osama (mosama@ucdavis.edu)
+ * @brief Operators for graph analytics.
+ * @version 0.1
+ *
+ * @copyright Copyright (c) 2022
+ *
+ */
+
+#pragma once
+
+#include <vector>
+#include <algorithm>
+#include <execution>
+#include <mutex>
+#include <utility>
+#include <ranges>
+
+/**
+ * @brief Neighbors expand operator for graph traversal.
+ *
+ * @par Overview
+ * Takes an input frontier and returns the neighbors of the active vertices
+ * within the frontier as a new frontier. During the traversal to neighbors,
+ * also applies an expand condition on the tuple of source vertex, neighbor
+ * vertex, edge and edge weight.
+ *
+ * @tparam my_graph_t Graph type.
+ * @tparam my_frontier_t Frontier type.
+ * @tparam expand_cond_t Condition type.
+ * @param g Graph.
+ * @param f Frontier.
+ * @param condition User-defined condition.
+ * @return my_frontier_t New frontier.
+ */
+template <typename my_graph_t, typename my_frontier_t, typename expand_cond_t>
+my_frontier_t neighbors_expand(my_graph_t& g,
+                               my_frontier_t& f,
+                               expand_cond_t condition) {
+  std::mutex m;
+  my_frontier_t output;
+  auto expand = [&](auto const& v) {
+    // For all edges of vertex v.
+    for (auto e : g.get_edges(v)) {
+      auto n = g.get_dest_vertex(e);
+      auto w = g.get_edge_weight(e);
+      // If expand condition is
+      // true, add the neighbor into
+      // the output frontier.
+      if (condition(v, n, e, w)) {
+        std::lock_guard<std::mutex> guard(m);
+        output.add_vertex(n);
+      }
+    }
+  };
+
+  // For all active vertices in the
+  // frontier, process in parallel.
+  std::for_each(std::execution::par, f.active_vertices.begin(),
+                f.active_vertices.end(), expand);
+
+  // Return the new output frontier.
+  return output;
+}