VeloGraphX

Exact dynamic graph analytics in C++20.

Maintain exact graph analytics as your graph changes — repairing affected work when that is cheaper and falling back to full recomputation when it is not.

VeloGraphX is a high-performance CPU engine for analytics on evolving graphs. It combines mutable graph storage, localized incremental maintenance, adaptive repair/recompute decisions, and reproducible systems evaluation.

2,000,000 updates · 0 BFS mismatches · 0 triangle mismatches
Adaptive repair/recompute · Multicore CPU · Storage-independent algorithms · Reproducible benchmarks

Engineering quality: 30 CTest targets · Linux/macOS CI · ASan/UBSan · Python 3.9–3.14 packaging

Quick links: Release · Enterprise Security · Security Policy · C++ examples · Python · Architecture · Dynamic storage · Benchmarks · Reproduction

Want to try it? Starting with v0.8.2, install the Python package with pip install velographx, or build the C++ examples from source → Quick start

When should I use VeloGraphX?

VeloGraphX is designed for workloads where a graph changes over time and analytics must be maintained across updates without assuming that incremental repair is always the fastest choice. Relevant use cases include evolving network analysis, relationship and fraud graphs, changing knowledge graphs, infrastructure/dependency graphs, and graph-systems research.

If your graph is static, a specialized static CSR engine may be simpler or faster. If approximate answers are acceptable, streaming or approximate graph methods may offer different trade-offs. VeloGraphX focuses on correctness-preserving analytics under graph mutation and explicit measurement of the repair-vs-recompute crossover.

What is different?

VeloGraphX brings four concerns into one systems design:

• Mutable graph storage: segmented CSR, packed deltas, sparse row patches and explicit consolidation.
• Incremental analytics: maintained state for dynamic BFS/SSSP, connected components, triangles, k-core, weighted SSSP and PageRank-related paths.
• Adaptive execution: measure affected work and observed cost instead of assuming incremental execution always wins.
• Auditable evaluation: correctness gates, pinned datasets/competitors, retained artifacts and explicit negative results.

Design principles

• Correctness first: incremental paths are checked against fresh or converged reference computation where required.
• Measure crossover: choose localized repair or full recomputation according to workload and observed cost.
• Separate algorithms from storage: graph-access abstractions let the same algorithmic path work across multiple representations.
• Make evidence reproducible: benchmark provenance, timing contracts and claim boundaries are part of the project design.

Python install

Starting with v0.8.2, VeloGraphX is distributed as a Python package with prebuilt wheels for supported CPython platforms.

python -m pip install velographx

Minimal dynamic Python example:

import velographx as vx

g = vx.Graph(4, False)
updates = vx.UpdateBatch()
updates.add(0, 1)
updates.add(1, 2)
g.apply(updates)

bfs = vx.IncrementalBFS(g, 0)
print(bfs.distances)

The Python module uses the same native C++20 engine underneath. Release CI builds and smoke-tests CPython 3.9–3.14 wheels for Linux, Windows, macOS Intel and Apple Silicon, plus a source distribution. See python/README.md for source, editable, and manual CMake installation paths.

Results at a glance

GitHub-hosted numbers are reproducible engineering evidence, not publication-grade hardware claims.

Selected competitor results

Dynamic BFS — VeloGraphX vs GraphBolt/DZiG

Both systems consume the same deterministic directed graph and mutation stream. The comparable timing envelope includes graph mutation + maintained answer update; GraphBolt stream-reading time is excluded.

Correctness: all reported VeloGraphX results were exact, and every GraphBolt/DZiG final answer passed independent fresh-recompute directed-reachability verification.

GraphBolt/DZiG is pinned to commit 2d56f39cb17c85d624bee6a63f8fc34a8f149a36 and executed with CILK_NWORKERS=1.

Static BFS — VeloGraphX vs GAPBS vs LAGraph

These measurements compare fresh BFS kernels on prepared graph representations.

Static SSSP — VeloGraphX vs GAPBS

The same campaign also retains cases where a competitor wins.

These results intentionally include both wins and losses. They demonstrate workload-specific behavior rather than a universal performance advantage.

Timing boundary: GAPBS results are fresh static recomputation on an already-materialized post-update graph and therefore are not presented as a direct dynamic-system comparison with VeloGraphX. Dataset loading, one-time preparation, and correctness verification are excluded from the primary kernel timing where specified by the benchmark contract.

For exact competitor revisions, dataset provenance, raw samples, correctness gates, timing contracts, and reproduction instructions, see the benchmark methodology and GraphBolt/DZiG + GAPBS benchmark contract.

Algorithm capabilities

