GeniusWeb RunServer

This is the homepage of the GeniusWeb run server.

The GeniusWeb main page is ​here.

The run server can run sessions and tournaments as specified.

Installation

• Install your apache-tomcat 8 installation ​​https://tomcat.apache.org/download-80.cgi. You can re-use an existing installation.
• Download the runserver war file from ​the artifactory. Go into the latest version of the runserver and download (right click) the war file. NOTICE: your browser must have cookies enabled to access the artifactory.
• Copy the downloaded war file into the tomcat webapps directory
• (Re)start tomcat

After (re)starting tomcat your local profilesserver should be up and running.

Upgrade

To upgrade,

• Stop tomcat
• remove the old war file plus the unzipped version (if exists) from the tomcat webapps directory
• repeat the installation as above

Using the GUI

After installing and starting, go to ​​http://localhost:8080/runserver-X.Y.Z (replace X.Y.Z with the version you installed). You should get this page

From here you can start a session or tournament, view the currently running negotiations and view the logs.

Running a Session

To run a session using the new-session GUI :

• Go to ​​​http://localhost:8080/runserver-X.Y.Z (replace X.Y.Z with the version you installed) and click on "new session".
• If you get the message "server closed the connection" this indicates that the profilesserver and partiesserver URLs are not valid
• If necessary, enter a valid profilesserver URL in the domain/profile server field
• If necessary, enter a valid partiesserver URL in the parties server field
• Inside the Participants area, select the party and profile for the first party
• In the Parameters area, you can add optional parameters, like "a":1,"b":"false" .Basically a json dictionary where the outer curly brackets are already placed for you.
• click add
• Repeat that until all parties have been added.
• Press the "Start Session" button.

When running a SHAOP session, you need to be careful with a number of settings. See also the image below:

• Select the SHAOP protocol
• Use a small number of rounds, this is what the protocol is designed for. Log files can get very large if you use a time deadline only.
• You can select either a SAOP or SHAOP party.
• We recommend to leave the "advanced COB settings" off as usually the automatically generated comparebids party with the same profile but without the filter is exactly what you need. The COB party is only called by SHAOP parties but the GUI always requires you to enter a COB party (also if you use a SAOP party). In the picture below, you can see that we have party 1 a conceder, but the comparebids party is there anyway.
• You should assign a partial profile to SHAOP party. For testing we recommend to use a reference to a utility space (eg, a linear-additive space) and to filter it with "partial=10". Most normal SAOP parties can not handle such partial spaces, so you normally do not filter their profile (In the picture, there is no "partial=10" applied to the jobs1 profile).

Figure. Settings for playing conceder (jobs1) against SHAOP (jobs2?partial=10)

Showing the results of a session run

Some time (depending on the deadline you set) after starting your session, links are provided to the log file, and to a visualizer that can plot the utilities of the bids recorded in the log file.

You can also view the log files later, through the "View logs" option in the main menu of the runserver.

If you click on "view the log file" you get an exact log of all the actions taken by the parties. Notice that in the SAOP protocol, this log file becomes available only after the session has been completed.

You can click on "render a utilities plot" to show a graphical representation of the utilities of all the offers made in the session, as in the figure below. Notice that this is only possible if (1) the log file is already available (2) the profiles are publicly available (3) the profiles are a UtilitySpace.

If you ran a SHAOP session, the plotter tries to show the utilities of the SHAOP parties in the negotiation as they place the real Offers. However the SHAOP party uses a partial profile without utility function. The plotter tries to be smart here: if the profile is a filtered utilityspace of the form "URL.?partial=N" it removes the "partial=N" filter option and uses the unfiltered profile for the plotting. It should be clear that these utilities have no real meaning in the partial profile that the SHAOP party is using, but the partial profile will normally get the utilities sorted corresponding to this original profile.

The information made available about the running session is determined by the protocol. For SAOP, there are currently two ways to check the progress on the running session

• Check the output of the tomcat web server (eg in catalina.out)
• Check the log files written by the protocol.

In general log files are not directly available, because this information could be abused by the negotiating parties.

Run a Tournament

To run a tournament using the new-tournament GUI :

• Go to ​​http://localhost:8080/runserver-X.Y.Z (replace X.Y.Z with the version you installed) and click on "new tournament".
• Select the Number of times to repeat the entire tournament.
• Select N: the number of teams in each session.
• enter a valid profilesserver URL in the domain/profile server field.
• Inside the Profiles area, select a profile in the Profile combobox and click add
  • If you selected the SHAOP protocol, the first team member is the SHAOP party which requires a partial profile. It is convenient to use a normal profile and add partial=N as filter for this profile. You also have to select the COB party profile that normally requires a linear-additive profile, so inormally it's the same profile but now without the filter.
