Getting started with the Power TAC simulation server

The instructions on this page are for those who wish to operate the Power TAC server in a source environment, either because you wish to modify or add on to the server, or you intend to develop a broker in the server environment (more on that soon), or you simply want to have access to the source. Keep in mind, though, that the source is linked into the online documentation. This may be more convenient than viewing it in Eclipse.

If you do not need source, you can operate the server from a binary release or snapshot distribution.

Prerequisites

• Required software
  • JDK 1.11 or higher
  • Maven 2 (maven 3.6.3 or higher)
  • git (2.17.0 or later)
• Optional software
  • A decent IDE, preferably one that knows how to work with Spring, AspectJ, and Maven. Most of us use the Springsource tool suite STS, a packaged version of Eclipse.

Recommended reading material

• Walls, Spring in Action, 3rd edition, Manning, 2011.
• Git book
• O'Brien et al., Maven by Example
• Mockito documentation
• Power TAC development standards and policies

Downloading the server

Note that this is for a development setup. The entire process is mostly automated with Git and Maven.

There are 21 modules that are needed to run the server, grouped into two aggregates: powertac-core and powertac-server. The powertac-core modules contain code used in both the server and in brokers. Keep in mind that you only need to pull down the server-distribution package if you simply want to run the server. You should need to pull down powertac-core only if you want to edit something in it, because maven will otherwise treat these modules as normal library dependencies. For each one, you can download the code with git clone. Note that git urls come in (at least) two flavors, and the ones given here are the standard http urls of the form https://github.com/powertac/module-name.git. You can also use a url of the form [email protected]:powertac/module-name.git to get a read-write clone using ssh. The advantage of the ssh protocol is that you don't need to supply a username/password to push changes, assuming you have set up your public ssh key in your github account.

• powertac-core: git clone http://github.com/powertac/powertac-core.git - you don't need this unless you want to look at the code or you need to make changes. Otherwise, maven will download the binary for you when you build the server, or when you compile an agent that depends on it. You can make the server use your local version of the powertac-core modules with mvn clean install from inside the powertac-core directory. This will place them in your local maven repo.
• powertac-server: git clone https://github.com/powertac/powertac-server.git - this is the server and all its modules outside powertac-core. As with the core modules, you can do a local install using mvn clean install inside the powertac-server directory. You can generate your own javadocs with mvn javadoc:aggregate; the generated html will show up in target/site/apidocs.
• server-distribution: This is needed to run the server from the command line; otherwise you can run it from inside STS. Unless you want to change this module, it's easiest to just download the zip file.

Once you have downloaded the modules to a directory of your choice, you need to go into your IDE and import individual projects. In STS, it's simply File->Import->Maven->Existing Maven Projects and choose the module(s) you are interested in. When you import the server, it will create a number of additional projects for you, one for each of the modules inside the server super-module. After everything settles down, it seems to be necessary to select powertac-server and then do right-button->Maven->UpdateProjectConfiguration. Let it do all of them.

Updating the server

Once you have a source setup and have been using it, you may want to periodically pull down updates from github. If git complains about local changes, you may need to stash or revert those changes (use git checkout -- filename to revert an individual file or `git checkout -- . to revert an entire directory tree) before git will pull down an update.

Building the server

If you have "Build Automatically" set in STS, the server will already be built at this point, and can be run inside STS. If your IDE is not set up to build automatically, try right-button->Run as->Maven build.

If you want to be able to run the server outside STS, through the command-line for example, you can either use the currently-deployed version of the current snapshot, or you can do a local install. You do that with mvn clean install in both powertac-core and powertac-server.

Running the server

The server runs the Power TAC simulation in two modes:

1. 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.
2. 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.

If you want to use a web-based gui to control the server, you can use the visualizer. Instructions are in the server-distribution README.md. We recommend using the web2 profile, because the code underlying the web profile is badly out of date and will eventually be dropped.

For most testing purposes, it often makes more sense to run the server from the command line. The easiest way to do this is to use the server-distribution package, which contains a pom.xml that automates the process. Instructions are included in the package. Otherwise, the main class is org.powertac.server.PowerTacServer in the server-main project. Command-line arguments and other configuration details are described on the Server-configuration page.

Setting up a run configuration in Eclipse/STS

Some folks have had trouble figuring this out. Here is the step-by-step:

• In STS, poke Run->Run Configurations.
• In the dialog, choose Aspect/Java application in the left-hand panel, then poke "new".
• Give the run configuration a name, like "server bootstrap".
• The project is server-main, the main class is org.powertac.server.PowerTacServer.
• Under the arguments tab, you need to specify the program arguments. For a bootstrap session, it would be --boot bootstrap.xml to write a bootstrap data file called "bootstrap.xml". For a sim session, the arguments are something like --sim --boot-data=file:bootstrap.xml --brokers=Sample1,Sample2 --config=file:cfg.props to load the bootstrap data file bootstrap.xml, override some system config properties from the file cfg.props (this is optional), and wait for brokers Sample1 and Sample2 to log in.
• Finally, under the Common tab, you can choose to have the new run configuration show up in the debug and run menus. It should also allocate a console and run in the background, but those should be the default settings.

Running the server outside of STS

If you want to run an agent in STS, it can be useful to run the server as a separate process or on a separate machine. You can do that with a released version of the server, of course. but it is also very useful to be able to do it with a development version.

The server is run with maven, so maven can manage dependencies and build the classpath. To run a development version of the server using maven, you need to first install powertac-core if you have chnaged it, followed by powertac-server. If you change anything in powertac-core, you will need to re-install both powertac-core and powertac-server. If you change anything in powertac-server, in general you need to re-install powertac-server (rather than the individual module) to ensure that transitive dependencies are satisfied. Once the necessary pieces are installed, you can go to the server-distribution directory and run it. Instructions are in server-distribution/README.md.