Skip to content

demand.py

apply_heat_mix_to_decentral_heat_buses(load, heat_share)

Apply heat production mix ratios to decentral heat loads to disaggregate by energy carrier.

This function transforms decentral heat loads (rural and urban decentral heat buses) by breaking them down into their constituent energy carrier contributions based on the actual heat production mix. Non-decentral loads are passed through unchanged.

Parameters:

Name Type Description Default
load pandas.Series

Series containing heat load data indexed by year, location, carrier, and bus_carrier. Should include loads from both decentral and non-decentral heat buses.

 required
heat_share pandas.Series

Series containing the fractional share of each energy carrier in the heat production mix for decentral heat buses, indexed by year, location, carrier, and bus_carrier. Values should sum to 1.0 for each (year, location) combination.

 required

Returns:

Type Description
pandas.Series

Series combining unchanged non-decentral loads with disaggregated decentral loads, where each decentral heat load has been multiplied by the heat production mix ratios and expanded into separate entries for each contributing energy carrier.
Notes

Decentral heat buses are identified by regex pattern matching for "decentral" or "rural" in the index. Each decentral load value is multiplied by all applicable heat share ratios to produce a detailed breakdown of the energy carriers feeding that heat demand.

Source code in evals/views/demand.py 
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
def apply_heat_mix_to_decentral_heat_buses(
    load: pd.Series, heat_share: pd.Series
) -> pd.Series:
    """
    Apply heat production mix ratios to decentral heat loads to disaggregate by energy carrier.

    This function transforms decentral heat loads (rural and urban decentral heat buses) by
    breaking them down into their constituent energy carrier contributions based on the
    actual heat production mix. Non-decentral loads are passed through unchanged.

    Parameters
    ----------
    load
        Series containing heat load data indexed by year, location, carrier, and bus_carrier.
        Should include loads from both decentral and non-decentral heat buses.
    heat_share
        Series containing the fractional share of each energy carrier in the heat production
        mix for decentral heat buses, indexed by year, location, carrier, and bus_carrier.
        Values should sum to 1.0 for each (year, location) combination.

    Returns
    -------
    :
        Series combining unchanged non-decentral loads with disaggregated decentral loads,
        where each decentral heat load has been multiplied by the heat production mix ratios
        and expanded into separate entries for each contributing energy carrier.

    Notes
    -----
    Decentral heat buses are identified by regex pattern matching for "decentral" or "rural"
    in the index. Each decentral load value is multiplied by all applicable heat share ratios
    to produce a detailed breakdown of the energy carriers feeding that heat demand.
    """
    decentral_heat = load.filter(regex="decentral|rural")

    load = load.drop(decentral_heat.index)

    to_concat = [load]
    for (year, location, carrier), data in decentral_heat.groupby(
        [DataModel.YEAR, DataModel.LOCATION, DataModel.CARRIER]
    ):
        ratios = filter_by(heat_share, year=year, location=location)
        result = data.item() * ratios
        to_concat.append(rename_aggregate(result, carrier))

    return pd.concat(to_concat)

view_demand_fed_sectoral(result_path, nc, config, subdir='evaluation')

Evaluate and export final energy demand (FED) disaggregated by sector.

This function calculates and exports final energy demand broken down by sector (Transport, Industry, Agriculture, HH & Service) with detailed energy carrier information. The output includes charts and Excel exports showing energy demand with sector-level disaggregation for comprehensive energy system analysis.

Parameters:

Name Type Description Default
result_path str | pathlib.Path

Path where the evaluation results (plots and data files) will be saved.

 required
nc pypsa.NetworkCollection

Dictionary containing PyPSA network objects, typically keyed by year or scenario. Each network should contain Load, Link, and Generator components with energy data.

 required
config dict

Configuration dictionary containing view settings and chart specifications. Must include 'view' key with chart type and other plotting parameters.

 required
subdir str | pathlib.Path

Subdirectory name within result_path where outputs will be saved.

 'evaluation'
Notes

Uses _get_sectoral_fed() to calculate FED with detailed heat mix processing, distribution loss accounting, and sector aggregation. Results are exported with sector-level disaggregation to show how energy demand is distributed across different end-use sectors of the economy.

