Rate (Power TAC common domain model 1.1.0 API)

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

```
public class Rate
extends RateCore
```
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

Constructors
Constructor and Description

Rate()
Default constructor only.

Constructors
Constructor and Description
`Rate()` Default constructor only.

Method Summary

Methods
Modifier and Type	Method and Description
`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()`
`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.
`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.
`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.RateCore
getId, getTariffId, setTariffId

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

Class Rate

Constructor Summary

Method Summary

Methods inherited from class org.powertac.common.RateCore

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

Methods inherited from class java.lang.Object

Constructor Detail

Rate

Method Detail

withWeeklyBegin

withWeeklyBegin

withWeeklyBegin

getWeeklyBegin

withWeeklyEnd

withWeeklyEnd

withWeeklyEnd

getWeeklyEnd

withDailyBegin

withDailyBegin

withDailyBegin

getDailyBegin

withDailyEnd

withDailyEnd

withDailyEnd

getDailyEnd

withNoticeInterval

withNoticeInterval

getNoticeInterval

addHourlyCharge

addHourlyCharge

getTierThreshold

withTierThreshold

getMinValue

withMinValue

getMaxValue

withMaxValue

getMaxCurtailment

withMaxCurtailment

isFixed

withFixed

isTimeOfUse

getExpectedMean

withExpectedMean

getRateHistory

applies

applies

applies

applies

withValue

getValue

getValue

getValue

isValid

toString