dhg

Load Structure

dhg.load_structure(file_path)[source]

Load a DHG’s structure from a file. The supported structure includes: Graph, DiGraph, BiGraph, Hypergraph.

Parameters: file_path (Union[str, Path]) – The file path to load the DHG’s structure.

Low-Order Structures

Base Class

class dhg.BaseGraph(num_v, e_list=None, e_weight=None, extra_selfloop=False, device=torch.device)[source]

The BaseGraph class is the base class for all graph structures.

Parameters

num_v (int) – The number of vertices.
e_list (Union[List[int], List[List[int]]], optional) – Edge list. Defaults to None.
e_weight (Union[float, List[float]], optional) – A list of weights for edges. Defaults to None.
extra_selfloop (bool, optional) – Whether to add extra self-loop to the graph. Defaults to False.
device (torch.device, optional) – The device to store the graph. Defaults to torch.device('cpu').

abstract property A: Return the sparsed adjacency matrix of the graph. Format torch.sparse_coo.

add_edges(e_list, e_weight=None, merge_op='mean')[source]

Add edges to the graph.

Parameters

e_list (Union[List[int], List[List[int]]]) – Edge list.
e_weight (Union[float, List[float]], optional) – A list of weights for edges. Defaults to None.
merge_op (str) – The merge operation for the conflicting edges. If set to None, the default merge operation specified in Graph Construction is used. Defaults to None.

add_extra_selfloop()[source]: Add extra selfloops to the graph.

clear()[source]: Remove all edges and caches from the graph.

abstract clone()[source]: Clone the graph.

abstract draw(**kwargs)[source]: Draw the structure.

abstract drop_edges(drop_rate, ord='uniform')[source]

Randomly drop edges from the graph. This function will return a new graph with non-dropped edges.

Parameters

drop_rate (float) – The drop rate of edges.
ord (str) – The order of dropping edges. Currently, only 'uniform' is supported. Defaults to uniform.

property e: Return the edge list and weight list in the graph.

abstract static from_adj_list(num_v, adj_list, extra_selfloop=False)[source]

Construct a graph from the adjacency list. Each line in the adjacency list has two components. The first element in each line is the source vertex index, and the rest elements are the target vertex indices that connected to the source vertex.

Note

This function can only construct unweighted graph.

Parameters

num_v (int) – The number of vertices.
adj_list (List[List[int]]) – Adjacency list.
extra_selfloop (bool) – Whether to add extra self-loop. Defaults to False.

Returns

The constructed graph.

Return type

BaseGraph

abstract static from_state_dict(state_dict)[source]

Load the DHG’s graph structure from the state dict.

Parameters: state_dict (dict) – The state dict to load the DHG’s graph.

abstract static load(file_path)[source]

Load the DHG’s graph structure from a file.

Parameters: file_path (Union[str, Path]) – The file path to load the DHG’s graph structure from.

property num_e: Return the number of edges in the graph.

property num_v: Return the number of vertices in the graph.

abstract remove_edges(e_list)[source]

Remove edges from the graph.

Parameters: e_list (List[List[int]]) – Edge list to be removed.

remove_extra_selfloop()[source]: Remove extra selfloops from the graph.

remove_selfloop()[source]: Remove all selfloops from the graph.

abstract save(file_path)[source]

Save the DHG’s graph structure to a file.

Parameters: file_path (Union[str, Path]) – The file path to store the DHG’s graph structure with DHG format.

smoothing(X, L, lamb)[source]

Spectral-based smoothing.

\[X_{smoothed} = X + \lambda \mathcal{L} X\]

Parameters

X (torch.Tensor) – The vertex feature matrix. Size \((|\mathcal{V}|, C)\).
L (torch.Tensor) – The Laplacian matrix with torch.sparse_coo_tensor format. Size \((|\mathcal{V}|, |\mathcal{V}|)\).
lamb (float) – \(\lambda\), the strength of smoothing.

abstract property state_dict: Get the state dict of the graph.

to(device)[source]

Move the graph to the specified device.

Parameters: device (torch.device) – The device to store the graph.

property v: Return vertices of the graph.

abstract v2v(X, aggr='mean', e_weight=None)[source]

Message passing from vertex to vertex on the graph structure.

Parameters

X (torch.Tensor) – Vertex feature matrix. Size: \((|\mathcal{V}|, C)\).
aggr (str, optional) – Aggregation function for neighbor messages, which can be 'mean', 'sum', or 'softmax_then_sum'. Default: 'mean'.
e_weight (torch.Tensor, optional) – The edge weight vector. Size: \((|\mathcal{E}|,)\). Defaults to None.

abstract property vars_for_DL: Return a name list of available variables for deep learning in this type of graph.

Graph

class dhg.Graph(num_v, e_list=None, e_weight=None, extra_selfloop=False, merge_op='mean', device=torch.device)[source]

Bases: dhg.structure.base.BaseGraph

Class for graph (undirected graph).

Parameters

num_v (int) – The number of vertices.
e_list (Union[List[int], List[List[int]]], optional) – Edge list. Defaults to None.
e_weight (Union[float, List[float]], optional) – A list of weights for edges. Defaults to None.
extra_selfloop (bool, optional) – Whether to add extra self-loop to the graph. Defaults to False.
merge_op (str) – The operation to merge those conflicting edges, which can be 'mean', 'sum' or 'max'. Defaults to 'mean'.
device (torch.device, optional) – The device to store the graph. Defaults to torch.device('cpu').

property A: Return the adjacency matrix \(\mathbf{A}\) of the sample graph with torch.sparse_coo_tensor format. Size \((|\mathcal{V}|, |\mathcal{V}|)\).

property D_v: Return the diagnal matrix of vertex degree \(\mathbf{D}_v\) with torch.sparse_coo_tensor format. Size \((|\mathcal{V}|, |\mathcal{V}|)\).

property D_v_neg_1: Return the nomalized diagnal matrix of vertex degree \(\mathbf{D}_v^{-1}\) with torch.sparse_coo_tensor format. Size \((|\mathcal{V}|, |\mathcal{V}|)\).

property D_v_neg_1_2: Return the nomalized diagnal matrix of vertex degree \(\mathbf{D}_v^{-\frac{1}{2}}\) with torch.sparse_coo_tensor format. Size \((|\mathcal{V}|, |\mathcal{V}|)\).

property L: Return the Laplacian matrix \(\mathbf{L}\) of the sample graph with torch.sparse_coo_tensor format. Size \((|\mathcal{V}|, |\mathcal{V}|)\).

\[\mathbf{L} = \mathbf{D}_v - \mathbf{A}\]

property L_GCN: Return the GCN Laplacian matrix \(\mathcal{L}_{GCN}\) of the graph with torch.sparse_coo_tensor format. Size \((|\mathcal{V}|, |\mathcal{V}|)\).

\[\mathcal{L}_{GCN} = \mathbf{\hat{D}}_v^{-\frac{1}{2}} \mathbf{\hat{A}} \mathbf{\hat{D}}_v^{-\frac{1}{2}}\]

property L_rw: Return the random walk Laplacian matrix \(\mathcal{L}_{rw}\) of the graph with torch.sparse_coo_tensor format. Size \((|\mathcal{V}|, |\mathcal{V}|)\).

\[\mathcal{L}_{rw} = \mathbf{I} - \mathbf{D}_v^{-1} \mathbf{A}\]

property L_sym: Return the symmetric Laplacian matrix \(\mathcal{L}_{sym}\) of the graph with torch.sparse_coo_tensor format. Size \((|\mathcal{V}|, |\mathcal{V}|)\).

\[\mathcal{L}_{sym} = \mathbf{I} - \mathbf{D}_v^{-\frac{1}{2}} \mathbf{A} \mathbf{D}_v^{-\frac{1}{2}}\]

N_v(v_idx, hop=1)[source]

Return the k-hop neighbors of the vertex v_idx with torch.Tensor format.

Parameters

v_idx (int) – The index of the vertex.
hop (int) – The number of the hop.

add_edges(e_list, e_weight=None, merge_op='mean')[source]

Add edges to the graph.

Parameters

e_list (Union[List[int], List[List[int]]]) – Edge list.
e_weight (Union[float, List[float]], optional) – A list of weights for edges. Defaults to None.
merge_op (str) – The operation to merge those conflicting edges, which can be 'mean', 'sum' or 'max'. Defaults to 'mean'.

add_extra_selfloop()[source]: Add extra selfloops to the graph.

clear()[source]: Remove all edges in this graph.

clone()[source]: Clone the graph.

property deg_v: Return the degree list of each vertex in the graph.

draw(e_style='line', v_label=None, v_size=1.0, v_color='r', v_line_width=1.0, e_color='gray', e_fill_color='whitesmoke', e_line_width=1.0, font_size=1.0, font_family='sans-serif', push_v_strength=1.0, push_e_strength=1.0, pull_e_strength=1.0, pull_center_strength=1.0)[source]

Draw the graph structure. The supported edge styles are: 'line' and 'circle'.

Parameters

e_style (str) – The edge style. The supported edge styles are: 'line' and 'circle'. Defaults to 'line'.
v_label (list, optional) – A list of vertex labels. Defaults to None.
v_size (Union[float, list]) – The vertex size. If v_size is a float, all vertices will have the same size. If v_size is a list, the size of each vertex will be set according to the corresponding element in the list. Defaults to 1.0.
v_color (Union[str, list]) – The vertex color. If v_color is a str, all vertices will have the same color. If v_color is a list, the color of each vertex will be set according to the corresponding element in the list. Defaults to 'r'.
v_line_width (Union[str, list]) – The vertex line width. If v_line_width is a float, all vertices will have the same line width. If v_line_width is a list, the line width of each vertex will be set according to the corresponding element in the list. Defaults to 1.0.
e_color (Union[str, list]) –
The edge color. If e_color is a str, all edges will have the same color. If e_color is a list, the color of each edge will be set according to the corresponding element in the list. Defaults to 'gray'.
e_fill_color (Union[str, list]) – The edge fill color. If e_fill_color is a str, all edges will have the same fill color. If e_fill_color is a list, the fill color of each edge will be set according to the corresponding element in the list. Defaults to 'whitesmoke'. This argument is only valid when e_style is 'circle'.
e_line_width (Union[str, list]) – The edge line width. If e_line_width is a float, all edges will have the same line width. If e_line_width is a list, the line width of each edge will be set according to the corresponding element in the list. Defaults to 1.0.
font_size (int) – The font size. Defaults to 1.0.
font_family (str) – The font family. Defaults to 'sans-serif'.
push_v_strength (float) – The vertex push strength. Defaults to 1.0.
push_e_strength (float) – The edge push strength. Defaults to 1.0.
pull_e_strength (float) – The edge pull strength. Defaults to 1.0.
pull_center_strength (float) – The center pull strength. Defaults to 1.0.

drop_edges(drop_rate, ord='uniform')[source]

Randomly drop edges from the graph. This function will return a new graph with non-dropped edges.

Parameters

drop_rate (float) – The drop rate of edges.
ord (str) – The order of dropping edges. Currently, only 'uniform' is supported. Defaults to uniform.

property e: Return edges and their weights in the graph with (edge_list, edge_weight_list) format. i-th element in the edge_list denotes i-th edge, \([v_{src} \longleftrightarrow v_{dst}]\). i-th element in edge_weight_list denotes the weight of i-th edge, \(e_{w}\). The lenght of the two lists are both \(|\mathcal{E}|\).

property e_both_side: Return the list of edges including both directions.

property e_dst: Return the index vector \(\vec{e}_{dst}\) of destination vertices in the graph with torch.Tensor format. Size \((|\mathcal{E}|,)\).

property e_src: Return the index vector \(\vec{e}_{src}\) of source vertices in the graph with torch.Tensor format. Size \((|\mathcal{E}|,)\).

property e_weight: Return the weight vector \(\vec{e}_{weight}\) of edges in the graph with torch.Tensor format. Size \((|\mathcal{E}|,)\).

static from_adj_list(num_v, adj_list, extra_selfloop=False, device=torch.device)[source]

Construct a graph from the adjacency list. Each line in the adjacency list has two components. The first element in each line is the source vertex index, and the rest elements are the target vertex indices that connected to the source vertex.

