spatial-graph 0.0.2__tar.gz → 0.0.4__tar.gz

spatial_graph-0.0.2/.github/workflows/ci.yaml → spatial_graph-0.0.4/.github/workflows/ci.yml

@@ -42,6 +42,25 @@ jobs:
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
 
+  benchmarks:
+    runs-on: ubuntu-latest
+    env:
+      UV_NO_SYNC: "1"
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.13"
+          enable-cache: true
+
+      - name: install
+        run: uv sync --no-dev --group test-codspeed
+
+      - name: Run benchmarks
+        uses: CodSpeedHQ/action@v3
+        with:
+          run: uv run pytest -W ignore --codspeed -v --color=yes
+
   deploy:
     name: Deploy
     needs: test
@@ -74,3 +93,15 @@ jobs:
         with:
           generate_release_notes: true
           files: "./dist/*"
+
+  docker-test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Build and test Docker image
+        run: |
+          docker build -t spatial_graph .
+          docker run --rm spatial_graph

spatial_graph-0.0.4/.github/workflows/docs.yaml

@@ -0,0 +1,29 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: write
+
+jobs:
+  docs:
+    name: Deploy Documentation
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email github-actions[bot]@users.noreply.github.com
+      - uses: astral-sh/setup-uv@v6
+      - name: Deploy documentation
+        run: uv run --group docs mkdocs gh-deploy --strict --force

{spatial_graph-0.0.2 → spatial_graph-0.0.4}/.gitignore

@@ -11,6 +11,8 @@ build
 dist
 .vscode
 docs/_build/
+coverage.xml
+site
 
 # remove me to enforce synchrony across development environments
 uv.lock

{spatial_graph-0.0.2 → spatial_graph-0.0.4}/.pre-commit-config.yaml

@@ -17,7 +17,7 @@ repos:
   - repo: https://github.com/astral-sh/ruff-pre-commit
     rev: v0.12.2
     hooks:
-      - id: ruff
+      - id: ruff-check
         args: [--fix, --unsafe-fixes]
       - id: ruff-format
 

spatial_graph-0.0.4/Dockerfile

