Derive weather-dependent configuration from top-level weather_year

[danielelerede-oet]

Changes proposed in this Pull Request

This PR simplifies the configuration of a model run by resolving the weather year, snapshot range, and atlite cutout configuration consistently.

Previously, users had to manually keep several options aligned when changing the weather year, including:

• load_options.weather_year;
• snapshots.start and snapshots.end;
• the default atlite cutout name.

With this PR, load_options.weather_year accepts two modes:

• an explicit integer, e.g., 2013 or 2018 (as it is already)
• or the optional value derive_from_snapshots

When an explicit year is provided, the workflow automatically derives:

• snapshots.start;
• snapshots.end;
• the default atlite cutout name;
• the internal atlite cutout configuration.

For example:

load_options:
  source: "gegis"
  weather_year: 2018

resolves to:

• snapshots from 2018-01-01 to 2019-01-01;
• the atlite cutout cutout-2018-era5;
• renewable profiles configured with cutout: auto using the resolved cutout.

Alternatively:

snapshots:
  start: "2013-03-01"
  end: "2013-03-07"
  inclusive: "left"

load_options:
  source: "gegis"
  weather_year: derive_from_snapshots

preserves the configured snapshot range and infers the demand weather year from snapshots.start.

Snapshot-derived weather years are only accepted when the configured range belongs to a single calendar year.

The PR also simplifies the atlite configuration by replacing:

atlite:
  default: ...
  cutouts:
    ...

with:

atlite:
  cutout:
    module: era5
    dx: 0.3
    dy: 0.3

The resolved atlite.default and atlite.cutouts entries are reconstructed internally by the workflow. Legacy atlite.cutouts and atlite.default configurations are migrated automatically to atlite.cutout with a deprecation warning.

User impact

Users can choose which configuration should be authoritative:

• use an explicit load_options.weather_year to derive an annual snapshot range and matching cutout;
• use derive_from_snapshots to preserve a custom snapshot range and infer the matching weather year.

This removes the need to manually synchronize the demand weather year, snapshots, atlite cutout, and renewable profile configuration.

Checklist

• I consent to the release of this PR's code under the AGPLv3 license and non-code contributions under CC0-1.0 and CC-BY-4.0.
• I tested my contribution locally and it seems to work fine.
• Code and workflow changes are sufficiently documented, including updates to docstrings for meaningful functions.
• Newly introduced dependencies are added to envs/environment.yaml and doc/requirements.txt.
• Changes in configuration options are added in all of config.default.yaml and config.tutorial.yaml.
• Add a test config or line additions to test/ (note tests are changing the config.tutorial.yaml)
• Changes in configuration options are also documented in doc/configtables/*.csv and line references are adjusted in doc/user-guide/configuration.md and doc/tutorials/electricity-model.md.
• If config sections were added, renamed, or removed, update doc/assets/scripts/extract_config_snippets.py accordingly.
• Archives of the uploaded data do not have an enclosing folder and archive names correspond to the conventions of configs/bundle_config.yaml.
• A note for the release notes doc/release-notes.md is amended in the format of previous release notes, including reference to the requested PR.

[davide-f]

Hello and thanks @danielelerede-oet !
Some merge conflicts have unfortunately arrived.

Regarding the proposal, what about keeping weather_year in load_options with optional value "derive_from_snapshots" to achieve the same goal?

This is a good point; good to keep in mind that weather_year is not too flexible depending on the data source and we can improve the documentation to improve that.
I see value in having the option to choose a different weather year to enable more customization and I see also the benefit in having the option you suggest.

How do you see having an optional non-default value like "weather_year: derive_from_snapshots" to select the weather_year from snapshots?

[danielelerede-oet]

Hi @davide-f , thanks for the suggestion. I have resolved the merge conflicts for the time being, but regarding your though I agree that keeping weather_year under load_options while supporting derive_from_snapshots as an optional, non-default value is a good compromise. I'll work on it

[danielelerede-oet]

Hi @davide-f the requested changes are ready and I updated the documentation and PR description accordingly