The implementation also includes graph-access abstraction, SIMD-oriented intersection paths, multicore scheduling, NUMA-aware policies, compression, partition caching and asynchronous partition loading.

Quick start

Requires CMake ≥ 3.20 and a C++20 compiler for source builds.

git clone https://github.com/sauravsingla/VeloGraphX.git
cd VeloGraphX
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j
ctest --test-dir build --output-on-failure
./build/velographx_example
./build/velographx_dynamic_example

Minimal static C++ API:

#include "velographx/algorithms.hpp"

velographx::CsrGraph graph({{0,1}, {1,2}, {2,3}}, false);
auto distance = velographx::bfs_distances(graph, 0);
auto triangles = velographx::triangle_count(graph);

Minimal dynamic C++ API:

#include "velographx/storage/dynamic_graph.hpp"
#include "velographx/incremental/triangles.hpp"

velographx::DynamicGraph graph(6, false);
velographx::UpdateBatch initial;
initial.add(0, 1);
initial.add(1, 2);
initial.add(2, 0);
graph.apply(initial);

velographx::IncrementalTriangleCount triangles(graph);

velographx::UpdateBatch update;
update.add(2, 3);
triangles.apply(update);

auto current_triangles = triangles.value();

For the complete dynamic C++ example, see examples/dynamic_transactions.cpp. For Python package usage and source-build options, see python/README.md.

Architecture

flowchart LR
    U[Update batch] --> G[Mutable graph\nbase CSR + deltas / row patches]
    G --> S{Adaptive selector}
    S -->|localized affected work| R[Exact incremental repair]
    S -->|repair cost too high| F[Full recomputation]
    R --> E[Maintained result]
    F --> E

The current storage layer uses segmented CSR, packed deltas, sparse row-level patches, forward/reverse adjacency, and explicit canonical CSR consolidation for long-running patch accumulation.

The selector uses update fraction, affected work, graph scale, root locality and observed cost to decide when incremental repair is worthwhile. See the architecture and dynamic-storage design for implementation details.

Algorithms & runtime

• Dynamic analytics: BFS/unweighted SSSP, weighted SSSP, connected components, triangle count, k-core and PageRank-related maintenance paths.
• Storage-independent execution: the graph-access contract supports mutable storage, CSR and foreign graph representations.
• CPU systems runtime: multicore execution, SIMD intersections, NUMA-aware policies, compression, partition caching and asynchronous partition loading.
• C++ engine, packaged Python interface: native hot paths remain in C++; v0.8.2 adds standard pip-installable Python distribution and cross-platform release wheels.

Benchmark & evidence

The headline results are backed by retained benchmark contracts, pinned datasets and competitors, correctness gates, machine-readable artifacts, and explicit claim boundaries. Known negative results are retained rather than hidden: competitors win some small-update regimes; GAP is much faster on the tested static SSSP workload; CSR is faster for full recompute; and compression currently trades traversal speed for memory reduction.

Reproduce the 2M-update exactness test

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release \
  -DVELOGRAPHX_BUILD_TESTS=OFF -DVELOGRAPHX_BUILD_BENCHMARKS=OFF
cmake --build build --target velographx -j 2
c++ -O3 -DNDEBUG -std=c++20 -Iinclude benchmarks/exactness_stress.cpp \
  build/libvelographx.a -pthread -o build/exactness_stress
./build/exactness_stress 2000000 256

The default build currently defines 30 CTest targets plus benchmark executables.

Evidence boundary / next step

The hosted campaigns establish correctness, reproducibility and crossover behavior, but shared GitHub runners are noisy and hardware can vary. Controlled-hardware publication tables remain pending. The canonical campaign is designed for pinned datasets and hardware, 1/2/4/8/16/32-thread scaling, NUMA placement, hardware counters and larger real-world/R-MAT workloads.

Project status

VeloGraphX is an active research and engineering project. Current library/package version: 0.8.2. APIs may evolve before 1.0, so pin a version or commit for reproducible experiments.

The v0.8.2 release adds production-oriented Python packaging, cross-platform wheel builds, source-distribution validation, installed-package smoke tests, and PyPI Trusted Publishing while preserving the existing C++20 engine and graph-analytics APIs. Research citation metadata is available in CITATION.cff.

Contributing

Contributions are welcome, particularly around dynamic graph algorithms, CPU optimization, storage policies, benchmark reproducibility, interoperability and documentation. See CONTRIBUTING.md before opening a contribution.

New to VeloGraphX? Start with a good first issue or join the Discussions to share a workload, idea or benchmark suggestion.

Apache-2.0 licensed. See CODE_OF_CONDUCT.md, SECURITY.md, and CHANGELOG.md.