Coefficient set¶

A set of coefficients for a cost model. Each entry records its value and unit, how it was obtained, the evidence for it, and the hardware and layouts over which it holds. The registry owns the sets; every consumer loads them through this schema.

The set below is illustrative; its values are not real coefficients. The registry's sets are in coefficients/.

kind: CoefficientSet
name: example-set
coefficients:
  - gemm_eps_max_bf16:
      value: 0.78
      units: dimensionless
      method: measured
      fitted: true
      ci95: [0.74, 0.81]
      scope: {hardware: [h100]}
  - gemm_eps_max_bf16:
      value: 0.81
      units: dimensionless
      method: measured
      fitted: true
      scope: {hardware: [h200]}
  - mfu_prefill:
      value: 0.32
      units: dimensionless
      method: literature
      fitted: false
      sources:
        - {kind: discussion, cite: "inference-sim#589", role: primary}
      rationale: >
        L40S prefill MFU discount; see the cited discussion.
      scope: {hardware: [l40s]}
  - pd_transfer_base_latency:
      value: 50
      units: us_per_transfer
      method: assumed
      fitted: false
      rationale: >
        A placeholder until a measurement exists.
      scope: {hardware: [h100, h200]}

Each entry in coefficients is a map with a single key, the entry's name. A name key inside an entry is accepted and replaced by that map key. A set is complete in itself: it does not inherit from another set. A scenario may still name several sets, and how a cost model combines them is described under Selecting an entry.

Keys¶

Key	Type	Required	Meaning
`kind`	string	yes	Always `CoefficientSet`.
`name`	string	yes	The set's identity. By convention, not checked, it equals the file name, which is what a scenario's `coefficients` uses.
`coefficients`	list	yes	At least one entry, each `- <entry name>: {...}`.

Entries¶

Key	Type	Required	Meaning
`value`	number	unless `method` is `not_charged`	The coefficient. Zero exactly when `method` is `not_charged`.
`units`	string	yes	One of the units.
`method`	string	yes	How the value was obtained. One of the methods.
`fitted`	boolean	yes	Whether the value comes from fitting a curve. Must be present even when false.
`scope`	mapping	yes	Where the value holds, below. At least one dimension.
`ci95`	`[low, high]`	no	95% confidence interval. Must contain `value`.
`sources`	list	depends on `method`	Citations, below. If present, not empty.
`rationale`	string	depends on `method`	The reasoning behind a value that was not measured.
`copied_from`	string	with method `copied`	The scope the value was copied from.
`supersedes`	string	no	An entry this one replaces.
`validated`	string or list	no	Names of metrics the value has been checked against, such as `itl`. Free text.
`unsupported`	string or list	no	Names of metrics it has been found not to hold for. Free text.

`scope`¶

Each dimension lists the values the coefficient holds for. An empty scope is not "everywhere"; it means the range is unknown, and it is rejected.

Key	Type	Required	Meaning
`hardware`	list of strings	no	Chips.
`model`	list of strings	no	Models.
`tp`	list of integers	no	Tensor-parallel widths.
`ep`	list of integers	no	Expert-parallel widths.
`nodes_spanned`	list of integers	no	How many nodes a collective crosses.

Dtype and backend are not scope dimensions. Both are part of the entry's name, as in gemm_eps_max_bf16.

`sources`¶

Key	Type	Required	Meaning
`kind`	string	yes	One of the source kinds.
`cite`	string	yes	The reference: an issue, a paper, a datasheet URL.
`role`	string	yes	One of the source roles.

Identity is name and scope¶

Two entries may share a name if their scopes differ. The set above has two gemm_eps_max_bf16 entries, one for H100 and one for H200. Two entries with the same name and the same scope are an error, because a cost model would use whichever came last. Scopes are compared without regard to order: [h100, h200] and [h200, h100] are the same scope.

Selecting an entry¶

The schema defines what an entry says. Choosing among entries is the cost model's job, and blis-latency-kernel does it as follows. An entry applies to a deployment if, for every dimension its scope states, the list includes the deployment's value; hardware and model names are compared without regard to case, and a dimension the scope omits does not constrain it. The kernel reads the scenario's sets in order and, within each set, its entries in order, and the last applicable entry for each name is the one it uses. A later set can therefore override part of an earlier one. Entries that do not apply are skipped. Construction fails if no entry applies at all, or if the cost model needs a coefficient no applicable entry supplies.

What a method requires¶

Method	`rationale`	`sources`	Other
`measured`	—	—	Allows `fitted: true`. A source is expected but not required.
`calibrated`	required	at least one of kind `measured_case`	Allows `fitted: true`. `validated` must name the held-out metrics.
`literature`	required	at least one
`vendor_spec`	required	at least one
`copied`	required	—	`copied_from` required.
`assumed`	required	—
`not_charged`	required	—	`value` must be 0.

Checks¶

A set fails to load if an entry is not a single-key map, an entry has no fitted key, sources is present but empty, ci95 is not a two-element list, validated or unsupported is neither a string nor a list of strings, or any mapping has a key its type does not declare.

A loaded set is invalid if

kind is not CoefficientSet, name is empty, or there are no entries;
an entry has no name, or repeats another entry's name and scope;
value is not finite, units or method is not recognized, or scope is empty;
value is 0 with a method other than not_charged, or nonzero with not_charged;
fitted is true with a method other than measured or calibrated;
a companion field the method requires, per the table above, is missing;
a source has an unrecognized kind or role, or an empty cite;
ci95 has a non-finite end, has low above high, or does not contain value.

Source: spec/coefficient.