See Also

_get_sectoral_fed : Core calculation function for final energy demand view_demand_fed_total : Export FED aggregated across all sectors

Source code in evals/views/demand.py 
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
def view_demand_fed_sectoral(
    result_path: str | Path,
    nc: NetworkCollection,
    config: dict,
    subdir: str | Path = "evaluation",
) -> None:
    """
    Evaluate and export final energy demand (FED) disaggregated by sector.

    This function calculates and exports final energy demand broken down by sector
    (Transport, Industry, Agriculture, HH & Service) with detailed energy carrier
    information. The output includes charts and Excel exports showing energy demand
    with sector-level disaggregation for comprehensive energy system analysis.

    Parameters
    ----------
    result_path
        Path where the evaluation results (plots and data files) will be saved.
    nc
        Dictionary containing PyPSA network objects, typically keyed by year or scenario.
        Each network should contain Load, Link, and Generator components with energy data.
    config
        Configuration dictionary containing view settings and chart specifications.
        Must include 'view' key with chart type and other plotting parameters.
    subdir
        Subdirectory name within result_path where outputs will be saved.

    Notes
    -----
    Uses _get_sectoral_fed() to calculate FED with detailed heat mix processing,
    distribution loss accounting, and sector aggregation. Results are exported
    with sector-level disaggregation to show how energy demand is distributed across
    different end-use sectors of the economy.

    See Also
    --------
    _get_sectoral_fed : Core calculation function for final energy demand
    view_demand_fed_total : Export FED aggregated across all sectors
    """
    fed = _get_sectoral_fed(nc)
    exporter = Exporter(statistics=[fed], view_config=config["view"])
    exporter.export(result_path, subdir=subdir)

view_demand_fed_total(result_path, nc, config, subdir='evaluation')

Evaluate and export total final energy demand (FED) aggregated across all sectors.

This function calculates and exports final energy demand aggregated across transport, industry, agriculture, and household & service sectors. The output is organized by bus_carrier (heat bus types and energy carriers) to show the total energy demand across the entire energy system without sector-level disaggregation.

Parameters:

Name Type Description Default
result_path str | pathlib.Path

Path where the evaluation results (plots and data files) will be saved.

 required
nc pypsa.NetworkCollection

Dictionary containing PyPSA network objects, typically keyed by year or scenario. Each network should contain Load, Link, and Generator components with energy data.

 required
config dict

Configuration dictionary containing view settings and chart specifications. Must include 'view' key with chart type and other plotting parameters.

 required
subdir str | pathlib.Path

Subdirectory name within result_path where outputs will be saved.

 'evaluation'
Notes

Uses _get_sectoral_fed() to calculate FED with detailed heat mix processing and distribution loss accounting. Results are exported with bus_carrier as the primary plot category, showing the total energy demand pattern across all carriers without sector-level breakdown.

See Also

_get_sectoral_fed : Core calculation function for final energy demand view_demand_fed_sectoral : Export FED with sector-level disaggregation

Source code in evals/views/demand.py 
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
def view_demand_fed_total(
    result_path: str | Path,
    nc: NetworkCollection,
    config: dict,
    subdir: str | Path = "evaluation",
) -> None:
    """
    Evaluate and export total final energy demand (FED) aggregated across all sectors.

    This function calculates and exports final energy demand aggregated across transport,
    industry, agriculture, and household & service sectors. The output is organized by
    bus_carrier (heat bus types and energy carriers) to show the total energy demand
    across the entire energy system without sector-level disaggregation.

    Parameters
    ----------
    result_path
        Path where the evaluation results (plots and data files) will be saved.
    nc
        Dictionary containing PyPSA network objects, typically keyed by year or scenario.
        Each network should contain Load, Link, and Generator components with energy data.
    config
        Configuration dictionary containing view settings and chart specifications.
        Must include 'view' key with chart type and other plotting parameters.
    subdir
        Subdirectory name within result_path where outputs will be saved.

    Notes
    -----
    Uses _get_sectoral_fed() to calculate FED with detailed heat mix processing and
    distribution loss accounting. Results are exported with bus_carrier as the primary
    plot category, showing the total energy demand pattern across all carriers without
    sector-level breakdown.

    See Also
    --------
    _get_sectoral_fed : Core calculation function for final energy demand
    view_demand_fed_sectoral : Export FED with sector-level disaggregation
    """
    fed = _get_sectoral_fed(nc)
    exporter = Exporter(statistics=[fed], view_config=config["view"])
    exporter.export(result_path, subdir=subdir)

