Role concept - Pyosch/powertac-server GitHub Wiki

#PowerTAC Role and Plugin concept up

Note: This page describes details of the original Grails prototype, and is largely irrelevant to the Spring/Java version. In particular, there is no longer a database, and the specific set of "plugin" modules is somewhat different.

##Overview This page describes the core entities defined within the scope of PowerTAC. Technically, each of these entities (except broker and competition controller) is realized as a [[grails plugin|http://grails.org/doc/latest/guide/single.html#12.%20Plug-ins]] that can be easily installed into (or removed from) the PowerTAC server. Like this, several different implementations for each role can be developed and easily added to the PowerTAC server on demand.

##Plugin DB Table Ownership All plugins installed into the server share access to a common competition database. Each table in the db is mapped to a specific [[domain class|https://github.com/powertac-plugins/powertac-common/tree/master/grails-app/domain/org/powertac/common]] via [[GORM (grails object relational mapping)|http://www.grails.org/doc/latest/]].

Information sharing between plugins is thus very easy but this design also increases the likelihood of concurrent read/write exceptions on the database level. To avoid such concurrency issues (notoriously hard to debug!), we introduce the concept of db table ownership for PowerTAC. Each plugin "owns" one or more db tables (i.e. domain classes). This means that (by convention) only the owning plugin is allowed to add / update / delete data in the respective table. All other plugins have free read access to all tables but are not allowed to change data in tables other than those they own.

If, for example, the tax authority plugin still needs to manipulate the CashUpdate table (which it does not own) in order to deduce taxes from a broker's cash account, it has to create a [[command object|https://github.com/powertac-plugins/powertac-common/tree/master/src/groovy/org/powertac/common/command]] that describes the required change. In this case an instance of org.powertac.common.command.CashDoUpdateCmd needs to be created. The command object contains all information required to update the CashUpdate table in order to execute the tax authority tax deduction. Once created by the tax authority, the command object is forwarded to the owning plugin (in this case the Accounting Service) which then executes the required transaction. The transport of the command object as well as the dissemination of the results are transparently handled by the server PowerTAC server (and not by the plugins themselves!).

Note: Each plugin should use its own Java package name in order to avoid class name conflicts between plugins

Alternative viewpoint: JEC The requirement to create command objects and pass them around through JMS is a holdover from an earlier architectural idea. Better to simply call a method on the type that owns the table. This will work if each plugin implements a facade interface provided in powertac-common.

However, this still does not solve the database contention problem, because it does not address issues of sessions and concurrency. Write contention is only eliminated if we can guarantee that the code in a given plugin is only ever executed within a single thread. It is not clear how to manage this, or even if it's a good idea.

Defined PowerTAC roles, table ownerships, and Java package name

  • Accounting Service (As)
    • Central bookkeeping entity. Keeps track of all cash, position, metering, and tariff changes
    • Table Ownership: CashUpdate, PositionUpdate, MeterReading, Tariff
    • Package: org.powertac.accountingservice
  • Auctioneer (Au)
    • Provides the PowerTAC market infrastructure that brokers could use to buy or sell energy futures.
    • Table Ownership: Orderbook, Shout, TransactionLog
    • Package: org.powertac.auctioneer
  • Brokers (Br)
    • Software agents outside the server, provided by competition participants; acquire customers, balance energy demand / supply, compete against other
    • Table Ownership:
    • Package: N/A (brokers are not executed inside the server)
  • Customer (Cu)
    • Small or big energy producers, consumers, or prosumers
    • Table Ownership: Customer (each customer should only manipulate his own record)
    • Package: org.powertac.customer.<mycustomer name> (Note: Many customers can be executed in parallel in one server instance, thus each customer has to have its own package name!)
  • Competition Controller (Cc)
    • Central scheduling unit
    • Triggers competition time changes
    • Table ownership: Broker, Competition, Product, Timeslot
    • Package: org.powertac.competitioncontroller
  • Distribution Utility (aka Distribution System Operator) (Du)
    • Ex-Post power balancing and power imbalance billing
    • Table Ownership:
    • Package: org.powertac.distributionutility
  • Liquidity Provider (Lp)
    • Couples wholesale market to PowerTAC market using arbitrage opportunities between both markets (explicit market coupling). Provides quotes (i.e. bid and ask orders with a certain spread between both) for all tradeable products in the market
    • Table ownership:
    • Package: org.powertac.liquidityprovider
  • Physical Environment (Pe)
    • Generates and returns weather forecasts and real weather data for every enabled timeslot
    • Table ownership: Weather
    • Package: org.powertac.physicalenvironment
  • Tariff Rule Enforcer (Tr)
    • Validates tariff against a defined set of market rules (e.g. minimum or maximum price constraints etc.)
    • Table ownership:
    • Package: org.powertac.tariffruleenforcer
  • Tax Authority
    • Taxes / subsidizes brokers based on their utilization of certain technologies, their portfolio's emission of CO2 etc.
    • Table ownership:
    • Package: org.powertac.taxauthority

##Defined DB tables and their table owners

  • Broker -> Competition Controller
  • CashUpdate -> Accounting Service
  • Competition -> Competition Controller
  • Customer -> Customer
  • MeterReading -> Accounting Service
  • Orderbook -> Auctioneer
  • PositionUpdate -> Accounting Service
  • Product -> Competition Controller
  • Shout -> Auctioneer
  • Tariff -> Accounting Service
  • Timeslot -> Competition Controller
  • TransactionLog -> Auctioneer
  • Weather -> Physical Environment
⚠️ **GitHub.com Fallback** ⚠️