Class tguf::TGStore

ClassList > tguf > TGStore

Abstract interface for temporal graph storage. Implementations can be purely in-memory or memory-mapped TGUF files.

• #include <tguf.h>

Classes

Type	Name
struct	IndexRange A contiguous slice of the graph (e.g., training split).

Public Types

Type	Name
enum	NegStrategy Determines how negative samples are generated during get_batch() .

Public Functions

Type	Name
virtual auto	edge_count () const = 0
virtual auto	gather_msgs (const torch::Tensor & e_id) const = 0 Performs a vectorized random-access gather of edge messages.
virtual auto	gather_node_feats (const torch::Tensor & n_id) const = 0 Performs a vectorized random-access gather of node features.
virtual auto	gather_timestamps (const torch::Tensor & e_id) const = 0 Performs a vectorized random-access gather of edge timestamps.
virtual auto	get_batch (std::size_t start, std::size_t size, NegStrategy strategy=NegStrategy::None, torch::Device device=torch::kCPU) const = 0 Retrieves a zero-copy slice of the graph.
virtual auto	get_edge_cutoff_for_label_event (std::size_t l_id) const = 0 Retrieves the maximum edge_id that can be safely processed before a label.
virtual auto	get_label_event (std::size_t l_id, torch::Device device=torch::kCPU) const = 0 Retrieves the metadata and target for a specific label event.
virtual auto	label_count () const = 0
virtual auto	label_dim () const = 0
virtual auto	msg_dim () const = 0
virtual auto	node_count () const = 0
virtual auto	node_feat_dim () const = 0
virtual auto	test_label_split () const = 0
virtual auto	test_split () const = 0
virtual auto	train_label_split () const = 0
virtual auto	train_split () const = 0
virtual auto	val_label_split () const = 0
virtual auto	val_split () const = 0
virtual	~TGStore () = default

Public Static Functions

Type	Name
auto	from_memory (const Batch & edges, const std::optional< torch::Tensor > & node_feats=std::nullopt, const std::optional< torch::Tensor > & label_n_id=std::nullopt, const std::optional< torch::Tensor > & label_time=std::nullopt, const std::optional< torch::Tensor > & label_target=std::nullopt, std::optional< std::size_t > val_start=std::nullopt, std::optional< std::size_t > test_start=std::nullopt) Factory method for a high-speed, purely RAM-based store.
auto	from_tguf (const std::string & path, std::optional< std::size_t > val_start=std::nullopt, std::optional< std::size_t > test_start=std::nullopt) Factory method for memory-mapped storage from a TGUF file. Supports datasets larger than available system RAM.

Public Types Documentation

enum NegStrategy

Determines how negative samples are generated during get_batch() .

enum tguf::TGStore::NegStrategy {
    None,
    Random,
    PreComputed
};

---

Public Functions Documentation

function edge_count

virtual auto tguf::TGStore::edge_count () const = 0

---

function gather_msgs

Performs a vectorized random-access gather of edge messages.

virtual auto tguf::TGStore::gather_msgs (
    const torch::Tensor & e_id
) const = 0

*

Parameters:

• e_id Tensor of edge indices [num_edges].

Returns:

torch::Tensor of messages [num_edges, msg_dim].

---

function gather_node_feats

Performs a vectorized random-access gather of node features.

virtual auto tguf::TGStore::gather_node_feats (
    const torch::Tensor & n_id
) const = 0

*

Parameters:

• n_id Tensor of node indices [num_nodes].

Returns:

torch::Tensor of features [num_nodes, node_feat_dim].

---

function gather_timestamps

Performs a vectorized random-access gather of edge timestamps.

virtual auto tguf::TGStore::gather_timestamps (
    const torch::Tensor & e_id
) const = 0

*

Parameters:

• e_id Tensor of edge indices [num_edges].

Returns:

torch::Tensor of timestamps [num_edges].

Note:

Optimized for memory-mapped I/O; performance may vary based on disk locality.

---

function get_batch

Retrieves a zero-copy slice of the graph.

virtual auto tguf::TGStore::get_batch (
    std::size_t start,
    std::size_t size,
    NegStrategy strategy=NegStrategy::None,
    torch::Device device=torch::kCPU
) const = 0

*

Parameters:

• start The starting edge ID.
• size The number of edges to include.
• strategy The negative sampling strategy to apply.
• device The torch::Device to materialize the batch on.

---

function get_edge_cutoff_for_label_event

Retrieves the maximum edge_id that can be safely processed before a label.

virtual auto tguf::TGStore::get_edge_cutoff_for_label_event (
    std::size_t l_id
) const = 0

** To prevent information leakage (look-ahead bias), the model state should only be updated with edges occurring before the timestamp of the label event l_id. *

Parameters:

• l_id The index of the label event.

Returns:

The upper-bound edge_id (exclusive) for model state updates.

---

function get_label_event

Retrieves the metadata and target for a specific label event.

virtual auto tguf::TGStore::get_label_event (
    std::size_t l_id,
    torch::Device device=torch::kCPU
) const = 0

*

Parameters:

• l_id The index of the label event.
• device The torch::Device to materialize data on.

Returns:

A LabelEvent containing affected node IDs and target values.

---

function label_count

virtual auto tguf::TGStore::label_count () const = 0

---

function label_dim

virtual auto tguf::TGStore::label_dim () const = 0

---

function msg_dim

virtual auto tguf::TGStore::msg_dim () const = 0

---

function node_count

virtual auto tguf::TGStore::node_count () const = 0

---

function node_feat_dim

virtual auto tguf::TGStore::node_feat_dim () const = 0

---

function test_label_split

virtual auto tguf::TGStore::test_label_split () const = 0

---

function test_split

virtual auto tguf::TGStore::test_split () const = 0

---

function train_label_split

virtual auto tguf::TGStore::train_label_split () const = 0

---

function train_split

virtual auto tguf::TGStore::train_split () const = 0

---

function val_label_split

virtual auto tguf::TGStore::val_label_split () const = 0

---

function val_split

virtual auto tguf::TGStore::val_split () const = 0

---

function ~TGStore

virtual tguf::TGStore::~TGStore () = default

---

Public Static Functions Documentation

function from_memory

Factory method for a high-speed, purely RAM-based store.

static auto tguf::TGStore::from_memory (
    const Batch & edges,
    const std::optional< torch::Tensor > & node_feats=std::nullopt,
    const std::optional< torch::Tensor > & label_n_id=std::nullopt,
    const std::optional< torch::Tensor > & label_time=std::nullopt,
    const std::optional< torch::Tensor > & label_target=std::nullopt,
    std::optional< std::size_t > val_start=std::nullopt,
    std::optional< std::size_t > test_start=std::nullopt
) 

---

function from_tguf

Factory method for memory-mapped storage from a TGUF file. Supports datasets larger than available system RAM.

static auto tguf::TGStore::from_tguf (
    const std::string & path,
    std::optional< std::size_t > val_start=std::nullopt,
    std::optional< std::size_t > test_start=std::nullopt
) 

---

---

The documentation for this class was generated from the following file include/tguf.h