impulse-graph 0.10.0__tar.gz

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.
Files changed (77) hide show
  1. impulse_graph-0.10.0/MANIFEST.in +26 -0
  2. impulse_graph-0.10.0/PKG-INFO +208 -0
  3. impulse_graph-0.10.0/README.md +173 -0
  4. impulse_graph-0.10.0/impulse-cpp/include/contracts/contracts_chunk1.hpp +522 -0
  5. impulse_graph-0.10.0/impulse-cpp/include/contracts/contracts_chunk2.hpp +462 -0
  6. impulse_graph-0.10.0/impulse-cpp/include/contracts/contracts_chunk3.hpp +403 -0
  7. impulse_graph-0.10.0/impulse-cpp/include/contracts/contracts_chunk4.hpp +412 -0
  8. impulse_graph-0.10.0/impulse-cpp/include/contracts/contracts_chunk5.hpp +277 -0
  9. impulse_graph-0.10.0/impulse-cpp/include/impulse_assert.h +266 -0
  10. impulse_graph-0.10.0/impulse-cpp/include/impulse_bytecode_emitter.hpp +46 -0
  11. impulse_graph-0.10.0/impulse-cpp/include/impulse_cel.h +2456 -0
  12. impulse_graph-0.10.0/impulse-cpp/include/impulse_compiler.hpp +1117 -0
  13. impulse_graph-0.10.0/impulse-cpp/include/impulse_cypher.hpp +955 -0
  14. impulse_graph-0.10.0/impulse-cpp/include/impulse_datalog.hpp +563 -0
  15. impulse_graph-0.10.0/impulse-cpp/include/impulse_format_v0_10.h +207 -0
  16. impulse_graph-0.10.0/impulse-cpp/include/impulse_format_v0_9.h +181 -0
  17. impulse_graph-0.10.0/impulse-cpp/include/impulse_graph.h +466 -0
  18. impulse_graph-0.10.0/impulse-cpp/include/impulse_hexio.h +165 -0
  19. impulse_graph-0.10.0/impulse-cpp/include/impulse_impk.hpp +717 -0
  20. impulse_graph-0.10.0/impulse-cpp/include/impulse_implog.hpp +19 -0
  21. impulse_graph-0.10.0/impulse-cpp/include/impulse_impscm.hpp +18 -0
  22. impulse_graph-0.10.0/impulse-cpp/include/impulse_index.h +170 -0
  23. impulse_graph-0.10.0/impulse-cpp/include/impulse_math_ops.h +485 -0
  24. impulse_graph-0.10.0/impulse-cpp/include/impulse_opcode_contracts.hpp +158 -0
  25. impulse_graph-0.10.0/impulse-cpp/include/impulse_opcode_macros.h +335 -0
  26. impulse_graph-0.10.0/impulse-cpp/include/impulse_scm_ast.hpp +909 -0
  27. impulse_graph-0.10.0/impulse-cpp/include/impulse_sexpr.hpp +332 -0
  28. impulse_graph-0.10.0/impulse-cpp/include/impulse_sha256.h +134 -0
  29. impulse_graph-0.10.0/impulse-cpp/include/impulse_simd.h +66 -0
  30. impulse_graph-0.10.0/impulse-cpp/include/impulse_vm.h +702 -0
  31. impulse_graph-0.10.0/impulse-cpp/include/impulse_vm_fluent.hpp +727 -0
  32. impulse_graph-0.10.0/impulse-cpp/src/impulse_bytecode_emitter.cpp +541 -0
  33. impulse_graph-0.10.0/impulse-cpp/src/impulse_graph.cpp +2082 -0
  34. impulse_graph-0.10.0/impulse-cpp/src/impulse_graph_internal.hpp +232 -0
  35. impulse_graph-0.10.0/impulse-cpp/src/impulse_index.cpp +882 -0
  36. impulse_graph-0.10.0/impulse-cpp/src/impulse_simd.cpp +216 -0
  37. impulse_graph-0.10.0/impulse-cpp/src/impulse_snapshot_writer.cpp +844 -0
  38. impulse_graph-0.10.0/impulse-cpp/src/impulse_statement_c_api.cpp +845 -0
  39. impulse_graph-0.10.0/impulse-cpp/src/impulse_vm.cpp +1042 -0
  40. impulse_graph-0.10.0/impulse-cpp/src/impulse_vm_context.cpp +1381 -0
  41. impulse_graph-0.10.0/impulse-cpp/src/impulse_vm_fluent.cpp +649 -0
  42. impulse_graph-0.10.0/impulse-cpp/src/impulse_vm_fluent_internal.hpp +843 -0
  43. impulse_graph-0.10.0/impulse-cpp/src/impulse_vm_fluent_multilane.cpp +1665 -0
  44. impulse_graph-0.10.0/impulse-cpp/src/impulse_vm_fluent_traversal.cpp +1321 -0
  45. impulse_graph-0.10.0/impulse-cpp/src/impulse_vm_internal.hpp +1257 -0
  46. impulse_graph-0.10.0/impulse-cpp/src/opcodes/shared/coo_walk_common.hpp +97 -0
  47. impulse_graph-0.10.0/impulse-cpp/src/opcodes/shared/dense_walk_common.hpp +114 -0
  48. impulse_graph-0.10.0/impulse-cpp/src/opcodes/shared/lane_walk_common.hpp +748 -0
  49. impulse_graph-0.10.0/impulse-cpp/src/opcodes/shared/mock_attr_common.hpp +105 -0
  50. impulse_graph-0.10.0/impulse-cpp/src/opcodes/shared/walk_stream_common.hpp +265 -0
  51. impulse_graph-0.10.0/impulse_graph/__init__.py +755 -0
  52. impulse_graph-0.10.0/impulse_graph/cypher.py +154 -0
  53. impulse_graph-0.10.0/impulse_graph/traversal.py +445 -0
  54. impulse_graph-0.10.0/impulse_graph/vm.py +610 -0
  55. impulse_graph-0.10.0/impulse_graph.egg-info/PKG-INFO +208 -0
  56. impulse_graph-0.10.0/impulse_graph.egg-info/SOURCES.txt +83 -0
  57. impulse_graph-0.10.0/impulse_graph.egg-info/dependency_links.txt +1 -0
  58. impulse_graph-0.10.0/impulse_graph.egg-info/requires.txt +1 -0
  59. impulse_graph-0.10.0/impulse_graph.egg-info/top_level.txt +1 -0
  60. impulse_graph-0.10.0/pyproject.toml +61 -0
  61. impulse_graph-0.10.0/setup.cfg +4 -0
  62. impulse_graph-0.10.0/setup.py +143 -0
  63. impulse_graph-0.10.0/src/impulse_python.cpp +919 -0
  64. impulse_graph-0.10.0/tests/test_cel_binding.py +80 -0
  65. impulse_graph-0.10.0/tests/test_cypher.py +87 -0
  66. impulse_graph-0.10.0/tests/test_domain_traversal.py +208 -0
  67. impulse_graph-0.10.0/tests/test_errors_and_boundaries.py +88 -0
  68. impulse_graph-0.10.0/tests/test_interchange.py +100 -0
  69. impulse_graph-0.10.0/tests/test_issues_57_58_59.py +160 -0
  70. impulse_graph-0.10.0/tests/test_reachability.py +46 -0
  71. impulse_graph-0.10.0/tests/test_sampler_and_attributes.py +50 -0
  72. impulse_graph-0.10.0/tests/test_snapshot.py +46 -0
  73. impulse_graph-0.10.0/tests/test_swe_sweep_80.py +131 -0
  74. impulse_graph-0.10.0/tests/test_traversal_analytics.py +100 -0
  75. impulse_graph-0.10.0/tests/test_vm.py +154 -0
  76. impulse_graph-0.10.0/tests/test_writer.py +30 -0
  77. impulse_graph-0.10.0/tests/test_writer_constructors.py +88 -0
