tempest-rw 0.0.1

GPU-accelerated temporal random walks on streaming graphs

Tempest

GPU-accelerated library for streaming temporal random walks. Walks follow a temporal graph's edges forward or backward in time under configurable bias (uniform, linear, exponential, reservoir-exponential, or temporal Node2Vec), with a sliding window that evicts old edges as new ones arrive. Edges may optionally carry a float feature vector that stays in sync with the edge store and is returned per hop alongside walks.

Distributed on PyPI as tempest-rw (the tempest name was already taken). The Python import name is still tempest — i.e. pip install tempest-rw, then import tempest.

Documentation

• C++ API (Doxygen) →
• Python API (pdoc) →

Installation

pip install tempest-rw

Or from a local checkout:

pip install .

Requires CMake ≥ 3.24, a C++17 compiler, and pybind11. A CUDA toolkit is optional; without it the package builds CPU-only.

To disable the CUDA backend at build time:

TEMPEST_DISABLE_CUDA=1 pip install .

Quick Start

One import, one class, one object:

from tempest import Tempest
import numpy as np

t = Tempest(is_directed=True, use_gpu=True)

t.add_edges(
    np.array([0, 1, 2], dtype=np.int32),
    np.array([1, 2, 3], dtype=np.int32),
    np.array([100, 200, 300], dtype=np.int64),
)

walks = t.get_walks(
    max_walk_len=10,
    num_walks_per_node=5,
    walk_bias="ReservoirExponential",
    direction="Forward",
    seed=42,
)
print(walks["nodes"].shape)           # (num_walks, max_walk_len)
print(walks["timestamps"].shape)      # (num_walks, max_walk_len)
print(walks["walk_lens"].shape)       # (num_walks,)
print(walks["edge_features"])         # None when no features were attached

Unused positions in nodes and timestamps are padded with -1. When edge features are attached at add_edges time they come back resolved per hop as walks["edge_features"] — see Edge Features (Optional) below.

Other entry points:

• t.get_walks_for_nodes(node_ids, ...) — one walk per entry in node_ids.
• t.get_walks_for_last_batch(...) — walks starting only from the nodes touched by the most recent add_edges call.

Introspection:

t.edge_count()           # active edges in the window
t.node_count()           # active nodes
t.get_node_ids()         # numpy int32 array
t.get_edges()            # dict: {"sources", "targets", "timestamps"}
t.feature_dim            # 0 if no features attached
t.is_directed
t.use_gpu
t.max_time_capacity
t.enable_node2vec
t.clear()                # wipe edges, features, and last-batch tracking

Walk Bias Types

Bias	Description
Uniform	Equal probability across valid timestamp groups.
Linear	Triangular probability, linear in group index.
ExponentialIndex	Exponential probability via inverse CDF over group index.
ReservoirExponential	Temporal exponential bias via Efraimidis-Spirakis reservoir sampling (zero precomputed weights).
TemporalNode2Vec	Structural (p, q) bias combined with temporal reservoir draw; pass enable_node2vec=True + node2vec_p + node2vec_q at construction time.

Edge Features (Optional)

Every edge can carry a fixed-size float feature vector. Features are stored CPU-side regardless of use_gpu and are never read during walk generation — they exist purely as a lookup table. Tempest keeps them in sync with the edge arrays across ingest-time sort/merge and sliding-window eviction, and get_walks / get_walks_for_nodes / get_walks_for_last_batch return them already resolved for every hop of every walk:

t = Tempest(is_directed=True, use_gpu=True)

sources    = np.array([0, 1, 2], dtype=np.int32)
targets    = np.array([1, 2, 3], dtype=np.int32)
timestamps = np.array([100, 200, 300], dtype=np.int64)
features   = np.array([[1.0, 2.0],
                       [3.0, 4.0],
                       [5.0, 6.0]], dtype=np.float32)  # [num_edges, feature_dim]

t.add_edges(sources, targets, timestamps, features)
assert t.feature_dim == 2

walks = t.get_walks(max_walk_len=5, num_walks_per_node=10, walk_bias="Uniform")
walks["edge_features"]         # float32, shape (num_walks, max_walk_len - 1, 2)
# Each row [w, i] is the feature vector of the edge traversed from
# nodes[w, i] to nodes[w, i + 1]. Padding slots past the walk's length are
# zero rows. When no features were attached, walks["edge_features"] is None.

Rules:

• The first add_edges call pins feature_dim. Every subsequent call must match: all-with-features or all-without, same feature_dim. Switching modes mid-stream raises.
• t.clear() wipes features and resets the schema, so the next add_edges may pick a new feature_dim.
• Features accept either a 2D [num_edges, feature_dim] float32 array or a flat 1D array of length num_edges * feature_dim.

Streaming API

t = Tempest(is_directed=True, max_time_capacity=3600)

for batch in stream_of_batches():
    t.add_edges(batch.sources, batch.targets, batch.timestamps)
    fresh_walks = t.get_walks_for_last_batch(max_walk_len=10, num_walks_per_node=1)

max_time_capacity defines the sliding-window length in timestamp units. After every batch, edges older than latest_timestamp - max_time_capacity are evicted and the temporal index is rebuilt. get_walks_for_last_batch starts walks only from the nodes touched by the most recent add_edges call — sources only for directed forward walks, targets only for directed backward walks, and the union of both for undirected graphs.

Building from Source

mkdir build && cd build
cmake .. -DTEMPEST_BUILD_TESTS=ON
cmake --build . -j
ctest --output-on-failure

Key CMake options:

• -DTEMPEST_ENABLE_CUDA=ON|OFF — build with/without the GPU backend.
• -DTEMPEST_BUILD_PYTHON=ON|OFF — build the pybind11 module.
• -DTEMPEST_BUILD_TESTS=ON|OFF — build the C++ test suite.
• -DTEMPEST_BUILD_BENCH=ON|OFF — build the CSV-emitting benchmarks.