dgl.DGLGraph.edge_ids¶
-
DGLGraph.
edge_ids
(u, v, force_multi=None, return_uv=False, etype=None)¶ Return the edge ID(s) given the two endpoints of the edge(s).
- Parameters
u (node IDs) –
The source node IDs of the edges. The allowed formats are:
int
: A single node.Int Tensor: Each element is a node ID. The tensor must have the same device type and ID data type as the graph’s.
iterable[int]: Each element is a node ID.
v (node IDs) –
The destination node IDs of the edges. The allowed formats are:
int
: A single node.Int Tensor: Each element is a node ID. The tensor must have the same device type and ID data type as the graph’s.
iterable[int]: Each element is a node ID.
force_multi (bool, optional) – DEPRECATED, use
return_uv
instead. Whether to allow the graph to be a multigraph, i.e. there can be multiple edges from one node to another.return_uv (bool, optional) – Whether to return the source and destination node IDs along with the edges. If False (default), it assumes that the graph is a simple graph and there is only one edge from one node to another. If True, there can be multiple edges found from one node to another.
etype (str or (str, str, str), optional) –
The type names of the edges. The allowed type name formats are:
(str, str, str)
for source node type, edge type and destination node type.or one
str
edge type name if the name can uniquely identify a triplet format in the graph.
Can be omitted if the graph has only one type of edges.
- Returns
If
return_uv=False
, it returns the edge IDs in a tensor, where the i-th element is the ID of the edge(u[i], v[i])
.If
return_uv=True
, it returns a tuple of three 1D tensors(eu, ev, e)
.e[i]
is the ID of an edge fromeu[i]
toev[i]
. It returns all edges (including parallel edges) fromeu[i]
toev[i]
in this case.
- Return type
Tensor, or (Tensor, Tensor, Tensor)
Notes
If the graph is a simple graph,
return_uv=False
, and there are no edges between some pairs of node(s), it will raise an error.If the graph is a multigraph,
return_uv=False
, and there are multiple edges between some pairs of node(s), it returns an arbitrary one from them.Examples
The following example uses PyTorch backend.
>>> import dgl >>> import torch
Create a homogeneous graph.
>>> g = dgl.graph((torch.tensor([0, 0, 1, 1, 1]), torch.tensor([1, 0, 2, 3, 2])))
Query for the edges.
>>> g.edge_ids(0, 0) 1 >>> g.edge_ids(torch.tensor([1, 0]), torch.tensor([3, 1])) tensor([3, 0])
Get all edges for pairs of nodes.
>>> g.edge_ids(torch.tensor([1, 0]), torch.tensor([3, 1]), return_uv=True) (tensor([1, 0]), tensor([3, 1]), tensor([3, 0]))
If the graph has multiple edge types, one need to specify the edge type.
>>> g = dgl.heterograph({ ... ('user', 'follows', 'user'): (torch.tensor([0, 1]), torch.tensor([1, 2])), ... ('user', 'follows', 'game'): (torch.tensor([0, 1, 2]), torch.tensor([1, 2, 3])), ... ('user', 'plays', 'game'): (torch.tensor([1, 3]), torch.tensor([2, 3])) ... }) >>> g.edge_ids(torch.tensor([1]), torch.tensor([2]), etype='plays') tensor([0])
Use a canonical edge type instead when there is ambiguity for an edge type.
>>> g.edge_ids(torch.tensor([0, 1]), torch.tensor([1, 2]), ... etype=('user', 'follows', 'user')) tensor([0, 1]) >>> g.edge_ids(torch.tensor([1, 2]), torch.tensor([2, 3]), ... etype=('user', 'follows', 'game')) tensor([1, 2])