.. _local-cost-function-chapter:

===================
Local Cost Function
===================

EPOS allows for possible plans of an agent to be *ranked* according to various measures of *cost*. In general, plans of lower cost are considered better, more convenient or more comfortable, whereas plans with higher cost are considered worse, less convenient and more uncomfortable. This *cost* can be generated before execution and by the user, such as plan preference, or it can be generated by the agent and while runtime, such as plan indexes. The function that abstracts this functionality is *local cost function*, :math:`l(\cdot)` as :math:`l \colon \mathbb{R}^{d} \rightarrow \mathbb{R}`. The classes of pre-implemented local cost functions can be found in ``func`` package in the code. Using :ref:`arguments-chapter`, ``localCostFunction`` indicates your choice of the local cost function. In order to create your own global cost function, you can use the ``func.VarCostFunction`` class as the template. For more information about how to log the local cost, check :ref:`logging-chapter` page.

.. _local-cost-function-index:

Index-based Local Cost Function
===============================

This is the simplest form of the local cost function in which the *plan index* indicates the plan cost. In this scenario, if an agent has 10 local plans, they are indexed from 0-9. Recall that the format of the :ref:`input-plans` is as follows:

 *planScore* : *planDimension1*, ... , *planDimensionN*.

In this case, *planScore* is ignored, and the index of the plan is used instead. The plan with lower index is considered better, more convenient or more comfortable. Intuitively, the index local cost function enables *linear* scale of plan "costs".

This function can be set in one of the following ways:

1. either setting ``localCostFunction=INDEX``, or

2. .. code-block:: java
      :caption: config.Configuration.java
      :name: index-configuration-java

      public static PlanCostFunction localCostFunc = new IndexCostFunction();

The exact implementation of the function is given in ``func.IndexCostFunction.java``. It is the subtype of ``PlanCostFunction``.

.. _local-cost-function-discomfort:

Discomfort-based Local Cost Function
====================================

Recall that the *planScore* field in each of the :ref:`input-plans` can have 2 different meanings, depending on the dataset. Discomfort Local Cost Function interprets this score as *discomfort* that should be minimized. 

Depending on the dataset, discomfort can have different meanings. For example in the case of energy usage planning, given that user has multiple alternative plans, the discomfort is how different the alternative plan is to the originally intended one. Also, discomfort can express the distance between citizens' houses and bike stations.

This function can be set in one of the following ways:

1. either setting ``localCostFunction=DISC``, or

2. .. code-block:: java
      :caption: config.Configuration.java
      :name: discomfort-configuration-java

      public static PlanCostFunction localCostFunc = new PlanDiscomfortFunction();

The implementation of this function can be found in ``func.PlanDiscomfortFunction.java``, and it is the subtype of ``PlanCostFunction``.


.. _local-cost-function-preference:

Preference-based Local Cost Function
====================================

Another meaning of the *planScore* field in each of the :ref:`input-plans` is *preference score*. Unlike the :ref:`local-cost-function-index` and :ref:`local-cost-function-discomfort` where the lower value of the score is interpreted as better and more comfortable, this function does the opposite: higher value of the score is better, expresses higher comfort and convenience. Intuitively, the plan with higher *preference score* should be selected.

However, as EPOS is a minimization algorithm, the *preference score* must be converted to a measure that should be minimized, i.e. discomfort. **The assumption that this implementation of the preference cost function makes is that all preference scores are between 0 and 1!** Then, the *preference score* is converted to discomfort as :math:`1 - planScore`.

This function can be set in one of the following ways:

1. either setting ``localCostFunction=PREF``, or

2. .. code-block:: java
      :caption: config.Configuration.java
      :name: preference-configuration-java

      public static PlanCostFunction localCostFunc = new PlanPreferenceFunction();

Depending on the dataset, preference can have different meanings. For example in the case of energy usage planning, given that user has multiple alternative plans, the preference is how comfortable (similar) the alternative plan is to the originally intended one. Or, in the bike-sharing scenario, preference score can abstract the likelihood of choosing certain bike station.

The exact implementation of the function is given in ``func.PreferenceCostFunction.java``. It is the subtype of ``PlanCostFunction``.