Diagnostics and readme

Malkovsky · Malkovsky · commit d37e6071caae · 2026-02-22T18:29:37.000+03:00
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -27,13 +27,32 @@ endif()
 # ---------------------------------------------------------------------------
 option(PIXIE_TESTS "Build unit tests" ON)
 option(PIXIE_BENCHMARKS "Build benchmarks (includes comparison benchmarks against third-party libraries)" OFF)
+option(PIXIE_DIAGNOSTICS "Include diagnostic logs" OFF)
 option(PIXIE_DOCS "Build Doxygen documentation" OFF)
 
+if(PIXIE_DIAGNOSTICS)
+    add_compile_definitions(PIXIE_DIAGNOSTICS)
+    set(PIXIE_DIAGNOSTICS_LIBS spdlog::spdlog_header_only)
+endif()
+
 # ---------------------------------------------------------------------------
 # Dependencies (fetched only when needed)
 # ---------------------------------------------------------------------------
 include(FetchContent)
 
+if(PIXIE_DIAGNOSTICS)
+    set(SPDLOG_BUILD_SHARED OFF CACHE BOOL "" FORCE)
+    set(SPDLOG_BUILD_EXAMPLE OFF CACHE BOOL "" FORCE)
+    set(SPDLOG_BUILD_TESTING OFF CACHE BOOL "" FORCE)
+    set(SPDLOG_INSTALL OFF CACHE BOOL "" FORCE)
+    FetchContent_Declare(
+        spdlog
+        GIT_REPOSITORY https://github.com/gabime/spdlog.git
+        GIT_TAG v1.14.1
+    )
+    FetchContent_MakeAvailable(spdlog)
+endif()
+
 if(PIXIE_BENCHMARKS)
     FetchContent_Declare(
         googlebenchmark
@@ -91,15 +110,17 @@ if(PIXIE_TESTS)
         PUBLIC include)
     target_link_libraries(unittests
         gtest
-        gtest_main)
+        gtest_main
+        ${PIXIE_DIAGNOSTICS_LIBS})
 
     add_executable(benchmark_tests
         src/tests/benchmark_tests.cpp)
     target_include_directories(benchmark_tests
         PUBLIC include)
     target_link_libraries(benchmark_tests
         gtest
-        gtest_main)
+        gtest_main
+        ${PIXIE_DIAGNOSTICS_LIBS})
 
     add_executable(test_rmm
         src/tests/test_rmm.cpp)
@@ -108,15 +129,17 @@ if(PIXIE_TESTS)
         PUBLIC include/misc)
     target_link_libraries(test_rmm
         gtest
-        gtest_main)
+        gtest_main
+        ${PIXIE_DIAGNOSTICS_LIBS})
 
     add_executable(louds_tree_tests
         src/tests/louds_tree_tests.cpp)
     target_include_directories(louds_tree_tests
         PUBLIC include)
     target_link_libraries(louds_tree_tests
         gtest
-        gtest_main)
+        gtest_main
+        ${PIXIE_DIAGNOSTICS_LIBS})
 endif()
 
 # ---------------------------------------------------------------------------
@@ -130,15 +153,17 @@ if(PIXIE_BENCHMARKS)
     target_link_libraries(benchmarks
         benchmark
         benchmark_main
-        pasta_bit_vector)
+        pasta_bit_vector
+        ${PIXIE_DIAGNOSTICS_LIBS})
     target_compile_definitions(benchmarks PRIVATE PIXIE_THIRD_PARTY_BENCHMARKS)
 
     add_executable(bench_rmm
         src/benchmarks/bench_rmm.cpp)
     target_include_directories(bench_rmm
         PUBLIC include)
     target_link_libraries(bench_rmm
-        benchmark)
+        benchmark
+        ${PIXIE_DIAGNOSTICS_LIBS})
 
     add_executable(bench_rmm_sdsl
         src/benchmarks/bench_rmm_sdsl.cpp)
@@ -147,23 +172,26 @@ if(PIXIE_BENCHMARKS)
         PRIVATE ${sdsl_lite_SOURCE_DIR}/include)
     target_link_libraries(bench_rmm_sdsl
         PRIVATE
-            benchmark)
+            benchmark
+            ${PIXIE_DIAGNOSTICS_LIBS})
 
     add_executable(louds_tree_benchmarks
         src/benchmarks/louds_tree_benchmarks.cpp)
     target_include_directories(louds_tree_benchmarks
         PUBLIC include)
     target_link_libraries(louds_tree_benchmarks
         benchmark
-        benchmark_main)
+        benchmark_main
+        ${PIXIE_DIAGNOSTICS_LIBS})
 
     add_executable(alignment_comparison
         src/benchmarks/alignment_comparison.cpp)
     target_include_directories(alignment_comparison
         PUBLIC include)
     target_link_libraries(alignment_comparison
         benchmark
-        benchmark_main)
+        benchmark_main
+        ${PIXIE_DIAGNOSTICS_LIBS})
 endif()
 
 # ---------------------------------------------------------------------------
