Package org.powertac.common

Class Tariff

java.lang.Object
org.powertac.common.Tariff
@Domain
public class Tariff
extends Object
Entity wrapper for TariffSpecification that supports Tariff evaluation and billing. Instances of this class are not intended to be serialized. Tariffs are composed of Rates, which may be applicable for limited daily and/or weekly times, and within particular usage tiers. The Tariff transforms the list of Rates into an array, indexed first by tier and second by hour, making it easy to find the correct Rate that applies for a particular accounting event. This will also make it easy to estimate the cost of a multi-Rate Tariff given an expected load/production profile.

This is not a serializable type; The server and brokers are responsible for creating and maintaining their own Tariff entities if they have an interest in the transformation of TariffSpecification represented by a Tariff instance.

NOTE: When creating one of these for the first time, you must call the init() method to initialize the publication date. It does not work to call it inside the constructor for some reason.

Author:
John Collins

  • Constructor Details

    • Tariff

      public Tariff​(TariffSpecification spec)
      Creates a new Tariff from the given TariffSpecification. Note that the tariff will not be usable until its init() method has been called.

  • Method Details

    • init

      public boolean init()
      Initializes tariff by building the rate map. Must be called before usage charges can be computed. This is not in the constructor because of testability problems. Return value is true just in case the initialization succeeds.

    • getTariffSpecification

      public TariffSpecification getTariffSpecification()

    • getSpecId

      public long getSpecId()

    • getId

      public long getId()
      make id a synonym for specId

    • addHourlyCharge

      @StateChange public boolean addHourlyCharge​(HourlyCharge newCharge, long rateId)
      Adds a new HourlyCharge to its Rate. Returns true just in case the operation was successful.

    • getRealizedPrice

      public double getRealizedPrice()
      Returns the actual realized price, or 0.0 if information unavailable. This value is negative for consumption tariffs, because it indicates that the customer has paid the broker.

    • getMinDuration

      public long getMinDuration()
      Delegation for TariffSpecification.minDuration

    • getPowerType

      public PowerType getPowerType()
      Type of power covered by this tariff

    • getSignupPayment

      public double getSignupPayment()
      One-time payment for subscribing to tariff, negative for payment from customer, positive for payment to customer.

    • getEarlyWithdrawPayment

      public double getEarlyWithdrawPayment()
      Payment from customer to broker for canceling subscription before minDuration has elapsed. This is typically a negative value.

    • getPeriodicPayment

      public double getPeriodicPayment()
      Flat payment per period for two-part tariffs, typically negative.

    • getMaxUpRegulation

      public double getMaxUpRegulation​(double kwh, double cumulativeUsage)
      Returns the maximum interruptible quantity in kwh for this tariff in the current timeslot, for the specified proposed and cumulative usage.

    • getUsageCharge

      public double getUsageCharge​(double kwh, double cumulativeUsage, boolean recordUsage)
      Returns the usage charge for a single customer in the current timeslot. If the kwh parameter is given as +1.0, you get the per-kwh value for energy consumption, which is typically a negative value. If you supply a non-zero value for cumulativeUsage, then the charge will be affected by the rate tier structure in accordance with the new cumulative usage.

      If the recordUsage parameter is true, then the usage and price will be recorded to update the realizedPrice.

    • getRegulationCharge

      public double getRegulationCharge​(double kwh, double cumulativeUsage, boolean recordUsage)
      Returns the usage charge for regulation usage/or production. If this tariff has a RegulationRate, then that will determine the charge; otherwise the call will be delegated to getUsageCharge(). Regulation usage does not contribute to cumulative usage, since it's assumed to balance out over time. TODO: is this reasonable? Note that negative values for kwh represent up-regulation, while positive values represent down-regulation. Also note that regulation amounts are truncated if the payments exceed the ratios (to the energy prices in the tariff) specified by the max ratios in the tariff market.

    • getUsageCharge

      public double getUsageCharge​(org.joda.time.Instant when, double kwh, double cumulativeUsage)
      Returns the usage charge for a single customer using an amount of energy at some time in the past or future. The return value is typically opposite in sign to the kwh parameter. If the requested time is farther in the future than maxHorizon, then the result will likely be a default value, which may not be useful. The cumulativeUsage parameter sets the base for probing the rate tier structure. Do not use this method for billing, because it does not update the realized-price data.

    • getUsageCharge

      public double getUsageCharge​(org.joda.time.Instant when, double kwh, double cumulativeUsage, TariffEvaluationHelper helper)
      Returns a risk-adjusted usage charge, with prices for variable rates adjusted by the given TariffEvaluationHelper.

    • getExpiration

      public org.joda.time.Instant getExpiration()

    • isExpired

      public boolean isExpired()
      True just in case the current time is past the expiration date of this Tariff.

    • setExpiration

      @StateChange public void setExpiration​(org.joda.time.Instant newDate)

    • getOfferDate

      public org.joda.time.Instant getOfferDate()

    • isCovered

      public boolean isCovered()
      True just in case the set of Rates cover all the possible hour and tier slots. If false, then there is some combination of hour and tier for which no Rate is specified.

    • getTariffSpec

      public TariffSpecification getTariffSpec()

    • getBroker

      public Broker getBroker()

    • getState

      public Tariff.State getState()

    • setState

      @StateChange public void setState​(Tariff.State newState)
      Updates the state of this tariff.

    • isActive

      public boolean isActive()
      True just in case this tariff is OFFERED or ACTIVE

    • getIsSupersededBy

      public Tariff getIsSupersededBy()

    • getTotalCost

      public double getTotalCost()

    • getTotalUsage

      public double getTotalUsage()

    • getMeanConsumptionPrice

      public double getMeanConsumptionPrice()

    • isWeekly

      public boolean isWeekly()

    • isRevoked

      public boolean isRevoked()
      True just in case this tariff has been revoked.

    • isSubscribable

      public boolean isSubscribable()
      True just in case this tariff can accept new subscriptions

    • isTimeOfUse

      public boolean isTimeOfUse()
      True just in case this tariff has at least one Time-of-Use rate

    • isTiered

      public boolean isTiered()
      True just in case this tariff has at least one tiered rate

    • isVariableRate

      public boolean isVariableRate()
      True just in case this tariff has at least one dynamic rate

    • isInterruptible

      public boolean isInterruptible()
      True just in case this tariff could result in curtailment

    • hasRegulationRate

      public boolean hasRegulationRate()
      Wrapper for TariffSpecification.hasRegulationRate()

    • isAnalyzed

      public boolean isAnalyzed()
      Returns the analyzed flag.