knobs

The knob registry: each optimization knob declared once.

KNOBSconstantProvisional: importable, but outside the compatibility promise; a minor release can change or remove it.
KnobSpecclassOne optimization knob.
knob_namesfunctionThe names of all knobs.
knobfunctionLook up a knob by name.
default_knob_valuesfunctionEach knob's default value, the choice an operator makes without a handler.

KNOBS: tuple[KnobSpec, ...] = (ACCUMULATION, KERNEL)

Provisional: importable, but outside the compatibility promise; a minor release can change or remove it.

KnobSpec(
    name: str,
    values: tuple[str, ...],
    default: str,
    approximate_values: frozenset[str],
    auto: Mapping[OptimizationGoal, str],
    applies_to: frozenset[str],
    summary: str,
    operator_auto: Mapping[str, Mapping[OptimizationGoal, str]] = dict(),
) -> None

dataclass

One optimization knob.

Provisional: importable, but outside the compatibility promise; a minor release can change or remove it.

name: str

The knob’s configuration key under optimization and operators[].optimization.

values: tuple[str, ...]

Its values, excluding auto.

default: str

The value that keeps the kernel library’s default numerics; auto falls back to it when the approximation gate is closed.

approximate_values: frozenset[str]

Values that change numerics relative to default.

auto: Mapping[OptimizationGoal, str]

The value auto picks for each goal, subject to the approximation gate.

applies_to: frozenset[str]

Operator type keys the knob can apply to.

summary: str

What the knob changes.

operator_auto: Mapping[str, Mapping[OptimizationGoal, str]] = field(default_factory=dict)

Operator-specific goal choices, overriding the general auto table.

resolve(requested: str, goal: OptimizationGoal, allow_approximate: bool, *, op_type: str | None = None) -> str

Resolve a requested value; auto follows the static table.

An explicit value is used as given. auto takes the goal’s value, unless that value is approximate and the gate is closed, in which case it takes default.

Parameters

Parameters of resolve
Name	Type	Default	Description
`requested`	`str`	Required	The requested value, possibly ``auto``.
`goal`	`OptimizationGoal`	Required	``optimization.goal``.
`allow_approximate`	`bool`	Required	``optimization.allow_approximate``.
`op_type`	`str \| None`	None	Canonical operator type for its auto-policy override, if any.

Returns

Returns of resolve
Value	Type	Description
`str`	`str`	A value from ``values``.

Raises

Errors raised by resolve
Type	Description
`ValueError`	If ``requested`` is neither ``auto`` nor one of ``values``.

is_approximate(value: str) -> bool

Whether value changes numerics relative to default.

knob_names() -> frozenset[str]

The names of all knobs.

Provisional: importable, but outside the compatibility promise; a minor release can change or remove it.

knob(name: str) -> KnobSpec

Look up a knob by name.

Provisional: importable, but outside the compatibility promise; a minor release can change or remove it.

Parameters

Parameters of knob
Name	Type	Default	Description
`name`	`str`	Required	The knob's name.

Returns

Returns of knob
Value	Type	Description
`KnobSpec`	`KnobSpec`	The knob.

Raises

Errors raised by knob
Type	Description
`KeyError`	When no knob has that name.

default_knob_values() -> dict[str, str]

Each knob’s default value, the choice an operator makes without a handler.

Provisional: importable, but outside the compatibility promise; a minor release can change or remove it.