Note

This function can only construct the unweighted graph.

Parameters

num_v (int) – The number of vertices.
adj_list (List[List[int]]) – Adjacency list.
extra_selfloop (bool) – Whether to add extra self-loop. Defaults to False.
device (torch.device) – The device to store the graph. Defaults to torch.device("cpu").

static from_hypergraph_clique(hypergraph, weighted=False, miu=1.0, device=torch.device)[source]

Construct a graph from a hypergraph with clique expansion refering to Higher Order Learning with Graphs paper.

Parameters

hypergraph (Hypergraph) – The source hypergraph.
weighted (bool, optional) – Whether to construct a weighted graph. Defaults to False.
miu (float, optional) – The parameter of clique expansion. Defaults to 1.0.
device (torch.device) – The device to store the graph. Defaults to torch.device("cpu").

static from_hypergraph_hypergcn(hypergraph, feature, with_mediator=False, remove_selfloop=True, device=torch.device)[source]

Construct a graph from a hypergraph with methods proposed in HyperGCN: A New Method of Training Graph Convolutional Networks on Hypergraphs paper .

Parameters

hypergraph (Hypergraph) – The source hypergraph.
feature (torch.Tensor) – The feature of the vertices.
with_mediator (str) – Whether to use mediator to transform the hyperedges to edges in the graph. Defaults to False.
remove_selfloop (bool) – Whether to remove self-loop. Defaults to True.
device (torch.device) – The device to store the graph. Defaults to torch.device("cpu").

static from_hypergraph_star(hypergraph, weighted=False, merge_op='sum', device=torch.device)[source]

Construct a graph from a hypergraph with star expansion refering to Higher Order Learning with Graphs paper.

Parameters

hypergraph (Hypergraph) – The source hypergraph.
weighted (bool, optional) – Whether to construct a weighted graph. Defaults to False.
merge_op (str) – The operation to merge those conflicting edges, which can be 'mean', 'sum' or 'max'. Defaults to 'sum'.
device (torch.device, optional) – The device to store the graph. Defaults to torch.device("cpu").

static from_state_dict(state_dict)[source]

Load the DHG’s graph structure from the state dict.

Parameters: state_dict (dict) – The state dict to load the DHG’s graph.

static load(file_path)[source]

Load the DHG’s graph structure from a file.

Parameters: file_path (Union[str, Path]) – The file path to load the DHG’s graph structure.

nbr_v(v_idx, hop=1)[source]

Return a vertex list of the k-hop neighbors of the vertex v_idx.

Parameters

v_idx (int) – The index of the vertex.
hop (int) – The number of the hop.

property num_e: Return the number of edges in the graph.

property num_v: Return the number of vertices in the graph.

remove_edges(e_list)[source]

Remove specified edges in the graph.

Parameters: e_list (Union[List[int], List[List[int]]]) – Edges to be removed.

remove_extra_selfloop()[source]: Remove extra selfloops from the graph.

remove_selfloop()[source]: Remove all selfloops from the graph.

save(file_path)[source]

Save the DHG’s graph structure to a file.

Parameters: file_path (Union[str, Path]) – The file path to store the DHG’s graph structure.

smoothing(X, L, lamb)[source]

Spectral-based smoothing.

\[X_{smoothed} = X + \lambda \mathcal{L} X\]

Parameters

X (torch.Tensor) – The vertex feature matrix. Size \((|\mathcal{V}|, C)\).
L (torch.Tensor) – The Laplacian matrix with torch.sparse_coo_tensor format. Size \((|\mathcal{V}|, |\mathcal{V}|)\).
lamb (float) – \(\lambda\), the strength of smoothing.

smoothing_with_GCN(X, drop_rate=0.0)[source]

Return the smoothed feature matrix with GCN Laplacian matrix \(\mathcal{L}_{GCN}\).

Parameters

X (torch.Tensor) – Vertex feature matrix. Size \((|\mathcal{V}|, C)\).
drop_rate (float) – Dropout rate. Randomly dropout the connections in adjacency matrix with probability drop_rate. Default: 0.0.

property state_dict: Get the state dict of the graph.

to(device)[source]

Move the graph to the specified device.

Parameters: device (torch.device) – The device to store the graph.

property v: Return the list of vertices.

v2v(X, aggr='mean', e_weight=None, drop_rate=0.0)[source]

Message passing from vertex to vertex on the graph structure.

Parameters

X (torch.Tensor) – Vertex feature matrix. Size: \((|\mathcal{V}|, C)\).
aggr (str, optional) – Aggregation function for neighbor messages, which can be 'mean', 'sum', or 'softmax_then_sum'. Default: 'mean'.
e_weight (torch.Tensor, optional) – The edge weight vector. Size: \((|\mathcal{E}|,)\). Defaults to None.
drop_rate (float) – Dropout rate. Randomly dropout the connections in adjacency matrix with probability drop_rate. Default: 0.0.

property vars_for_DL

Return a name list of available variables for deep learning in the graph including

Sparse Matrices:

\[\mathbf{A}, \mathcal{L}, \mathcal{L}_{sym}, \mathcal{L}_{rw}, \mathcal{L}_{GCN}\]

Sparse Diagonal Matrices:

\[\mathbf{D}_v, \mathbf{D}_v^{-1}, \mathbf{D}_v^{-\frac{1}{2}},\]

Vectors:

\[\vec{e}_{src}, \vec{e}_{dst}, \vec{e}_{weight}\]

Directed Graph

class dhg.DiGraph(num_v, e_list=None, e_weight=None, extra_selfloop=False, merge_op='mean', device=torch.device)[source]

Bases: dhg.structure.base.BaseGraph

Class for directed graph.

Parameters

num_v (int) – The Number of vertices.
e_list (Union[List[int], List[List[int]]], optional) – Initial edge set. Defaults to None.
e_weight (Union[float, List[float]], optional) – A list of weights for edges. Defaults to None.
extra_selfloop (bool, optional) – Whether to add extra self-loop to the directed graph. Defaults to False.
merge_op (str) – The operation to merge those conflicting edges, which can be one of 'mean', 'sum', or 'max'. Defaults to 'mean'.
device (torch.device, optional) – The device to store the directed graph. Defaults to torch.device('cpu').

property A: Return the adjacency matrix \(\mathbf{A}\) of the directed graph with torch.sparse_coo_tensor format. Size \((|\mathcal{V}|, |\mathcal{V}|)\).

property A_T: Return the transposed adjacency matrix \(\mathbf{A}^\top\) of the directed graph with torch.sparse_coo_tensor format. Size \((|\mathcal{V}|, |\mathcal{V}|)\).

property D_v_in: Return the diagnal matrix of vertex in degree \(\mathbf{D}_{v_{in}}\) with torch.sparse_coo_tensor format. Size \((|\mathcal{V}|, |\mathcal{V}|)\).

property D_v_in_neg_1: Return the nomalized diagnal matrix of vertex in degree \(\mathbf{D}_{v_{in}}^{-1}\) with torch.sparse_coo_tensor format. Size \((|\mathcal{V}|, |\mathcal{V}|)\).

property D_v_out: Return the diagnal matrix of vertex out degree \(\mathbf{D}_{v_{out}}\) with torch.sparse_coo_tensor format. Size \((|\mathcal{V}|, |\mathcal{V}|)\).

property D_v_out_neg_1: Return the nomalized diagnal matrix of vertex out degree \(\mathbf{D}_{v_{out}}^{-1}\) with torch.sparse_coo_tensor format. Size \((|\mathcal{V}|, |\mathcal{V}|)\).

N_v_in(v_idx)[source]

Return the predecessors of the vertex v_idx with torch.Tensor format.

Parameters: v_idx (int) – The index of the vertex.

N_v_out(v_idx)[source]

Return the successors of the vertex v_idx with torch.Tensor format.

Parameters: v_idx (int) – The index of the vertex.

add_edges(e_list, e_weight=None, merge_op='mean')[source]

Add edges to the directed graph.

Parameters

e_list (Union[List[int], List[List[int]]]) – Edge list.
e_weight (Union[float, List[float]], optional) – A list of weights for edges. Defaults to None.
merge_op (str) – The operation to merge those conflicting edges, which can be one of 'mean', 'sum', or 'max'. Defaults to 'mean'.

add_extra_selfloop()[source]: Add extra selfloops to the directed graph.

clear()[source]: Remove all edges in the directed graph.

clone()[source]: Clone the directed graph.

property deg_v_in: Return the in degree list of each vertices in the directed graph.

property deg_v_out: Return the out degree list of each vertices in the directed graph.

draw(e_style='line', v_label=None, v_size=1.0, v_color='r', v_line_width=1.0, e_color='gray', e_line_width=1.0, font_size=1.0, font_family='sans-serif', push_v_strength=1.0, push_e_strength=1.0, pull_e_strength=1.0, pull_center_strength=1.0)[source]

Draw the directed graph structure.

Parameters

e_style (str) – The edge style. The supported styles are only 'line'. Defaults to 'line'.
v_label (list) – The vertex label. Defaults to None.
v_size (Union[str, list]) – The vertex size. If v_size is a float, all vertices will have the same size. If v_size is a list, the size of each vertex will be set according to the corresponding element in the list. Defaults to 1.0.
v_color (Union[str, list]) –
The vertex color. If v_color is a str, all vertices will have the same color. If v_color is a list, the color of each vertex will be set according to the corresponding element in the list. Defaults to 'r'.
v_line_width (Union[str, list]) – The vertex line width. If v_line_width is a float, all vertices will have the same line width. If v_line_width is a list, the line width of each vertex will be set according to the corresponding element in the list. Defaults to 1.0.
e_color (Union[str, list]) –
The edge color. If e_color is a str, all edges will have the same color. If e_color is a list, the color of each edge will be set according to the corresponding element in the list. Defaults to 'gray'.
e_line_width (Union[str, list]) – The edge line width. If e_line_width is a float, all edges will have the same line width. If e_line_width is a list, the line width of each edge will be set according to the corresponding element in the list. Defaults to 1.0.
font_size (int) – The font size. Defaults to 1.0.
font_family (str) – The font family. Defaults to 'sans-serif'.
push_v_strength (float) – The vertex push strength. Defaults to 1.0.
push_e_strength (float) – The edge push strength. Defaults to 1.0.
pull_e_strength (float) – The edge pull strength. Defaults to 1.0.
pull_center_strength (float) – The center pull strength. Defaults to 1.0.

drop_edges(drop_rate, ord='uniform')[source]

Randomly drop edges from the directed graph. This function will return a new directed graph with non-dropped edges.

Parameters

drop_rate (float) – The drop rate of edges.
ord (str) – The order of dropping edges. Currently, only 'uniform' is supported. Defaults to uniform.

property e: Return edges and their weights in the directed graph with (edge_list, edge_weight_list) format. i-th element in the edge_list denotes i-th edge, \([v_{src} \longrightarrow v_{dst}]\). i-th element in edge_weight_list denotes the weight of i-th edge, \(e_{w}\). The lenght of the two lists are both \(|\mathcal{E}|\).

property e_dst: Return the index vector \(\vec{e}_{dst}\) of destination vertices in the directed graph with torch.Tensor format. Size \((|\mathcal{E}|,)\).

property e_src: Return the index vector \(\vec{e}_{src}\) of source vertices in the directed graph with torch.Tensor format. Size \((|\mathcal{E}|,)\).

property e_weight: Return the weight vector \(\vec{e}_{weight} of edges\) in the directed graph with torch.Tensor format. Size \((|\mathcal{E}|,)\).

static from_adj_list(num_v, adj_list, extra_selfloop=False, device=torch.device)[source]

Construct a directed graph from the adjacency list. Each line in the adjacency list has two components. The first element in each line is the source vertex index, and the rest elements are the target vertex indices that connected to the source vertex.

Note

This function can only construct the unweighted directed graph.

Parameters

num_v (int) – The number of vertices.
adj_list (List[List[int]]) – Adjacency list.
extra_selfloop (bool) – Whether to add extra self-loop. Defaults to False.
device (torch.device) – The device to store the directed graph. Defaults to torch.device('cpu').

