holonomy-lib 0.8.0__py3-none-any.whl

holonomy_explorer/__init__.py

@@ -0,0 +1 @@
+"""Local, offline views of computations performed by holonomy_lib."""

holonomy_explorer/__main__.py

@@ -0,0 +1,79 @@
+"""Launch with holonomy-explorer or python -m holonomy_explorer."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import webbrowser
+
+import torch
+
+from .common import Context
+from .server import create_server
+
+# Local-only defaults requested by the explorer brief; every deployment can override.
+DEFAULT_HOST = "127.0.0.1"
+WILDCARD_HOST = "0.0.0.0"  # IPv4 bind-all address; browse via loopback instead.
+DEFAULT_PORT = 8765
+DEFAULT_DTYPE = "float64"
+MAX_PORT = 65535  # TCP port field is an unsigned 16-bit integer.
+
+
+def main() -> None:
+    """Parse deployment settings, print the bound URL, and serve until Ctrl-C."""
+    parser = argparse.ArgumentParser(
+        description="Local holonomy_lib explorer. Offline UI; CPU/CUDA tensors.",
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+    )
+    parser.add_argument(
+        "--host",
+        default=os.getenv("HOLONOMY_EXPLORER_HOST", DEFAULT_HOST),
+        help="bind address; env HOLONOMY_EXPLORER_HOST",
+    )
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=os.getenv("HOLONOMY_EXPLORER_PORT", str(DEFAULT_PORT)),
+        help="TCP port, 0 chooses a free port; env HOLONOMY_EXPLORER_PORT",
+    )
+    parser.add_argument(
+        "--device",
+        default=os.getenv(
+            "HOLONOMY_EXPLORER_DEVICE",
+            "cuda" if torch.cuda.is_available() else "cpu",
+        ),
+        help="torch device; env HOLONOMY_EXPLORER_DEVICE; ROCm also uses cuda",
+    )
+    parser.add_argument(
+        "--dtype",
+        choices=("float32", "float64"),
+        default=os.getenv("HOLONOMY_EXPLORER_DTYPE", DEFAULT_DTYPE),
+        help="tensor precision; env HOLONOMY_EXPLORER_DTYPE",
+    )
+    parser.add_argument(
+        "--no-browser", action="store_true", help="print URL without opening a browser"
+    )
+    args = parser.parse_args()
+    if not 0 <= args.port <= MAX_PORT:
+        parser.error(f"port must be between 0 and {MAX_PORT}")
+    try:
+        context = Context.from_request({"device": args.device, "dtype": args.dtype})
+        server = create_server(args.host, args.port, str(context.device), args.dtype)
+    except (OSError, ValueError, RuntimeError) as error:
+        parser.error(str(error))
+    # Wildcard bindings are not navigable destinations; loopback reaches this server.
+    browser_host = DEFAULT_HOST if args.host == WILDCARD_HOST else args.host
+    url = f"http://{browser_host}:{server.server_address[1]}"
+    print(f"Holonomy explorer: {url} ({context.device}, {args.dtype})", flush=True)
+    if not args.no_browser:
+        webbrowser.open(url)
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        pass
+    finally:
+        server.server_close()
+
+
+if __name__ == "__main__":
+    main()

holonomy_explorer/batching.py

@@ -0,0 +1,182 @@
+"""Synchronized warm-up and repeated timings of the actual library paths."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+import torch
+
+from holonomy_lib.manifolds import KappaStereographicManifold
+from holonomy_lib.spectral import heat_kernel_chebyshev
+from holonomy_lib.spectral.laplacian import symmetric_normalized
+from holonomy_lib.topology import persistence_diagrams
+
+from .common import (
+    DEFAULT_REPEATS,
+    DEFAULT_SEED,
+    DEFAULT_SWEEP,
+    MAX_BATCH_SIZE,
+    MAX_NODES,
+    MAX_PERSISTENCE_BATCH,
+    MAX_PERSISTENCE_SIZE,
+    MAX_REPEATS,
+    Context,
+    Request,
+    choice,
+    integer,
+)
+from .datasets import MAX_SEED
+from .topology import reference_check
+
+# Keep the initial persistence sweep small enough for interactive CPU reduction.
+DEFAULT_PROBLEM_SIZE = 8
+BENCHMARK_GRAPH_DENSITY = 0.25  # Example Erdős-Rényi connection probability.
+BENCHMARK_POINT_SCALE = 0.2  # Uniform square sits inside the κ=-1 unit ball.
+
+
+def _operation(
+    primitive: str,
+    batch: int,
+    size: int,
+    context: Context,
+    seed: int,
+) -> Callable[[], Any]:
+    generator = context.generator(seed)
+    options: dict[str, Any] = {"device": context.device, "dtype": context.dtype}
+    if primitive == "heat":
+        upper = (
+            (
+                torch.rand((batch, size, size), generator=generator, **options)
+                < BENCHMARK_GRAPH_DENSITY
+            )
+            .to(context.dtype)
+            .triu(1)
+        )
+        adjacency = upper + upper.mT
+        # Matrix construction is outside the measured primitive call.
+        laplacian = symmetric_normalized(adjacency)
+        signal = torch.ones((batch, size, 1), **options)
+        return lambda: heat_kernel_chebyshev(laplacian, 1.0, signal=signal)
+    points = torch.rand((batch, size, 2), generator=generator, **options)
+    if primitive == "distance":
+        points = (points - 0.5) * (2 * BENCHMARK_POINT_SCALE)
+        manifold = KappaStereographicManifold(n=2, kappa=-1, **options)
+        return lambda: manifold.distance(points[:, :, None, :], points[:, None, :, :])
+    return lambda: persistence_diagrams(points, max_dim=1)
+
+
+def _probe(output: Any) -> Request:
+    if isinstance(output, torch.Tensor):
+        return {
+            "shape": list(output.shape),
+            "all_finite": bool(torch.isfinite(output).all()),
+        }
+    diagrams, masks = output
+    return {
+        "diagram_shapes": [list(item.shape) for item in diagrams],
+        "valid_bars": [int(mask.sum()) for mask in masks],
+    }
+
+
+@torch.no_grad()
+def compute(request: Request) -> Request:
+    """Sweep batch sizes, warming each shape before synchronized measurements.
+
+    Repeats and device/shape sweeps are deliberately sequential to avoid timing
+    competing work. The tensor operation itself receives the whole batch.
+
+    References:
+        Hammond, Vandergheynst and Gribonval (2011), Wavelets on graphs.
+        Bachmann et al. (2020), Constant Curvature Graph Convolutional Networks.
+        Edelsbrunner, Letscher and Zomorodian (2002), Topological persistence.
+    """
+    selected = Context.from_request(request)
+    primitive = choice(
+        request, "primitive", "heat", ("heat", "distance", "persistence")
+    )
+    size_cap = MAX_PERSISTENCE_SIZE if primitive == "persistence" else MAX_NODES
+    batch_cap = MAX_PERSISTENCE_BATCH if primitive == "persistence" else MAX_BATCH_SIZE
+    size = integer(request, "size", DEFAULT_PROBLEM_SIZE, 1, size_cap)
+    repeats = integer(request, "repeats", DEFAULT_REPEATS, 1, MAX_REPEATS)
+    seed = integer(request, "seed", DEFAULT_SEED, 0, MAX_SEED)
+    batches = request.get(
+        "batches", [batch for batch in DEFAULT_SWEEP if batch <= batch_cap]
+    )
+    if (
+        not isinstance(batches, list)
+        or not batches
+        or len(batches) > len(DEFAULT_SWEEP)
+    ):
+        raise ValueError(f"batches must contain 1 to {len(DEFAULT_SWEEP)} batch sizes")
+    if any(type(batch) is not int or not 1 <= batch <= batch_cap for batch in batches):
+        raise ValueError(
+            f"each batch size must be an integer between 1 and {batch_cap}"
+        )
+    devices = [torch.device("cpu")]
+    if torch.cuda.is_available():
+        devices.append(
+            selected.device
+            if selected.device.type == "cuda"
+            else torch.device("cuda", 0)
+        )
+    rows: list[Request] = []
+    warnings: list[str] = []
+    references: list[Request] = []
+    for device in devices:
+        context = Context(device, selected.dtype)
+        if primitive == "persistence":
+            reference = reference_check(context)
+            references.append({"device": str(device), **reference})
+            if not reference["passed"]:
+                warnings.append(
+                    f"{device}: square H1 reference failed; "
+                    "timing the current provisional reduction."
+                )
+        for batch in sorted(set(batches)):
+            operation = _operation(primitive, batch, size, context, seed)
+            probe = _probe(context.call(operation))
+            times = []
+            for _ in range(repeats):
+                start = context.elapsed_ms
+                context.call(operation)
+                times.append(context.elapsed_ms - start)
+            timings = torch.tensor(times, dtype=torch.float64)
+            median = timings.quantile(0.5)
+            rows.append(
+                {
+                    "device": str(device),
+                    "batch": batch,
+                    "min_ms": timings.min(),
+                    "median_ms": median,
+                    "max_ms": timings.max(),
+                    "samples_ms": times,
+                    "per_item_ms": median / batch,
+                    "per_item_min_ms": timings.min() / batch,
+                    "per_item_max_ms": timings.max() / batch,
+                    "probe": probe,
+                }
+            )
+        selected.elapsed_ms += context.elapsed_ms
+        selected.calls.extend(context.calls)
+    return selected.finish(
+        rows=rows,
+        warnings=warnings,
+        reference_checks=references,
+        parameters={
+            "primitive": primitive,
+            "size": size,
+            "repeats": repeats,
+            "seed": seed,
+            "batches": sorted(set(batches)),
+            "warmups": 1,
+        },
+        timing_note=(
+            "Wall time, synchronized before and after each call; "
+            "input generation excluded."
+        ),
+        persistence_note=(
+            "Persistence reduction is sequential per batch member, with CPU "
+            "bookkeeping even for GPU inputs. It is expected to scale differently."
+        ),
+    )