• Repeat the last step until all needed profiles have been added. Give at least N profiles
• enter a valid partiesserver URL in the parties server field
• Inside the Parties area, select a party in the Party combobox and click add
  • If you selected SHAOP protocol, you can provide a parameter "elicitationcost" if you want elicitation cost different from 0.1. You also need to add the COB party. The team members always will stay together when the sessions are generated. You can also use s SAOP party for Party, but you need to make sure that this party can handle the partial profile.
• Repeat that until all teams have been added. Give at least N teams (N is the number of teams in each session as you set above)
• Press the "Start Tournament" button.

When the tournament is started, you get an option at the bottom of the screen "show results table". If you click this option, you get a screen showing an overview of the results. This overview tries to access the original profiles and compute the utilities of the final bid. If there was no accepted bid, the results table shows the utility of the reservation bid in the profile.

Using hard coded profiles

As mentioned on ​the profilesserver wiki page you can easily generate a partial profile out of an existing utilityspace by using a filter option. A big advantage of this is that the result plotters can hack out the filter option and use the utilityspace that the profile was generated from to show "hypothetical" utility values. However there are reasons not to do this, for example

• A party getting the URL can equally easily hack out the filter option to gain access to the utilityspace
• Every time a websocket is created to the URL, a new, different filtered profile is generated. This may not fit the use case.

Of course, profiles can also be written by hand to avoid this. However if that is done, the result plotters can not apply this convenient trick anymore.

If you want a hard fixed profile but keep the trick used by the results plotters to remain working, an easy hack can be applied:

• create the utilityspaces that reflect your idealized/hypothetical profile to be used by the result plotters
• ​Download filtered profiles programmatically or write them by hand and store these on the server under a hashed name preventing recovery of the utilityspace name.
• run the parties with these hashed profiles
• after the run completes, manually edit the log files, replacing the hashed profilename with the original utilityapsce name. Make sure you make a backup of the log file, in case you screw up the replace.
• view the modified log file using the existing-log viewer

Visualizing results in older log files

To visualize an existing log file you can ues the following:

• To visualize a APP file, use ​http://localhost:8080/runserver/utilstable.xhtml?APP where you use the correct APP number (no 'json' extension)
• To visualize a SAOP or SHAOP log, use ​http://localhost:8080/runserver/plotlog.xhtml?id=SAOP where you use the correct S(H)AOP number (no 'json' extension)

The source code

You can read the source code through the "Browse source" button at the top of this page. You can check out the source code through svn with

svn checkout https://tracinsy.ewi.tudelft.nl/pub/svn/GeniusWebRunServer/

Communication protocol

This section deals with the communication protocols with the runserver. These may be relevant when you need to communicate directly with it, e.g. when you build your own GUI or start up your own sessions and tournaments from a script.

Other implementations of a runserver should adhere to the same communication protocols to ensure compatibility with GeniusWeb.

Run Negotiation

This section describes the RunNego​ service. It is available at http:..:8080//runserver/run. This service starts up and runs a complete Nego (session or tournament) when it is accessed (http get or post). To start a negotiation, the http get must include a JSON-serialized ​geniusweb.protocol.NegoSettings header.

The contents of NegoSettings depends on the type of session/tournament that is to be run and is determined by the protocol. For some more discussion please refer to the ​GeniusWeb core wiki page.

View Running Negotiations

The websocket address ws:..runserver-X.Y.Z/websocket/running sends updates of the current list of running negotiations. The list is sent as a JSON List of strings, each string being the negotiation ID of the running session. Every time the list changes, a new complete list is sent to clients listening to the websocket.

Viewing the outcome of a negotiation

Logs are available through http:..:8080//runserver-X.Y.Z/log. The filenames are the Negotiation IDs extended with ".json". The negotiation ID consists of the protocol name (SAOP, SHAOP, APP) followed by a serial number.

A log file usually is created only after the negotiation (session or tournament) completed. Protocols may opt to write these more frequently but since these logs are public they could be abused by parties, to see what their opponents are doing.

General server info

available at http:..:8080//runserver-X.Y.Z/info Returns a map with server details. Currently contains the runserver version number, eg {"version":"1.4.0"} . The version matches the runserver maven POM version.

Using the source code

You can download the source repository of rhe java implementation. Note that you don't need this if you just want to use the run server to run sessions or tournaments.

svn checkout https://tracinsy.ewi.tudelft.nl/svn/GeniusWebRunServer/

Since this is a tomcat web application, you need Eclipse Enterprise edition if you want to run this from Eclipse. Also, to checkout from Eclipse, you need to prepare Eclipse for this. Check ​https://tracinsy.ewi.tudelft.nl/pubtrac/GeniusWeb

It is maven based so you only need maven to compile the code.

Troubleshooting

• services accessible on 'localhost' but fetching profiles or starting parties does not work. When you go to localhost:8080/partiesserver , and copy one of the party URIs in the browser, you do not get ws://... as response
  • This behaviour can be cuased by java being unable to resolve the correct IP address of your machine
• Java sometimes can not resolve the machine IP address properly
  • This may happen if nslookup returns multiple IP numbers, in which Java seems to pick one at random, causing random failures.