Server structure - Pyosch/powertac-server GitHub Wiki

up
The Power TAC server is built as a set of relatively independent components on the Spring IOC framework. The minimal set of components and their dependencies is shown below.

The arrows indicate dependency relationships. Note that the core modules depend only on common and server-interface. This includes powertac-server, except that it also includes the application configuration file, an xml file that depends on all the other modules only to the extent that it must load them.

We now briefly describe the purpose of each module, starting at the bottom:

This module contains the domain model, including all the serializable types that are exchanged between broker agents and the server. The intent is that this module would be incorporated in an agent framework as well as in the server. It also includes:

• a message converter to marshal and unmarshal messages between server and agent,
• a set of "aspects" that can be used to generate a consistent record of state changes,
• the basic simulation clock, and
• a set of message types that can ensure that agent and server clocks are synchronized.

Activation: Aside from the clock, all behavior in this component is invoked by method calls from other components.

Contains interface definitions for the core server components, including Accounting, Auctioneer, TariffMarket, BrokerProxy, and a number of listener and marker interfaces that are used to control server activity. Also contains a few domain types that are not shared with brokers, including AbstractCustomer, TariffSubscription, and RandomSeed.

Provides accounting services in support of other components, and the tariff market. Cash accounting includes customer billing and payments, tariff publication fees, market settlements, interest on debt, and credits and debits related to taxes and incentives. Market position accounting tracks the current commitments in the wholesale market for each broker. This is needed by the distribution-utility to run the balancing process in the current timeslot. The tariff market receives and validates tariff offerings from brokers, assesses fees for publication and revocation of tariffs, handles tariff subscriptions from customers, and publishes tariffs to customers and brokers.

Activation: Both the accounting service and tariff market are activated once/timeslot (as described in the time management discussion by the competition-control, at which point they work through their respectives queues of unprocessed transactions. Once processed, transactions related to specific brokers will be forwarded to brokers through the broker-proxy, along with a bank statement.

Operates a day-ahead market for trading power between wholesale providers (gencos) and customers.

Activation: The market receives incoming messages called "shouts" through the broker proxy. Each shout represents a sell or buy order for a specific amount of energy in a specific timeslot for a maximum (for buy orders) or minimum (for sell orders) price. Once in each timeslot the market is cleared, and the resulting transactions are posted to accounting through its API.

Responsible for power distribution (which brokers must pay for) and for running the balancing process in the current timeslot. Depending on implementation, the balancing process may involve activation of controls on controllable loads and sources, and buying excess power (at a reduced rate) and selling power to clear deficits (at an inflated rate) from/to brokers in each timeslot to achieve overall balance between supply and demand.

Activation: This component is activated by the competition-control as part of the per-timeslot activities. Transactions are forwarded to accounting to update bank balances, and then forwarded to brokers. The balancing process is described in the game specification and in a detailed story on balancing.

Models a function of a distribution utility in a market that is being liberalized to include competitive brokers. It does this by offering default tariffs that are presumably relatively unattractive to customers. At the beginning of a simulation, all customers are subscribed to these default tariffs. One of the primary responsibilities of competing brokers is to attract customers away from these default tariffs.

A secondary function of the default broker is to collect bootstrap data during a bootstrap simulation. During a bootstrap run, the default broker is the only broker available. It collects the customer usage data, market price data, and weather data during the bootstrap period and saves it to a file. This file can then be pulled in at the beginning of a normal simulation and sent to all brokers to bootstrap their models.

Activation: The default broker acts as a normal broker, receiving and sending messages through the broker-proxy. Therefore, it depends primarily on common; its dependence on server-interface is limited to the broker-proxy API.

Multiple customer model components may be configured. Each of them must implement the AbstractCustomer interface from server-interface. These are the customer models. In order for this to work, each must use a different package name for its implementation classes, because the configuration file in powertac-server must be able to distinguish them using fully-qualified classnames.

Individual customer-models may be one of two types (although only tariff customers are supported as of November 2011):

• contract customers represent large industrial, institutional, or government entities. They may negotiate custom contracts with brokers, and the models usually represent individual entities.
• tariff customers represent populations that have some common characteristics, such as suburban families, or urban apartment-dwellers. They cannot negotiate individual contracts, but must accept an offered tariff. Customer models participate in the timeslot cycle by generating their power production and consumption quantities, based on weather and tariff terms, and reporting production and consumption through the corresponding TariffSubscription instances (provided by the server-interface component). They participate in the tariff-market cycle by inspecting available tariffs, and potentially switching their subscriptions.

Activation: Customer plugins are activated by competition-controller once/timeslot. They do not receive or originate messages directly; all their interactions are through the APIs of other plugins (such as the weather-service) and through Tariffs and TariffSubscriptions.

These represent external players in the wholesale market, such as large power plants or wind farms. They may be simple simulation models, or they may be conduits for real-world bid data collected from existing wholesale markets.

Activation: Gencos are special kinds of brokers. They send and receive messages through the broker-proxy.

This is the top-level of the simulation server. It contains the main method, structures the overall simulation scenario through competition-control, and manages the simulation clock through its clock-control. It manages external connections and provides logging and message-routing services. It also provides several smaller services, including the broker-proxy and weather-service.

A few of the individual elements of powertac-server deserve a more thorough discussion:

Structures the simulation, through three different mechanisms:

• Controls startup and shutdown of individual simulations. Each simulation starts up in two phases, called "pre-game" and "game". During the pre-game cycle, the logger is started, all the parameters for the simulation are determined (simulation length and speed, time period being simulated, and the setup parameters for all the components. Once the pre-game cycle is complete, brokers can log in, and a web interface could potentially be used to examine and adjust these parameters. The game is started after brokers have logged in; the specifics depend on whether the server is running in bootstrap mode.
• Handles virtually all behavior specific to bootstrap and sim modes of operation, although the actual data collection for bootstrap mode is delegated to the default-broker. In bootstrap mode, broker login is not allowed, the number of timeslots is fixed, and the bootstrap-data file is written at the completion of the simulation. In sim mode, the bootstrap data file is read. During pre-game the server environment is checked for consistency with the bootstrap environment (because the bootstrap file may be old, or from a different machine), and the configuration is updated to match the bootstrap environment. When the game is started, the bootstrap data is sent to brokers.
• Implements the basic time-management scheme. This behavior depends on the individual components registering for activation in specific phases. Because the mapping of components to phases is outside the purview of the components, the number of phases and the mapping of components to phases is specified in the server configuration file.

Provides the "ticks" that drive the simulation forward, ensures that the server always completes its work in each timeslot before starting the next, and allows external brokers to pause the clock. The pause feature is included to allow human decision-makers to participate in a competition. The details are described in the "Simulation clock" section of the time management discussion.

Receives messages from brokers and forwards them to server elements that have registered as listeners. Receives messages from server elements through its routing API and forwards them to brokers (which may be remote or local to the server, such as the default broker and the gencos).

Gathers all incoming and outgoing messages from the broker-proxy and forwards them to an internal or external visualizer to allow browser-based viewing of a game in progress.

Provides weather forecasts and current-hour weather conditions during each timeslot. Some customer models will use this information to influence energy consumption (temperature, for example), and production (wind speed, sky cover). Brokers who have subscribed customers that are weather-sensitive will also need this data to predict production and consumption. In most cases, this component will be a proxy for an external data source containing real-world weather and forecast history data.

Activation: This module is activated during timeslot phase processing. Customer instances must retrieve weather reports and weather forecasts through the WeatherService API, defined in server-interface. The same data will be serialized and sent to brokers as messages through the broker-proxy.