metal-graph

Fast graph analytics for Apple Silicon.

metal-graph is a Python and C library for ranking, searching, and exploring graphs on a Mac. Build a graph once from NumPy arrays, then run PageRank, HITS hub/authority scoring, batched personalized PageRank, breadth-first search, neighborhood extraction, and connected-components analysis through one consistent API.

The library uses the Metal GPU for work that benefits from it and a threaded CPU path for smaller jobs. That choice is automatic by default, so using metal-graph does not require Metal knowledge or device-management code.

It is particularly useful for:

• knowledge-graph and retrieval pipelines;
• entity ranking, recommendations, and repo maps;
• graph-backed agent memory and neighborhood lookup;
• local analysis of large graphs on Apple Silicon.

Why use metal-graph?

• A small, practical API. Inputs and outputs are NumPy arrays, and integer or string IDs are supported.
• Useful graph operations included. PageRank, HITS, batched PPR with top-k, BFS, sparse BFS, bounded k-hop extraction, and weakly connected components are available today.
• Good performance across different query sizes. Large traversals can use the GPU, while tiny reachable components can stay on the CPU and avoid GPU launch overhead.
• Transparent execution. mg.last_run_info() reports what ran, where it ran, and how long the engine took.
• Tested against established libraries. More than 1,000 Python cases cover correctness, properties, and integration behavior. CI also checks the C API, wheels, and GPU-required jobs.

The main interface is Python (metal_graph, with NumPy input and output). A stable C API is available in include/mg.h, but it is not bundled into the Python wheel; install it separately from source with CMake.

Requirements

• macOS 14 or newer
• Apple Silicon with an M1 or newer
• CPython 3.10–3.14

Installing a prebuilt wheel does not require a compiler. Building from source, including installing the C API, additionally requires CMake 3.24 or newer and Xcode with the Metal compiler.

Install

Install the prebuilt wheel from PyPI:

python3 -m pip install metal-graph
python3 -c "import metal_graph as mg; print(mg.__version__, mg.has_gpu())"

No compiler or Metal setup is needed for the wheel. Source builds, development setup, native tests, wheel validation, and C API installation are covered in CONTRIBUTING.md.

Quick start

import numpy as np
import metal_graph as mg

# Build an immutable directed graph.
src = np.array([0, 0, 1, 2], dtype=np.uint32)
dst = np.array([1, 2, 2, 3], dtype=np.uint32)
G = mg.Graph.from_edges(
    src,
    dst,
    directed=True,
    num_vertices=4,
)

# Rank every vertex.
rank = mg.pagerank(G)
hubs, authorities = mg.hits(G)

# Explore from vertex 0.
dist, parent = mg.bfs(G, sources=[0], direction="out")
vertices, sparse_dist, sparse_parent = mg.bfs(
    G,
    sources=[0],
    direction="out",
    output="sparse",
)
neighbors, edge_ids = mg.k_hop(
    G,
    seeds=[0],
    k=2,
    direction="both",
)

# Find weakly connected components.
components = mg.experimental.wcc(G)

For a batch of personalized ranking queries, pack the seeds using offsets:

seeds = np.array([0, 2], dtype=np.uint32)
seed_weights = np.ones(2, dtype=np.float32)
seed_offsets = np.array([0, 1, 2], dtype=np.uint64)

ids, scores = mg.ppr_topk(
    G,
    seeds,
    seed_weights,
    seed_offsets,
    k=4,
)
# ids and scores both have shape (number_of_queries, k)

By default, metal-graph chooses the execution path for each call:

mg.set_execution("auto")       # "auto", "gpu", or "cpu"
mg.last_run_info()             # op, path, iterations, engine time, HITS status

The notebooks/ directory contains complete examples for the core API, batched PPR retrieval, and low-latency BFS.

Available operations

• Graph.from_edges(...) builds an immutable weighted or unweighted graph.
• pagerank(...) returns a score for every vertex.
• hits(...) returns L1-normalized hub and authority scores.
• ppr_topk(...) answers a batch of personalized PageRank queries and returns only the highest-scoring vertices.
• bfs(...) returns dense distances and parents, or compact results with output="sparse".
• k_hop(...) finds a bounded neighborhood and its induced input edges.
• experimental.wcc(...) labels weakly connected components.

Performance

Unless stated otherwise, the results below were measured on an Apple M4 Max running macOS 26.2. Timings cover the Python call through the returned result, so they include normal API overhead. Lower is better.

