vibespatial.runtime.crossover¶

Attributes¶

`DEFAULT_CROSSOVER_POLICIES`
`DEFAULT_BROADCAST_CROSSOVER_POLICIES`

Classes¶

`WorkloadShape`	Classification of how left and right geometry arrays relate in size.
`PhysicalWorkEstimate`	Shape-level work estimate for GPU dispatch.
`DispatchDecision`	Enum where members are also (and must be) strings
`CrossoverPolicy`	Per-kernel crossover thresholds for AUTO dispatch.

Functions¶

`detect_workload_shape`(→ WorkloadShape)	Classify the workload shape for a binary operation.
`estimate_physical_work_from_owned`(→ PhysicalWorkEstimate)	Build a physical work estimate from an owned geometry carrier.
`estimate_spatial_index_work_from_owned`(...)	Estimate spatial-index build work from owned columnar geometry shape.
`estimate_grouped_work_from_owned`(→ PhysicalWorkEstimate)	Estimate segmented grouped geometry work from native carriers.
`estimate_pairwise_work_from_owned`(→ PhysicalWorkEstimate)	Estimate aligned binary work from left/right owned columnar shape.
`estimate_relation_pair_work_from_owned`(...)	Estimate many-to-many relation work before candidate rows are gathered.
`estimate_segment_pair_work_from_owned`(...)	Estimate within-geometry quadratic segment comparison work.
`estimate_pairwise_product_work_from_owned`(...)	Estimate aligned binary vertex- or segment-product work.
`estimate_part_pair_work_from_owned`(→ PhysicalWorkEstimate)	Estimate within-geometry component endpoint graph work.
`effective_crossover_threshold`(→ int)
`default_crossover_policy`(→ CrossoverPolicy)
`select_dispatch_for_rows`(→ DispatchDecision)	Select CPU or GPU execution based on row count and crossover policy.
`select_dispatch_for_estimate`(→ DispatchDecision)	Select CPU or GPU execution from an ADR-0046 physical work estimate.

Module Contents¶

class vibespatial.runtime.crossover.WorkloadShape¶

Classification of how left and right geometry arrays relate in size.

PAIRWISE: left and right have the same length; element-wise ops. BROADCAST_RIGHT: right has length 1, left has length > 1; the single

right geometry is broadcast against every left row.

SCALAR_RIGHT: right is a scalar (not an array); skips pandas index: alignment entirely.

BROADCAST_LEFT is intentionally omitted — no consumer exists today. INDEXED is intentionally omitted — gather-evaluate-scatter is a different computation model, not a workload shape.

PAIRWISE = 'pairwise'¶

BROADCAST_RIGHT = 'broadcast_right'¶

SCALAR_RIGHT = 'scalar_right'¶

vibespatial.runtime.crossover.detect_workload_shape(left_count: int, right_count: int | None) → WorkloadShape¶: Classify the workload shape for a binary operation.

class vibespatial.runtime.crossover.PhysicalWorkEstimate¶

Shape-level work estimate for GPU dispatch.

ADR-0046 makes row count a bootstrap signal, not the physical execution contract. This carrier lets callers expose the actual work units that dominate the selected shape while preserving row-only compatibility for older dispatch paths.

row_count: int¶

coordinate_count: int = 0¶

coordinate_pair_count: int = 0¶

segment_count: int = 0¶

segment_pair_count: int = 0¶

part_count: int = 0¶

part_pair_count: int = 0¶

ring_count: int = 0¶

candidate_pair_count: int = 0¶

relation_pair_count: int = 0¶

group_count: int = 0¶

output_row_count: int = 0¶

output_byte_count: int = 0¶

temporary_byte_count: int = 0¶

primary_unit_count: int | None = None¶

primary_unit_name: str = 'row'¶

classmethod from_rows(row_count: int) → PhysicalWorkEstimate¶

classmethod for_candidate_pairs(*, row_count: int, candidate_pair_count: int, output_row_count: int = 0, output_byte_count: int = 0, temporary_byte_count: int = 0, primary_unit_name: str = 'candidate-pair') → PhysicalWorkEstimate¶

classmethod for_relation_pairs(*, row_count: int, relation_pair_count: int, output_row_count: int = 0, output_byte_count: int = 0, temporary_byte_count: int = 0, primary_unit_name: str = 'relation-pair') → PhysicalWorkEstimate¶

property is_row_only: bool¶

dispatch_unit_count() → int¶

dispatch_unit_name() → str¶

live_device_byte_count() → int¶: Return the estimated simultaneously live output and scratch bytes.

is_device_memory_admissible(available_device_bytes: int, *, budget_numerator: int = 1, budget_denominator: int = 2) → bool¶

Return whether this shape fits its reserved share of free device memory.

A physical plan cannot consume all currently free memory: downstream output carriers, allocator fragmentation, and concurrently resident native inputs remain live. Callers may tune the reserved share for a shape, while the default admits at most half of currently available memory.

telemetry_detail() → str¶

vibespatial.runtime.crossover.estimate_physical_work_from_owned(owned: object, *, candidate_pair_count: int = 0, relation_pair_count: int = 0, group_count: int = 0, output_row_count: int = 0, output_byte_count: int = 0, temporary_byte_count: int = 0, primary_unit_count: int | None = None, primary_unit_name: str = 'work-unit') → PhysicalWorkEstimate¶

Build a physical work estimate from an owned geometry carrier.

The helper intentionally inspects only stable columnar shape metadata: row count and coordinate-buffer lengths. Indexed views scale the compact base-buffer shape to their logical row count so dispatch estimates describe work executed after row indirection rather than merely the referenced storage. It does not materialize geometry objects or host rows, so it is safe to call from dispatch planning.