static from_feature_kNN(features, k, p=2, distance2weight=False, include_center=False, center_as_src=True, device=torch.device)[source]

Construct a directed graph from feature matrix with kNN algorithm.

Parameters

features (torch.Tensor) – Feature tensor. Size: \((N_v \times C)\).
k (int) – The Number of nearest neighbors for each vertex.
p (int) – The p-norm for distance computation. Defaults to 2.
distance2weight (bool) – Whether to use distance as weight. If set to True, this function will project the distance to weight by \(e^{-x}\), where \(x\) is the computed distance. If set to False, this function will set the weight of all edges to 1. Defaults to False.
include_center (bool) – Whether the k-neighborhood includes the center vertex itself. Defaults to False.
center_as_src (bool) – Whether the center vertex is the source vertex of the edge. Defaults to True.
device (torch.device) – The device to store the directed graph. Defaults to torch.device('cpu').

static from_state_dict(state_dict)[source]

Load the directed graph from the state dict.

Parameters: state_dict (dict) – The state dict to load the directed graph.

static load(file_path)[source]

Load the DHG’s directed graph structure from a file.

Parameters: file_path (Union[str, Path]) – The file path to load the DHG’s directed graph structure.

nbr_v_in(v_idx)[source]

Return a vertex list of the predecessors of the vertex v_idx.

Parameters: v_idx (int) – The index of the vertex.

nbr_v_out(v_idx)[source]

Return a vertex list of the successors of the vertex v_idx.

Parameters: v_idx (int) – The index of the vertex.

property num_e: Return the number of edges in the directed graph.

property num_v: Return the number of vertices in the directed graph.

remove_edges(e_list)[source]

Remove specifed edges in the directed graph.

Parameters: e_list (Union[List[int], List[List[int]]]) – Edges to be removed.

remove_extra_selfloop()[source]: Remove extra selfloops from the directed graph.

remove_selfloop()[source]: Remove all selfloops from the directed graph.

reverse_direction()[source]: Reverse the direction of edges in directed graph.

save(file_path)[source]

Save the DHG’s directed graph structure to a file.

Parameters: file_path (Union[str, Path]) – The file path to store the DHG’s directed graph structure.

smoothing(X, L, lamb)[source]

Spectral-based smoothing.

\[X_{smoothed} = X + \lambda \mathcal{L} X\]

Parameters

X (torch.Tensor) – The vertex feature matrix. Size \((|\mathcal{V}|, C)\).
L (torch.Tensor) – The Laplacian matrix with torch.sparse_coo_tensor format. Size \((|\mathcal{V}|, |\mathcal{V}|)\).
lamb (float) – \(\lambda\), the strength of smoothing.

property state_dict: Get the state dict of the directed graph.

to(device)[source]

Move the directed graph to the specified device.

Parameters: device (torch.device) – The device to store the directed graph.

property v: Return the list of vertices.

v2v(X, aggr='mean', e_weight=None, direction='dst2src', drop_rate=0.0)[source]

Message passing from vertex to vertex on the directed graph structure.

Parameters

X (torch.Tensor) – Vertex feature matrix. Size: \((|\mathcal{V}|, C)\).
aggr (str, optional) – Aggregation function for neighbor messages, which can be 'mean', 'sum', or 'softmax_then_sum'. Default: 'mean'.
e_weight (torch.Tensor, optional) – The edge weight vector. Size: \((|\mathcal{E}|,)\). Defaults to None.
direction (str, optional) – The direction of message passing. Can be 'src2dst' or 'dst2src'. Default: 'dst2src'.
drop_rate (float) – Dropout rate. Randomly dropout the connections in adjacency matrix with probability drop_rate. Default: 0.0.

property vars_for_DL

Return a name list of available variables for deep learning in the directed graph including

Sparse Matrices:

\[\mathbf{A}, \mathbf{A}^\top\]

Sparse Diagnal Matrices:

\[\mathbf{D}_{v_{in}}, \mathbf{D}_{v_{out}}, \mathbf{D}_{v_{in}}^{-1}, \mathbf{D}_{v_{out}}^{-1}\]

Vectors:

\[\vec{e}_{src}, \vec{e}_{dst}, \vec{e}_{weight}\]

Bipartite Graph

class dhg.BiGraph(num_u, num_v, e_list=None, e_weight=None, merge_op='mean', device=torch.device)[source]

Bases: dhg.structure.base.BaseGraph

Class for bipartite graph.

Parameters

num_u (int) – The Number of vertices in set \(\mathcal{U}\).
num_v (int) – The Number of vertices in set \(\mathcal{V}\).
e_list (Union[List[int], List[List[int]]], optional) – Initial edge set. Defaults to None.
e_weight (Union[float, List[float]], optional) – A list of weights for edges. Defaults to None.
merge_op (str) – The operation to merge those conflicting edges, which can be one of 'mean', 'sum', or 'max'. Defaults to 'mean'.
device (torch.device, optional) – The device to store the bipartite graph. Defaults to torch.device('cpu').

property A: Return the adjacency matrix \(\mathbf{A}\) of the bipartite graph with torch.sparse_coo_tensor format. Size \((|\mathcal{U}| + |\mathcal{V}|, |\mathcal{U}| + |\mathcal{V}|)\).

property B: Return the bipartite adjacency matrix \(\mathbf{B}\) of the bipartite graph with torch.sparse_coo_tensor format. Size \((|\mathcal{U}|, |\mathcal{V}|)\).

property B_T: Return the transposed bipartite adjacency matrix \(\mathbf{B}^\top\) of the bipartite graph with torch.sparse_coo_tensor format. Size \((|\mathcal{V}|, |\mathcal{U}|)\).

property D_u: Return the diagnal matrix of vertex in degree \(\mathbf{D}_u\) with torch.sparse_coo_tensor format. Size \((|\mathcal{U}|, |\mathcal{U}|)\).

property D_u_neg_1: Return the nomalized diagnal matrix of vertex in degree \(\mathbf{D}_u^{-1}\) with torch.sparse_coo_tensor format. Size \((|\mathcal{U}|, |\mathcal{U}|)\).

property D_v: Return the diagnal matrix of vertex out degree \(\mathbf{D}_v\) with torch.sparse_coo_tensor format. Size \((|\mathcal{V}|, |\mathcal{V}|)\).

property D_v_neg_1: Return the nomalized diagnal matrix of vertex out degree \(\mathbf{D}_v^{-1}\) with torch.sparse_coo_tensor format. Size \((|\mathcal{V}|, |\mathcal{V}|)\).

property L_GCN: Return the GCN Laplacian matrix of the bipartite graph with torch.Tensor format. Size \((|\mathcal{U}| + |\mathcal{V}|, |\mathcal{U}| + |\mathcal{V}|)\).

N_u(v_idx)[source]

Return neighbor vertices in set \(\mathcal{U}\) of the specified vertex v_idx with torch.Tensor format.

Parameters: v_idx (int) – The index of the vertex.

N_v(u_idx)[source]

Return neighbor vertices in set \(\mathcal{V}\) of the specified vertex u_idx with torch.Tensor format.

Parameters: u_idx (int) – The index of the vertex.

add_edges(e_list, e_weight=None, merge_op='mean')[source]

Add edges to the bipartite graph.

Parameters

e_list (Union[List[int], List[List[int]]]) – Edge list.
e_weight (Union[float, List[float]], optional) – A list of weights for edges. Defaults to None.
merge_op (str) – The operation to merge those conflicting edges, which can be one of 'mean', 'sum', or 'max'. Defaults to 'mean'.

clear()[source]: Remove all edges in the bipartite graph.

clone()[source]: Clone the bipartite graph.

property deg_u: Return the degree list of vertices in set \(\mathcal{U}\).

property deg_v: Return the degree list of vertices in set \(\mathcal{V}\).

draw(e_style='line', u_label=None, u_size=1.0, u_color='m', u_line_width=1.0, v_label=None, v_size=1.0, v_color='r', v_line_width=1.0, e_color='gray', e_line_width=1.0, u_font_size=1.0, v_font_size=1.0, font_family='sans-serif', push_u_strength=1.0, push_v_strength=1.0, push_e_strength=1.0, pull_e_strength=1.0, pull_u_center_strength=1.0, pull_v_center_strength=1.0)[source]

Draw the bipartite graph structure.

Parameters

e_style (str) – The edge style. The supported edge styles are only 'line'. Defaults to 'line'.
u_label (list) – The label of vertices in set \(\mathcal{U}\). Defaults to None.
u_size (Union[str, list]) – The size of vertices in set \(\mathcal{U}\). If u_size is a float, all vertices will have the same size. If u_size is a list, the size of each vertex will be set according to the corresponding element in the list. Defaults to 1.0.
u_color (Union[str, list]) –
The color of vertices in set \(\mathcal{U}\). If u_color is a str, all vertices will have the same color. If u_color is a list, the color of each vertex will be set according to the corresponding element in the list. Defaults to 'm'.
u_line_width (Union[str, list]) – The line width of vertices in set \(\mathcal{U}\). If u_line_width is a float, all vertices will have the same line width. If u_line_width is a list, the line width of each vertex will be set according to the corresponding element in the list. Defaults to 1.0.
v_label (list) – The label of vertices in set \(\mathcal{V}\). Defaults to None.
v_size (Union[str, list]) – The size of vertices in set \(\mathcal{V}\). If v_size is a float, all vertices will have the same size. If v_size is a list, the size of each vertex will be set according to the corresponding element in the list. Defaults to 1.0.
v_color (Union[str, list]) –
The color of vertices in set \(\mathcal{V}\). If v_color is a str, all vertices will have the same color. If v_color is a list, the color of each vertex will be set according to the corresponding element in the list. Defaults to 'r'.
v_line_width (Union[str, list]) – The line width of vertices in set \(\mathcal{V}\). If v_line_width is a float, all vertices will have the same line width. If v_line_width is a list, the line width of each vertex will be set according to the corresponding element in the list. Defaults to 1.0.
e_color (Union[str, list]) –
The color of edges. If e_color is a str, all edges will have the same color. If e_color is a list, the color of each edge will be set according to the corresponding element in the list. Defaults to 'gray'.
e_line_width (Union[str, list]) – The line width of edges. If e_line_width is a float, all edges will have the same line width. If e_line_width is a list, the line width of each edge will be set according to the corresponding element in the list. Defaults to 1.0.
u_font_size (float) – The font size of vertex labels in set \(\mathcal{U}\). Defaults to 1.0.
v_font_size (float) – The font size of vertex labels in set \(\mathcal{V}\). Defaults to 1.0.
font_family (str) – The font family of vertex labels. Defaults to 'sans-serif'.
push_u_strength (float) – The strength of pushing vertices in set \(\mathcal{U}\). Defaults to 1.0.
push_v_strength (float) – The strength of pushing vertices in set \(\mathcal{V}\). Defaults to 1.0.
push_e_strength (float) – The strength of pushing edges. Defaults to 1.0.
pull_e_strength (float) – The strength of pulling edges. Defaults to 1.0.
pull_u_center_strength (float) – The strength of pulling vertices in set \(\mathcal{U}\) to the center. Defaults to 1.0.
pull_v_center_strength (float) – The strength of pulling vertices in set \(\mathcal{V}\) to the center. Defaults to 1.0.

drop_edges(drop_rate, ord='uniform')[source]

Randomly drop edges from the bipartite graph. This function will return a new bipartite graph with non-dropped edges.

Parameters

drop_rate (float) – The drop rate of edges.
ord (str) – The order of dropping edges. Currently, only 'uniform' is supported. Defaults to uniform.

property e: Return edges and their weights in the bipartite graph with (edge_list, edge_weight_list) format. i-th element in the edge_list denotes i-th edge, \([u \longleftrightarrow v]\). i-th element in edge_weight_list denotes the weight of i-th edge, \(e_{w}\). The lenght of the two lists are both \(|\mathcal{E}|\).

property e_u: Return the index vector \(\vec{e}_{u}\) of vertices in set \(\mathcal{U}\) in the bipartite graph with torch.Tensor format. Size \((|\mathcal{E}|,)\).

