docs: proper README with LearnerND integration guide and example scripts

basnijholt · basnijholt · commit 4e49e893fac1 · 2026-04-04T23:11:25.000-07:00
diff --git a/README.md b/README.md
@@ -1,124 +1,130 @@
 # adaptive-triangulation
 
-Fast N-dimensional Delaunay triangulation in Rust with Python bindings.
+[![CI](https://github.com/python-adaptive/adaptive-triangulation/actions/workflows/ci.yml/badge.svg)](https://github.com/python-adaptive/adaptive-triangulation/actions)
+[![License](https://img.shields.io/badge/license-BSD--3--Clause-blue.svg)](LICENSE)
 
-[![PyPI](https://img.shields.io/pypi/v/adaptive-triangulation)](https://pypi.org/project/adaptive-triangulation/)
-[![Python](https://img.shields.io/pypi/pyversions/adaptive-triangulation)](https://pypi.org/project/adaptive-triangulation/)
-[![License](https://img.shields.io/github/license/python-adaptive/adaptive-triangulation)](LICENSE)
-[![CI](https://img.shields.io/github/actions/workflow/status/python-adaptive/adaptive-triangulation/ci.yml)](https://github.com/python-adaptive/adaptive-triangulation/actions)
-[![Downloads](https://img.shields.io/pypi/dm/adaptive-triangulation)](https://pypi.org/project/adaptive-triangulation/)
+Fast N-dimensional Delaunay triangulation in Rust with Python bindings (PyO3).
+Drop-in replacement for [adaptive](https://github.com/python-adaptive/adaptive)'s `Triangulation` class — **5-99× faster**.
 
-`adaptive-triangulation` is a Rust/PyO3 implementation of the incremental Bowyer-Watson
-algorithm for Delaunay triangulation. It is designed as a fast drop-in triangulation backend for
-`adaptive`, while remaining useful as a standalone computational geometry package for 2D, 3D, and
-higher-dimensional point sets.
+## Performance
+
+### Standalone triangulation (incremental insertion)
+| Case | Rust | Python | Speedup |
+|---|---:|---:|---:|
+| 2D, 1K pts | 38.5 ms | 668 ms | **17×** |
+| 2D, 5K pts | 260 ms | 8,547 ms | **33×** |
+| 3D, 500 pts | 133 ms | 5,571 ms | **42×** |
+
+### LearnerND integration (end-to-end, `ring_of_fire` 2D)
+| N pts | Learner2D (scipy) | LearnerND (Python) | LearnerND (Rust) |
+|---|---:|---:|---:|
+| 1,000 | 0.34 s | 0.91 s | **0.23 s** |
+| 2,000 | 1.17 s | 1.80 s | **0.38 s** |
+| 5,000 | 6.99 s | 4.57 s | **0.99 s** |
+
+LearnerND + Rust is **5× faster** than LearnerND + Python, and **7× faster** than Learner2D at 5K points.
 
 ## Installation
 
 ```bash
 pip install adaptive-triangulation
 ```
 
-## Quick Start
+Requires a Rust toolchain for building from source. Pre-built wheels are available for common platforms via CI.
+
+## Quick start
 
 ```python
-import adaptive_triangulation as at
-import numpy as np
-
-# 2D triangulation
-points = [[0, 0], [1, 0], [0, 1], [1, 1], [0.5, 0.5]]
-tri = at.Triangulation(points)
-print(f"Simplices: {tri.simplices}")
-
-# Incremental point insertion
-deleted, added = tri.add_point((0.25, 0.75))
-print(f"Deleted simplices: {deleted}")
-print(f"Added simplices: {added}")
-
-# Circumsphere queries
-for simplex in tri.simplices:
-    center, radius = tri.circumscribed_circle(simplex)
-    print(simplex, center, radius)
-
-# Works in any dimension
-points_3d = np.random.rand(10, 3).tolist()
-tri3d = at.Triangulation(points_3d)
-print(f"3D simplices: {len(tri3d.simplices)}")
+from adaptive_triangulation import Triangulation
+
+# Build a 2D triangulation
+tri = Triangulation([(0, 0), (1, 0), (0, 1), (1, 1)])
+
+# Insert points incrementally (Bowyer-Watson)
+deleted, added = tri.add_point((0.5, 0.5))
+
+# Query properties
+print(len(tri.simplices))     # number of triangles
+print(tri.dim)                # 2
+print(tri.reference_invariant())  # True
 ```
 
-Standalone geometry helpers are also available:
+## Usage with adaptive's LearnerND
+
+This is a drop-in replacement for `adaptive`'s built-in triangulation.
+Monkey-patch the module to use Rust triangulation everywhere:
 
 ```python
 import adaptive_triangulation as at
+from adaptive.learner import learnerND as lnd_mod
+from adaptive.learner.learnerND import LearnerND
+
+# Replace both the class and standalone functions
+lnd_mod.Triangulation = at.Triangulation
+lnd_mod.circumsphere = at.circumsphere
+lnd_mod.simplex_volume_in_embedding = at.simplex_volume_in_embedding
+lnd_mod.point_in_simplex = at.point_in_simplex
 
-triangle = [[0.0, 0.0], [1.0, 0.0], [0.0, 1.0]]
-center, radius = at.circumsphere(triangle)
-inside = at.point_in_simplex([0.25, 0.25], triangle)
-area = at.volume(triangle)
+# Now use LearnerND as normal — it's 5× faster
+learner = LearnerND(my_function, bounds=[(-1, 1), (-1, 1)])
 ```
 
-## Performance
+See [`examples/adaptive_learnernd.py`](examples/adaptive_learnernd.py) for a full working example with timing comparison.
+
+## API
 
-The table below compares release-mode `adaptive-triangulation` against the Python reference
-implementation used in the test suite on the same machine. Each case builds a triangulation from a
-minimal seed simplex and inserts the remaining points incrementally.
-
-| Case | Rust (`maturin develop --release`) | Python reference | Speedup |
-| --- | ---: | ---: | ---: |
-| 2D, 1,000 points | 38.5 ms | 668.1 ms | 17.4x |
-| 2D, 5,000 points | 259.8 ms | 8547.2 ms | 32.9x |
-| 3D, 500 points | 133.4 ms | 5570.9 ms | 41.8x |
-
-Absolute timings will vary by machine, but the release build consistently outperforms the pure
-Python reference by a wide margin on construction and incremental insertion workloads.
-
-## API Reference
-
-### Module attributes
-
-- `__version__`: Package version sourced from `Cargo.toml`.
-
-### `Triangulation`
-
-- `Triangulation(coords)`: Build an N-dimensional Delaunay triangulation from points in general position.
-- `add_point(point, simplex=None, transform=None)`: Insert one point and return `(deleted_simplices, added_simplices)`.
-- `add_simplex(simplex)`: Insert a simplex directly into the triangulation state.
-- `delete_simplex(simplex)`: Remove a simplex from the triangulation state.
-- `locate_point(point)`: Return the simplex containing a query point, or an empty tuple when none is found.
-- `get_reduced_simplex(point, simplex, eps=1e-8)`: Reduce a simplex to the smallest face containing the point.
-- `circumscribed_circle(simplex, transform=None)`: Compute the circumsphere center and radius for a simplex.
-- `point_in_circumcircle(pt_index, simplex, transform=None)`: Check whether a stored vertex lies inside a simplex circumsphere.
-- `point_in_cicumcircle(pt_index, simplex, transform=None)`: Legacy alias for `point_in_circumcircle`.
-- `point_in_simplex(point, simplex, eps=1e-8)`: Test whether a point lies inside a simplex.
-- `volume(simplex)`: Compute the volume of one simplex by vertex index.
-- `volumes()`: Return the volumes of all simplices in the triangulation.
-- `faces(dim=None, simplices=None, vertices=None)`: Iterate over faces filtered by dimension, simplices, or vertices.
-- `containing(face)`: Return the simplices that contain a face.
-- `get_vertices(indices)`: Fetch vertex coordinates for a sequence of vertex indices.
-- `bowyer_watson(pt_index, containing_simplex=None, transform=None)`: Run one Bowyer-Watson insertion step for an existing vertex.
-- `reference_invariant()`: Check internal consistency against the reference invariants used by the tests.
-- `vertex_invariant(vertex)`: Compatibility placeholder that currently raises `NotImplementedError`.
-- `convex_invariant(vertex)`: Compatibility placeholder that currently raises `NotImplementedError`.
-- `vertices`: Vertex coordinates stored by the triangulation.
-- `simplices`: Set of simplices represented as tuples of vertex indices.
-- `vertex_to_simplices`: Reverse map from vertex index to incident simplices.
-- `hull`: Set of vertex indices on the convex hull.
-- `dim`: Spatial dimension of the triangulation.
-- `default_transform`: Identity metric transform for the current dimension.
+### `Triangulation` class
+
+```python
+tri = Triangulation(coords)           # Build from initial points
+tri.add_point(point)                   # Incremental insertion → (deleted, added)
+tri.locate_point(point)                # Find containing simplex
+tri.circumscribed_circle(simplex)      # → (center, radius)
+tri.volume(simplex)                    # Simplex volume
+tri.volumes()                          # All simplex volumes
+tri.point_in_simplex(point, simplex)   # Containment test
+tri.point_in_circumcircle(pt, simplex) # Circumcircle test
+tri.bowyer_watson(pt_index)            # Direct Bowyer-Watson
+tri.reference_invariant()              # Consistency check
+```
+
+**Properties:** `vertices`, `simplices`, `vertex_to_simplices`, `hull`, `dim`, `default_transform`
 
 ### Standalone functions
 
-- `circumsphere(points)`: Compute the circumsphere of a simplex given explicit coordinates.
-- `fast_2d_circumcircle(points)`: Fast circumcircle routine specialized for three 2D points.
-- `fast_3d_circumsphere(points)`: Fast circumsphere routine specialized for four 3D points.
-- `fast_3d_circumcircle(points)`: Alias for the 3D circumsphere helper.
-- `point_in_simplex(point, simplex, eps=1e-8)`: Generic point-in-simplex predicate.
-- `fast_2d_point_in_simplex(point, simplex, eps=1e-8)`: Fast 2D point-in-triangle predicate.
-- `volume(simplex)`: Compute the volume of a simplex from coordinates.
-- `simplex_volume_in_embedding(vertices)`: Compute simplex volume in a higher-dimensional embedding space.
-- `orientation(face, origin)`: Return the orientation of a face relative to an origin point.
-- `fast_norm(point)`: Compute the Euclidean norm of a point.
+```python
+from adaptive_triangulation import (
+    circumsphere,              # General circumsphere
+    fast_2d_circumcircle,      # Optimized 2D
+    fast_3d_circumsphere,      # Optimized 3D
+    point_in_simplex,          # Containment test
+    volume,                    # Simplex volume
+    simplex_volume_in_embedding,  # Volume in embedding space
+    orientation,               # Face orientation
+)
+```
+
+## Examples
+
+- [`examples/basic_usage.py`](examples/basic_usage.py) — Core API walkthrough
+- [`examples/adaptive_learnernd.py`](examples/adaptive_learnernd.py) — LearnerND integration with timing
+- [`examples/benchmark_vs_python.py`](examples/benchmark_vs_python.py) — Standalone benchmarks across dimensions
+
+## Development
+
+```bash
+# Build (requires Rust toolchain)
+pip install maturin
+maturin develop --release
+
+# Tests
+cargo test                    # Rust tests
+python -m pytest tests/ -v    # Python tests
+
+# Linting
+pre-commit run --all-files    # ruff, mypy, cargo fmt, cargo clippy
+```
 
 ## License
 
-BSD-3-Clause, matching the `adaptive` project. See [LICENSE](LICENSE).
+BSD-3-Clause
diff --git a/examples/adaptive_learnernd.py b/examples/adaptive_learnernd.py
@@ -0,0 +1,54 @@
+"""Using adaptive-triangulation with adaptive's LearnerND.
+
+Drop-in replacement for adaptive's built-in Triangulation class,
+providing 5× speedup for LearnerND and 7× vs Learner2D at 5K points.
+
+Requirements:
+    pip install adaptive adaptive-triangulation
+"""
+
+import time
+
+import numpy as np
+
+import adaptive_triangulation as at
+from adaptive.learner import learnerND as lnd_mod
+from adaptive.learner.learnerND import LearnerND
+
+
+def ring_of_fire(xy: tuple[float, float]) -> float:
+    """A 2D function with a ring-shaped feature — good test for adaptive sampling."""
+    x, y = xy
+    a, d = 0.2, 0.5
+    return x + np.exp(-((x**2 + y**2 - d**2) ** 2) / a**4)
+
+
+bounds = [(-1, 1), (-1, 1)]
+n_points = 2000
+
+# --- Baseline: pure Python triangulation ---
+t0 = time.perf_counter()
+learner_py = LearnerND(ring_of_fire, bounds=bounds)
+for _ in range(n_points):
+    points, _ = learner_py.ask(1)
+    for p in points:
+        learner_py.tell(p, ring_of_fire(p))
+t_python = time.perf_counter() - t0
+print(f"Python triangulation: {t_python:.2f}s ({n_points} points)")
+
+# --- Rust triangulation: monkey-patch the module ---
+# Replace both the Triangulation class AND the standalone geometry functions
+lnd_mod.Triangulation = at.Triangulation
+lnd_mod.circumsphere = at.circumsphere
+lnd_mod.simplex_volume_in_embedding = at.simplex_volume_in_embedding
+lnd_mod.point_in_simplex = at.point_in_simplex
+
+t0 = time.perf_counter()
+learner_rust = LearnerND(ring_of_fire, bounds=bounds)
+for _ in range(n_points):
+    points, _ = learner_rust.ask(1)
+    for p in points:
+        learner_rust.tell(p, ring_of_fire(p))
+t_rust = time.perf_counter() - t0
+print(f"Rust triangulation:   {t_rust:.2f}s ({n_points} points)")
+print(f"Speedup: {t_python / t_rust:.1f}×")
diff --git a/examples/basic_usage.py b/examples/basic_usage.py
@@ -0,0 +1,45 @@
+"""Basic usage of adaptive-triangulation.
+
+Demonstrates core Triangulation API: construction, point insertion,
+simplex queries, and geometry computations.
+"""
+
+import numpy as np
+
+from adaptive_triangulation import Triangulation, circumsphere, volume
+
+# Create a 2D triangulation from initial points
+points = [(0.0, 0.0), (1.0, 0.0), (0.0, 1.0), (1.0, 1.0)]
+tri = Triangulation(points)
+
+print(f"Vertices: {len(tri.vertices)}")
+print(f"Simplices: {len(tri.simplices)}")
+print(f"Dimension: {tri.dim}")
+
+# Add a point incrementally (Bowyer-Watson insertion)
+deleted, added = tri.add_point((0.5, 0.5))
+print(f"\nAfter adding (0.5, 0.5):")
+print(f"  Deleted simplices: {len(deleted)}")
+print(f"  Added simplices: {len(added)}")
+print(f"  Total simplices: {len(tri.simplices)}")
+
+# Query geometry
+for simplex in tri.simplices:
+    verts = tri.get_vertices(simplex)
+    center, radius = tri.circumscribed_circle(simplex)
+    vol = tri.volume(simplex)
+    print(f"  Simplex {simplex}: volume={vol:.4f}, circumradius={radius:.4f}")
+
+# Standalone functions work on raw point arrays
+pts = np.array([[0.0, 0.0], [1.0, 0.0], [0.5, 0.866]])
+center, radius = circumsphere(pts)
+vol = volume(pts)
+print(f"\nStandalone: circumcenter={center}, radius={radius:.4f}, volume={vol:.4f}")
+
+# Locate which simplex contains a query point
+containing = tri.locate_point((0.3, 0.3))
+print(f"\nPoint (0.3, 0.3) is in simplex: {containing}")
+
+# Check invariants
+assert tri.reference_invariant(), "Triangulation invariant violated!"
+print("\nAll invariants passed ✓")
diff --git a/examples/benchmark_vs_python.py b/examples/benchmark_vs_python.py
