feat: add river-water and sea-water sourced heat pumps

[amos-schledorn]

Closes # (if applicable).

Changes proposed in this Pull Request

This PR adds potential river-water and sea-water sourced heat pumps based on the implementations by @MajaHIC, @juboerms and @felix-land:

• retrieval of HERA data for river discharge and ambient temperature
• retrieval of Copernicus data for seawater temperatures
• Computation of river-water heat potentials per onshore region (approximation of river water temperature from ambient temperature based on Triebs & Tsatsaronis 2022
• Mapping of seawater temperatures to onshore regions
• Spatial limitation of river-water and sea-water heat to district heating areas (Manz et al. 2024)
• For both river water and sea water, DEA's excess-heat-sourced heat pumps are assumed for cost data - improvement to be tracked in separate issue
• Added interactive plotting of heat source maps for air, river water and sea water (temperature and, where available energy)
• Added interactive plotting of COPs
• Optional interactive plotting of bus balances, s.t. matching string pattern (plotting:interactive_bus_balance:bus_name_pattern), defaults to None

Open TODOs

• Introduce lower temperature threshold for sea water utilisation
• Add Copernicus data to bundle
• Add copyright notice for Copernicus data
• Update data retrieval
• Add plotting procedure for heat potentials
• Final sanity checks

Checklist

• I tested my contribution locally and it works as intended.
• Code and workflow changes are sufficiently documented.
• Changed dependencies are added to envs/environment.yaml.
• Changes in configuration options are added in config/config.default.yaml.
• Changes in configuration options are documented in doc/configtables/*.csv.
• Sources of newly added data are documented in doc/data_sources.rst.
• A release note doc/release_notes.rst is added.

To be tracked in separate issues

• Scaling of heat pump investment costs: Change scaling of heat pump investment costs to electric capacity #1705
• Restriction of sea-water heat usage: Restrict sea-water heat pump energy output #1706

Testing

Note: I've made these test runs with sea-water heat pump investment costs set to those of air-sourced heat pumps (fixed now but the results have not been re-computed).

Test config

scenario:
  clusters:
  - 30 # number of clusters

clustering:
  resolution_sector: 5h

sector:
  heat_pump_sources:
      urban central:
      - air
      - sea_water
      - river_water
      - geothermal

plotting:
  heat_source_map:
    enable: true

countries: ['DE', 'DK', 'AT']

electricity:
  renewable_carriers: [solar, solar-hsat, onwind, offwind-ac, offwind-dc, offwind-float]

Results

District heat balances

Sea-water heat pumps are built extensively, river-water heat pumps only sparingly. This is expected, due to unlimited sea-water use and river-water heat pump investment costs likely being overestimated.

Example of COP plot

Example of heat source plot

(river water temperature)

[Copilot]

Pull Request Overview

This PR integrates river-water and sea-water sourced heat pumps into the workflow by adding new data retrieval, processing, and visualization steps.

• Introduces retrieval and preprocessing of HERA river discharge/ambient temperature and Copernicus seawater temperature data
• Adds Snakemake rules and scripts to compute heat potentials, COP profiles, and interactive heat source maps
• Updates environment files, default/test configurations, and documentation to register the new heat sources

Reviewed Changes

Copilot reviewed 33 out of 33 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
scripts/build_cop_profiles/BaseCopApproximator.py	Renamed the COP approximation method and added a cop property
scripts/build_ambient_air_temperature_yearly_average.py	New script computing yearly average ambient air temperature rasters
rules/retrieve.smk	Added rules to download HERA and seawater temperature datasets
rules/postprocess.smk	Added plotting rules for heat source maps and COP profiles
rules/build_sector.smk	Added rules for building river/sea water heat potentials
envs/*-pinned.yaml & envs/environment.yaml	Pinned/copied copernicusmarine dependency across environments
doc/data-bundle.rst & doc/data-retrieval.rst	Documented Copernicus data source and retrieval instructions
doc/configtables/sector.csv	Updated limited_heat_sources schema for river water
doc/release_notes.rst	Announced support for river-water and sea-water heat pumps
config/*.yaml	Enabled new heat pump sources and interactive bus-balance plotting
Snakefile	Registered new plotting and COP profile targets in the default rule

Comments suppressed due to low confidence (2)

config/plotting.default.yaml:1315

• [nitpick] Key uses an underscore (river_water) whereas other heat-pump keys use spaces (e.g. air heat pump). Consider renaming to urban central river water heat pump for consistency.

urban central river_water heat pump: '#184861'

Snakefile:194

• Removing default_target: True from the all rule may prevent Snakemake from building new targets by default. Ensure the default target remains correctly specified.

-    default_target: True

[Copilot]

Pull Request Overview

This PR implements river-water and sea-water sourced heat pumps by adding data retrieval, potential computation, and plotting support.

• Introduces retrieval rules for HERA river data and Copernicus sea-water temperatures
• Adds scripts and Snakemake rules to compute ambient air, river, and sea heat potentials
• Updates configuration and documentation to enable new heat pump sources and plotting

Reviewed Changes

Copilot reviewed 33 out of 33 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
scripts/build_cop_profiles/BaseCopApproximator.py	Renames COP approximation method and enforces COP ≥ 1
scripts/build_ambient_air_temperature_yearly_average.py	New script to compute yearly average onshore air temperatures
rules/retrieve.smk	Adds seawater_temperature and retrieve_hera_data rules
rules/build_sector.smk	Adds build_river_heat_potential and build_sea_heat_potential
envs/*-pinned.yaml & envs/environment.yaml	Pins copernicusmarine dependency in all environments
config/config.default.yaml & plotting.default.yaml	Enables new heat pump sources and interactive plotting defaults
doc/data-bundle.rst & doc/configtables/sector.csv	Documents the new sea- and river-water data bundle and config
doc/release_notes.rst	Notes support for river-water and sea-water heat pumps

Comments suppressed due to low confidence (2)

config/plotting.default.yaml:1315

• [nitpick] Legend keys elsewhere use space-separated names (e.g., sea water heat pump). Rename river_water to river water for consistency.

urban central river_water heat pump: '#184861'

scripts/build_cop_profiles/BaseCopApproximator.py:76

• Renaming approximate_cop to _approximate_cop will break subclasses still overriding approximate_cop. Either update all subclass methods or retain the public abstract name and call it internally.

def _approximate_cop(self) -> Union[xr.DataArray, np.array]:

[Copilot]

Pull Request Overview

This PR adds support for river‐water and sea‐water sourced heat pumps by integrating new data retrieval rules, processing routines, and configuration options. Key changes include:

• New functions to process and map river discharge, ambient, and seawater temperature data.
• Updates to configuration files and plotting routines to incorporate the new heat pump source types.
• Adjustments to dependency files and release notes to document the added features.

Reviewed Changes

Copilot reviewed 33 out of 33 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
scripts/build_cop_profiles/BaseCopApproximator.py	Added a cop property with a cleaner API for approximating COP values.
scripts/build_ambient_air_temperature_yearly_average.py	New script to compute yearly average ambient air temperature with geographic masking.
rules/retrieve.smk	Introduced new rules to retrieve seawater and HERA data.
rules/postprocess.smk	Added a rule for plotting heat source maps.
rules/build_sector.smk	Added rules for computing river and sea water heat potentials and updated heat source temperature input handling.
envs/, doc/, Snakefile, config/*	Updated dependencies, documentation, configuration, and workflow definitions to support the new heat pump configurations.

Comments suppressed due to low confidence (1)

Snakefile:92

• [nitpick] Consider refactoring the repeated lambda-based expand calls into a dedicated function or rule to improve readability and reduce duplication in the Snakefile.

expand( RESULTS + "graphs/cop_profiles_s_{clusters}_{planning_horizons}.html", ... )

[amos-schledorn]

The failing CI is a little odd: System.IO.IOException: No space left on device : '/home/runner/actions-runner/cached/_diag/Worker_20250526-162559-utc.log'
Maybe @lkstrp can help?