carbatpy.utils.cost_calculation
===============================

.. py:module:: carbatpy.utils.cost_calculation

.. autoapi-nested-parse::

   Calculating costs for equipment

   SI units input is only implemented for the Towler method and the limits are
   checked now for Towler! (BA 2025-08-14/15)

   Created on Wed Jul 31 13:59:25 2024

   @author: Mina Anton, Majid Zarif



Attributes
----------

.. autoapisummary::

   carbatpy.utils.cost_calculation.DIR
   carbatpy.utils.cost_calculation.xl_data
   carbatpy.utils.cost_calculation.Eco


Classes
-------

.. autoapisummary::

   carbatpy.utils.cost_calculation.CAP_methods


Functions
---------

.. autoapisummary::

   carbatpy.utils.cost_calculation.get_cost_inst


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

.. py:data:: DIR

.. py:data:: xl_data

.. py:class:: CAP_methods

   .. py:attribute:: Couper_columns


   .. py:attribute:: Couper_xl_data


   .. py:attribute:: Turton_columns


   .. py:attribute:: Turton_xl_data


   .. py:attribute:: Towler_columns


   .. py:attribute:: Towler_xl_data


   .. py:attribute:: Towler_df


   .. py:attribute:: Towler_unit_col_index


   .. py:attribute:: CEPCI_columns


   .. py:attribute:: CEPCI_xl_data


   .. py:attribute:: warn


   .. py:method:: Towler_Method(Comp_dict, verbose=False, Desired_year=None)

      Cost estimation according to Towler and Gavin (2012).

      Calculates costs based on "Chemical engineering design: principles,
      practice and economics of plant and process design".

      The estimation follows the power-law relation:

      .. math::
          C_e = a + b \cdot S^n



      :param Comp_dict: Dictionary containing variables for the cost estimate.
                        Example::

                            {
                                "Category": "Compressor",
                                "Component Name": "hydrogen compressor",
                                "Component Attribute": 1000
                            }
      :type Comp_dict: dict
      :param CI: Capital investment of the investigated component.
      :type CI: float
      :param S: Capacity of the investigated component.
      :type S: float
      :param n: Cost exponent (typically :math:`n < 1` to account for economies of scale).
      :type n: float
      :param a: Constant base value for known device costs.
      :type a: float
      :param b: Proportionality constant for device costs.
      :type b: float
      :param verbose: If True, prints values and explanations. The default is False.
      :type verbose: bool, optional
      :param Desired_year: Target year for the cost index relative to the current year.
                           If None, the current year index is used.
      :type Desired_year: float, optional

      :raises ValueError: If the component name is not found in the Towler method database.

      :returns: The installed cost of the component, adjusted for inflation,
                operational pressure, and material of construction.
      :rtype: float

      .. rubric:: Notes

      SI-unit input is implemented and limits are checked. (Updated: 2025-08-15)



   .. py:method:: get_values_by_name(name_value, columns=None, df=None)

      Retrieve the values of specific columns for the row matching a given 'name' value.

      :param name_value: The value to search for in the 'name' column.
      :type name_value: str
      :param columns: List of column names whose values should be returned.
                      Defaults to ["S_lower", "S_upper"] if not provided.
      :type columns: list of str, optional
      :param df: DataFrame in which to search. Defaults to self.Towler_df if not provided.
      :type df: pandas.DataFrame, optional

      :returns: A dictionary mapping each requested column name to its value for the matching row,
                or None if no matching row is found.
      :rtype: dict or None

      .. rubric:: Notes

      - If multiple rows have the same 'name', only the first match is returned.
      - This method is flexible and can be used with any DataFrame and column list.



   .. py:method:: check_value_within_limits(name_value, value, verbose, lower_col='S_lower', upper_col='S_upper', df=None, error=False)

      Check if a given value lies within predefined limits from a DataFrame entry.

      :param name_value: The value to search for in the 'name' column of the DataFrame.
      :type name_value: str
      :param value: The numeric value to be checked.
      :type value: float
      :param lower_col: Column name for the lower limit. Default is "S_lower".
      :type lower_col: str, optional
      :param upper_col: Column name for the upper limit. Default is "S_upper".
      :type upper_col: str, optional
      :param df: DataFrame to search in. Defaults to self.Towler_df.
      :type df: pandas.DataFrame, optional
      :param error: If True, raises a ValueError when the value is out of range.
                    If False, issues a UserWarning instead.
      :type error: bool, optional

      :returns: True if the value is within limits or if no limits are defined.
                False if the value is out of range.
      :rtype: bool

      .. rubric:: Notes

      - If the limits are missing or NaN, the check passes automatically.
      - If multiple rows match `name_value`, only the first is used.



.. py:function:: get_cost_inst() -> CAP_methods

   Return module-level CAP_methods singleton (lazy init).


.. py:data:: Eco