canvas_engineering.residuals

Residual signal tracking for scheduling and diagnostics.

canvas_engineering.residuals.ResidualSpec dataclass

Declares what error signals a region emits and how to summarize them.

Parameters:

Name	Type	Description	Default
kinds	Tuple[str, ...]	Named error signal types to track. Each gets its own running scalar summary.	('prediction',)
reduce	str	How to reduce an error tensor to scalars. "max_mean" = [max, mean] sliced to n_kinds. "mean" = mean only. "max" = max only. "l2" = L2 norm.	'max_mean'
decay	float	EMA decay factor. summary = decay * old + (1 - decay) * new. Higher decay = smoother, slower response. 0.95 is a good default.	0.95

canvas_engineering.residuals.ResidualAccumulator

Bases: Module

Tracks running scalar summaries of residual signals per region.

Not a learned module — uses nn.Module only for device management and state_dict integration. No trainable parameters.

The accumulator stores a (n_regions, n_kinds) buffer of running EMA scalars. Each call to update() reduces an error tensor to scalars and blends them into the running summary.

Usage

acc = ResidualAccumulator(["err_a", "err_b"], ResidualSpec()) acc.update("err_a", error_tensor) # (B, N, D) or (B, N) or scalar print(acc.summaries()) # {"err_a": {"prediction": 0.12}, ...}

reset()

Reset all summaries to zero.

summaries()

Get current summaries as {region: {kind: value}}.

Returns a plain dict of floats (detached from compute graph).

summary_tensor()

Get raw (n_regions, n_kinds) summary tensor.

update(region, error)

Update running summary for a region.

Parameters:

Name	Type	Description	Default
region	str	Region name (must be in the region_names list).	required
error	Tensor	Error tensor of any shape. Reduced to scalar(s) via the spec's reduce mode, then blended into the EMA.	required