property e_v: Return the index vector \(\vec{e}_{v}\) of vertices in set \(\mathcal{V}\) in the bipartite graph with torch.Tensor format. Size \((|\mathcal{E}|,)\).

property e_weight: Return the weight vector \(\vec{e}_{weight}\) of edges in the bipartite graph with torch.Tensor format. Size \((|\mathcal{E}|,)\).

static from_adj_list(num_u, num_v, adj_list, device=torch.device)[source]

Construct a bipartite graph from the adjacency list. Each line in the adjacency list has two components. The first element in each line is the u_idx, and the rest elements are the v_idx that connected to the u_idx.

Note

This function can only construct the unweighted bipartite graph.

Parameters

num_u (int) – The number of vertices in set \(\mathcal{U}\).
num_v (int) – The number of vertices in set \(\mathcal{V}\).
adj_list (List[List[int]]) – Adjacency list.
device (torch.device) – The device to store the bipartite graph. Defaults to torch.device('cpu').

static from_hypergraph(hypergraph, vertex_as_U=True, weighted=False, device=torch.device)[source]

Construct a bipartite graph from the hypergraph.

Parameters

hypergraph (Hypergraph) – Hypergraph.
vertex_as_U (bool) – If set to True, vertices in hypergraph will be transformed to vertices in set \(U\), and hyperedges in hypergraph will be transformed to vertices in set \(V\). Otherwise, vertices in hypergraph will be transformed to vertices in set \(V\), and hyperedges in hypergraph will be transformed to vertices in set \(U\). Defaults to True.
weighted (bool) – If set to True, the bipartite graph will be constructed with weighted edges. The weight of each edge is assigned by the weight of the associated hyperedge in the original hypergraph. Defaults to False.
device (torch.device) – The device to store the bipartite graph. Defaults to torch.device('cpu').

static from_state_dict(state_dict)[source]

Load the bipartite graph structure from a state dictionary.

Parameters: state_dict (dict) – The state dictionary to load the bipartite graph structure.

static load(file_path)[source]

Load the DHG’s bipartite graph structure from a file.

Parameters: file_path (Union[str, Path]) – The file path to load the DHG’s bipartite graph structure.

nbr_u(v_idx)[source]

Return a neighbor vertex list in set \(\mathcal{U}\) of the specified vertex v_idx.

Parameters: v_idx (int) – The index of the vertex in set \(\mathcal{V}\).

nbr_v(u_idx)[source]

Return a neighbor vertex list in set \(\mathcal{V}\) of the specified vertex u_idx.

Parameters: u_idx (int) – The index of the vertex in set \(\mathcal{U}\).

property num_e: Return the number of edges in the bipartite graph.

property num_u: Return the number of vertices in set \(\mathcal{U}\).

property num_v: Return the number of vertices in set \(\mathcal{V}\).

remove_edges(e_list)[source]

Remove specifed edges in the bipartite graph.

Parameters: e_list (Union[List[int], List[List[int]]]) – Edges to be removed.

save(file_path)[source]

Save the DHG’s bipartite graph structure to a file.

Parameters: file_path (Union[str, Path]) – The file path to store the DHG’s bipartite graph structure.

smoothing(X, L, lamb)[source]

Spectral-based smoothing.

\[X_{smoothed} = X + \lambda \mathcal{L} X\]

Parameters

X (torch.Tensor) – The vertex feature matrix. Size \((|\mathcal{V}|, C)\).
L (torch.Tensor) – The Laplacian matrix with torch.sparse_coo_tensor format. Size \((|\mathcal{V}|, |\mathcal{V}|)\).
lamb (float) – \(\lambda\), the strength of smoothing.

smoothing_with_GCN(X, drop_rate=0.0)[source]

Return the smoothed feature matrix with GCN Laplacian matrix \(\mathcal{L}_{GCN}\).

Parameters

X (torch.Tensor) – Vertex feature matrix of the bipartite graph. Size \((|\mathcal{U}| + |\mathcal{V}|, C)\).
drop_rate (float) – Dropout rate. Randomly dropout the connections in adjacency matrix with probability drop_rate. Default: 0.0.

property state_dict: Get the state dict of the bipartite graph.

switch_uv()[source]: Switch the set \(\mathcal{U}\) and set \(\mathcal{V}\) of the bipartite graph, and return the vertex set switched bipartite graph.

to(device)[source]

Move the bipartite graph to the specified device.

Parameters: device (torch.device) – The device to store the bipartite graph.

property u: Return the list of vertices in set \(\mathcal{U}\).

u2v(X, aggr='mean', e_weight=None, drop_rate=0.0)[source]

Message passing from vertices in set \(\mathcal{U}\) to vertices in set \(\mathcal{V}\) on the bipartite graph structure.

Parameters

X (torch.Tensor) – Feature matrix of vertices in set \(\mathcal{U}\). Size: \((|\mathcal{U}|, C)\).
aggr (str, optional) – Aggregation function for neighbor messages, which can be 'mean', 'sum', or 'softmax_then_sum'. Default: 'mean'.
e_weight (torch.Tensor, optional) – The edge weight vector. Size: \((|\mathcal{E}|,)\). Defaults to None.
drop_rate (float) – Dropout rate. Randomly dropout the connections in adjacency matrix with probability drop_rate. Default: 0.0.

property v: Return the list of vertices in set \(\mathcal{V}\).

v2u(X, aggr='mean', e_weight=None, drop_rate=0.0)[source]

Message passing from vertices in set \(\mathcal{V}\) to vertices in set \(\mathcal{U}\) on the bipartite graph structure.

Parameters

X (torch.Tensor) – Feature matrix of vertices in set \(\mathcal{V}\). Size: \((|\mathcal{V}|, C)\).
aggr (str, optional) – Aggregation function for neighbor messages, which can be 'mean', 'sum', or 'softmax_then_sum'. Default: 'mean'.
e_weight (torch.Tensor, optional) – The edge weight vector. Size: \((|\mathcal{E}|,)\). Defaults to None.
drop_rate (float) – Dropout rate. Randomly dropout the connections in adjacency matrix with probability drop_rate. Default: 0.0.

property vars_for_DL

Return a name list of available variables for deep learning in the bipartite graph including

Sparse Matrices:

\[\mathbf{A}, \mathbf{B}, \mathbf{B}^\top\]

Sparse Diagnal Matrices:

\[\mathbf{D}_u, \mathbf{D}_v, \mathbf{D}_u^{-1}, \mathbf{D}_v^{-1}\]

Vectors:

\[\vec{e}_{u}, \vec{e}_{v}, \vec{e}_{weight}\]

High-Order Structures

Base Class

class dhg.BaseHypergraph(num_v, e_list_v2e=None, e_list_e2v=None, w_list_v2e=None, w_list_e2v=None, e_weight=None, v_weight=None, device=torch.device)[source]

The BaseHypergraph class is the base class for all hypergraph structures.

Parameters

num_v (int) – The number of vertices in the hypergraph.
e_list_v2e (Union[List[int], List[List[int]]], optional) – A list of hyperedges describes how the vertices point to the hyperedges. Defaults to None.
e_list_e2v (Union[List[int], List[List[int]]], optional) – A list of hyperedges describes how the hyperedges point to the vertices. Defaults to None.
w_list_v2e (Union[List[float], List[List[float]]], optional) – The weights are attached to the connections from vertices to hyperedges, which has the same shape as e_list_v2e. If set to None, the value 1 is used for all connections. Defaults to None.
w_list_e2v (Union[List[float], List[List[float]]], optional) – The weights are attached to the connections from the hyperedges to the vertices, which has the same shape to e_list_e2v. If set to None, the value 1 is used for all connections. Defaults to None.
e_weight (Union[float, List[float]], optional) – A list of weights for hyperedges. If set to None, the value 1 is used for all hyperedges. Defaults to None.
v_weight (Union[float, List[float]], optional) – Weights for vertices. If set to None, the value 1 is used for all vertices. Defaults to None.
device (torch.device, optional) – The deivce to store the hypergraph. Defaults to torch.device('cpu').

abstract property H: Return the hypergraph incidence matrix.

property H_e2v: Return the hypergraph incidence matrix with sparse matrix format.

H_e2v_of_group(group_name)[source]

Return the hypergraph incidence matrix with sparse matrix format in the specified hyperedge group.

Parameters: group_name (str) – The name of the specified hyperedge group.

abstract property H_of_group

Return the hypergraph incidence matrix in the specified hyperedge group.

Parameters: group_name (str) – The name of the specified hyperedge group.

property H_v2e: Return the hypergraph incidence matrix with sparse matrix format.

H_v2e_of_group(group_name)[source]

Return the hypergraph incidence matrix with sparse matrix format in the specified hyperedge group.

Parameters: group_name (str) – The name of the specified hyperedge group.

property R_e2v: Return the weight matrix of connections (hyperedges point to vertices) with sparse matrix format.

R_e2v_of_group(group_name)[source]

Return the weight matrix of connections (hyperedges point to vertices) with sparse matrix format in the specified hyperedge group.

Parameters: group_name (str) – The name of the specified hyperedge group.

property R_v2e: Return the weight matrix of connections (vertices point to hyperedges) with sparse matrix format.

R_v2e_of_group(group_name)[source]

Return the weight matrix of connections (vertices point to hyperedges) with sparse matrix format in the specified hyperedge group.

Parameters: group_name (str) – The name of the specified hyperedge group.

property W_e: Return the hyperedge weight matrix of the hypergraph.

W_e_of_group(group_name)[source]

Return the hyperedge weight matrix of the specified hyperedge group.

Parameters: group_name (str) – The name of the specified hyperedge group.

property W_v: Return the vertex weight matrix of the hypergraph.

add_hyperedges(e_list_v2e, e_list_e2v, w_list_v2e=None, w_list_e2v=None, e_weight=None, merge_op='mean', group_name='main')[source]

Add hyperedges to the hypergraph. If the group_name is not specified, the hyperedges will be added to the default main hyperedge group.

Parameters

num_v (int) – The number of vertices in the hypergraph.
e_list_v2e (Union[List[int], List[List[int]]]) – A list of hyperedges describes how the vertices point to the hyperedges.
e_list_e2v (Union[List[int], List[List[int]]]) – A list of hyperedges describes how the hyperedges point to the vertices.
w_list_v2e (Union[List[float], List[List[float]]], optional) – The weights are attached to the connections from vertices to hyperedges, which has the same shape as e_list_v2e. If set to None, the value 1 is used for all connections. Defaults to None.
w_list_e2v (Union[List[float], List[List[float]]], optional) – The weights are attached to the connections from the hyperedges to the vertices, which has the same shape to e_list_e2v. If set to None, the value 1 is used for all connections. Defaults to None.
e_weight (Union[float, List[float]], optional) – A list of weights for hyperedges. If set to None, the value 1 is used for all hyperedges. Defaults to None.
merge_op (str) – The merge operation for the conflicting hyperedges. The possible values are mean, sum, max, and min. Defaults to mean.
group_name (str, optional) – The target hyperedge group to add these hyperedges. Defaults to the main hyperedge group.

clear()[source]: Remove all hyperedges and caches from the hypergraph.

abstract clone()[source]: Return a copy of this type of hypergraph.

abstract draw(**kwargs)[source]: Draw the structure.

abstract drop_hyperedges(drop_rate, ord='uniform')[source]

Randomly drop hyperedges from the hypergraph. This function will return a new hypergraph with non-dropped hyperedges.

Parameters

drop_rate (float) – The drop rate of hyperedges.
ord (str) – The order of dropping edges. Currently, only 'uniform' is supported. Defaults to uniform.

abstract drop_hyperedges_of_group(group_name, drop_rate, ord='uniform')[source]

Randomly drop hyperedges from the specified hyperedge group. This function will return a new hypergraph with non-dropped hyperedges.

Parameters

group_name (str) – The name of the hyperedge group.
drop_rate (float) – The drop rate of hyperedges.
ord (str) – The order of dropping edges. Currently, only 'uniform' is supported. Defaults to uniform.

abstract property e: Return all hyperedges and weights in the hypergraph.

abstract e2v(X, aggr='mean', e2v_weight=None, v_weight=None)[source]

