mlx-graphs 0.0.1__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- mlx_graphs/__init__.py +0 -0
- mlx_graphs/data/__init__.py +6 -0
- mlx_graphs/data/batch.py +201 -0
- mlx_graphs/data/collate.py +62 -0
- mlx_graphs/data/data.py +117 -0
- mlx_graphs/nn/__init__.py +5 -0
- mlx_graphs/nn/conv/__init__.py +4 -0
- mlx_graphs/nn/conv/gat_conv.py +174 -0
- mlx_graphs/nn/conv/gcn_conv.py +63 -0
- mlx_graphs/nn/conv/gin_conv.py +99 -0
- mlx_graphs/nn/conv/sage_conv.py +97 -0
- mlx_graphs/nn/graph_network_block.py +90 -0
- mlx_graphs/nn/linear.py +24 -0
- mlx_graphs/nn/message_passing.py +140 -0
- mlx_graphs/nn/pooling/__init__.py +5 -0
- mlx_graphs/nn/pooling/global_pooling.py +79 -0
- mlx_graphs/utils/__init__.py +8 -0
- mlx_graphs/utils/array_ops.py +47 -0
- mlx_graphs/utils/scatter.py +208 -0
- mlx_graphs/utils/sorting.py +46 -0
- mlx_graphs/utils/topology.py +103 -0
- mlx_graphs/utils/transformations.py +274 -0
- mlx_graphs/utils/validators.py +92 -0
- mlx_graphs-0.0.1.dist-info/LICENSE +21 -0
- mlx_graphs-0.0.1.dist-info/METADATA +120 -0
- mlx_graphs-0.0.1.dist-info/RECORD +28 -0
- mlx_graphs-0.0.1.dist-info/WHEEL +5 -0
- mlx_graphs-0.0.1.dist-info/top_level.txt +1 -0
mlx_graphs/__init__.py
ADDED
|
File without changes
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
# from .data import GraphData # noqa
|
|
2
|
+
# from .batch import (GraphDataBatch, batch, unbatch) # noqa
|
|
3
|
+
# from .collate import collate # noqa
|
|
4
|
+
|
|
5
|
+
# TODO: when uncommenting, this generates a circular import error, need tovfix that
|
|
6
|
+
# to import GraphData with from mlx_graphs.data import GraphData
|
mlx_graphs/data/batch.py
ADDED
|
@@ -0,0 +1,201 @@
|
|
|
1
|
+
from typing import Union
|
|
2
|
+
|
|
3
|
+
import mlx.core as mx
|
|
4
|
+
import numpy as np
|
|
5
|
+
|
|
6
|
+
from mlx_graphs.data.data import GraphData
|
|
7
|
+
from mlx_graphs.data.collate import collate
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
class GraphDataBatch(GraphData):
|
|
11
|
+
"""Concatenates multiple `GraphData` into a single unified `GraphDataBatch`
|
|
12
|
+
for efficient computation and parallelization over multiple graphs.
|
|
13
|
+
|
|
14
|
+
All graphs remain disconnected in the batch, meaning that any pairs of graphs
|
|
15
|
+
have no nodes or edges in common.
|
|
16
|
+
`GraphDataBatch` can be especially used to speed up graph classification tasks, where
|
|
17
|
+
multiple graphs can easily fit into memory and be processed in parallel.
|
|
18
|
+
|
|
19
|
+
Args:
|
|
20
|
+
graphs: List of `GraphData` objects to batch together
|
|
21
|
+
|
|
22
|
+
Example:
|
|
23
|
+
|
|
24
|
+
.. code-block:: python
|
|
25
|
+
|
|
26
|
+
graphs = [
|
|
27
|
+
GraphData(
|
|
28
|
+
edge_index=mx.array([[0, 0, 0], [1, 1, 1]]),
|
|
29
|
+
node_features=mx.zeros((3, 1)),
|
|
30
|
+
),
|
|
31
|
+
GraphData(
|
|
32
|
+
edge_index=mx.array([[1, 1, 1], [2, 2, 2]]),
|
|
33
|
+
node_features=mx.ones((3, 1)),
|
|
34
|
+
),
|
|
35
|
+
GraphData(
|
|
36
|
+
edge_index=mx.array([[3, 3, 3], [4, 4, 4]]),
|
|
37
|
+
node_features=mx.ones((3, 1)) * 2,
|
|
38
|
+
)
|
|
39
|
+
]
|
|
40
|
+
batch = GraphDataBatch(graphs)
|
|
41
|
+
|
|
42
|
+
>>> batch.num_graphs
|
|
43
|
+
3
|
|
44
|
+
|
|
45
|
+
>>> batch
|
|
46
|
+
GraphDataBatch(
|
|
47
|
+
edge_index=array([[0, 0, 0, 4, 4, 4, 9, 9, 9], [1, 1, 1, 5, 5, 5, 10, 10, 10]], dtype=int32),
|
|
48
|
+
node_features=array([[0.0], [0.0], [0.0], [1.0], [1.0], [1.0], [2.0], [2.0], [2.0]], dtype=float32))
|
|
49
|
+
|
|
50
|
+
>>> batch[1]
|
|
51
|
+
GraphData(
|
|
52
|
+
edge_index=array([[1, 1, 1], [2, 2, 2]], dtype=int32),
|
|
53
|
+
node_features=array([[1], [1], [1]], dtype=float32))
|
|
54
|
+
|
|
55
|
+
>>> batch[1:]
|
|
56
|
+
[
|
|
57
|
+
GraphData(
|
|
58
|
+
edge_index=array([[1, 1, 1], [2, 2, 2]], dtype=int32),
|
|
59
|
+
node_features=array([[1], [1], [1]], dtype=float32)),
|
|
60
|
+
GraphData(
|
|
61
|
+
edge_index=array([[3, 3, 3], [4, 4, 4]], dtype=int32),
|
|
62
|
+
node_features=array([[2], [2], [2]], dtype=float32))
|
|
63
|
+
]
|
|
64
|
+
"""
|
|
65
|
+
|
|
66
|
+
def __init__(self, graphs: list[GraphData], **kwargs) -> None:
|
|
67
|
+
batch_kwargs = collate(graphs)
|
|
68
|
+
super().__init__(_num_graphs=len(graphs), **batch_kwargs, **kwargs)
|
|
69
|
+
|
|
70
|
+
@property
|
|
71
|
+
def num_graphs(self):
|
|
72
|
+
"""Number of graphs in the batch."""
|
|
73
|
+
return self._num_graphs # provided via collate
|
|
74
|
+
|
|
75
|
+
@property
|
|
76
|
+
def batch_indices(self):
|
|
77
|
+
"""Mask indicating for each node its corresponding batch index."""
|
|
78
|
+
return self._batch_indices # provided via collate
|
|
79
|
+
|
|
80
|
+
def __getitem__(self, idx: Union[int, slice]) -> Union[GraphData, list[GraphData]]:
|
|
81
|
+
if isinstance(idx, int):
|
|
82
|
+
idx = self._handle_neg_index_if_needed(idx)
|
|
83
|
+
return self._get_graph(idx)
|
|
84
|
+
|
|
85
|
+
elif isinstance(idx, slice):
|
|
86
|
+
start, stop, step = (
|
|
87
|
+
idx.start or 0,
|
|
88
|
+
idx.stop or self._num_graphs,
|
|
89
|
+
idx.step or 1,
|
|
90
|
+
)
|
|
91
|
+
start = self._handle_neg_index_if_needed(start)
|
|
92
|
+
stop = self._handle_neg_index_if_needed(stop)
|
|
93
|
+
if stop < start:
|
|
94
|
+
raise IndexError(
|
|
95
|
+
"Batch slicing out of range (stop is greater than start)."
|
|
96
|
+
)
|
|
97
|
+
|
|
98
|
+
return [self._get_graph(i) for i in range(start, stop, step)]
|
|
99
|
+
|
|
100
|
+
elif isinstance(idx, (mx.array, list)):
|
|
101
|
+
if isinstance(idx, list):
|
|
102
|
+
idx = mx.array(idx)
|
|
103
|
+
|
|
104
|
+
if idx.ndim != 1:
|
|
105
|
+
raise ValueError(
|
|
106
|
+
"Batch indexing with mx.array only supports 1D index array."
|
|
107
|
+
)
|
|
108
|
+
|
|
109
|
+
idx = self._handle_neg_index_if_needed(idx)
|
|
110
|
+
return [self._get_graph(i) for i in idx]
|
|
111
|
+
|
|
112
|
+
raise TypeError("GraphDataBatch indices should be int or slice.")
|
|
113
|
+
|
|
114
|
+
def _get_graph(self, idx: int) -> GraphData:
|
|
115
|
+
"""Returns a `GraphData` from the batch with its original attributes and edge index."""
|
|
116
|
+
large_graph_dict = {
|
|
117
|
+
attr: getattr(self, attr)
|
|
118
|
+
for attr in self.to_dict()
|
|
119
|
+
if not attr.startswith("_")
|
|
120
|
+
}
|
|
121
|
+
|
|
122
|
+
single_graph_dict = {}
|
|
123
|
+
for attr in large_graph_dict:
|
|
124
|
+
from_idx, upto_idx = self._get_attr_slice_at_index(attr, idx)
|
|
125
|
+
attr_array = getattr(self, attr)
|
|
126
|
+
|
|
127
|
+
# Using mx.take_along_axis required indices with same number of dimensions as the values
|
|
128
|
+
# Singleton dimensions are thus added to all dimensions except the __concat__ dimension
|
|
129
|
+
gather_dim = self.to_dict()[f"_cat_dim_{attr}"]
|
|
130
|
+
broadcast_dim = [
|
|
131
|
+
-1 if dim == gather_dim else 1 for dim in range(attr_array.ndim)
|
|
132
|
+
]
|
|
133
|
+
range_at_dim = mx.arange(from_idx, upto_idx).reshape(broadcast_dim)
|
|
134
|
+
|
|
135
|
+
# Gather values at the current range on the __concat__ dimension
|
|
136
|
+
original_value = mx.take_along_axis(attr_array, range_at_dim, gather_dim)
|
|
137
|
+
|
|
138
|
+
# If __inc__ is True, we get back the original values by subtracting
|
|
139
|
+
# the cumulative sum at the batch index
|
|
140
|
+
if f"_inc_{attr}" in self.to_dict():
|
|
141
|
+
original_value -= self.to_dict()[f"_cumsum_{attr}"][idx]
|
|
142
|
+
|
|
143
|
+
single_graph_dict[attr] = original_value
|
|
144
|
+
|
|
145
|
+
return GraphData(**single_graph_dict)
|
|
146
|
+
|
|
147
|
+
def _get_attr_slice_at_index(self, attr: str, idx: int):
|
|
148
|
+
"""Returns the starting and ending index to retrieve the original attribute `attr`
|
|
149
|
+
from the batch, at the given index `idx`.
|
|
150
|
+
"""
|
|
151
|
+
attr_sizes = self.to_dict()[f"_size_{attr}"]
|
|
152
|
+
cum_attr_counts = mx.cumsum(mx.concatenate([mx.array([0]), attr_sizes]))
|
|
153
|
+
|
|
154
|
+
from_idx = cum_attr_counts[idx].item()
|
|
155
|
+
upto_idx = cum_attr_counts[idx + 1].item()
|
|
156
|
+
|
|
157
|
+
return from_idx, upto_idx
|
|
158
|
+
|
|
159
|
+
def _handle_neg_index_if_needed(self, index: Union[mx.array, list, int]):
|
|
160
|
+
"""Returns the corresponsing positive index or indices of negative batch indices.
|
|
161
|
+
Raises an index error if indices are incorrect. This method accepts either an mx.array,
|
|
162
|
+
a list or a single int index.
|
|
163
|
+
"""
|
|
164
|
+
if isinstance(index, int):
|
|
165
|
+
index = mx.array([index])
|
|
166
|
+
elif isinstance(index, mx.array):
|
|
167
|
+
index = index.tolist()
|
|
168
|
+
|
|
169
|
+
# Should be changed once boolean indexing exists in mlx
|
|
170
|
+
index = np.asarray(index)
|
|
171
|
+
index[index < 0] += self.num_graphs
|
|
172
|
+
|
|
173
|
+
if np.any((index < 0) | (index > self.num_graphs)):
|
|
174
|
+
raise IndexError("Batch indexing out of range.")
|
|
175
|
+
|
|
176
|
+
index = index.tolist()
|
|
177
|
+
return index[0] if len(index) == 1 else index
|
|
178
|
+
|
|
179
|
+
|
|
180
|
+
def batch(graphs: list[GraphData]) -> GraphDataBatch:
|
|
181
|
+
"""Constructs a `GraphDataBatch` object from a list of `GraphData`.
|
|
182
|
+
|
|
183
|
+
Args:
|
|
184
|
+
batch: List of `GraphData` to merge into a single batch
|
|
185
|
+
|
|
186
|
+
Returns:
|
|
187
|
+
`GraphDataBatch` storing a large batched graph
|
|
188
|
+
"""
|
|
189
|
+
return GraphDataBatch(graphs)
|
|
190
|
+
|
|
191
|
+
|
|
192
|
+
def unbatch(batch: GraphDataBatch) -> list[GraphData]:
|
|
193
|
+
"""Reconstructs a list of `GraphData` objects from a `GraphDataBatch`.
|
|
194
|
+
|
|
195
|
+
Args:
|
|
196
|
+
batch: `GraphDataBatch` to unbatch
|
|
197
|
+
|
|
198
|
+
Returns:
|
|
199
|
+
List of unbatched `GraphData`
|
|
200
|
+
"""
|
|
201
|
+
return [batch[idx] for idx in range(batch.num_graphs)]
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
import mlx.core as mx
|
|
2
|
+
|
|
3
|
+
from mlx_graphs.data.data import GraphData
|
|
4
|
+
from mlx_graphs.utils.validators import validate_list_of_graph_data
|
|
5
|
+
|
|
6
|
+
|
|
7
|
+
@validate_list_of_graph_data
|
|
8
|
+
def collate(graph_list: list[GraphData]) -> dict:
|
|
9
|
+
"""Concatenates attributes of multiple graphs based on the specifications
|
|
10
|
+
of each `GraphData`.
|
|
11
|
+
|
|
12
|
+
By default, concatenates all default array attributes in dim 0
|
|
13
|
+
apart from `edge_index` which is concatenated along dim 1.
|
|
14
|
+
Each graph remains independent in the final graph by incrementing
|
|
15
|
+
the indices in `edge_index` based on the cumsum of previous number
|
|
16
|
+
of nodes per graph.
|
|
17
|
+
|
|
18
|
+
Args:
|
|
19
|
+
graph_list: List of `GraphData` objects to collate
|
|
20
|
+
|
|
21
|
+
Returns:
|
|
22
|
+
Dict containing all the attributes of the unified and disconnected big graph as
|
|
23
|
+
well as the "private" attributes used behind the hood by the batching. These private
|
|
24
|
+
attributes start with an underscore "_" and can be ignore by the user.
|
|
25
|
+
"""
|
|
26
|
+
batch_attr_dict = {}
|
|
27
|
+
|
|
28
|
+
for attr in graph_list[0].to_dict():
|
|
29
|
+
__inc__ = graph_list[0].__inc__(key=attr)
|
|
30
|
+
__cat_dim__ = graph_list[0].__cat_dim__(key=attr)
|
|
31
|
+
|
|
32
|
+
cumsum: mx.array = None
|
|
33
|
+
if __inc__:
|
|
34
|
+
num_attr_list = [getattr(graph, "__inc__")(attr) for graph in graph_list]
|
|
35
|
+
cumsum = mx.cumsum(mx.array([0] + num_attr_list))
|
|
36
|
+
|
|
37
|
+
attr_list, attr_sizes = [], []
|
|
38
|
+
for i, graph in enumerate(graph_list):
|
|
39
|
+
attr_array = getattr(graph, attr)
|
|
40
|
+
|
|
41
|
+
if __inc__:
|
|
42
|
+
attr_array = attr_array + cumsum[i]
|
|
43
|
+
|
|
44
|
+
attr_list.append(attr_array)
|
|
45
|
+
attr_sizes.append(attr_array.shape[__cat_dim__])
|
|
46
|
+
|
|
47
|
+
# Private attributes are used later in batching for indexing
|
|
48
|
+
batch_attr_dict[f"_size_{attr}"] = mx.array(attr_sizes)
|
|
49
|
+
batch_attr_dict[f"_cat_dim_{attr}"] = __cat_dim__
|
|
50
|
+
if __inc__:
|
|
51
|
+
batch_attr_dict[f"_inc_{attr}"] = True
|
|
52
|
+
batch_attr_dict[f"_cumsum_{attr}"] = cumsum
|
|
53
|
+
|
|
54
|
+
if attr == "edge_index":
|
|
55
|
+
batch_indices = []
|
|
56
|
+
for i in range(len(cumsum) - 1):
|
|
57
|
+
batch_indices.extend([i] * (cumsum[i + 1] - cumsum[i]).item())
|
|
58
|
+
batch_attr_dict["_batch_indices"] = mx.array(batch_indices)
|
|
59
|
+
|
|
60
|
+
batch_attr_dict[attr] = mx.concatenate(attr_list, axis=__cat_dim__)
|
|
61
|
+
|
|
62
|
+
return batch_attr_dict
|
mlx_graphs/data/data.py
ADDED
|
@@ -0,0 +1,117 @@
|
|
|
1
|
+
from typing import Optional, Union
|
|
2
|
+
|
|
3
|
+
import mlx.core as mx
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
class GraphData:
|
|
7
|
+
"""
|
|
8
|
+
Represents a graph data object with optional features and labels.
|
|
9
|
+
|
|
10
|
+
Args:
|
|
11
|
+
edge_index: edge index representing the topology of
|
|
12
|
+
the graph, with shape [2, num_edges].
|
|
13
|
+
node_features: Array of shape [num_nodes, num_node_features]
|
|
14
|
+
containing the features of each node.
|
|
15
|
+
edge_features: Array of shape [num_edges, num_edge_features]
|
|
16
|
+
containing the features of each edge.
|
|
17
|
+
graph_features: Array of shape [num_graph_features]
|
|
18
|
+
containing the global features of the graph.
|
|
19
|
+
node_labels: Array of shape [num_nodes, num_node_labels]
|
|
20
|
+
containing the labels of each node.
|
|
21
|
+
edge_labels: Array of shape [num_edges, num_edge_labels]
|
|
22
|
+
containing the labels of each edge.
|
|
23
|
+
graph_labels: Array of shape [num_graph_labels]
|
|
24
|
+
containing the global labels of the graph.
|
|
25
|
+
**kwargs: Additional keyword arguments to store any other custom attributes.
|
|
26
|
+
"""
|
|
27
|
+
|
|
28
|
+
def __init__(
|
|
29
|
+
self,
|
|
30
|
+
edge_index: Optional[mx.array] = None,
|
|
31
|
+
node_features: Optional[mx.array] = None,
|
|
32
|
+
edge_features: Optional[mx.array] = None,
|
|
33
|
+
graph_features: Optional[mx.array] = None,
|
|
34
|
+
node_labels: Optional[mx.array] = None,
|
|
35
|
+
edge_labels: Optional[mx.array] = None,
|
|
36
|
+
graph_labels: Optional[mx.array] = None,
|
|
37
|
+
**kwargs,
|
|
38
|
+
):
|
|
39
|
+
self.edge_index = edge_index
|
|
40
|
+
self.node_features = node_features
|
|
41
|
+
self.edge_features = edge_features
|
|
42
|
+
self.graph_features = graph_features
|
|
43
|
+
self.node_labels = node_labels
|
|
44
|
+
self.edge_labels = edge_labels
|
|
45
|
+
self.graph_labels = graph_labels
|
|
46
|
+
for key, value in kwargs.items():
|
|
47
|
+
setattr(self, key, value)
|
|
48
|
+
|
|
49
|
+
def __repr__(self):
|
|
50
|
+
strings = []
|
|
51
|
+
for k, v in vars(self).items():
|
|
52
|
+
if v is not None and not k.startswith("_"):
|
|
53
|
+
if isinstance(v, mx.array):
|
|
54
|
+
strings.append(
|
|
55
|
+
f"{k}(shape={v.shape}, {str(v.dtype).split('.')[-1]})"
|
|
56
|
+
)
|
|
57
|
+
else:
|
|
58
|
+
strings.append(f"{k}={v}")
|
|
59
|
+
|
|
60
|
+
prefix = "\n\t"
|
|
61
|
+
return f"{type(self).__name__}({prefix + prefix.join(strings)})"
|
|
62
|
+
|
|
63
|
+
def to_dict(self) -> dict:
|
|
64
|
+
"""Converts the Data object to a dictionary.
|
|
65
|
+
|
|
66
|
+
Returns:
|
|
67
|
+
A dictionary with all attributes of the `GraphData` object.
|
|
68
|
+
"""
|
|
69
|
+
return {k: v for k, v in self.__dict__.items() if v is not None}
|
|
70
|
+
|
|
71
|
+
@property
|
|
72
|
+
def num_nodes(self) -> Union[int, None]:
|
|
73
|
+
"""Number of nodes in the graph."""
|
|
74
|
+
if self.node_features:
|
|
75
|
+
return self.node_features.shape[0]
|
|
76
|
+
return None
|
|
77
|
+
|
|
78
|
+
def __cat_dim__(self, key: str, *args, **kwargs) -> int:
|
|
79
|
+
"""This method can be overriden when batching is used with custom attributes.
|
|
80
|
+
Given the name of a custom attribute `key`, returns the dimension where the
|
|
81
|
+
concatenation happens during batching.
|
|
82
|
+
|
|
83
|
+
By default, all attribute names containing "index" will be concatenated on axis 1,
|
|
84
|
+
e.g. `edge_index`. Other attributes are concatenated on axis 0, e.g. node features.
|
|
85
|
+
|
|
86
|
+
Args:
|
|
87
|
+
key: Name of the attribute on which change the default concatenation dimension
|
|
88
|
+
while using batching.
|
|
89
|
+
|
|
90
|
+
Returns:
|
|
91
|
+
The dimension where concatenation will happen when batching.
|
|
92
|
+
"""
|
|
93
|
+
if "index" in key:
|
|
94
|
+
return 1
|
|
95
|
+
return 0
|
|
96
|
+
|
|
97
|
+
def __inc__(self, key: str, *args, **kwargs) -> Union[int, None]:
|
|
98
|
+
"""This method can be overriden when batching is used with custom attributes.
|
|
99
|
+
Given the name of a custom attribute `key`, returns an integer indicating the
|
|
100
|
+
incrementing value to apply to the elemnts of the attribute.
|
|
101
|
+
|
|
102
|
+
By default, all attribute names containing "index" will be incremented based on
|
|
103
|
+
the number of nodes in previous batches to avoid duplicate nodes in the index,
|
|
104
|
+
e.g. `edge_index`. Other attributes are cnot incremented and keep their original
|
|
105
|
+
values, e.g. node features.
|
|
106
|
+
If incrementation is not used, the return value should be set to `None`.
|
|
107
|
+
|
|
108
|
+
Args:
|
|
109
|
+
key: Name of the attribute on which change the default incrementation behavior
|
|
110
|
+
while using batching.
|
|
111
|
+
|
|
112
|
+
Returns:
|
|
113
|
+
Incrementing value for the given attribute or None.
|
|
114
|
+
"""
|
|
115
|
+
if "index" in key:
|
|
116
|
+
return len(self.node_features) if self.node_features is not None else None
|
|
117
|
+
return None
|
|
@@ -0,0 +1,174 @@
|
|
|
1
|
+
from typing import Optional
|
|
2
|
+
|
|
3
|
+
import mlx.core as mx
|
|
4
|
+
import mlx.nn as nn
|
|
5
|
+
|
|
6
|
+
from mlx_graphs.nn.linear import Linear
|
|
7
|
+
from mlx_graphs.nn.message_passing import MessagePassing
|
|
8
|
+
from mlx_graphs.utils import get_src_dst_features, scatter
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
class GATConv(MessagePassing):
|
|
12
|
+
"""Graph Attention Network convolution layer.
|
|
13
|
+
|
|
14
|
+
Args:
|
|
15
|
+
node_features_dim: Size of input node features
|
|
16
|
+
out_features_dim: Size of output node embeddings
|
|
17
|
+
heads: Number of attention heads
|
|
18
|
+
concat: Whether to use concat of heads or mean reduction
|
|
19
|
+
bias: Whether to use bias in the node projection
|
|
20
|
+
negative_slope: Slope for the leaky relu
|
|
21
|
+
dropout: Probability p for dropout
|
|
22
|
+
edge_features_dim: Size of edge features
|
|
23
|
+
|
|
24
|
+
Example:
|
|
25
|
+
|
|
26
|
+
.. code-block:: python
|
|
27
|
+
|
|
28
|
+
conv = GATConv(16, 32, heads=2, concat=True)
|
|
29
|
+
edge_index = mx.array([[0, 1, 2, 3, 4], [0, 0, 1, 1, 3]])
|
|
30
|
+
node_features = mx.random.uniform(low=0, high=1, shape=(5, 16))
|
|
31
|
+
|
|
32
|
+
h = conv(edge_index, node_features)
|
|
33
|
+
|
|
34
|
+
>>> h.shape
|
|
35
|
+
[5, 64]
|
|
36
|
+
"""
|
|
37
|
+
|
|
38
|
+
def __init__(
|
|
39
|
+
self,
|
|
40
|
+
node_features_dim: int,
|
|
41
|
+
out_features_dim: int,
|
|
42
|
+
heads: int = 1,
|
|
43
|
+
concat: bool = True,
|
|
44
|
+
bias: bool = True,
|
|
45
|
+
negative_slope: float = 0.2,
|
|
46
|
+
dropout: float = 0.0,
|
|
47
|
+
edge_features_dim: Optional[int] = None,
|
|
48
|
+
**kwargs,
|
|
49
|
+
):
|
|
50
|
+
kwargs.setdefault("aggr", "add")
|
|
51
|
+
super(GATConv, self).__init__(**kwargs)
|
|
52
|
+
|
|
53
|
+
self.out_features_dim = out_features_dim
|
|
54
|
+
self.heads = heads
|
|
55
|
+
self.concat = concat
|
|
56
|
+
self.negative_slope = negative_slope
|
|
57
|
+
|
|
58
|
+
self.lin_proj = Linear(node_features_dim, heads * out_features_dim, bias=False)
|
|
59
|
+
|
|
60
|
+
glorot_init = nn.init.glorot_uniform()
|
|
61
|
+
self.att_src = glorot_init(mx.zeros((1, heads, out_features_dim)))
|
|
62
|
+
self.att_dst = glorot_init(mx.zeros((1, heads, out_features_dim)))
|
|
63
|
+
|
|
64
|
+
if bias:
|
|
65
|
+
bias_shape = (heads * out_features_dim) if concat else (out_features_dim)
|
|
66
|
+
self.bias = mx.zeros(bias_shape)
|
|
67
|
+
|
|
68
|
+
if dropout > 0.0:
|
|
69
|
+
self.dropout = nn.Dropout(dropout)
|
|
70
|
+
|
|
71
|
+
if edge_features_dim is not None:
|
|
72
|
+
self.edge_lin_proj = Linear(
|
|
73
|
+
edge_features_dim, heads * out_features_dim, bias=False
|
|
74
|
+
)
|
|
75
|
+
self.edge_att = glorot_init(mx.zeros((1, heads, out_features_dim)))
|
|
76
|
+
|
|
77
|
+
def __call__(
|
|
78
|
+
self,
|
|
79
|
+
edge_index: mx.array,
|
|
80
|
+
node_features: mx.array,
|
|
81
|
+
edge_features: Optional[mx.array] = None,
|
|
82
|
+
) -> mx.array:
|
|
83
|
+
"""Computes the forward pass of GATConv.
|
|
84
|
+
|
|
85
|
+
Args:
|
|
86
|
+
edge_index: input edge index of shape `[2, num_edges]`
|
|
87
|
+
node_features: input node features
|
|
88
|
+
edge_features: edge features
|
|
89
|
+
|
|
90
|
+
Returns:
|
|
91
|
+
mx.array: computed node embeddings
|
|
92
|
+
"""
|
|
93
|
+
H, C = self.heads, self.out_features_dim
|
|
94
|
+
|
|
95
|
+
src_feats = dst_feats = self.lin_proj(node_features).reshape(-1, H, C)
|
|
96
|
+
|
|
97
|
+
alpha_src = (src_feats * self.att_src).sum(-1)
|
|
98
|
+
alpha_dst = (dst_feats * self.att_dst).sum(-1)
|
|
99
|
+
|
|
100
|
+
alpha_src, alpha_dst = get_src_dst_features(edge_index, (alpha_src, alpha_dst))
|
|
101
|
+
dst_idx = edge_index[1]
|
|
102
|
+
|
|
103
|
+
node_features = self.propagate(
|
|
104
|
+
node_features=(src_feats, dst_feats),
|
|
105
|
+
edge_index=edge_index,
|
|
106
|
+
message_kwargs={
|
|
107
|
+
"alpha_src": alpha_src,
|
|
108
|
+
"alpha_dst": alpha_dst,
|
|
109
|
+
"index": dst_idx,
|
|
110
|
+
"edge_features": edge_features,
|
|
111
|
+
},
|
|
112
|
+
)
|
|
113
|
+
|
|
114
|
+
if self.concat:
|
|
115
|
+
node_features = node_features.reshape(
|
|
116
|
+
-1, self.heads * self.out_features_dim
|
|
117
|
+
)
|
|
118
|
+
else:
|
|
119
|
+
node_features = mx.mean(node_features, axis=1)
|
|
120
|
+
|
|
121
|
+
if "bias" in self:
|
|
122
|
+
node_features = node_features + self.bias
|
|
123
|
+
|
|
124
|
+
return node_features
|
|
125
|
+
|
|
126
|
+
def message(
|
|
127
|
+
self,
|
|
128
|
+
src_features: mx.array,
|
|
129
|
+
dst_features: mx.array,
|
|
130
|
+
alpha_src: mx.array = None,
|
|
131
|
+
alpha_dst: mx.array = None,
|
|
132
|
+
index: mx.array = None,
|
|
133
|
+
edge_features: Optional[mx.array] = None,
|
|
134
|
+
) -> mx.array:
|
|
135
|
+
"""Computes a message for each edge in the graph following GAT's propagation rule.
|
|
136
|
+
|
|
137
|
+
Args:
|
|
138
|
+
src_features: Features of the source nodes.
|
|
139
|
+
dst_features: Features of the destination nodes (not used in this function but included for compatibility).
|
|
140
|
+
alpha_src: Precomputed attention values for the source nodes.
|
|
141
|
+
alpha_dst: Precomputed attention values for the destination nodes.
|
|
142
|
+
index: 1D array with indices of either src or dst nodes to compute softmax.
|
|
143
|
+
edge_features: Features of the edges in the graph.
|
|
144
|
+
|
|
145
|
+
Returns:
|
|
146
|
+
mx.array: The computed messages for each edge in the graph.
|
|
147
|
+
"""
|
|
148
|
+
alpha = alpha_src + alpha_dst
|
|
149
|
+
|
|
150
|
+
if edge_features is not None:
|
|
151
|
+
alpha_edge = self._compute_alpha_edge_features(edge_features)
|
|
152
|
+
alpha = alpha + alpha_edge
|
|
153
|
+
|
|
154
|
+
alpha = nn.leaky_relu(alpha, self.negative_slope)
|
|
155
|
+
alpha = scatter(alpha, index, self.num_nodes, aggr="softmax")
|
|
156
|
+
|
|
157
|
+
if "dropout" in self:
|
|
158
|
+
alpha = self.dropout(alpha)
|
|
159
|
+
|
|
160
|
+
return mx.expand_dims(alpha, -1) * src_features
|
|
161
|
+
|
|
162
|
+
def _compute_alpha_edge_features(self, edge_features: mx.array):
|
|
163
|
+
assert all(
|
|
164
|
+
layer in self for layer in ["edge_lin_proj", "edge_att"]
|
|
165
|
+
), "Using edge features, GATConv layer should be provided argument `edge_features_dim`."
|
|
166
|
+
|
|
167
|
+
if edge_features.ndim == 1:
|
|
168
|
+
edge_features = edge_features.reshape(-1, 1)
|
|
169
|
+
|
|
170
|
+
edge_features = self.edge_lin_proj(edge_features)
|
|
171
|
+
edge_features = edge_features.reshape(-1, self.heads, self.out_features_dim)
|
|
172
|
+
alpha_edge = (edge_features * self.edge_att).sum(axis=-1)
|
|
173
|
+
|
|
174
|
+
return alpha_edge
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
from typing import Any, Optional
|
|
2
|
+
|
|
3
|
+
import mlx.core as mx
|
|
4
|
+
import mlx.nn as nn
|
|
5
|
+
|
|
6
|
+
from mlx_graphs.nn.message_passing import MessagePassing
|
|
7
|
+
from mlx_graphs.utils import degree, invert_sqrt_degree
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
class GCNConv(MessagePassing):
|
|
11
|
+
"""Applies a GCN convolution over input node features.
|
|
12
|
+
|
|
13
|
+
Args:
|
|
14
|
+
node_features_dim: size of input node features
|
|
15
|
+
out_features_dim: size of output node embeddings
|
|
16
|
+
bias: whether to use bias in the node projection
|
|
17
|
+
"""
|
|
18
|
+
|
|
19
|
+
def __init__(
|
|
20
|
+
self,
|
|
21
|
+
node_features_dim: int,
|
|
22
|
+
out_features_dim: int,
|
|
23
|
+
bias: bool = True,
|
|
24
|
+
**kwargs,
|
|
25
|
+
):
|
|
26
|
+
kwargs.setdefault("aggr", "add")
|
|
27
|
+
super(GCNConv, self).__init__(**kwargs)
|
|
28
|
+
|
|
29
|
+
self.linear = nn.Linear(node_features_dim, out_features_dim, bias)
|
|
30
|
+
|
|
31
|
+
def __call__(
|
|
32
|
+
self,
|
|
33
|
+
edge_index: mx.array,
|
|
34
|
+
node_features: mx.array,
|
|
35
|
+
edge_weights: Optional[mx.array] = None,
|
|
36
|
+
normalize: bool = True,
|
|
37
|
+
**kwargs: Any,
|
|
38
|
+
) -> mx.array:
|
|
39
|
+
assert edge_index.shape[0] == 2, "edge_index must have shape (2, num_edges)"
|
|
40
|
+
assert (
|
|
41
|
+
edge_index[1].size > 0
|
|
42
|
+
), "'col' component of edge_index should not be empty"
|
|
43
|
+
|
|
44
|
+
node_features = self.linear(node_features)
|
|
45
|
+
|
|
46
|
+
row, col = edge_index
|
|
47
|
+
|
|
48
|
+
# Compute node degree normalization for the mean aggregation.
|
|
49
|
+
norm: mx.array = None
|
|
50
|
+
if normalize:
|
|
51
|
+
deg = degree(col, node_features.shape[0], edge_weights=edge_weights)
|
|
52
|
+
# NOTE : need boolean indexing in order to zero out inf values
|
|
53
|
+
deg_inv_sqrt = invert_sqrt_degree(deg)
|
|
54
|
+
norm = deg_inv_sqrt[row] * deg_inv_sqrt[col]
|
|
55
|
+
|
|
56
|
+
# Compute messages and aggregate them with sum and norm.
|
|
57
|
+
node_features = self.propagate(
|
|
58
|
+
edge_index=edge_index,
|
|
59
|
+
node_features=node_features,
|
|
60
|
+
message_kwargs={"edge_weights": norm},
|
|
61
|
+
)
|
|
62
|
+
|
|
63
|
+
return node_features
|