carbatpy.models.coupled.cb_comp
===============================

.. py:module:: carbatpy.models.coupled.cb_comp

.. autoapi-nested-parse::

   Calculation of a Carnot Battery (PTES) with two energy storages.


   Created on Tue Aug  5 12:33:52 2025

   @author: atakan
   Universität Duisburg-Essen, Germany

   In the framework of 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.cb_comp.dir_names_both


Functions
---------

.. autoapisummary::

   carbatpy.models.coupled.cb_comp.cb_calc


Module Contents
---------------

.. py:function:: cb_calc(dir_names, **kwargs)

   Runs a Carnot battery model by sequentially simulating a heat pump and an Organic Rankine Cycle (ORC)
   using the provided configuration files or dictionaries.

   The function first executes the heat pump cycle based on the configuration in `dir_names["hp"]`.
   If successful and without warnings, it extracts the relevant thermodynamic conditions and storage states
   to configure and launch the subsequent ORC calculation (using `dir_names["orc"]`).
   Both cycles may accept additional configuration dictionaries (useful for parameter optimization).
   If `plotting` is True, figures for both cycles are generated.

   The overall Carnot battery round-trip efficiency (`rte`) is computed as the product of the heat pump COP
   and the ORC thermal efficiency.

   :param dir_names: A dictionary with keys "hp" (for heat pump) and "orc" (for ORC), each containing
                     either the path to a YAML (or similar) configuration file or a configuration dictionary.
   :type dir_names: dict
   :param \*\*kwargs:
                      Additional keyword arguments. Supported keys:
                          config : dict, optional
                              Dictionary with additional or overriding configuration for the heat pump (`"hp"`) and/or ORC (`"orc"`)
                              in the form {"hp": config_hp_dict, "orc": config_orc_dict}. Useful for optimization or parameter studies.
                          verbose : bool, optional
                              If True, enables verbose output. Default is False.
                          plotting : bool, optional
                              If True, generates diagrams for both the heat pump and ORC cycles.

   :returns: * **rte** (*float*) -- The round-trip efficiency of the Carnot battery (heat pump COP × ORC thermal efficiency);
               returns negative values if warnings occur.
             * **results** (*dict*) -- A dictionary with two entries:

               - ``"hp"``  : results {COP, outputs_hp, warnings_hp, fig_hp, ax_hp}
               - ``"orc"`` : results {eta_th, outputs_orc, warnings_orc, fig_orc, ax_orc}

               Each tuple contains the cycle performance metric, outputs, component warnings, and (optionally) plots.

   .. rubric:: Notes

   This function calls both the heat pump and ORC functions in sequence, using outputs from the heat pump
   (such as working fluid composition and storage temperatures) to configure the ORC run. It is suitable
   for integrating the full Carnot battery workflow, either for direct calculations, sensitivity studies,
   or optimization routines.

   If component warnings deviate from zero for either cycle, the function will print diagnostic messages
   (if ``verbose`` is True) and return a negative code for ``rte``.

   .. rubric:: Examples

   >>> dir_names = {"hp": "heat_pump_config.yaml", "orc": "orc_config.yaml"}
   >>> rte, results = cb_calc(dir_names, config={"hp": hp_opt_config, "orc": orc_opt_config}, plotting=True)


.. py:data:: dir_names_both