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 and Description
TariffSubscription(CustomerInfo customer, Tariff tariff) You need a CustomerInfo and a Tariff to create one of these.

Method Summary

Modifier and Type	Method and Description
void	deferredUnsubscribe(int customerCount) Handles the actual unsubscribe operation.
void	ensureRegulationCapacity() Ensures that regulationAccumulator is non-null - needed for non-regulatable customer models
double	getCurtailment() Deprecated. Use getRegulation() instead, but remember that it returns a per-member value, while this method returns an aggregate value.
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()
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 generate 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.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

TariffSubscription

public TariffSubscription(CustomerInfo customer,
                          Tariff tariff)

You need a CustomerInfo and a Tariff to create one of these.

Method Detail

getId

public long getId()

getCustomer

public CustomerInfo getCustomer()

getTariff

public Tariff getTariff()

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.

getCurtailment

@Deprecated
public double getCurtailment()

Deprecated. Use getRegulation() instead, but remember that it returns a per-member value, while this method returns an aggregate value.

Returns the regulation in aggregate kwh 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. Note that 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

@StateChange
public void setRegulation(double newValue)

setRegulationCapacity

@StateChange
public void setRegulationCapacity(RegulationCapacity capacity)

Communicates the ability of the customer model to handle regulation requests. Quantities are per-member.

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