Package org.powertac.common

Class TariffEvaluationHelper

java.lang.Object
org.powertac.common.TariffEvaluationHelper
public class TariffEvaluationHelper
extends Object
Probe object that can be used by customer models and other players to generate cost estimates for tariffs, including a risk-adjusted estimates of the actual cost of variable-rate tariffs. There are four values for a variable-rate tariff that must be combined to generate an estimate: the broker's claim of the expectedMean price, the brokers commitment to a maxValue of the price, the actual experienced realizedPrice, and the amount of power that has been sold through the tariff. The assumption is that the actual realizedPrice would be more predictive for a tariff with a more substantial price history (large amount of power sold). Note that some of the data needed to estimate price comes from the Tariff's Rates, which may apply at certain times and/or under certain tier threshold conditions, and some comes from the Tariff itself. The price estimate is generated as
   alpha * (wtExpected * expectedMean + wtMax * maxValue)
     + (1 - alpha) * realizedPrice
where alpha = 1 - wtRealized * (1 - 1 / (1 + totalKWh / soldThreshold)). In the case where multiple variable Rates apply, the values of expectedMean and maxValue are the usage-weighted means of the corresponding values from the individual Rates. Usage: A Customer may need to evaluate multiple tariff offerings by estimating cost over a week or more of 1-hour timeslots. Tier usage is computed over a 24-hour period. Therefore, the recommended usage is to create a single instance of this class for each customer model, and re-initialize it for each tariff. Therefore, only a default constructor is provided, along with an init() method that clears out state and optionally sets parameter values. Evalution of time-of-use rates depends on being able to compute the hour of the day for some arbitrary offset. This functionality depends on the Joda Time "default time zone" being set to DateTimeZone.UTC. This normally happens in the TimeService, but may also need to be done in test code.
Author:
John Collins

  • Constructor Details

  • Method Details

    • init

      public void init​(double wtExpected, double wtMax, double wtRealized, double soldThreshold)
      Initializes, setting parameters, then normalize the weights for expectedMean and maxValue.

    • init

      public void init()
      Initializes, without changing parameter settings

    • initializeCostFactors

      public void initializeCostFactors​(double wtExpected, double wtMax, double wtRealized, double soldThreshold)
      Initializes cost factors and normalizes

    • initializeRegulationFactors

      public void initializeRegulationFactors​(double expectedCurtailment, double expectedDischarge, double expectedDownReg)
      Initializes regulation factors. Applicable only for tariffs with RegulationRates. See Section 4.1.1 of the spec for details, especially Eq. 5. Signs are from the standpoint of the customer -- expectedCurtailment and expectedDischarge are negative, expectedDownReg is positive. If this method is not called, default values are zero for all factors.

    • initializeRegulationDiscount

      public void initializeRegulationDiscount​(double upregHalf, double upregSlope, double downregHalf, double downregSlope)
      Initializes regulation rate discount factors. Applicable only for tariffs with RegulationRates.

    • getMarketBootstrapData

      public MarketBootstrapData getMarketBootstrapData()
      Retrieves the market bootstrap data from the Competition. Needed to discount regulation rates.

    • estimateCost

      public double estimateCost​(Tariff tariff, double[] usage, org.joda.time.Instant start, boolean includePeriodicCharge)
      Estimate the total cost of buying the given amounts of power from the given tariff, starting in the timeslot identified by startIndex. Payments include usage charges, and periodic payments just in case includePeriodicCharge is true. They do not include signup or withdrawal charges. Note that there is a strong assumption that the projected usage is for a single customer, not the total population in some model. This assumption is embedded in the structure of usage tiers in the tariff.

    • estimateCost

      public double estimateCost​(Tariff tariff, double[] usage, boolean includePeriodicCharge)
      Estimate cost for a profile starting in the next timeslot

    • estimateCost

      public double estimateCost​(Tariff tariff, double[] usage, org.joda.time.Instant start)
      Returns aggregate estimated cost, including periodic charges

    • estimateCost

      public double estimateCost​(Tariff tariff, double[] usage)
      Returns aggregate estimated cost, including periodic charges, starting in the next timeslot.

    • estimateCostArray

      public double[] estimateCostArray​(Tariff tariff, double[] usage, boolean includePeriodicCharge)
      Returns the cost estimate in the form of an array of the same shape as the usage vector. Each element of the result corresponds to the corresponding element of the usage array. Periodic charges are included just in case includePeriodicCharge is true.

    • estimateCostArray

      public double[] estimateCostArray​(Tariff tariff, double[] usage)
      Returns a cost estimate in array form, including periodic charges.

    • getWtExpected

      public double getWtExpected()
      Parameter access

    • getNormWtExpected

      public double getNormWtExpected()

    • setWtExpected

      public void setWtExpected​(double wt)

    • getWtMax

      public double getWtMax()

    • getNormWtMax

      public double getNormWtMax()

    • setWtMax

      public void setWtMax​(double wt)

    • getWtRealized

      public double getWtRealized()

    • setWtRealized

      public void setWtRealized​(double wt)

    • getSoldThreshold

      public double getSoldThreshold()

    • setSoldThreshold

      public void setSoldThreshold​(double st)

    • getExpectedCurtailment

      public double getExpectedCurtailment()
      Returns the expected-curtailment-per-timeslot quantity

    • getExpectedDischarge

      public double getExpectedDischarge()
      Returns the expected-discharge-per-timeslot quantity

    • getExpectedDownRegulation

      public double getExpectedDownRegulation()
      Returns the expected-down-regulation-per-timeslot quantity

    • getExpectedRegulation

      public double getExpectedRegulation()

    • getUpregHalf

      public Double getUpregHalf()

    • getUpregSlope

      public Double getUpregSlope()

    • getDownregHalf

      public Double getDownregHalf()

    • getDownregSlope

      public Double getDownregSlope()

    • getLog

      public static org.apache.logging.log4j.Logger getLog()

    • getExpCurtail

      public double getExpCurtail()

    • getExpDischarge

      public double getExpDischarge()

    • getExpDown

      public double getExpDown()

    • getAlpha

      public double getAlpha()

    • getTariff

      public Tariff getTariff()

    • getTimeService

      public TimeService getTimeService()