carbatpy.models.coupled.heat_pump_comp

Heat pump with two two-tank storages (component-based formulation, comp.py).

Created on Sun Jan 4 11:06:10 2026

Author: atakan University of Duisburg-Essen, Germany

Within the Priority Programme: “Carnot Batteries: Inverse Design from Markets to Molecules” (SPP 2403) https://www.uni-due.de/spp2403/ https://git.uni-due.de/spp-2403/residuals_weather_storage

Attributes

dir_name_out

Functions

deep_merge(→ dict)

Recursively merge two nested dictionaries.

resolve_config(→ dict)

Create an isolated configuration and apply optional overrides.

heat_pump(dir_name, **kwargs)

Compute a heat pump with two two-tank storages.

Module Contents

carbatpy.models.coupled.heat_pump_comp.deep_merge(dst: dict, src: dict) → dict[source]

Recursively merge two nested dictionaries.

  • Values from src are written into dst.

  • For nested dicts, merging is done recursively.

  • Non-dict values overwrite the value in dst.

Notes

  • dst is modified in-place.

  • src is not modified.

Parameters:

  • dst (dict) – Target dictionary; will be updated in-place.

  • src (dict) – Source dictionary; its values are merged into dst.

Returns:

The updated dst dictionary (same reference).

Return type:

dict

carbatpy.models.coupled.heat_pump_comp.resolve_config(dir_or_dict, override=None) → dict[source]

Create an isolated configuration and apply optional overrides.

  • If dir_or_dict is a path, load the YAML configuration.

  • If dir_or_dict is a dict, use a deep copy of it.

  • Overrides are deep-merged into the base configuration.

  • Always returns a new, isolated structure (no references to global defaults).

Parameters:

  • dir_or_dict (str or dict) – Path to a YAML file or a configuration dictionary.

  • override (dict, optional) – Dictionary with parameters to override (e.g., for optimization).

Returns:

Fully isolated and merged configuration structure.

Return type:

dict

carbatpy.models.coupled.heat_pump_comp.heat_pump(dir_name, **kwargs)[source]

Compute a heat pump with two two-tank storages.

Component-based formulation that builds an isolated, merged configuration from a base (file or dict), computes the component sequence (start, compressor, condenser, throttle, evaporator), and returns COP, outputs, warnings, and optionally a combined plot.

Key Properties

  • No in-place modifications to CB_DEFAULTS or externally provided configurations.

  • Configurations are handled in isolation (deepcopy/recursive merges).

  • Matplotlib Figure/Axes are consistently passed to all plot calls so that the entire cycle is drawn on the same axes.

param dir_name:

Path to a YAML configuration file or a configuration dict.

type dir_name:

str or dict

param config:

Overrides to the base configuration (e.g., for optimization). Passed via **kwargs.

type config:

dict, optional

param verbose:

If True, print additional information. Passed via **kwargs. Default is False.

type verbose:

bool, optional

param plotting:

If True, create a combined T-H_dot plot. Passed via **kwargs. Default is False.

type plotting:

bool, optional

returns:

Result dictionary with the following keys:

  • "COP" (float): Coefficient of performance of the heat pump.

  • "output" (dict): Component outputs and the configuration used (accessible via "config" key).

  • "warnings" (dict): Warnings per component and additional items such as "pressure_ratio".

  • "figure" (matplotlib.figure.Figure or None): Figure object if plotting=True, otherwise None.

  • "axes" (matplotlib.axes.Axes or None): Axes object if plotting=True, otherwise None.

  • "costs" (float or dict): Aggregate cost metric from components, computed via cb.orc_comp.all_costs().

rtype:

dict

raises KeyError:

If the compressor power is missing in the configuration (process.fixed.compressor.power).

raises ValueError:

If input parameters are outside valid ranges.

See also

compute_orc_carnot_battery

Compute ORC cycle

load_config

Load configuration from YAML file

Notes

The coefficient of performance (COP) is calculated as:

\[COP = \frac{\dot{Q}_{cond}}{W_{comp}}\]

where \(\dot{Q}_{cond}\) is the condenser heat output and \(W_{comp}\) is the compressor work input.

Component Sequence

The heat pump cycle follows this sequence:

  1. Start: Initialize working fluid state

  2. Compressor: Compress refrigerant to high pressure

  3. Condenser: Reject heat to hot storage tank

  4. Throttle: Expand refrigerant to low pressure (isenthalpic)

  5. Evaporator: Absorb heat from cold storage tank

Configuration Priority

Configurations are merged in the following order (later overrides earlier):

  1. CB_DEFAULTS (base defaults)

  2. Configuration from dir_name (file or dict)

  3. User-provided config parameter (via kwargs)

Examples

Basic usage with configuration file:

>>> result = heat_pump("config/hp_default.yaml", verbose=True)
>>> print(f"COP: {result['COP']:.2f}")
COP: 3.45

With configuration dict and plotting:

>>> config_dict = {
...     "working_fluid": {"name": "R134a"},
...     "process": {"fixed": {"compressor": {"power": 5000}}}
... }
>>> result = heat_pump(config_dict, plotting=True)
>>> result['figure'].savefig('heat_pump_cycle.png')

With configuration overrides for optimization:

>>> result = heat_pump(
...     "config/hp_default.yaml",
...     config={
...         "components": {
...             "compressor": {"eta_is": 0.85},
...             "evaporator": {"delta_T": 5.0}
...         }
...     }
... )
>>> print(f"Optimized COP: {result['COP']:.2f}")
Optimized COP: 3.52

Access component outputs:

>>> result = heat_pump("config.yaml")
>>> compressor_output = result['output']['compressor']
>>> print(f"Discharge temp: {compressor_output['T_out']:.1f} K")
Discharge temp: 323.5 K
carbatpy.models.coupled.heat_pump_comp.dir_name_out = '\\io-hp-data.yaml'[source]