Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
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.
- Required software
- JDK 1.8 or higher
- Maven 2 (maven 3.3.x or higher)
- git (184.108.40.206 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 git 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 only 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 --recursive url. 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@example.com: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 key in your github account.
git clone --recursive 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 installfrom inside the powertac-core directory. This will place them in your local maven repo.
git clone --recursive 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 installinside the powertac-server directory. You can generate your own javadocs with
mvn javadoc:aggregate; the generated html will show up in
- 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.
Note that the code loaded with the
git clone --recursive call will not always be up-to-date. This happens because the powertac-server module contains not only the list of submodules, but also the exact MD5 git version id values for each module, and it frequently does not get updated when individual modules are updated. The cure for this is to manually update all the modules. First, check whether any of the modules have the "detached HEAD" status, with
git submodule foreach git status. If you find one, then force each module to the "master" branch with
git submodule foreach git checkout master. Finally, do
git submodule foreach git pull origin master to get the latest version of each module. This should give you the HEAD version from the git repos, which is always the current development version.
Once you have downloaded the projects to a directory of your choice, you need to go into your IDE and import the 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. 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.
Other modules are automatically pulled down by the script. These are the (read-only) URLs if you need 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. You have to pull updates for the powertac-core modules separately from the rest of the server. For the server, pull powertac-server, then run
git submodule foreach git pull origin master inside powertac-server to get updates to all the modules. 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:
- 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.
- 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.xmlto 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.propsto 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.