holonomy_explorer/common.py

@@ -0,0 +1,187 @@
+"""Request validation, compute timing, and the JSON boundary."""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from inspect import signature
+from time import perf_counter
+from typing import Any, TypeVar
+
+import torch
+
+# These are UI resource budgets, not numerical accuracy claims. They bound dense
+# graph work, cubic VR simplex counts, and repeated sweeps on a laptop CPU.
+MAX_NODES = 64
+MAX_POINTS = 40
+MAX_CURVATURE_POINTS = 12
+MAX_BATCH_SIZE = 256
+MAX_PERSISTENCE_BATCH = 16
+MAX_PERSISTENCE_SIZE = 16
+MAX_REPEATS = 7
+MAX_FLOW_STEPS = 24
+MAX_FLOW_FRAMES = 8
+MAX_REQUEST_BYTES = 256 * 1024
+REQUEST_TIMEOUT_SECONDS = 20
+
+# Presentation and sampling defaults are choices for a small first view.
+DEFAULT_SEED = 0
+DEFAULT_NODES = 24
+DEFAULT_POINTS = 24
+DEFAULT_NOISE = 0.05
+DEFAULT_REPEATS = 3
+DEFAULT_SWEEP = (1, 4, 16, 64, 256)
+CURVE_SAMPLES = 65
+GRID_RINGS = 5
+GRID_RAYS = 12
+# Stay away from the positive-curvature chart pole when sampling the grid.
+CHART_POLE_FRACTION = 0.8
+DEFAULT_GRID_EXTENT = 1.0
+SECONDS_TO_MS = 1000
+DTYPES = {"float32": torch.float32, "float64": torch.float64}
+Request = dict[str, Any]
+T = TypeVar("T")
+
+
+def integer(request: Request, key: str, default: int, low: int, high: int) -> int:
+    """Read an integer without silently truncating fractional input."""
+    value = request.get(key, default)
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise ValueError(f"{key} must be an integer")
+    if not low <= value <= high:
+        raise ValueError(f"{key} must be between {low} and {high}")
+    return value
+
+
+def number(
+    request: Request, key: str, default: float, low: float, high: float
+) -> float:
+    """Read a finite scalar within the control's documented domain."""
+    value = request.get(key, default)
+    if isinstance(value, bool) or not isinstance(value, (float, int)):
+        raise ValueError(f"{key} must be a number")
+    value = float(value)
+    if not math.isfinite(value) or not low <= value <= high:
+        raise ValueError(f"{key} must be finite and between {low} and {high}")
+    return value
+
+
+def choice(request: Request, key: str, default: str, options: tuple[str, ...]) -> str:
+    """Read a named option, rejecting unexpected routes through the adapter."""
+    value = request.get(key, default)
+    if value not in options:
+        raise ValueError(f"{key} must be one of {', '.join(options)}")
+    return str(value)
+
+
+def json_safe(value: Any) -> Any:
+    """Detach tensors once at the boundary; JSON has no NaN or infinity."""
+    if isinstance(value, torch.Tensor):
+        return json_safe(value.detach().cpu().tolist())
+    if isinstance(value, float):
+        return value if math.isfinite(value) else None
+    if isinstance(value, dict):
+        return {str(key): json_safe(item) for key, item in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [json_safe(item) for item in value]
+    return value
+
+
+@dataclass
+class Context:
+    """Keep chosen tensor placement and synchronized library-call time together."""
+
+    device: torch.device
+    dtype: torch.dtype
+    elapsed_ms: float = 0.0
+    calls: list[Request] = field(default_factory=list)
+
+    @classmethod
+    def from_request(cls, request: Request) -> Context:
+        dtype_name = choice(request, "dtype", "float64", tuple(DTYPES))
+        device = torch.device(str(request.get("device", "cpu")))
+        if device.type not in ("cpu", "cuda"):
+            raise ValueError("device must be cpu or cuda (CUDA also names ROCm)")
+        if device.type == "cpu":
+            device = torch.device("cpu")
+        if device.type == "cuda":
+            if not torch.cuda.is_available():
+                raise ValueError(
+                    "CUDA/ROCm is not available in this Python environment"
+                )
+            device = torch.device("cuda", device.index or 0)
+        # Allocate now so an invalid GPU index fails before any computation.
+        torch.empty(0, device=device, dtype=DTYPES[dtype_name])
+        return cls(device, DTYPES[dtype_name])
+
+    def sync(self) -> None:
+        if self.device.type == "cuda":
+            torch.cuda.synchronize(self.device)
+
+    def call(self, function: Callable[..., T], *args: Any, **kwargs: Any) -> T:
+        """Time only the requested library operation, including device completion."""
+        self.sync()
+        start = perf_counter()
+        try:
+            return function(*args, **kwargs)
+        finally:
+            self.sync()
+            duration = (perf_counter() - start) * SECONDS_TO_MS
+            self.elapsed_ms += duration
+            self.calls.append(
+                {
+                    "function": f"{function.__module__}.{function.__qualname__}",
+                    "elapsed_ms": duration,
+                    "device": str(self.device),
+                    "parameters": _scalar_arguments(function, args, kwargs),
+                }
+            )
+
+    def tensor(self, data: Any) -> torch.Tensor:
+        return torch.as_tensor(data, device=self.device, dtype=self.dtype)
+
+    def generator(self, seed: int) -> torch.Generator:
+        return torch.Generator(device=self.device).manual_seed(seed)
+
+    def finish(self, **values: Any) -> Request:
+        return dict(
+            json_safe(values),
+            device=str(self.device),
+            dtype=str(self.dtype).removeprefix("torch."),
+            elapsed_ms=self.elapsed_ms,
+            calls=json_safe(self.calls),
+        )
+
+
+def _scalar_arguments(
+    function: Callable[..., Any],
+    args: tuple[Any, ...],
+    kwargs: Request,
+) -> Request:
+    # Read defaults from the dependency instead of copying them into the UI.
+    # Some torch C builtins have no Python signature; their inputs are already
+    # described by the scene's parameters and data arrays.
+    try:
+        bound = signature(function).bind(*args, **kwargs)
+    except (ValueError, TypeError):
+        return {}
+    bound.apply_defaults()
+    return {
+        key: value
+        for key, value in bound.arguments.items()
+        if isinstance(value, (str, int, float, bool)) or value is None
+    }
+
+
+def points_tensor(request: Request, context: Context, cap: int) -> torch.Tensor:
+    """Read a finite (N, 2) point array; empty clicks are a valid cloud."""
+    raw = request.get("points", [])
+    if not isinstance(raw, list) or len(raw) > cap:
+        raise ValueError(f"points must be a list containing at most {cap} points")
+    if not raw:
+        return context.tensor([]).reshape(0, 2)
+    points = context.tensor(raw)
+    if points.shape != (len(raw), 2) or not bool(torch.isfinite(points).all()):
+        raise ValueError("points must contain finite [x, y] pairs")
+    return points

holonomy_explorer/curvature.py

@@ -0,0 +1,154 @@
+"""Stereographic distances, geodesics, and a checked mean estimate."""
+
+from __future__ import annotations
+
+import math
+
+import torch
+
+from holonomy_lib.hyperbolic import frechet_mean
+from holonomy_lib.manifolds import KappaStereographicManifold
+
+from .common import (
+    CHART_POLE_FRACTION,
+    CURVE_SAMPLES,
+    DEFAULT_GRID_EXTENT,
+    GRID_RAYS,
+    GRID_RINGS,
+    MAX_CURVATURE_POINTS,
+    Context,
+    Request,
+    number,
+    points_tensor,
+)
+
+# Residual tolerance is a display diagnostic, scaled to the dtype's resolution.
+MEAN_RESIDUAL_EPS_POWER = 0.5
+# An initial asymmetric triangle inside every displayed chart at |κ| <= 2.
+DEFAULT_CURVATURE_POINTS = ((-0.35, -0.15), (0.35, -0.15), (0.0, 0.4))
+
+
+@torch.no_grad()
+def compute(request: Request) -> Request:
+    """Evaluate one chart with a leading singleton scene batch.
+
+    Points outside the chart remain in the response but are excluded from all
+    geometry. The library mean uses sequential Karcher iterations; its residual
+    is reported because an iteration cap alone does not establish convergence.
+
+    References:
+        Bachmann et al. (2020), Constant Curvature Graph Convolutional Networks.
+        Karcher (1977), Riemannian center of mass and mollifier smoothing.
+    """
+    context = Context.from_request(request)
+    kappa = number(request, "kappa", -1, -2, 2)
+    points = points_tensor(request, context, MAX_CURVATURE_POINTS)
+    manifold = KappaStereographicManifold(
+        n=2,
+        kappa=kappa,
+        device=context.device,
+        dtype=context.dtype,
+    )
+    # The negative-curvature ball is open. Use the documented hemispherical
+    # chart for positive κ as well, without relying on a membership sign bug.
+    valid = (
+        points.square().sum(-1) * abs(kappa) < 1
+        if kappa != 0
+        else torch.ones(len(points), device=context.device, dtype=torch.bool)
+    )
+    indices = valid.nonzero().flatten()
+    included = points[valid]
+    distance = context.call(
+        manifold.distance,
+        included[None, :, None, :],
+        included[None, None, :, :],
+    )[0]
+    raw_pairs = request.get("pairs")
+    if raw_pairs is None:
+        pairs = torch.combinations(indices, r=2)
+    else:
+        if not isinstance(raw_pairs, list) or len(raw_pairs) > MAX_CURVATURE_POINTS**2:
+            raise ValueError("pairs must be a list of point-index pairs")
+        if raw_pairs:
+            if any(
+                not isinstance(pair, list)
+                or len(pair) != 2
+                or any(type(index) is not int for index in pair)
+                for pair in raw_pairs
+            ):
+                raise ValueError("each pair must contain two integer indices")
+            pairs = torch.tensor(raw_pairs, device=context.device, dtype=torch.long)
+            if bool(((pairs < 0) | (pairs >= len(points))).any()):
+                raise ValueError("pair index is outside the point list")
+            pairs = pairs[valid[pairs].all(-1)]
+        else:
+            pairs = torch.empty((0, 2), device=context.device, dtype=torch.long)
+    steps = torch.linspace(
+        0, 1, CURVE_SAMPLES, device=context.device, dtype=context.dtype
+    )
+    start, end = points[pairs[:, 0]], points[pairs[:, 1]]
+    tangent = context.call(manifold.log, start, end)
+    curves = context.call(
+        manifold.exp, start[:, None, :], tangent[:, None, :] * steps[None, :, None]
+    )
+    extent = DEFAULT_GRID_EXTENT
+    if kappa > 0:
+        # exp_0 reaches the hemisphere boundary at tangent radius π/(4√κ).
+        extent = min(extent, CHART_POLE_FRACTION * math.pi / (4 * math.sqrt(kappa)))
+    angles = torch.linspace(
+        0, math.tau, CURVE_SAMPLES, device=context.device, dtype=context.dtype
+    )
+    radii = torch.arange(1, GRID_RINGS + 1, device=context.device, dtype=context.dtype)
+    radii *= extent / GRID_RINGS
+    rings = radii[:, None, None] * torch.stack((angles.cos(), angles.sin()), -1)[None]
+    ray_angles = (
+        torch.arange(GRID_RAYS, device=context.device, dtype=context.dtype)
+        * math.tau
+        / GRID_RAYS
+    )
+    rays = (
+        extent
+        * steps[None, :, None]
+        * torch.stack((ray_angles.cos(), ray_angles.sin()), -1)[:, None]
+    )
+    grid = context.call(manifold.exp_0, torch.cat((rings, rays)))
+    mean: Request | None = None
+    warnings: list[str] = []
+    if kappa <= 0 and len(included):
+        try:
+            estimate = context.call(frechet_mean, included[None], manifold)
+            average_log = context.call(
+                manifold.log, estimate[:, None, :], included[None]
+            ).mean(1)
+            residual = context.call(manifold.norm, estimate, average_log)[0]
+            converged = bool(
+                residual <= torch.finfo(context.dtype).eps ** MEAN_RESIDUAL_EPS_POWER
+            )
+            mean = {"point": estimate[0], "residual": residual, "converged": converged}
+            if not converged:
+                warnings.append(
+                    "Fréchet iteration has not converged; "
+                    "the marked point is only an estimate."
+                )
+        except (ValueError, RuntimeError) as error:
+            warnings.append(f"Fréchet mean unavailable: {error}")
+    return context.finish(
+        points=points,
+        valid=valid,
+        included_indices=indices,
+        distances=distance,
+        pairs=pairs,
+        curves=curves,
+        grid=grid,
+        mean=mean,
+        warnings=warnings,
+        boundary_radius=1 / math.sqrt(abs(kappa)) if kappa else None,
+        parameters={"kappa": kappa, "curve_samples": CURVE_SAMPLES},
+        chart_note=(
+            "Open hyperbolic ball"
+            if kappa < 0
+            else "Conservative hemispherical chart"
+            if kappa > 0
+            else "Flat chart: distance is 2 × Euclidean coordinate distance"
+        ),
+    )