Message passing of hyperedges to vertices. The combination of e2v_aggregation and e2v_update.

Parameters

X (torch.Tensor) – Hyperedge feature matrix. Size \((|\mathcal{E}|, C)\).
aggr (str) – The aggregation method. Can be 'mean', 'sum' and 'softmax_then_sum'.
e2v_weight (torch.Tensor, optional) – The weight vector attached to connections (hyperedges point to vertices). If not specified, the function will use the weights specified in hypergraph construction. Defaults to None.
v_weight (torch.Tensor, optional) – The vertex weight vector. If not specified, the function will use the weights specified in hypergraph construction. Defaults to None.

abstract e2v_aggregation(X, aggr='mean', e2v_weight=None)[source]

Message aggregation step of hyperedges to vertices.

Parameters

X (torch.Tensor) – Hyperedge feature matrix. Size \((|\mathcal{E}|, C)\).
aggr (str) – The aggregation method. Can be 'mean', 'sum' and 'softmax_then_sum'.
e2v_weight (torch.Tensor, optional) – The weight vector attached to connections (hyperedges point to vertices). If not specified, the function will use the weights specified in hypergraph construction. Defaults to None.

abstract e2v_aggregation_of_group(group_name, X, aggr='mean', e2v_weight=None)[source]

Message aggregation step of hyperedges to vertices in specified hyperedge group.

Parameters

group_name (str) – The specified hyperedge group.
X (torch.Tensor) – Hyperedge feature matrix. Size \((|\mathcal{E}|, C)\).
aggr (str) – The aggregation method. Can be 'mean', 'sum' and 'softmax_then_sum'.
e2v_weight (torch.Tensor, optional) – The weight vector attached to connections (hyperedges point to vertices). If not specified, the function will use the weights specified in hypergraph construction. Defaults to None.

abstract e2v_of_group(group_name, X, aggr='mean', e2v_weight=None, v_weight=None)[source]

Message passing of hyperedges to vertices in specified hyperedge group. The combination of e2v_aggregation_of_group and e2v_update_of_group.

Parameters

group_name (str) – The specified hyperedge group.
X (torch.Tensor) – Hyperedge feature matrix. Size \((|\mathcal{E}|, C)\).
aggr (str) – The aggregation method. Can be 'mean', 'sum' and 'softmax_then_sum'.
e2v_weight (torch.Tensor, optional) – The weight vector attached to connections (hyperedges point to vertices). If not specified, the function will use the weights specified in hypergraph construction. Defaults to None.
v_weight (torch.Tensor, optional) – The vertex weight vector. If not specified, the function will use the weights specified in hypergraph construction. Defaults to None.

abstract e2v_update(X, v_weight=None)[source]

Message update step of hyperedges to vertices.

Parameters

X (torch.Tensor) – Vertex feature matrix. Size \((|\mathcal{V}|, C)\).
v_weight (torch.Tensor, optional) – The vertex weight vector. If not specified, the function will use the weights specified in hypergraph construction. Defaults to None.

abstract e2v_update_of_group(group_name, X, v_weight=None)[source]

Message update step of hyperedges to vertices in specified hyperedge group.

Parameters

group_name (str) – The specified hyperedge group.
X (torch.Tensor) – Vertex feature matrix. Size \((|\mathcal{V}|, C)\).
v_weight (torch.Tensor, optional) – The vertex weight vector. If not specified, the function will use the weights specified in hypergraph construction. Defaults to None.

abstract e_of_group(group_name)[source]

Return all hyperedges and weights in the specified hyperedge group.

Parameters: group_name (str) – The name of the specified hyperedge group.

abstract static from_state_dict(state_dict)[source]

Load the DHG’s hypergraph structure from the state dict.

Parameters: state_dict (dict) – The state dict to load the DHG’s hypergraph.

property group_names: Return the names of hyperedge groups in the hypergraph.

abstract static load(file_path)[source]

Load the DHG’s hypergraph structure from a file.

Parameters: file_path (str) – The file path to load the DHG’s hypergraph structure.

property num_e: Return the number of hyperedges in the hypergraph.

num_e_of_group(group_name)[source]

Return the number of hyperedges in the specified hyperedge group.

Parameters: group_name (str) – The name of the specified hyperedge group.

property num_groups: Return the number of hyperedge groups in the hypergraph.

property num_v: Return the number of vertices in the hypergraph.

remove_hyperedges(e_list_v2e, e_list_e2v, group_name=None)[source]

Remove the specified hyperedges from the hypergraph.

Parameters

e_list_v2e (Union[List[int], List[List[int]]]) – A list of hyperedges describes how the vertices point to the hyperedges.
e_list_e2v (Union[List[int], List[List[int]]]) – A list of hyperedges describes how the hyperedges point to the vertices.
group_name (str, optional) – Remove these hyperedges from the specified hyperedge group. If not specified, the function will remove those hyperedges from all hyperedge groups. Defaults to the None.

abstract save(file_path)[source]

Save the DHG’s hypergraph structure to a file.

Parameters: file_path (str) – The file_path to store the DHG’s hypergraph structure.

smoothing(X, L, lamb)[source]

Spectral-based smoothing.

\[X_{smoothed} = X + \lambda \mathcal{L} X\]

Parameters

X (torch.Tensor) – The vertex feature matrix. Size \((|\mathcal{V}|, C)\).
L (torch.Tensor) – The Laplacian matrix with torch.sparse_coo_tensor format. Size \((|\mathcal{V}|, |\mathcal{V}|)\).
lamb (float) – \(\lambda\), the strength of smoothing.

abstract property state_dict: Get the state dict of the hypergraph.

to(device)[source]

Move the hypergraph to the specified device.

Parameters: device (torch.device) – The device to store the hypergraph.

property v: Return the list of vertices.

abstract v2e(X, aggr='mean', v2e_weight=None, e_weight=None)[source]

Message passing of vertices to hyperedges. The combination of v2e_aggregation and v2e_update.

Parameters

X (torch.Tensor) – Vertex feature matrix. Size \((|\mathcal{V}|, C)\).
aggr (str) – The aggregation method. Can be 'mean', 'sum' and 'softmax_then_sum'.
v2e_weight (torch.Tensor, optional) – The weight vector attached to connections (vertices point to hyepredges). If not specified, the function will use the weights specified in hypergraph construction. Defaults to None.
e_weight (torch.Tensor, optional) – The hyperedge weight vector. If not specified, the function will use the weights specified in hypergraph construction. Defaults to None.

abstract v2e_aggregation(X, aggr='mean', v2e_weight=None)[source]

Message aggretation step of vertices to hyperedges.

Parameters

X (torch.Tensor) – Vertex feature matrix. Size \((|\mathcal{V}|, C)\).
aggr (str) – The aggregation method. Can be 'mean', 'sum' and 'softmax_then_sum'.
v2e_weight (torch.Tensor, optional) – The weight vector attached to connections (vertices point to hyepredges). If not specified, the function will use the weights specified in hypergraph construction. Defaults to None.

abstract v2e_aggregation_of_group(group_name, X, aggr='mean', v2e_weight=None)[source]

Message aggregation step of vertices to hyperedges in specified hyperedge group.

Parameters

group_name (str) – The specified hyperedge group.
X (torch.Tensor) – Vertex feature matrix. Size \((|\mathcal{V}|, C)\).
aggr (str) – The aggregation method. Can be 'mean', 'sum' and 'softmax_then_sum'.
v2e_weight (torch.Tensor, optional) – The weight vector attached to connections (vertices point to hyepredges). If not specified, the function will use the weights specified in hypergraph construction. Defaults to None.

abstract v2e_of_group(group_name, X, aggr='mean', v2e_weight=None, e_weight=None)[source]

Message passing of vertices to hyperedges in specified hyperedge group. The combination of e2v_aggregation_of_group and e2v_update_of_group.

Parameters

group_name (str) – The specified hyperedge group.
X (torch.Tensor) – Vertex feature matrix. Size \((|\mathcal{V}|, C)\).
aggr (str) – The aggregation method. Can be 'mean', 'sum' and 'softmax_then_sum'.
v2e_weight (torch.Tensor, optional) – The weight vector attached to connections (vertices point to hyepredges). If not specified, the function will use the weights specified in hypergraph construction. Defaults to None.
e_weight (torch.Tensor, optional) – The hyperedge weight vector. If not specified, the function will use the weights specified in hypergraph construction. Defaults to None.

abstract v2e_update(X, e_weight=None)[source]

Message update step of vertices to hyperedges.

Parameters

X (torch.Tensor) – Hyperedge feature matrix. Size \((|\mathcal{E}|, C)\).
e_weight (torch.Tensor, optional) – The hyperedge weight vector. If not specified, the function will use the weights specified in hypergraph construction. Defaults to None.

abstract v2e_update_of_group(group_name, X, e_weight=None)[source]

Message update step of vertices to hyperedges in specified hyperedge group.

Parameters

group_name (str) – The specified hyperedge group.
X (torch.Tensor) – Hyperedge feature matrix. Size \((|\mathcal{E}|, C)\).
e_weight (torch.Tensor, optional) – The hyperedge weight vector. If not specified, the function will use the weights specified in hypergraph construction. Defaults to None.

abstract v2v(X, aggr='mean', v2e_aggr=None, v2e_weight=None, e_weight=None, e2v_aggr=None, e2v_weight=None, v_weight=None)[source]

Message passing of vertices to vertices. The combination of v2e and e2v.

Parameters

X (torch.Tensor) – Vertex feature matrix. Size \((|\mathcal{V}|, C)\).
aggr (str) – The aggregation method. Can be 'mean', 'sum' and 'softmax_then_sum'. If specified, this aggr will be used to both v2e and e2v.
v2e_aggr (str, optional) – The aggregation method for hyperedges to vertices. Can be 'mean', 'sum' and 'softmax_then_sum'. If specified, it will override the aggr in e2v.
v2e_weight (torch.Tensor, optional) – The weight vector attached to connections (vertices point to hyepredges). If not specified, the function will use the weights specified in hypergraph construction. Defaults to None.
e_weight (torch.Tensor, optional) – The hyperedge weight vector. If not specified, the function will use the weights specified in hypergraph construction. Defaults to None.
e2v_aggr (str, optional) – The aggregation method for vertices to hyperedges. Can be 'mean', 'sum' and 'softmax_then_sum'. If specified, it will override the aggr in v2e.
e2v_weight (torch.Tensor, optional) – The weight vector attached to connections (hyperedges point to vertices). If not specified, the function will use the weights specified in hypergraph construction. Defaults to None.
v_weight (torch.Tensor, optional) – The vertex weight vector. If not specified, the function will use the weights specified in hypergraph construction. Defaults to None.

abstract v2v_of_group(group_name, X, aggr='mean', v2e_aggr=None, v2e_weight=None, e_weight=None, e2v_aggr=None, e2v_weight=None, v_weight=None)[source]

Message passing of vertices to vertices in specified hyperedge group. The combination of v2e_of_group and e2v_of_group.

Parameters

group_name (str) – The specified hyperedge group.
X (torch.Tensor) – Vertex feature matrix. Size \((|\mathcal{V}|, C)\).
aggr (str) – The aggregation method. Can be 'mean', 'sum' and 'softmax_then_sum'. If specified, this aggr will be used to both v2e_of_group and e2v_of_group.
v2e_aggr (str, optional) – The aggregation method for hyperedges to vertices. Can be 'mean', 'sum' and 'softmax_then_sum'. If specified, it will override the aggr in e2v_of_group.
v2e_weight (torch.Tensor, optional) – The weight vector attached to connections (vertices point to hyepredges). If not specified, the function will use the weights specified in hypergraph construction. Defaults to None.
e_weight (torch.Tensor, optional) – The hyperedge weight vector. If not specified, the function will use the weights specified in hypergraph construction. Defaults to None.
e2v_aggr (str, optional) – The aggregation method for vertices to hyperedges. Can be 'mean', 'sum' and 'softmax_then_sum'. If specified, it will override the aggr in v2e_of_group.
e2v_weight (torch.Tensor, optional) – The weight vector attached to connections (hyperedges point to vertices). If not specified, the function will use the weights specified in hypergraph construction. Defaults to None.
v_weight (torch.Tensor, optional) – The vertex weight vector. If not specified, the function will use the weights specified in hypergraph construction. Defaults to None.