Most cells come from source commit a4a8bc; the HippoRAG PPR cell marked ² comes from the isolated artifact at source commit 7afb4b2. metal-graph cells are medians of 20 warm calls. External baselines generally use four timed calls after one warm-up, with additional samples for sub-2 ms BFS measurements. The full benchmark report contains p95 values, package versions, and methodology.

metal-graph latency

HITS on Apple Metal

The focused HITS run used the same Apple M4 Max on macOS 26.6.2, with an absolute L1 convergence target of 1e-5 and 20 warm calls per implementation. Every baseline shown below passed a score-agreement check against the fp64 reference. The complete HITS benchmark report includes p95 and cold timings, setup costs, package versions, methodology, and source provenance.

SciPy's matrix coalesces the KG's 2.0M repeated input links into 305,667 weighted nonzero positions, while metal-graph retains every parallel link. This gives SciPy a substantial workload advantage on that row and makes its 2.67× result the most conservative comparison.

Comparison with CPU graph libraries

Each cell shows metal-graph vs external median (speedup). These are end-to-end API comparisons, not claims that every library performs identical internal work.

The rustworkx BFS adapter returns the same dense dist + parent shape as metal-graph. PageRank uses the faster completed igraph or rustworkx call for each dataset, but solver and iteration behavior are not fully normalized. WCC compares the corresponding operation, although the external libraries return their native component representation. Treat the PageRank and WCC ratios as practical API-level context. The recorded versions were rustworkx 0.18.0 and igraph 1.0.0.

Performance varies with the graph and operation. For example, HippoRAG WCC and source-0 BFS measured 3.2× and 4.8× faster, while Orkut WCC measured 1.21×. Using the benchmark's historical gate definitions, 17 of 18 full-run PageRank, high-degree BFS, and WCC cells exceeded the documented 2× target. The source-0 BFS column above is not that exact gate matrix.

Contextual personalized PageRank comparison

The igraph query loop uses PRPACK and cannot be pinned to metal-graph's iteration count. This table is useful end-to-end context, not an identical-work comparison.

How execution is chosen

mode="auto" is intended for normal use. The planner starts with the GPU when a Metal device is available and the graph has at least a per-operation number of stored edges: one million for pagerank (including personalized PageRank), hits, ppr_topk, bfs, and wcc; otherwise it starts with the CPU. By default, k_hop starts with the CPU at every size; MG_E_GPU_MIN_KHOP or MG_E_GPU_MIN can override that default. Its induced-edge extraction runs on the host on either path. Individual algorithms can override the planner's candidate when another path is more appropriate.

PageRank and HITS retain their original fp64 CPU arithmetic below one million stored edges. Lowering their GPU thresholds explicitly opts into fp32 GPU arithmetic, changing the precision of the computation.

BFS, for example, first tries a bounded serial traversal. If the reachable component fits within its vertex and scanned-edge caps, the CPU answers the query directly. If it does not fit, the partial attempt is discarded and the regular CPU or GPU path runs instead. Each reached vertex's adjacency is charged against the edge cap when the vertex is discovered, so an attempt that cannot fit is usually abandoned early. The caps are larger when the fallback is the GPU than when it is the threaded CPU path.

ppr_topk applies the same idea per query. When the vertices reachable from a query's seeds along outgoing edges fit within the vertex and scanned-edge caps, every other vertex has an exact score of zero, so the CPU solves that query exactly in fp64 on the reachable set alone, with the same summation order (including the fixed 16,384-edge tiles of rows with that many incoming edges), audit rule, and tie order as the full CPU path. Dropping the unreachable zero-contribution edges therefore preserves the dense result exactly. To locate those tiles, the first auto- or CPU-mode ppr_topk call on a directed graph builds a small cached index of the large rows' tile boundaries (up to three parallel passes over the edges). Queries that do not fit run on the planned CPU or GPU path; in a mixed batch only those rows go to the GPU, so their scores carry the usual GPU float32 tolerance while the others are fp64. last_run_info() reports path="cpu" when every query in the batch was answered this way, and the planned path otherwise. Forced GPU mode skips the attempt.

You can override the planner when testing or profiling:

mg.set_execution("gpu")   # require the GPU path
mg.set_execution("cpu")   # require the CPU path
mg.set_execution("auto")  # restore automatic selection

mg.last_run_info() returns a snapshot of the last recorded algorithm run on the calling thread, including its chosen path, iteration count, and engine time. After HITS, it also distinguishes convergence from exhaustion of the iteration budget:

hubs, authorities = mg.hits(G, tol=1e-5, max_iter=100)
info = mg.last_run_info()  # Read before running another algorithm.
if info["stop_reason"] == "max_iter":
    print("Iteration budget reached; scores may need more iterations.")
