Module Autotune.Family_decision

What a commitment on the matmul family tree is

(gh-ocannl-591)

The family tree's levels commit to values of t, not to display strings. A consumer that reads a decision back off a path — the certain-traffic floor sketch_path_traffic_floor, the lattice lift lift_geometry_lattice, a ranking or profitability pass over the search's paths, the tests — matches on the datum. to_label is the rendering, used by logs, decline reports and goldens; nothing parses it back, so rewording a label (or renaming a level, which level derives from the datum) changes what is printed and nothing else.

This replaced a Printf.sprintf / Scanf.sscanf protocol whose failure mode was silent: a reworded geometry label made every scan arm fall through, so the traffic floor's increment was 0 on every path — a sound bound, so nothing raised, no golden moved, and the family bound quietly stopped differentiating the tree.

type geometry = {
  1. g_bm : Base.int;
  2. g_bn : Base.int;
  3. g_bk : Base.int;
  4. g_tm : Base.int;
  5. g_tn : Base.int;
}

A committed tile geometry. Which fields are meaningful is the geometry_choice constructor's business: g_bm/g_bk always; g_bn is 0 for Cpu_packed's unsplit full column extent and the mma lane width for Gpu_mma; g_tm/g_tn are the per-thread tile of Gpu_blocktile and 0 elsewhere. g_bk = 0 in Gpu_mma is the unstaged full-K block.

type geometry_choice =
  1. | Gpu_blocktile of geometry
    (*

    The GPU scalar blocktile menu: both operand tiles staged in kernel.

    *)
  2. | Gpu_mma of geometry
    (*

    The GPU tensorized menu: g_bk > 0 stages both operand tiles in kernel, g_bk = 0 is the unstaged full-K block.

    *)
  3. | Cpu_blocktile of Base.int
    (*

    The CPU blocktile menu's single block size (bm = bn = bk).

    *)
  4. | Cpu_packed of geometry
    (*

    The CPU packed composition; what it costs depends on the Packing_shape above it.

    *)
  5. | Lattice
    (*

    The staged tile-size lattice beyond the curated menu (gh-ocannl-514 phase 5), excluded by default policy and lifted by lift_geometry_lattice; its axes commit as Lattice_box.

    *)
type t =
  1. | Fusion of [ `Unfused | `Fused ]
    (*

    The root: the epilogue-fusion flavor (gh-ocannl-613).

    *)
  2. | Pipeline of [ `Blocktile | `Tensorized ]
    (*

    Which composed pipeline.

    *)
  3. | Batch of [ `Serial | `Grid ]
    (*

    The batch-geometry twin (gh-ocannl-643), GPU only.

    *)
  4. | Packing of [ `In_kernel | `Hoisted ]
    (*

    The CPU blocktile pipeline's link-time packing twin (gh-ocannl-470).

    *)
  5. | Geometry of geometry_choice
    (*

    The tile geometry, per the pipeline's own menu.

    *)
  6. | Lattice_box of {
    1. lb_axis : [ `Bm | `Bk ];
    2. lb_lo : Base.int;
    3. lb_hi : Base.int;
    }
    (*

    One binary interval refinement of a lattice axis: the value range still open below the commitment, lb_lo = lb_hi at a singleton. A box prices at lb_lo, its most favorable corner.

    *)
  7. | Twin of [ `Plain | `Swizzled | `Depth of Base.int ]
    (*

    The per-staged-geometry twins: the swizzled staged layout, the pipelined depths.

    *)
  8. | Tensorized_form of [ `Whole_triple | `Packed ]
    (*

    The CPU tensorized composition.

    *)
  9. | Row_block of Base.int
    (*

    The CPU whole-triple row block; 0 is the unsplit form, > 0 a pool-rendered Grid split.

    *)
  10. | Packing_shape of [ `Serial | `Hoisted | `Hoisted_grid | `Hoisted_grid_pack_rest | `Grid_pack_rest | `Grid ]
    (*

    Which CPU packed composition: where the panels are packed (in kernel, at link time, per Grid chunk) — what makes a packed geometry's traffic additional or merely relocated.

    *)

One committed decision. Each constructor belongs to exactly one level (level) and carries the whole identity of the commitment: no consumer needs the level name, or the label, to know what was decided.

type path = (Base.string * t) Base.list

What Ir.Schedule_space.enumerate and the ~path of Ir.Schedule_space.search carry at this label type: the committed vector, outermost level first. The string is the level's display name; the decision is the identity.

val equal : t -> t -> Base.bool
val compare : t -> t -> Base.int
val level : t -> Base.string

The level a decision belongs to — the name Ir.Schedule_space.tree.Choice carries. Derived from the datum, so a node's level and its children's identities cannot drift apart.

val to_label : t -> Base.string

The display rendering. Nothing reads it back.

val render_path : path -> Base.string

A path as "level=label > level=label > …", for logs and reports.