Module stack 

Opt-in, shared autotuning above individual kernels.

Tensor operators and fused graphs use the same controller as explicit application plans. Existing LocalTuner behavior is unchanged until enable_stack_autotune is called; only sets declaring an exact workload signature and reference participate in the new path.

Structs

Candidate

Stable candidate identity and its declared eligibility/scratch requirement.

CandidateReport

One candidate’s local timing/validation metadata.

Decision

Implementation selection, not a computed output or an instruction to replay a request.

Problem

Exact operation/environment signature; shapes are not bucketed or guessed.

RuntimeEnvironment

Supply extra tags for a deployment’s compiler flags and load/topology/power regime. Set these BEFORE constructing devices/starting inference; changing them live is unsupported.

StackPolicy

Immutable limits shared by operator, graph and application selection. Defaults are selection rules, not measured performance guarantees.

StackTuner

No state mutex is held while running a candidate, validator, profile, or disk operation. Contenders use the declared reference instead of waiting (also avoids nested-tuning deadlocks).

Stats

Controller-local counters; these are not GPU utilization or performance estimates.

Tolerance

Absolute/relative comparison limits and bounded host readback size.

TuneFailure

Structured selection failure; Display combines the kind and explanatory message.

TuneReport

Bounded in-memory diagnostics for one selection workload.

Enums

DecisionSource

Why a reference or selected implementation was returned.

FailureKind

Failure classification used to distinguish rejected trials from device faults.

Mode

Selection policy for adapters participating in the shared controller.

Scope

Workload level included in cache identity and dependency tracking.

Timing

Completed-work timing requested from the trial adapter.

Validation

Whether the adapter can establish numerical agreement for this trial.

Traits

TrialRunner

Benchmarks MUST use isolated state. A completed measurement includes all device work whose cost belongs to the plan. A submit-only host timestamp is not a valid measurement.

Functions

cache_key

Encode the full workload, ordered candidate manifest, reference and numerical policy. This returns identity text, not a cryptographic hash or proof of correctness.

enable_stack_autotune

Install once, before worker threads/model loading. No implicit environment mutation or I/O.

fields

Canonical, length-delimited encoding prevents concatenation aliases such as (ab,c)/(a,bc).

is_tuning

Whether the current thread is inside a shared-controller trial. This is nesting state, not a query of GPU activity or other processes.

median

Sort positive finite ratios in place and return their median. Empty, zero, negative or nonfinite input returns None.

paired_score

Return (median_selected_over_reference, relative_mad) for completed pairs. Requires at least policy.samples nonzero pairs and acceptable relative MAD; an unavailable/noisy score returns None, not a statistically proven speedup.

runtime_environment

Probe and memoize immutable environment identity for this runtime/client. Deployment tags must be set before first use; live mutation is not supported. Missing identity yields session-only caching rather than a fabricated driver version.

stack_autotuner

Return the installed controller, or None to preserve the legacy tuner route. Merely querying it does not create a controller, inspect files or run trials.

try_execute_stack

Fallible full-stack path. Actual request execution is performed ONCE after selection; an execution error invalidates future choices but is never silently replayed on another kernel. Requires an installed controller, an in-range explicit reference and an exact workload signature on the set. Missing metadata returns AutotuneError before live execution.

workload_digest

This is NOT a cryptographic authenticity check. Caches must be in a trusted user directory.