print(info["converged"], info["stop_reason"], info["final_delta_l1"])

converged is a boolean for HITS, stop_reason is "converged", "max_iter", or "empty_graph", and final_delta_l1 is the last measured L1 change in the hub vector. Other operations, and the initial state before an operation, report None, "not_applicable", and None respectively; these fields do not report PageRank or PPR convergence. A later recorded run replaces the current metadata, but a previously returned dictionary remains unchanged. The C API exposes the same status through mg_last_run_convergence(); see the C example. Forced GPU mode raises an error if no device is available.

Graph IDs and result behavior

External integer or string IDs are mapped to dense user indices in np.unique order. Algorithm inputs and outputs use those user indices. Use G.index_of(ids) to map external IDs to indices and G.external_ids[index] to map back. G.external_ids returns a detached, read-only NumPy snapshot, so changing a caller-owned copy cannot alter the graph's ID mapping.

Graphs are immutable after construction. Duplicate edges and self-loops are kept, and PageRank counts them. Non-finite or negative weights are rejected. Undirected graphs are symmetrized internally, while G.num_edges continues to report the number of input edges.

The most important result conventions are:

• PageRank follows NetworkX-compatible weighted normalization and dangling mass handling. max_iter is a budget: metal-graph returns the current result when it is reached, while NetworkX raises.
• HITS returns (hubs, authorities) with separate L1-normalized float32 vectors. It ignores edge weights, counts parallel edges separately, and returns zeros for edgeless graphs. max_iter is a budget: scores are returned even when it is exhausted; inspect last_run_info() for the stopping reason.
• ppr_topk normalizes seed weights, combines duplicate seeds, returns deterministic top-k ordering, and pads with id=-1, score=0 when k > V.
• BFS supports direction="out", "in", or "both". Unreachable distances and missing parents are -1. Parent choice can vary when several same-depth parents are valid on a parallel path.
• Sparse BFS returns aligned (vertices, dist, parent) arrays in ascending user-index order.
• k_hop returns ascending vertex indices and original input edge IDs. max_vertices and max_edges bound result size, not worst-case runtime, scanned edges, or scratch memory. Use as_graph=True to materialize the returned neighborhood as a new graph.
• WCC treats directed edges as undirected and numbers components by their first appearance in user-index order.

Version 0.1.2 changes CPU floating-point summation: PageRank and PPR scores can differ from 0.1.1 in the last float32 bit, and PPR near-ties can change order. Large adjacency rows can also change HITS scores through tiled fp64 summation. These ranking results remain deterministic across CPU thread counts; see the 0.1.2 release notes for details.

Current limits

• The library currently supports V, E < 2^31; graph values are fp32 and graph IDs are int32 internally.
• Graphs are immutable snapshots rather than streaming or mutable graphs.
• HITS materializes and caches the reverse CSR for directed graphs, so its first call adds a second adjacency-sized structure to the graph snapshot.
• direction="both" BFS on directed graphs and capped k_hop run on the deterministic CPU path.
• Batched GPU PPR keeps the CSR plus an eight-query tile in memory. The dominant tile state uses roughly 100 bytes per vertex. Oversized workloads raise a descriptive working-set error; mode="cpu" avoids that GPU limit.
• GPU top-k selection uses its bit-identical CPU fallback for tiny graphs (V < 4096), k >= V, k > 4096, and degenerate tie floods.
• Typed and temporal k_hop filters are reserved for a future release; edge_types= and time_range= currently raise NotImplementedError.

Benchmarks and reproducibility

bench/run.py --suite v01 runs the full matrix against igraph, rustworkx, SciPy, and NetworkX. It uses synthetic RMAT and knowledge-graph-shaped data plus SHA-pinned SNAP datasets, which are downloaded only with --fetch. See the benchmark guide for commands and artifact format.

New published performance claims require a matched, checked-in JSON and rendered-report pair from a physical run. The disclosed exception is the reconstructed RMAT-18 through LiveJournal data described above; only Orkut has a matched pair for the later full-suite values.

Project resources

• Example notebooks
• Benchmark guide
• Contribution and development guide
• C API
• v0.1 implementation and design rationale

Roadmap

Possible future additions include label propagation, core number, similarity top-k, typed and temporal neighborhood filters, MLX device-resident results, and a NetworkX backend preview. Louvain and Leiden community detection are longer-term candidates.

License

Apache-2.0 (LICENSE). The vendored metal-cpp library is Apache-2.0, © Apple Inc.; see THIRD_PARTY_NOTICES.md.