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 Summary

Constructors

Constructor and Description
TariffEvaluationHelper() Default constructor

Method Summary

Methods

Modifier and Type	Method and Description
double	estimateCost(Tariff tariff, double[] usage) Returns aggregate estimated cost, including periodic charges, starting in the next timeslot.
double	estimateCost(Tariff tariff, double[] usage, boolean includePeriodicCharge) Estimate cost for a profile starting in the next timeslot
double	estimateCost(Tariff tariff, double[] usage, org.joda.time.Instant start) Returns aggregate estimated cost, including periodic charges
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.
double[]	estimateCostArray(Tariff tariff, double[] usage) Returns a cost estimate in array form, including periodic charges.
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.
double	getExpectedCurtailment() Returns the expected-curtailment-per-timeslot quantity
double	getExpectedDischarge() Returns the expected-discharge-per-timeslot quantity
double	getExpectedDownRegulation() Returns the expected-down-regulation-per-timeslot quantity
double	getNormWtExpected()
double	getNormWtMax()
double	getSoldThreshold()
double	getWtExpected() Parameter access
double	getWtMax()
double	getWtRealized()
void	init() Initializes, without changing parameter settings
void	init(double wtExpected, double wtMax, double wtRealized, double soldThreshold) Initializes, setting parameters, then normalize the weights for expectedMean and maxValue.
void	initializeCostFactors(double wtExpected, double wtMax, double wtRealized, double soldThreshold) Initializes cost factors and normalizes
void	initializeRegulationFactors(double expectedCurtailment, double expectedDischarge, double expectedDownReg) Initializes regulation factors.
void	setSoldThreshold(double st)
void	setWtExpected(double wt)
void	setWtMax(double wt)
void	setWtRealized(double wt)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

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

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