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 the runserver, you can start the tomcat server.

Go to ​​http://localhost:8080/runserver-X.Y.Z (replace X.Y.Z with the version you installed). You should get this page

If you have also installed the ​partiesserver and ​profilesserver you can now start a session or tournament, view the currently running negotiations and view the logs.

Running a Session

The GUI varies slightly, depending on the protocol that you select. We discuss the variants here.

SAOP

To run a SAOP 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. You can also change the URL halfway the setup process if you want to use multiple partyservers, eg also the pypartiesserver.
• 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.

MOPAC

If you run a MOPAC setting you get some additional options

• You can select a ​Voting Evaluator.
• With MOPAC you can use the power parameter to indicate a party's power
• Many parties that support MOPAC have parameters to control the voting behaviour.

With these settings, the conceder gets power 2 and therefore having him accept your offer helps a lot. Also randomparty sets minPower which means its votes are only valid if at least total power of 3 is reached. Because it is difficult to reach a deal with multiple parties, the most likely outcome for randomparty will be a deal with conceder.

SHAOP

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)

Learn

A learn session is special, because no negotiation is done during this session. Therefore, you can not select any profiles. You should provide the parties their 'persistentstate' and 'negotiationdata'. The GUI already adds these to the parameters, but the values probably should be fixed to the values you used in the earlier sessions.

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 available only after the session completes, because this information could be abused by the negotiating parties.

At the bottom of the plot is a message "Agreement:X" where X can be 'yes', 'no' or 'partial' (or '?' if the protocol is not fully supported by the plotter).

The MOPAC protocol shows the utilities of the offers made by the parties. In each round, all remaining parties place an offer (in non-deterministic order) so as the negotiation progresses less and less parties make subsequent offers. In negotiations with many parties and partial deals it may be necessary to check the log file for further details about what happened in the negotiation.

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.

• The left column shows the session number, starting at 0. The 'A' behind it means the first agreement from this session (some protocols allow multiple agreements in a single session).
• The second column shows the bid that was agreed on.
• The third and further columns show, for each party, the utility of that agreement (or 0 if the party did not accept that bid), the penalty of that party (0 if it did not receive a penalty), and the name of the party.

So the 6A in this example is the first ageement and 6B is the second agreement from this session. In 6A, only parties 1 and 2 agreed on the bid, in 6B parties 3 and 4 agreed on that bid. If there is no agreement at all, an row will be showed without agereement bid but just the party utilities.

Tournament with Learn

If you run a tournament with Learn, the GUI remains almost unchanged, except for a Learning Time field at the top. Here you can select a separate deadline time for the learn session.

In Tournament with Learn, all parties must be provided a persistentstate UUID. The GUI adds this to the parameters, with a random new UUID. You may want to change thes to previously used UUIDs if you want to learn over multiple tournaments. The tournament runner will generate negotiationdata parameters for each session, and all the generated parameters will be added to the final Learn session.

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 existing 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.

The service returns a unique ID which is used to name the log file for this run.

This service dumps information into a log file after each session. For a session, the entire final SessionState is written to the log file. For a tournament, a SessionResult (see SessionState#getResult) is apended to the log file after each completed session.

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/pub/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.