nvalchemi.training.CosineWeight

pydantic model nvalchemi.training.CosineWeight

Loss weight that eases from start to end on a half-cosine curve.

CosineWeight interpolates like LinearWeight but follows a half-cosine (smooth ease-in/ease-out) path: it starts and ends nearly flat and changes fastest near the midpoint. Writing \(s\) for start, \(e\) for end, and \(T\) for num_steps, the weight at schedule index \(t\) is

\[w(t) = s + (e - s)\,\frac{1 - \cos(\pi \tau)}{2}, \qquad \tau = \operatorname{clamp}\!\left(\frac{t}{T},\, 0,\, 1\right).\]

The clamp on \(\tau\) yields \(w = s\) for \(t \le 0\) (where \(\cos 0 = 1\)) and \(w = e\) for \(t \ge T\) (where \(\cos \pi = -1\)), with the fastest change at the midpoint \(t = T/2\). Prefer it over a linear ramp when you want a gentler onset and settle for a term, which can avoid the abrupt gradient shifts a sharp linear turn-on causes. The schedule index \(t\) is the global step when per_epoch=False (default) and the epoch when per_epoch=True.

Examples

>>> from nvalchemi.training.losses import CosineWeight
>>> w = CosineWeight(start=0.0, end=1.0, num_steps=10)
>>> w(step=0, epoch=0), round(w(step=5, epoch=0), 3), w(step=100, epoch=0)
(0.0, 0.5, 1.0)

Anneal a weight downward on the cosine curve:

>>> w = CosineWeight(start=1.0, end=0.1, num_steps=5000)

Notes

num_steps must be strictly positive. Instances are frozen (immutable) per the shared _BaseWeightSchedule config.