Skip to content

Command Line Reference

Abdullah edited this page Sep 1, 2026 · 7 revisions

Command-Line Reference

Complete reference for all GraphBrew command-line options.


Quick Reference

One-command experiment mode

# Download N graphs per size and run the configured experiment pipeline
python3 scripts/graphbrew_experiment.py --target-graphs 150

# Preview without executing
python3 scripts/graphbrew_experiment.py --target-graphs 150 --dry-run

--target-graphs N auto-enables the catalog, build, reorder, benchmark, and analysis stages for the selected graph sizes.

Combine with --size to target a specific size category:

python3 scripts/graphbrew_experiment.py --target-graphs 200 --size small

Size categories (edge-count ranges, auto-discovered from SuiteSparse):

Size Edge Range Max Available
small 10K – 500K ~225
medium 500K – 5M ~134
large 5M – 50M ~70
xlarge 50M – 500M ~37

Evaluation modes

Mode Command Description
One-Command --target-graphs 150 Download, build, reorder, benchmark, and analyze
Reorder Only --phase reorder --size small Test reordering algorithms only
Benchmark Only --phase benchmark --size small --skip-cache Run graph algorithm benchmarks (BFS, PR, etc.)
End-to-End --full --size small --auto Full evaluation pipeline without training
Validation --brute-force --validation-benchmark pr Compare configured orderings for one kernel

Historical offline-model modes

These commands are retained for offline compatibility. They are not required by explicit GraphBrew compositions.

Mode Command Description
Standard --train --size small --auto One-pass training: reorder → benchmark → cache → weights
Iterative --train-iterative --target-accuracy 90 Repeated training until target accuracy
Batched --train-batched --size medium --batch-size 8 Large-scale batched training

New Flags

Flag Description
--target-graphs N One-command mode: download N graphs/size and run the pipeline
--dry-run Print planned stages and resource requirements, then exit
--skip-eval Skip the optional offline-model evaluation phase

Common Modifiers

Modifier Description
--quick Key algorithms only (faster)
--skip-cache Skip cache simulation (faster)
--skip-expensive Skip BC/SSSP benchmarks
--all-variants Test all algorithm variants
--auto Auto-detect memory/disk limits
--precompute Use pre-generated label maps
--pregenerate-sg Pre-generate reordered .sg per algorithm (default ON)
--no-pregenerate-sg Disable .sg pre-generation; reorder at runtime instead

Run Phases Separately

You can run each phase independently. Later phases automatically load results from earlier phases:

Phase Command Description
Phase 0 (automatic) Convert .mtx.sg with RANDOM baseline + pre-generate reordered .sg per algorithm
Phase 1 --phase reorder Generate reordered graphs (.lo label maps)
Phase 2 --phase benchmark Run graph algorithm benchmarks (BFS, PR, etc.)
Phase 3 --phase cache Run cache simulation
Phase 4 --phase weights Historical offline-model export
Phase 5 --phase adaptive Deprecated offline-model analysis
# Run each phase separately
python3 scripts/graphbrew_experiment.py --phase reorder --size small
python3 scripts/graphbrew_experiment.py --phase benchmark --size small
python3 scripts/graphbrew_experiment.py --phase cache --size small

# Or chain them
python3 scripts/graphbrew_experiment.py --phase reorder --size small && \
python3 scripts/graphbrew_experiment.py --phase benchmark --size small && \
python3 scripts/graphbrew_experiment.py --phase cache --size small

Note: Results are saved to results/ after each phase. Later benchmark and cache phases load pregenerated .lo mappings from the reorder phase. Historical model commands may also read results/data/adaptive_models.json; explicit compositions do not.


Benchmark Binaries

All binaries are located in bench/bin/. The automated pipeline uses seven benchmarks by default (TC excluded from experiments):

