carbatpy.models.coupled.heat_pump_comp ====================================== .. py:module:: carbatpy.models.coupled.heat_pump_comp .. autoapi-nested-parse:: 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 ---------- .. autoapisummary:: carbatpy.models.coupled.heat_pump_comp.dir_name_out Functions --------- .. autoapisummary:: carbatpy.models.coupled.heat_pump_comp.deep_merge carbatpy.models.coupled.heat_pump_comp.resolve_config carbatpy.models.coupled.heat_pump_comp.heat_pump Module Contents --------------- .. py:function:: deep_merge(dst: dict, src: dict) -> dict 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. .. rubric:: Notes - dst is modified in-place. - src is not modified. :param dst: Target dictionary; will be updated in-place. :type dst: dict :param src: Source dictionary; its values are merged into dst. :type src: dict :returns: The updated dst dictionary (same reference). :rtype: dict .. py:function:: resolve_config(dir_or_dict, override=None) -> dict 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). :param dir_or_dict: Path to a YAML file or a configuration dictionary. :type dir_or_dict: str or dict :param override: Dictionary with parameters to override (e.g., for optimization). :type override: dict, optional :returns: Fully isolated and merged configuration structure. :rtype: dict .. py:function:: heat_pump(dir_name, **kwargs) 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. .. seealso:: :obj:`compute_orc_carnot_battery` Compute ORC cycle :obj:`load_config` Load configuration from YAML file .. rubric:: Notes The coefficient of performance (COP) is calculated as: .. math:: COP = \frac{\dot{Q}_{cond}}{W_{comp}} where :math:`\dot{Q}_{cond}` is the condenser heat output and :math:`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) .. rubric:: 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 .. py:data:: dir_name_out :value: '\\io-hp-data.yaml'