org.powertac.common
Class Rate

java.lang.Object
  org.powertac.common.state.XStreamStateLoggable
      org.powertac.common.Rate

public class Rate
extends XStreamStateLoggable

Tariffs are composed of Rates. Rates may be applicable on particular days of the week, particular times of day, or above some usage threshold. Rates may be fixed or variable. Tariffs and their rates are public information. New tariffs and their Rates are communicated to Customers and to Brokers when tariffs are published. Energy and money quantities in Rates are given from the customer's viewpoint. In other words, a Rate for a consumption tariff will typically specify that the customer pays (negative money value) to recieve energy (positive energy quantity).

Each TariffSpecification must include at least one Rate. Rates can be fixed (the default) or variable. A fixed rate has a single value attribute that represents the customer payment for a kWh of energy. This value is typically negative for a consumption tariff (customer pays to receive energy) and positive for a production tariff. A variable rate must specify a minValue, a maxValue, and an expectedMean. To be valid, a Rate for a consumption tariff must have minValue >= expectedMean >= maxValue. For a production tariff, these relationships are reversed. These ranges constrain the HourlyCharge values that may be applied to the Rate.

The maxCurtailment parameter can be between 0.0 and 1.0 when applied to an interruptible PowerType. If greater than zero, then the production or consumption associated with the tariff can be shut off remotely for economic or balancing purposes, using an EconomicControlEvent or by issuing a BalancingOrder to the DU. The curtailment cannot exceed the product of maxCurtailment and the amount \ that would have been produced or consumed in the absence of the external control.

If a non-zero tierThreshold is given, then the rate applies only after daily consumption/production exceeds the threshold; to achieve a tiered structure, there needs to be at least one Rate with a tierThreshold of zero, and one for each threshold beyond zero. Tier thresholds must be positive for consumption tariffs, negative for production tariffs. For the purpose of determining tier applicability, production and consumption tracking is reset at midnight every day, in the TariffSubscription.

Time-of-use and day-of-week Rates can be specified with dailyBegin / dailyEnd and weeklyBegin / weeklyEnd specifications. For dailyBegin / dailyEnd, the values are integer hours in the range 0:23. A Rate that applies from 22:00 in the evening until 6:00 the next morning would have dailyBegin=22 and dailyEnd=6. Weekly begin/end specifications are integers in the range 1:7, with 1=Monday.

It is possible for multiple rates to be applicable at any given combination of time/usage. If this is the case, the most specific rate applies. So if there is a fixed rate that applies all the time, it will be overridden by a time-of-use rate during its period of applibility. Also, if the times for time-of-use rates overlap, they are sorted by start-time, and the applicable rate with the latest start time will apply. This logic is implemented in Tariff.

State log fields for readResolve():
new(long tariffId, int weeklyBegin, int weeklyEnd,
int dailyBegin, int dailyEnd, double tierThreshold,
boolean fixed, double minValue, double maxValue,
long noticeInterval, double expectedMean, double maxCurtailment)

Author:

John Collins

Constructor Summary

Rate()
Default constructor only.

Method Summary