view_demand_heat_system(result_path, nc, config, subdir='evaluation')

Evaluate and export heat system energy flows with carrier-focused visualization.

This function analyzes the complete heat system by combining energy input for heat production from Link components with direct heat generation from Generator components (specifically solar thermal). Unlike view_demand_heat(), this function organizes results by carrier rather than bus_carrier to provide insight into the energy sources feeding the heat system. Solar heat generation is specifically aggregated and labeled for clear identification in the output.

Parameters:

Name Type Description Default
result_path str | pathlib.Path

Path where the evaluation results (plots and data files) will be saved.

 required
nc pypsa.NetworkCollection

Dictionary containing PyPSA network objects, typically keyed by year or scenario. Each network should contain Link and Generator components with energy data.

 required
config dict

Configuration dictionary containing view settings and chart specifications. Must include 'view' key with chart type and other plotting parameters.

 required
subdir str | pathlib.Path

Subdirectory name within result_path where outputs will be saved.

 'evaluation'
Notes

The function combines two data sources: 1. Energy input for heat production from Link components (from get_energy_for_heat_production) 2. Solar heat generation from Generator components, aggregated as "solar heat"

Key differences from view_demand_heat(): - Results organized by carrier (energy source) rather than bus_carrier (heat bus type) - Generator supply specifically renamed to "solar heat" for clarity - Index levels swapped to prioritize carrier information during visualization - Simplified chart configuration without specific pivot settings

This view is particularly useful for understanding the overall energy source mix feeding the heat system across all heat bus types.

Source code in evals/views/demand.py 
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
def view_demand_heat_system(
    result_path: str | Path,
    nc: NetworkCollection,
    config: dict,
    subdir: str | Path = "evaluation",
) -> None:
    """
    Evaluate and export heat system energy flows with carrier-focused visualization.

    This function analyzes the complete heat system by combining energy input for heat
    production from Link components with direct heat generation from Generator components
    (specifically solar thermal). Unlike view_demand_heat(), this function organizes
    results by carrier rather than bus_carrier to provide insight into the energy
    sources feeding the heat system. Solar heat generation is specifically aggregated
    and labeled for clear identification in the output.

    Parameters
    ----------
    result_path
        Path where the evaluation results (plots and data files) will be saved.
    nc
        Dictionary containing PyPSA network objects, typically keyed by year or scenario.
        Each network should contain Link and Generator components with energy data.
    config
        Configuration dictionary containing view settings and chart specifications.
        Must include 'view' key with chart type and other plotting parameters.
    subdir
        Subdirectory name within result_path where outputs will be saved.

    Notes
    -----
    The function combines two data sources:
    1. Energy input for heat production from Link components (from get_energy_for_heat_production)
    2. Solar heat generation from Generator components, aggregated as "solar heat"

    Key differences from view_demand_heat():
    - Results organized by carrier (energy source) rather than bus_carrier (heat bus type)
    - Generator supply specifically renamed to "solar heat" for clarity
    - Index levels swapped to prioritize carrier information during visualization
    - Simplified chart configuration without specific pivot settings

    This view is particularly useful for understanding the overall energy source mix
    feeding the heat system across all heat bus types.
    """
    fed_for_heat = get_energy_for_heat_production(nc)
    # swap index levels to keep carrier information during plotting
    fed_for_heat = fed_for_heat.swaplevel(DataModel.CARRIER, DataModel.BUS_CARRIER)
    fed_for_heat.index.names = DataModel.YEAR_IDX_NAMES

    generator_supply = collect_myopic_statistics(
        nc,
        statistic="supply",
        comps="Generator",
        bus_carrier=BusCarrier.heat_buses(),
    ).pipe(rename_aggregate, "solar heat")

    exporter = Exporter(
        statistics=[fed_for_heat, generator_supply],
        view_config=config["view"],
    )

    exporter.export(result_path, subdir=subdir)

