impulse-graph 0.10.0__cp313-cp313-win_amd64.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.
- impulse_graph/__init__.py +755 -0
- impulse_graph/_impulse_native.cp313-win_amd64.pyd +0 -0
- impulse_graph/cypher.py +154 -0
- impulse_graph/traversal.py +445 -0
- impulse_graph/vm.py +610 -0
- impulse_graph-0.10.0.dist-info/METADATA +208 -0
- impulse_graph-0.10.0.dist-info/RECORD +9 -0
- impulse_graph-0.10.0.dist-info/WHEEL +5 -0
- impulse_graph-0.10.0.dist-info/top_level.txt +1 -0
|
@@ -0,0 +1,755 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Impulse Graph Engine Python SDK & C++ Bytecode VM Binding
|
|
3
|
+
Spec v0.9.0
|
|
4
|
+
"""
|
|
5
|
+
|
|
6
|
+
from typing import Dict, List, Optional, Union
|
|
7
|
+
|
|
8
|
+
import numpy as np
|
|
9
|
+
|
|
10
|
+
try:
|
|
11
|
+
from ._impulse_native import Snapshot as _NativeSnapshot
|
|
12
|
+
from ._impulse_native import Writer as _NativeWriter
|
|
13
|
+
except ImportError:
|
|
14
|
+
try:
|
|
15
|
+
from _impulse_native import Snapshot as _NativeSnapshot
|
|
16
|
+
from _impulse_native import Writer as _NativeWriter
|
|
17
|
+
except ImportError:
|
|
18
|
+
_NativeSnapshot = None
|
|
19
|
+
_NativeWriter = None
|
|
20
|
+
|
|
21
|
+
from . import vm
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
class DomainView:
|
|
25
|
+
"""
|
|
26
|
+
Domain Anchor Context representing a specific entity domain (e.g. User, Product).
|
|
27
|
+
"""
|
|
28
|
+
|
|
29
|
+
def __init__(
|
|
30
|
+
self,
|
|
31
|
+
snapshot: "Snapshot",
|
|
32
|
+
domain_id: int,
|
|
33
|
+
domain_name: str,
|
|
34
|
+
node_count: int = 0,
|
|
35
|
+
key_type: int = 1,
|
|
36
|
+
catalog: Optional[Union[str, Dict[str, int]]] = None,
|
|
37
|
+
):
|
|
38
|
+
self._snapshot = snapshot
|
|
39
|
+
self.domain_id = domain_id
|
|
40
|
+
self.domain_name = domain_name
|
|
41
|
+
self.node_count = node_count
|
|
42
|
+
self.key_type = key_type
|
|
43
|
+
self._catalog = catalog
|
|
44
|
+
|
|
45
|
+
def from_node(self, node_id: int) -> "Traversal":
|
|
46
|
+
from .traversal import Traversal
|
|
47
|
+
|
|
48
|
+
return Traversal(
|
|
49
|
+
self._snapshot, start_node=node_id, initial_domain=self, catalog=self._catalog
|
|
50
|
+
)
|
|
51
|
+
|
|
52
|
+
def from_nodes(self, node_ids: Union[List[int], np.ndarray]) -> "Traversal":
|
|
53
|
+
from .traversal import Traversal
|
|
54
|
+
|
|
55
|
+
return Traversal(
|
|
56
|
+
self._snapshot, start_nodes=node_ids, initial_domain=self, catalog=self._catalog
|
|
57
|
+
)
|
|
58
|
+
|
|
59
|
+
def all(self) -> "Traversal":
|
|
60
|
+
from .traversal import Traversal
|
|
61
|
+
|
|
62
|
+
return Traversal(self._snapshot, all_nodes=True, initial_domain=self, catalog=self._catalog)
|
|
63
|
+
|
|
64
|
+
def to_dense_id(self, key: str) -> int:
|
|
65
|
+
return self._snapshot.resolve_dense_id(self.domain_id, key)
|
|
66
|
+
|
|
67
|
+
def to_key(self, node_id: int) -> str:
|
|
68
|
+
try:
|
|
69
|
+
raw = self._snapshot.resolve_key(self.domain_id, node_id)
|
|
70
|
+
return (
|
|
71
|
+
raw.decode("utf-8", errors="replace")
|
|
72
|
+
if isinstance(raw, (bytes, bytearray))
|
|
73
|
+
else str(raw)
|
|
74
|
+
)
|
|
75
|
+
except Exception:
|
|
76
|
+
return f"{self.domain_name}::{node_id}"
|
|
77
|
+
|
|
78
|
+
def from_key(self, key: str) -> "Traversal":
|
|
79
|
+
return self.from_node(self.to_dense_id(key))
|
|
80
|
+
|
|
81
|
+
def from_keys(self, keys: List[str]) -> "Traversal":
|
|
82
|
+
return self.from_nodes([self.to_dense_id(k) for k in keys])
|
|
83
|
+
|
|
84
|
+
|
|
85
|
+
class Snapshot:
|
|
86
|
+
"""
|
|
87
|
+
Managed wrapper for an off-heap zero-copy memory-mapped Impulse Graph Binary Snapshot (.imps).
|
|
88
|
+
"""
|
|
89
|
+
|
|
90
|
+
def __init__(self, path: str, catalog: Optional[Union[str, Dict[str, int]]] = None):
|
|
91
|
+
if _NativeSnapshot is None:
|
|
92
|
+
raise RuntimeError("_impulse_native extension is not compiled.")
|
|
93
|
+
self._native = _NativeSnapshot(path)
|
|
94
|
+
self._auto_catalog: Dict[str, int] = {}
|
|
95
|
+
try:
|
|
96
|
+
for idx in range(self._native.relation_count()):
|
|
97
|
+
rel_info = self._native.get_relation(idx)
|
|
98
|
+
rel_name = rel_info.get("name")
|
|
99
|
+
if rel_name:
|
|
100
|
+
self._auto_catalog[rel_name] = idx
|
|
101
|
+
except Exception:
|
|
102
|
+
pass
|
|
103
|
+
self._catalog = catalog if catalog is not None else (self._auto_catalog or None)
|
|
104
|
+
self._default_ctx = None
|
|
105
|
+
self._default_state = None
|
|
106
|
+
|
|
107
|
+
def __enter__(self):
|
|
108
|
+
return self
|
|
109
|
+
|
|
110
|
+
def __exit__(self, exc_type, exc_val, exc_tb):
|
|
111
|
+
self.close()
|
|
112
|
+
|
|
113
|
+
def _check_open(self):
|
|
114
|
+
if self._native is None:
|
|
115
|
+
raise RuntimeError("Snapshot is closed")
|
|
116
|
+
|
|
117
|
+
def close(self):
|
|
118
|
+
if self._default_ctx is not None:
|
|
119
|
+
self._default_ctx.destroy()
|
|
120
|
+
self._default_ctx = None
|
|
121
|
+
self._default_state = None
|
|
122
|
+
if self._native is not None:
|
|
123
|
+
self._native.close()
|
|
124
|
+
self._native = None
|
|
125
|
+
|
|
126
|
+
def _get_default_vm(self):
|
|
127
|
+
self._check_open()
|
|
128
|
+
if self._default_ctx is None:
|
|
129
|
+
self._default_ctx = vm.VmContext(self)
|
|
130
|
+
self._default_state = vm.VmState()
|
|
131
|
+
else:
|
|
132
|
+
self._default_ctx.reset()
|
|
133
|
+
self._default_state.reset()
|
|
134
|
+
return self._default_ctx, self._default_state
|
|
135
|
+
|
|
136
|
+
@property
|
|
137
|
+
def default_context(self) -> vm.VmContext:
|
|
138
|
+
self._check_open()
|
|
139
|
+
if self._default_ctx is None:
|
|
140
|
+
self._get_default_vm()
|
|
141
|
+
return self._default_ctx
|
|
142
|
+
|
|
143
|
+
@property
|
|
144
|
+
def default_state(self) -> vm.VmState:
|
|
145
|
+
self._check_open()
|
|
146
|
+
if self._default_state is None:
|
|
147
|
+
self._get_default_vm()
|
|
148
|
+
return self._default_state
|
|
149
|
+
|
|
150
|
+
def domain_count(self) -> int:
|
|
151
|
+
self._check_open()
|
|
152
|
+
return self._native.domain_count()
|
|
153
|
+
|
|
154
|
+
def get_domain(self, index: int) -> dict:
|
|
155
|
+
self._check_open()
|
|
156
|
+
return self._native.get_domain(index)
|
|
157
|
+
|
|
158
|
+
def domain(
|
|
159
|
+
self, name_or_id: Union[str, int], catalog: Optional[Union[str, Dict[str, int]]] = None
|
|
160
|
+
) -> DomainView:
|
|
161
|
+
self._check_open()
|
|
162
|
+
effective_catalog = catalog if catalog is not None else self._catalog
|
|
163
|
+
if isinstance(name_or_id, int):
|
|
164
|
+
count = self.domain_count()
|
|
165
|
+
for i in range(count):
|
|
166
|
+
dom_info = self.get_domain(i)
|
|
167
|
+
if dom_info["domain_id"] == name_or_id:
|
|
168
|
+
return DomainView(
|
|
169
|
+
self,
|
|
170
|
+
domain_id=dom_info["domain_id"],
|
|
171
|
+
domain_name=dom_info["name"],
|
|
172
|
+
node_count=dom_info.get("node_count", 0),
|
|
173
|
+
key_type=dom_info["key_type"],
|
|
174
|
+
catalog=effective_catalog,
|
|
175
|
+
)
|
|
176
|
+
raise KeyError(f"Domain ID {name_or_id} not found in snapshot catalog.")
|
|
177
|
+
elif isinstance(name_or_id, str):
|
|
178
|
+
count = self.domain_count()
|
|
179
|
+
for i in range(count):
|
|
180
|
+
dom_info = self.get_domain(i)
|
|
181
|
+
if dom_info["name"] == name_or_id:
|
|
182
|
+
return DomainView(
|
|
183
|
+
self,
|
|
184
|
+
domain_id=dom_info["domain_id"],
|
|
185
|
+
domain_name=dom_info["name"],
|
|
186
|
+
node_count=dom_info.get("node_count", 0),
|
|
187
|
+
key_type=dom_info["key_type"],
|
|
188
|
+
catalog=effective_catalog,
|
|
189
|
+
)
|
|
190
|
+
raise KeyError(f"Domain '{name_or_id}' not found in snapshot catalog.")
|
|
191
|
+
raise TypeError(f"domain() argument must be str or int, got {type(name_or_id).__name__}")
|
|
192
|
+
|
|
193
|
+
def relation_count(self) -> int:
|
|
194
|
+
self._check_open()
|
|
195
|
+
return self._native.relation_count()
|
|
196
|
+
|
|
197
|
+
def get_relation(self, index: int) -> dict:
|
|
198
|
+
self._check_open()
|
|
199
|
+
return self._native.get_relation(index)
|
|
200
|
+
|
|
201
|
+
def is_reachable(self, relation_index: int, src_id: int, tgt_id: int) -> bool:
|
|
202
|
+
self._check_open()
|
|
203
|
+
return self._native.is_reachable(relation_index, src_id, tgt_id)
|
|
204
|
+
|
|
205
|
+
def resolve_key(self, domain_id: int, node_id: int) -> bytes:
|
|
206
|
+
self._check_open()
|
|
207
|
+
return self._native.resolve_key(domain_id, node_id)
|
|
208
|
+
|
|
209
|
+
def resolve_dense_id(self, domain_id: int, key: str) -> int:
|
|
210
|
+
self._check_open()
|
|
211
|
+
return self._native.resolve_dense_id(domain_id, key)
|
|
212
|
+
|
|
213
|
+
def resolve_keys_batch(
|
|
214
|
+
self, domain_id: int, node_ids: Union[List[int], np.ndarray]
|
|
215
|
+
) -> List[str]:
|
|
216
|
+
"""Resolve a batch of dense node IDs back to string identifiers."""
|
|
217
|
+
self._check_open()
|
|
218
|
+
result = []
|
|
219
|
+
for nid in node_ids:
|
|
220
|
+
try:
|
|
221
|
+
k_bytes = self.resolve_key(domain_id, int(nid))
|
|
222
|
+
result.append(k_bytes.decode("utf-8", errors="replace"))
|
|
223
|
+
except Exception:
|
|
224
|
+
result.append(f"Node::{nid}")
|
|
225
|
+
return result
|
|
226
|
+
|
|
227
|
+
def get_row_offsets_array(self, relation_index: int = 0) -> np.ndarray:
|
|
228
|
+
"""Zero-copy memoryview into CSR row offsets uint32 array."""
|
|
229
|
+
self._check_open()
|
|
230
|
+
mv = self._native.get_csr_row_offsets(relation_index)
|
|
231
|
+
return np.frombuffer(mv, dtype=np.uint32)
|
|
232
|
+
|
|
233
|
+
def get_col_indices_array(self, relation_index: int = 0) -> np.ndarray:
|
|
234
|
+
"""Zero-copy memoryview into CSR column indices uint32 array."""
|
|
235
|
+
self._check_open()
|
|
236
|
+
mv = self._native.get_csr_col_indices(relation_index)
|
|
237
|
+
return np.frombuffer(mv, dtype=np.uint32)
|
|
238
|
+
|
|
239
|
+
def get_csc_row_offsets_array(self, relation_index: int = 0) -> np.ndarray:
|
|
240
|
+
"""Zero-copy memoryview into inverse CSC row offsets uint32 array."""
|
|
241
|
+
self._check_open()
|
|
242
|
+
mv = self._native.get_csc_row_offsets(relation_index)
|
|
243
|
+
return np.frombuffer(mv, dtype=np.uint32)
|
|
244
|
+
|
|
245
|
+
def get_csc_col_indices_array(self, relation_index: int = 0) -> np.ndarray:
|
|
246
|
+
"""Zero-copy memoryview into inverse CSC column indices uint32 array."""
|
|
247
|
+
self._check_open()
|
|
248
|
+
mv = self._native.get_csc_col_indices(relation_index)
|
|
249
|
+
return np.frombuffer(mv, dtype=np.uint32)
|
|
250
|
+
|
|
251
|
+
def get_attribute_array(
|
|
252
|
+
self,
|
|
253
|
+
relation_index: int = 0,
|
|
254
|
+
attribute_index: int = 0,
|
|
255
|
+
dtype=np.float32,
|
|
256
|
+
shape: Optional[tuple] = None,
|
|
257
|
+
) -> np.ndarray:
|
|
258
|
+
"""
|
|
259
|
+
Zero-copy memoryview into columnar Structure-of-Arrays (SoA) attribute section.
|
|
260
|
+
Supports 1D scalar attributes or 2D (N x D) embedding matrices.
|
|
261
|
+
"""
|
|
262
|
+
self._check_open()
|
|
263
|
+
mv = self._native.get_attribute_data(relation_index, attribute_index)
|
|
264
|
+
arr = np.frombuffer(mv, dtype=dtype)
|
|
265
|
+
if shape is not None:
|
|
266
|
+
return arr.reshape(shape)
|
|
267
|
+
return arr
|
|
268
|
+
|
|
269
|
+
def get_attribute_offsets_array(
|
|
270
|
+
self, relation_index: int = 0, attribute_index: int = 0
|
|
271
|
+
) -> Optional[np.ndarray]:
|
|
272
|
+
"""Zero-copy memoryview into variable-length attribute offsets uint32 array."""
|
|
273
|
+
self._check_open()
|
|
274
|
+
mv = self._native.get_attribute_offsets(relation_index, attribute_index)
|
|
275
|
+
if mv is None:
|
|
276
|
+
return None
|
|
277
|
+
return np.frombuffer(mv, dtype=np.uint32)
|
|
278
|
+
|
|
279
|
+
def get_attribute_info(
|
|
280
|
+
self, relation_index: int = 0, attribute_index: int = 0
|
|
281
|
+
) -> dict:
|
|
282
|
+
"""Get attribute type_code, dimension, and byte sizes."""
|
|
283
|
+
self._check_open()
|
|
284
|
+
return self._native.get_attribute_info(relation_index, attribute_index)
|
|
285
|
+
|
|
286
|
+
def get_string_attribute(
|
|
287
|
+
self, relation_index: int = 0, attribute_index: int = 0, index: int = 0
|
|
288
|
+
) -> str:
|
|
289
|
+
"""Retrieve a single string attribute by index using variable-length offsets."""
|
|
290
|
+
self._check_open()
|
|
291
|
+
offsets = self.get_attribute_offsets_array(relation_index, attribute_index)
|
|
292
|
+
data = self._native.get_attribute_data(relation_index, attribute_index)
|
|
293
|
+
data_bytes = bytes(data)
|
|
294
|
+
if offsets is not None:
|
|
295
|
+
if index + 1 >= len(offsets):
|
|
296
|
+
raise IndexError(f"Attribute index {index} out of range (max {len(offsets) - 2})")
|
|
297
|
+
start = int(offsets[index])
|
|
298
|
+
end = int(offsets[index + 1])
|
|
299
|
+
return data_bytes[start:end].decode("utf-8", errors="replace")
|
|
300
|
+
return data_bytes.decode("utf-8", errors="replace")
|
|
301
|
+
|
|
302
|
+
def get_string_attributes(
|
|
303
|
+
self, relation_index: int = 0, attribute_index: int = 0
|
|
304
|
+
) -> List[str]:
|
|
305
|
+
"""Retrieve all strings for a variable-length string attribute."""
|
|
306
|
+
self._check_open()
|
|
307
|
+
offsets = self.get_attribute_offsets_array(relation_index, attribute_index)
|
|
308
|
+
data = self._native.get_attribute_data(relation_index, attribute_index)
|
|
309
|
+
data_bytes = bytes(data)
|
|
310
|
+
if offsets is not None:
|
|
311
|
+
res = []
|
|
312
|
+
for i in range(len(offsets) - 1):
|
|
313
|
+
start = int(offsets[i])
|
|
314
|
+
end = int(offsets[i + 1])
|
|
315
|
+
res.append(data_bytes[start:end].decode("utf-8", errors="replace"))
|
|
316
|
+
return res
|
|
317
|
+
return [data_bytes.decode("utf-8", errors="replace")]
|
|
318
|
+
|
|
319
|
+
def sample_neighbors(
|
|
320
|
+
self,
|
|
321
|
+
relation_index: int,
|
|
322
|
+
nodes: Union[List[int], np.ndarray],
|
|
323
|
+
k_samples: int,
|
|
324
|
+
seed: int = 42,
|
|
325
|
+
) -> tuple[np.ndarray, np.ndarray]:
|
|
326
|
+
"""High-speed SIMD C++ neighborhood sampler for GNN mini-batching."""
|
|
327
|
+
self._check_open()
|
|
328
|
+
if isinstance(nodes, np.ndarray):
|
|
329
|
+
nodes_list = nodes.astype(np.uint64).tolist()
|
|
330
|
+
else:
|
|
331
|
+
nodes_list = [int(x) for x in nodes]
|
|
332
|
+
return self._native.sample_neighbors(relation_index, nodes_list, k_samples, seed)
|
|
333
|
+
|
|
334
|
+
def execute_query(self, query: vm.CompiledQuery, input_param: int = 0) -> vm.QueryResult:
|
|
335
|
+
self._check_open()
|
|
336
|
+
native_query = getattr(query, "_native", query)
|
|
337
|
+
return vm.QueryResult(self._native.execute_query(native_query, input_param))
|
|
338
|
+
|
|
339
|
+
def traverse(self, start_node: int = 0, catalog: Union[str, dict] | None = None) -> "Traversal":
|
|
340
|
+
"""Initiate a friendly fluent graph path traversal starting from start_node."""
|
|
341
|
+
self._check_open()
|
|
342
|
+
from .traversal import Traversal
|
|
343
|
+
|
|
344
|
+
effective_catalog = catalog if catalog is not None else self._catalog
|
|
345
|
+
return Traversal(self, start_node=start_node, catalog=effective_catalog)
|
|
346
|
+
|
|
347
|
+
def cypher(
|
|
348
|
+
self,
|
|
349
|
+
query: str,
|
|
350
|
+
params: dict | None = None,
|
|
351
|
+
catalog: Union[str, dict] | None = None,
|
|
352
|
+
) -> Union[List[int], int]:
|
|
353
|
+
"""Execute a declarative openCypher query directly against the snapshot off-heap."""
|
|
354
|
+
self._check_open()
|
|
355
|
+
from .cypher import CypherQuery
|
|
356
|
+
|
|
357
|
+
effective_catalog = catalog if catalog is not None else self._catalog
|
|
358
|
+
c_query = CypherQuery(query, catalog=effective_catalog)
|
|
359
|
+
return c_query.execute(self, params=params)
|
|
360
|
+
|
|
361
|
+
def compile_cypher(
|
|
362
|
+
self,
|
|
363
|
+
query: str,
|
|
364
|
+
catalog: Union[str, dict] | None = None,
|
|
365
|
+
) -> "Traversal":
|
|
366
|
+
"""Compile a declarative openCypher query into a reusable Traversal / VM executable."""
|
|
367
|
+
self._check_open()
|
|
368
|
+
from .cypher import CypherQuery
|
|
369
|
+
|
|
370
|
+
effective_catalog = catalog if catalog is not None else self._catalog
|
|
371
|
+
c_query = CypherQuery(query, catalog=effective_catalog)
|
|
372
|
+
return c_query.build_traversal(self)
|
|
373
|
+
|
|
374
|
+
def _relation_shape(self, relation_index: int, transpose: bool = False) -> tuple[int, int]:
|
|
375
|
+
rel = self.get_relation(relation_index)
|
|
376
|
+
src_count = rel["node_count"]
|
|
377
|
+
tgt_count = rel["node_count"]
|
|
378
|
+
try:
|
|
379
|
+
src_dom = self.domain(int(rel["src_domain_id"]))
|
|
380
|
+
if src_dom.node_count > 0:
|
|
381
|
+
src_count = src_dom.node_count
|
|
382
|
+
except Exception:
|
|
383
|
+
pass
|
|
384
|
+
try:
|
|
385
|
+
tgt_dom = self.domain(int(rel["tgt_domain_id"]))
|
|
386
|
+
if tgt_dom.node_count > 0:
|
|
387
|
+
tgt_count = tgt_dom.node_count
|
|
388
|
+
except Exception:
|
|
389
|
+
pass
|
|
390
|
+
return (tgt_count, src_count) if transpose else (src_count, tgt_count)
|
|
391
|
+
|
|
392
|
+
def to_scipy_csr(self, relation_index: int = 0, transpose: bool = False):
|
|
393
|
+
"""
|
|
394
|
+
Convert snapshot topology to a scipy.sparse.csr_matrix or csc_matrix.
|
|
395
|
+
Uses zero-copy off-heap pointers.
|
|
396
|
+
"""
|
|
397
|
+
import scipy.sparse as sp
|
|
398
|
+
|
|
399
|
+
if transpose:
|
|
400
|
+
try:
|
|
401
|
+
indptr = self.get_csc_row_offsets_array(relation_index)
|
|
402
|
+
indices = self.get_csc_col_indices_array(relation_index)
|
|
403
|
+
except Exception:
|
|
404
|
+
# Transpose forward CSR if CSC is not compiled in file
|
|
405
|
+
forward = self.to_scipy_csr(relation_index, transpose=False)
|
|
406
|
+
return forward.transpose().tocsr()
|
|
407
|
+
_, cols = self._relation_shape(relation_index, transpose=True)
|
|
408
|
+
rows = len(indptr) - 1 if len(indptr) > 0 else 0
|
|
409
|
+
if len(indices) > 0:
|
|
410
|
+
cols = max(cols, int(indices.max()) + 1)
|
|
411
|
+
data = np.ones(len(indices), dtype=np.float32)
|
|
412
|
+
return sp.csr_matrix((data, indices, indptr), shape=(rows, cols))
|
|
413
|
+
|
|
414
|
+
indptr = self.get_row_offsets_array(relation_index)
|
|
415
|
+
indices = self.get_col_indices_array(relation_index)
|
|
416
|
+
_, cols = self._relation_shape(relation_index, transpose=False)
|
|
417
|
+
rows = len(indptr) - 1 if len(indptr) > 0 else 0
|
|
418
|
+
if len(indices) > 0:
|
|
419
|
+
cols = max(cols, int(indices.max()) + 1)
|
|
420
|
+
data = np.ones(len(indices), dtype=np.float32)
|
|
421
|
+
return sp.csr_matrix((data, indices, indptr), shape=(rows, cols))
|
|
422
|
+
|
|
423
|
+
def to_torch_csr(self, relation_index: int = 0, transpose: bool = False, device: str = "cpu"):
|
|
424
|
+
"""
|
|
425
|
+
Convert snapshot CSR topology to a torch.sparse_csr_tensor.
|
|
426
|
+
Safe for zero-copy read-only inference.
|
|
427
|
+
"""
|
|
428
|
+
import torch
|
|
429
|
+
|
|
430
|
+
if transpose:
|
|
431
|
+
try:
|
|
432
|
+
crow_np = self.get_csc_row_offsets_array(relation_index)
|
|
433
|
+
col_np = self.get_csc_col_indices_array(relation_index)
|
|
434
|
+
except Exception:
|
|
435
|
+
fwd = self.to_torch_csr(relation_index, transpose=False, device="cpu")
|
|
436
|
+
return fwd.transpose(0, 1).to_sparse_csr().to(device)
|
|
437
|
+
else:
|
|
438
|
+
crow_np = self.get_row_offsets_array(relation_index)
|
|
439
|
+
col_np = self.get_col_indices_array(relation_index)
|
|
440
|
+
|
|
441
|
+
_, cols = self._relation_shape(relation_index, transpose=transpose)
|
|
442
|
+
rows = len(crow_np) - 1 if len(crow_np) > 0 else 0
|
|
443
|
+
if len(col_np) > 0:
|
|
444
|
+
cols = max(cols, int(col_np.max()) + 1)
|
|
445
|
+
size = (rows, cols)
|
|
446
|
+
|
|
447
|
+
# Use np.copy or int64 casting to satisfy PyTorch sparse_csr 64-bit requirement
|
|
448
|
+
crow_indices = torch.from_numpy(crow_np.astype(np.int64))
|
|
449
|
+
col_indices = torch.from_numpy(col_np.astype(np.int64))
|
|
450
|
+
values = torch.ones(col_indices.shape[0], dtype=torch.float32)
|
|
451
|
+
|
|
452
|
+
tensor = torch.sparse_csr_tensor(crow_indices, col_indices, values, size=size)
|
|
453
|
+
return tensor.to(device) if device != "cpu" else tensor
|
|
454
|
+
|
|
455
|
+
def to_torch_edge_index(
|
|
456
|
+
self, relation_index: int = 0, transpose: bool = False, device: str = "cpu"
|
|
457
|
+
):
|
|
458
|
+
"""
|
|
459
|
+
Convert snapshot CSR topology to PyTorch Geometric COO edge_index tensor of shape (2, num_edges).
|
|
460
|
+
"""
|
|
461
|
+
import torch
|
|
462
|
+
|
|
463
|
+
if transpose:
|
|
464
|
+
try:
|
|
465
|
+
indptr = self.get_csc_row_offsets_array(relation_index)
|
|
466
|
+
indices = self.get_csc_col_indices_array(relation_index)
|
|
467
|
+
except Exception:
|
|
468
|
+
fwd = self.to_torch_edge_index(relation_index, transpose=False, device="cpu")
|
|
469
|
+
return torch.stack([fwd[1], fwd[0]]).to(device)
|
|
470
|
+
else:
|
|
471
|
+
indptr = self.get_row_offsets_array(relation_index)
|
|
472
|
+
indices = self.get_col_indices_array(relation_index)
|
|
473
|
+
|
|
474
|
+
degrees = np.diff(indptr)
|
|
475
|
+
src = np.repeat(np.arange(len(degrees), dtype=np.int64), degrees)
|
|
476
|
+
dst = indices.astype(np.int64)
|
|
477
|
+
edge_index = torch.from_numpy(np.vstack([src, dst]))
|
|
478
|
+
return edge_index.to(device) if device != "cpu" else edge_index
|
|
479
|
+
|
|
480
|
+
def to_networkx(self, relation_index: int = 0, create_using=None):
|
|
481
|
+
"""Convert snapshot CSR topology to a NetworkX Graph or DiGraph."""
|
|
482
|
+
import networkx as nx
|
|
483
|
+
|
|
484
|
+
if create_using is None:
|
|
485
|
+
create_using = nx.DiGraph
|
|
486
|
+
indptr = self.get_row_offsets_array(relation_index)
|
|
487
|
+
indices = self.get_col_indices_array(relation_index)
|
|
488
|
+
G = create_using()
|
|
489
|
+
for u in range(len(indptr) - 1):
|
|
490
|
+
for v in indices[indptr[u] : indptr[u + 1]]:
|
|
491
|
+
G.add_edge(u, int(v))
|
|
492
|
+
return G
|
|
493
|
+
|
|
494
|
+
def to_polars(self, relation_index: int = 0):
|
|
495
|
+
"""Convert snapshot CSR topology into a Polars DataFrame with columns ['src', 'dst']."""
|
|
496
|
+
import polars as pl
|
|
497
|
+
|
|
498
|
+
indptr = self.get_row_offsets_array(relation_index)
|
|
499
|
+
indices = self.get_col_indices_array(relation_index)
|
|
500
|
+
degrees = np.diff(indptr)
|
|
501
|
+
src = np.repeat(np.arange(len(degrees), dtype=np.uint32), degrees)
|
|
502
|
+
return pl.DataFrame({"src": src, "dst": indices})
|
|
503
|
+
|
|
504
|
+
def to_pandas(self, relation_index: int = 0):
|
|
505
|
+
"""Convert snapshot CSR topology into a Pandas DataFrame with columns ['src', 'dst']."""
|
|
506
|
+
import pandas as pd
|
|
507
|
+
|
|
508
|
+
indptr = self.get_row_offsets_array(relation_index)
|
|
509
|
+
indices = self.get_col_indices_array(relation_index)
|
|
510
|
+
degrees = np.diff(indptr)
|
|
511
|
+
src = np.repeat(np.arange(len(degrees), dtype=np.uint32), degrees)
|
|
512
|
+
return pd.DataFrame({"src": src, "dst": indices})
|
|
513
|
+
|
|
514
|
+
def to_arrow_table(self, relation_index: int = 0):
|
|
515
|
+
"""Convert snapshot CSR topology into an Apache Arrow Table."""
|
|
516
|
+
import pyarrow as pa
|
|
517
|
+
|
|
518
|
+
indptr = self.get_row_offsets_array(relation_index)
|
|
519
|
+
indices = self.get_col_indices_array(relation_index)
|
|
520
|
+
degrees = np.diff(indptr)
|
|
521
|
+
src = np.repeat(np.arange(len(degrees), dtype=np.uint32), degrees)
|
|
522
|
+
return pa.Table.from_arrays([pa.array(src), pa.array(indices)], names=["src", "dst"])
|
|
523
|
+
|
|
524
|
+
|
|
525
|
+
class Writer:
|
|
526
|
+
def __init__(self, output_path: str, global_features: int = 1):
|
|
527
|
+
if _NativeWriter is None:
|
|
528
|
+
raise RuntimeError("_impulse_native extension is not compiled.")
|
|
529
|
+
self._native = _NativeWriter(output_path, global_features)
|
|
530
|
+
|
|
531
|
+
def __enter__(self):
|
|
532
|
+
return self
|
|
533
|
+
|
|
534
|
+
def __exit__(self, exc_type, exc_val, exc_tb):
|
|
535
|
+
self.destroy()
|
|
536
|
+
|
|
537
|
+
def destroy(self):
|
|
538
|
+
if self._native is not None:
|
|
539
|
+
self._native.destroy()
|
|
540
|
+
|
|
541
|
+
def add_domain(self, domain_id: int, key_type: int, name: str):
|
|
542
|
+
self._native.add_domain(domain_id, key_type, name)
|
|
543
|
+
|
|
544
|
+
def add_relation(
|
|
545
|
+
self,
|
|
546
|
+
src_domain_id: int,
|
|
547
|
+
tgt_domain_id: int,
|
|
548
|
+
encoding_type: int,
|
|
549
|
+
node_count: int,
|
|
550
|
+
edge_count: int,
|
|
551
|
+
section_features: int,
|
|
552
|
+
row_offsets: Union[List[int], np.ndarray],
|
|
553
|
+
col_indices: Union[List[int], np.ndarray],
|
|
554
|
+
):
|
|
555
|
+
if isinstance(row_offsets, np.ndarray):
|
|
556
|
+
row_offsets = row_offsets.astype(np.uint32).tolist()
|
|
557
|
+
if isinstance(col_indices, np.ndarray):
|
|
558
|
+
col_indices = col_indices.astype(np.uint32).tolist()
|
|
559
|
+
|
|
560
|
+
self._native.add_relation(
|
|
561
|
+
src_domain_id,
|
|
562
|
+
tgt_domain_id,
|
|
563
|
+
encoding_type,
|
|
564
|
+
node_count,
|
|
565
|
+
edge_count,
|
|
566
|
+
section_features,
|
|
567
|
+
list(row_offsets),
|
|
568
|
+
list(col_indices),
|
|
569
|
+
)
|
|
570
|
+
|
|
571
|
+
def add_attribute(
|
|
572
|
+
self,
|
|
573
|
+
relation_index: int,
|
|
574
|
+
name: str,
|
|
575
|
+
type_code: int,
|
|
576
|
+
dimension: int,
|
|
577
|
+
data: Union[bytes, bytearray, np.ndarray],
|
|
578
|
+
offsets: Optional[Union[bytes, bytearray, np.ndarray]] = None,
|
|
579
|
+
):
|
|
580
|
+
data_bytes = data.tobytes() if isinstance(data, np.ndarray) else data
|
|
581
|
+
offsets_bytes = offsets.tobytes() if isinstance(offsets, np.ndarray) else offsets
|
|
582
|
+
self._native.add_attribute(relation_index, name, type_code, dimension, data_bytes, offsets_bytes)
|
|
583
|
+
|
|
584
|
+
def finalize(self):
|
|
585
|
+
self._native.finalize()
|
|
586
|
+
|
|
587
|
+
@classmethod
|
|
588
|
+
def from_scipy(cls, output_path: str, matrix, domain_name: str = "Node", key_type: int = 4):
|
|
589
|
+
"""
|
|
590
|
+
Convenience constructor: Compile a scipy.sparse.csr_matrix or csc_matrix into an .imps file.
|
|
591
|
+
"""
|
|
592
|
+
import scipy.sparse as sp
|
|
593
|
+
|
|
594
|
+
if not sp.isspmatrix_csr(matrix):
|
|
595
|
+
matrix = matrix.tocsr()
|
|
596
|
+
|
|
597
|
+
num_nodes = matrix.shape[0]
|
|
598
|
+
num_edges = matrix.nnz
|
|
599
|
+
|
|
600
|
+
with cls(output_path) as writer:
|
|
601
|
+
writer.add_domain(0, key_type, domain_name)
|
|
602
|
+
writer.add_relation(
|
|
603
|
+
src_domain_id=0,
|
|
604
|
+
tgt_domain_id=0,
|
|
605
|
+
encoding_type=0,
|
|
606
|
+
node_count=num_nodes,
|
|
607
|
+
edge_count=num_edges,
|
|
608
|
+
section_features=0,
|
|
609
|
+
row_offsets=matrix.indptr,
|
|
610
|
+
col_indices=matrix.indices,
|
|
611
|
+
)
|
|
612
|
+
writer.finalize()
|
|
613
|
+
|
|
614
|
+
@classmethod
|
|
615
|
+
def from_torch(
|
|
616
|
+
cls,
|
|
617
|
+
output_path: str,
|
|
618
|
+
edge_index,
|
|
619
|
+
num_nodes: Optional[int] = None,
|
|
620
|
+
domain_name: str = "Node",
|
|
621
|
+
key_type: int = 4,
|
|
622
|
+
):
|
|
623
|
+
"""
|
|
624
|
+
Convenience constructor: Compile a PyTorch edge_index tensor (2, E) or torch.sparse_csr_tensor into an .imps file.
|
|
625
|
+
"""
|
|
626
|
+
import torch
|
|
627
|
+
|
|
628
|
+
if hasattr(edge_index, "is_sparse_csr") and edge_index.is_sparse_csr:
|
|
629
|
+
crow = edge_index.crow_indices().cpu().numpy().astype(np.uint32)
|
|
630
|
+
col = edge_index.col_indices().cpu().numpy().astype(np.uint32)
|
|
631
|
+
n_nodes = num_nodes or edge_index.size(0)
|
|
632
|
+
n_edges = col.shape[0]
|
|
633
|
+
else:
|
|
634
|
+
if isinstance(edge_index, torch.Tensor):
|
|
635
|
+
ei = edge_index.cpu().numpy()
|
|
636
|
+
else:
|
|
637
|
+
ei = np.asarray(edge_index)
|
|
638
|
+
|
|
639
|
+
src = ei[0].astype(np.int64)
|
|
640
|
+
dst = ei[1].astype(np.int64)
|
|
641
|
+
n_nodes = num_nodes or int(max(src.max(), dst.max()) + 1)
|
|
642
|
+
n_edges = len(src)
|
|
643
|
+
|
|
644
|
+
# Sort edges by source node
|
|
645
|
+
sort_idx = np.argsort(src)
|
|
646
|
+
src_sorted = src[sort_idx]
|
|
647
|
+
dst_sorted = dst[sort_idx]
|
|
648
|
+
|
|
649
|
+
# Compute CSR offsets
|
|
650
|
+
counts = np.bincount(src_sorted, minlength=n_nodes)
|
|
651
|
+
crow = np.zeros(n_nodes + 1, dtype=np.uint32)
|
|
652
|
+
crow[1:] = np.cumsum(counts, dtype=np.uint32)
|
|
653
|
+
col = dst_sorted.astype(np.uint32)
|
|
654
|
+
|
|
655
|
+
with cls(output_path) as writer:
|
|
656
|
+
writer.add_domain(0, key_type, domain_name)
|
|
657
|
+
writer.add_relation(
|
|
658
|
+
src_domain_id=0,
|
|
659
|
+
tgt_domain_id=0,
|
|
660
|
+
encoding_type=0,
|
|
661
|
+
node_count=n_nodes,
|
|
662
|
+
edge_count=n_edges,
|
|
663
|
+
section_features=0,
|
|
664
|
+
row_offsets=crow,
|
|
665
|
+
col_indices=col,
|
|
666
|
+
)
|
|
667
|
+
writer.finalize()
|
|
668
|
+
|
|
669
|
+
@classmethod
|
|
670
|
+
def from_dataframe(
|
|
671
|
+
cls,
|
|
672
|
+
output_path: str,
|
|
673
|
+
df,
|
|
674
|
+
src_col: str = "src",
|
|
675
|
+
tgt_col: str = "dst",
|
|
676
|
+
domain_name: str = "Node",
|
|
677
|
+
key_type: int = 1, # STRING key
|
|
678
|
+
):
|
|
679
|
+
"""
|
|
680
|
+
Convenience constructor: Compile a Pandas/Polars DataFrame into an .imps file with automatic key mapping.
|
|
681
|
+
"""
|
|
682
|
+
if hasattr(df, "to_pandas"):
|
|
683
|
+
pdf = df.to_pandas()
|
|
684
|
+
else:
|
|
685
|
+
pdf = df
|
|
686
|
+
|
|
687
|
+
src_raw = pdf[src_col].values
|
|
688
|
+
tgt_raw = pdf[tgt_col].values
|
|
689
|
+
|
|
690
|
+
# Unique key mapping
|
|
691
|
+
unique_keys, inverse = np.unique(np.concatenate([src_raw, tgt_raw]), return_inverse=True)
|
|
692
|
+
n_nodes = len(unique_keys)
|
|
693
|
+
n_edges = len(src_raw)
|
|
694
|
+
|
|
695
|
+
src_ids = inverse[:n_edges]
|
|
696
|
+
dst_ids = inverse[n_edges:]
|
|
697
|
+
|
|
698
|
+
sort_idx = np.argsort(src_ids)
|
|
699
|
+
src_sorted = src_ids[sort_idx]
|
|
700
|
+
dst_sorted = dst_ids[sort_idx]
|
|
701
|
+
|
|
702
|
+
counts = np.bincount(src_sorted, minlength=n_nodes)
|
|
703
|
+
row_offsets = np.zeros(n_nodes + 1, dtype=np.uint32)
|
|
704
|
+
row_offsets[1:] = np.cumsum(counts, dtype=np.uint32)
|
|
705
|
+
col_indices = dst_sorted.astype(np.uint32)
|
|
706
|
+
|
|
707
|
+
with cls(output_path) as writer:
|
|
708
|
+
writer.add_domain(0, key_type, domain_name)
|
|
709
|
+
writer.add_relation(
|
|
710
|
+
src_domain_id=0,
|
|
711
|
+
tgt_domain_id=0,
|
|
712
|
+
encoding_type=0,
|
|
713
|
+
node_count=n_nodes,
|
|
714
|
+
edge_count=n_edges,
|
|
715
|
+
section_features=0,
|
|
716
|
+
row_offsets=row_offsets,
|
|
717
|
+
col_indices=col_indices,
|
|
718
|
+
)
|
|
719
|
+
writer.finalize()
|
|
720
|
+
|
|
721
|
+
@classmethod
|
|
722
|
+
def from_networkx(cls, output_path: str, graph, domain_name: str = "Node"):
|
|
723
|
+
"""
|
|
724
|
+
Convenience constructor: Compile a NetworkX Graph / DiGraph into an .imps file.
|
|
725
|
+
"""
|
|
726
|
+
nodes = sorted(list(graph.nodes()))
|
|
727
|
+
node_map = {n: i for i, n in enumerate(nodes)}
|
|
728
|
+
n_nodes = len(nodes)
|
|
729
|
+
|
|
730
|
+
row_offsets = [0]
|
|
731
|
+
col_indices = []
|
|
732
|
+
for n in nodes:
|
|
733
|
+
nbrs = [node_map[nbr] for nbrbr in [graph.neighbors(n)] for nbr in sorted(nbrbr)]
|
|
734
|
+
col_indices.extend(nbrs)
|
|
735
|
+
row_offsets.append(len(col_indices))
|
|
736
|
+
|
|
737
|
+
with cls(output_path) as writer:
|
|
738
|
+
writer.add_domain(0, 4, domain_name)
|
|
739
|
+
writer.add_relation(
|
|
740
|
+
src_domain_id=0,
|
|
741
|
+
tgt_domain_id=0,
|
|
742
|
+
encoding_type=0,
|
|
743
|
+
node_count=n_nodes,
|
|
744
|
+
edge_count=len(col_indices),
|
|
745
|
+
section_features=0,
|
|
746
|
+
row_offsets=np.array(row_offsets, dtype=np.uint32),
|
|
747
|
+
col_indices=np.array(col_indices, dtype=np.uint32),
|
|
748
|
+
)
|
|
749
|
+
writer.finalize()
|
|
750
|
+
|
|
751
|
+
|
|
752
|
+
from .traversal import Traversal # noqa: E402
|
|
753
|
+
|
|
754
|
+
__version__ = "0.9.0"
|
|
755
|
+
__all__ = ["Snapshot", "DomainView", "Writer", "Traversal", "vm"]
|