Package org.powertac.common

Class TariffSubscription

  • @Domain
public class TariffSubscription
extends Object
    A TariffSubscription is an entity representing an association between a Customer and a Tariff. Instances of this class are not intended to be serialized. You get one by calling the subscribe() method on Tariff. If there is no current subscription for that Customer (which in most cases is actually a population model), then a new TariffSubscription is created and returned from the Tariff.
    Author:
    John Collins, Carsten Block

    • Constructor Detail

      • TariffSubscription

        public TariffSubscription​(CustomerInfo customer,
                          Tariff tariff)
        You need a CustomerInfo and a Tariff to create one of these.

      • TariffSubscription

        public TariffSubscription​(CustomerInfo customer,
                          long tariffId)
        Alternate constructor for logtool analyzers in which Tariffs cannot be reconstructed. Many features won't work if the Tafiff does not exist.

    • Method Detail

      • getId

        public long getId()

      • getTariff

        public Tariff getTariff()

      • getTariffId

        public long getTariffId()

      • getCustomersCommitted

        public int getCustomersCommitted()

      • setCustomersCommitted

        @StateChange
public void setCustomersCommitted​(int value)

      • getTotalUsage

        public double getTotalUsage()

      • subscribe

        @StateChange
public void subscribe​(int customerCount)
        Subscribes some number of discrete customers. This is typically some portion of the population in a population model. We assume this is called from Tariff, as a result of calling tariff.subscribe(). Also, we record the expiration date of the tariff contract, just in case the tariff has a minDuration. For the purpose of computing expiration, all contracts are assumed to begin at 00:00 on the day of the subscription.

      • unsubscribe

        public void unsubscribe​(int customerCount)
        Removes customerCount customers (at most) from this subscription, posts early-withdrawal fees if appropriate.

      • deferredUnsubscribe

        @StateChange
public void deferredUnsubscribe​(int customerCount)
        Handles the actual unsubscribe operation. Intended to be called by the TariffMarket (phase 4) to avoid subscription changes between customer consumption/production and balancing.

      • handleRevokedTariff

        public Tariff handleRevokedTariff()
        Handles the subscription switch in case the underlying Tariff has been revoked. The actual processing of tariff revocations, including switching subscriptions to superseding tariffs, is deferred to be handled by the tariff market.

      • usePower

        public void usePower​(double kwh)
        Generates and posts a TariffTransaction instance for the current timeslot that represents the amount of production (negative amount) or consumption (positive amount), along with the credit/debit that results. Also generates a separate TariffTransaction for the fixed periodic payment if it's non-zero. Note that the power usage value and the numbers in the TariffTransaction are aggregated across the subscribed population, not per-member values. This is where the signs on energy and cost are inverted to convert from the customer-centric view in the tariff to the broker-centric view in the transactions.

      • getCurtailment

        public double getCurtailment()
        Returns the regulation in kwh, aggregated across the subscribed population, for the previous timeslot. Intended to be called by Customer models only. Value is non-negative for consumption power types, non-positive for production types. For storage types it may be positive or negative. NOTE: this method is not idempotent; if you call it twice in the same timeslot, the second time returns zero.

      • getRegulation

        public double getRegulation()
        Returns the regulation quantity exercised per member in the previous timeslot. For non-storage devices, only up-regulation through curtailment is supported, and the result will be a non-negative value. For storage devices, it may be positive (up-regulation) or negative (down-regulation). Intended to be called by customer models. NOTE: This method is not idempotent, because the regulation quantity is reset to zero after it's accessed.

      • setRegulation

        public void setRegulation​(double newValue)

      • setRegulationCapacity

        public void setRegulationCapacity​(RegulationCapacity capacity)
        Communicates the ability of the customer model to handle regulation requests. Quantities are per-member. NOTE: This method must be called once/timeslot for any customer that offers regulation capacity, because otherwise the capacity will be carried over from the previous timeslot.

      • ensureRegulationCapacity

        public void ensureRegulationCapacity()
        Ensures that regulationAccumulator is non-null - needed for non-regulatable customer models

      • hasRegulationRate

        public boolean hasRegulationRate()
        True just in case this subscription allows regulation.

      • postRatioControl

        @StateChange
public void postRatioControl​(double ratio)
        Posts the ratio for an EconomicControlEvent to the subscription for the current timeslot.

      • postBalancingControl

        @StateChange
public void postBalancingControl​(double kwh)
        Posts a BalancingControlEvent to the subscription and generates the correct TariffTransaction. This updates the regulation for the current timeslot by the amount of the control. A positive value for kwh represents up-regulation, or an increase in production - in other words, a net gain for the broker's energy account balance. The kwh value is a population value, not a per-member value.

      • getRemainingRegulationCapacity

        public RegulationAccumulator getRemainingRegulationCapacity()
        Returns the maximum aggregate up-regulation possible after the customer model has run and possibly applied economic controls. Since this is potentially accessed through the balancing market after customers have updated their subscriptions, it's possible that the value will have to be changed due to a change in customer count. TODO: may need to be modified -- see issue #733.

      • getExpiredCustomerCount

        public int getExpiredCustomerCount()
        Returns the number of individual customers who may withdraw from this subscription without penalty. Should return the total customer count for a non-expiring tariff.