75 new variable statistics final energy by carrierambient heat

[maxnutz]

Short description of this pull request

Introduces new statistics function on Final Energy [by Carrier]|Ambient Heat

Definition: Energy consumption of ambient heat using heat pumps, geothermal and solar thermal energy excluding transmission/distribution losses

Current Value: 9819.48853926 TJ
Value is currently much too low compared to "Energie in Österreich 2025". (Factor 3-4)

---

Checklist

Before asking for review, please make shure, the following steps are completed (whenever possible):

• Changes are tested locally and behave as expected.
• Code is documented using numpy-styled function docstrings
• All tests succeed
• All Sourcery-bot review suggestions have been implemented or rejected with an explanation.

Sourcery-Bot starts to review your pull request, whenever it is created. This may take some time. After having finished these steps, please request for review in the Pull Request.

Summary by Sourcery

Add support for computing final energy statistics for ambient heat, including heat pumps and solar thermal, and integrate it into the existing statistics and mapping framework.

New Features:

• Introduce Final_Energy_by_Carrier__Ambient_Heat statistics function to derive ambient heat consumption from PyPSA networks.
• Expose ambient heat as a new mapped indicator in the default statistics-to-IAM mapping configuration.

Enhancements:

• Add a unit index remapping utility to standardize units for comparing input and output energy flows across statistics functions.

Tests:

• Add a dedicated test suite for Final_Energy_by_Carrier__Ambient_Heat covering balanced, zero-heat, zero-electric, and non-aggregated snapshot scenarios.

[sourcery-ai]

Reviewer's Guide

Adds a new Final_Energy_by_Carrier__Ambient_Heat statistics function, supporting both annual aggregation and snapshot-level output; introduces a unit-remapping helper to align input/output energy flows; and wires the new statistic into tests and configuration mappings.

Flow diagram for Final_Energy_by_Carrier__Ambient_Heat statistics computation

flowchart TD
    start[Call Final_Energy_by_Carrier__Ambient_Heat]
    hp_out[n.statistics.energy_balance for heat pump heat output]
    hp_in[n.statistics.energy_balance for heat pump electricity input]
    remap_out[remap_unit_index on e_out]
    remap_in[remap_unit_index on e_in]
    sum_hp[Add e_out and e_in then groupby kwargs.groupby]
    solar[n.statistics.supply for solar_thermal_carriers]
    concat[Concat res_heat_pump and solar_thermal series]
    ret[Return ambient heat series]

    start --> hp_out
    start --> hp_in
    hp_out --> remap_out
    hp_in --> remap_in
    remap_out --> sum_hp
    remap_in --> sum_hp
    sum_hp --> solar
    solar --> concat
    concat --> ret

Loading

File-Level Changes

Change	Details	Files
Implement ambient-heat final energy statistics that combine heat pump balances and solar thermal supply, with annual and snapshot-level outputs.	Add Final_Energy_by_Carrier__Ambient_Heat function that queries heat-pump heat output and electricity input via n.statistics.energy_balance and remaps units for direct comparison. Aggregate remapped heat-pump input/output by groupby to derive ambient-heat contribution and combine it with solar-thermal supply retrieved via n.statistics.supply. Support aggregate_per_year toggle to return either a Series (aggregated) or a DataFrame with snapshot columns, and integrate NaN handling for solar-thermal time series.	pypsa_validation_processing/statistics_functions.py
Introduce a unit-index remapping helper to normalize units for comparing input and output flows in statistics functions.	Add remap_unit_index utility that rebuilds a MultiIndex with units replaced according to UNITS_MAPPING. Use remap_unit_index in ambient-heat statistics to align heat and electricity units before aggregation.	pypsa_validation_processing/utils.py
Add targeted tests for the ambient-heat statistics to validate querying behavior, aggregation mode, and zero-flow scenarios.	Create a minimal _AmbientHeatStatisticsAccessor and _AmbientHeatNetwork test harness to simulate energy_balance and supply calls for different scenarios. Verify that Final_Energy_by_Carrier__Ambient_Heat issues expected statistics queries, returns correct Series/DataFrame structures, and enforces consistency between zero heat output and zero electric input. Test aggregate_per_year=False behavior to ensure snapshot-level DataFrame with MultiIndex index and DatetimeIndex columns.	tests/test_statistics_functions.py
Register the new ambient-heat statistic in the default mapping configuration for use by the higher-level framework.	Extend mapping.default.yaml to map "Final Energy [by Carrier]	Ambient Heat" to Final_Energy_by_Carrier__Ambient_Heat.

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#75	Implement a new statistics function Final_Energy_by_Carrier__Ambient_Heat in statistics_functions.py that extracts ambient heat final energy (heat pumps and solar thermal) from a PyPSA network.	✅
#75	Provide proper documentation for the new ambient heat statistics function via a comprehensive numpy-style docstring.	✅
#75	Integrate the new ambient heat variable into the configuration and test suite (add mapping in mapping.default.yaml and corresponding tests in tests/).	✅

Possibly linked issues

• New Variable Statistics: Final Energy [by Carrier]|Ambient Heat #75: The PR implements the new Ambient Heat statistics function, adds unit remapping helper, tests, and mapping.default.yaml entry.

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.