Add can_retire validation for multi-stage optimization

[lbonaldo]

Description

The current implementation of multi-stage optimization doesn't allow a resource to switch from can_retire = 0 to can_retire = 1 between stages. This PR adds a validation check on the can_retire flag and throws an error if necessary.

What type of PR is this? (check all applicable)

• Feature

Checklist

• Code changes are sufficiently documented; i.e. new functions contain docstrings and .md files under /docs/src have been updated if necessary.
• The latest changes on the target branch have been incorporated, so that any conflicts are taken care of before merging. This can be accomplished either by merging in the target branch (e.g. 'git merge develop') or by rebasing on top of the target branch (e.g. 'git rebase develop'). Please do not hesitate to reach out to the GenX development team if you need help with this.
• Code has been tested to ensure all functionality works as intended.
• CHANGELOG.md has been updated (if this is a 'notable' change).
• I consent to the release of this PR's code under the GNU General Public license.

How this can be tested

By running the multi-stage example with can_retire = 0 for some resources in stage = 1, and then switching to can_retire = 1 in stage = 2.

Post-approval checklist for GenX core developers

After the PR is approved

• Check that the latest changes on the target branch are incorporated, either via merge or rebase
• Remember to squash and merge if incorporating into develop

[sambuddhac]

So, we for sure don't want the "can retire" to flip values between stages? Any rationale in support of that?

[lbonaldo]

The current multi-stage implementation utilizes the RET_CAP set to create variables for keeping track of retired capacity across all stages. If there is a change in this set between two stages, this function will throw an exception if a key is not found between the current and previous stages.