Package org.powertac.common

Class 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

      All Methods Instance Methods Concrete Methods 
      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.

    • 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

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

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