boolean	addHourlyCharge(HourlyCharge newCharge) Adds a new HourlyCharge to a variable rate.
boolean	addHourlyCharge(HourlyCharge newCharge, boolean publish) Allows initial publication of HourlyCharge instances within the notification interval.
boolean	applies() True just in case this Rate applies at this moment, ignoring the tier.
boolean	applies(org.joda.time.base.AbstractInstant when) True just in case this Rate applies at the given DateTime, ignoring the tier.
boolean	applies(double usage) True just in case this Rate applies at this moment, for the indicated usage tier.
boolean	applies(double usage, org.joda.time.base.AbstractInstant when) True just in case this Rate applies at the specified time, for the indicated usage tier.
int	getDailyBegin()
int	getDailyEnd()
double	getExpectedMean()
long	getId() Returns the id of this Rate
double	getMaxCurtailment() Returns the maximum proportion of offered load or supply that can be curtailed in a given timeslot.
double	getMaxValue()
double	getMinValue()
long	getNoticeInterval()
TreeSet<HourlyCharge>	getRateHistory() Returns the sequence of HourlyCharge instances for this Rate.
long	getTariffId() Returns the id of the TariffSpecification to which this Rate is attached.
double	getTierThreshold()
double	getValue() Returns the rate for the current time.
double	getValue(org.joda.time.base.AbstractInstant when) Shortcut to get value at an instant without a TEH.
double	getValue(org.joda.time.base.AbstractInstant when, TariffEvaluationHelper helper) Returns the rate for some time in the past or future, regardless of whether the Rate applies at that time, and regardless of whether the requested time is beyond the notification interval of a variable rate.
int	getWeeklyBegin()
int	getWeeklyEnd()
boolean	isFixed()
boolean	isTimeOfUse() True just in case this Rate does not apply everywhen
boolean	isValid(TariffSpecification spec) Returns true just in case this Rate is internally valid, and valid with respect to the given TariffSpecification.
void	setTariffId(long id) Sets the backpointer to the tariff.
String	toString()
Rate	withDailyBegin(org.joda.time.base.AbstractDateTime begin) Sets the time of day when this Rate comes into effect.
Rate	withDailyBegin(int begin) Sets the time of day when this Rate comes into effect as hours since midnight.
Rate	withDailyBegin(org.joda.time.ReadablePartial begin) Sets the time of day when this Rate comes into effect.
Rate	withDailyEnd(org.joda.time.base.AbstractDateTime end) Sets the time of day when this Rate is no longer in effect.
Rate	withDailyEnd(int end) Sets the time of day when this Rate is no longer in effect, given as hours since midnight.
Rate	withDailyEnd(org.joda.time.ReadablePartial end) Sets the time of day when this Rate is no longer in effect.
Rate	withExpectedMean(double value) Specifies the expected mean charge/kWh, excluding periodic charges, for this Rate.
Rate	withFixed(boolean fixed) Specifies whether this Rate is fixed (true) or variable (false).
Rate	withMaxCurtailment(double value) Sets the maximum proportion of offered load or supply that can be curtailed.
Rate	withMaxValue(double maxValue) Specifies the maximum charge (furthest from zero) for variable Rates.
Rate	withMinValue(double minValue) Specifies the minimum charge (closest to zero) for variable Rates.
Rate	withNoticeInterval(org.joda.time.Duration interval) Specifies the minimum interval for rate change notifications for a variable Rate.
Rate	withNoticeInterval(long hours) Specifies the minimum interval in hours for rate change notifications for a variable Rate.
Rate	withTierThreshold(double tierThreshold) Sets the usage threshold for applicability of this Rate.
Rate	withValue(double value) Specifies the charge/kWh for a fixed rate, from the customer's viewpoint.
Rate	withWeeklyBegin(org.joda.time.base.AbstractDateTime begin) Sets the day of the week on which this Rate comes into effect.
Rate	withWeeklyBegin(int begin) Sets the day of the week on which this Rate comes into effect.
Rate	withWeeklyBegin(org.joda.time.ReadablePartial begin) Sets the day of the week on which this Rate comes into effect.
Rate	withWeeklyEnd(org.joda.time.base.AbstractDateTime end) Sets the weekly end of applicability for this Rate, by processing end spec to extract dayOfWeek field.
Rate	withWeeklyEnd(int end) Sets the weekly end of applicability for this Rate.
Rate	withWeeklyEnd(org.joda.time.ReadablePartial end) Sets the weekly end of applicability for this Rate, by processing end spec to extract dayOfWeek field.

Methods inherited from class org.powertac.common.state.XStreamStateLoggable

readResolve

Methods inherited from class java.lang.Object

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

Constructor Detail

Rate

public Rate()

Default constructor only. You create one of these with the constructor and the fluent-style setter methods.

Method Detail

getId

public long getId()

Returns the id of this Rate

getTariffId

public long getTariffId()

Returns the id of the TariffSpecification to which this Rate is attached.

setTariffId

public void setTariffId(long id)

Sets the backpointer to the tariff. This is a non-fluent setter, intended to be called by Tariff. It is public to better support state logging

withWeeklyBegin

public Rate withWeeklyBegin(org.joda.time.base.AbstractDateTime begin)

Sets the day of the week on which this Rate comes into effect. The begin parameter is processed to extract the dayOfWeek field.

withWeeklyBegin

public Rate withWeeklyBegin(org.joda.time.ReadablePartial begin)

Sets the day of the week on which this Rate comes into effect. Process begin spec to extract dayOfWeek field

withWeeklyBegin

public Rate withWeeklyBegin(int begin)

Sets the day of the week on which this Rate comes into effect. Note that a value of 1 represents Monday, while 7 represents Sunday.

getWeeklyBegin

public int getWeeklyBegin()

withWeeklyEnd

public Rate withWeeklyEnd(org.joda.time.base.AbstractDateTime end)

Sets the weekly end of applicability for this Rate, by processing end spec to extract dayOfWeek field.

withWeeklyEnd

public Rate withWeeklyEnd(org.joda.time.ReadablePartial end)

Sets the weekly end of applicability for this Rate, by processing end spec to extract dayOfWeek field.

withWeeklyEnd

public Rate withWeeklyEnd(int end)

Sets the weekly end of applicability for this Rate. A value of 1 represents Monday, and 7 represents Sunday.

getWeeklyEnd

public int getWeeklyEnd()

withDailyBegin

public Rate withDailyBegin(org.joda.time.base.AbstractDateTime begin)

Sets the time of day when this Rate comes into effect.

withDailyBegin

public Rate withDailyBegin(org.joda.time.ReadablePartial begin)

Sets the time of day when this Rate comes into effect.

withDailyBegin

public Rate withDailyBegin(int begin)

Sets the time of day when this Rate comes into effect as hours since midnight.

getDailyBegin

public int getDailyBegin()

withDailyEnd

public Rate withDailyEnd(org.joda.time.base.AbstractDateTime end)

