Getting Started

This page is intended to help agent developers get started with the Power TAC server and agent framework. Please feel free to add your experiences and insights to the Discussion page (note that you may need to log in to edit that page).

There are currently two main components needed by broker developers: the simulation server (.zip or .tar.gz), and the sources for the sample broker (.zip or .tar.gz). Release notes and download links for older released versions are available on the Release History page.

If you would prefer to use development snapshots rather than a released version, you can download them from github: the simulation server snapshot is distributed as a maven pom.xml file, while the sample broker snapshot is distributed in source form. Both include detailed README files to help you get started. Note that the sample broker on github is the HEAD of the development branch, while the server will pull in the latest development snapshot, which is usually more stable than the tip of the development branches of all the components.

If you wish to modify or contribute to further development of the simulation server or the sample broker, please read throught the Getting Started and Development Policies pages on the Power TAC github wiki.

In addition, you may want to download the Power TAC log-analysis tool.

Sample Broker

At the time of this writing, the only available implementation of a Power TAC sample broker is in Java. Others, including a Repast framework, are on the agenda but awaiting a volunteer to take responsibility.

The sample broker, like the Power TAC simulation server and the tournament manager, is a Spring application. It can be run from a command-line using Maven, or it can be run from a development environment like STS, the Spring Tool Suite. STS is Eclipse with a number of additions specific to Spring. Other IDEs can also be used if you prefer, but STS is what most of the server development team uses, with the result that there is help available within the Power TAC community.

Building and running the sample broker

To run the broker, you can either use or the IDE of your choice, or you can use maven at the command line. The main class is org.powertac.samplebroker.core.BrokerMain. Details on command-line arguments are in the README file.

The recommended way to use the sample broker is to acquire and modify the source code. Released source packages are posted on the github download page. The "bleeding edge" of broker development is always available through the sample-broker project on github, for which you will need a git client. Note that you can clone it if you don't want to use git for your scm tool, or you can fork it if you want to share your work on github. As long as you confine your changes to modules outside the core package, you should be able to integrate your work with future releases fairly easily; the development team works hard to maintain backward-compatibility.

All interaction with the simulation server is through xml-serialized jms messages. You receive them by including them in the registration list in the initialize() method (see MarketManagerService.java for example), and then writing a handleMessage() method to process it. You may, of course, add additional message-handling modules simply by following the pattern in the existing MarketManagerService and PortfolioManagerService. Any module that implements the Initializable interface will have its initialize(BrokerContext context) method called at startup. Outgoing messages to the server are sent by calling the sendMessage() method on the context. All the message types are in the common module, specifically in the common and common.msg packages. Javadocs are posted on our Jenkins CI server. You should not need to download the common package; maven will take care of that.

Brokers also need to interact with the Power TAC Tournament Manager, through a REST interface. This interaction is encapsulated in the core.BrokerTournamentService module. The only purpose of this interaction is to acquire credentials and access details for simulation servers that run under control of the Tournament Manager.

If you want to add new top-level modules to the broker, it should be enough to simply annotate them with with @Service ahead of the class declaration, and implement the Initializable interface. MarketManagerService and PortfolioManagerService are annotated this way. This is all the information Spring needs to instantiate it and wire it in through dependency injection.

Power TAC simulation server

The Power TAC simulation server (or just the "server") is designed to be installed and run using maven, a tool that provides a rich dependency-management infrastructure as well as goal-directed build automation. If you do not have a copy of maven 3.0 or higher on your system, you will need to install it. Although it is not absolutely necessary, we recommend that you build your brokers as maven projects as well, or using some other tool that uses maven repositories, such as Gradle. Note that the server release packages are simply maven configuration files with some documentation; all the actual code will be downloaded by maven the first time you try to run the server.

Running the server

The server runs the Power TAC simulation in two modes; detailed instructions are in the README file included with the server distribution package once you have downloaded and unpacked it:

• In "bootstrap" mode, the model runs for a period of time with only the default broker, and collects data on customer power usage, market prices, and weather. This data is saved to a file at the end of the bootstrap period. The resulting data file can be used to run multiple sim sessions.
• In "sim" mode, the model loads a bootstrap data file and restores the model to its state at the end of the bootstrap period, then allows brokers to log in and sends them the bootstrap data before starting a simulation. The simulation literally starts at the end of the bootstrap period, so for example the first timeslot is not number 0, but the number of timeslots in the bootstrap period. Note that not all of the timeslot-related data is carried over from the bootstrap sim - for example, you cannot see the orderbooks from timeslots that completed in the bootstrap period.

As described in the README file, you can run the server as a web-based app under the jetty webserver, or as a command-line app without a visual interface. In bootstrap mode, there is not much to see, and it runs too fast for the visualizer to keep up. However, you can run a bootstrap session using the visualizer to generate the bootstrap data file needed by the full simulator.

Using the visualizer

To run the simulator/visualizer combination, you will need a machine with at least 4 Gb of memory and several Gb of free disk space. Two or more cores will be helpful, although the server, visualizer, and sample broker should not be compute-bound on any reasonably hefty desktop or laptop machine. When you start the server using mvn -P web it will (if necessary) download modules from the maven repository, then start an instance of the jetty webserver containing the server and visualizer. Once jetty is running, browse to http://localhost:8080/visualizer to get started. If you navigate to the "Competition Control" page, you will see a form that allows you to set up and run boot and sim sessions. The top of that page is shown here:

Common options allow you to select an alternate configuration file, and to specify a suffix for naming log files. If you leave them both blank, it will use the default configuration in config/server.properties, and the logfiles will be named log/powertac-boot-0.trace and log/powertac-boot-0.state for a boot session. Since a standard sim runs for about 2 hours, there is a sample configuration file short-game.props provided that will finish in around 10 minutes. You are welcome to edit these files or copy and modify them as you see fit. Details on the various configuration options and what they do are provided in comments in config/server.properties. Keep in mind that some values (like the competition.timeslotLength) may not have the expected effect if you change them, but values like interest rates and fees should have the expected effects.

To run a boot session, scroll down to the boot panel (shown below), fill in the name of the file you wish to have the bootstrap data saved to (for example, boot.xml, and poke the "Run" button. A boot session normally takes less than 5 minutes to complete.

Once you have a bootstrap-data file available, you can run sim sessions. Simply scroll down to the sim panel (shown below), fill in the name of a bootstrap-data file (created by a boot session), add brokers, and start the session with the "Run" button. The server will load the bootstrap data, then wait for the brokers to log in before starting the simulation. Brokers are identified by their "usernames" -- this is the value of the samplebroker.core.powerTacBroker.username property in sample-broker/broker.properties.

If you want to run a broker on a separate machine, you will have to choose a JMS URL that is visible on the network. The default url is tcp://localhost:61616; if you want to use an external URL and you are running on a machine "tardis.powertac.org", the url would be tcp://tardis.powertac.org:61616. This value would also have to be set in the broker's broker.properties file for all participating brokers.

Once all the brokers have logged in and the boot data has been loaded, the Game Status indicator at the top of the page will change to "running" and you can poke the Game View link to see the visualizer display. In the visualizer display, the wrench icon brings you back to the competition control page.

Using the command-line interface

For many testing purposes, it makes more sense to run the server from the command line. Detailed instructions are given in the README file.

Understanding the log files

As the server runs, it dumps data to two log files, known as the trace log and the state log. See the Logfile Analysis page for details on interpreting this data.