diff --git a/CMakePresets.json b/CMakePresets.json
@@ -38,6 +38,7 @@
             "cacheVariables": {
                 "BENCHMARK_ENABLE_LIBPFM": "ON",
                 "CMAKE_BUILD_TYPE": "RelWithDebInfo",
+                "PIXIE_DIAGNOSTICS": "ON",
                 "PIXIE_BENCHMARKS": "ON"
             }
         },
diff --git a/README.md b/README.md
@@ -1,24 +1,31 @@
-# pixie
+# Pixie
+
+<img src="src/docs/images/logo.png" alt="Pixie logo" width="256" align="left" style="float: left; margin-right: 16px; margin-bottom: 8px;" />
 
 `pixie` is a **succinct data structures library**.
+
+<br clear="left" />
+
 ---
 
 ## Features
 
 * **BitVector**
-  * Data structure with 3.61% overhead supporting rank and select for 1 bits. Select support for 0 bits require additional 0.39%, currently not implemented
+  * Data structure with 3.61% overhead supporting rank and select for 1 bits.
   * Supports:
     * `rank(i)`: number of set bits (`1`s) up to position `i`.
     * `select(k)`: position of the `k`-th set bit.
-  * Implementation mainly follows [1] with SIMD optimizations similar to [2] 
-  * AVX-512 support is mandatory for now and thus will not compile without it.
+    * Similar operations `rank0/select0` for `0`.
+  * Implementation mainly follows [1] with SIMD optimizations similar to [2]
+  * Optimized via AVX-512/AVX-2, for large binary sequences performance is I/O bounded.
+* **RmMTree**
+  * Implementation of a range min-max tree, it supports `rank`, `select` and `excess`-related operations allowing for a fast navigation in DFUDS/BP trees.
 ---
 
 ## Requirements
 
 * C++20
