sage.plotting.consistency_diagnostics

Consistency-model training diagnostics: a single figure that puts the per-term loss curves and the per-term gradient-norm balance side by side.

The multi-detector consistency model trains several objectives at once — BCE classification, the coherent point-estimate NLL, the coupling term, and the per-detector tc/mchirp consistency NLLs. Two things must be watched together:

  • the loss curves (is each term learning, is anything spiking?), and

  • the gradient-norm contribution of each term relative to BCE (is any auxiliary term out-gradienting the classifier on the shared parameters?).

plot_consistency_diagnostics() renders both in one figure, plus the scale of the corroboration features entering the ranking head.

All inputs are plain arrays (per-iteration histories) so the routine is decoupled from how they are collected — the training loop logs them, or an offline audit produces them.

Functions

plot_consistency_diagnostics(merged, cons[, feats, ...])

Combined loss + gradient-norm diagnostics for consistency training.

Module Contents

plot_consistency_diagnostics(merged, cons, feats=None, grad_xbce=None, grad_target=0.33, cons_weight=0.1, epoch_boundaries=(), smooth=25, title=None, save_path=None)[source]

Combined loss + gradient-norm diagnostics for consistency training.

Parameters:

  • merged (array, shape (N, 4)) – Per-iteration merged-loss components [total, bce, pe_reg, coupling] (the raw, pre-weight values returned by BCEWithPEsigmaLoss).

  • cons (array, shape (N, 3)) – Per-iteration consistency-loss components [total, tc, mc].

  • feats (array, shape (N, 3), optional) – Per-iteration ranking-head input scales [backbone_meanabs, corr_meanabs, corr_maxabs].

  • grad_xbce (dict {term: value}, optional) – Per-term gradient norm as a multiple of the BCE gradient norm (e.g. {"cons_mc": 0.12, "cons_tc": 0.04, ...}). Rendered as the gradient-balance bar panel with the grad_target ceiling line.

  • grad_target (float) – The per-/total-aux gradient-norm ceiling (fraction of BCE) to mark.

  • epoch_boundaries (sequence of int) – Iteration indices to mark with vertical lines (epoch transitions).

  • smooth (int) – Rolling-mean window for the noisy per-iteration curves.

  • title (str, optional)

  • save_path (str or Path, optional) – If given, the figure is saved here (dpi 110).

Return type:

matplotlib.figure.Figure