clophfit.fitting.grid#

Machinery for expanding a grid of fit specifications.

A grid search over fitting options is generic: something describes which knobs exist, a product is taken over configuration blocks, each combination becomes a flat specification, and specifications that describe the same model must not appear twice under different names. Only the vocabulary - which knobs a given project exposes and what it calls them - is project-specific.

This module owns the machinery. The caller supplies the knobs.

The separation matters because of how it failed before. When a project kept the knob descriptions, the expansion, and the checks in three places that had to agree, six knobs were configured and silently never reached the model: runs succeeded, diagnostics looked normal, and trace ids claimed distinctions the fitted models did not have. Keeping the mechanism here means a project describes each knob once and gets expansion, signatures and duplicate detection from it.

Classes#

Knob

One configurable quantity, from configuration block to model kwarg.

Functions#

`direct_kwargs`(cfg, knobs)	Return the model kwargs that are plain pass-throughs of a knob.
`apply_blocks`(cfg, knobs, blocks)	Copy every knob from its source block into cfg.
`model_signature`(cfg, knobs[, extra_fields])	Return a digest of everything in cfg that changes the fitted model.
`check_unique_signature`(seen, signature, identifier)	Record a specification's signature, rejecting a duplicate model.
`inert_knobs`(rows, knobs)	Return the knobs that never arrived at the model or never varied.

Module Contents#

class clophfit.fitting.grid.Knob#

One configurable quantity, from configuration block to model kwarg.

Parameters:

name (str) – Key this knob occupies in an expanded specification.
block (str) – Name of the configuration block it is read from.
source_key (str) – Key within that block. Differs from name only where the configuration spelling and the specification spelling diverge.
default (Any) – Value used when the block omits the key.
target (str) – Model-kwarg this knob is passed as, when the pass-through is a plain rename with no coercion or conditional construction. Empty means the caller places it, which is the case for anything that lands inside a config object or needs a type conversion.
reader (Callable[[dict[str, Any]], Any] | None) – How to read the resulting value back out of the built model kwargs. None marks a knob that is consumed on the way through and has no one corresponding kwarg, so it cannot be verified directly.

property key: str#

The key to read from the source block.

Return type:: str

clophfit.fitting.grid.direct_kwargs(cfg, knobs)#

Return the model kwargs that are plain pass-throughs of a knob.

Parameters:

cfg (Mapping[str, Any]) – An expanded specification.
knobs (Iterable[Knob]) – Knobs to consider; those without a target are skipped.

Returns:

Target name to value.

Return type:

dict[str, Any]

Notes

Only knobs whose journey to the model is a rename belong here. A knob that is coerced, made conditional, or folded into a config object stays with the caller: expressing those generically would need a coercion language whose mistakes are exactly as silent as the ones this registry exists to prevent.

clophfit.fitting.grid.apply_blocks(cfg, knobs, blocks)#

Copy every knob from its source block into cfg.

Parameters:

cfg (dict[str, Any]) – Specification being built; mutated in place.
knobs (Iterable[Knob]) – Knobs to copy.
blocks (Mapping[str, Mapping[str, Any]]) – Source block per block name.

Raises:

KeyError – If a knob names a block that was not supplied, which would otherwise surface much later as a missing value in a fitted model.

Return type:

None

clophfit.fitting.grid.model_signature(cfg, knobs, extra_fields=())#

Return a digest of everything in cfg that changes the fitted model.

Parameters:

cfg (Mapping[str, Any]) – An expanded specification.
knobs (Iterable[Knob]) – Knobs whose resolved values determine the model.
extra_fields (Sequence[str]) – Further specification keys that also determine the model but are not knobs, such as a dataset variant or a sampling width.

Returns:

Short hex digest over the resolved values.

Return type:

str

Notes

Identifiers built from the names of configuration blocks distinguish two blocks that are named differently whether or not they describe different models. This digest is taken from resolved values instead, so specifications that agree as models agree here.

clophfit.fitting.grid.check_unique_signature(seen, signature, identifier)#

Record a specification’s signature, rejecting a duplicate model.

Parameters:

seen (dict[str, str]) – Signature to identifier, accumulated across one grid; mutated in place.
signature (str) – Signature of the specification being added.
identifier (str) – Human-readable identifier, used in the error message.

Raises:

ValueError – If a different identifier already claimed this signature, meaning two cells of one grid would fit identical models under different names.

Return type:

None

clophfit.fitting.grid.inert_knobs(rows, knobs)#

Return the knobs that never arrived at the model or never varied.

Parameters:

rows (Sequence[Mapping[str, Any]]) – One mapping of knob name to arrived value per specification, with "<MISSING>" where a knob produced no kwarg.
knobs (Sequence[Knob]) – Knobs the grid is supposed to vary.

Returns:

Knob name to the reason it is inert; empty when every knob varies.

Return type:

dict[str, str]

Notes

The constancy check applies only to a grid of more than one specification. A single-specification grid pins its knobs by construction, so a constant value there is the intended configuration rather than evidence a knob went missing.