carbatpy.models.coupled.orc_comp
================================

.. py:module:: carbatpy.models.coupled.orc_comp

.. autoapi-nested-parse::

   Created on Sun Jan  4 11:28:38 2026

   @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.orc_comp.dir_name_m


Functions
---------

.. autoapisummary::

   carbatpy.models.coupled.orc_comp.orc
   carbatpy.models.coupled.orc_comp.all_costs


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

.. py:function:: orc(dir_name, cop, q_dot_high, **kwargs)

   Compute an Organic Rankine Cycle (ORC) for a Carnot battery.

   The ORC uses an isolated configuration (from file or dict). The evaporator
   heat input ``q_dot_high`` and the COP of the preceding charging heat pump
   are prescribed; the working fluid mass flow is determined accordingly.

   Components
   ----------
   - Pump
   - Evaporator
   - Expander
   - Condenser to ambient (condenser_sur)
   - Main condenser

   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 cop: COP of the preceding charging heat pump.
   :type cop: float
   :param q_dot_high: Prescribed heat flow rate to the evaporator in watts [W].
   :type q_dot_high: float
   :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 cycle plot. Passed via ``**kwargs``.
                    Default is False.
   :type plotting: bool, optional

   :returns: Result dictionary with the following keys:

             - ``"eta_th"`` (float): Thermal efficiency defined as net electric
               power divided by evaporator heat input.
             - ``"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 required configuration entries are missing (e.g.,
       ``working_fluid.p_high``).
   :raises ValueError: If input parameters are outside valid ranges.

   .. seealso::

      :obj:`compute_hp_carnot_battery`
          Compute heat pump cycle

      :obj:`load_config`
          Load configuration from YAML file

   .. rubric:: Notes

   The thermal efficiency is calculated as:

   .. math::

       \eta_{th} = \frac{W_{net}}{\dot{Q}_{evap}}

   where :math:`W_{net}` is the net electrical power output and
   :math:`\dot{Q}_{evap}` is the heat input to the evaporator.

   The configuration is processed in the following order:

   1. Load base configuration from ``dir_name``
   2. Apply ``CB_DEFAULTS``
   3. Merge user-provided ``config`` overrides
   4. Validate required parameters

   .. rubric:: Examples

   Basic usage with configuration file:

   >>> result = compute_orc_carnot_battery(
   ...     dir_name="config/orc_default.yaml",
   ...     cop=3.5,
   ...     q_dot_high=10000.0,
   ...     verbose=True
   ... )
   >>> print(f"Thermal efficiency: {result['eta_th']:.2%}")
   Thermal efficiency: 12.50%

   With configuration dict and plotting:

   >>> config_dict = {
   ...     "working_fluid": {"name": "R245fa", "p_high": 2e6},
   ...     "components": {"expander": {"eta_is": 0.85}}
   ... }
   >>> result = compute_orc_carnot_battery(
   ...     dir_name=config_dict,
   ...     cop=3.2,
   ...     q_dot_high=15000.0,
   ...     plotting=True
   ... )
   >>> result['figure'].savefig('orc_cycle.png')

   With configuration overrides:

   >>> result = compute_orc_carnot_battery(
   ...     dir_name="config/orc_default.yaml",
   ...     cop=3.5,
   ...     q_dot_high=10000.0,
   ...     config={"components": {"pump": {"eta_is": 0.75}}}
   ... )


.. py:function:: all_costs(components_all, verbose)

.. py:data:: dir_name_m
   :value: '\\io-orc-data.yaml'