property v_weight: Return the vertex weights of the hypergraph.

abstract property vars_for_DL: Return a name list of available variables for deep learning in this type of hypergraph.

Hypergraph

class dhg.Hypergraph(num_v, e_list=None, e_weight=None, v_weight=None, merge_op='mean', device=torch.device)[source]

Bases: dhg.structure.base.BaseHypergraph

The Hypergraph class is developed for hypergraph structures.

Parameters

num_v (int) – The number of vertices in the hypergraph.
e_list (Union[List[int], List[List[int]]], optional) – A list of hyperedges describes how the vertices point to the hyperedges. Defaults to None.
e_weight (Union[float, List[float]], optional) – A list of weights for hyperedges. If set to None, the value 1 is used for all hyperedges. Defaults to None.
v_weight (Union[List[float]], optional) – A list of weights for vertices. If set to None, the value 1 is used for all vertices. Defaults to None.
merge_op (str) – The operation to merge those conflicting hyperedges in the same hyperedge group, which can be 'mean', 'sum' or 'max'. Defaults to 'mean'.
device (torch.device, optional) – The deivce to store the hypergraph. Defaults to torch.device('cpu').

property D_e: Return the hyperedge degree matrix \(\mathbf{D}_e\) with torch.sparse_coo_tensor format.

property D_e_neg_1: Return the hyperedge degree matrix \(\mathbf{D}_e^{-1}\) with torch.sparse_coo_tensor format.

D_e_neg_1_of_group(group_name)[source]

Return the hyperedge degree matrix \(\mathbf{D}_e^{-1}\) of the specified hyperedge group with torch.sparse_coo_tensor format.

Parameters: group_name (str) – The name of the specified hyperedge group.

D_e_of_group(group_name)[source]

Return the hyperedge degree matrix \(\mathbf{D}_e\) of the specified hyperedge group with torch.sparse_coo_tensor format.

Parameters: group_name (str) – The name of the specified hyperedge group.

property D_v: Return the vertex degree matrix \(\mathbf{D}_v\) with torch.sparse_coo_tensor format.

property D_v_neg_1: Return the vertex degree matrix \(\mathbf{D}_v^{-1}\) with torch.sparse_coo_tensor format.

property D_v_neg_1_2: Return the vertex degree matrix \(\mathbf{D}_v^{-\frac{1}{2}}\) with torch.sparse_coo_tensor format.

D_v_neg_1_2_of_group(group_name)[source]

Return the vertex degree matrix \(\mathbf{D}_v^{-\frac{1}{2}}\) of the specified hyperedge group with torch.sparse_coo_tensor format.

Parameters: group_name (str) – The name of the specified hyperedge group.

D_v_neg_1_of_group(group_name)[source]

Return the vertex degree matrix \(\mathbf{D}_v^{-1}\) of the specified hyperedge group with torch.sparse_coo_tensor format.

Parameters: group_name (str) – The name of the specified hyperedge group.

D_v_of_group(group_name)[source]

Return the vertex degree matrix \(\mathbf{D}_v\) of the specified hyperedge group with torch.sparse_coo_tensor format.

Parameters: group_name (str) – The name of the specified hyperedge group.

property H: Return the hypergraph incidence matrix \(\mathbf{H}\) with torch.sparse_coo_tensor format.

property H_T: Return the transpose of the hypergraph incidence matrix \(\mathbf{H}^\top\) with torch.sparse_coo_tensor format.

H_T_of_group(group_name)[source]

Return the transpose of the hypergraph incidence matrix \(\mathbf{H}^\top\) of the specified hyperedge group with torch.sparse_coo_tensor format.

Parameters: group_name (str) – The name of the specified hyperedge group.

H_of_group(group_name)[source]

Return the hypergraph incidence matrix \(\mathbf{H}\) of the specified hyperedge group with torch.sparse_coo_tensor format.

Parameters: group_name (str) – The name of the specified hyperedge group.

property L_HGNN: Return the HGNN Laplacian matrix \(\mathcal{L}_{HGNN}\) of the hypergraph with torch.sparse_coo_tensor format.

\[\mathcal{L}_{HGNN} = \mathbf{D}_v^{-\frac{1}{2}} \mathbf{H} \mathbf{W}_e \mathbf{D}_e^{-1} \mathbf{H}^\top \mathbf{D}_v^{-\frac{1}{2}}\]

L_HGNN_of_group(group_name)[source]

Return the HGNN Laplacian matrix \(\mathcal{L}_{HGNN}\) of the specified hyperedge group with torch.sparse_coo_tensor format.

\[\mathcal{L}_{HGNN} = \mathbf{D}_v^{-\frac{1}{2}} \mathbf{H} \mathbf{W}_e \mathbf{D}_e^{-1} \mathbf{H}^\top \mathbf{D}_v^{-\frac{1}{2}}\]

Parameters: group_name (str) – The name of the specified hyperedge group.

property L_rw: Return the random walk Laplacian matrix \(\mathcal{L}_{rw}\) of the hypergraph with torch.sparse_coo_tensor format.

\[\mathcal{L}_{rw} = \mathbf{I} - \mathbf{D}_v^{-1} \mathbf{H} \mathbf{W}_e \mathbf{D}_e^{-1} \mathbf{H}^\top\]

L_rw_of_group(group_name)[source]

Return the random walk Laplacian matrix \(\mathcal{L}_{rw}\) of the specified hyperedge group with torch.sparse_coo_tensor format.

\[\mathcal{L}_{rw} = \mathbf{I} - \mathbf{D}_v^{-1} \mathbf{H} \mathbf{W}_e \mathbf{D}_e^{-1} \mathbf{H}^\top\]

Parameters: group_name (str) – The name of the specified hyperedge group.

property L_sym: Return the symmetric Laplacian matrix \(\mathcal{L}_{sym}\) of the hypergraph with torch.sparse_coo_tensor format.

\[\mathcal{L}_{sym} = \mathbf{I} - \mathbf{D}_v^{-\frac{1}{2}} \mathbf{H} \mathbf{W}_e \mathbf{D}_e^{-1} \mathbf{H}^\top \mathbf{D}_v^{-\frac{1}{2}}\]

L_sym_of_group(group_name)[source]

Return the symmetric Laplacian matrix \(\mathcal{L}_{sym}\) of the specified hyperedge group with torch.sparse_coo_tensor format.

\[\mathcal{L}_{sym} = \mathbf{I} - \mathbf{D}_v^{-\frac{1}{2}} \mathbf{H} \mathbf{W}_e \mathbf{D}_e^{-1} \mathbf{H}^\top \mathbf{D}_v^{-\frac{1}{2}}\]

Parameters: group_name (str) – The name of the specified hyperedge group.

N_e(v_idx)[source]

Return the neighbor hyperedges of the specified vertex with torch.Tensor format.

Note

The v_idx must be in the range of [0, num_v).

Parameters: v_idx (int) – The index of the vertex.

N_e_of_group(v_idx, group_name)[source]

Return the neighbor hyperedges of the specified vertex of the specified hyperedge group with torch.Tensor format.

Note

The v_idx must be in the range of [0, num_v).

Parameters

v_idx (int) – The index of the vertex.
group_name (str) – The name of the specified hyperedge group.

N_v(e_idx)[source]

Return the neighbor vertices of the specified hyperedge with torch.Tensor format.

Note

The e_idx must be in the range of [0, num_e).

Parameters: e_idx (int) – The index of the hyperedge.

N_v_of_group(e_idx, group_name)[source]

Return the neighbor vertices of the specified hyperedge of the specified hyperedge group with torch.Tensor format.

Note

The e_idx must be in the range of [0, num_e_of_group()).

Parameters

e_idx (int) – The index of the hyperedge.
group_name (str) – The name of the specified hyperedge group.

property W_e: Return the weight matrix \(\mathbf{W}_e\) of hyperedges with torch.sparse_coo_tensor format.

W_e_of_group(group_name)[source]

Return the weight matrix \(\mathbf{W}_e\) of hyperedges of the specified hyperedge group with torch.sparse_coo_tensor format.

Parameters: group_name (str) – The name of the specified hyperedge group.

property W_v: Return the weight matrix \(\mathbf{W}_v\) of vertices with torch.sparse_coo_tensor format.

add_hyperedges(e_list, e_weight=None, merge_op='mean', group_name='main')[source]

Add hyperedges to the hypergraph. If the group_name is not specified, the hyperedges will be added to the default main hyperedge group.

Parameters

num_v (int) – The number of vertices in the hypergraph.
e_list (Union[List[int], List[List[int]]]) – A list of hyperedges describes how the vertices point to the hyperedges.
e_weight (Union[float, List[float]], optional) – A list of weights for hyperedges. If set to None, the value 1 is used for all hyperedges. Defaults to None.
merge_op (str) – The merge operation for the conflicting hyperedges. The possible values are "mean", "sum", and "max". Defaults to "mean".
group_name (str, optional) – The target hyperedge group to add these hyperedges. Defaults to the main hyperedge group.

add_hyperedges_from_bigraph(bigraph, U_as_vertex=False, group_name='main')[source]

Add hyperedges from the bipartite graph.

Parameters

bigraph (BiGraph) – The bigraph to join the hypergraph.
U_as_vertex (bool) – If set to True, vertices in set \(\mathcal{U}\) and set \(\mathcal{V}\) will be treated as vertices and hyperedges in the constructed hypergraph, respectively. If set to False, vertices in set \(\mathcal{U}\) and set \(\mathcal{V}\) will be treated as hyperedges and vertices in the constructed hypergraph, respectively. Defaults to True.
group_name (str, optional) – The target hyperedge group to add these hyperedges. Defaults to the main hyperedge group.

add_hyperedges_from_feature_kNN(feature, k, group_name='main')[source]

Add hyperedges from the feature matrix by k-NN. Each hyperedge is constructed by the central vertex and its \(k\)-Nearest Neighbor vertices.

Parameters

features (torch.Tensor) – The feature matrix.
k (int) – The number of nearest neighbors.
group_name (str, optional) – The target hyperedge group to add these hyperedges. Defaults to the main hyperedge group.

add_hyperedges_from_graph(graph, group_name='main')[source]

Add hyperedges from edges in the graph. Each edge in the graph is treated as a hyperedge.

Parameters

graph (Graph) – The graph to join the hypergraph.
group_name (str, optional) – The target hyperedge group to add these hyperedges. Defaults to the main hyperedge group.

add_hyperedges_from_graph_kHop(graph, k, only_kHop=False, group_name='main')[source]

Add hyperedges from vertices and its k-Hop neighbors in the graph. Each hyperedge in the hypergraph is constructed by the central vertex and its \(k\)-Hop neighbor vertices.

Note

If the graph have \(|\mathcal{V}|\) vertices, the constructed hypergraph will have \(|\mathcal{V}|\) vertices and equal to or less than \(|\mathcal{V}|\) hyperedges.

Parameters

graph (Graph) – The graph to join the hypergraph.
k (int) – The number of hop neighbors.
only_kHop (bool) – If set to True, only the central vertex and its \(k\)-th Hop neighbors are used to construct the hyperedges. By default, the constructed hyperedge will include the central vertex and its [ \(1\)-th, \(2\)-th, \(\cdots\), \(k\)-th ] Hop neighbors. Defaults to False.
group_name (str, optional) – The target hyperedge group to add these hyperedges. Defaults to the main hyperedge group.

clear()[source]: Clear all hyperedges and caches from the hypergraph.

clone()[source]: Return a copy of the hypergraph.

property deg_e: Return the degree list of each hyperedge.

deg_e_of_group(group_name)[source]

Return the degree list of each hyperedge of the specified hyperedge group.

Parameters: group_name (str) – The name of the specified hyperedge group.

property deg_v: Return the degree list of each vertex.

deg_v_of_group(group_name)[source]

Return the degree list of each vertex of the specified hyperedge group.

Parameters: group_name (str) – The name of the specified hyperedge group.