Binary Algorithm Description
pr PageRank (pull) Page importance ranking
pr_spmv PageRank (SpMV) Sparse matrix-vector PageRank
bfs BFS Breadth-first search
cc Connected Components (Afforest) Find connected subgraphs
cc_sv Connected Components (SV) Shiloach-Vishkin CC
sssp Shortest Paths Single-source shortest paths
bc Betweenness Centrality Centrality measure
tc Triangle Counting Count triangles
converter - Convert graph formats

Universal Options

These options work with all benchmarks:

Input/Output

Option Description Example
-f <file> Input graph file (required) -f graph.el
-o <id> Reordering algorithm ID (0-16) -o 7
-s Make graph undirected (symmetrize) -s
-j type:n:m Partition graph (type=0 Cagra, 1 TRUST), default 0:1:1 -j 0:2:2
-n <trials> Number of benchmark trials -n 5

File Format Detection

GraphBrew automatically detects the file format from the file extension:

Extension Format Description
.el Edge list Text file with "src dst" pairs
.wel Weighted edge list Text file with "src dst weight"
.mtx Matrix Market Standard sparse matrix format
.gr DIMACS DIMACS graph format
.sg Serialized graph Binary format (unweighted)
.wsg Weighted serialized Binary format (weighted)
.graph METIS METIS adjacency format

Example:

./bench/bin/pr -f graph.el -s -n 5      # Auto-detected as edge list
./bench/bin/sssp -f graph.wel -s -n 5   # Auto-detected as weighted edge list

General Flags

Option Description
-h Show help message
-v Verify results (slower)
-g <scale> Generate 2^scale Kronecker graph
-u <scale> Generate 2^scale uniform-random graph
-k <degree> Average degree for synthetic graph (default: 16)
-m Reduce memory usage during graph building
-l Log performance within each trial
-a Output analysis of last run
-S Keep self-loops (default: removed)

Partitioning / Segmentation

Type Partitioning Implementation Notes
0 Cagra/GraphIT CSR slicing cache/popt.hMakeCagraPartitionedGraph Uses graphSlicer, honors -z (use indegree)
1 TRUST (triangle counting) partition/trust.hTrustPartitioner::MakeTrustPartitionedGraph Orients edges, partitions p_n × p_m

Tip: Cache simulation headers live in bench/include/cache_sim/ (cache_sim.h, graph_sim.h). Cagra partition helpers live in bench/include/graphbrew/partition/cagra/ (popt.h). See docs/INDEX.md for a quick map.

Examples:

# Cagra partitioning into 2x2 segments (out-degree)
./bench/bin/pr -f graph.mtx -j 0:2:2

# TRUST partitioning into 2x2 segments
./bench/bin/tc -f graph.mtx -j 1:2:2

Reordering Algorithm IDs

Use with -o <id>:

ID Algorithm Category
0 ORIGINAL None
1 Random Basic
2 Sort Basic
3 HubSort Hub-based
4 HubCluster Hub-based
5 DBG DBG-based
6 HubSortDBG DBG-based
7 HubClusterDBG DBG-based
8 RabbitOrder Community (has variants, see below)
9 GOrder Cache-based (has variants, see below)
10 COrder Cache-based
11 RCMOrder Classic (has variants, see below)
12 GraphBrewOrder Community (has variants, see below)
13 MAP External mapping
14 AdaptiveOrder experimental selector compatibility interface
15 LeidenOrder Leiden (GVE-Leiden baseline)
16 GoGraphOrder Flow-edge (has variants, see below)

Note: For current variant lists, see scripts/lib/core/utils.py which defines:

  • RABBITORDER_VARIANTS, GORDER_VARIANTS, RCM_VARIANTS, GRAPHBREW_VARIANTS, GOGRAPH_VARIANTS
  • Use get_algo_variants(algo_id) to query programmatically

GOrder Variants (Algorithm 9)

GOrder supports four variants:

