pulsatrix::CalibrationLoss Class Reference

BS = mean_n( Σ_k (p[n,k] − y[n,k])² ), y one-hot at target_class[n] – Brier's original multi-class proper scoring rule. More...

#include <calibration_loss.hpp>

Public Member Functions
	CalibrationLoss (DeviceBackend *backend)
	Constructs a calibration loss.
float	forward (const Tensor &probs, const Tensor &target_class)
	Computes the Brier score and caches what backward() needs.
Tensor	backward () const
	Gradient w.r.t. probs: 2(p[n,k] − y[n,k]) / N.

Detailed Description

BS = mean_n( Σ_k (p[n,k] − y[n,k])² ), y one-hot at target_class[n] – Brier's original multi-class proper scoring rule.

Note

Takes probabilities directly, not raw logits – deliberately not fused with softmax the way CrossEntropyLoss is. CrossEntropyLoss fuses softmax specifically because log(softmax(x)) needs the log-sum-exp stabilization trick to avoid log(0); the Brier score has no log anywhere, so there is no numerical-stability reason to fuse softmax the same way. A caller with raw logits composes the existing SoftmaxModule first. See mission_calibration_loss.md's Design section.

Does not decompose into aleatoric/epistemic uncertainty. That decomposition structurally requires a credal set or second-order distribution – genuinely multiple forward passes / an ensemble (Hofman, Sale & Hüllermeier, arXiv:2404.12215) – which a single deterministic prediction cannot produce. This class computes the base scoring-rule loss only; the decomposition is a distinct, not-yet-built feature requiring its own multi-forward-pass design, not something this single-pass API silently omits or approximates.

Averaged over the batch of N examples (not over N·K elements) – mirrors DQNLoss/PolicyGradientLoss's "mean over examples" convention: each example contributes one Brier score (itself already summed over K classes), so the batch mean divides by N, not N·K.

Not a Module subclass, for MSELoss's own reason: a loss is the seed point relevance propagation starts from, not something propagate_relevance is defined for.

Constructor & Destructor Documentation

CalibrationLoss()

pulsatrix::CalibrationLoss::CalibrationLoss ( DeviceBackend *  backend )

explicit

Constructs a calibration loss.

Parameters

backend

Backend to allocate the gradient tensor through. Not owned; must outlive this loss.

Member Function Documentation

backward()

Tensor pulsatrix::CalibrationLoss::backward

(

)

const

Gradient w.r.t. probs: 2(p[n,k] − y[n,k]) / N.

Returns

Gradient tensor, shape (N, num_classes) – the shape of probs passed to forward().

Exceptions

std::logic_error

if forward() has never been called.

forward()

float pulsatrix::CalibrationLoss::forward	(	const Tensor &	probs,
		const Tensor &	target_class
	)

Computes the Brier score and caches what backward() needs.

Parameters

probs	Predicted probabilities, shape (N, num_classes), N >= 1, num_classes >= 1. Not validated to sum to 1 per row – an internal numerical invariant of whatever produced them (e.g. SoftmaxModule), not an external boundary this loss owns.
target_class	Ground-truth class index per example, shape (N, 1) – the same float-encoded discrete-index convention DQNLoss/PolicyGradientLoss use.

Returns

The scalar mean Brier score.

Exceptions

std::invalid_argument

if either tensor has the wrong rank, if the batch dimensions disagree, if an encoded class index is not within 1e-4 of a whole number, or if a decoded index falls outside [0, num_classes) – all external boundaries, byte-for-byte PolicyGradientLoss::forward's own classification.

Note

Device-generic: runs on Cpu, Cuda or Hip tensors (GPU-native-kernels Mission 1b); inputs must share one device.

---

The documentation for this class was generated from the following file:

• include/pulsatrix/calibration_loss.hpp