Package org.powertac.common
Class TariffSubscription
- java.lang.Object
-
- org.powertac.common.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 Summary
Constructors Constructor Description TariffSubscription(CustomerInfo customer, long tariffId)
Alternate constructor for logtool analyzers in which Tariffs cannot be reconstructed.TariffSubscription(CustomerInfo customer, Tariff tariff)
You need a CustomerInfo and a Tariff to create one of these.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description void
deferredUnsubscribe(int customerCount)
Handles the actual unsubscribe operation.void
ensureRegulationCapacity()
Ensures that regulationAccumulator is non-null - needed for non-regulatable customer modelsdouble
getCurtailment()
Returns the regulation in kwh, aggregated across the subscribed population, for the previous timeslot.CustomerInfo
getCustomer()
int
getCustomersCommitted()
int
getExpiredCustomerCount()
Returns the number of individual customers who may withdraw from this subscription without penalty.long
getId()
double
getRegulation()
Returns the regulation quantity exercised per member in the previous timeslot.RegulationAccumulator
getRemainingRegulationCapacity()
Returns the maximum aggregate up-regulation possible after the customer model has run and possibly applied economic controls.Tariff
getTariff()
long
getTariffId()
double
getTotalUsage()
Tariff
handleRevokedTariff()
Handles the subscription switch in case the underlying Tariff has been revoked.boolean
hasRegulationRate()
True just in case this subscription allows regulation.void
postBalancingControl(double kwh)
Posts a BalancingControlEvent to the subscription and generates the correct TariffTransaction.void
postRatioControl(double ratio)
Posts the ratio for an EconomicControlEvent to the subscription for the current timeslot.void
setCustomersCommitted(int value)
void
setRegulation(double newValue)
void
setRegulationCapacity(RegulationCapacity capacity)
Communicates the ability of the customer model to handle regulation requests.void
subscribe(int customerCount)
Subscribes some number of discrete customers.void
unsubscribe(int customerCount)
Removes customerCount customers (at most) from this subscription, posts early-withdrawal fees if appropriate.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.
-
-
-
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.
-
-
Method Detail
-
getId
public long getId()
-
getCustomer
public CustomerInfo getCustomer()
-
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.
-
-