@@ -0,0 +1,38 @@
+FROM ubuntu:24.04
+
+ENV DEBIAN_FRONTEND=noninteractive \
+    MAMBA_ROOT_PREFIX=/opt/conda \
+    PATH=/opt/conda/bin:$PATH
+
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends \
+      git curl tar bzip2 ca-certificates && \
+    rm -rf /var/lib/apt/lists/*
+
+# auto-detect arch and grab the matching micromamba binary
+RUN set -eux; \
+    arch="$(uname -m)"; \
+    case "$arch" in \
+      x86_64)    url_arch=linux-64 ;; \
+      aarch64|arm64) url_arch=linux-aarch64 ;; \
+      ppc64le)   url_arch=linux-ppc64le ;; \
+      *)         echo "Unsupported arch: $arch"; exit 1 ;; \
+    esac; \
+    curl -Ls "https://micro.mamba.pm/api/micromamba/$url_arch/latest" \
+      | tar -xvj -C /usr/local/bin bin/micromamba; \
+    chmod +x /usr/local/bin/bin/micromamba; \
+    mv /usr/local/bin/bin/micromamba /usr/local/bin/micromamba; \
+    rmdir /usr/local/bin/bin
+
+
+WORKDIR /app
+COPY . /app
+
+RUN micromamba create -y -n test-env -c conda-forge python=3.12 pip compilers
+RUN micromamba run -n test-env pip install -e . --group test
+
+SHELL ["micromamba", "run", "-n", "test-env", "/bin/bash", "-o", "pipefail", "-c"]
+
+
+# when you docker run, this will invoke pytest from inside test-env
+CMD ["micromamba", "run", "-n", "test-env", "pytest", "-q", "-x"]

{spatial_graph-0.0.2 → spatial_graph-0.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spatial-graph
-Version: 0.0.2
+Version: 0.0.4
 Summary: A spatial graph datastructure for python.
 Project-URL: homepage, https://github.com/funkelab/spatial_graph
 Project-URL: repository, https://github.com/funkelab/spatial_graph
@@ -20,7 +20,7 @@ Requires-Python: >=3.9
 Requires-Dist: ct3>=3.3.3
 Requires-Dist: numpy
 Requires-Dist: setuptools>=75.8.0
-Requires-Dist: witty>=v0.2.1
+Requires-Dist: witty>=v0.3.0
 Description-Content-Type: text/markdown
 
 # spatial-graph
@@ -28,8 +28,9 @@ Description-Content-Type: text/markdown
 [![License](https://img.shields.io/pypi/l/spatial-graph.svg?color=green)](https://github.com/funkelab/spatial_graph/raw/main/LICENSE)
 [![PyPI](https://img.shields.io/pypi/v/spatial-graph.svg?color=green)](https://pypi.org/project/spatial-graph)
 [![Python Version](https://img.shields.io/pypi/pyversions/spatial-graph.svg?color=green)](https://python.org)
-[![CI](https://github.com/funkelab/spatial_graph/actions/workflows/ci.yaml/badge.svg)](https://github.com/funkelab/spatial_graph/actions/workflows/ci.yaml)
+[![CI](https://github.com/funkelab/spatial_graph/actions/workflows/ci.yml/badge.svg)](https://github.com/funkelab/spatial_graph/actions/workflows/ci.yml)
 [![codecov](https://codecov.io/gh/funkelab/spatial_graph/branch/main/graph/badge.svg)](https://codecov.io/gh/funkelab/spatial_graph)
+[![CodSpeed](https://img.shields.io/endpoint?url=https://codspeed.io/badge.json)](https://codspeed.io/funkelab/spatial_graph)
 
 `spatial_graph` provides a data structure for directed and undirected graphs,
 where each node has an nD position (in time or space).
@@ -74,7 +75,6 @@ graph = sg.SpatialGraph(
     node_attr_dtypes={"position": "double[3]"},
     edge_attr_dtypes={"score": "float32"},
     position_attr="position",
-    directed=False,
 )
 ```
 
@@ -133,8 +133,35 @@ graph.remove_nodes(nodes[:1000])
 
 A `SpatialGraph` consists of three data structures:
 
-* The `Graph` itself, holding nodes, edges, and their attributes ([graphlite](https://github.com/haasdo95/graphlite)).
-* Two R-trees for spatial node and edge queries (based on [rtree.c](https://github.com/tidwall/rtree.c)).
+* The `Graph` itself, holding nodes, edges, and their attributes
+  ([graphlite](https://github.com/haasdo95/graphlite)).
+* Two R-trees for spatial node and edge queries (based on
+  [rtree.c](https://github.com/tidwall/rtree.c)). We modified the original code
+  to also include a fast kNN search.
+
+## Cross-Platform Support
+
+`spatial_graph` compiles C/C++ code at runtime, and as such needs access to a
+compiler. If you already have one, great! You can use the PyPI package.
+
+If you (or your users) don't have a compiler installed, you either need to
+
+1. Install a compiler. This might be weird for non-technical users.
+2. Install `spatial_graph` from `conda-forge`, where we include a compiler
+   (`clang`) in its dependencies.
+
+### Why is this so complicated?
+
+There is no cross-platform C/C++ compiler that we can install using `pip`.
+[`numba`](https://github.com/numba/numba) is maybe the closest to having solved
+that problem: `numba` does compile during runtime even if you don't have a
+compiler locally installed. This works because `numba` is generating LLVM IR,
+an intermediate representation language that LLVM can compile into machine
+code. `numba` depends on [`llvmlite`](https://github.com/numba/llvmlite), which
+provides a subset of the LLVM API, statically linked into the binaries in that
+package. This is just enough to compile the `numba` generated LLVM IR into
+machine code. We can't use this strategy, because we compile general C/C++
+code. Converting that into LLVM IR is exactly what we need a compiler for.
 
 ## For Developers
 
@@ -147,3 +174,14 @@ git push upstream --follow-tags
 ```
 
 This will trigger the CI workflow, which will build the package and upload it to PyPI.
+
+### Testing in a conda environment
+
+To simulate a naive user environment, with *no* assumptions made about the
+availability of a C/C++ compiler, you can run the included Dockerfile
+(where the key part of the conda env is the `compilers` package):
+
+```bash
+docker build -t spatial_graph .
+docker run --rm spatial_graph
+```

{spatial_graph-0.0.2 → spatial_graph-0.0.4}/README.md

@@ -3,8 +3,9 @@
 [![License](https://img.shields.io/pypi/l/spatial-graph.svg?color=green)](https://github.com/funkelab/spatial_graph/raw/main/LICENSE)
 [![PyPI](https://img.shields.io/pypi/v/spatial-graph.svg?color=green)](https://pypi.org/project/spatial-graph)
 [![Python Version](https://img.shields.io/pypi/pyversions/spatial-graph.svg?color=green)](https://python.org)
-[![CI](https://github.com/funkelab/spatial_graph/actions/workflows/ci.yaml/badge.svg)](https://github.com/funkelab/spatial_graph/actions/workflows/ci.yaml)
+[![CI](https://github.com/funkelab/spatial_graph/actions/workflows/ci.yml/badge.svg)](https://github.com/funkelab/spatial_graph/actions/workflows/ci.yml)
 [![codecov](https://codecov.io/gh/funkelab/spatial_graph/branch/main/graph/badge.svg)](https://codecov.io/gh/funkelab/spatial_graph)
+[![CodSpeed](https://img.shields.io/endpoint?url=https://codspeed.io/badge.json)](https://codspeed.io/funkelab/spatial_graph)
 
 `spatial_graph` provides a data structure for directed and undirected graphs,
 where each node has an nD position (in time or space).
@@ -49,7 +50,6 @@ graph = sg.SpatialGraph(
     node_attr_dtypes={"position": "double[3]"},
     edge_attr_dtypes={"score": "float32"},
     position_attr="position",
-    directed=False,
 )
 ```
 
@@ -108,8 +108,35 @@ graph.remove_nodes(nodes[:1000])
 
 A `SpatialGraph` consists of three data structures:
 
-* The `Graph` itself, holding nodes, edges, and their attributes ([graphlite](https://github.com/haasdo95/graphlite)).
-* Two R-trees for spatial node and edge queries (based on [rtree.c](https://github.com/tidwall/rtree.c)).
+* The `Graph` itself, holding nodes, edges, and their attributes
+  ([graphlite](https://github.com/haasdo95/graphlite)).
+* Two R-trees for spatial node and edge queries (based on
+  [rtree.c](https://github.com/tidwall/rtree.c)). We modified the original code
+  to also include a fast kNN search.
+
+## Cross-Platform Support
+
+`spatial_graph` compiles C/C++ code at runtime, and as such needs access to a
+compiler. If you already have one, great! You can use the PyPI package.
+
+If you (or your users) don't have a compiler installed, you either need to
+
+1. Install a compiler. This might be weird for non-technical users.
+2. Install `spatial_graph` from `conda-forge`, where we include a compiler
+   (`clang`) in its dependencies.
+
+### Why is this so complicated?
+
+There is no cross-platform C/C++ compiler that we can install using `pip`.
+[`numba`](https://github.com/numba/numba) is maybe the closest to having solved
+that problem: `numba` does compile during runtime even if you don't have a
+compiler locally installed. This works because `numba` is generating LLVM IR,
+an intermediate representation language that LLVM can compile into machine
+code. `numba` depends on [`llvmlite`](https://github.com/numba/llvmlite), which
+provides a subset of the LLVM API, statically linked into the binaries in that
+package. This is just enough to compile the `numba` generated LLVM IR into
+machine code. We can't use this strategy, because we compile general C/C++
+code. Converting that into LLVM IR is exactly what we need a compiler for.
 
 ## For Developers
 
@@ -122,3 +149,14 @@ git push upstream --follow-tags
 ```
 
 This will trigger the CI workflow, which will build the package and upload it to PyPI.
+
+### Testing in a conda environment
+
+To simulate a naive user environment, with *no* assumptions made about the
+availability of a C/C++ compiler, you can run the included Dockerfile
+(where the key part of the conda env is the `compilers` package):
+
+```bash
+docker build -t spatial_graph .
+docker run --rm spatial_graph
+```

spatial_graph-0.0.4/docs/index.md

@@ -0,0 +1,90 @@
+# spatial-graph
+
+`spatial-graph` provides a data structure for directed and undirected graphs,
+where each node has an nD position (in time or space).
+
+It leverages well-in-time compiled C++ code for efficient graph operations,
+coupled with an rtree implementation for fast spatial queries.
+
+## Goals
+
+- Support for arbitrary number of dimensions
+- Typed node identifiers and attributes
+    - Any fixed-length type that is supported by `numpy`
+- Efficient node/edge queries by
+    - ROI
+    - kNN (by points / lines)
+- numpy-like interface for efficient:
+    - Graph population and manipulation
+    - Query results
+    - Attribute access
+- Minimal memory footprint
+- Minimal dependencies
+- PYX API for graph algorithms in C/C++
+
+## Basic Usage
+
+Graph creation:
+
+```python
+graph = sg.SpatialGraph(
+    ndims=3,
+    node_dtype="uint64",
+    node_attr_dtypes={"position": "double[3]"},
+    edge_attr_dtypes={"score": "float32"},
+    position_attr="position",
+)
+```
+
+Adding nodes/edges:
+
+```python
+graph.add_nodes(
+    np.array([1, 2, 3, 4, 5], dtype="uint64"),
+    position=np.array(
+        [
+            [0.1, 0.1, 0.1],
+            [0.2, 0.2, 0.2],
+            [0.3, 0.3, 0.3],
+            [0.4, 0.4, 0.4],
+            [0.5, 0.5, 0.5],
+        ],
+        dtype="double",
+    ),
+)
+
+graph.add_edges(
+    np.array([[1, 2], [3, 4], [5, 1]], dtype="uint64"),
+    score=np.array([0.2, 0.3, 0.4], dtype="float32"),
+)
+```
+
+Query nodes/edges in ROI:
+
+```python
+# nodes/edges will be numpy arrays of dtype uint64 and shape (n,)/(n, 2)
+nodes = graph.query_nodes_in_roi(np.array([[0.0, 0.0, 0.0], [0.25, 0.25, 0.25]]))
+edges = graph.query_edges_in_roi(np.array([[0.0, 0.0, 0.0], [0.25, 0.25, 0.25]]))
+```
+
+Query nodes/edges by position:
+
+```python
+nodes = graph.query_nearest_nodes(np.array([0.3, 0.3, 0.3]), k=3)
+edges = graph.query_nearest_edges(np.array([0.3, 0.3, 0.3]), k=3)
+```
+
+Access node/edge attributes:
+
+```python
+node_positions = graph.node_attrs[nodes].position
+edge_scores = graph.edge_attrs[edges].score
+```
+
+Delete nodes/edges:
+
+```python
+graph.remove_nodes(nodes[:1000])
+```
+
+See the [API documentation](./reference) for more details.

{spatial_graph-0.0.2 → spatial_graph-0.0.4}/examples/basic_usage.py

@@ -23,7 +23,6 @@ def main():
         node_attr_dtypes={"position": "double[3]"},
         edge_attr_dtypes={"score": "float32"},
         position_attr="position",
-        directed=False,
     )
     print(f"   Created graph with {graph.ndims} dimensions")
     print(f"   Node dtype: {graph.node_dtype}")

{spatial_graph-0.0.2 → spatial_graph-0.0.4}/examples/query_nearest_vispy.py

@@ -30,7 +30,6 @@ graph = SpatialGraph(
     node_attr_dtypes={"position": "double[3]"},
     edge_attr_dtypes={"score": "float32"},
     position_attr="position",
-    directed=False,
 )
 nodes = np.arange(100_000, dtype="uint64")
 graph.add_nodes(nodes, position=np.random.random((100_000, 3)))

spatial_graph-0.0.4/mkdocs.yml

@@ -0,0 +1,44 @@
+site_name: "spatial-graph"
+site_url: https://github.com/funkelab/spatial_graph
+site_description: >-
+  High performance spatial graph library for Python
+# Repository
+repo_name: funkelab/spatial_graph
+repo_url: https://github.com/funkelab/spatial_graph
+
+theme:
+  name: material
+  palette:
+    scheme: default
+    primary: pink
+  features:
+    - content.tabs.link
+    - content.code.copy
+    - content.code.annotate
+    - navigation.instant
+
+plugins:
+  - search
+  - api-autonav:
+      modules: ["src/spatial_graph"]
+  - mkdocstrings:
+      handlers:
+        python:
+          inventories:
+            - https://docs.python.org/3/objects.inv
+          options:
+            docstring_section_style: list # or "table"
+            docstring_style: "numpy"
+            preload_modules: [spatial_graph]
+            filters: ["!^_"]
+            heading_level: 1
+            merge_init_into_class: true
+            parameter_headings: true
+            separate_signature: true
+            show_root_heading: true
+            show_signature_annotations: true
+            show_symbol_type_heading: true
+            show_symbol_type_toc: true
+            summary: true
+            inherited_members: true
+            force_inspection: true

{spatial_graph-0.0.2 → spatial_graph-0.0.4}/pyproject.toml

@@ -5,7 +5,6 @@ build-backend = "hatchling.build"
 [tool.hatch.version]
 source = "vcs"
 
-
 [project]
 name = "spatial-graph"
 dynamic = ["version"]
@@ -28,17 +27,26 @@ classifiers = [
   "Programming Language :: Python :: 3.13",
   "Typing :: Typed",
 ]
-dependencies = ["witty>=v0.2.1", "CT3>=3.3.3", "numpy", "setuptools>=75.8.0"]
+dependencies = ["witty>=v0.3.0", "CT3>=3.3.3", "numpy", "setuptools>=75.8.0"]
 
 [dependency-groups]
+test = ["pytest>=8.3.5", "pytest-cov>=6.1.1"]
+test-codspeed = [{ include-group = "test" }, "pytest-codspeed >=3.2.0"]
 dev = [
+  { include-group = "test" },
   "ipython>=8.18.1",
   "mypy>=1.15.0",
   "pre-commit>=4.2.0",
-  "pytest>=8.3.5",
-  "pytest-cov>=6.1.1",
+  "pytest-benchmark>=5.1.0",  # specifically excluded from test group for ci
   "ruff>=0.11.10",
 ]
+docs = [
+  "mkdocs>=1.6.1",
+  "mkdocs-api-autonav>=0.3.0",
+  "mkdocs-material>=9.6.15",
+  "mkdocstrings-python>=1.16.12",
+  "ruff",
+]
 
 
 [project.urls]
@@ -48,6 +56,8 @@ repository = "https://github.com/funkelab/spatial_graph"
 [tool.ruff]
 target-version = "py39"
 line-length = 88
+fix = true
+unsafe-fixes = true
 
 [tool.ruff.lint]
 select = [
@@ -75,3 +85,20 @@ pretty = true
 [tool.pytest.ini_options]
 addopts = "-v --color=yes"
 filterwarnings = ["error", "ignore:'cgi' is deprecated"]
+
+
+[tool.coverage.report]
+show_missing = true
+exclude_lines = [
+  "pragma: no cover",
+  "if TYPE_CHECKING:",
+  "@overload",
+  "except ImportError",
+  "raise AssertionError",
+  "\\.\\.\\.",
+  "if __name__ == .__main__.:",
+  "raise NotImplementedError",
+]
+
+[tool.coverage.run]
+source = ['spatial_graph']

spatial_graph-0.0.4/src/spatial_graph/__init__.py

@@ -0,0 +1,24 @@
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("spatial_graph")
+except PackageNotFoundError:  # pragma: no cover
+    __version__ = "unknown"
+
+
+from ._graph import DiGraph, Graph, GraphBase
+from ._rtree import LineRTree, PointRTree
+from ._spatial_graph import SpatialDiGraph, SpatialGraph, SpatialGraphBase
+from ._util import create_graph
+
+__all__ = [
+    "DiGraph",
+    "Graph",
+    "GraphBase",
+    "LineRTree",
+    "PointRTree",
+    "SpatialDiGraph",
+    "SpatialGraph",
+    "SpatialGraphBase",
+    "create_graph",
+]

spatial_graph-0.0.2/src/spatial_graph/dtypes.py → spatial_graph-0.0.4/src/spatial_graph/_dtypes.py

@@ -87,18 +87,15 @@ class DType:
             "base_c_type[::1]"      if not an array type and add_dim
             "base_c_type[:, ::1]"   if an array type and add_dim
 
-        Args:
-
-            use_memory_view:
-
-                If set, will produce "dtype[::1]" instead of "dtype[dim]" for
-                array types.
-
-            add_dim:
-
-                Append a dim to the type, e.g., "int32_t[::1]" instead of
-                "int32_t" for dtype "int32". If this DType is already an array,
-                will create a 2D array, e.g., "int32_t[:, ::1]".
+        Parameters
+        ----------
+        use_memory_view : bool
+            If set, will produce "dtype[::1]" instead of "dtype[dim]" for
+            array types.
+        add_dim : bool
+            Append a dim to the type, e.g., "int32_t[::1]" instead of
+            "int32_t" for dtype "int32". If this DType is already an array,
+            will create a 2D array, e.g., "int32_t[:, ::1]".
         """
         if self.is_array:
             if add_dim:

spatial_graph-0.0.4/src/spatial_graph/_graph/__init__.py

@@ -0,0 +1,3 @@
+from .graph import DiGraph, Graph, GraphBase
+
+__all__ = ["DiGraph", "Graph", "GraphBase"]