Package org.powertac.common

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

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

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

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

      • getBroker

        public Broker getBroker()

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