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, and engine time

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 one million stored edges; otherwise it starts with the CPU. Individual algorithms can override that candidate when another path is more appropriate.

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.

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() reports the operation, chosen path, iteration count, and engine time. 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.
• 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.

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.