Market Intelligence Service functionality

Roles

 * Market Intelligence Service (MIS)
 * Broker
 * Customer
 * Tariff Customer
 * Contract Customer
 * Consumer
 * Producer
 * Competition Control Service (CCS)

==User Stories == The following stories are presented approximately in order of actor role:
 * 1) (M) As a Broker, I want to request historical consumption and generation time series for all Customers under contract with me so that I can use that information in my prediction model.
 * 2) (M) As the MIS, I want to limit the extent of history to seven days prior to when the Customer entered a contract with this Broker Agent.
 * 3) (M) As a Broker, I want to request historical aggregate consumption and generation statistics for the Customer population so that I can use that information in my prediction model.
 * 4) (C) As the MIS, I want to charge extra for this additional information so that I represent the cost of information acquisition.
 * 5) (M) As a Broker, I want to submit one set of tariffs per round of tariff negotiation within a contracting phase so that I can try and improve my portfolio of customers.
 * 6) (C) As a Broker, I want to be able to replace my current set of tariffs for the round.
 * 7) (W) As the MIS, I want to charge a fee for tariff-set replacement within a round so that am not flooded with replacement requests.
 * 8) (M) As a Broker, I want to receive a count of the number of Customers willing to accept my current tariffs so that I can model how they would affect my supply and demand balance.
 * 9) (M) As a Broker, I want to request aggregated supply/demand profiles for the Customers that are willing to accept my current tariffs so that I can model how they would affect my supply and demand balance.
 * 10) (C) As the MIS, I want to charge extra for this additional information so that I represent the cost of predictive analytics.
 * 11) (M) As a Broker, I want to request predicted (i.e., artificially distorted) future generation time series for intermittent generators so that I don't have to predict future generation from past history.
 * 12) (M) As any agent, I want to request all currently-offered tariffs at the end of the last round of the contracting phase.
 * 13) (S) As a Customer, I want to request reputation metrics for all Brokers so that those metrics can be used in my preferences.
 * 14) (C) As a Broker, I want to request reputation metrics at least for myself and possibly for all Brokers so that I consider this in my strategy.
 * 15) As the MIS, I want to restrict the information available a Broker and charge a fee for additional information.
 * 16) (M) As the CCS, I want to request which Customers are allocated to which Brokers at the end of each contracting phase.
 * 17) (M) As the MIS, I want to charge each Broker a fee that depends on the maximum number of concurrently offered tariffs for any negotiation round in the current contracting phase.
 * 18) (M) As the MIS, I want to request, from the CCS or Depot, a transactional debit from a Broker's cash-balance so that I can charge a fee for my services.
 * 19) (M) As the MIS, I want to collect the preferences of each Customer so that I can run my customer preference model.
 * 20) (C) As a Tariff Customer, I want to charge a fee (or receive some reciprocal benefit) for providing my preference information to the MIS.
 * 21) (M) As the MIS, I want to capture inertial effects of existing contracts so that large swings in the tariff market are less likely.
 * 22) (S) As the MIS, I want to include factors that affect taxes and incentives (e.g. share of renewable energy for a Producer) in the customer profiles so that Broker agents can optimize their portfolios accordingly.
 * 23) (M) As the MIS, I want to help simulate exogenous shocks to the overall system so that the Broker agents are robust (e.g. lack of recent information, loss of historical information).

[Note: The annotations in parentheses in front of each story are from the MoSCoW method -- Must, Should, Could, Won't.]

Storyboard

 * Login
 * Broker
 * Submit tariffs for contracting phase
 * Receive number of customers willing to accept tariffs
 * Review fees charged for contracting phase
 * Request information
 * Approve fees to be charged
 * Wait for confirmation of fees charged and receive information
 * CCS
 * Request customer-to-broker mapping for current execution phase
 * Customer
 * Submit preference information
 * Request broker reputation metrics
 * Anonymous
 * Request tariffs for each broker from last contracting phase
 * Request historical tariffs for each broker from all completed contracting phases

User Story 3.2:
Impose a technical limitation instead and introduce as a game rule (limit number of messages or number of bids per round).

All other stories are confirmed as noted above (some with updated MoSCoW tags).

Tariff Attributes
The following pre-defined attributes are based on discussions with Yixin, Carsten and others and also based on tariffs available at http://www.energychoices.co.uk. (The data structure allows for additional "non-standard" attributes to be added for research purposes.)
 * 1) Broker: Name of the broker
 * 2) Name: Name of the tariff (unique only in the Broker's context)
 * 3) Base Fee: Standing payment irrespective of production/consumption
 * 4) Tier1Rate: Map of hourly rates per kwh upto Tier1 threshold
 * 5) Tier1Max: Threshold in kwh for consumption or production at tier1 rate
 * 6) Tier2Rate: Map of hourly rates per kwh beyond Tier1 threshold
 * 7) RateGuarantee: Number of days for which unit rate is guaranteed after signup
 * 8) LeadTime: Minimum lead time for price change signals (in hours)
 * 9) OfferRate: Signup premium or discount (%) offered for a limited period
 * 10) OfferPeriod: Number of days for which signup premium/discount is applied
 * 11) OfferDelay: Number of days before signup offer is accounted for and paid
 * 12) Duration: Contract duration from signup in number of days
 * 13) ExitFee: Fees due for early termination of tariff
 * 14) Balance: Percentage of production/consumption capacity held for balancing
 * 15) FuelMix: Map of percentages for Renewable | Nuclear | Gas | Coal | Other
 * 16) CarbonWeight: CO2 emissions in kg per kwh (can be computed from Fuel Mix)

[Note: The language of the terms is such that the same tariff can be used for consumers and producers. Please see details and discussion of a relevant game design issue on the Discussion page.]

Here is a sample tariff represented in XML:  6.50  0=0.05, 9=0.10, 18=0.12, 21=0.08  15  0=0.10, 9=0.14, 21=0.10  90 20.0</ExitFee> <RateGuarantee units="days">0</RateGuarantee> <LeadTime units="hours">4</LeadTime> <OfferRate type="discount">0.15</OfferRate> <OfferPeriod units="days">30</OfferPeriod> <OfferDelay units="days">60</OfferDelay> <FuelMix>19, 5, 46, 22, 8</FuelMix> <Balance>0.03</Balance> </Tariff>