Index: tutorials/MOPAC/tutorial.tex
===================================================================
--- tutorials/MOPAC/tutorial.tex	(revision 39)
+++ tutorials/MOPAC/tutorial.tex	(revision 39)
@@ -0,0 +1,456 @@
+\documentclass{article}
+\usepackage[margin=1in]{geometry}
+\usepackage{authblk}
+
+\usepackage[utf8]{inputenc}
+\pagestyle{plain}
+\usepackage{eurosym}
+\usepackage[table]{xcolor}
+\usepackage{graphicx}
+\usepackage{enumitem}\newsavebox\fnbox
+\usepackage{hyperref}
+\usepackage{placeins}
+\usepackage{listings}
+
+\usepackage{booktabs}
+\usepackage{caption} 
+\captionsetup[table]{skip=10pt}
+
+\newtheorem{exercise}{Exercise}
+
+\newcommand{\code}[1]{\texttt{#1}}
+
+\newcommand{\fbf}{\textbf}
+
+\newcommand{\gw}{\sc{{GeniusWeb}}}
+
+\title{ {\gw} MOPaC Tutorial}
+\author{Wouter Pasman}
+
+
+\affil{Interactive Intelligence, Delft University of Technology}
+
+%define colors for various boxes
+\definecolor{infocolor}{rgb}{0.8, 0.9, 0.99}
+\definecolor{warningcolor}{rgb}{0.99, 0.9, 0.8}
+\definecolor{tipcolor}{rgb}{0.9, 0.99, 0.8}
+
+
+
+\usepackage{courier} %% Sets font for listing as Courier.
+\usepackage{listings, xcolor}
+\lstset{
+	tabsize = 4, %% set tab space width
+	showstringspaces = false, %% prevent space marking in strings, string is defined as the text that is generally printed directly to the console
+	numbers = left, %% display line numbers on the left
+	commentstyle = \color{green}, %% set comment color
+	keywordstyle = \color{blue}, %% set keyword color
+	stringstyle = \color{red}, %% set string color
+	rulecolor = \color{black}, %% set frame color to avoid being affected by text color
+	basicstyle = \small \ttfamily , %% set listing font and size
+	breaklines = true, %% enable line breaking
+	numberstyle = \tiny,
+}
+
+\usepackage{xcolor}
+
+
+% DEFINE JSON LISTING LAYOUT
+\colorlet{punct}{red!60!black}
+\definecolor{background}{HTML}{EEEEEE}
+\definecolor{delim}{RGB}{20,105,176}
+\colorlet{numb}{magenta!60!black}
+\lstdefinelanguage{json}{
+	basicstyle=\normalfont\ttfamily,
+	numbers=left,
+	numberstyle=\scriptsize,
+	stepnumber=1,
+	numbersep=8pt,
+	showstringspaces=false,
+	breaklines=true,
+	frame=lines,
+	%backgroundcolor=\color{background},
+	literate=
+	*{0}{{{\color{numb}0}}}{1}
+	{1}{{{\color{numb}1}}}{1}
+	{2}{{{\color{numb}2}}}{1}
+	{3}{{{\color{numb}3}}}{1}
+	{4}{{{\color{numb}4}}}{1}
+	{5}{{{\color{numb}5}}}{1}
+	{6}{{{\color{numb}6}}}{1}
+	{7}{{{\color{numb}7}}}{1}
+	{8}{{{\color{numb}8}}}{1}
+	{9}{{{\color{numb}9}}}{1}
+	{:}{{{\color{punct}{:}}}}{1}
+	{,}{{{\color{punct}{,}}}}{1}
+	{\{}{{{\color{delim}{\{}}}}{1}
+	{\}}{{{\color{delim}{\}}}}}{1}
+	{[}{{{\color{delim}{[}}}}{1}
+	{]}{{{\color{delim}{]}}}}{1},
+}
+
+% END json listing layout
+
+\begin{document}
+\maketitle
+
+This 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
+installed and basic knowledge of GeniusWeb,
+eg from the  \href{https://tracinsy.ewi.tudelft.nl/pubtrac/GeniusWeb/export/HEAD/tutorials/SAOP/tutorial.pdf}{SAOP tutorial}.
+
+The 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. 
+
+
+\section{Creating a MOPaC party}
+Creating 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:
+
+\begin{enumerate}
+\item a MOPAC-capable party has to return "MOPAC" as part of the Capabilities in its getCapabilities function. 
+\item a MOPAC capable party has to understand and properly handle MOPAC protocol events and create the appropriate actions. A short outline is on
+\href{https://tracinsy.ewi.tudelft.nl/pubtrac/GeniusWeb#Capabilities}{the wiki page},
+ 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 
+  \href{https://tracinsy.ewi.tudelft.nl/pubtrac/GeniusWeb/browser/protocol/src/main/java/geniusweb/protocol/session/mopac/MOPAC.java}{MOPAC javadoc}, but briefly:
+	\begin{itemize}
+		\item handle incoming SessionSettings and fetch the profile
+		\item wait for YourTurn and send an Offer
+		\item wait for Voting and reply with Votes
+		\item wait for OptIn and reply again with Votes
+		\item loop back to wait for Yourturn above
+	\end{itemize}
+\end{enumerate}
+
+The RandomParty already is MOPaC capable, so RandomParty can be used as a starting point ot create a MOPaC party.
+
+\section{Running a MOPaC session}
+After you put yuor compiled party on the TomCat server and started the server, navigate to the runserver webpage in your
+web 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.
+Clicking on the new session link should take you to the Session creation webpage. 
+
+\subsection{Options}
+
+Here 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:
+
+\begin{itemize}
+\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.
+\item Voting Evaluator: This is method by which the protocol determines which deals form an agreement. There are currently two ways to do this:
+	\begin{itemize}
+	\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.
+	\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).
+	\end{itemize}
+\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.
+\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.
+\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.
+\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.
+\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.
+\end{itemize}
+
+\subsection{Steps to Run a Negotiation Session}
+Now to run a session, do the following
+\begin{enumerate}
+\item Go to the runserver with your browser and select "new session"
+\item Set the negotiation parameters as required.
+\item Choose a MOPaC compatible party from the Party dropdown.
+\item Choose a profile for the party.
+\item Set the extra parameters for the party. This can be entered in the following way: "a": 1, "b": 2
+\item Click on the add button to select the party with its profile for the negotiation session.
+\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.
+\item Click on “Start Session” button to begin the session.
+\end{enumerate}
+
+\subsection{Utilities Plot}
+Once 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.
+
+\begin{figure}
+	\centering
+	\includegraphics[width=10cm]{images/graph.png}
+	\caption{An Example Utilities Plot from a MOPaC negotiation session with 4 parties.}
+	\label{fig:graph}
+\end{figure}
+
+\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.
+
+\FloatBarrier
+
+\subsection{Log File}
+ 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}:
+
+
+\begin{lstlisting}[language = json  ,caption={json contents of MOPAC.json log file}, label={ls:logfile}, escapeinside={(*@}{@*)}]
+{
+	"MOPACState": {
+		"phase": { ...	},
+		"actions": [
+			{
+				"Offer": {
+					"actor": "randomparty_2_0_3_3",
+					"bid": {
+						"issuevalues": { ...  }
+					}
+				}
+			},
+			...,
+			{
+				"Votes": {
+					"actor": "randomparty_2_0_3_6_3",
+					"votes": [
+						{
+							"Vote": {
+								"actor": "randomparty_2_0_3_3",
+								"bid": {
+									"issuevalues": {...	}
+								},
+								"minPower": 2,
+								"maxPower": 2147483647
+							}
+						},
+						{
+							"Vote": {
+								"actor": "randomparty_2_0_3_3",
+								"bid": {
+									"issuevalues": {...}
+								},
+								"minPower": 2,
+								"maxPower": 2147483647
+							}
+						}
+					]
+				}
+			},
+		...
+		],
+		"progress": {
+			"ProgressTime": {
+				"duration": 600000,
+				"start": 1632732640424
+			}
+		},
+		"settings": {
+			"MOPACSettings": {
+				"participants": [ ...],
+				"deadline": {
+					"DeadlineTime": {
+						"durationms": 600000
+					}
+				},
+				"votingevaluator": {
+					"LargestAgreement": {
+					}
+				}
+			}
+		},
+		"partyprofiles": {
+			"randomparty_2_0_3_4": {
+				"party": {
+					"partyref": "http://..../randomparty-2.0.3",
+					"parameters": {
+					}
+				},
+				"profile": "ws://.../websocket/get/party/party4"
+			},
+			...
+		}
+	}
+}
+\end{lstlisting}
+
+We see in the file:
+
+\begin{itemize}
+\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
+	\begin{itemize}
+	\item party.partyref: type of party,
+	\item party.parameters: extra parameters of the party, 
+	\item profile: preference profile of the party.
+	\end{itemize}
+\item settings: Settings specific to the session that is being run. If running MOPaC protocol, the settings contains:
+	\begin{itemize}
+	\item MOPACSettings.participants: The participants in the negotiation session. This is similar to the data in partyprofiles.
+	\item MOPACSettings.deadline: Contains the number of rounds and duration in milliseconds.
+	\item MOPACSettings.votingevaluator: Contains the type of voting evaluator used for the MOPaC session.
+	\end{itemize}
+
+\item progress: Has data about the duration of the session and when the ne- gotiation ended.
+\item connections: Has the reference to each party and the runtime errors if any including the stack trace.
+\item phase: The most important information from the phase is partyStates.agreements which contains the parties which participate in the largest agreement of
+the session. partyStates.actions contains information about the last
+action performed
+\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.
+	\begin{itemize}
+	\item Offer: Contains information about which party made the bid and the bid itself with its issue values.
+	\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.
+	\end{itemize}
+
+\end{itemize}
+
+\FloatBarrier
+
+\section{Running a MOPAC tournament}
+To 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.
+To run a tournament:
+
+\begin{enumerate}
+\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.
+\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.
+\item Choose session protocol as “MOPAC”, and Voting Evaluator and deadline. These three options are discussed in the previous section.
+\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.
+\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.
+\item Click the “Start Tournament” button.
+\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.
+\end{enumerate}
+
+
+
+
+\subsection{Results Table}
+For 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:
+
+\begin{figure}
+	\centering
+	\includegraphics[width=15cm]{images/tourresults.png}
+	\caption{An Example Results Table after running a MOPaC negotiation tournament.}
+	\label{fig:tourresults}
+\end{figure}
+
+
+\begin{itemize}
+	\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.
+	\item The second column shows the issue values of the bid that was accepted.
+	\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.
+\end{itemize}
+
+\subsection{Log File}
+The 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:
+\begin{itemize}
+	\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.
+	\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.
+	\item AllPermutationsState.results is an array of
+	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.
+	
+\end{itemize}
+
+
+\begin{lstlisting}[language = json  ,caption={json contents of APP.json log file with tournament result}, label={ls:logfile2}, escapeinside={(*@}{@*)}]
+{
+	"AllPermutationsState": {
+		"toursettings": {
+			"AllPermutationsSettings": {
+				"teams": [
+					{
+						"Team": [
+							{
+								"partyref": "http://.../randomparty-2.0.3",
+								"parameters": {
+								}
+							}
+						]
+					},
+				...
+				],
+				"profileslists": [
+					{
+						"ProfileList": [
+							"ws://.../party/party1"
+						]
+					},
+					...
+				],
+				"reuseTeams": false,
+				"teamsPerSession": 3,
+				"sessionsettings": {
+					"MOPACSettings": {
+						"participants": [
+
+						],
+						"deadline": {
+							"DeadlineRounds": {
+								"rounds": 10,
+								"durationms": 10000
+							}
+						},
+						"votingevaluator": {
+							"LargestAgreement": {	}
+						}
+					}
+				},
+				"numberTournaments": 1
+			}
+		},
+		"sessionsettings": [
+			{
+				"MOPACSettings": {
+					"participants": [
+						{
+							"TeamInfo": {
+								"parties": [
+									{
+										"party": {
+											"partyref": "http://...randomparty-2.0.3",
+											"parameters": {
+											}
+										},
+										"profile": "ws://...party/party3"
+									}
+								]
+							}
+						},
+					...
+					],
+					"deadline": {
+						"DeadlineRounds": {
+							"rounds": 10,
+							"durationms": 10000
+						}
+					},
+					"votingevaluator": {
+						"LargestAgreement": {	}
+					}
+				}
+			},
+		........
+		],
+		"results": [
+			{
+				"participants": {
+					"boulware_2_0_3_3": {
+						"party": {
+							"partyref": "http://...boulware-2.0.3",
+							"parameters": {	}
+						},
+						"profile": "ws://.../party/party4"
+					},
+					"randomparty_2_0_3__1": {
+						"party": {
+							"partyref": "http://192.168.178.16:8080/partiesserver/run/randomparty-2.0.3",
+							"parameters": {		}
+						},
+						"profile": "ws://.../party/party3"
+					},
+					"conceder_2_0_3_2": {
+						"party": {
+							"partyref": "http://..conceder-2.0.3",
+							"parameters": {		}
+						},
+						"profile": "ws://...party/party2"
+					}
+				},
+				"agreements": {
+					"randomparty_2_0_3__1": {
+						"issuevalues": {...}
+					},
+					"conceder_2_0_3_192_168_178_16_2": {
+						"issuevalues": {...}
+					}
+				},
+				"penalties": {
+				},
+				"error": null
+			},
+			......
+		]
+	}
+}
+\end{lstlisting}
+
+
+
+\end{document}
