=============
Resource Calc
=============

The Resource Calc algorithm generates a list of resource functions for
the current schedule. These functions specify the costs of possible
vendor orders, and the respective increases in the schedule score; for
more information, see the "Resource Functions" file.


-= Input and output =-

Input: Current schedule, vendor description
Output: List of resource functions


-= Main steps =-

The algorithm includes two subroutines, Cost Calc and Score Calc,
which construct the functions for a given event and property. Cost
Calc outputs the cost function, which is the dependency of the order
cost on the number of items. Score Calc outputs the score function,
which is the dependency of the score increase on the number of items.

The Score Calc subroutine calls the Mean-PLF procedure, which should
be part of the probabilistic library. This procedure computes the mean
y-value of an uncertain piece-linear function for a given x-value.


- Cost Calc -

Input: 
  Property: Service or combined property
  Duration: Duration of the related event
  Max-Items: Limit on the number of ordered items
Output:
  Piece-linear function with the domain [1 .. Max-Items],
    which is the dependency of the cost on the number of items

Best-Cost = +Infinity
For each Item-Type that matches Property:
  For each known Vendor:
    If Vendor offers Item-Type at a known cost:
      Let Cost be the cost for one item of Item-Type for Duration
      If Cost < Best-Cost, then Cost = Best-Cost
If Best-Cost == +Infinity, then return "None"
If Max-Items == 1,
  then return a piece-linear function with one point: (1, Best-Cost)
Else, return a piece-linear function that includes two inflection points:
  (1, Best-Cost) and (Max-Items, Max-Items * Best-Cost)


- Score Calc -

Input:
  Pref: Piece-linear preference function for a given property
  Weight: "Overall weight" of this preference, which is the
    product of the preference weight and event weight
  Current-Items: Number of items already available in the room
  Max-Items: Limit on the number of ordered items
Output:
  Piece-linear function with the domain [1 .. Max-Items],
    which is the dependency of the score increase on the number of items

Create piece-linear Score-Function, which initially has no points
Current-Score = Mean-PLF(Pref, Current-Items)
  Comment: Mean-PLF procedure returns the mean y-value
           of Pref for x-value equal to Current-Items
Add the following point to Score-Function:
  x = 1
  y = Weight * (Mean-PLF(Pref, Current-Items + 1) - Current-Score)
If Max-Times == 1, then return the resulting one-point Score-Function
For every inflection point Inflection-X of Pref in the interval
    [Current-Items + 2 .. Current-Items + Max-Items - 1]:
  Add the following point to Cost-Function:
    x = Inflection-X - Current-Items
    y = Weight * (Mean-PLF(Pref, Inflection-X) - Current-Score)
      Comment: If Pref includes multiple PLFs with probabilities,
               we consider inflection points of all these PLFs
Add the following point to Score-Function:
  x = Max-Items
  y = Weight * (Mean-PLF(Pref, Current-Items + Max-Items) - Current-Score)
Return Score-Function


- Resource Calc -

Create Resource-List, which is initially empty
For every event in the schedule:
  For every service and combined property:
    If the event does not have a preference for this property,
      then go the next iteration of the loop
    Let Pref by the respective preference function
    Let Current-Items be the number of items for this property
      that are already available in the room
        Comment: For a service property, Current-Items is zero;
                 for a combined property, it may not be zero
    If Current-Items corresponds to the maximum of Pref,
      then go to the next iteration of the loop
    Let Best-Items be the smallest number greater than Current-Items
      that corresponds to the maximum of Pref
    Max-Items = Best-Items - Current-Items
    Call the Cost Calc subroutine to construct Cost-Function;
      the arguments for this call are as follows:
        - current property
        - duration of the current event
        - Max-Items
    If Cost-Function is "None," then go to the next iteration of the loop
    Create Function-Pair with the following fields:
      Event id: Current event
      Property: Current property
      Cost function: Cost-Function
      Score function: Call the Score Calc subroutine to construct it;
        the arguments for this call are as follows:
          - Preference function for the current property
          - Product of the scaled weight of this function
              and scaled weight of the current event
          - Current-Items
          - Max-Items
      Add Function-Pair to Resource-List
Return Resource-List


-= Efficiency improvements =-

We can use the following techniques to improve the efficiency of
Resource Calc.

() When loading a conference scenario, the system should pre-compute
the mean values of all uncertain preference functions. That is, for
every uncertain function, it should build a new piece-linear function
that represents its mean y-values for all x-values. If the user later
modifies some uncertain functions, the system should re-compute their
mean values. This technique improves the efficiency of Score Func,
which uses mean values of uncertain preference functions.

() When loading a conference scenario, the system should pre-compute
the maximums of all preference functions. Note that, if a function is
uncertain, the system uses the maximum of the respective mean-value
function. If the user later modifies some functions, the system should
re-compute their maximums. This technique improves the efficiency of
checking whether a given number of items corresponds to the maximum of
the respective preference function.