vibespatial.runtime.adaptive¶

Classes¶

`MonitoringBackend`	Enum where members are also (and must be) strings
`MonitoringSample`
`MonitoringProbe`	Base class for protocol classes.
`DeviceSnapshot`
`WorkloadProfile`
`AdaptivePlan`
`AdaptiveRuntime`
`ChunkedPlanIterator`	Yield AdaptivePlans for successive chunks of a streaming workload.

Functions¶

`capture_device_snapshot`(→ DeviceSnapshot)
`select_kernel_variant`(...)
`plan_adaptive_execution`(→ AdaptivePlan)
`get_cached_snapshot`(→ DeviceSnapshot)	Return a session-scoped DeviceSnapshot, creating it on first call.
`invalidate_snapshot_cache`(→ None)	Clear the cached snapshot so the next call to get_cached_snapshot() re-probes.
`plan_kernel_dispatch`(, mixed_geometry, ...)	Plan kernel dispatch with a cached device snapshot.
`plan_dispatch_selection`(...)	Thin wrapper: plan dispatch and return just the RuntimeSelection.
`estimate_avg_vertices`(→ float)	Estimate average vertices per geometry from an OwnedGeometryArray.

Module Contents¶

class vibespatial.runtime.adaptive.MonitoringBackend¶

Enum where members are also (and must be) strings

UNAVAILABLE = 'unavailable'¶

NVML = 'nvml'¶

class vibespatial.runtime.adaptive.MonitoringSample¶

sm_utilization_pct: float¶

memory_utilization_pct: float¶

device_name: str = 'unknown'¶

class vibespatial.runtime.adaptive.MonitoringProbe¶

Base class for protocol classes.

Protocol classes are defined as:

class Proto(Protocol):
    def meth(self) -> int:
        ...

Such classes are primarily used with static type checkers that recognize structural subtyping (static duck-typing).

For example:

class C:
    def meth(self) -> int:
        return 0

def func(x: Proto) -> int:
    return x.meth()

func(C())  # Passes static type check

See PEP 544 for details. Protocol classes decorated with @typing.runtime_checkable act as simple-minded runtime protocols that check only the presence of given attributes, ignoring their type signatures. Protocol classes can be generic, they are defined as:

class GenProto[T](Protocol):
    def meth(self) -> T:
        ...

class vibespatial.runtime.adaptive.DeviceSnapshot¶

backend: MonitoringBackend¶

gpu_available: bool¶

device_profile: vibespatial.runtime.precision.DevicePrecisionProfile¶

sm_utilization_pct: float | None = None¶

memory_utilization_pct: float | None = None¶

device_name: str = 'unknown'¶

reason: str = ''¶

property underutilized: bool¶

property under_memory_pressure: bool¶

class vibespatial.runtime.adaptive.WorkloadProfile¶

row_count: int¶

geometry_families: tuple[str, Ellipsis] = ()¶

mixed_geometry: bool = False¶

current_residency: vibespatial.runtime.residency.Residency¶

coordinate_stats: vibespatial.runtime.precision.CoordinateStats | None = None¶

is_streaming: bool = False¶

chunk_index: int = 0¶

avg_vertices_per_geometry: float = 0.0¶

class vibespatial.runtime.adaptive.AdaptivePlan¶

runtime_selection: vibespatial.runtime._runtime.RuntimeSelection¶

dispatch_decision: vibespatial.runtime.crossover.DispatchDecision¶

crossover_policy: vibespatial.runtime.crossover.CrossoverPolicy¶

precision_plan: vibespatial.runtime.precision.PrecisionPlan¶

variant: vibespatial.runtime.kernel_registry.KernelVariantSpec | None¶

chunk_rows: int¶

replan_after_chunk: bool¶

diagnostics: tuple[str, Ellipsis]¶

class vibespatial.runtime.adaptive.AdaptiveRuntime¶

device_snapshot: DeviceSnapshot | None = None¶

plan(*, kernel_name: str, kernel_class: vibespatial.runtime.precision.KernelClass | str, workload: WorkloadProfile, requested_mode: vibespatial.runtime._runtime.ExecutionMode | str = ExecutionMode.AUTO, requested_precision: vibespatial.runtime.precision.PrecisionMode | str = PrecisionMode.AUTO, variants: tuple[vibespatial.runtime.kernel_registry.KernelVariantSpec, Ellipsis] | None = None) → AdaptivePlan¶

