Using the Grails Prototype

You may also be interested in Documentation on the Grails-based demo agent.

Updates to Release 0.4, July 2011
On 11 July 2011 we make available a set of updates to the 0.4 release. Most of the notes for 0.4 still apply; the most important changes are a dramatic improvement in performance, a much improved format for customer bootstrap load data, significant improvements to the demo broker, and several smaller bugfixes. The download script is designed to install over the top of an existing 0.4 installation, but it will download everything if you run it in an empty directory.

Release 0.4 (Pilot), early July 2011
Although we may release bugfixes and one or two new features before the pilot competition on 17 July, we expect this to be the last release before the 2011 competition. It incorporates a number of bugfixes and new features over the 0.3 version. This version is downloaded using a new script. It works very much the same way as the 0.3 script, except you do not need to specify the version - it is version-specific.

Download the release package
To pull down the release package (16 modules), follow these steps (examples are for a unix or cygwin shell):


 * Create a new empty directory (we'll assume you call it powertac-0.4) and copy the script to this directory.


 * Move to the directory and run the script. On Windows you will need to download GNU tar and add it to %PATH% in order to properly extract the downloaded Github tarballs.


 * The script takes a minute or two and reports its progress; make sure there are no errors. It works to run the script again over the top of an existing installation; that will simply replace the current contents of the module directories with fresh copies from github.

Running the server and agent
The server and agent work the same way as in the previous release 0.3 - see below for details.

Release notes
There are a large number of enhancements and bugfixes in this release. The performance is improved somewhat, although this is an area that still needs some work. It is now safe to run the clock with a timeslot interval of 6 seconds or less (corresponding to a simulation rate of 600); if processing takes longer than the configured interval, the clock is paused and a SimPause message is sent to brokers. A SimResume message is sent, along with a new simulation start time, when the clock resumes. You should expect to see this happen once every 24 timeslots as the customer model recomputes its load profile. Other enhancements include


 * The Distribution Utility now charges a distribution fee per kwh, and it charges for balancing according to Scenario I as defined in Section 2.6.2 of the current game specification.
 * The server can run multiple games without quitting and restarting.
 * The broker will automatically log in if you include the option  on the command line, or if you add the line   to Config.groovy.
 * When a game starts, the server opens and writes to a new log file with a name taken from the ID of the Competition instance.
 * Before starting the simulation clock, the customer model runs for two simulated weeks under the terms of the default tariff. The observed load is then provided to brokers before starting the clock. However, the data is simply packaged as a list, not as a proper object type. We expect to fix this with an interim release.
 * The beginnings of a customer price-elasticity model is in place and working. You should see some load shifting with a Time-of-use tariff.
 * The orderbook representation is changed and should be correct and much more understandable.
 * The beginnings of a game visualizer are in the package, but it's not yet much to look at; this is a major thrust of our planned work over the final days leading up to the competition.
 * A broker can request a pause in the simulation clock by submitting a  message to the server, and resume the clock with a   message. This is intended as a debugging tool, and will help with research into mixed-initiative brokers with user interfaces.

There remain a few issues that limit what a broker can do in this version, including:


 * Weather forecasts are not available - weather reports are implemented, but forecasts are not yet working.
 * Customer model does not model controllable sources/loads - we are working on this, but it's not ready.
 * Documentation for broker and customer model are still very weak - you should see a new broker developer's guide very soon.

Please do not hesitate to let us know if you see other problems or if you have suggestions for improvement through the developer's mailing list. You are of course free to browse the open issues and related discussions on our github development site as well.

Release 0.3, mid-June 2011
For this version, we have developed a script that downloads all the server components along with the demo broker. You do not need to install or use git, but you will need working installations of groovy and grails. See the developer's Getting Started page for setup instructions and links. This script currently depends on tar to expand the tarballs, and it has not been tested on Windows. It should work without problems on Linux and OS X, and it should work on Windows after you install GNU tar (see below). If someone knows how to eliminate the dependence on tar, please let us know.

Download the release package
To pull down the release package (16 modules), follow these steps (examples are for a unix or cygwin shell):


 * Create a new empty directory (we'll assume you call it powertac-0.3) and copy the script to this directory.


 * Move to the directory and run the script, giving the release ID as an argument. On Windows you need download a version of GNU tar and add it to %PATH% in order to properly extract the downloaded Github tarballs.


 * The script takes a minute or two and reports its progress; make sure there are no errors. It works to run the script again over the top of an existing installation; that will simply replace the current contents of the module directories with fresh copies from github.

Run the server
To start the server, simply enter the powertac-server directory and use the command. This will resolve dependencies, compile all the code, and start the server on localhost:8080. Once it is running, you will see the line

in the console. If you browse to this address, you will see a web page that allows you to modify some aspects of the server configuration, and to start a new simulation. The default configuration runs a simulation of just 96 hours, to facilitate testing.

While the server is running, it writes to a log file in logs/powertac-server.log. If you start a simulation and watch the log, you will see evidence of most server processes as they run.

Note that the first time you run the server it must download and compile a number of plugins; this can take some time. The downloads and much of the compiling actually happens in $HOME/.grails, which in some computing environments is a network drive. In this case, the wait can be quite long. You can override this default setting by editing the file  in both the   and   directories, adding the line.

Run the demo agent
The directory  is an agent framework, written in grails, that incorporates all the necessary message handling and time-keeping to interact properly with the server. To run the agent on the same machine with the server, it's necessary to force it to use a non-standard port for its web front-end. Do this as

and wait for its server running message. To connect the agent to the server, start the server first, but don't start a simulation. Then start the agent and log it in from its web page (by default, the server ignores the agent's password; you can just leave it blank). Finally, configure the server (poke the "default competition" entry and edit/save it) and start it (poke the "dashboard" entry and start the competition). Once the server is running, you can use the broker's web page to submit a tariff, then watch its progress through the server. Note that new tariffs are by default published once every 6 timeslots.

PowerTAC Demo Agent Documentation

Release notes
This package is far more capable than the 0.2 release from May, but there remain a few missing features and odd bugs that we are aware of. In the following, we give the Github issue number for each issue:


 * Server performance is inadequate - we have the timeslot interval set to 12 seconds, which means a full game would take over 4 hours. Our goal is to get it down to 5 seconds.
 * Load and price profiles are not available at the start of a simulation - this is fairly essential bootstrap information for a broker, and it's not yet working.
 * Balancing is very primitive - the Distribution Utility does not yet implement even the "static" balancing scheme outlined in the game specification. We hope to have this working in an interim release very shortly.
 * Weather forecasts are not available - weather reports are implemented, but forecasts are not yet working.
 * Customer model does not effectively model price elasticity - this feature is coming along nicely, but it's not yet ready.
 * Customer model does not model controllable sources/loads - we are working on this, but it's not ready.
 * Orderbook does not correctly separate bids and asks - the Orderbook abstraction produced by the wholesale market is supposed to contain a list of un-cleared bids and a separate list of un-cleared asks, but instead it includes all uncleared bids and asks in both lists.
 * Server does not completely recycle after the end of a simulation - it does dump its database, but you cannot start another simulation without restarting it.
 * Visualizer is not displayed - the server's game visualizer is incomplete and does not currently display.
 * Pause mode not implemented - the server's clock moves ahead relentlessly. A goal is to allow it to pause, either because a GUI-driven broker needs more time, or because some server process cannot meet the timeslot time-limit. This should mostly address the performance problem.

Release 0.2, mid-May 2011
Because the development team is still actively developing, we have not yet packaged the Power TAC server plugins to be automatically resolved by maven. Therefore, you will have to use the release branch in development mode, which means you need to install git and download each component from its github repository and checkout the correct branch. With a git command-line tool, you do this as git clone https://github.com/powertac/powertac-server.git git clone https://github.com/powertac-plugins/powertac-common.git ... etc. ... There are a number of git clients, either embedded in tools like Springsource STS (a custom-packaged version of Eclipse) and IntelliJ, or command-line or GUI clients.

You will need to install Grails 1.3.7 before you can run the server or the demo agent.

To retrieve the server, you will need the server and 12 plugins, each cloned into parallel directories. Instructions for downloading and setting up the server as a developer are given in the developer's wiki on github. If you follow these instructions, you will have the development branch, not the release branch. We attempt to keep the development branch reasonably stable, but we cannot support it for non-developers. To get to the release branch, you will need to check out the branch release-0.2 in each of the component directories. Using the command-line version of git, this is accomplished by git checkout release-0.2 Once you have done this, you should be ready to start the server.

In addition to the server, there is a simple Grails-based demo agent that runs the communication protocol and provides a simple web interface to the underlying data model.