Fix convertible-bond dividend drop between evaluation and settlement …

[LeonxLJX]

…dates

In BinomialConvertibleEngine::calculate(), future dividends are subtracted from s0 using the risk-free rate's referenceDate (the evaluation date) as cutoff, but the tree and DiscretizedConvertible anchor all dividend/coupon/callability times at arguments_.settlementDate (evaluation date + settlementDays).

A dividend falling strictly between the evaluation date and the settlement date was subtracted from s0 but treated as 'already occurred' inside the tree and never added back, so its value silently vanished from the price.

Roll the dividend-adjusted spot forward to the settlement date by dividing by the settlement-date discount factor, so the tree starts from the correct settlement-date forward price and the in-lag dividend is properly priced.

Adds a regression test that asserts an in-lag dividend reduces the convertible bond price by an economically meaningful amount.

Closes #2701 (Issue B)

[CLAassistant]

All committers have signed the CLA.

[boring-cyborg]

Thanks for opening this pull request! It might take a while before we look at it, so don't worry if there seems to be no feedback. We'll get to it.

[LeonxLJX]

Why this one-line divide is the right fix.

Root cause. BinomialConvertibleEngine::calculate() subtracts future dividends from s0 using the risk-free rate's referenceDate (evaluation date) as the cutoff. But the binomial tree and DiscretizedConvertible anchor every dividend/coupon/callability time at arguments_.settlementDate (eval date + settlementDays). So a dividend falling strictly between the two is removed from s0 yet treated as 'already occurred' inside the tree and never added back — it's silently dropped from the price (issue #2701).

Judgment. Dividing the ex-dividend s0 by the settlement-date discount factor rolls the spot forward to the settlement date, so the tree now starts from the correct settlement-date forward price and the in-lag-window dividend is no longer lost. It's a minimal, local change that doesn't touch the tree construction.

Suggestion. Worth adding a second regression that also exercises the original #2701 scenario (dividend at settlement) to lock in no-regression, and a quick check that callability/coupon times in the same lag window don't need the same roll — happy to add if you want belt-and-suspenders coverage.

[lballabio]

It's correct to compensate for the discount factor between evaluation date and settlement date if the tree is pricing the bond at the settlement date: this would be true even in the absence of any dividends.

However, after this fix, any dividend between the evaluation date and the settlement date is still subtracted and not added back, so we're not fixing that: it's a different fix.

I think that the possible dividend was a non-issue, though: if we're calculating the price at the settlement date, it is correct to start from an underlying price that doesn't include any dividend paid before that; at that point, the underlying price would be adjusted accordingly and the dividend would be paid and gone and not affecting the bond price anymore.

So all in all this PR is correct as far as the code change, but the comment above it should not mention the dividends. Instead, we could add another comment where the dividends are subtracted, stating that we're also subtracting any possible dividend between evaluation and settlement, that it won't be added back, and that it's the right thing to do.

[LeonxLJX]

Thanks for the careful read, Luigi. You're right — the original
comment framed the discount-factor roll-forward as if it existed
because of dividends between ref and settlement, which is
misleading: the real reason is that the tree (and
DiscretizedConvertible) anchor every dividend/coupon/callability
time at arguments_.settlementDate, so the engine must hand the
lattice the settlement-date forward price regardless of whether
any dividends exist in the window.

I just pushed a docs-only commit on
fix/convertible-dividend-settlement-lag that rewrites the
roll-forward comment around that point and keeps the
subtract-dividends comment but reframes it as "subtracted here,
never re-added because the tree sees it as already paid by
settlement". No code changes. Please take another look.

[lballabio]

This comment should be updated too; it's still subtracted and not added back, and it's the correct thing to do.