Package org.powertac.common

Class Rate

java.lang.Object
org.powertac.common.state.XStreamStateLoggable
org.powertac.common.RateCore
org.powertac.common.Rate
@Domain(fields={"tariffId","weeklyBegin","weeklyEnd","dailyBegin","dailyEnd","tierThreshold","fixed","minValue","maxValue","noticeInterval","expectedMean","maxCurtailment"})
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 receive 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=5. 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

  • Field Summary

    Fields 
    Modifier and Type Field Description
    static int NO_TIME  

  • Constructor Summary

    Constructors 
    Constructor Description
    Rate()
    Default constructor only.

  • Method Summary

    Modifier and Type Method 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​(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.
    boolean applies​(org.joda.time.base.AbstractInstant when)
    True just in case this Rate applies at the given DateTime, ignoring the 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​(PowerType powerType)  
    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​(int begin)  
    Rate withDailyBegin​(org.joda.time.base.AbstractDateTime begin)
    Sets the time of day when this Rate comes into effect.
    Rate withDailyBegin​(org.joda.time.ReadablePartial begin)
    Sets the time of day when this Rate comes into 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.base.AbstractDateTime end)
    Sets the time of day when this Rate is no longer in effect.
    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​(long hours)
    Specifies the minimum interval in hours for rate change notifications for a variable Rate.
    Rate withNoticeInterval​(org.joda.time.Duration interval)
    Specifies the minimum interval 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​(int begin)  
    Rate withWeeklyBegin​(org.joda.time.base.AbstractDateTime 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​(int end)
    Sets the weekly end of applicability for this Rate.
    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​(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

  • Field Details

  • Constructor Details

    • Rate

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

  • Method Details

    • 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

      @StateChange public Rate withWeeklyBegin​(int begin)

    • 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

      @StateChange public Rate withWeeklyEnd​(int end)
      Sets the weekly end of applicability for this Rate. A value of 1 represents Monday, and 7 represents Sunday. Values outside this range will result in weeklyEnd being restored to its default value of NO_TIME, an error in the log, and a return value of null.

    • 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

      @StateChange public Rate withDailyBegin​(int begin)

    • 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

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

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

      @StateChange public boolean addHourlyCharge​(HourlyCharge newCharge, boolean publish)
      Allows initial publication of HourlyCharge instances within the notification interval.

    • getTierThreshold

      public double getTierThreshold()

    • withTierThreshold

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

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

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

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

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

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

      @StateChange 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.

    • isValid

      public boolean isValid​(PowerType powerType)

    • toString

      public String toString()
      Overrides:
      toString in class Object