draw(e_style='circle', v_label=None, v_size=1.0, v_color='r', v_line_width=1.0, e_color='gray', e_fill_color='whitesmoke', e_line_width=1.0, font_size=1.0, font_family='sans-serif', push_v_strength=1.0, push_e_strength=1.0, pull_e_strength=1.0, pull_center_strength=1.0)[source]

Draw the hypergraph structure.

Parameters

e_style (str) – The style of hyperedges. The available styles are only 'circle'. Defaults to 'circle'.
v_label (list) – The labels of vertices. Defaults to None.
v_size (float or list) – The size of vertices. Defaults to 1.0.
v_color (str or list) –
The color of vertices. Defaults to 'r'.
v_line_width (float or list) – The line width of vertices. Defaults to 1.0.
e_color (str or list) –
The color of hyperedges. Defaults to 'gray'.
e_fill_color (str or list) –
The fill color of hyperedges. Defaults to 'whitesmoke'.
e_line_width (float or list) – The line width of hyperedges. Defaults to 1.0.
font_size (float) – The font size of labels. Defaults to 1.0.
font_family (str) – The font family of labels. Defaults to 'sans-serif'.
push_v_strength (float) – The strength of pushing vertices. Defaults to 1.0.
push_e_strength (float) – The strength of pushing hyperedges. Defaults to 1.0.
pull_e_strength (float) – The strength of pulling hyperedges. Defaults to 1.0.
pull_center_strength (float) – The strength of pulling vertices to the center. Defaults to 1.0.

drop_hyperedges(drop_rate, ord='uniform')[source]

Randomly drop hyperedges from the hypergraph. This function will return a new hypergraph with non-dropped hyperedges.

Parameters

drop_rate (float) – The drop rate of hyperedges.
ord (str) – The order of dropping edges. Currently, only 'uniform' is supported. Defaults to uniform.

drop_hyperedges_of_group(group_name, drop_rate, ord='uniform')[source]

Randomly drop hyperedges from the specified hyperedge group. This function will return a new hypergraph with non-dropped hyperedges.

Parameters

group_name (str) – The name of the hyperedge group.
drop_rate (float) – The drop rate of hyperedges.
ord (str) – The order of dropping edges. Currently, only 'uniform' is supported. Defaults to uniform.

property e: Return all hyperedges and weights in the hypergraph.

e2v(X, aggr='mean', e2v_weight=None, drop_rate=0.0)[source]

Message passing of hyperedges to vertices. The combination of e2v_aggregation and e2v_update.

Parameters

X (torch.Tensor) – Hyperedge feature matrix. Size \((|\mathcal{E}|, C)\).
aggr (str) – The aggregation method. Can be 'mean', 'sum' and 'softmax_then_sum'.
e2v_weight (torch.Tensor, optional) – The weight vector attached to connections (hyperedges point to vertices). If not specified, the function will use the weights specified in hypergraph construction. Defaults to None.
drop_rate (float) – Dropout rate. Randomly dropout the connections in incidence matrix with probability drop_rate. Default: 0.0.

e2v_aggregation(X, aggr='mean', e2v_weight=None, drop_rate=0.0)[source]

Message aggregation step of hyperedges to vertices.

Parameters

X (torch.Tensor) – Hyperedge feature matrix. Size \((|\mathcal{E}|, C)\).
aggr (str) – The aggregation method. Can be 'mean', 'sum' and 'softmax_then_sum'.
e2v_weight (torch.Tensor, optional) – The weight vector attached to connections (hyperedges point to vertices). If not specified, the function will use the weights specified in hypergraph construction. Defaults to None.
drop_rate (float) – Dropout rate. Randomly dropout the connections in incidence matrix with probability drop_rate. Default: 0.0.

e2v_aggregation_of_group(group_name, X, aggr='mean', e2v_weight=None, drop_rate=0.0)[source]

Message aggregation step of hyperedges to vertices in specified hyperedge group.

Parameters

group_name (str) – The specified hyperedge group.
X (torch.Tensor) – Hyperedge feature matrix. Size \((|\mathcal{E}|, C)\).
aggr (str) – The aggregation method. Can be 'mean', 'sum' and 'softmax_then_sum'.
e2v_weight (torch.Tensor, optional) – The weight vector attached to connections (hyperedges point to vertices). If not specified, the function will use the weights specified in hypergraph construction. Defaults to None.
drop_rate (float) – Dropout rate. Randomly dropout the connections in incidence matrix with probability drop_rate. Default: 0.0.

property e2v_dst: Return the destination vertex index vector \(\overrightarrow{e2v}_{dst}\) of the connections (hyperedges point to vertices) in the hypergraph.

e2v_dst_of_group(group_name)[source]

Return the destination vertex index vector \(\overrightarrow{e2v}_{dst}\) of the connections (hyperedges point to vertices) in the specified hyperedge group.

Parameters: group_name (str) – The name of the specified hyperedge group.

e2v_of_group(group_name, X, aggr='mean', e2v_weight=None, drop_rate=0.0)[source]

Message passing of hyperedges to vertices in specified hyperedge group. The combination of e2v_aggregation_of_group and e2v_update_of_group.

Parameters

group_name (str) – The specified hyperedge group.
X (torch.Tensor) – Hyperedge feature matrix. Size \((|\mathcal{E}|, C)\).
aggr (str) – The aggregation method. Can be 'mean', 'sum' and 'softmax_then_sum'.
e2v_weight (torch.Tensor, optional) – The weight vector attached to connections (hyperedges point to vertices). If not specified, the function will use the weights specified in hypergraph construction. Defaults to None.
drop_rate (float) – Dropout rate. Randomly dropout the connections in incidence matrix with probability drop_rate. Default: 0.0.

property e2v_src: Return the source hyperedge index vector \(\overrightarrow{e2v}_{src}\) of the connections (hyperedges point to vertices) in the hypergraph.

e2v_src_of_group(group_name)[source]

Return the source hyperedge index vector \(\overrightarrow{e2v}_{src}\) of the connections (hyperedges point to vertices) in the specified hyperedge group.

Parameters: group_name (str) – The name of the specified hyperedge group.

e2v_update(X)[source]

Message update step of hyperedges to vertices.

Parameters: X (torch.Tensor) – Vertex feature matrix. Size \((|\mathcal{V}|, C)\).

e2v_update_of_group(group_name, X)[source]

Message update step of hyperedges to vertices in specified hyperedge group.

Parameters

group_name (str) – The specified hyperedge group.
X (torch.Tensor) – Vertex feature matrix. Size \((|\mathcal{V}|, C)\).

property e2v_weight: Return the weight vector \(\overrightarrow{e2v}_{weight}\) of the connections (hyperedges point to vertices) in the hypergraph.

e2v_weight_of_group(group_name)[source]

Return the weight vector \(\overrightarrow{e2v}_{weight}\) of the connections (hyperedges point to vertices) in the specified hyperedge group.

Parameters: group_name (str) – The name of the specified hyperedge group.

e_of_group(group_name)[source]

Return all hyperedges and weights of the specified hyperedge group.

Parameters: group_name (str) – The name of the specified hyperedge group.

static from_bigraph(bigraph, U_as_vertex=True, device=torch.device)[source]

Construct the hypergraph from the bipartite graph.

Parameters

bigraph (BiGraph) – The bipartite graph to construct the hypergraph.
U_as_vertex (bool, optional) – If set to True, vertices in set \(\mathcal{U}\) and set \(\mathcal{V}\) will be treated as vertices and hyperedges in the constructed hypergraph, respectively. If set to False, vertices in set \(\mathcal{U}\) and set \(\mathcal{V}\) will be treated as hyperedges and vertices in the constructed hypergraph, respectively. Defaults to True.
device (torch.device, optional) – The device to store the hypergraph. Defaults to torch.device('cpu').

static from_feature_kNN(features, k, device=torch.device)[source]

Construct the hypergraph from the feature matrix. Each hyperedge in the hypergraph is constructed by the central vertex ans its \(k-1\) neighbor vertices.

Note

The constructed hypergraph is a k-uniform hypergraph. If the feature matrix has the size \(N \times C\), the number of vertices and hyperedges of the constructed hypergraph are both \(N\).

Parameters

features (torch.Tensor) – The feature matrix.
k (int) – The number of nearest neighbors.
device (torch.device, optional) – The device to store the hypergraph. Defaults to torch.device('cpu').

static from_graph(graph, device=torch.device)[source]

Construct the hypergraph from the graph. Each edge in the graph is treated as a hyperedge in the constructed hypergraph.

Note

The construsted hypergraph is a 2-uniform hypergraph, and has the same number of vertices and edges/hyperedges as the graph.

Parameters

graph (Graph) – The graph to construct the hypergraph.
device (torch.device, optional) – The device to store the hypergraph. Defaults to torch.device('cpu').

static from_graph_kHop(graph, k, only_kHop=False, device=torch.device)[source]

Construct the hypergraph from the graph by k-Hop neighbors. Each hyperedge in the hypergraph is constructed by the central vertex and its \(k\)-Hop neighbor vertices.

Note

If the graph have \(|\mathcal{V}|\) vertices, the constructed hypergraph will have \(|\mathcal{V}|\) vertices and equal to or less than \(|\mathcal{V}|\) hyperedges.

Parameters

graph (Graph) – The graph to construct the hypergraph.
k (int) – The number of hop neighbors.
only_kHop (bool) – If set to True, only the central vertex and its \(k\)-th Hop neighbors are used to construct the hyperedges. By default, the constructed hyperedge will include the central vertex and its [ \(1\)-th, \(2\)-th, \(\cdots\), \(k\)-th ] Hop neighbors. Defaults to False.
device (torch.device, optional) – The device to store the hypergraph. Defaults to torch.device('cpu').

static from_state_dict(state_dict)[source]

Load the hypergraph from the state dict.

Parameters: state_dict (dict) – The state dict to load the hypergraph.

property group_names: Return the names of all hyperedge groups in the hypergraph.

static load(file_path)[source]

Load the DHG’s hypergraph structure from a file.

Parameters: file_path (Union[str, Path]) – The file path to load the DHG’s hypergraph structure.

nbr_e(v_idx)[source]

Return the neighbor hyperedge list of the specified vertex.

Parameters: v_idx (int) – The index of the vertex.

nbr_e_of_group(v_idx, group_name)[source]

Return the neighbor hyperedge list of the specified vertex of the specified hyperedge group.

Parameters

v_idx (int) – The index of the vertex.
group_name (str) – The name of the specified hyperedge group.

nbr_v(e_idx)[source]

Return the neighbor vertex list of the specified hyperedge.

Parameters: e_idx (int) – The index of the hyperedge.

nbr_v_of_group(e_idx, group_name)[source]

Return the neighbor vertex list of the specified hyperedge of the specified hyperedge group.

Parameters

e_idx (int) – The index of the hyperedge.
group_name (str) – The name of the specified hyperedge group.

property num_e: Return the number of hyperedges in the hypergraph.

num_e_of_group(group_name)[source]

Return the number of hyperedges of the specified hyperedge group.

Parameters: group_name (str) – The name of the specified hyperedge group.

property num_groups: Return the number of hyperedge groups in the hypergraph.

property num_v: Return the number of vertices in the hypergraph.

remove_group(group_name)[source]

Remove the specified hyperedge group from the hypergraph.

Parameters: group_name (str) – The name of the hyperedge group to remove.

remove_hyperedges(e_list, group_name=None)[source]

Remove the specified hyperedges from the hypergraph.

Parameters

e_list (Union[List[int], List[List[int]]]) – A list of hyperedges describes how the vertices point to the hyperedges.
group_name (str, optional) – Remove these hyperedges from the specified hyperedge group. If not specified, the function will remove those hyperedges from all hyperedge groups. Defaults to the None.

save(file_path)[source]

Save the DHG’s hypergraph structure a file.

Parameters: file_path (Union[str, Path]) – The file path to store the DHG’s hypergraph structure.

smoothing(X, L, lamb)[source]

Spectral-based smoothing.

\[X_{smoothed} = X + \lambda \mathcal{L} X\]

Parameters

