Package org.powertac.common

Class 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 Detail

      • TariffEvaluationHelper

        public TariffEvaluationHelper()
        Default constructor

    • Method Detail

      • 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()