Sets the time of day when this Rate is no longer in effect.

withDailyEnd

public Rate withDailyEnd(org.joda.time.ReadablePartial end)

Sets the time of day when this Rate is no longer in effect.

withDailyEnd

public Rate withDailyEnd(int end)

Sets the time of day when this Rate is no longer in effect, given as hours since midnight.

getDailyEnd

public int getDailyEnd()

withNoticeInterval

public Rate withNoticeInterval(org.joda.time.Duration interval)

Specifies the minimum interval for rate change notifications for a variable Rate. The value is truncated to integer hours.

withNoticeInterval

public Rate withNoticeInterval(long hours)

Specifies the minimum interval in hours for rate change notifications for a variable Rate.

getNoticeInterval

public long getNoticeInterval()

addHourlyCharge

public boolean addHourlyCharge(HourlyCharge newCharge)

Adds a new HourlyCharge to a variable rate. If this Rate is not variable, or if the HourlyCharge arrives past its noticeInterval, then we log an error and drop it on the floor. If the update is valid but there's already an HourlyCharge in the specified timeslot, then the update must replace the existing HourlyCharge. Returns true just in case the new charge was added successfully.

addHourlyCharge

public boolean addHourlyCharge(HourlyCharge newCharge,
                               boolean publish)

Allows initial publication of HourlyCharge instances within the notification interval.

getTierThreshold

public double getTierThreshold()

withTierThreshold

public Rate withTierThreshold(double tierThreshold)

Sets the usage threshold for applicability of this Rate. The value is interpreted from the Customer's viewpoint, so positive values represent energy consumption in kWh, negative values represent energy production.

getMinValue

public double getMinValue()

withMinValue

public Rate withMinValue(double minValue)

Specifies the minimum charge (closest to zero) for variable Rates. Value should be negative for consumption tariffs, positive for production tariffs.

getMaxValue

public double getMaxValue()

withMaxValue

public Rate withMaxValue(double maxValue)

Specifies the maximum charge (furthest from zero) for variable Rates. Value should be negative for consumption tariffs, positive for production tariffs.

getMaxCurtailment

public double getMaxCurtailment()

Returns the maximum proportion of offered load or supply that can be curtailed in a given timeslot.

withMaxCurtailment

public Rate withMaxCurtailment(double value)

Sets the maximum proportion of offered load or supply that can be curtailed. Must be between 0.0 and 1.0. Values > 0.0 are only meaningful for controllable capacities.

isFixed

public boolean isFixed()

withFixed

public Rate withFixed(boolean fixed)

Specifies whether this Rate is fixed (true) or variable (false).

isTimeOfUse

public boolean isTimeOfUse()

True just in case this Rate does not apply everywhen

getExpectedMean

public double getExpectedMean()

withExpectedMean

public Rate withExpectedMean(double value)

Specifies the expected mean charge/kWh, excluding periodic charges, for this Rate.

getRateHistory

public TreeSet<HourlyCharge> getRateHistory()

Returns the sequence of HourlyCharge instances for this Rate.

applies

public boolean applies()

True just in case this Rate applies at this moment, ignoring the tier.

applies

public boolean applies(org.joda.time.base.AbstractInstant when)

True just in case this Rate applies at the given DateTime, ignoring the tier.

applies

public boolean applies(double usage)

True just in case this Rate applies at this moment, for the indicated usage tier.

applies

public boolean applies(double usage,
                       org.joda.time.base.AbstractInstant when)

True just in case this Rate applies at the specified time, for the indicated usage tier.

withValue

public Rate withValue(double value)

Specifies the charge/kWh for a fixed rate, from the customer's viewpoint. Negative values represent customer debits, while positive values represent customer credits.

getValue

public double getValue()

Returns the rate for the current time. Note that the value is returned even in case the Rate does not apply at the current time or current usage tier. For variable rates, the value returned during periods of inapplicability is meaningless, of course.

getValue

public double getValue(org.joda.time.base.AbstractInstant when)

Shortcut to get value at an instant without a TEH.

getValue

public double getValue(org.joda.time.base.AbstractInstant when,
                       TariffEvaluationHelper helper)

Returns the rate for some time in the past or future, regardless of whether the Rate applies at that time, and regardless of whether the requested time is beyond the notification interval of a variable rate. If helper is given, and this rate is not fixed, and there is not an HourlyCharge for the requested timeslot, then the helper is used to produce the value.

isValid

public boolean isValid(TariffSpecification spec)

Returns true just in case this Rate is internally valid, and valid with respect to the given TariffSpecification. For all Rates, maxCurtailment is between 0.0 and 1.0. For a CONSUMPTION tariff, tierThreshold must be non-negative, while for a PRODUCTION tariff, tierThreshold must be non-positive. For a non-fixed rate, maxValue must be at least as "large" as minValue, where "larger" means more negative for a CONSUMPTION tariff, and more positive for a PRODUCTION tariff. Also, expectedMean must be between minValue and maxValue, and noticeInterval must be non-negative.

toString

public String toString()

Overrides:

toString in class Object