scml.std.ufun
=============

.. py:module:: scml.std.ufun


Classes
-------

.. autoapisummary::

   scml.std.ufun.UFunLimit
   scml.std.ufun.UtilityInfo
   scml.std.ufun.StdUFun


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

.. py:class:: UFunLimit

   Bases: :py:obj:`tuple`


   .. py:attribute:: utility


   .. py:attribute:: input_quantity


   .. py:attribute:: input_price


   .. py:attribute:: output_quantity


   .. py:attribute:: output_price


   .. py:attribute:: exogenous_input_quantity


   .. py:attribute:: exogenous_input_price


   .. py:attribute:: exogenous_output_quantity


   .. py:attribute:: exogenous_output_price


   .. py:attribute:: inventory_input


   .. py:attribute:: inventory_output


   .. py:attribute:: producible


.. py:class:: UtilityInfo

   .. py:attribute:: producible
      :type:  int


   .. py:attribute:: total_input
      :type:  int


   .. py:attribute:: total_output
      :type:  int


   .. py:attribute:: shortfall_quantity
      :type:  int


   .. py:attribute:: shortfall_penalty
      :type:  float


   .. py:attribute:: remaining_quantity
      :type:  int


   .. py:attribute:: disposal_cost
      :type:  float


   .. py:attribute:: storage_cost
      :type:  float


   .. py:attribute:: utility
      :type:  float


.. py:class:: StdUFun(ex_pin: int, ex_qin: int, ex_pout: int, ex_qout: int, input_product: int, input_agent: bool, output_agent: bool, production_cost: float, disposal_cost: float, storage_cost: float, shortfall_penalty: float, input_penalty_scale: float | None, output_penalty_scale: float | None, storage_penalty_scale: float | None, n_input_negs: int, n_output_negs: int, current_step: int, agent_id: str | None, time_range: tuple[int, int], inventory_in: int = 0, inventory_out: int = 0, input_qrange: tuple[int, int] = (0, 0), input_prange: tuple[int, int] = (0, 0), output_qrange: tuple[int, int] = (0, 0), output_prange: tuple[int, int] = (0, 0), force_exogenous: bool = True, n_lines: int = 10, normalized: bool = False, current_balance: int | float = float('inf'), suppliers: set[str] = set(), consumers: set[str] = set(), perishable=True, **kwargs)

   Bases: :py:obj:`scml.oneshot.ufun.OneShotUFun`


   Calculates the utility function of a list of contracts or offers.

   :param force_exogenous: Is the agent forced to accept exogenous contracts
                           given through `ex_*` arguments?
   :param ex_pin: total price of exogenous inputs for this agent
   :param ex_qin: total quantity of exogenous inputs for this agent
   :param ex_pout: total price of exogenous outputs for this agent
   :param ex_qout: total quantity of exogenous outputs for this agent.
   :param cost: production cost of the agent.
   :param disposal_cost: disposal cost per unit of input/output.
   :param shortfall_penalty: penalty for failure to deliver one unit of output.
   :param input_agent: Is the agent an input agent which means that its input
                       product is the raw material
   :param output_agent: Is the agent an output agent which means that its output
                        product is the final product
   :param n_lines: Number of production lines. If None, will be read through the AWI.
   :param input_product: Index of the input product. If None, will be read through
                         the AWI
   :param input_qrange: A 2-int tuple giving the range of input quantities negotiated.
                        If not given will be read through the AWI
   :param input_prange: A 2-int tuple giving the range of input unit prices negotiated.
                        If not given will be read through the AWI
   :param output_qrange: A 2-int tuple giving the range of output quantities negotiated.
                         If not given will be read through the AWI
   :param output_prange: A 2-int tuple giving the range of output unit prices negotiated.
                         If not given will be read through the AWI
   :param n_input_negs: How many input negotiations are allowed. If not given, it
                        will be the number of suppliers as given by the AWI
   :param n_output_negs: How many output negotiations are allowed. If not given, it
                         will be the number of consumers as given by the AWI
   :param current_step: Current simulation step. Needed only for `ufun_range`
                        when returning best outcomes
   :param normalized: If given the values returned by `from_*`, `utility_range`
                      and `__call__` will all be normalized between zero and one.

   Remarks:
       - The utility function assumes that the agent will have to pay for
         all its input products but will receive money only for the output
         products it could generate and sell.
       - The utility function respects production capacity (n. lines). The
         agent cannot produce more than the number of lines it has.
       - disposal cost is paid for items bought but not produced only. Items
         consumed in production (i.e. sold) are not counted.