@energyLS thanks for catching this. It seems the text wasn't updated after changes between the working and released docs versions.

Since we are at it, I had a thought that we could parametrise this example to be simpler and more intuitive. In the current stochastic risk-neutral setup, the model yields slightly less solar, more wind, and about three times more electrolysis, which is close to optimization noise. The risk_aversion extension then shows that the cheapest hedge is to overbuild solar and pair it with long-duration hydrogen storage, even though solar is stressed in the "volcano" scenario. When preparing these docs, I thought this a fantastic example where an unintuitive economic solution prevails, but I heard a few times that people questioned if it could be an error.

Rather than open another PR just for this .md file, my suggestion is: let me reparameterize the example into a simpler instance and add it directly to this PR; and you can review the new example, if this is ok? I will need a quiet hour, will push it tonight.

Then I'll merge this PR with an eventually better example.

@energyLS thanks for catching this. It seems the text wasn't updated after changes between the working and released docs versions.

Since we are at it, I had a thought that we could parametrise this example to be simpler and more intuitive. In the current stochastic risk-neutral setup, the model yields slightly less solar, more wind, and about three times more electrolysis, which is close to optimization noise. The risk_aversion extension then shows that the cheapest hedge is to overbuild solar and pair it with long-duration hydrogen storage, even though solar is stressed in the "volcano" scenario. When preparing these docs, I thought this a fantastic example where an unintuitive economic solution prevails, but I heard a few times that people questioned if it could be an error.

Rather than open another PR just for this .md file, my suggestion is: let me reparameterize the example into a simpler instance and add it directly to this PR; and you can review the new example, if this is ok? I will need a quiet hour, will push it tonight.

Then I'll merge this PR with an eventually better example.

Dear @Irieo thank you so much for the detailled reply and the insights. I fully support your idea to reparameterize, and I would be happy to review. Just ping me when it is ready for a review!

Dear @Irieo thank you so much for the detailled reply and the insights. I fully support your idea to reparameterize, and I would be happy to review. Just ping me when it is ready for a review!

Thanks Leon. After playing a bit with numbers, two suggestions in 918e6a1: (i) backup generator does not have existing capacity now (so hedge comes at CAPEX + OPEX costs), and (ii) volcano scenario is a bit more likely. Please take a look if this is now intuitive and clear.
Doctest should pass 🟢