vibespatial.runtime.adaptive.capture_device_snapshot(*, probe: MonitoringProbe | None = None, gpu_available: bool | None = None, device_profile: vibespatial.runtime.precision.DevicePrecisionProfile | None = None) → DeviceSnapshot¶

vibespatial.runtime.adaptive.select_kernel_variant(*, kernel_name: str, runtime_selection: vibespatial.runtime._runtime.RuntimeSelection, precision_plan: vibespatial.runtime.precision.PrecisionPlan, workload: WorkloadProfile, variants: tuple[vibespatial.runtime.kernel_registry.KernelVariantSpec, Ellipsis] | None = None) → vibespatial.runtime.kernel_registry.KernelVariantSpec | None¶

vibespatial.runtime.adaptive.plan_adaptive_execution(*, kernel_name: str, kernel_class: vibespatial.runtime.precision.KernelClass | str, workload: WorkloadProfile, requested_mode: vibespatial.runtime._runtime.ExecutionMode | str = ExecutionMode.AUTO, requested_precision: vibespatial.runtime.precision.PrecisionMode | str = PrecisionMode.AUTO, device_snapshot: DeviceSnapshot | None = None, variants: tuple[vibespatial.runtime.kernel_registry.KernelVariantSpec, Ellipsis] | None = None) → AdaptivePlan¶

vibespatial.runtime.adaptive.get_cached_snapshot() → DeviceSnapshot¶: Return a session-scoped DeviceSnapshot, creating it on first call.

vibespatial.runtime.adaptive.invalidate_snapshot_cache() → None¶: Clear the cached snapshot so the next call to get_cached_snapshot() re-probes.

vibespatial.runtime.adaptive.plan_kernel_dispatch(*, kernel_name: str, kernel_class: vibespatial.runtime.precision.KernelClass | str, row_count: int, requested_mode: vibespatial.runtime._runtime.ExecutionMode | str = ExecutionMode.AUTO, requested_precision: vibespatial.runtime.precision.PrecisionMode | str = PrecisionMode.AUTO, geometry_families: tuple[str, Ellipsis] = (), mixed_geometry: bool = False, current_residency: vibespatial.runtime.residency.Residency = Residency.HOST, coordinate_stats: vibespatial.runtime.precision.CoordinateStats | None = None, is_streaming: bool = False, chunk_index: int = 0, gpu_available: bool | None = None) → AdaptivePlan¶

Plan kernel dispatch with a cached device snapshot.

This is the recommended entry point for all GPU dispatch decisions. It gets (or creates) a session-scoped DeviceSnapshot, builds a WorkloadProfile, and calls plan_adaptive_execution().

vibespatial.runtime.adaptive.plan_dispatch_selection(*, kernel_name: str, kernel_class: vibespatial.runtime.precision.KernelClass | str, row_count: int, requested_mode: vibespatial.runtime._runtime.ExecutionMode | str = ExecutionMode.AUTO, gpu_available: bool | None = None) → vibespatial.runtime._runtime.RuntimeSelection¶: Thin wrapper: plan dispatch and return just the RuntimeSelection.

class vibespatial.runtime.adaptive.ChunkedPlanIterator(*, kernel_name: str, kernel_class: vibespatial.runtime.precision.KernelClass | str, total_rows: int, requested_mode: vibespatial.runtime._runtime.ExecutionMode | str = ExecutionMode.AUTO, requested_precision: vibespatial.runtime.precision.PrecisionMode | str = PrecisionMode.AUTO)¶

Yield AdaptivePlans for successive chunks of a streaming workload.

This is a design-only interface for future streaming integration where io_arrow.py chunk sizing should be informed by AdaptivePlan.chunk_rows. No production code calls this yet.

kernel_name¶

kernel_class¶

total_rows¶

requested_mode¶

requested_precision¶

vibespatial.runtime.adaptive.estimate_avg_vertices(owned: object) → float¶

Estimate average vertices per geometry from an OwnedGeometryArray.

Used by kernel dispatch to select between simple (1-thread-per-geometry) and cooperative (1-block-per-geometry) kernel variants. Returns 0.0 if the geometry array has no families or no coordinates.

Accepts object to avoid importing OwnedGeometryArray at module scope (which would create a circular import).