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.
@@ -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"]