Merge pull request #3 from euphoricpoptarts/main

CMake Package and File Organization

Author: egboman

CMakeLists.txt

@@ -1,47 +1,14 @@
-cmake_minimum_required(VERSION 3.18)
-project(jetpartition CXX)
+cmake_minimum_required(VERSION 3.23)
+project(jetpartition LANGUAGES CXX VERSION 1.1.0)
 set(CMAKE_CXX_STANDARD 17)
 set(CMAKE_CXX_STANDARD_REQUIRED True)
 if(NOT CMAKE_BUILD_TYPE)
   set(CMAKE_BUILD_TYPE Release)
 endif()
-# GKlib is a dependency of Metis when built from its github repo
-# Unfortunately there is no simple way to avoid also linking GKlib in this case
-# Older distributions of metis do not create this dependency
-SET(LINK_GKLIB False CACHE BOOL "Newer Metis distributions require us to link GKlib")
 
+# both the apps and the library depend on kokkos and kokkoskernels
+# find KokkosKernels also handles kokkos
 find_package(KokkosKernels REQUIRED)
 add_compile_options(-Wall -Wextra -Wshadow)
-
-# This is used by the build script
-# to avoid putting metis and gklib in the global path
-include_directories(${METIS_DIR}/include)
-link_directories(${METIS_DIR}/lib)
-
-add_executable(jet partition.cpp)
-add_executable(jet4 partition.cpp)
-add_executable(jet2 partition.cpp)
-add_executable(jet_host partition.cpp)
-add_executable(jet_import import_coarse.cpp)
-add_executable(jet_export partition.cpp)
-add_executable(jet_serial partition.cpp)
-add_executable(pstat part_eval.cpp)
-
-target_compile_definitions(jet PUBLIC HASHMAP_P)
-target_compile_definitions(jet4 PUBLIC HASHMAP_P FOUR9)
-target_compile_definitions(jet2 PUBLIC HASHMAP_P TWO9)
-target_compile_definitions(jet_host PUBLIC HASHMAP_P HOST)
-target_compile_definitions(jet_import PUBLIC HASHMAP_P HOST)
-target_compile_definitions(jet_export PUBLIC HASHMAP_P HOST EXP)
-target_compile_definitions(jet_serial PUBLIC HASHMAP_P SERIAL)
-foreach(prog jet jet4 jet2 jet_host jet_import jet_export jet_serial pstat)
-    target_link_libraries(${prog} Kokkos::kokkos Kokkos::kokkoskernels)
-endforeach(prog)
-foreach(prog jet jet4 jet2 jet_host jet_export jet_serial)
-    target_link_libraries(${prog} metis)
-endforeach(prog)
-if(LINK_GKLIB)
-foreach(prog jet jet4 jet2 jet_host jet_export jet_serial)
-    target_link_libraries(${prog} GKlib)
-endforeach(prog)
-endif()
+add_subdirectory(src)
+add_subdirectory(app)

README.md

@@ -2,7 +2,8 @@
 
 The Jet Partitioner is a parallel graph partitioner that runs on most CPU and GPU systems (via Kokkos, a required dependency).
 This partitioner was developed in a collaboration between Sandia National Labs and Pennsylvania State University.
-For details about the algorithm, please see https://arxiv.org/abs/2304.13194
+For details about the algorithm, please see https://arxiv.org/abs/2304.13194  
+If you intend to cite this partitioner in a publication, please cite https://doi.org/10.1137/23M1559129
 
 ## Dependencies
 