vibespatial.runtime.crossover.estimate_spatial_index_work_from_owned(owned: object, *, output_row_count: int = 0, output_byte_count: int = 0, temporary_byte_count: int = 0, primary_unit_name: str = 'spatial-index-unit') → PhysicalWorkEstimate¶: Estimate spatial-index build work from owned columnar geometry shape.

vibespatial.runtime.crossover.estimate_grouped_work_from_owned(owned: object, *, grouped: object | None = None, group_count: int | None = None, output_row_count: int | None = None, output_byte_count: int = 0, temporary_byte_count: int = 0, primary_unit_name: str = 'grouped-segment') → PhysicalWorkEstimate¶

Estimate segmented grouped geometry work from native carriers.

The estimate uses only owned columnar metadata and grouped carrier shape fields. It does not inspect group labels or geometry objects on host, so callers can use it for dispatch telemetry before admissibility checks.

vibespatial.runtime.crossover.estimate_pairwise_work_from_owned(left: object, right: object, *, workload: WorkloadShape | None = None, output_row_count: int | None = None, primary_unit_name: str = 'pair-coordinate') → PhysicalWorkEstimate¶: Estimate aligned binary work from left/right owned columnar shape.

vibespatial.runtime.crossover.estimate_relation_pair_work_from_owned(left: object, right: object, *, pair_count: int, output_byte_count: int | None = None, temporary_byte_count: int | None = None, temporary_bytes_per_segment: int = 0, primary_unit_name: str = 'relation-segment') → PhysicalWorkEstimate¶: Estimate many-to-many relation work before candidate rows are gathered.

vibespatial.runtime.crossover.estimate_segment_pair_work_from_owned(owned: object, *, selected_row_count: int | None = None, output_row_count: int = 0, output_byte_count: int = 0, temporary_byte_count: int = 0, primary_unit_name: str = 'segment-pair') → PhysicalWorkEstimate¶

Estimate within-geometry quadratic segment comparison work.

The exact sum of per-geometry segment pairs lives behind device offsets for arbitrary-width geometry. Dispatch planning must not synchronize to recover it, so this helper computes the balanced-distribution estimate from authoritative buffer lengths and family row counts. Fixed-width carriers make that estimate exact; variable-width carriers retain the correct quadratic physical shape without a host metadata crossover.

vibespatial.runtime.crossover.estimate_pairwise_product_work_from_owned(left: object, right: object, *, pair_unit: str, output_row_count: int | None = None, output_byte_count: int = 0, temporary_byte_count: int = 0, primary_unit_name: str | None = None) → PhysicalWorkEstimate¶

Estimate aligned binary vertex- or segment-product work.

Exact per-row products require reducing device offsets. The balanced product preserves the quadratic shape from authoritative aggregate lengths without introducing a planning synchronization. A one-row right carrier naturally models broadcast reuse; an already tiled right carrier is divided across the aligned row count.

vibespatial.runtime.crossover.estimate_part_pair_work_from_owned(owned: object, *, output_row_count: int = 0, output_byte_count: int = 0, temporary_byte_count: int = 0, primary_unit_name: str = 'part-pair') → PhysicalWorkEstimate¶: Estimate within-geometry component endpoint graph work.

class vibespatial.runtime.crossover.DispatchDecision¶

Enum where members are also (and must be) strings

CPU = 'cpu'¶

GPU = 'gpu'¶

class vibespatial.runtime.crossover.CrossoverPolicy¶

Per-kernel crossover thresholds for AUTO dispatch.

auto_min_rows is the pairwise threshold (left and right have the same length). broadcast_min_rows is an optional lower threshold for broadcast workload shapes (BROADCAST_RIGHT / SCALAR_RIGHT) where the right-side geometry fits in L1 cache and is reused N times, making GPU profitable at much smaller N.

kernel_name: str¶

kernel_class: vibespatial.runtime.precision.KernelClass¶

auto_min_rows: int¶

reason: str¶

broadcast_min_rows: int | None = None¶

vibespatial.runtime.crossover.DEFAULT_CROSSOVER_POLICIES: dict[vibespatial.runtime.precision.KernelClass, int]¶

vibespatial.runtime.crossover.DEFAULT_BROADCAST_CROSSOVER_POLICIES: dict[vibespatial.runtime.precision.KernelClass, int]¶

vibespatial.runtime.crossover.effective_crossover_threshold(policy: CrossoverPolicy, workload_shape: WorkloadShape | None = None) → int¶

vibespatial.runtime.crossover.default_crossover_policy(kernel_name: str, kernel_class: vibespatial.runtime.precision.KernelClass | str) → CrossoverPolicy¶

vibespatial.runtime.crossover.select_dispatch_for_rows(*, requested_mode: vibespatial.runtime._runtime.ExecutionMode | str, row_count: int, policy: CrossoverPolicy, gpu_available: bool, workload_shape: WorkloadShape | None = None) → DispatchDecision¶

Select CPU or GPU execution based on row count and crossover policy.

When workload_shape is BROADCAST_RIGHT or SCALAR_RIGHT, the effective threshold is policy.broadcast_min_rows (or policy.auto_min_rows // 10 if the policy does not set a broadcast threshold). This reflects the fact that broadcast workloads have perfect right-side data locality and benefit from GPU execution at much smaller N than pairwise workloads.

vibespatial.runtime.crossover.select_dispatch_for_estimate(*, requested_mode: vibespatial.runtime._runtime.ExecutionMode | str, work_estimate: PhysicalWorkEstimate, policy: CrossoverPolicy, gpu_available: bool, workload_shape: WorkloadShape | None = None) → DispatchDecision¶: Select CPU or GPU execution from an ADR-0046 physical work estimate.