view_demand_heat_total(result_path, nc, config, subdir='evaluation')

Evaluate and export energy required for heat production and generation.

This function analyzes the energy input mix used for heat production by combining data from both link components (for heat production technologies like heat pumps, boilers) and generator components (for direct heat generation). Results are grouped by bus_carrier rather than carrier to show the input energy carrier mix for each type of heat bus. The output includes charts and Excel exports showing the energy balance for heat production across different heat technologies and carriers.

Parameters:

Name Type Description Default
result_path str | pathlib.Path

Path where the evaluation results (plots and data files) will be saved.

 required
nc pypsa.NetworkCollection

Dictionary containing PyPSA network objects, typically keyed by year or scenario. Each network should contain Link and Generator components with energy data.

 required
config dict

Configuration dictionary containing view settings and chart specifications. Must include 'view' key with chart type and other plotting parameters.

 required
subdir str | pathlib.Path

Subdirectory name within result_path where outputs will be saved.

 'evaluation'
Notes

The function combines two data sources: 1. Energy input for heat production from Link components (from get_energy_for_heat_production) 2. Direct heat supply from Generator components connected to heat buses

The data is organized by bus_carrier (heat bus types) rather than the usual carrier grouping to provide insight into the energy mix feeding different heat systems (urban central, urban decentral, rural heat). Index levels are swapped between carrier and bus_carrier to facilitate plotting with the specified chart class.

Source code in evals/views/demand.py 
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
def view_demand_heat_total(
    result_path: str | Path,
    nc: NetworkCollection,
    config: dict,
    subdir: str | Path = "evaluation",
) -> None:
    """
    Evaluate and export energy required for heat production and generation.

    This function analyzes the energy input mix used for heat production by combining
    data from both link components (for heat production technologies like heat pumps,
    boilers) and generator components (for direct heat generation). Results are grouped
    by bus_carrier rather than carrier to show the input energy carrier mix for each
    type of heat bus. The output includes charts and Excel exports showing the energy
    balance for heat production across different heat technologies and carriers.

    Parameters
    ----------
    result_path
        Path where the evaluation results (plots and data files) will be saved.
    nc
        Dictionary containing PyPSA network objects, typically keyed by year or scenario.
        Each network should contain Link and Generator components with energy data.
    config
        Configuration dictionary containing view settings and chart specifications.
        Must include 'view' key with chart type and other plotting parameters.
    subdir
        Subdirectory name within result_path where outputs will be saved.

    Notes
    -----
    The function combines two data sources:
    1. Energy input for heat production from Link components (from get_energy_for_heat_production)
    2. Direct heat supply from Generator components connected to heat buses

    The data is organized by bus_carrier (heat bus types) rather than the usual carrier
    grouping to provide insight into the energy mix feeding different heat systems
    (urban central, urban decentral, rural heat). Index levels are swapped between
    carrier and bus_carrier to facilitate plotting with the specified chart class.
    """
    fed_for_heat = get_energy_for_heat_production(nc)

    generator_supply = collect_myopic_statistics(
        nc,
        statistic="supply",
        comps="Generator",
        bus_carrier=BusCarrier.heat_buses(),
    )
    # swap index levels to keep carrier information during plotting
    generator_supply = generator_supply.swaplevel(
        DataModel.CARRIER, DataModel.BUS_CARRIER
    )
    generator_supply.index.names = DataModel.YEAR_IDX_NAMES

    exporter = Exporter(
        statistics=[fed_for_heat, generator_supply],
        view_config=config["view"],
    )

    exporter.defaults.plot_category = DataModel.BUS_CARRIER
    exporter.defaults.pivot_index = [
        DataModel.YEAR,
        DataModel.LOCATION,
        DataModel.BUS_CARRIER,
    ]

    exporter.export(result_path, subdir=subdir)