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.
- impulse_graph-0.10.0/MANIFEST.in +26 -0
- impulse_graph-0.10.0/PKG-INFO +208 -0
- impulse_graph-0.10.0/README.md +173 -0
- impulse_graph-0.10.0/impulse-cpp/include/contracts/contracts_chunk1.hpp +522 -0
- impulse_graph-0.10.0/impulse-cpp/include/contracts/contracts_chunk2.hpp +462 -0
- impulse_graph-0.10.0/impulse-cpp/include/contracts/contracts_chunk3.hpp +403 -0
- impulse_graph-0.10.0/impulse-cpp/include/contracts/contracts_chunk4.hpp +412 -0
- impulse_graph-0.10.0/impulse-cpp/include/contracts/contracts_chunk5.hpp +277 -0
- impulse_graph-0.10.0/impulse-cpp/include/impulse_assert.h +266 -0
- impulse_graph-0.10.0/impulse-cpp/include/impulse_bytecode_emitter.hpp +46 -0
- impulse_graph-0.10.0/impulse-cpp/include/impulse_cel.h +2456 -0
- impulse_graph-0.10.0/impulse-cpp/include/impulse_compiler.hpp +1117 -0
- impulse_graph-0.10.0/impulse-cpp/include/impulse_cypher.hpp +955 -0
- impulse_graph-0.10.0/impulse-cpp/include/impulse_datalog.hpp +563 -0
- impulse_graph-0.10.0/impulse-cpp/include/impulse_format_v0_10.h +207 -0
- impulse_graph-0.10.0/impulse-cpp/include/impulse_format_v0_9.h +181 -0
- impulse_graph-0.10.0/impulse-cpp/include/impulse_graph.h +466 -0
- impulse_graph-0.10.0/impulse-cpp/include/impulse_hexio.h +165 -0
- impulse_graph-0.10.0/impulse-cpp/include/impulse_impk.hpp +717 -0
- impulse_graph-0.10.0/impulse-cpp/include/impulse_implog.hpp +19 -0
- impulse_graph-0.10.0/impulse-cpp/include/impulse_impscm.hpp +18 -0
- impulse_graph-0.10.0/impulse-cpp/include/impulse_index.h +170 -0
- impulse_graph-0.10.0/impulse-cpp/include/impulse_math_ops.h +485 -0
- impulse_graph-0.10.0/impulse-cpp/include/impulse_opcode_contracts.hpp +158 -0
- impulse_graph-0.10.0/impulse-cpp/include/impulse_opcode_macros.h +335 -0
- impulse_graph-0.10.0/impulse-cpp/include/impulse_scm_ast.hpp +909 -0
- impulse_graph-0.10.0/impulse-cpp/include/impulse_sexpr.hpp +332 -0
- impulse_graph-0.10.0/impulse-cpp/include/impulse_sha256.h +134 -0
- impulse_graph-0.10.0/impulse-cpp/include/impulse_simd.h +66 -0
- impulse_graph-0.10.0/impulse-cpp/include/impulse_vm.h +702 -0
- impulse_graph-0.10.0/impulse-cpp/include/impulse_vm_fluent.hpp +727 -0
- impulse_graph-0.10.0/impulse-cpp/src/impulse_bytecode_emitter.cpp +541 -0
- impulse_graph-0.10.0/impulse-cpp/src/impulse_graph.cpp +2082 -0
- impulse_graph-0.10.0/impulse-cpp/src/impulse_graph_internal.hpp +232 -0
- impulse_graph-0.10.0/impulse-cpp/src/impulse_index.cpp +882 -0
- impulse_graph-0.10.0/impulse-cpp/src/impulse_simd.cpp +216 -0
- impulse_graph-0.10.0/impulse-cpp/src/impulse_snapshot_writer.cpp +844 -0
- impulse_graph-0.10.0/impulse-cpp/src/impulse_statement_c_api.cpp +845 -0
- impulse_graph-0.10.0/impulse-cpp/src/impulse_vm.cpp +1042 -0
- impulse_graph-0.10.0/impulse-cpp/src/impulse_vm_context.cpp +1381 -0
- impulse_graph-0.10.0/impulse-cpp/src/impulse_vm_fluent.cpp +649 -0
- impulse_graph-0.10.0/impulse-cpp/src/impulse_vm_fluent_internal.hpp +843 -0
- impulse_graph-0.10.0/impulse-cpp/src/impulse_vm_fluent_multilane.cpp +1665 -0
- impulse_graph-0.10.0/impulse-cpp/src/impulse_vm_fluent_traversal.cpp +1321 -0
- impulse_graph-0.10.0/impulse-cpp/src/impulse_vm_internal.hpp +1257 -0
- impulse_graph-0.10.0/impulse-cpp/src/opcodes/shared/coo_walk_common.hpp +97 -0
- impulse_graph-0.10.0/impulse-cpp/src/opcodes/shared/dense_walk_common.hpp +114 -0
- impulse_graph-0.10.0/impulse-cpp/src/opcodes/shared/lane_walk_common.hpp +748 -0
- impulse_graph-0.10.0/impulse-cpp/src/opcodes/shared/mock_attr_common.hpp +105 -0
- impulse_graph-0.10.0/impulse-cpp/src/opcodes/shared/walk_stream_common.hpp +265 -0
- impulse_graph-0.10.0/impulse_graph/__init__.py +755 -0
- impulse_graph-0.10.0/impulse_graph/cypher.py +154 -0
- impulse_graph-0.10.0/impulse_graph/traversal.py +445 -0
- impulse_graph-0.10.0/impulse_graph/vm.py +610 -0
- impulse_graph-0.10.0/impulse_graph.egg-info/PKG-INFO +208 -0
- impulse_graph-0.10.0/impulse_graph.egg-info/SOURCES.txt +83 -0
- impulse_graph-0.10.0/impulse_graph.egg-info/dependency_links.txt +1 -0
- impulse_graph-0.10.0/impulse_graph.egg-info/requires.txt +1 -0
- impulse_graph-0.10.0/impulse_graph.egg-info/top_level.txt +1 -0
- impulse_graph-0.10.0/pyproject.toml +61 -0
- impulse_graph-0.10.0/setup.cfg +4 -0
- impulse_graph-0.10.0/setup.py +143 -0
- impulse_graph-0.10.0/src/impulse_python.cpp +919 -0
- impulse_graph-0.10.0/tests/test_cel_binding.py +80 -0
- impulse_graph-0.10.0/tests/test_cypher.py +87 -0
- impulse_graph-0.10.0/tests/test_domain_traversal.py +208 -0
- impulse_graph-0.10.0/tests/test_errors_and_boundaries.py +88 -0
- impulse_graph-0.10.0/tests/test_interchange.py +100 -0
- impulse_graph-0.10.0/tests/test_issues_57_58_59.py +160 -0
- impulse_graph-0.10.0/tests/test_reachability.py +46 -0
- impulse_graph-0.10.0/tests/test_sampler_and_attributes.py +50 -0
- impulse_graph-0.10.0/tests/test_snapshot.py +46 -0
- impulse_graph-0.10.0/tests/test_swe_sweep_80.py +131 -0
- impulse_graph-0.10.0/tests/test_traversal_analytics.py +100 -0
- impulse_graph-0.10.0/tests/test_vm.py +154 -0
- impulse_graph-0.10.0/tests/test_writer.py +30 -0
- 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
|
+
```
|