source: tutorials/MOPAC/tutorial.tex@ 48

Last change on this file since 48 was 48, checked in by bart, 3 years ago

Added java logconverter to add utilities to log results. Fixed
bug in python ProgressTime.
File size: 20.4 KB
Line 
1\documentclass{article}
2\usepackage[margin=1in]{geometry}
3\usepackage{authblk}
4
5\usepackage[utf8]{inputenc}
6\pagestyle{plain}
7\usepackage{eurosym}
8\usepackage[table]{xcolor}
9\usepackage{graphicx}
10\usepackage{enumitem}\newsavebox\fnbox
11\usepackage{hyperref}
12\usepackage{placeins}
13\usepackage{listings}
14
15\usepackage{booktabs}
16\usepackage{caption}
17\captionsetup[table]{skip=10pt}
18
19\newtheorem{exercise}{Exercise}
20
21\newcommand{\code}[1]{\texttt{#1}}
22
23\newcommand{\fbf}{\textbf}
24
25\newcommand{\gw}{\sc{{GeniusWeb}}}
26
27\title{ {\gw} MOPaC Tutorial}
28\author{Wouter Pasman}
29
30
31\affil{Interactive Intelligence, Delft University of Technology}
32
33%define colors for various boxes
34\definecolor{infocolor}{rgb}{0.8, 0.9, 0.99}
35\definecolor{warningcolor}{rgb}{0.99, 0.9, 0.8}
36\definecolor{tipcolor}{rgb}{0.9, 0.99, 0.8}
37
38
39
40\usepackage{courier} %% Sets font for listing as Courier.
41\usepackage{listings, xcolor}
42\lstset{
43 tabsize = 4, %% set tab space width
44 showstringspaces = false, %% prevent space marking in strings, string is defined as the text that is generally printed directly to the console
45 numbers = left, %% display line numbers on the left
46 commentstyle = \color{green}, %% set comment color
47 keywordstyle = \color{blue}, %% set keyword color
48 stringstyle = \color{red}, %% set string color
49 rulecolor = \color{black}, %% set frame color to avoid being affected by text color
50 basicstyle = \small \ttfamily , %% set listing font and size
51 breaklines = true, %% enable line breaking
52 numberstyle = \tiny,
53}
54
55\usepackage{xcolor}
56
57
58% DEFINE JSON LISTING LAYOUT
59\colorlet{punct}{red!60!black}
60\definecolor{background}{HTML}{EEEEEE}
61\definecolor{delim}{RGB}{20,105,176}
62\colorlet{numb}{magenta!60!black}
63\lstdefinelanguage{json}{
64 basicstyle=\normalfont\ttfamily,
65 numbers=left,
66 numberstyle=\scriptsize,
67 stepnumber=1,
68 numbersep=8pt,
69 showstringspaces=false,
70 breaklines=true,
71 frame=lines,
72 %backgroundcolor=\color{background},
73 literate=
74 *{0}{{{\color{numb}0}}}{1}
75 {1}{{{\color{numb}1}}}{1}
76 {2}{{{\color{numb}2}}}{1}
77 {3}{{{\color{numb}3}}}{1}
78 {4}{{{\color{numb}4}}}{1}
79 {5}{{{\color{numb}5}}}{1}
80 {6}{{{\color{numb}6}}}{1}
81 {7}{{{\color{numb}7}}}{1}
82 {8}{{{\color{numb}8}}}{1}
83 {9}{{{\color{numb}9}}}{1}
84 {:}{{{\color{punct}{:}}}}{1}
85 {,}{{{\color{punct}{,}}}}{1}
86 {\{}{{{\color{delim}{\{}}}}{1}
87 {\}}{{{\color{delim}{\}}}}}{1}
88 {[}{{{\color{delim}{[}}}}{1}
89 {]}{{{\color{delim}{]}}}}{1},
90}
91
92% END json listing layout
93
94\begin{document}
95\maketitle
96
97This tutorial will help you using the MOPaC protocol in {\gw}. . It is assumed that you read the \href{https://tracinsy.ewi.tudelft.nl/pubtrac/GeniusWeb/export/HEAD/design/mopac/MOPaC.pdf}{MOPaC protocol description} and
98installed and basic knowledge of GeniusWeb,
99eg from the \href{https://tracinsy.ewi.tudelft.nl/pubtrac/GeniusWeb/export/HEAD/tutorials/SAOP/tutorial.pdf}{SAOP tutorial}.
100
101The main difference between SAOP and MOPaC is the events that parties need to respond to. Also the running of a session is slightly different and the log file contents differ.
102
103
104\section{Creating a MOPaC party}
105Creating a MOPaC party is almost identical to creating a SAOP party (see the \href{https://tracinsy.ewi.tudelft.nl/pubtrac/GeniusWeb/export/HEAD/tutorials/SAOP/tutorial.pdf}{SAOP tutorial}). The differences:
106
107\begin{enumerate}
108\item a MOPAC-capable party has to return "MOPAC" as part of the Capabilities in its getCapabilities function.
109\item a MOPAC capable party has to understand and properly handle MOPAC protocol events and create the appropriate actions. A short outline is on
110\href{https://tracinsy.ewi.tudelft.nl/pubtrac/GeniusWeb#Capabilities}{the wiki page},
111 the details of this protocol are spelled out in the \href{https://tracinsy.ewi.tudelft.nl/pubtrac/GeniusWeb/export/HEAD/design/mopac/MOPaC.pdf}{MOPAC Specification} and
112 \href{https://tracinsy.ewi.tudelft.nl/pubtrac/GeniusWeb/browser/protocol/src/main/java/geniusweb/protocol/session/mopac/MOPAC.java}{MOPAC javadoc}, but briefly:
113 \begin{itemize}
114 \item handle incoming SessionSettings and fetch the profile
115 \item wait for YourTurn and send an Offer
116 \item wait for Voting and reply with Votes
117 \item wait for OptIn and reply again with Votes
118 \item loop back to wait for Yourturn above
119 \end{itemize}
120\end{enumerate}
121
122The RandomParty already is MOPaC capable, so RandomParty can be used as a starting point ot create a MOPaC party.
123
124\section{Running a MOPaC session}
125After you put yuor compiled party on the TomCat server and started the server, navigate to the runserver webpage in your
126web browser. This should be available at a url that looks like: localhost:8080/runserver-x.y.z, where x.y.z is the version of the GeniusWeb server you have installed locally.
127Clicking on the new session link should take you to the Session creation webpage.
128
129\subsection{Options}
130
131Here you have several options that you can tweak. We can broadly divide the options into two categories, the first is the set of options that are chosen for all the parties in the negotiation session. These are Protocol, Voting Evaluator, Deadline, and Domain. The rest of the settings are to be set per party. We discuss each of the options briefly below:
132
133\begin{itemize}
134\item Protocol: This option allows you to set the protocol for the negotiation session. Choose MOPAC since the assumption here is that you would like to run a MOPaC session.
135\item Voting Evaluator: This is method by which the protocol determines which deals form an agreement. There are currently two ways to do this:
136 \begin{itemize}
137 \item Largest Agreement: Using this Voting Evaluation method, the earliest agreement with largest number of parties is chosen as the deal. Here, only 1 agreement is required and the negotiation stops soon after.
138 \item Largest Agreements and Repeat: Rather than stop after the first largest agreement, the rest of the parties that could not reach a consensus try to do so. The negotiation stops when either all parties have a consensus or 1 party is not part of a consensus (unless the deadline is reached, see below).
139 \end{itemize}
140\item Deadline: This is the time period for which the parties will negotiate. The scale of the time period can either be rounds or seconds. Since a second is a relatively large time scale for computers, using the scale of rounds would be easier to comprehend. For the MOPaC protocol, each round comprises of the four phases, namely Bidding, Voting, Opt-In and Termination/Continuation Phase.
141\item Domain: Here, you can choose the domain in which you would like the parties to negotiate. All domains that have been uploaded to the TomCat profilesserver and were parsed correctly are available here.
142\item Party: This allows you to choose the parties that participate in the negotiation from those available on the TomCat server.All parties that have been uploaded to the TomCat profilesserver are available here, but a few of these are not capable of doing MOPaC. Especially notice that randomparty is MOPaC capable but randompyparty is not. You can create, upload and run your own parties to your partiesserver.
143\item Profile: Here, you can choose the profile of the party. This describes the preferences of the party to various issues in the domain and affects how they will negotiate. All profiles that have been uploaded to the TomCat profilesserver and were parsed correctly are available here.
144\item Parameters: These are some extra protocol- and party- specific parameters that can be set for each party. For the MOPaC protocol, there is currently 1 parameter: power which controls the power that the party has in the negotiation. See Section 2 of the MOPaC Protocol document for more details about what the implications of the power of a party in the proceedings of the negotiation. The default power of a party, if not set explicitly, is 1. The range values that power can take is the set of natural numbers.
145\end{itemize}
146
147\subsection{Steps to Run a Negotiation Session}
148Now to run a session, do the following
149\begin{enumerate}
150\item Go to the runserver with your browser and select "new session"
151\item Set the negotiation parameters as required.
152\item Choose a MOPaC compatible party from the Party dropdown.
153\item Choose a profile for the party.
154\item Set the extra parameters for the party. This can be entered in the following way: "a": 1, "b": 2
155\item Click on the add button to select the party with its profile for the negotiation session.
156\item Repeat step 3-6 for all parties you want to add. Make sure to add at least 3 parties, each with a different profile, since MOPaC is a multi-lateral negotiation protocol.
157\item Click on “Start Session” button to begin the session.
158\end{enumerate}
159
160\subsection{Utilities Plot}
161Once the session is completed, two links will be generated, one for the utilities plot and another for the log file. This plot is a graphical representation of the utilities of all the offers made in the session. The X axis captures the different offers made by parties in the session. The Y axis shows the utilties of the offers. An example utility plot is shown in figure \ref{fig:graph}. Here, each offer 1, 2, 3 and 4 is made by one of the parties (indeterminable in this plot). For each offer, the utility of each agent is plotted on the Y axis. Hence, the plot shows how the utilities for each agent differs for each offer. The plot makes no distinction between different rounds and so utilities offers made in subsequent rounds are plotted after the last offer in the previous round.
162
163\begin{figure}
164 \centering
165 \includegraphics[width=10cm]{images/graph.png}
166 \caption{An Example Utilities Plot from a MOPaC negotiation session with 4 parties.}
167 \label{fig:graph}
168\end{figure}
169
170\textbf{Note} The line plot gives a false sense of sequence between the offers. Please keep in mind that this graphs shows utilities at each offer and not at each round. Each round comprises of 4 simultaneous offers, not sequential offers. We are still thinking of the most informative way to represent this multi-dimensional information. Please do write to us if you have any ideas.
171
172\FloatBarrier
173
174\subsection{Log File}
175 The log file contains the final State - in this case a MOPACState - and is documented in the \href{https://tracinsy.ewi.tudelft.nl/pubtrac/GeniusWeb/browser/protocol/src/main/java/geniusweb/protocol/session/mopac/MOPACState.java}{javadoc}. It details how the session progressed - which parties were part of the session, who made which bid, what were each party’s offers and the final agreements and their corresponding utilities. This state is stored as a JSON object. We describe the log file using an example log file as shown in listing \ref{ls:logfile}:
176
177
178\begin{lstlisting}[language = json ,caption={json contents of MOPAC.json log file}, label={ls:logfile}, escapeinside={(*@}{@*)}]
179{
180 "MOPACState": {
181 "phase": { ... },
182 "actions": [
183 {
184 "Offer": {
185 "actor": "randomparty_2_0_3_3",
186 "bid": {
187 "issuevalues": { ... }
188 }
189 }
190 },
191 ...,
192 {
193 "Votes": {
194 "actor": "randomparty_2_0_3_6_3",
195 "votes": [
196 {
197 "Vote": {
198 "actor": "randomparty_2_0_3_3",
199 "bid": {
200 "issuevalues": {... }
201 },
202 "minPower": 2,
203 "maxPower": 2147483647
204 }
205 },
206 {
207 "Vote": {
208 "actor": "randomparty_2_0_3_3",
209 "bid": {
210 "issuevalues": {...}
211 },
212 "minPower": 2,
213 "maxPower": 2147483647
214 }
215 }
216 ]
217 }
218 },
219 ...
220 ],
221 "progress": {
222 "ProgressTime": {
223 "duration": 600000,
224 "start": 1632732640424
225 }
226 },
227 "settings": {
228 "MOPACSettings": {
229 "participants": [ ...],
230 "deadline": {
231 "DeadlineTime": {
232 "durationms": 600000
233 }
234 },
235 "votingevaluator": {
236 "LargestAgreement": {
237 }
238 }
239 }
240 },
241 "partyprofiles": {
242 "randomparty_2_0_3_4": {
243 "party": {
244 "partyref": "http://..../randomparty-2.0.3",
245 "parameters": {
246 }
247 },
248 "profile": "ws://.../websocket/get/party/party4"
249 },
250 ...
251 }
252 }
253}
254\end{lstlisting}
255
256We see in the file:
257
258\begin{itemize}
259\item partyprofiles: Describes the parties that take part in the negotiation session and their preference profiles. Has a JSON object with a key for each party. Each party has
260 \begin{itemize}
261 \item party.partyref: type of party,
262 \item party.parameters: extra parameters of the party,
263 \item profile: preference profile of the party.
264 \end{itemize}
265\item settings: Settings specific to the session that is being run. If running MOPaC protocol, the settings contains:
266 \begin{itemize}
267 \item MOPACSettings.participants: The participants in the negotiation session. This is similar to the data in partyprofiles.
268 \item MOPACSettings.deadline: Contains the number of rounds and duration in milliseconds.
269 \item MOPACSettings.votingevaluator: Contains the type of voting evaluator used for the MOPaC session.
270 \end{itemize}
271
272\item progress: Has data about the duration of the session and when the ne- gotiation ended.
273\item connections: Has the reference to each party and the runtime errors if any including the stack trace.
274\item phase: The most important information from the phase is partyStates.agreements which contains the parties which participate in the largest agreement of
275the session. partyStates.actions contains information about the last
276action performed
277\item actions: This contains the actions performed by the parties in chronolog- ical order. Actions can be either of type Offer or Votes, corresponding to the bidding and voting phase of the MOPaC protocol.
278 \begin{itemize}
279 \item Offer: Contains information about which party made the bid and the bid itself with its issue values.
280 \item Votes: Contains information about which party the votes belong to and a list of bids that the party accepted. Only the bids present in Votes.votes array were accepted by the party. Rest are rejected. In each vote, maxPower and minPower contains the minimum and maximum consensus threshold. See Section 2.1 of the MOPaC Protocol document for more information on this.
281 \end{itemize}
282
283\end{itemize}
284
285\FloatBarrier
286
287\section{Running a MOPAC tournament}
288To run a MOPaC tournament, navigate to the run server page and click on the “new tournament” link. It should take you to a page with options to configure the settings for running a new tournament.
289To run a tournament:
290
291\begin{enumerate}
292\item Choose the number of times you want to repeat the tournament. Please note that each tournament could take a considerable amount of time if there are more than 3 parties in each session.
293\item Choose the number of teams in each session. It denotes the number of parties that will be chosen from a list of available parties. The number of teams in a session can vary from a minimum of 2 to a maximum of number of parties available.
294\item Choose session protocol as “MOPAC”, and Voting Evaluator and deadline. These three options are discussed in the previous section.
295\item Next you choose the domain in which you want your parties to negotiate and add different preference profiles that you want to have available. Here you can choose any number of profiles, but it is suggested you have at least as many profiles as number of teams in a session since you don’t want the profiles of different agents to repeat.
296\item Next you choose the parties and their parameters. Please check the previous section for more details about these options. You should have added as many parties as the number of teams in a session.
297\item Click the “Start Tournament” button.
298\item When the tournament is started, you get options similar to what you get when you run a session at the bottom of the screen: link to the results table and the log file.
299\end{enumerate}
300
301
302
303
304\subsection{Results Table}
305For a tournament, there is no Utilities Plot. Instead, you have a results table, which is an overview of the results. It 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. We show an example result table in figure \ref{fig:tourresults}. The table can be described column wise as follows:
306
307\begin{figure}
308 \centering
309 \includegraphics[width=15cm]{images/tourresults.png}
310 \caption{An Example Results Table after running a MOPaC negotiation tournament.}
311 \label{fig:tourresults}
312\end{figure}
313
314
315\begin{itemize}
316 \item The first column shows the session number and agreement number, start- ing from 0A, where 0 is the session number and A is the first agreement. If there were more agreements in session 0, they would be shown in 0B, 0C and so on.
317 \item The second column shows the issue values of the bid that was accepted.
318 \item Columns 3 and onward show the utility of the agreement for each party and the penalty incurred by the party. This is represented as follows: <utility>-<penalty>. If a party was not part of an agreement, the column contains 0-0, i.e. no penalty and no utility.
319\end{itemize}
320
321\subsection{Log File}
322The log file of a tournament is slightly different compared to the log file for the session: it now conains the final state of the tournament: an \href{https://tracinsy.ewi.tudelft.nl/pubtrac/GeniusWeb/browser/protocol/src/main/java/geniusweb/protocol/tournament/allpermutations/AllPermutationsState.java}{AllPermutationsState}. We show an example log file in listing \ref{ls:logfile2}. The following points summarize the structure of the log file:
323\begin{itemize}
324 \item AllPermutationsState.toursettings.AllPermutationsSettings contains teams which has the full set of parties available for the tournament, profilelists which has the full set of profiles available and sessionsettings which has the settings chosen in the run tournaments webpage.
325 \item AllPermutationsState.sessionsettings is an array of the various permutations of profiles and parties chosen according to the run tournament settings. This is generated by the AllPermutationState, according to the "toursettings", and added to the log file for convenience. Each element has a list of participants (party + profile), deadline, and voting evaluator type.
326 \item AllPermutationsState.results is an array of
327 SessionResults, one for each session. The log file does not contain the fiull MOPACState because the log file would become too large. Each SessionResult contains participants which is a list of parties with profiles, and agreements which is the set of parties that have come to an agreement along with the issue values.
328
329\end{itemize}
330
331
332\begin{lstlisting}[language = json ,caption={json contents of APP.json log file with tournament result}, label={ls:logfile2}, escapeinside={(*@}{@*)}]
333{
334 "AllPermutationsState": {
335 "toursettings": {
336 "AllPermutationsSettings": {
337 "teams": [
338 {
339 "Team": [
340 {
341 "partyref": "http://.../randomparty-2.0.3",
342 "parameters": {
343 }
344 }
345 ]
346 },
347 ...
348 ],
349 "profileslists": [
350 {
351 "ProfileList": [
352 "ws://.../party/party1"
353 ]
354 },
355 ...
356 ],
357 "reuseTeams": false,
358 "teamsPerSession": 3,
359 "sessionsettings": {
360 "MOPACSettings": {
361 "participants": [
362
363 ],
364 "deadline": {
365 "DeadlineRounds": {
366 "rounds": 10,
367 "durationms": 10000
368 }
369 },
370 "votingevaluator": {
371 "LargestAgreement": { }
372 }
373 }
374 },
375 "numberTournaments": 1
376 }
377 },
378 "sessionsettings": [
379 {
380 "MOPACSettings": {
381 "participants": [
382 {
383 "TeamInfo": {
384 "parties": [
385 {
386 "party": {
387 "partyref": "http://...randomparty-2.0.3",
388 "parameters": {
389 }
390 },
391 "profile": "ws://...party/party3"
392 }
393 ]
394 }
395 },
396 ...
397 ],
398 "deadline": {
399 "DeadlineRounds": {
400 "rounds": 10,
401 "durationms": 10000
402 }
403 },
404 "votingevaluator": {
405 "LargestAgreement": { }
406 }
407 }
408 },
409 ........
410 ],
411 "results": [
412 {
413 "participants": {
414 "boulware_2_0_3_3": {
415 "party": {
416 "partyref": "http://...boulware-2.0.3",
417 "parameters": { }
418 },
419 "profile": "ws://.../party/party4"
420 },
421 "randomparty_2_0_3__1": {
422 "party": {
423 "partyref": "http://192.168.178.16:8080/partiesserver/run/randomparty-2.0.3",
424 "parameters": { }
425 },
426 "profile": "ws://.../party/party3"
427 },
428 "conceder_2_0_3_2": {
429 "party": {
430 "partyref": "http://..conceder-2.0.3",
431 "parameters": { }
432 },
433 "profile": "ws://...party/party2"
434 }
435 },
436 "agreements": {
437 "randomparty_2_0_3__1": {
438 "issuevalues": {...}
439 },
440 "conceder_2_0_3_192_168_178_16_2": {
441 "issuevalues": {...}
442 }
443 },
444 "penalties": {
445 },
446 "error": null
447 },
448 ......
449 ]
450 }
451}
452\end{lstlisting}
453
454
455
456\end{document}
Note: See TracBrowser for help on using the repository browser.