easygraph.classes.base module

class easygraph.classes.base.BaseHypergraph(num_v: int, v_property: Dict | List[Dict] | None = None, e_list: List[int] | List[List[int]] | None = None, e_property: Dict | List[Dict] | None = None, e_weight: float | List[float] | None = None, extra_selfloop: bool = False, device: str = 'cpu')

Bases: object

The BaseHypergraph class is the base class for all hypergraph 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 H: torch.Tensor

Return the hypergraph incidence matrix.

property H_e2v: torch.Tensor

Return the hypergraph incidence matrix with sparse matrix format.

H_e2v_of_group(group_name: str) → torch.Tensor

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: torch.Tensor

Return the hypergraph incidence matrix in the specified hyperedge group.

Parameters:

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

property H_v2e: torch.Tensor

Return the hypergraph incidence matrix with sparse matrix format.

H_v2e_of_group(group_name: str) → torch.Tensor

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: torch.Tensor

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

R_e2v_of_group(group_name: str) → torch.Tensor

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: torch.Tensor

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

R_v2e_of_group(group_name: str) → torch.Tensor

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: torch.Tensor

Return the hyperedge weight matrix of the hypergraph.

W_e_of_group(group_name: str) → torch.Tensor

Return the hyperedge weight matrix of the specified hyperedge group.

Parameters:

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

property W_v: torch.Tensor

Return the vertex weight matrix of the hypergraph.

add_hyperedges(e_list_v2e: List[int] | List[List[int]], e_list_e2v: List[int] | List[List[int]], w_list_v2e: List[float] | List[List[float]] | None = None, w_list_e2v: List[float] | List[List[float]] | None = None, e_weight: float | List[float] | None = None, merge_op: str = 'mean', group_name: str = 'main')

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()

Remove all hyperedges and caches from the hypergraph.

abstract clone() → BaseHypergraph

Return a copy of this type of hypergraph.

abstract draw(**kwargs)

Draw the structure.

abstract drop_hyperedges(drop_rate: float, ord='uniform')

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: str, drop_rate: float, ord='uniform')

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: Tuple[List[List[int]], List[float]]

Return all hyperedges and weights in the hypergraph.

abstract e2v(X: torch.Tensor, aggr: str = 'mean', e2v_weight: torch.Tensor | None = None, v_weight: torch.Tensor | None = None)

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: torch.Tensor, aggr: str = 'mean', e2v_weight: torch.Tensor | None = None)

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: str, X: torch.Tensor, aggr: str = 'mean', e2v_weight: torch.Tensor | None = None)

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: str, X: torch.Tensor, aggr: str = 'mean', e2v_weight: torch.Tensor | None = None, v_weight: torch.Tensor | None = None)

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: torch.Tensor, v_weight: torch.Tensor | None = None)

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: str, X: torch.Tensor, v_weight: torch.Tensor | None = None)

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: str) → Tuple[List[List[int]], List[float]]

Return all hyperedges and weights in the specified hyperedge group.

Parameters:

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

property e_property

abstract static from_state_dict(state_dict: dict)

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

Parameters:

state_dict (dict) – The state dict to load the EasyGraph’s hypergraph.

property group_names: List[str]

Return the names of hyperedge groups in the hypergraph.

abstract static load(file_path: str | Path)

Load the EasyGraph’s hypergraph structure from a file.

Parameters:

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

property num_e: int

Return the number of hyperedges in the hypergraph.

num_e_of_group(group_name: str) → int

Return the number of hyperedges in the specified hyperedge group.

Parameters:

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

property num_groups: int

Return the number of hyperedge groups in the hypergraph.

property num_v: int

Return the number of vertices in the hypergraph.

remove_hyperedges(e_list_v2e: List[int] | List[List[int]], e_list_e2v: List[int] | List[List[int]], group_name: str | None = None)

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: str | Path)

Save the EasyGraph’s hypergraph structure to a file.

Parameters:

file_path (str) – The file_path to store the EasyGraph’s hypergraph structure.

smoothing(X: torch.Tensor, L: torch.Tensor, lamb: float) → torch.Tensor

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: Dict[str, Any]

Get the state dict of the hypergraph.

to(device: str = 'cpu') → BaseHypergraph

Move the hypergraph to the specified device.

Parameters:

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

property v: List[int]

Return the list of vertices.

abstract v2e(X: torch.Tensor, aggr: str = 'mean', v2e_weight: torch.Tensor | None = None, e_weight: torch.Tensor | None = None)

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: torch.Tensor, aggr: str = 'mean', v2e_weight: torch.Tensor | None = None, drop_rate: float = 0.0)

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: str, X: torch.Tensor, aggr: str = 'mean', v2e_weight: torch.Tensor | None = None, drop_rate: float = 0.0)

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: str, X: torch.Tensor, aggr: str = 'mean', v2e_weight: torch.Tensor | None = None, e_weight: torch.Tensor | None = None)

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: torch.Tensor, e_weight: torch.Tensor | None = None)

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: str, X: torch.Tensor, e_weight: torch.Tensor | None = None)

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: torch.Tensor, aggr: str = 'mean', v2e_aggr: str | None = None, v2e_weight: torch.Tensor | None = None, e_weight: torch.Tensor | None = None, e2v_aggr: str | None = None, e2v_weight: torch.Tensor | None = None, v_weight: torch.Tensor | None = None)

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: str, X: torch.Tensor, aggr: str = 'mean', v2e_aggr: str | None = None, v2e_weight: torch.Tensor | None = None, e_weight: torch.Tensor | None = None, e2v_aggr: str | None = None, e2v_weight: torch.Tensor | None = None, v_weight: torch.Tensor | None = None)

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_property

property v_weight: List[float]

Return the vertex weights of the hypergraph.

abstract property vars_for_DL: List[str]

Return a name list of available variables for deep learning in this type of hypergraph.

easygraph.classes.base.load_structure(file_path: str | Path)

Load a EasyGraph’s high-order network structure from a file. The supported structure Hypergraph.

Parameters:

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