Temporal encoding for HGTConv

[KilianZimmerer]

This PR adds support for Relative Temporal Encoding (RTE) to the HGTConv layer, as described in the original "Heterogeneous Graph Transformer" paper.

Description of Changes

use_RTE flag: A new boolean argument use_RTE is added to the HGTConv constructor to enable or disable temporal encoding. When enabled, it initializes a PositionalEncoding module.

New forward argument: The forward method now accepts an optional edge_time_diff_dict. This dictionary should contain a 1D tensor of time differences (∆T) for each edge type, which serves as the input to the encoding function.

Input Validation: A new _validate_inputs helper function has been added to ensure that if use_RTE is enabled, the edge_time_diff_dict is provided and contains a time difference tensor for every edge type. It also warns the user if they provide time data when use_RTE is disabled.

RTE Application: In the message function, the calculated temporal encoding (temporal_features) is added to the key (k_j) and value (v_j) vectors of the source nodes. This injects the temporal information directly into the attention mechanism.

Implementation Note

This implementation adds temporal encoding to the key (k_j) and value (v_j) vectors after their projection (a deviation from the paper) to preserve the efficient, parallelized node-level computation, which would otherwise become a much slower, edge-specific operation.

Tests Added

Tests have been added to validate this feature:

• Unit tests for correctness (sensitivity, edge cases, error handling).
• A behavioral test to confirm that the model can learn a purely time-dependent rule when RTE is enabled.

References

Hu, Z., Dong, Y., Wang, K., & Sun, Y. (2020). Heterogeneous Graph Transformer.
arXiv link: https://arxiv.org/abs/2003.01332