@@ -15,7 +16,7 @@ Metis (https://github.com/KarypisLab/METIS): Used for initial partitioning of co
 
 ### Building
 
-Standard CMake build process. If your Metis build requires GKlib, add `-DLINK_GKLIB=True` to your cmake command when building Jet. Example build scripts are provided for macOS with OpenMP and Linux systems with Cuda. These scripts handle all required dependencies.
+Standard CMake build process. CMake version >= 3.23 required. If your Metis build requires GKlib, add `-DLINK_GKLIB=True` to your cmake command when building Jet. You can add `-DMETIS_HINT=<metis install location>` to help cmake find metis (and gklib if it has the same install location) if you have not added metis to your relevant path variables. Example build scripts are provided for macOS with OpenMP and Linux systems with Cuda. These scripts handle all required dependencies.
 
 ### Executables
 
@@ -30,13 +31,18 @@ jet\_serial: jet but runs on the host on a single thread.
 pstat: Given a metis graph file, partition file, and k-value, will print out quality information on the partition.
 
 ### Using Jet Partitioner in Your Code
-We can not provide an option to compile a library due to the use of templates. However, you can import "jet.hpp" into your code to use the partitioner via the "jet\_partitioner::partition" method. Note that this requires you to add our source directory to your include path and also to link our dependencies. This method currently always uses the default coarsening algorithm.
+We provide a cmake package that you can install on your system. Add `find_package(jet CONFIG REQUIRED)` to your project's CMakeLists.txt file and link your executable/s to `jet::jet`. Include `jet.h` in your code to use one of the provided partitioning functions. Each function is distinguished by the target Kokkos execution space it will run in and the type of KokkosKernels CrsMatrix which it accepts. Reference `jet_defs.h` for the relevant template definitions of these parameters. You can set the desired part count and imbalance values on the input config_t struct (see `jet_config.h` for other parameters).
+
+#### Tips
+On Linux systems, you can create a file `~/.cmake/packages/jet/find.txt` that cmake will automatically use to find the jet cmake package.
+Inside this file, add the full path to the jet install directory.
 
 ### Input Format
-We do not yet support vertex weights within metis graph files.
+The partitioner executables accept graphs stored in the metis graph file format. We do not yet support vertex weights within metis graph files.
 
 ### Config File format:  
 \<Coarsening algorithm\> (0 for 2-hop matching)/(1 for HEC)/(2 for pure matching)/(default is 2-hop matching)  
 \<Number of parts\>  
 \<Partitioning attempts\>  
 \<Imbalance value\>  
+\<Ultra quality settings\> (Optional) 1 to enable, 0 to disable (default)

app/CMakeLists.txt

@@ -0,0 +1,30 @@
+# jet executables
+add_executable(jet_ex driver.cpp)
+set_property(TARGET jet_ex PROPERTY OUTPUT_NAME jet)
+add_executable(jet4 driver.cpp)
+add_executable(jet2 driver.cpp)
+add_executable(jet_host driver.cpp)
+add_executable(jet_import import_coarse.cpp)
+add_executable(jet_export driver.cpp)
+add_executable(jet_serial driver.cpp)
+add_executable(pstat part_eval.cpp)
+
+foreach(prog jet_import pstat)
+    target_include_directories(${prog} PRIVATE ${CMAKE_SOURCE_DIR}/header ${CMAKE_SOURCE_DIR}/src)
+endforeach(prog)
+
+# compile definitions to set exe behavior
+target_compile_definitions(jet4 PUBLIC FOUR9)
+target_compile_definitions(jet2 PUBLIC TWO9)
+target_compile_definitions(jet_host PUBLIC HOST)
+target_compile_definitions(jet_import PUBLIC HOST)
+target_compile_definitions(jet_export PUBLIC HOST EXP)
+target_compile_definitions(jet_serial PUBLIC SERIAL)
+
+# link executables
+target_link_libraries(jet_import Kokkos::kokkos Kokkos::kokkoskernels)
+target_link_libraries(pstat Kokkos::kokkos Kokkos::kokkoskernels)
+# other executables get the kokkos dependencies via jet
+foreach(prog jet_ex jet4 jet2 jet_host jet_export jet_serial)
+    target_link_libraries(${prog} jet)
+endforeach(prog)

import_coarse.cpp app/driver.cpp

@@ -36,86 +36,93 @@
 // SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 //
 // ************************************************************************
-#include "contract.hpp"
-#include "uncoarsen.hpp"
-#include "defs.h"
+
+#include "jet_defs.h"
 #include "io.hpp"
+#include "jet.h"
+#include "jet_config.h"
 #include <limits>
+#include <vector>
+#include <algorithm>
 
 using namespace jet_partitioner;
 
-part_vt partition(value_t& edge_cut,
-                    const config_t& config,
-                    ExperimentLoggerUtil<value_t>& experiment) {
-
-    using coarsener_t = contracter<matrix_t>;
-    using uncoarsener_t = uncoarsener<matrix_t, part_t>;
-    using coarse_level_triple = typename coarsener_t::coarse_level_triple;
-
-    std::list<coarse_level_triple> cg_list = load_coarse();
-    Kokkos::fence();
-    Kokkos::Timer t;
-    double start_time = t.seconds();
-    part_t k = config.num_parts;
-    double fin_coarsening_time = t.seconds();
-    double imb_ratio = config.max_imb_ratio;
-    part_vt coarsest_p = load_coarse_part(cg_list.back().mtx.numRows());
-    Kokkos::fence();
-    experiment.addMeasurement(Measurement::InitPartition, t.seconds() - fin_coarsening_time);
-    part_vt part = uncoarsener_t::uncoarsen(cg_list, coarsest_p, k, imb_ratio
-        , edge_cut, experiment);
-
-    Kokkos::fence();
-    double fin_uncoarsening = t.seconds();
-    cg_list.clear();
-    Kokkos::fence();
-    double fin_time = t.seconds();
-    experiment.addMeasurement(Measurement::Total, fin_time - start_time);
-    experiment.addMeasurement(Measurement::Coarsen, fin_coarsening_time - start_time);
-    experiment.addMeasurement(Measurement::FreeGraph, fin_time - fin_uncoarsening);
-
-    experiment.refinementReport();
-    experiment.verboseReport();
-
-    return part;
-}
-
-void degree_weighting(const matrix_t& g, wgt_view_t vweights){
+void degree_weighting(const matrix_t& g, wgt_vt vweights){
     Kokkos::parallel_for("set v weights", r_policy(0, g.numRows()), KOKKOS_LAMBDA(const ordinal_t i){
         vweights(i) = g.graph.row_map(i + 1) - g.graph.row_map(i);
     });
 }
 
+value_t median(std::vector<value_t>& cuts){
+    std::sort(cuts.begin(), cuts.end());
+    int count = cuts.size();
+    if(count % 2 == 0){
+        return (cuts[count / 2] + cuts[(count / 2) - 1]) / 2;
+    } else {
+        return cuts[count / 2];
+    }
+}
+
 int main(int argc, char **argv) {
 
-    if (argc < 2) {
+    if (argc < 3) {
         std::cerr << "Insufficient number of args provided" << std::endl;
-        std::cerr << "Usage: " << argv[0] << " <config_file> <optional partition_output_filename> <optional metrics_filename>" << std::endl;
+        std::cerr << "Usage: " << argv[0] << " <metis_graph_file> <config_file> <optional partition_output_filename> <optional metrics_filename>" << std::endl;
         return -1;
     }
     config_t config;
-    if(!load_config(config, argv[1])) return -1;
+    char *filename = argv[1];
+    if(!load_config(config, argv[2])) return -1;
     char *part_file = nullptr;
     char *metrics = nullptr;
-    if(argc >= 3){
-        part_file = argv[2];
-    }
     if(argc >= 4){
-        metrics = argv[3];
+        part_file = argv[3];
+    }
+    if(argc >= 5){
+        metrics = argv[4];
     }
+#ifdef FOUR9
+    config.refine_tolerance = 0.9999;
+#elif defined TWO9
+    config.refine_tolerance = 0.99;
+#endif
+#ifdef EXP
+    config.dump_coarse = true;
+#endif
+    config.verbose = true;
 
     Kokkos::initialize();
     //must scope kokkos-related data
     //so that it falls out of scope b4 finalize
     {
+        matrix_t g;
+        bool uniform_ew = false;
+        if(!load_metis_graph(g, uniform_ew, filename)) return -1;
+        std::cout << "vertices: " << g.numRows() << "; edges: " << g.nnz() / 2 << std::endl;
+        wgt_vt vweights("vertex weights", g.numRows());
+        Kokkos::deep_copy(vweights, 1);
+
         part_vt best_part;
 
         value_t edgecut_min = std::numeric_limits<value_t>::max();
+        std::vector<value_t> cuts;
+        int64_t avg = 0;
         for (int i=0; i < config.num_iter; i++) {
             Kokkos::fence();
             value_t edgecut = 0;
-            ExperimentLoggerUtil<value_t> experiment;
-            part_vt part = partition(edgecut, config, experiment);
+            experiment_data<value_t> experiment;
+#ifdef HOST
+            part_vt part = partition_host(edgecut, config, g, vweights, uniform_ew,
+                experiment);
+#elif defined SERIAL
+            part_vt part = partition_serial(edgecut, config, g, vweights, uniform_ew,
+                experiment);
+#else
+            part_vt part = partition(edgecut, config, g, vweights, uniform_ew,
+                experiment);
+#endif
+            avg += edgecut;
+            cuts.push_back(edgecut);
 
             if (edgecut < edgecut_min) {
                 edgecut_min = edgecut;
@@ -130,7 +137,9 @@ int main(int argc, char **argv) {
             }
             if(metrics != nullptr) experiment.log(metrics, first, last);
         }
-        std::cout << "Imported coarse graphs, min edgecut found is " << edgecut_min << std::endl;
+        std::cout << "graph " << filename << ", min edgecut found is " << edgecut_min << std::endl;
+        std::cout << "average edgecut: " << (avg / config.num_iter) << std::endl;
+        std::cout << "median edgecut: " << median(cuts) << std::endl;
 
         if(part_file != nullptr && config.num_iter > 0) write_part(best_part, part_file);
     }