-* Compiler with AVX-512 support recommended for best performance.
-* [CMake](https://cmake.org/) ≥ 3.15.
+* [CMake](https://cmake.org/) ≥ 3.18.
 
 ---
 
@@ -27,57 +34,78 @@
 ```bash
 git clone https://github.com/Malkovsky/pixie.git
 cd pixie
-mkdir build && cd build
-cmake ..
-make -j
+cmake --preset release
+cmake --build --preset release
+```
+
+Manual alternative:
+
+```bash
+mkdir -p build/release
+cmake -B build/release -DCMAKE_BUILD_TYPE=Release
+cmake --build build/release -j
 ```
 
-This will build the library along with benchmarks and tests.
+Tests are enabled by default (`PIXIE_TESTS=ON`). Benchmarks are opt-in; enable with `-DPIXIE_BENCHMARKS=ON` or configure with the `benchmarks-all` preset, you can use `benchmark-diagnostic` preset for performance diagnostics (Release with debug info + performance counters support). 
 
 ---
 
 ## Running Tests
 
-After building:
+After building with presets, binaries are located in `build/release`.
 
 ### BitVector
 
 ```bash
-./unittests
+./build/release/unittests
 ```
 
 ### RmM Tree
 
 ```bash
-./test_rmm
+./build/release/test_rmm
 ```
 
 ---
 
 ## Running Benchmarks
 
+Before running benchmarks, configure with presets:
+
+```bash
+cmake --preset benchmarks-all
+cmake --build --preset release
+```
+
+For a RelWithDebInfo diagnostic build, use:
+
+```bash
+cmake --preset benchmarks-diagnostic
+cmake --build --preset release
+```
+
 ### BitVector
 
 Benchmarks are random 50/50 0-1 bitvectors up to $2^{34}$ bits.
 
 ```bash
-./benchmarks
+./build/release/benchmarks
 ```
 
 ### RmM Tree
 
 ```bash
-./bench_rmm
+./build/release/bench_rmm
 ```
 
-For comparison with range min-max tree implementation from [sdsl-lite](https://github.com/simongog/sdsl-lite) (Release build required: `cmake .. -DCMAKE_BUILD_TYPE=Release`):
+For comparison with range min-max tree implementation from [sdsl-lite](https://github.com/simongog/sdsl-lite) (Release build required; use the release preset or `-DCMAKE_BUILD_TYPE=Release`):
 
 ```bash
 sudo cpupower frequency-set --governor performance
-./bench_rmm_sdsl --benchmark_out=rmm_bench_sdsl.json
+./build/release/bench_rmm_sdsl --benchmark_out=rmm_bench_sdsl.json
 ```
 
-For visualization, write the JSON output to a file using `--benchmark_out=<file>` (e.g. `./bench_rmm --benchmark_out=rmm_bench.json`) and plot it with `misc/plot_rmm.py` (add `--sdsl-json rmm_bench_sdsl.json` for comparison).
+For visualization, write the JSON output to a file using `--benchmark_out=<file>` (e.g. `./build/release/bench_rmm --benchmark_out=rmm_bench.json`) and plot it with `scripts/plot_rmm.py` (add `--sdsl-json rmm_bench_sdsl.json` for comparison).
 
 ---
 
diff --git a/include/pixie/bitvector.h b/include/pixie/bitvector.h
@@ -10,6 +10,10 @@
 #include <string>
 #include <vector>
 
+#ifdef PIXIE_DIAGNOSTICS
+#include <spdlog/spdlog.h>
+#endif
+
 namespace pixie {
 
 /**
@@ -381,6 +385,55 @@ class BitVector {
   }
 
  public:
+#ifdef PIXIE_DIAGNOSTICS
+  struct DiagnosticsBytes {
+    size_t source_bitvector_bytes = 0;
+    size_t super_block_rank_bytes = 0;
+    size_t basic_block_rank_bytes = 0;
+    size_t select1_samples_bytes = 0;
+    size_t select0_samples_bytes = 0;
+    size_t total_bytes = 0;
+  };
+
+  /**
+   * @brief Returns the number of bytes used by each internal component.
+   */
+  DiagnosticsBytes diagnostics_bytes() const {
+    DiagnosticsBytes result;
+    result.source_bitvector_bytes = (num_bits_ + 7) / 8;
+    result.super_block_rank_bytes = super_block_rank_.AsConstBytes().size();
+    result.basic_block_rank_bytes = basic_block_rank_.AsConstBytes().size();
+    result.select1_samples_bytes = select1_samples_.AsConstBytes().size();
+    result.select0_samples_bytes = select0_samples_.AsConstBytes().size();
+    result.total_bytes = result.super_block_rank_bytes +
+                         result.basic_block_rank_bytes +
+                         result.select1_samples_bytes +
+                         result.select0_samples_bytes;
+    return result;
+  }
+
+  /**
+   * @brief Log memory usage of internal components.
+   */
+  void memory_report() const {
+    const auto diagnostics = diagnostics_bytes();
+    const double source_bytes =
+        static_cast<double>(diagnostics.source_bitvector_bytes);
+    const auto log_bytes = [&](std::string_view label, size_t bytes) {
+      const double percentage =
+          source_bytes > 0.0 ? 100.0 * static_cast<double>(bytes) / source_bytes
+                             : 0.0;
+      spdlog::info("BitVector {}: {} bytes ({:.2f}% of source)", label, bytes,
+                   percentage);
+    };
+    log_bytes("source_bitvector", diagnostics.source_bitvector_bytes);
+    log_bytes("super_block_rank", diagnostics.super_block_rank_bytes);
+    log_bytes("basic_block_rank", diagnostics.basic_block_rank_bytes);
+    log_bytes("select1_samples", diagnostics.select1_samples_bytes);
+    log_bytes("select0_samples", diagnostics.select0_samples_bytes);
+    log_bytes("total", diagnostics.total_bytes);
+  }
+#endif
   /**
    * @brief Construct from an external array of 64-bit words.
    * @param
diff --git a/src/benchmarks/benchmarks.cpp b/src/benchmarks/benchmarks.cpp
@@ -89,6 +89,9 @@ static void BM_RankNonInterleaved(benchmark::State& state) {
   auto bits_as_words = bits.As64BitInts();
   PrepareRandomBits50pFill(bits_as_words);
   pixie::BitVector bv(bits_as_words, n);
+#ifdef PIXIE_DIAGNOSTICS
+  bv.memory_report();
+#endif
 
   std::mt19937_64 rng(42);
   for (auto _ : state) {
diff --git a/src/docs/Doxyfile.in b/src/docs/Doxyfile.in
@@ -61,7 +61,7 @@ PROJECT_BRIEF          =
 # pixels and the maximum width should not exceed 200 pixels. Doxygen will copy
 # the logo to the output directory.
 
-PROJECT_LOGO           =
+PROJECT_LOGO           = images/logo.png
 
 # With the PROJECT_ICON tag one can specify an icon that is included in the tabs
 # when the HTML document is shown. Doxygen will copy the logo to the output
diff --git a/src/docs/images/logo.png b/src/docs/images/logo.png

Original file line number	Diff line number	Diff line change
`@@ -38,6 +38,7 @@`
`38`	`38`	`"cacheVariables": {`
`39`	`39`	`"BENCHMARK_ENABLE_LIBPFM": "ON",`
`40`	`40`	`"CMAKE_BUILD_TYPE": "RelWithDebInfo",`
	`41`	`+ "PIXIE_DIAGNOSTICS": "ON",`
`41`	`42`	`"PIXIE_BENCHMARKS": "ON"`
`42`	`43`	`}`
`43`	`44`	`},`