Refactor APB benchmarks: rename to abstraction_penalty and modularize

- Rename bench/apb/ to bench/abstraction_penalty/
- Create apb_common.hpp with shared infrastructure:
  - bench() function template to eliminate timing boilerplate
  - Args struct for consistent CLI parsing
  - load_graph() function for graph loading
- Refactor all 8 APB benchmark files to use shared infrastructure
- Remove ~1100 lines of duplicated code
- Add descriptive file headers documenting what each benchmark measures
- Remove dead code (#if 0 blocks, unused variables)
- Fix containers.cpp VOV format support

Line count improvements:
- bfs.cpp: 419 -> 261 (38% reduction)
- dfs.cpp: 277 -> 170 (39% reduction)
- spmv.cpp: 444 -> 180 (59% reduction)
- plain.cpp: 596 -> 296 (50% reduction)
- dijkstra.cpp: 384 -> 187 (51% reduction)
- exec.cpp: 222 -> 121 (45% reduction)
- tbb.cpp: 359 -> 176 (51% reduction)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: lums658

agents/nwgraph_instructions.md

@@ -33,7 +33,7 @@ This document tracks cleanup tasks for the NWGraph codebase, including completed
 ### Apply Consistent Code Formatting
 - [x] Run clang-format on all 88 headers in `include/nwgraph/`
 - [x] Run clang-format on all test files in `test/`
-- [x] Run clang-format on all benchmark files in `bench/` (gapbs and apb)
+- [x] Run clang-format on all benchmark files in `bench/` (gapbs and abstraction_penalty)
 - [x] Run clang-format on all example files in `examples/`
 
 **Formatting standards (defined in `.clang-format`):**
@@ -169,9 +169,9 @@ Known TODO locations:
 - [x] Move all benchmarks under `bench/` with subdirectories:
   ```
   bench/
-  ├── gapbs/           # NWGraph GAP Benchmark Suite implementations
-  ├── apb/             # Abstraction Penalty Benchmarks
-  └── gapbs-reference/ # Original GAP Benchmark Suite (submodule)
+  ├── gapbs/               # NWGraph GAP Benchmark Suite implementations
+  ├── abstraction_penalty/ # Abstraction Penalty Benchmarks
+  └── gapbs-reference/     # Original GAP Benchmark Suite (submodule)
   ```
 - [x] Update `CMakeLists.txt` to reflect new directory structure
 - [x] Add original GAP Benchmark Suite as submodule for comparison
@@ -187,12 +187,26 @@ Known TODO locations:
   - `tc.cpp` converted to use `Times` class and `Log.hpp`
   - `js.cpp` disabled (commented out, needs conversion if re-enabled)
 
-### Abstraction Penalty Benchmarks (`bench/apb/`)
-- [x] Move current `apb/` contents to `bench/apb/`
+### Abstraction Penalty Benchmarks (`bench/abstraction_penalty/`)
+- [x] Move current `apb/` contents to `bench/abstraction_penalty/`
 - [x] Connect APB executables to `bench` target
-- [ ] Bring APB benchmarks to same quality level as GAP benchmarks (future)
+- [x] Create shared infrastructure (`apb_common.hpp`):
+  - `bench()` function template to eliminate timing boilerplate
+  - `Args` struct for consistent CLI parsing
+  - `load_graph()` function for graph loading
+- [x] Refactor all APB benchmarks to use shared infrastructure:
+  - `bfs.cpp` - BFS traversal benchmarks (261 lines, was 419)
+  - `dfs.cpp` - DFS traversal benchmarks (170 lines, was 277)
+  - `spmv.cpp` - SpMV benchmarks (180 lines, was 444)
+  - `plain.cpp` - Plain range benchmarks (296 lines, was 596)
+  - `dijkstra.cpp` - Dijkstra property access (188 lines, was 384)
+  - `exec.cpp` - Execution policy benchmarks (121 lines, was 222)
+  - `tbb.cpp` - TBB parallelization benchmarks (176 lines, was 359)
+  - `containers.cpp` - Container comparison benchmarks (235 lines)
+- [x] Remove dead code (`#if 0` blocks, unused variables)
+- [x] Add descriptive file headers documenting what each benchmark measures
 - [ ] Ensure consistent logging and output format (future)
-- [ ] Document what each APB measures (iteration overhead, container overhead, etc.) (future)
+- [ ] Add structured output matching gapbs pattern (future)
 
 ### Build Options
 - `NWGRAPH_BUILD_BENCH=ON` - Build NWGraph benchmarks (gapbs + apb)

bench/CMakeLists.txt

@@ -4,7 +4,7 @@
 # This directory contains benchmark implementations organized into subdirectories:
 #
 #   gapbs/           - NWGraph implementations of GAP Benchmark Suite
-#   apb/             - Abstraction Penalty Benchmarks
+#   abstraction_penalty/ - Abstraction Penalty Benchmarks
 #   gapbs-reference/ - Original GAP Benchmark Suite (submodule, optional)
 # =============================================================================
 
@@ -15,7 +15,7 @@ add_custom_target(bench)
 # Include subdirectories
 # -----------------------------------------------------------------------------
 add_subdirectory(gapbs)
-add_subdirectory(apb)
+add_subdirectory(abstraction_penalty)
 
 # -----------------------------------------------------------------------------
 # Original GAP Benchmark Suite (optional, for comparison)

bench/apb/CMakeLists.txt bench/abstraction_penalty/CMakeLists.txtbench/apb/CMakeLists.txt renamed to bench/abstraction_penalty/CMakeLists.txt

@@ -53,3 +53,10 @@ add_dependencies(bench dijkstra.exe)
 add_executable(dfs.exe dfs.cpp)
 target_link_libraries(dfs.exe nwgraph)
 add_dependencies(bench dfs.exe)
+
+# -----------------------------------------------------------------------------
+# Container abstraction penalty (requires docopt)
+# -----------------------------------------------------------------------------
+add_executable(containers.exe containers.cpp)
+target_link_libraries(containers.exe nwgraph docopt)
+add_dependencies(bench containers.exe)

bench/abstraction_penalty/apb_common.hpp

@@ -0,0 +1,155 @@
+/**
+ * @file apb_common.hpp
+ *
+ * @brief Common utilities for abstraction penalty benchmarks.
+ *
+ * @copyright SPDX-FileCopyrightText: 2022 Battelle Memorial Institute
+ * @copyright SPDX-FileCopyrightText: 2022 University of Washington
+ *
+ * SPDX-License-Identifier: BSD-3-Clause
+ *
+ * @authors
+ *   Andrew Lumsdaine
+ *
+ */
+
+#ifndef NW_GRAPH_APB_COMMON_HPP
+#define NW_GRAPH_APB_COMMON_HPP
+
+#include <fstream>
+#include <iostream>
+#include <string>
+#include <utility>
+
+#include "nwgraph/edge_list.hpp"
+#include "nwgraph/io/mmio.hpp"
+#include "nwgraph/util/timer.hpp"
+
+namespace nw::graph::apb {
+
+/**
+ * @brief Run a benchmark with setup and timed work phases.
+ *
+ * @tparam Setup  Callable for per-trial setup (not timed)
+ * @tparam Work   Callable for timed work
+ * @param name    Benchmark name for output
+ * @param ntrial  Number of trials to run
+ * @param setup   Setup function called before each trial (not timed)
+ * @param work    Work function to time
+ * @return Average time per trial in milliseconds
+ */
+template <typename Setup, typename Work>
+double bench(const std::string& name, size_t ntrial, Setup&& setup, Work&& work) {
+  double             time = 0;
+  nw::util::ms_timer t(name);
+  for (size_t i = 0; i < ntrial; ++i) {
+    setup();
+    t.start();
+    work();
+    t.stop();
+    time += t.elapsed();
+  }
+  std::cout << t.name() << " " << time / ntrial << " ms" << std::endl;
+  return time / ntrial;
+}
+
+/**
+ * @brief Run a benchmark without setup phase.
+ *
+ * @tparam Work   Callable for timed work
+ * @param name    Benchmark name for output
+ * @param ntrial  Number of trials to run
+ * @param work    Work function to time
+ * @return Average time per trial in milliseconds
+ */
+template <typename Work>
+double bench(const std::string& name, size_t ntrial, Work&& work) {
+  return bench(name, ntrial, [] {}, std::forward<Work>(work));
+}
+
+/**
+ * @brief Load a graph from file (Matrix Market or serialized BGL17 format).
+ *
+ * @tparam Directedness  Graph directedness (directed or undirected)
+ * @tparam Attributes    Edge attribute types
+ * @param file           Path to graph file
+ * @return edge_list containing the graph
+ */
+template <nw::graph::directedness Directedness, class... Attributes>
+nw::graph::edge_list<Directedness, Attributes...> load_graph(const std::string& file) {
+  std::ifstream in(file);
+  std::string   type;
+  in >> type;
+
+  if (type == "BGL17") {
+    nw::util::life_timer                                _(std::string("deserialize ") + file);
+    nw::graph::edge_list<Directedness, Attributes...> el(0);
+    el.deserialize(file);
+    return el;
+  } else if (type == "%%MatrixMarket") {
+    nw::util::life_timer _(std::string("read_mm ") + file);
+    return nw::graph::read_mm<Directedness, Attributes...>(file);
+  } else {
+    std::cerr << "Error: Unrecognized graph file format: " << file << "\n";
+    std::cerr << "Expected 'BGL17' or '%%MatrixMarket' header\n";
+    exit(1);
+  }
+}
+
+/**
+ * @brief Print usage message and exit.
+ *
+ * @param prog  Program name (argv[0])
+ * @param msg   Optional additional message
+ */
+inline void usage(const std::string& prog, const std::string& msg = "") {
+  if (!msg.empty()) {
+    std::cerr << "Error: " << msg << "\n";
+  }
+  std::cerr << "Usage: " << prog << " -f FILE [-n NTRIALS] [-v] [-d]\n";
+  std::cerr << "  -f, --file FILE    Input graph file (Matrix Market or BGL17)\n";
+  std::cerr << "  -n, --ntrials N    Number of trials [default: 1]\n";
+  std::cerr << "  -v, --verbose      Verbose output\n";
+  std::cerr << "  -d, --debug        Debug output\n";
+  exit(1);
+}
+
+/**
+ * @brief Simple command-line argument parser for APB benchmarks.
+ */
+struct Args {
+  std::string file;
+  size_t      ntrial  = 1;
+  bool        verbose = false;
+  bool        debug   = false;
+
+  Args(int argc, char* argv[]) {
+    for (int i = 1; i < argc; ++i) {
+      std::string arg(argv[i]);
+
+      if (arg == "-f" || arg == "--file" || arg == "-i" || arg == "--edgelistfile") {
+        if (++i >= argc) usage(argv[0], "Missing argument for " + arg);
+        file = argv[i];
+      } else if (arg == "-n" || arg == "--ntrials" || arg == "--ntrial") {
+        if (++i >= argc) usage(argv[0], "Missing argument for " + arg);
+        ntrial = std::stoul(argv[i]);
+      } else if (arg == "-v" || arg == "--verbose") {
+        verbose = true;
+      } else if (arg == "-d" || arg == "--debug") {
+        debug = true;
+      } else if (arg == "-h" || arg == "--help") {
+        usage(argv[0]);
+      } else {
+        usage(argv[0], "Unknown option: " + arg);
+      }
+    }
+
+    if (file.empty()) {
+      usage(argv[0], "Input file required (-f)");
+    }
+  }
+};
+
+}  // namespace nw::graph::apb
+
+#endif  // NW_GRAPH_APB_COMMON_HPP