PowerTAC Demo Agent Documentation

= Overview =

This material has been obsolete since early 2011.

This document is a guide to help developers use the PowerTAC Demo Agent - GRAILS (PDA-G) as a foundation to develop an agent for the PowerTAC platform.

This is written under the assumption that the developer is familiar with Java and Groovy. PDA-G is developed using the GRAILS framework to take advance of its support in web-based application. Web-based user interface is used to view agent status and control agent behavior.

Advantages of using PDA-G for developing an agent:
 * Easy to add support for new messages from server
 * Easy to register of message handlers
 * Easy to add phase activation tasks
 * Easy to send message to server

The main goals are flexibility and ease of use. These would allow developers to concentrate on agent domain-specific behaviors without dealing with low level details in the communication layer.

There are two main events that could trigger agent action:
 * 1) A particular event from the server. This is in form of JMS messages coming from the server.
 * 2) Phase activation. This is a way to introduce periodic trigger for agent to perform processing at the beginning of each timeslot. Phase is used to maintain processing order of the registered tasks.  Agent can register tasks to be performed in each phase.  The number of phases in PDA-G is defined in the configuration file. Timeslot is kept in synch with server via server time management messages.  System (agent's host OS) time is required to be managed with Network Time Protocol (NTP) service to maintain synchronization with server time.

An additional source of event could be from interaction with the agent's web-based UI.

Communication with server
Agent makes web service (WS) call to authenticate with the server using username and password. The WS call will response with URL to JMS server and agent's JMS destination name (queue name). After login, communication between server and agent is over JMS messages.

Structure
+ grails-app/ + conf/ - BuildConfig.groovy - Config.groovy + spring/ - resources.groovy + controllers/                                                  Agent's web controllers + domain/                                                       Agent's domain classes + i18n/ + jobs/ + views/ + services/                                                     Agent's services + src/ + java/ + groovy/ + api/                                                        API classes + core/                                                       Core package + exceptions/                                                 Exceptions classes + infrastructure/                                             Messaging and persistence infrastructure + interfaces/                                                 Interfaces + test/ + unit/ + integration/ + web-app/

Each component of an agent is wired up using Spring allow easy replacement of different implementation in resource file grails-app/conf/spring/resources.groovy. For example, default messagePersistenceManager uses hibernate/GORM to manage persistence. Developer could implement persistence manager that store data using a different method and replace messagePersistenceManager bean with the new class. Similar concept applies to other agent components.

Note: Auto-wiring is done by GRAILS on GRAILS controllers, services, jobs but not in classes in 'src' directory. Auto-wiring for classes in 'src' directory is accomplished by 'resource.groovy'

grails-app/conf/spring/resources.groovy
= Getting started =

From github
Repeat Step 2 for
 * 1) cd /your/target/checkout/directory
 * 2) git clone git://github.com/powertac/powertac-demo-agent-grails.git
 * 1) git clone git://github.com/powertac-plugins/powertac-common.git
 * 2) git clone git://github.com/powertac-plugins/powertac-db-stuff.git

Running agent in developement mode
Note: currently, all dependency modules have to be checkout as sub-directory under one directory.

1) Start an instance of the server (instruction on how to download server at )

% cd powertac-server % grails run-app

2) Start an instance of the agent (specify server.port so it would not conflict with server if server is running on the same machine)

% cd powertac-demo-agent-grails % grails -Dserver.port=9090 run-app

3) Browse to http://localhost:9090/powertac-demo-agent-grails and perform login for agent to server

4) Browse to http://localhost:8080/powertac-server to get to server web dashbard to perform server function (e.g. start competition)

Registering to event from server
The simplest method to register to an event (message) from server is to implement MessageListenerWithAutoRegistration interface. The implementation would have a getMessages method that returns a list of interested message types and an onMessage for each of the interested message type. An example is MarketMessageListener.

Registering to phase activation
The simplest method to register with phase activation is to implement TimeslotPhaseProcessorWithAutoRegistration interface. The implementation would have a getPhases method that returns a list of interested phase and an activate method that take in a Instant object and a phase number that would be call when each of the interested phase is activated. An example is ShoutRequestService.

= Sample code =

ShoutRequestService
= Reference material = ./services/org/powertac/broker/GameStateService.groovy                       Service for retrieve/update GameState ./services/org/powertac/broker/PauseActionStateService.groovy                Service for pausing game functionality ./services/org/powertac/broker/TimeslotPhaseService.groovy                   Service for time slot phase activation ./services/org/powertac/broker/CashPositionService.groovy                    Service for retrieve/update CashPosition ./services/org/powertac/broker/ConnectionService.groovy                      Service for connection management ./services/org/powertac/broker/JmsManagementService.groovy                   Service for JMS management ./services/org/powertac/broker/AutoLoginService.groovy                       Service for auto login functionality ./services/org/powertac/broker/ShoutRequestService.groovy                    Service for requesting shout ./services/org/powertac/broker/CompetitionManagementService.groovy           Service for managing competition ./services/org/powertac/broker/TariffPublishingService.groovy                Service for publishing tarifff to server ./jobs/org/powertac/broker/LoginJob.groovy                                   Task for auto login ./jobs/org/powertac/broker/ClockDriveJob.groovy                              Task for time slot management ./conf/UrlMappings.groovy                                                    Url mapping configuration file ./conf/BootStrap.groovy                                                      Bootstrap file ./conf/Config.groovy                                                         Project configuration file ./conf/DataSource.groovy                                                     Datasource configuration file ./conf/BuildConfig.groovy                                                    Build/dependency configuration file ./conf/QuartzConfig.groovy                                                   Timer service configuration file ./conf/spring/resources.groovy                                               Spring resource file ./domain/org/powertac/broker/ShoutRequest.groovy                             Domain class for ShoutRequest ./domain/org/powertac/broker/PauseActionState.groovy                         Domain class for PauseActionState ./domain/org/powertac/broker/GameState.groovy                                Domain class for GameState ./controllers/org/powertac/broker/ShoutRequestController.groovy              Web controller for ShoutRequest ./controllers/org/powertac/broker/StatusController.groovy                    Web controller for conntection/login status ./controllers/org/powertac/broker/TariffPublisherController.groovy           Web controller for tarriff publishing ./controllers/org/powertac/broker/ConnectionController.groovy                Web controller for connection management ./controllers/org/powertac/broker/GameStatusController.groovy                Web controller for game status

= FAQ =

The web interface is only there to help with ease of agent development. Agents could be developed without using the web interface.
 * How to run a non-web-based agent?

Agent behavior can be controlled with both asynchronous events and periodic events. * Asynchronous events come from messages from the server such as TariffSpecification, Orderbook, etc. * Periodic events come from registered tasks to be executed for each timeslot.
 * What relevant source files control the demo agent's behaviour?

agent? Kang, P. "Software Architecture of the TAC Energy Trading Broker", August 5, 2010
 * Any other recommendations for getting started tuning / developing an