hawk.ext

The extension protocol: the seams a kind DECLARES.

Each seam is a declaration consumed by the walk and the emitter, never a post-hoc edit of generated text. This module lands two seams:

• Sink policy — how an accumulate sink commits. Built: plain, atomic and compensated (Neumaier, correction committed to a companion plane the declaration names). A scattered accumulate commits through the target’s atomic add under plain/atomic alike (hawk_abi::accum_add) — a scattered read-modify-write has no correct use under any parallel launch; atomic just names that commit explicitly. An own-column write is a store under plain/atomic, but an accumulate into the plane’s prior value under compensated (see compensated() for the host-side zeroing contract). banded is a named, unbuilt slot that refuses with its own message.

• Guard policy — which mask gates the sample, and whether one is present at all. A set mask skips the sample’s whole body. The default gates on a bound terminated slot; Guard(mask=None) is the data-only seam, for a kind that must run every sample. Guard(active_set=True) additionally reads an active-set index map (eagle’s ActiveSet): the index prologue maps launch position t to sample active_map[t] and stops at active_count, so live samples share warps; the body is unchanged.

The custom-primitive seam (hawk.ext.primitive) adds a forward the author writes as an ordinary Python function of traced values, inlined at every call, plus the VJP/JVP rules that replace the table’s rule for that subgraph.

A Kind carries all of these plus its compile hook. A vocabulary is extended by INHERITANCE: a KernelKind subclass, or Kind.extend() for the instance form, carries a base’s vocabulary and seam fields forward, merging rather than shadowing — see KernelKind for the rules.

Module Attributes

PLAIN	The default.
ATOMIC	The scattered commit plain already makes, named out loud.
DEFAULT_GUARD	gate on a bound terminated slot.
DEFAULT_KIND	plain commits, the default mask guard, no compile hook, no vocabulary.

Functions

sink_policy(…)	Resolve an value by name.
compensated(…)	A Neumaier-compensated accumulate whose correction lands in into.
primitive(…)	Register a custom primitive named name.
primitives()	A copy of the primitive registry, by name (introspection only).

Classes

Guard	Which masks gate the sample.
Kind	A kind's class-level vocabulary, its output set, its declared seams and its compile hook.
Output	Which sink parameter(s) a kind's kernel treats as its output set — the set a compensated sink's target is resolved from (compensated_target()).
PrimitiveDef	One registered primitive: its forward and the rules that replace the table.
KernelKind	The class-form spelling of Kind: sugar, not a second kind.