Variant Example Description
(default) -o 9 Compatibility auto mode — legacy GoGraph below the 32-bit edge-position limit, faithful CSR above it
gograph -o 9:gograph Force the legacy GoGraph path for reproducibility checks
csr -o 9:csr Faithful CSR-native implementation
fast -o 9:fast Parallel batch — atomic score updates, fan-out cap, scales across threads

The gograph and csr variants use the same RCM warm start and faithful serial greedy semantics. The CSR path avoids the legacy edge-list materialization and 32-bit edge-position limit. Default window size w=5 (matching the original SIGMOD'16 paper). Override with GORDER_WINDOW=N.

The fast variant replaces the serial UnitHeap with a score array + active frontier. It is a relaxed parallel heuristic and is not assumed to be mapping-equivalent to the faithful variants.

GoGraphOrder Variants (Algorithm 16)

GoGraphOrder maximises M(σ) — the count of edges where source precedes destination in the ordering. Primarily benefits directed graphs (M(σ) is constant for symmetric/undirected graphs).

Variant Example Description
(default) -o 16 Optimised faithful: flat delta array, merged pev, degree-1 short-circuit
fast -o 16:fast Iterative flow-score sorting — heuristic O(n log n + m) per iteration
naive -o 16:naive Original faithful (per-call map, for validation)

All three variants produce different orderings and must be treated as separate experimental configurations.

RCMOrder Variants (Algorithm 11)

RCM supports two variants:

Variant Example Description
(default) -o 11 GoGraph double-RCM (two-pass, high quality)
bnf -o 11:bnf CSR-native BNF start node + deterministic parallel CM BFS, faster reorder

The BNF variant uses George-Liu pseudo-peripheral node finder with RCM++ width-minimizing criterion and a speculative parallel Cuthill-McKee BFS that produces the same ordering as serial.

GraphBrewOrder Ordering Strategies (Algorithm 12)

GraphBrewOrder composes a Leiden or Rabbit partitioner with explicit block and per-community ordering choices. Options can be passed directly — the graphbrew prefix is not required.

Ordering strategies (passed directly as -o 12:strategy):

Strategy Example Description
(default) -o 12 Leiden + per-community RabbitOrder (LAYER mode)
hrab -o 12:hrab Leiden + Rabbit super-graph + RCM intra; measured, not a universal best
dfs -o 12:dfs DFS dendrogram traversal
bfs -o 12:bfs BFS dendrogram traversal
conn -o 12:conn Connectivity BFS within communities
dbg -o 12:dbg DBG within each community
corder -o 12:corder Hot/cold within communities
dbg-global -o 12:dbg-global DBG across all vertices
corder-global -o 12:corder-global Hot/cold across all vertices
streaming -o 12:streaming Leiden + lazy aggregation
lazyupdate -o 12:lazyupdate Batched community weight updates
rabbit -o 12:rabbit RabbitOrder single-pass pipeline
rabbit:dfs -o 12:rabbit:dfs RabbitOrder + DFS post-ordering
compose -o 12:compose:sg_*:comm_*:intra_* Pluggable three-axis composition (see below)

Compose-variant axes (pick one of each):

Axis Prefix Picks Maps to
Super-graph order sg_ none, super_rabbit, super_rcm, tile_rabbit, hilbert SuperGraphOrder enum
Community order comm_ size, size_asc, degree_desc, degree_asc, identity, cut_min CommunityOrder enum
Intra-community order intra_ bfs, rcm, rcmpp, hubsort, hub2, deg_asc, alternate, random, bndlast, core, dendrogram, gorder IntraCommunityOrder enum
Refinement pass refine_ none, 2swap RefinementPass enum

Extra compose modifiers (anywhere after compose:):

Token Effect
gw<N> Gorder window size for relaxed local Gorder (default 5); choose through a controlled comparison
sgres<F> Super-graph modularity resolution γ (default 0.10)
cd_rabbit / cd_leiden Override the GraphBrewOrder community-detection backend after algorithm ID 12

Legacy alias tokens s1_*, s2_*, s3_* are still accepted (older parity scripts depend on them).

The rejected capacity-run and faithful-local-Gorder prototypes are test-only and intentionally have no public CLI tokens.

Examples:

  • -o 12:compose:sg_super_rabbit:comm_identity:intra_rcm — equivalent to 12:hrab
  • -o 12:compose:sg_tile_rabbit:comm_identity:intra_bfs — equivalent to 12:tqr
  • -o 12:compose:sg_none:comm_size:intra_rcm — no super-graph, sort by size, RCM intra
  • -o 12:leiden:compose:comm_degree_desc:intra_hubsort — Leiden + per-community hub-first sort, communities ordered by total degree desc
  • -o 12:rabbit:compose:sg_super_rabbit:comm_degree_desc:intra_hubsort — 4-axis Rabbit-super × degree-desc × hub-first

Defaults if omitted: sg_none, comm_size, intra_bfs, refine_none. See GraphBrewOrder#the-compose-variant-pluggable-axes for details.

Resolution modes:

Mode Syntax Description
Auto -o 12 or -o 12:hrab Compute resolution from graph density/CV (default)
Dynamic -o 12:dynamic Auto initial, adjust each pass
Fixed -o 12:0.75 or -o 12:hrab:0.75 Use specified resolution value

Cluster variants (for per-community dispatch mode):

Variant Description Default Final Algo
leiden Leiden community detection (default) RabbitOrder (8)
rabbit RabbitOrder community detection (supports all orderings) Native DFS
hubcluster Hub-degree based clustering N/A (native)
rcm Leiden + per-community RCM + super-graph BNF-RCM N/A (bandwidth minimization)

Both leiden and rabbit presets can be combined with any ordering strategy (Layer 1). For example:

  • -o 12:rabbit:dbg — Rabbit communities + DBG ordering
  • -o 12:rabbit:hubcluster — Rabbit communities + hub-cluster ordering
  • -o 12:leiden:dbg — Leiden communities + DBG ordering
  • -o 12:rcm — Leiden communities + per-community RCM + super-graph RCM

Without an ordering suffix, 12:rabbit uses its native DFS and 12:leiden uses the default LAYER ordering.

Override the final reordering algorithm with :<algo_id>, e.g. -o "12:leiden:7" uses HubClusterDBG.

Multi-Layer Configuration: GraphBrewOrder's CLI string is parsed as a multi-layer pipeline:

  • Layer 0 (Preset): leiden | rabbit | hubcluster
  • Layer 1 (Ordering): hrab | dfs | bfs | conn | dbg | corder | dbg-global | corder-global | streaming | lazyupdate | ...
  • Layer 2 (Aggregation): gvecsr | leiden | streaming | hybrid
  • Layer 3 (Features): merge | hubx | gord | hsort | rcm | norefine | verify | graphbrew | recursive | flat (additive — combine any)
  • Layer 4 (Dispatch): finalAlgoId (0-11), depth (-1=auto), subAlgoId
  • Layer 5 (Numeric): resolution (float), max_iterations, max_passes

Example: -o 12:leiden:hrab:gvecsr:merge:hubx:0.75 sets preset=leiden, ordering=hrab, aggregation=gvecsr, features=[merge,hubx], resolution=0.75.

See GRAPHBREW_LAYERS in scripts/lib/core/utils.py for the full definition.

Chained reorderings: Pass multiple -o flags to apply orderings sequentially:

./bench/bin/converter -f graph.el -s -o 2 -o 8:csr -b graph.sg  # SORT then RABBITORDER

See Reordering-Algorithms#chained-orderings for all defined chains.

Auto-Resolution: Automatically computed based on graph's coefficient of variation (CV):

  • High-CV graphs (social/web): resolution ≈ 0.50 (coarser communities, better locality)
  • Low-CV graphs (road networks): resolution ≈ 0.60-0.77 (finer communities)

Benchmark-Specific Options

PageRank (pr)

./bench/bin/pr [options]
Option Description Default
-i <iter> Maximum iterations 20
-t <tol> Convergence tolerance 1e-4

Note: The damping factor is hardcoded to 0.85 in the implementation.

Examples:

# Standard PageRank
./bench/bin/pr -f graph.el -s -n 5

# With custom parameters
./bench/bin/pr -f graph.el -s -i 100 -t 1e-8 -n 5

# With reordering
./bench/bin/pr -f graph.el -s -o 12 -n 5

BFS (bfs)

./bench/bin/bfs [options]
Option Description Default
-r <id[,id...]> Original source ID or ordered source list Random

Examples:

# BFS from vertex 0
./bench/bin/bfs -f graph.el -s -r 0 -n 5

# One timed trial per listed original source
./bench/bin/bfs -f graph.el -s -r 4,27,103

# BFS from random roots
./bench/bin/bfs -f graph.el -s -n 5

# With reordering
./bench/bin/bfs -f graph.el -s -o 7 -r 0 -n 5

Connected Components (cc)

./bench/bin/cc [options]

No additional options.

Examples:

# Find components
./bench/bin/cc -f graph.el -s -n 5

# With verification
./bench/bin/cc -f graph.el -s -v -n 3

SSSP (sssp)

./bench/bin/sssp [options]
Option Description Default
-r <id[,id...]> Original source ID or ordered source list; list size sets trials Random
-d <delta> Delta for delta-stepping 1

Examples:

# SSSP from vertex 0
./bench/bin/sssp -f graph.wel -s -r 0 -n 5

# With custom delta
./bench/bin/sssp -f graph.wel -s -r 0 -d 2 -n 5

# One timed trial for each original source ID
./bench/bin/sssp -f graph.wel -s -r 4,27,103 -d 2

Note: SSSP requires weighted edges (.wel format).

Betweenness Centrality (bc)

./bench/bin/bc [options]
Option Description Default
-r <id[,id...]> Original source ID or ordered source list Random
-i <iterations> Number of source iterations 1

Examples:

# BC from single source
./bench/bin/bc -f graph.el -s -r 0 -n 5

# BC with multiple iterations (more accurate)
./bench/bin/bc -f graph.el -s -i 4 -n 5

# Explicit-list BC is single-source Brandes: one trial per source
./bench/bin/bc -f graph.el -s -r 4,27,103 -i 1

Source lists are fully resolved through the graph's original-to-internal ID permutation before timing. Invalid, duplicate, unmapped, or isolated sources fail closed; the runtime never falls back to the numeric ID or a random source.

Triangle Counting (tc)

./bench/bin/tc [options]

No additional options.

Examples:

# Count triangles
./bench/bin/tc -f graph.el -s -n 5

# With reordering (important for TC!)
./bench/bin/tc -f graph.el -s -o 7 -n 5

Converter

./bench/bin/converter [options]
Option Description
-f <input> Input file
-s Symmetrize input
-o <id> Apply reordering algorithm
-b <file> Output serialized graph (.sg)
-e <file> Output edge list (.el)
-p <file> Output Matrix Market format (.mtx)
-y <file> Output Ligra format (.ligra)
-w Make output weighted (.wel/.wsg)
-x <file> Output reordered labels as text (.so)
-q <file> Output reordered labels as binary (.lo)
-V <file> Output separate CSR array files (.out_degree/.out_neigh/.offset)

Examples:

# Convert to binary format
./bench/bin/converter -f graph.el -s -b graph.sg

# Use converted graph
./bench/bin/pr -f graph.sg -n 5

Environment Variables

Thread Control

# Set number of OpenMP threads
export OMP_NUM_THREADS=8
./bench/bin/pr -f graph.el -s -n 5

AdaptiveOrder

Historical deterministic low-reuse policy:

./bench/bin/bfs -f graph.sg -s \
  -o '14:_:_:_:allkernel-lowreuse-rule:best-endtoend:1' -n 3

The final field is the declared mapping reuse count. This interface remains available for compatibility. Controlled runs should prefer explicit Algorithm-12 compositions and include ORIGINAL. See AdaptiveOrder.

Historical model-emulation modes can use:

export PERCEPTRON_WEIGHTS_FILE=/path/to/weights.json

Those modes are offline compatibility surfaces.

NUMA Binding

# Bind to NUMA node 0
numactl --cpunodebind=0 --membind=0 ./bench/bin/pr -f graph.el -s -n 5

Output Format

Standard Output

Loading graph from graph.el...
Graph has N nodes and M edges
Reordering with HUBCLUSTERDBG...

Trial   Time(s)
1       X.XXXX
2       X.XXXX
3       X.XXXX
4       X.XXXX
5       X.XXXX

Average: X.XXXX seconds
Std Dev: X.XXXX seconds

With Verification

Loading graph from graph.el...
...
Verification: PASSED

BFS Output (includes throughput)

Source: 0
Trial   Time(s)   Edges Visited   MTEPS
1       X.XXXX    ...             ...
2       X.XXXX    ...             ...
3       X.XXXX    ...             ...

Average: X.XXXX seconds, XX.X MTEPS

Common Command Patterns

Quick Test

./bench/bin/pr -f scripts/test/graphs/tiny/tiny.el -s -n 1

Compare Algorithms

for algo in 0 7 12 14 15; do
    echo "=== Algorithm $algo ==="
    ./bench/bin/pr -f graph.el -s -o $algo -n 3
done

Run All Benchmarks

for bench in pr pr_spmv bfs cc cc_sv sssp bc tc; do
    echo "=== $bench ==="
    ./bench/bin/$bench -f graph.el -s -o 7 -n 3
done

Batch Processing

for graph in graphs/*.el; do
    echo "=== $graph ==="
    ./bench/bin/pr -f "$graph" -s -o 7 -n 3 | tail -2
done

Exit Codes

Code Meaning
0 Success
1 General error
-1 Argument parsing failed
Other System error

Python Script Options (graphbrew_experiment.py)

See Python-Scripts for complete script documentation and module reference.

Key options summary:

Category Key Options
Pipeline --full, --train, --train-iterative, --train-batched, --phase PHASE
Size/Resources --size small|medium|large, --auto, --max-memory GB
Speed --quick, --skip-cache, --skip-expensive, --skip-slow
Variants --all-variants, --rabbit-variants LIST, --gorder-variants LIST, --graphbrew-variants LIST, --resolution VALUE
Offline models --train, --eval-weights (historical research path)
Labels --precompute, --generate-maps, --use-maps
Validation --brute-force, --validation-benchmark NAME
Dependencies --check-deps, --install-deps, --install-boost
Testing --test [FILTER], --evaluate
# Quick examples
python3 scripts/graphbrew_experiment.py --full --size small --auto --quick
python3 scripts/graphbrew_experiment.py --train --size medium --auto --precompute
python3 scripts/graphbrew_experiment.py --brute-force --validation-benchmark bfs

# Testing & evaluation
python3 scripts/graphbrew_experiment.py --test                # Run make check
python3 scripts/graphbrew_experiment.py --test gorder          # make check with pytest filter
python3 scripts/graphbrew_experiment.py --evaluate             # Model × Criterion analysis

eval_weights

Trains weights and simulates C++ scoring to report accuracy/regret. See Python-Scripts#weight-evaluation---eval-weights.

python3 scripts/graphbrew_experiment.py --eval-weights  # No arguments needed

Tips

  1. Always use -s for undirected graphs
  2. Use -n 5 or more for reliable timing
  3. Start with -o 0 as baseline
  4. Benchmark -o 0, -o 5, and -o 8:csr before choosing a policy
  5. Verify first run with -v to check correctness

← Back to Home | Configuration Files →

Clone this wiki locally