X (torch.Tensor) – The vertex feature matrix. Size \((|\mathcal{V}|, C)\).
L (torch.Tensor) – The Laplacian matrix with torch.sparse_coo_tensor format. Size \((|\mathcal{V}|, |\mathcal{V}|)\).
lamb (float) – \(\lambda\), the strength of smoothing.

smoothing_with_HGNN(X, drop_rate=0.0)[source]

Return the smoothed feature matrix with the HGNN Laplacian matrix \(\mathcal{L}_{HGNN}\).

\[\mathbf{X} = \mathbf{D}_v^{-\frac{1}{2}} \mathbf{H} \mathbf{W}_e \mathbf{D}_e^{-1} \mathbf{H}^\top \mathbf{D}_v^{-\frac{1}{2}} \mathbf{X}\]

Parameters

X (torch.Tensor) – The feature matrix. Size \((|\mathcal{V}|, C)\).
drop_rate (float) – Dropout rate. Randomly dropout the connections in incidence matrix with probability drop_rate. Default: 0.0.

smoothing_with_HGNN_of_group(group_name, X, drop_rate=0.0)[source]

Return the smoothed feature matrix with the HGNN Laplacian matrix \(\mathcal{L}_{HGNN}\).

\[\mathbf{X} = \mathbf{D}_v^{-\frac{1}{2}} \mathbf{H} \mathbf{W}_e \mathbf{D}_e^{-1} \mathbf{H}^\top \mathbf{D}_v^{-\frac{1}{2}} \mathbf{X}\]

Parameters

group_name (str) – The name of the specified hyperedge group.
X (torch.Tensor) – The feature matrix. Size \((|\mathcal{V}|, C)\).
drop_rate (float) – Dropout rate. Randomly dropout the connections in incidence matrix with probability drop_rate. Default: 0.0.

property state_dict: Get the state dict of the hypergraph.

to(device)[source]

Move the hypergraph to the specified device.

Parameters: device (torch.device) – The target device.

property v: Return the list of vertices.

v2e(X, aggr='mean', v2e_weight=None, e_weight=None, drop_rate=0.0)[source]

Message passing of vertices to hyperedges. The combination of v2e_aggregation and v2e_update.

Parameters

X (torch.Tensor) – Vertex feature matrix. Size \((|\mathcal{V}|, C)\).
aggr (str) – The aggregation method. Can be 'mean', 'sum' and 'softmax_then_sum'.
v2e_weight (torch.Tensor, optional) – The weight vector attached to connections (vertices point to hyepredges). If not specified, the function will use the weights specified in hypergraph construction. Defaults to None.
e_weight (torch.Tensor, optional) – The hyperedge weight vector. If not specified, the function will use the weights specified in hypergraph construction. Defaults to None.
drop_rate (float) – Dropout rate. Randomly dropout the connections in incidence matrix with probability drop_rate. Default: 0.0.

v2e_aggregation(X, aggr='mean', v2e_weight=None, drop_rate=0.0)[source]

Message aggretation step of vertices to hyperedges.

Parameters

X (torch.Tensor) – Vertex feature matrix. Size \((|\mathcal{V}|, C)\).
aggr (str) – The aggregation method. Can be 'mean', 'sum' and 'softmax_then_sum'.
v2e_weight (torch.Tensor, optional) – The weight vector attached to connections (vertices point to hyepredges). If not specified, the function will use the weights specified in hypergraph construction. Defaults to None.
drop_rate (float) – Dropout rate. Randomly dropout the connections in incidence matrix with probability drop_rate. Default: 0.0.

v2e_aggregation_of_group(group_name, X, aggr='mean', v2e_weight=None, drop_rate=0.0)[source]

Message aggregation step of vertices to hyperedges in specified hyperedge group.

Parameters

group_name (str) – The specified hyperedge group.
X (torch.Tensor) – Vertex feature matrix. Size \((|\mathcal{V}|, C)\).
aggr (str) – The aggregation method. Can be 'mean', 'sum' and 'softmax_then_sum'.
v2e_weight (torch.Tensor, optional) – The weight vector attached to connections (vertices point to hyepredges). If not specified, the function will use the weights specified in hypergraph construction. Defaults to None.
drop_rate (float) – Dropout rate. Randomly dropout the connections in incidence matrix with probability drop_rate. Default: 0.0.

property v2e_dst: Return the destination hyperedge index vector \(\overrightarrow{v2e}_{dst}\) of the connections (vertices point to hyperedges) in the hypergraph.

v2e_dst_of_group(group_name)[source]

Return the destination hyperedge index vector \(\overrightarrow{v2e}_{dst}\) of the connections (vertices point to hyperedges) in the specified hyperedge group.

Parameters: group_name (str) – The name of the specified hyperedge group.

v2e_of_group(group_name, X, aggr='mean', v2e_weight=None, e_weight=None, drop_rate=0.0)[source]

Message passing of vertices to hyperedges in specified hyperedge group. The combination of e2v_aggregation_of_group and e2v_update_of_group.

Parameters

group_name (str) – The specified hyperedge group.
X (torch.Tensor) – Vertex feature matrix. Size \((|\mathcal{V}|, C)\).
aggr (str) – The aggregation method. Can be 'mean', 'sum' and 'softmax_then_sum'.
v2e_weight (torch.Tensor, optional) – The weight vector attached to connections (vertices point to hyepredges). If not specified, the function will use the weights specified in hypergraph construction. Defaults to None.
e_weight (torch.Tensor, optional) – The hyperedge weight vector. If not specified, the function will use the weights specified in hypergraph construction. Defaults to None.
drop_rate (float) – Dropout rate. Randomly dropout the connections in incidence matrix with probability drop_rate. Default: 0.0.

property v2e_src: Return the source vertex index vector \(\overrightarrow{v2e}_{src}\) of the connections (vertices point to hyperedges) in the hypergraph.

v2e_src_of_group(group_name)[source]

Return the source vertex index vector \(\overrightarrow{v2e}_{src}\) of the connections (vertices point to hyperedges) in the specified hyperedge group.

Parameters: group_name (str) – The name of the specified hyperedge group.

v2e_update(X, e_weight=None)[source]

Message update step of vertices to hyperedges.

Parameters

X (torch.Tensor) – Hyperedge feature matrix. Size \((|\mathcal{E}|, C)\).
e_weight (torch.Tensor, optional) – The hyperedge weight vector. If not specified, the function will use the weights specified in hypergraph construction. Defaults to None.

v2e_update_of_group(group_name, X, e_weight=None)[source]

Message update step of vertices to hyperedges in specified hyperedge group.

Parameters

group_name (str) – The specified hyperedge group.
X (torch.Tensor) – Hyperedge feature matrix. Size \((|\mathcal{E}|, C)\).
e_weight (torch.Tensor, optional) – The hyperedge weight vector. If not specified, the function will use the weights specified in hypergraph construction. Defaults to None.

property v2e_weight: Return the weight vector \(\overrightarrow{v2e}_{weight}\) of the connections (vertices point to hyperedges) in the hypergraph.

v2e_weight_of_group(group_name)[source]

Return the weight vector \(\overrightarrow{v2e}_{weight}\) of the connections (vertices point to hyperedges) in the specified hyperedge group.

Parameters: group_name (str) – The name of the specified hyperedge group.

v2v(X, aggr='mean', drop_rate=0.0, v2e_aggr=None, v2e_weight=None, v2e_drop_rate=None, e_weight=None, e2v_aggr=None, e2v_weight=None, e2v_drop_rate=None)[source]

Message passing of vertices to vertices. The combination of v2e and e2v.

Parameters

X (torch.Tensor) – Vertex feature matrix. Size \((|\mathcal{V}|, C)\).
aggr (str) – The aggregation method. Can be 'mean', 'sum' and 'softmax_then_sum'. If specified, this aggr will be used to both v2e and e2v.
drop_rate (float) – Dropout rate. Randomly dropout the connections in incidence matrix with probability drop_rate. Default: 0.0.
v2e_aggr (str, optional) – The aggregation method for hyperedges to vertices. Can be 'mean', 'sum' and 'softmax_then_sum'. If specified, it will override the aggr in e2v.
v2e_weight (torch.Tensor, optional) – The weight vector attached to connections (vertices point to hyepredges). If not specified, the function will use the weights specified in hypergraph construction. Defaults to None.
v2e_drop_rate (float, optional) – Dropout rate for hyperedges to vertices. Randomly dropout the connections in incidence matrix with probability drop_rate. If specified, it will override the drop_rate in e2v. Default: None.
e_weight (torch.Tensor, optional) – The hyperedge weight vector. If not specified, the function will use the weights specified in hypergraph construction. Defaults to None.
e2v_aggr (str, optional) – The aggregation method for vertices to hyperedges. Can be 'mean', 'sum' and 'softmax_then_sum'. If specified, it will override the aggr in v2e.
e2v_weight (torch.Tensor, optional) – The weight vector attached to connections (hyperedges point to vertices). If not specified, the function will use the weights specified in hypergraph construction. Defaults to None.
e2v_drop_rate (float, optional) – Dropout rate for vertices to hyperedges. Randomly dropout the connections in incidence matrix with probability drop_rate. If specified, it will override the drop_rate in v2e. Default: None.

v2v_of_group(group_name, X, aggr='mean', drop_rate=0.0, v2e_aggr=None, v2e_weight=None, v2e_drop_rate=None, e_weight=None, e2v_aggr=None, e2v_weight=None, e2v_drop_rate=None)[source]

Message passing of vertices to vertices in specified hyperedge group. The combination of v2e_of_group and e2v_of_group.

Parameters

group_name (str) – The specified hyperedge group.
X (torch.Tensor) – Vertex feature matrix. Size \((|\mathcal{V}|, C)\).
aggr (str) – The aggregation method. Can be 'mean', 'sum' and 'softmax_then_sum'. If specified, this aggr will be used to both v2e_of_group and e2v_of_group.
drop_rate (float) – Dropout rate. Randomly dropout the connections in incidence matrix with probability drop_rate. Default: 0.0.
v2e_aggr (str, optional) – The aggregation method for hyperedges to vertices. Can be 'mean', 'sum' and 'softmax_then_sum'. If specified, it will override the aggr in e2v_of_group.
v2e_weight (torch.Tensor, optional) – The weight vector attached to connections (vertices point to hyepredges). If not specified, the function will use the weights specified in hypergraph construction. Defaults to None.
v2e_drop_rate (float, optional) – Dropout rate for hyperedges to vertices. Randomly dropout the connections in incidence matrix with probability drop_rate. If specified, it will override the drop_rate in e2v_of_group. Default: None.
e_weight (torch.Tensor, optional) – The hyperedge weight vector. If not specified, the function will use the weights specified in hypergraph construction. Defaults to None.
e2v_aggr (str, optional) – The aggregation method for vertices to hyperedges. Can be 'mean', 'sum' and 'softmax_then_sum'. If specified, it will override the aggr in v2e_of_group.
e2v_weight (torch.Tensor, optional) – The weight vector attached to connections (hyperedges point to vertices). If not specified, the function will use the weights specified in hypergraph construction. Defaults to None.
e2v_drop_rate (float, optional) – Dropout rate for vertices to hyperedges. Randomly dropout the connections in incidence matrix with probability drop_rate. If specified, it will override the drop_rate in v2e_of_group. Default: None.

property v_weight: Return the list of vertex weights.

property vars_for_DL

Return a name list of available variables for deep learning in the hypergraph including

Sparse Matrices:

\[\mathbf{H}, \mathbf{H}^\top, \mathcal{L}_{sym}, \mathcal{L}_{rw} \mathcal{L}_{HGNN},\]

Sparse Diagnal Matrices:

\[\mathbf{W}_v, \mathbf{W}_e, \mathbf{D}_v, \mathbf{D}_v^{-1}, \mathbf{D}_v^{-\frac{1}{2}}, \mathbf{D}_e, \mathbf{D}_e^{-1},\]

Vectors:

\[\begin{split}\overrightarrow{v2e}_{src}, \overrightarrow{v2e}_{dst}, \overrightarrow{v2e}_{weight},\\ \overrightarrow{e2v}_{src}, \overrightarrow{e2v}_{dst}, \overrightarrow{e2v}_{weight}\end{split}\]