CalmarLoss

Defined in fynance.models.loss

class CalmarLoss(rf=0., period=252, eps=1e-8)

Bases: BaseLoss

Negative Calmar ratio as a differentiable loss.

Calmar = annualized return / maximum drawdown. Minimizing this loss maximizes return per unit of worst peak-to-trough loss. The maximum drawdown is computed differentiably from the cumulative return path via torch.cummax.

Parameters are inherited from BaseLoss (period, eps).

Notes

Drawdowns are \(O(\text{returns})\), so a fixed absolute eps (e.g. 1e-8) is dimensionally wrong: on a low- or zero-drawdown batch the ratio would explode and dominate gradients. The drawdown is therefore floored with a returns-scaled value |equity|.mean() / MAX_RATIO (plus a bare eps backstop for the degenerate all-zero batch), capping the ratio at roughly MAX_RATIO in the low-drawdown regime regardless of the return scale.

The ratio is then passed through a smooth saturating map, MAX_RATIO * tanh(ratio / MAX_RATIO), instead of a hard clamp. A hard clamp pins the loss to a constant on a near-zero-drawdown batch and so zeroes the gradient in exactly the strong-uptrend regime training still wants to push on; tanh is near-linear for normal-regime ratios (leaving their numerics unchanged) yet keeps a residual, non-zero gradient when the ratio is large. This keeps the loss finite and bounded while preserving its sign convention (minimizing it maximizes the ratio).

forward(y_pred, y_true=None)

Compute the negative Calmar ratio (scalar).