@@ -0,0 +1,26 @@
1
+ include README.md
2
+ include pyproject.toml
3
+ include setup.py
4
+ recursive-include src *.cpp *.hpp *.h
5
+ recursive-include impulse_graph *.py *.pyi
6
+ recursive-include impulse-cpp/include *.h *.hpp
7
+ recursive-include impulse-cpp/src *.cpp *.hpp *.h
8
+
9
+ global-exclude *.so
10
+ global-exclude *.dylib
11
+ global-exclude *.dll
12
+ global-exclude *.pyd
13
+ global-exclude *.pyc
14
+ global-exclude *.pyo
15
+ global-exclude *.imps
16
+ global-exclude .DS_Store
17
+ global-exclude *.orig
18
+
19
+ prune build
20
+ prune dist
21
+ prune **/__pycache__
22
+ prune **/.pytest_cache
23
+ prune **/.ruff_cache
24
+ prune tests/__pycache__
25
+ prune impulse_graph/__pycache__
26
+ prune examples/__pycache__
@@ -0,0 +1,208 @@
1
+ Metadata-Version: 2.4
2
+ Name: impulse-graph
3
+ Version: 0.10.0
4
+ Summary: Impulse Graph Engine Python SDK & C++ Bytecode VM Binding
5
+ Author: Impulse Graph Team
6
+ Author-email: Impulse Graph Team <engineering@impulsegraph.io>
7
+ License: Apache-2.0
8
+ Project-URL: Homepage, https://docs.impulsegraph.io
9
+ Project-URL: Repository, https://github.com/impulse-graph/impulse-graph-core
10
+ Project-URL: Documentation, https://docs.impulsegraph.io
11
+ Project-URL: Issue Tracker, https://github.com/impulse-graph/impulse-graph-core/issues
12
+ Project-URL: Changelog, https://github.com/impulse-graph/impulse-graph-core/releases
13
+ Keywords: graph,graph-analytics,graphblas,zero-copy,pytorch,gnn,simd,vector-vm,rebac
14
+ Classifier: Development Status :: 4 - Beta
15
+ Classifier: Intended Audience :: Developers
16
+ Classifier: Intended Audience :: Science/Research
17
+ Classifier: Programming Language :: Python :: 3
18
+ Classifier: Programming Language :: Python :: 3.8
19
+ Classifier: Programming Language :: Python :: 3.9
20
+ Classifier: Programming Language :: Python :: 3.10
21
+ Classifier: Programming Language :: Python :: 3.11
22
+ Classifier: Programming Language :: Python :: 3.12
23
+ Classifier: Programming Language :: Python :: 3.13
24
+ Classifier: Programming Language :: C++
25
+ Classifier: Operating System :: OS Independent
26
+ Classifier: Topic :: Scientific/Engineering
27
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
28
+ Classifier: Topic :: Database
29
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
30
+ Requires-Python: >=3.8
31
+ Description-Content-Type: text/markdown
32
+ Requires-Dist: numpy>=1.20.0
33
+ Dynamic: author
34
+ Dynamic: requires-python
35
+
36
+ # Impulse Graph Engine Python SDK & C++ Bytecode VM Binding (`impulse-python`)
37
+
38
+ The official Python SDK for **Impulse Graph Engine** (`impulse-graph`), pairing zero-copy memory-mapped graph analytics with native C++20 `ImpulseVM` bytecode execution, off-heap data interchange, and high-performance ML/Data Science interop (PyTorch, PyG, SciPy, NumPy, Apache Arrow, Polars, NetworkX).
39
+
40
+ ---
41
+
42
+ ## 1. Features & Architectural Highlights
43
+
44
+ * **Zero-Copy Memory-Mapped Snapshots (`.imps`)**: Query multi-terabyte binary graph snapshots directly off-heap without heap copies or garbage collection overhead.
45
+ * **ML & Data Science Data Interchange**: First-class zero-copy interop with **PyTorch & PyG** (`torch.sparse_csr_tensor`, `torch_geometric.data.Data`, GNN neighbor sampling), **SciPy** (`csr_matrix` / `csgraph`), **Apache Arrow**, **Polars / Pandas**, and **NetworkX**.
46
+ * **Bytecode Virtual Machine (`QueryBuilder`)**: Fluent C++20 bytecode compiler generating vector instructions (`OP_CSR_WALK`, `OP_CSC_WALK`, `OP_COLLECT_BITSET`, `OP_MXV`).
47
+ * **NumPy Zero-Copy Interop**: Direct memoryviews into off-heap columnar attribute sections and node index buffers.
48
+ * **Declarative Cypher & Traversal DSL**: High-level graph pattern matching and reachability queries.
49
+ * **Convenience Snapshot Constructors**: Create `.imps` snapshots directly from PyTorch tensors (`Writer.from_torch`), SciPy sparse matrices (`Writer.from_scipy`), DataFrames (`Writer.from_dataframe`), or NetworkX graphs (`Writer.from_networkx`).
50
+
51
+ 👉 **[Read the Snapshot Interchange Guide (`SNAPSHOT_INTERCHANGE_GUIDE.md`)](SNAPSHOT_INTERCHANGE_GUIDE.md)** for in-depth data interchange recipes and framework comparisons.
52
+
53
+ ---
54
+
55
+ ## 2. Prerequisites & Installation
56
+
57
+ ### Prerequisites
58
+
59
+ | Dependency | Minimum Version | Notes |
60
+ | :--- | :--- | :--- |
61
+ | **Python** | 3.8+ | Python 3.8 through 3.14 supported. |
62
+ | **C++ Compiler** | GCC 11+, Clang 14+, MSVC 2022+ | Full C++20 support required to compile native C-ABI extension. |
63
+ | **CMake** | 3.20+ | Used to configure Highway SIMD dependencies during extension build. |
64
+ | **pip & setuptools** | Recent | `pip install pybind11 numpy pytest`. |
65
+
66
+ ### Install from Source (Development Mode)
67
+
68
+ ```bash
69
+ cd impulse-graph-core/impulse-python
70
+
71
+ # Install in editable/development mode
72
+ pip install -e .
73
+ ```
74
+
75
+ Or build the native C++ extension module in-place:
76
+ ```bash
77
+ python setup.py build_ext --inplace
78
+ ```
79
+
80
+ ---
81
+
82
+ ## 3. Running the Self-Contained Test Suite
83
+
84
+ All unit tests are **100% self-contained** in the `tests/` directory and execute offline without external dataset downloads:
85
+
86
+ ```bash
87
+ # Run test suite with pytest
88
+ pytest tests/
89
+ ```
90
+
91
+ Test coverage includes:
92
+ * `tests/test_writer.py`: Programmatic `.imps` creation and header verification.
93
+ * `tests/test_snapshot.py`: Off-heap zero-copy memoryview and domain/relation metadata inspection.
94
+ * `tests/test_reachability.py`: Point-to-point graph reachability.
95
+ * `tests/test_vm.py`: Bytecode compiler, register windowing, and bitset collections.
96
+ * `tests/test_cypher.py`: Cypher pattern compilation and execution.
97
+
98
+ ---
99
+
100
+ ## 4. Running Examples & Sample Datasets
101
+
102
+ The `examples/` directory contains end-to-end sample scripts demonstrating real-world usage.
103
+
104
+ ### Standard Sample Datasets Setup
105
+
106
+ Examples that load pre-built snapshots (`02_social_traversal.py`, `03_rbac_reachability.py`, `04_cel_transactions.py`) look for canonical `.imps` files in the directory specified by the **`IMPULSE_DATASETS_DIR`** environment variable:
107
+
108
+ 1. **Download & Extract Sample Datasets**:
109
+ ```bash
110
+ curl -fsSLO https://github.com/impulse-graph/impulse-graph-core/releases/download/v0.10.0/impulse-sample-datasets.tar.gz
111
+ tar -xzf impulse-sample-datasets.tar.gz -C ~/impulse-datasets/
112
+ ```
113
+
114
+ 2. **Export Environment Variable**:
115
+ ```bash
116
+ export IMPULSE_DATASETS_DIR=~/impulse-datasets
117
+ ```
118
+
119
+ *(Note: If `IMPULSE_DATASETS_DIR` is unset, examples will automatically search local fallback paths such as `../../datasets` or generate local sample graphs).*
120
+
121
+ ### Running Example Scripts
122
+
123
+ ```bash
124
+ # 1. Programmatically build snapshot with Writer and query with Snapshot
125
+ python examples/01_snapshot_basics.py
126
+
127
+ # 2. Multi-hop traversal on social network graph (social_graph.imps)
128
+ python examples/02_social_traversal.py
129
+
130
+ # 3. Relationship-Based Access Control (ReBAC) on rbac_snapshot.imps
131
+ python examples/03_rbac_reachability.py
132
+
133
+ # 4. Google CEL expression filtering and zero-copy NumPy array extraction
134
+ python examples/04_cel_transactions.py
135
+
136
+ # 5. PyTorch sparse CSR, PyG Data conversion & GNN neighbor sampling
137
+ python examples/05_pytorch_pyg.py
138
+
139
+ # 6. SciPy sparse matrix, csgraph Dijkstra & GraphBLAS matrix math
140
+ python examples/06_scipy_sparse.py
141
+
142
+ # 7. Columnar data interchange with Apache Arrow, Polars & Pandas
143
+ python examples/07_arrow_polars.py
144
+
145
+ # 8. NetworkX graph construction, PageRank & shortest paths
146
+ python examples/08_networkx.py
147
+ ```
148
+
149
+ ---
150
+
151
+ ## 5. Python API Quick Reference
152
+
153
+ ### Snapshot Data Interchange (PyTorch, SciPy, Arrow, Polars)
154
+
155
+ ```python
156
+ from impulse_graph import Snapshot
157
+
158
+ with Snapshot("graph.imps") as snap:
159
+ # 1. PyTorch Sparse CSR Tensor
160
+ torch_csr = snap.to_torch_csr(relation_index=0)
161
+
162
+ # 2. SciPy CSR Matrix
163
+ scipy_mat = snap.to_scipy_csr(relation_index=0)
164
+
165
+ # 3. Polars / Pandas DataFrame
166
+ df = snap.to_polars(relation_index=0)
167
+
168
+ # 4. SIMD GNN Neighborhood Sampling
169
+ srcs, tgts = snap.sample_neighbors(relation_index=0, nodes=[0, 1], k_samples=3)
170
+ ```
171
+
172
+ ### Fluent `QueryBuilder` Example
173
+
174
+ ```python
175
+ from impulse_graph import Snapshot, vm
176
+
177
+ # 1. Build a bytecode query using QueryBuilder
178
+ builder = vm.QueryBuilder()
179
+ query = (
180
+ builder.input_node(0) # Seed node ID 0
181
+ .walk_edge(relation_id=0) # 1-hop CSR neighbors
182
+ .walk_edge(relation_id=0) # 2-hop CSR neighbors
183
+ .collect_bitset() # Collect destination frontier
184
+ .compile()
185
+ )
186
+
187
+ # 2. Execute query against snapshot
188
+ with Snapshot("graph.imps") as snap:
189
+ result = snap.execute_query(query, input_param=0)
190
+ print("Execution Success:", result.is_ok())
191
+ print("Result Register R" + str(result.result_register) + ":", hex(result.raw_value))
192
+ ```
193
+
194
+ ### Snapshot Writer Constructors
195
+
196
+ ```python
197
+ from impulse_graph import Writer
198
+ import scipy.sparse as sp
199
+ import torch
200
+
201
+ # From SciPy sparse matrix
202
+ adj = sp.random(1000, 1000, density=0.01, format="csr")
203
+ Writer.from_scipy("scipy_graph.imps", adj)
204
+
205
+ # From PyTorch COO edge_index
206
+ edge_index = torch.tensor([[0, 1, 2], [1, 2, 0]], dtype=torch.int64)
207
+ Writer.from_torch("torch_graph.imps", edge_index, num_nodes=3)
208
+ ```
@@ -0,0 +1,173 @@
1
+ # Impulse Graph Engine Python SDK & C++ Bytecode VM Binding (`impulse-python`)
2
+
3
+ The official Python SDK for **Impulse Graph Engine** (`impulse-graph`), pairing zero-copy memory-mapped graph analytics with native C++20 `ImpulseVM` bytecode execution, off-heap data interchange, and high-performance ML/Data Science interop (PyTorch, PyG, SciPy, NumPy, Apache Arrow, Polars, NetworkX).
4
+
5
+ ---
6
+
7
+ ## 1. Features & Architectural Highlights
8
+
9
+ * **Zero-Copy Memory-Mapped Snapshots (`.imps`)**: Query multi-terabyte binary graph snapshots directly off-heap without heap copies or garbage collection overhead.
10
+ * **ML & Data Science Data Interchange**: First-class zero-copy interop with **PyTorch & PyG** (`torch.sparse_csr_tensor`, `torch_geometric.data.Data`, GNN neighbor sampling), **SciPy** (`csr_matrix` / `csgraph`), **Apache Arrow**, **Polars / Pandas**, and **NetworkX**.
11
+ * **Bytecode Virtual Machine (`QueryBuilder`)**: Fluent C++20 bytecode compiler generating vector instructions (`OP_CSR_WALK`, `OP_CSC_WALK`, `OP_COLLECT_BITSET`, `OP_MXV`).
12
+ * **NumPy Zero-Copy Interop**: Direct memoryviews into off-heap columnar attribute sections and node index buffers.
13
+ * **Declarative Cypher & Traversal DSL**: High-level graph pattern matching and reachability queries.
14
+ * **Convenience Snapshot Constructors**: Create `.imps` snapshots directly from PyTorch tensors (`Writer.from_torch`), SciPy sparse matrices (`Writer.from_scipy`), DataFrames (`Writer.from_dataframe`), or NetworkX graphs (`Writer.from_networkx`).
15
+
16
+ 👉 **[Read the Snapshot Interchange Guide (`SNAPSHOT_INTERCHANGE_GUIDE.md`)](SNAPSHOT_INTERCHANGE_GUIDE.md)** for in-depth data interchange recipes and framework comparisons.
17
+
18
+ ---
19
+
20
+ ## 2. Prerequisites & Installation
21
+
22
+ ### Prerequisites
23
+
24
+ | Dependency | Minimum Version | Notes |
25
+ | :--- | :--- | :--- |
26
+ | **Python** | 3.8+ | Python 3.8 through 3.14 supported. |
27
+ | **C++ Compiler** | GCC 11+, Clang 14+, MSVC 2022+ | Full C++20 support required to compile native C-ABI extension. |
28
+ | **CMake** | 3.20+ | Used to configure Highway SIMD dependencies during extension build. |
29
+ | **pip & setuptools** | Recent | `pip install pybind11 numpy pytest`. |
30
+
31
+ ### Install from Source (Development Mode)
32
+
33
+ ```bash
34
+ cd impulse-graph-core/impulse-python
35
+
36
+ # Install in editable/development mode
37
+ pip install -e .
38
+ ```
39
+
40
+ Or build the native C++ extension module in-place:
41
+ ```bash
42
+ python setup.py build_ext --inplace
43
+ ```
44
+
45
+ ---
46
+
47
+ ## 3. Running the Self-Contained Test Suite
48
+
49
+ All unit tests are **100% self-contained** in the `tests/` directory and execute offline without external dataset downloads:
50
+
51
+ ```bash
52
+ # Run test suite with pytest
53
+ pytest tests/
54
+ ```
55
+
56
+ Test coverage includes:
57
+ * `tests/test_writer.py`: Programmatic `.imps` creation and header verification.
58
+ * `tests/test_snapshot.py`: Off-heap zero-copy memoryview and domain/relation metadata inspection.
59
+ * `tests/test_reachability.py`: Point-to-point graph reachability.
60
+ * `tests/test_vm.py`: Bytecode compiler, register windowing, and bitset collections.
61
+ * `tests/test_cypher.py`: Cypher pattern compilation and execution.
62
+
63
+ ---
64
+
65
+ ## 4. Running Examples & Sample Datasets
66
+
67
+ The `examples/` directory contains end-to-end sample scripts demonstrating real-world usage.
68
+
69
+ ### Standard Sample Datasets Setup
70
+
71
+ Examples that load pre-built snapshots (`02_social_traversal.py`, `03_rbac_reachability.py`, `04_cel_transactions.py`) look for canonical `.imps` files in the directory specified by the **`IMPULSE_DATASETS_DIR`** environment variable:
72
+
73
+ 1. **Download & Extract Sample Datasets**:
74
+ ```bash
75
+ curl -fsSLO https://github.com/impulse-graph/impulse-graph-core/releases/download/v0.10.0/impulse-sample-datasets.tar.gz
76
+ tar -xzf impulse-sample-datasets.tar.gz -C ~/impulse-datasets/
77
+ ```
78
+
79
+ 2. **Export Environment Variable**:
80
+ ```bash
81
+ export IMPULSE_DATASETS_DIR=~/impulse-datasets
82
+ ```
83
+
84
+ *(Note: If `IMPULSE_DATASETS_DIR` is unset, examples will automatically search local fallback paths such as `../../datasets` or generate local sample graphs).*
85
+
86
+ ### Running Example Scripts
87
+
88
+ ```bash
89
+ # 1. Programmatically build snapshot with Writer and query with Snapshot
90
+ python examples/01_snapshot_basics.py
91
+
92
+ # 2. Multi-hop traversal on social network graph (social_graph.imps)
93
+ python examples/02_social_traversal.py
94
+
95
+ # 3. Relationship-Based Access Control (ReBAC) on rbac_snapshot.imps
96
+ python examples/03_rbac_reachability.py
97
+
98
+ # 4. Google CEL expression filtering and zero-copy NumPy array extraction
99
+ python examples/04_cel_transactions.py
100
+
101
+ # 5. PyTorch sparse CSR, PyG Data conversion & GNN neighbor sampling
102
+ python examples/05_pytorch_pyg.py
103
+
104
+ # 6. SciPy sparse matrix, csgraph Dijkstra & GraphBLAS matrix math
105
+ python examples/06_scipy_sparse.py
106
+
107
+ # 7. Columnar data interchange with Apache Arrow, Polars & Pandas
108
+ python examples/07_arrow_polars.py
109
+
110
+ # 8. NetworkX graph construction, PageRank & shortest paths
111
+ python examples/08_networkx.py
112
+ ```
113
+
114
+ ---
115
+
116
+ ## 5. Python API Quick Reference
117
+
118
+ ### Snapshot Data Interchange (PyTorch, SciPy, Arrow, Polars)
119
+
120
+ ```python
121
+ from impulse_graph import Snapshot
122
+
123
+ with Snapshot("graph.imps") as snap:
124
+ # 1. PyTorch Sparse CSR Tensor
125
+ torch_csr = snap.to_torch_csr(relation_index=0)
126
+
127
+ # 2. SciPy CSR Matrix
128
+ scipy_mat = snap.to_scipy_csr(relation_index=0)
129
+
130
+ # 3. Polars / Pandas DataFrame
131
+ df = snap.to_polars(relation_index=0)
132
+
133
+ # 4. SIMD GNN Neighborhood Sampling
134
+ srcs, tgts = snap.sample_neighbors(relation_index=0, nodes=[0, 1], k_samples=3)
135
+ ```
136
+
137
+ ### Fluent `QueryBuilder` Example
138
+
139
+ ```python
140
+ from impulse_graph import Snapshot, vm
141
+
142
+ # 1. Build a bytecode query using QueryBuilder
143
+ builder = vm.QueryBuilder()
144
+ query = (
145
+ builder.input_node(0) # Seed node ID 0
146
+ .walk_edge(relation_id=0) # 1-hop CSR neighbors
147
+ .walk_edge(relation_id=0) # 2-hop CSR neighbors
148
+ .collect_bitset() # Collect destination frontier
149
+ .compile()
150
+ )
151
+
152
+ # 2. Execute query against snapshot
153
+ with Snapshot("graph.imps") as snap:
154
+ result = snap.execute_query(query, input_param=0)
155
+ print("Execution Success:", result.is_ok())
156
+ print("Result Register R" + str(result.result_register) + ":", hex(result.raw_value))
157
+ ```
158
+
159
+ ### Snapshot Writer Constructors
160
+
161
+ ```python
162
+ from impulse_graph import Writer
163
+ import scipy.sparse as sp
164
+ import torch
165
+
166
+ # From SciPy sparse matrix
167
+ adj = sp.random(1000, 1000, density=0.01, format="csr")
168
+ Writer.from_scipy("scipy_graph.imps", adj)
169
+
170
+ # From PyTorch COO edge_index
171
+ edge_index = torch.tensor([[0, 1, 2], [1, 2, 0]], dtype=torch.int64)
172
+ Writer.from_torch("torch_graph.imps", edge_index, num_nodes=3)
173
+ ```