Rolling horizon tutorial

[abelsiqueira]

BLOCKED until other rolling horizon PRs are merged.

Create a tutorial for rolling horizon with a similar output to the JuMP tutorial https://jump.dev/JuMP.jl/stable/tutorials/algorithms/rolling_horizon/.

Related issues

Closes #1385
Part of #1365

Checklist

• I am following the contributing guidelines
• Tests are passing
• Lint workflow is passing
• Docs were updated and workflow is passing

[github-actions]

🤖 CompareMPS report

✅ MPS files match

[codecov]

Codecov Report

❌ Patch coverage is 97.29730% with 4 lines in your changes missing coverage. Please review.
✅ Project coverage is 98.47%. Comparing base (eb442c5) to head (bdbab55).
⚠️ Report is 4 commits behind head on main.

Files with missing lines	Patch %	Lines
src/rolling-horizon/rolling-horizon.jl	90.47%	4 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1387      +/-   ##
==========================================
- Coverage   98.61%   98.47%   -0.14%     
==========================================
  Files          38       42       +4     
  Lines        1368     1511     +143     
==========================================
+ Hits         1349     1488     +139     
- Misses         19       23       +4     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[github-actions]

📝 Check the documentation preview: https://tulipaenergy.github.io/TulipaEnergyModel.jl/previews/PR1387

[abelsiqueira]

@clizbe, the tutorial here can be reviewed in parallel to the rest of the rolling horizon changes

[abelsiqueira]

This has been rebased and marked as ready to review

[datejada]

Thanks @abelsiqueira, I left a minor comments, but generally speaking, I like it 😄
Anyway, let's wait for @clizbe's comments, since she has a sharp eye for the documentation 😉

[datejada]

I think for the sanity check, it is better to have a table here with the min, max, and average error. In addition, the definition of the error should be only one as:

error = demand + charging - thermal - solar - discharge

The sanity check is that this should be zero or within the tolerances of the solver.

[abelsiqueira]

Thanks for the review, @datejada. I'll wait for @clizbe's review to make a single update.

[clizbe]

Thanks for the PR! Looks like a nice tutorial. I didn't run the code, but read through it. I think there's some context missing (or maybe in different sections of the docs) and I wonder about the window naming. Is this the standard naming convention? If not, can we come up with something more intuitive?

[abelsiqueira]

Thanks for the review @clizbe, I've committed the easy and commented on the rest

[datejada]

@clizbe, it is not on you, I am the one sorry here, I have not been able to explain myself correctly with the RH, let me try again 😜

1. The solutions will differ as long as there are constraints connecting different time periods, such as energy storage balance, ramping constraints, and unit commitment. Since we have a battery in this case, energy storage balance constraints are crucial, leading us to expect feasible solutions.

2. Why do we anticipate these differences? When we optimize for an entire week at once, the model benefits from perfect foresight of the optimization horizon. This means that at the beginning of the week, the model knows what will happen by the end, allowing it to optimize the storage level from the first hour based on this comprehensive information. In contrast, a rolling horizon approach limits the optimization to a two-day window. As a result, the model cannot foresee events that occur later in the week and can only optimize for the immediate two days. While this creates suboptimal outcomes for the overall week, it remains a viable solution.

3. Why accept suboptimal solutions? There are a couple of reasons. First, solving an entire planning horizon (like a full year) may not be feasible or could take a long time. The rolling horizon approach provides a practical approximation to the perfect foresight model. Second, using smaller optimization models allows for a more accurate representation of market dynamics. With detailed considerations (like startup/shutdown processes, ramping, and DC optimal power flow), players are often limited in their foresight to just a few days, leading to suboptimal decisions. This reality is naturally reflected in the prices generated by the rolling horizon method.

4. How do we define uncertainty in our model? Uncertainty refers to potential future scenarios that occur with specific probabilities, such as a dry weather year, a wet weather year, or an average weather year, each with associated probabilities A, B, and C, respectively.

5. Does uncertainty affect the rolling horizon approach? Not really. The rolling horizon analysis typically focuses on a single scenario (for example, a dry weather year). The differences in the solutions arise not from uncertainty but from the fact that each optimization window is shorter than the overall horizon for that scenario.

6. Some might argue that a shorter optimization window allows the rolling horizon to account for future uncertainty. However, as defined in Tulipa, this is not an accurate use of the term uncertainty in this context. The rolling horizon simply prevents the solution from anticipating future events that lie outside its optimization window.

7. Is there a way in which the rolling horizon approach and the full model yield the same results? Yes, if there are no intertemporal constraints—such as those related to storage, ramping, or unit commitment—the solutions will be identical.

[datejada]

After this, I would add the comparison of the duals for the sake of completeness.

[clizbe]

You should make a TED talk! ;)

[abelsiqueira]

@datejada, I've updated the errors now as well, let me know if that's what you're looking for

[datejada]

@abelsiqueira Thanks for the changes in the PR. I have a suggestion for the wording in the last part, but I'm pre-approving, so you can merge after accepting the change.

[abelsiqueira]

Thanks for the reviews @clizbe and @datejada, the tutorial looks much better now!