source: doc/userguide.tex

Last change on this file was 261, checked in by Adel Magra, 5 years ago

Corrected mistakes in the user guide.

File size: 102.7 KB
Line 
1
2% Created by Colin Williams on 2012-01-06.
3% Copyright (c) 2012 __MyCompanyName__. All rights reserved.
4%
5\documentclass[]{article}
6
7% Use utf-8 encoding for foreign characters
8\usepackage[utf8]{inputenc}
9
10% the page geometry.
11\usepackage[a4paper,top=2cm, bottom=2cm, left=1cm, right=1cm]{geometry}
12\usepackage{minibox}
13% Uncomment some of the following if you use the features
14%
15% Running Headers and footers
16%\usepackage{fancyhdr}
17
18% Multipart figures
19%\usepackage{subfigure}
20
21% More symbols
22%\usepackage{amsmath}
23%\usepackage{amssymb}
24%\usepackage{latexsym}
25
26% Surround parts of graphics with box
27\usepackage{boxedminipage}
28
29% Package for including code in the document
30\usepackage{listings}
31
32% If you want to generate a toc for each chapter (use with book)
33\usepackage{minitoc}
34
35% This is now the recommended way for checking for PDFLaTeX:
36\usepackage{ifpdf}
37\usepackage{comment}
38
39%\newif\ifpdf
40%\ifx\pdfoutput\undefined
41%\pdffalse % we are not running PDFLaTeX
42%\else
43%\pdfoutput=1 % we are running PDFLaTeX
44%\pdftrue
45%\fi
46
47
48\usepackage{array}
49\usepackage{url}
50\usepackage{listings}
51\usepackage{color}
52\usepackage{amsmath}
53\usepackage{mathtools}
54
55% clickable links in the contents section
56\usepackage{hyperref}
57\hypersetup{
58 colorlinks,
59 citecolor=black,
60 filecolor=black,
61 linkcolor=black,
62 urlcolor=black
63}
64
65
66\definecolor{dkgreen}{rgb}{0,0.6,0}
67\definecolor{gray}{rgb}{0.5,0.5,0.5}
68\definecolor{mauve}{rgb}{0.58,0,0.82}
69
70
71\newcommand*\vtick{\textsc{\char13}}
72
73\lstset{
74 language=Java,
75 tabsize=4,
76 showstringspaces=false,
77 basicstyle=\tt,
78 numberstyle=\tiny\color{gray}, % line number style
79 keywordstyle=\color{blue}, % keyword style
80 commentstyle=\color{dkgreen}, % comment style
81 stringstyle=\color{mauve}, % string literal style
82}
83
84\ifpdf
85\usepackage[pdftex]{graphicx}
86\else
87\usepackage{graphicx}
88\fi
89
90% this gives us \FloatBarrier to prevent images to float all to the end
91\usepackage{placeins}
92\newcommand\Genius{{\sc Genius}}
93
94% Alter some LaTeX defaults for better treatment of figures:
95 % See p.105 of "TeX Unbound" for suggested values.
96 % See pp. 199-200 of Lamport's "LaTeX" book for details.
97 % General parameters, for ALL pages:
98 \renewcommand{\topfraction}{0.9} % max fraction of floats at top
99 \renewcommand{\bottomfraction}{0.8} % max fraction of floats at bottom
100 % Parameters for TEXT pages (not float pages):
101 \setcounter{topnumber}{2}
102 \setcounter{bottomnumber}{2}
103 \setcounter{totalnumber}{4} % 2 may work better
104 \setcounter{dbltopnumber}{2} % for 2-column pages
105 \renewcommand{\dbltopfraction}{0.9} % fit big float above 2-col. text
106 \renewcommand{\textfraction}{0.07} % allow minimal text w. figs
107 % Parameters for FLOAT pages (not text pages):
108 \renewcommand{\floatpagefraction}{0.7} % require fuller float pages
109 % N.B.: floatpagefraction MUST be less than topfraction !!
110 \renewcommand{\dblfloatpagefraction}{0.7} % require fuller float pages
111
112 % remember to use [htp] or [htpb] for placement
113
114
115
116%===========================================================================
117\title{Using the {\Genius} Framework for Running Autonomous Negotiating Parties}
118\author{T. Baarslag, W. Pasman, K. Hindriks, D. Tykhonov}
119
120\date{\today}
121
122\begin{document}
123
124\ifpdf
125\DeclareGraphicsExtensions{.pdf, .jpg, .tif}
126\else
127\DeclareGraphicsExtensions{.eps, .jpg}
128\fi
129
130\maketitle
131
132
133\abstract{\noindent {\Genius} \cite{Genius}~is a negotiation environment that implements an open architecture for heterogeneous negotiating parties. {\Genius}~can be used to implement, or simulate, real life negotiations. This document describes how you can install the environment, work with the provided scenarios and negotiation parties, and write, compile, and run an party yourself. \\
134
135\noindent
136For a quick start on how to set up your workspace with {\Genius} we refer to Section \ref{sec:appendix}.
137
138}
139
140\pagebreak
141\tableofcontents
142
143\pagebreak
144
145
146%=========================================================================================
147\section{Theory Crash Course}
148This section provides a crash course on some essential theory needed to understand the negotiation system. Furthermore, it provides an overview of the features of a negotiation implemented in {\Genius}.
149
150\subsection{Bids, Issues and Values}
151Parties participating in a negotiation interact in a domain. The domain specifies the possible bids. The parties all have their own preferences, which is reflected in their profile. Figure~\ref{Fig:domain} shows a picture of a domain that describes the issues in the negotiation.
152
153\begin{figure}[htb]
154 \centering
155 \includegraphics[width=0.4\textwidth]{media/domain.png}
156 \caption{An example domain for laptop negotiation. Issues are orange, values are green}\label{Fig:domain}
157\end{figure}
158
159The \textit{Domain} describes which issues are the subject of the negotiation and which values an issue can attain. A domain contains $n$ issues: $D=(I_1,\ldots,I_n)$. Each issue $i$ consists of $k$ values: $I_i=(v^i_1,\ldots,v^i_k)$. Combining these concepts, a party can formulate a \textit{Bid}: a mapping from each issue to a chosen value (denoted by $c$), $b=(v^i_{c},\ldots,v^n_{c})$.
160
161To give an example, in the laptop domain the issues are ``laptop'', ``harddisk'' and ``monitor''. In this domain the issues can only attain discrete values, e.g. the ``harddisk'' issue can only have the values ``60Gb'', ``80Gb'' and ``120Gb''. These issues are all instance of \textit{IssueDiscrete}. A valid bid in the laptop domain is e.g. \verb|Laptop:Dell, Harddisk: 80Gb, monitor:17"|. A bid \verb|Laptop Asus, Harddisk: 80Gb, monitor:17"| is not a valid bid because Asus is not a valid issue value in the example domain, and \verb|Laptop Asus, Harddisk: 80Gb, CPU:i7"| is not valid because CPU is not an issue in this domain.
162
163\subsection{Preference Profile, Utility Space and Elicitation}
164The \textit{Preference Profile} describes how bids are preferred over other bids. Typically, each participant in a negotiation has his own preference profile. Genius supports utility spaces and partially ordered profiles.
165
166\subsubsection{Utility spaces}
167One form of profile is the \textit{UtilitySpace}. The UtilitySpace specifies the preferences using an \textit{evaluator}: a function that maps bids into a real number in the range [0,1] where 0 is the minimum utility and 1 is the maximum utility of a bid. So a bid is preferred if and only if it has a higher utility than another bid.
168
169A common form of the Utility space is the \textit{Linear Additive Utility Space}. This space is additive because each of the issue values in the domain have their own utility of their own, and all the sub-utilities just add up for the total utility of the bid. For instance, we like Apple with utility evaluation 0.7 and Dell with 0.4, completely independent of how much memory the computer has. Figure~\ref{Fig:utilspace} shows a picture of a utility space for the example domain that we gave above.
170
171\begin{figure}[htb]
172 \centering
173 \includegraphics[width=0.6\textwidth]{media/utilspace.png}
174 \caption{An example additive utility space for the laptop domain.}\label{Fig:utilspace}
175\end{figure}
176
177In an additive space the evaluator also specifies the importance of the issue relative to the other issues in the form of a weight. The weights of all issues sum up to 1.0 to simplify calculating the utility of a bid. The utility is the weighted sum of the scaled evaluation values.
178
179\begin{equation}
180 U(v^i_{c},\ldots,v^n_{c}) = \sum_{i=1}^{n} w_i \dfrac{\text{eval}(v^i_{c})}{\text{max}(\text{eval}(I_i))}
181 \label{eqn:Utility}
182\end{equation}
183
184Other types of UtilitySpaces are the \textit{ConstraintUtilitySpace} and the \textit{NonlinearUtilitySpace}. These are more experimental and not described here in more detail.
185
186\subsubsection{Preference Uncertainty through a Partially ordered profile}\label{sec:partialordering}
187
188The \textit{UncertainAdditiveUtilitySpace} is a profile type that uses a partial ordering instead of assigning a utility value to bids. In a partial ordering, the available information is that bid $X$ is preferred over bid $Y$ for a subset of possible bids.
189
190An UncertainAdditiveUtilitySpace profile is generated from a AdditiveUtilitySpace as will be described in the section \ref{sec:scenariocreation}, but the underlying AdditiveUtilitySpace is normally not visible for the party that uses the profile. Instead, given an UncertainAdditiveUtilitySpace, the agent's goal is to formulate its own estimated utility function $ \hat{U}(\omega) $ that approximates the real utility function $ U(\omega) $ for every bid $\omega$ as much as possible. That is, the agent needs to find `the most likely' utility function from a limited ranking of outcomes.
191
192The generation of the partial ordering works as follows. The values $comparisons$, $errors$ and $experimental$ are additional parameters of the UncertainAdditiveUtilitySpace that control the generation.
193\begin{enumerate}
194\item a subset of $comparisons$ bids are selected randomly from all possible bids.
195\item the selected bids are sorted in ascending utility
196\end{enumerate}
197
198This partial ordering is available to the agent through what we call a \textit{UserModel}.
199
200Notice: AbstractNegotiatonParty on initialization will do a simplistic attempt to convert an UncertainAdditiveUtilitySpace into an AdditiveLinearUtilitySpace.
201
202Warning: if the number of possible bids is very large, iterating over all bids in the outcome space and sorting them can result in running out of memory.
203
204\subsubsection{Elicitation through the User}
205
206In the case where the preference profile is uncertain, the Agent might want to elicit more information about the true utility space in order to improve its UserModel. It is able to do so by querying the \textit{User} against an \textit{elicitation cost}. A User is generated automatically from an UncertainAdditiveUtilitySpace as will be described in section \ref{sec:scenariocreation}. To get a clearer picture of the role of the User, one can think of it as being the personified ``User" for which the agent is negotiating. The Agent can then ask the User questions about what it wants to improve its performance, but this bothers the User to an extent. This bother is captured by the elicitation cost attributed to the User. At the end of the negotiation, the true performance of the Agent is recorded as the User utility. It is obtained by subtracting the total bother inflicted to the User to the utility of the bid agreed upon. Namely, if $\omega$ is the agreement, then:
207
208\begin{equation}
209 \text{User Utility}=U(\omega)-\text{Total Bother Cost}
210\end{equation}
211
212Figure \ref{Fig:uncertainty} presents an overview of the dynamics between the different actors involved under preference uncertainty.
213
214\begin{figure}[htb]
215 \centering
216 \includegraphics[width=0.6\textwidth]{media/Uncertainty_Diagram.png}
217 \caption{Negotiation dynamics under preference uncertainty}\label{Fig:uncertainty}
218\end{figure}
219
220\subsection{Optimality of a Bid}
221In general, given the set of all bids, there are a small subset of bids which are more preferred as outcomes by all parties in the negotiation. Identifying these special bids may lead to a better agreement for both parties.
222
223For a single party, the optimal bid is the bid that is most preferred / has maximum utility. Often this bid is not preferred so much / has a low utility for other parties, and therefore the chance of agreement is low. A more general notion of optimality of a negotiation involves the utility of all parties.
224
225\begin{figure}[htb]
226 \centering
227 \includegraphics[width=0.37\textwidth]{media/image5.png}
228\caption{A point indicates the utility for both parties of a bid. The red line is the Pareto optimal frontier.}\label{Fig:utility plot}
229\end{figure}
230
231There are multiple ways to define a more global ``optimum''. One approach to optimality is that a bid is not optimal for both parties if there is another bid that has the higher utility for one party, and at least equal utility for the other party. Thus, only bids in Figure~\ref{Fig:utility plot} for which there is no other bid at the top right is optimal. This type of optimality is called Pareto optimality and forms an important concept in automated negotiation. The collection of Pareto optimal bids is called the Pareto optimal frontier.
232
233A major challenge in a negotiation is that parties can hide their preferences. This entails that an party does not know which bid the opponent prefers given a set of bids. This problem can be partly resolved by building an \textit{opponent model} of the opponent's preferences by analyzing the negotiation trace. Each turn the party can now offer the best bid for the opponent given a set of similar preferred bids. {\Genius} provides a number of components that can estimate an opponent model.
234
235\subsection{Negotiation Protocol}
236The negotiation protocol determines the overall order of actions during a negotiation. Parties are obliged to stick to this protocol, as deviations from the protocol are caught and penalized. {\Genius} supports multiple protocols. These are discussed in detail in section \ref{sec:protocols}.
237
238
239\subsection{Reservation Value}
240A reservation value is a real-valued constant that sets a threshold below which a rational party should not accept any offers. Intuitively, a reservation value is the utility associated with the Best Alternative to a Negotiated Agreement (BATNA).
241
242A reservation value is the minimum acceptable utility, offers with a utility would normally not be accepted by a party. Reservation values typically differ for each negotiation party. In case no reservation value is set in a profile, it is assumed to be 0. Notice that if a negotiation ends with no agreement, parties normally get a utility of 0, regardless of the reservation value.
243
244\subsection{Time Pressure}
245A negotiation lasts a predefined time in seconds, or alternatively rounds. In {\Genius}~the time line is \emph{normalized}, i.e.: time $t \in [0, 1]$, where $t = 0$ represents the start of the negotiation and $t = 1$ represents the deadline. Notice that manipulation of the remaining time can be a factor influencing the outcome.
246
247There is an important difference between a time-based and rounds-based protocol. In a time-based protocol the computational cost of an party should be taken into account as it directly influences the amount of bids which can be made. In contrast, for a rounds-based negotiation the time can be thought of as paused within a round; therefore computational cost does not play a role.
248
249Apart from a deadline, a scenario may also feature \emph{discount factors}. Discount factors decrease the utility of the bids under negotiation as time passes. While time is shared between both parties, the discount generally differs per party.
250The default implementation of discount factors is as follows: let $d$ in $[0, 1]$ be the discount factor that is specified in the preference profile of a party; let $t$ in $[0, 1]$ be the current normalized time, as defined by the timeline; we compute the discounted utility $U_D^t$ of an outcome $\omega$ from the undiscounted utility function $U$ as follows:
251\begin{eqnarray}
252U_D^t(\omega) = U(\omega) \cdot d^t
253\end{eqnarray}
254If $d = 1$, the utility is not affected by time, and such a scenario is considered to be undiscounted, while if $d$ is very small there is high pressure on the parties to reach an agreement. Note that discount factors are part of the preference profiles and therefore different parties may have a different discount factor.
255
256If a discount factor is present, reservation values will be discounted in exactly the same way as the utility of any other outcome. It is worth noting that, by having a discounted reservation value, it may be rational for parties to end the negotiation early and thereby default to the reservation value.
257
258Note: time pressure has little meaning if the profile is not defined in terms of utilities, eg a partially ordered profile.
259
260%=========================================================================================
261\section{Protocols}\label{sec:protocols}
262This section describes the various negotiation protocols. The protocol determines the overall order of actions during a negotiation.
263This section focuses on the MultiParty protocols as these have been properly developed. There is also a protocol class for the bilateral negotiation, but this is basically a hard coded Stacked Alternating Offers Protocol and not further developed.
264
265 The (Multilateral) protocol describes if the negotiation is finished, what the agreement is, which actions can be done in the next round. Briefly, to run a session the system checks with the protocol if the negotiation is already finished, and if not which calls need to be made to the parties (both chooseAction and receiveMessage). We recommend checking the javadoc of MultilateralProtocol for up-to-date detail information and how the protocol is used by the system to run sessions.
266
267 The Multilateral protocol uses the notion of rounds and turns to describe the negotiation layout. A round is a part of the negotiation where all participants get a turn to respond to the current state of the negotiation. A turn refers to the opportunity of one party to make a response to the current state of the negotiation.
268
269If a party violates the protocol -- for instance by sending an action that is not one of the allowed ones, or by crashing, the negotiation ends and the outcome usually is 'no agreement' for all parties. In bilateral negotiation we have a special case then: the party's utility is set to its reservation value, whereas the opponent is awarded the utility of the last offer.
270
271All protocols are found in the package \verb|genius.core.protocol| and have the names matching the subsections below.
272
273
274\subsection{Stacked Alternating Offers Protocol}
275According to this protocol \cite{MultilateralOffersProtocols} , all of the participants around the table get a turn per round. Turns are taken clock-wise around the table. One of the negotiating parties starts the negotiation with an offer that is observed by all others immediately. Whenever an offer is made, the next party in line gets a call to receiveMessage containing the bid, followed by a call to chooseAction from which it can return the following actions:
276\begin{itemize}
277\item Accept the offer (not available the very first turn).
278\item send an Offer to make a counter offer (thus rejecting and overriding the previous offer, if there was any)
279\item send an EndNegotiation and ending the negotiation without any agreement.
280\end{itemize}
281
282This protocol is the default protocol for Parties (as returned by getProtocol()).
283
284
285\subsection{Alternating Multiple Offers Protocol}
286According to this protocol \cite{MultilateralOffersProtocols}, all parties have a bid from all parties available to them, before they vote on these bids. This implemented in the following way: The protocol has a bidding phase followed by voting phases. In the bidding phase all participants put their offer on the table. These offers appear to all parties through receiveMessage() in a specific order. In the voting phases all participants vote on all of the bids on the negotiation table, in the same order as received. For each offer, the party's chooseAction() is called. If one of the bids on the negotiation table is accepted by all of the parties, then the negotiation ends with this bid.
287
288In each even round (we start in round 0), each party gets only one turn for an OfferForVoting.
289
290In each odd round there are N voting turns for each party (N being the number of offers), one for each offer in order of reception. these are the available options:
291\begin{itemize}
292\item Accept the offer
293\item Reject the offer
294\end{itemize}
295
296
297\subsection{Alternating Majority Consensus Protocol}
298
299This protocol is essentially equal to the Alternating Multiple Offers Protocol, but now an offer the protocol keeps track of the acceptable offer that got most accepts.
300Initially, this may be the first offer that got one accept. After a number of rounds, some offers receive multiple accepts and these then become the new acceptable offer.
301
302If an offer is accepted by all parties, the negotiation ends. Otherwise, the negotiation continues (unless the deadline is reached). If the deadline is reached, the acceptable offer becomes the agreement.
303
304
305\subsection{Simple Mediator Based Protocol}
306In this protocol, the parties do not hear the other parties directly. Instead, they only hear the mediator and the mediator hears the bids of all the parties. The mediator determines which bid will be voted on, collects the votes and determines the outcome. The mediator is just another NegotiationParty, but it extends Mediator.
307
308The protocol requires that exactly one party is a Mediator. The {\Genius} GUI enforces this presence of a Mediator. When you run a negotiation from the command line you have to ensure the presence of a single Mediator.
309
310This protocol uses the following turns in every round:
311\begin{enumerate}
312\item Mediator proposes an OfferForVoting
313\item The other parties (not the mediator) place a VoteForOfferAcceptance on the OfferForVoting
314\item The mediator makes a InformVotingResult that informs all parties about the outcome of this round.
315\end{enumerate}
316
317With this protocol, the last InformVotingResult with an accept determines the current outcome.
318
319As mentioned, you have to provide one mediator. There is the following options
320\begin{itemize}
321\item RandomFlippingMediator. This mediator generates random bids until all parties accept. Then, it
322 randomly flips one issue of the current offer to generate a new offer. It
323 keeps going until the deadline is reached.
324 \item FixedOrderFlippingMediator. This mediator behaves exactly like the RandomFlippingMediator, except that it uses a fixed-seed Random generator for every run. This makes it easier for testing.
325
326\end{itemize}
327
328\subsection{Mediator Feedback Based Protocol}
329Like the Simple Mediator Based Protocol, the parties do not hear the other parties directly. Instead, they only hear the mediator and the mediator hears the bids of all the parties. The mediator determines which bid will be voted on, collects the votes and determines the outcome. The mediator is just another NegotiationParty, but it extends Mediator.
330
331 The mediator generates its first bid randomly and sends it to the negotiating parties. After each bid, each party compares the mediator\vtick s new bid with his previous bid and gives feedback (`better', `worse' or `same') to the mediator. For its further bids, the mediator updates the previous bid, hopefully working towards some optimum. The negotiation runs on until the deadline (unless some party crashes). This protocol is explained in detail in \cite{MultiMediatedNegoProtocolsWithFeedback}.
332
333This protocol uses the following turns in every round:
334\begin{enumerate}
335\item Mediator proposes an OfferForFeedback.
336\item The other parties (not the mediator) place a GiveFeedback, indicateing whether the last bid placed by the mediator is better or worse than the previous bid.
337\end{enumerate}
338
339The accepted bid is the last bid that was not receiving a `worse' vote.
340
341\subsection{Beyond the Protocol}
342This section outlines the procedures for the parts of the session outside the scope of the protocol specification.
343
344Before the protocol can be started, the parties have to be loaded and initialized. During initialization, the party's persistent data may have to be loaded from a file. If the persistent data can not be read, a default empty dataset is created for the party. Then the party's init code is called to set up the party. All the time spent in this initialization phase is already being subtracted from the total available negotiation time.
345
346After the protocol has been completed, the protocol is called a last time to determine the final outcome.
347The parties are called to inform them that the negotiation ended, and what the outcome was. This happens even when parties crashed or did illegal actions. The negotiation has already finished, so these calls are not weighing in on the total negotiation time. Instead, these calls are typically limited to 1 second.
348
349Finally, if the party has modified the persistent data, this data needs to be saved. Again, this action is limited to a 1 second duration.
350
351Errors surrounding these out-of-protocol procedures are not part of the negotiation itself and therefore logged and handled separately. These errors are printed only to the console/terminal \footnote{To see the console output, run from Eclipse or start up Genius from a separate terminal. }
352, and only from the single session runner.
353
354
355%=========================================================================================
356\section{Install and Run {\Genius} }
357{\Genius} can run on any machine running Java 8. Java 9 is not yet supported. Please report any bugs found to \url{negotiation@ii.tudelft.nl}.
358
359To install the environment, the file \texttt{genius-XXX.zip} can be downloaded from \url{http://ii.tudelft.nl/genius/?q=article/releases}. Unzip the file at a convenient location on your machine. This will result in a folder ``genius-XXX" containing the following files:
360
361\begin{itemize}
362 \item a \texttt{userguide.pdf} which is this document.
363 \item \texttt{genius-XXX.jar}, the {\Genius} negotiation simulator;
364 \item a few example folders, containing ready-to-compile parties and components.
365 \item a \texttt{multilateraltournament.xml} example file
366\end{itemize}
367
368You start {\Genius} by double-clicking the genius-XXX.jar file, or using "open with" and then selecting Java.
369
370 After starting the simulator a screen similar to Figure~\ref{Fig:negosimulator start} is shown. This screen is divided in three portions:
371
372\begin{itemize}
373 \item The \textbf{Menubar} allows us to start a new negotiation.
374 \item The \textbf{Components Window} shows all available scenarios, parties, and BOA components.
375 \item The \textbf{Status Window} shows the negotiation status or selected domain/preference profile.
376\end{itemize}
377
378\begin{figure}[htb]
379 \centering
380 \includegraphics[width=0.6\textwidth]{media/start.png}
381\caption{{\Genius} right after start-up. The left half is the components panel, the right half the status panel.}\label{Fig:negosimulator start}
382\end{figure}
383
384
385Progress messages and error messages are printed mainly to the standard output. On Mac OSX you can view these messages by opening the console window (double-click on Systemdisk/Applications/Utilities/Console.app). On Windows this is not directly possible. Console output can be read only if you start the application from the console window by hand, as follows. Go to the directory with the genius-XXX.jar and enter
386\texttt{java -jar genius-XXX.jar}.
387This will start the simulator, and all messages will appear in the console window. You may see some errors and warnings that are non-critical.
388
389In some rare cases, parties and scenarios require more memory than allocated by default to Java. This problem can be resolved by using the Xmx and Xms parameters when launching the executable jar, for example \texttt{java -Xmx1536M -Xms1536M -jar genius-XXX.jar}. But usually, if your party runs out of memory then there is some design flaw or bug. Competitions usually are run with the default amount of java memory so it is recommended to ensure that your party performs properly without requiring additional memory.
390
391Please refer to chapter \ref{sec:debugging} for instructions on running {\Genius} in debug mode to debug your party.
392
393\subsection{Running on Hi-DPI screens}
394There is a bug in Java 8 that prevents windows from scaling up the {\Genius} application windows on hi-dpi screens. The bug is that Java 8 tells Windows that it will do the up-scaling itself, while java actually does not scale up anything. To fix this, do the following:
395
396Find \verb|java.exe| and \verb|javaw.exe| that are used for running {\Genius} (Double check if you have installed multiple versions of Java). Usually they are somewhere below \verb|C:\Program Files\Java\jre\bin| or similar. For both applications, do this:
397
398\begin{enumerate}
399
400\item Right click on the icon and select Properties
401\item Go to Compatibility tab
402\item Check "Override high DPI scaling behavior".
403\item Scaling performed by: set to "System"
404\end{enumerate}
405
406%=========================================================================================
407\section{Scenario Creation}\label{sec:scenariocreation}
408{\Genius} offers tools to create Domains and Profiles. Currently {\Genius} supports editing the Additive and the UncertainAdditive utility space
409 This section discusses how to create domains and preference profiles.
410
411
412\subsection{Creating a Domain}
413By right clicking on the list of available scenarios in the Domains panel a popup menu with the option to create a new domain is shown. After clicking this option a pop-up appears requesting the name for the new domain. After you enter a name and click ok, the new domain is created and a window similar to Figure~\ref{Fig:newdomain} is shown. Initially, a domain contains zero issues. We can simply add an issue by pressing the ``Add issue'' button. This results in the opening of a dialog similar to Figure~\ref{fig:createIssueD}.
414
415\begin{figure}[htb]
416 \centering
417 \includegraphics[width=0.9\textwidth]{media/exampledomain.png}
418\caption{{\Genius} after creating a new Example domain.}\label{Fig:newdomain}
419\end{figure}
420
421The current version of {\Genius}~supports the creation of discrete and integer issues. Starting with a discrete issue, the values of the issue should be specified. In Figure~\ref{fig:createIssueD} we show the values of the issue ``Harddisk''. Note the empty evaluation values window, later on when creating a preference profile we will use this tab to specify the preference of each value.
422
423Instead of a discrete issue, we can also add an integer issue as shown in Figure~\ref{fig:createIssueI}. For an integer issue we first need to specify the lowest possible value and the highest value, for example the price range for a second hand car may be $[500, 700]$. Next, when creating a preference profile we need to specify the utility of the lowest possible value (500) and the highest value (700). During the negotiation we can offer any value for the issue within the specified range.
424
425The next step is to press ``Ok'' to add the issue. Generally, a domain consists of multiple issues. We can simply add the other issues by repeating the process above. If you are satisfied with the domain, you can save it by pressing ``Save changes''.
426
427Finally, note that the issues of a domain can only be edited if the scenario does not (yet) specify preference profiles. This is to avoid inconsistencies between the preference profiles and the domains.
428
429\begin{figure}[ht]
430\center
431\begin{minipage}[b]{0.35\linewidth}
432 \includegraphics[width=0.95\textwidth]{media/image7a.png}
433\caption{Creating a discrete issue.}
434\label{fig:createIssueD}
435\end{minipage}
436\begin{minipage}[b]{0.55\linewidth}
437 \includegraphics[width=1.0\textwidth]{media/image7b.png}
438\caption{Creating an integer issue.}\label{fig:createIssueI}
439\end{minipage}
440\end{figure}
441
442\FloatBarrier
443
444\subsection{Creating an AdditiveUtilitySpace}\label{sec:createAdditive}
445Now that we created a domain, the next step is to add a set of preference profiles. Make sure that your domain is correct before proceeding, as \textit{the domain can not be changed when it contains profiles}. By right clicking on the domain a popup menu is opened which has an option to create a new preference profile. Selecting this option results in the opening of a new window which looks similar to Figure~\ref{fig:utilcreated}.
446
447\begin{figure}[htb]
448 \centering
449 \includegraphics[width=0.8\textwidth]{media/laptop.png}
450\caption{{\Genius} after creating a new utility space.}\label{fig:utilcreated}
451\end{figure}
452
453Now you are ready to start customizing the preference profile. There are three steps: setting the importance of the issues, determining the preference of the values of the issues, and configuring the reservation value and discount. Make sure that you leave the "Enable preference uncertainty" checkbox unchecked.
454
455\begin{enumerate}
456\item Adjust the relative weights of the issues by using the sliders next to that issue. Note that when you move a slider, the weights of the other sliders are automatically updated such that the all weights still sum up to one. If you do not want that the weight of another issue automatically changes, you can lock its weight by selecting the checkbox behind it. Now that we set the weights of the issues, it is a good idea to save the utility space.
457\item set the evaluation of the issues. To specify the evaluation of an issue you can double click it to open a new window looking similar to Figure~\ref{fig:createIssueD} or Figure~\ref{fig:createIssueI} depending on the type of the issue.
458
459For a discrete issue we need to specify the evaluation value of each discrete value. A specific value can be assigned any positive non-zero integer as evaluation value. During the negotiation the utility of a value is determined by dividing the value by the highest value for that particular issue. To illustrate, if we give 60 Gb evaluation 5, 80 Gb evaluation 8, and 120 Gb evaluation 10; then the utilities of these values are respectively 0.5, 0.8, and 1.0.
460
461Specifying the preference of a integer issue is even easier. In this case we simply need to specify the utility of the lowest possible value and the highest possible value. The utility of a value in this range is calculated during the negotiation by using linear interpolation of the utilities of both given utilities.
462
463\item The final step is to set the reservation value and discount of a preference profile.
464
465\item If you are satisfied with the profile you can save it by pressing ``Save changes''.
466\end{enumerate}
467
468\subsection{Creating an UncertainAdditiveUtilitySpace and a User}
469
470To create an uncertain additive utility space, first open or create an AdditiveUtilitySpace (section \ref{sec:createAdditive}), which defines a utility function $U$ over all possible outcomes. Check the "Enable preference uncertainty" checkbox (Figure \ref{fig:utilcreated}) to create a UncertainAdditiveUtilitySpace.
471
472The resulting UncertainAdditiveUtilitySpace is a partial ordering generated from the AdditiveUtilitySpace $U$. To be precise, it is a ranking $\mathcal{O}$ of $d$ different bids in the outcome space, consistent with $U$~\cite{Tsi18}:
473
474\begin{equation}
475\mathcal{O}=\left\{o^{(1)},o^{(2)}, \dots, o^{(d)} \right\}, \textrm{where } U(o^{(1)}) \leq U(o^{(2)}) \cdots \leq U(o^{(d)}).
476\end{equation}
477
478
479Use ``Nr. of outcomes in ranking'' to set $d$. The smaller you choose $d$, the higher the level of preference uncertainty. The minimal and maximal bid in the domain are always present in the ranking, which is why the smallest $d$ that can be chosen is 2. If you want to have the bid comparisons list to be a `controlled random' sequence that generates the same random ranking at every run, leave the fixed seed option enabled. If you want to generate different random bids at every run, disable the fixed seed option. If your profile is for testing purposes, also check ``Grant parties access to real utility functions''. The details of these settings are explained in section \ref{sec:partialordering}.
480
481The creation of an uncertain additive utility space automatically creates a User that has the ability to reveal information about the true utility of the bids against an elicitation cost in the range $[0,1]$. Use ``Elicitation cost" to set the cost of eliciting information from the User. Press "Save changes" to store your profile.
482
483%=========================================================================================
484\section{Running Negotiations}
485This section discusses how to run a negotiation. There are two modes to run a negotiation:
486
487\begin{itemize}
488 \item \textbf{Session}. A single negotiation session in which a number of parties negotiate.
489 \item \textbf{Tournament}. A tournament of multiparty sessions.
490\end{itemize}
491
492you start one of these by selecting them from the Start menu (Figure \ref{Fig:negosimulator start}).
493
494Before going into detail on how each of these modes work, we first discuss the two types of parties that can be used: automated parties and non-automated parties. Automated parties are parties that can compete against other parties in a negotiation without relying on input by a user. In general, these parties are able to make a large amount of bids in a limited amount of time.
495
496In contrast, non-automated parties are parties that are fully controlled by the user. These types of parties ask the user each round which action they should make. {\Genius}~by default includes the UIAgent -- which has a simple user interface -- and the more extensive Extended UIAgent.
497
498
499\subsection{Running a Session}\label{sec:singlesessionrun}
500To run a negotiation session select the menu ``Start'' and then ``Session''. This opens a window similar to Figure~\ref{Fig:multipartysession}.
501
502\begin{figure}[h!]
503 \centering
504 \includegraphics[width=0.5\textwidth]{media/multipartysession.png}
505\caption{A multi-party negotiation session.}\label{Fig:multipartysession}
506\end{figure}
507
508The following parameters need to be specified to run a negotiation:
509
510\medskip
511\begin{minipage}{.8 \textwidth}
512\begin{itemize}
513 \item \textbf{Negotiation protocol}. The set of available protocols. See Chapter \ref{sec:protocols}.
514 \item \textbf{Mediator}. The mediator ID and strategy that is to be used for this session. This is only visible if the protocol uses a mediator.
515 \item \textbf{Participant Information}. The information (ID, strategy, profile) for the a party in the session. This information is copied into the table of participants when you click "Add Party".
516 \item \textbf{A table with participants}. This table shows all currently added participants. You can add a party by setting the participant information above, and then clicking "Add Party". You can remove a party by selecting the party to remove in the table, and then clicking "Remove Party".
517 \item \textbf{Deadline}. The deadline to use. Can be "Round" or "Time". This determines the maximum duration of the session.
518 \item \textbf{Data Persistency}. What kind of persistent data is available to the parties. The options are discussed in section \ref{sec:sessiongeneration}.
519 \item \textbf{Enable System.out print}. If disabled, all system.out.print is suppressed during the negotiation. This is useful if for instance parties are flooding the output console, slowing down the system.
520 \item \textbf{Enable progress graph}. If enabled (default), a progress chart is shown during the negotiation. You can disable this e.g. if the drawing is slowing down the system.
521\item \textbf{Bilateral options} These appear only if you have exactly 2 parties added. The sub-options of this panel are
522 \begin{itemize}
523 \item \textbf{Show Util-Util Graph}. If enabled, the progress panel will show a graph where the utilities of the 2 parties are set along the X and Y axes. Also, the pareto frontier and nash point are shown in this graph. If disabled, it will show the default: a graph where the utilities of all parties are along the Y axis, and the time along the X axis.
524 \item \textbf{Show all bids}. If enabled, and if 'Show Util-Util Graph' is enabled, this will show all the possible bids in the Util-Util graph.
525 \end{itemize}
526
527\end{itemize}
528\end{minipage}
529\medskip
530
531
532The negotiation is started when you press the start button. The tab contents will change to a progress overview panel
533showing you the results of the negotiation (Figure \ref{fig:biprogress} and Figure \ref{fig:multiprogress}). The results are also stored in a log file.
534 These results can be easily analyzed by importing them into spreadsheet software such as Excel.
535
536 \begin{figure}[ht]
537 \center
538 \begin{minipage}[b]{0.4\linewidth}
539 \includegraphics[width=0.95\textwidth]{media/bilateralprogress.png}
540 \caption{Bilateral progress panel.}
541 \label{fig:biprogress}
542 \end{minipage}
543 \begin{minipage}[b]{0.4\linewidth}
544 \includegraphics[width=0.95\textwidth]{media/multilateralprogress.png}
545 \caption{Multilateral progress.}\label{fig:multiprogress}
546 \end{minipage}
547 \end{figure}
548
549
550\subsection{Running a Tournament}
551A tournament is a set of sessions. To prepare a tournament, select ``Start'' and then ``Tournament''.
552
553\begin{figure}[htb]
554 \centering
555 \includegraphics[width=0.7\textwidth]{media/multipartytournament.png}
556\caption{Tournament}\label{Fig:multipartytournament}
557\end{figure}
558
559The Tournament tab will appear similar to Figure~\ref{Fig:multipartytournament}. This panel shows a set of tournament options. The detailed meaning of all these settings is explained in \ref{sec:sessiongeneration}.
560
561\begin{itemize}
562 \item \textbf{Protocol}. The protocol to use for each session.
563 \item \textbf{Deadline}. The limits on time and number of rounds for each session.
564 \item \textbf{Number of tournaments}. The number of times the entire tournament will be run.
565 \item \textbf{Agents per Session}. The number of agents N to use for each session.
566 \item \textbf{Agent Repetition}. whether to draw parties with or without return.
567 \item \textbf{Randomize session order}. whether to randomize the session order
568 \item \textbf{Data persistency}. The type of persistent data available to the parties. Same options as in section \ref{sec:singlesessionrun}.
569 \item \textbf{Mediator}. The mediator to use. This option is visible only if the selected protocol needs a mediator.
570 \item \textbf{Agents}. The pool of agents to draw from. Click or drag in the agents area to (de)select agents. Click "Clear" to clear the pool.
571 \item \textbf{Profiles}. The profiles pool. Click or drag in the profiles area to (de)select agents. Click "Clear" to clear the pool.
572 \item \textbf{Special bilateral options}. These options appear only if Agents per session is set to 2 and is discussed in below .
573\end{itemize}
574
575
576
577\subsubsection{Bilateral special options}
578If you have set 'Agents per session' to 2, and deselect 'Agent play both sides', you get an additional panel where you can select different Agents and Profiles for the B side of the 2-sided negotiation as in Figure~\ref{Fig:multipartytournament2}.
579
580\begin{figure}[htb]
581 \centering
582 \includegraphics[width=0.7\textwidth]{media/multipartytournament2.png}
583\caption{Bilateral Tournament}\label{Fig:multipartytournament2}
584\end{figure}
585
586After you click "Start Tournament", the tournament starts. The panel then is swapped for a tournament progress panel (Figure \ref{Fig:tournamentprogress}).
587In the top there is a progress bar showing the total number of sessions and the current session. The table shows all session results. The table is also saved to a $.csv$ log file in the log directory.
588
589\begin{figure}[htb]
590 \centering
591 \includegraphics[width=0.9\textwidth]{media/tournamentprogress.png}
592\caption{Tournament Progress panel}\label{Fig:tournamentprogress}
593\end{figure}
594
595The results of the tournament are shown on screen and also stored in a log file. These results can be easily analyzed by importing them into spreadsheet software such as Excel.
596
597
598\subsection{Running from the command line}
599You can run a multi-party tournament from the command line, as follows.
600
601\begin{enumerate}
602\item Prepare an xml file that describes the settings for the tournament
603\item Run the command runner and give it the prepared file
604\end{enumerate}
605
606\subsubsection{Prepare the XML settings file}
607The first step is to create an xml file containing the values needed for session generation (Section \ref{sec:sessiongeneration}).
608Make a copy of the \verb|multilateraltournament.xml| file inside your genius directory and edit it (with a plain text editor). Inside the \verb|<tournaments>| element you will find a number of \verb|<tournament>| elements. Each of these \verb|<tournament>| elements defines a complete tournament so you can run multiple tournaments using one xml file.
609
610The contents of each \verb|<tournament>| element is as follows. The meaning of the fields is detailed in section \ref{sec:sessiongeneration}.
611
612\begin{itemize}
613\item \textbf{protocolItem}. Contains the protocol to use, in the form of a protocolItem.
614\item \textbf{deadline}. the Deadline value.
615\item \textbf{repeats}. the repeats value.
616\item \textbf{persistentDataType}. The type of the persistent data.
617\item \textbf{numberOfPartiesPerSession}. the Parties per session value.
618\item \textbf{repetitionAllowed}. the value for the Party Repetition.
619\item \textbf{enablePrint}. allow agents to print.
620\item \textbf{partyRepItems}. This element contains a number of \verb|<item>| elements. Each of these party items contains a description of a party as discussed below.
621\item \textbf{mediator}. the mediator, if needed. This is similar in contents to a party item discussed below.
622 \item \textbf{partyProfileItems}. This element contains a number of items. There must be at least as much as numberOfNonMediatorsPerSession.
623 \end{itemize}
624
625We have a number of items:
626\begin{itemize}
627
628\item A profile item : contains
629 \begin{itemize}
630 \item \textbf{url} that contains the description of that party profile. These URIs point to files and therefore are of the form \verb|file:path/to/file.xml|
631 \end{itemize}
632
633\item A party item (and mediator) contains:
634 \begin{itemize}
635 \item \textbf{classPath} the java.party.class.path to the main class. That class must implement the NegotiationParty interface
636 \item \textbf{properties} can contain a number of \verb|<property>| nodes with these values
637 \begin{itemize}
638 \item isMediator: this property indicates the party item is a mediator. If not set, the party will be
639 run as a normal party instead of a mediator, which will probably cause protocol violations
640 \end{itemize}
641 \end{itemize}
642
643\item protocol item. This item contains the protocol information:
644 \begin{itemize}
645 \item \textbf{hasMediator} which is true iff protocol requires mediator
646 \item \textbf{description} a one-line textual description of the mediator
647 \item \textbf{classPath} the java full.class.path of the protocol class
648 \item \textbf{protocolName} a brief protocol name
649 \end{itemize}
650\end{itemize}
651
652
653
654The tournament will consist of sessions created creating all permutations of \verb|<numberOfNonMediatorsPerSession>| from the partyRepItems (with or without reuse, depending on \textbf{repetitionAllowed}. The randomization also is applied to the profile items.
655
656
657\subsubsection{Run the tournament}
658To run the tournament, open a terminal/console and change the working directory to the genius directory.
659Then enter this command (where yourfile.xml is the name of the file you just edited and XXX the version of genius that you use):
660
661\vspace{0.5cm}
662\verb|java -cp genius-XXX-jar-with-dependencies.jar genius.cli.Runner yourfile.xml|
663\vspace{0.5cm}
664
665Press return if the app prompts you for the log file location to log to the default \verb|logs/...csv| file.
666
667\subsection{Tournament Session Generation}\label{sec:sessiongeneration}
668Instead of manually setting all the setting, a tournament generates the exact session settings from the tournament settings. These
669settings are specified either in the user interface settings, or in an XML file. The parameters are:
670
671\begin{itemize}
672\item \textbf{Protocol} The protocol value is used for all sessions. See section \ref{sec:protocols}.
673\item \textbf{Mediator} The mediator to use for all sessions (ignored if the protocol does not need a mediator)
674\item \textbf{Deadline} The deadline is used for all sessions. A deadline contains two values:
675 \begin{itemize}
676 \item \textbf{value}. This is the maximum value determining the deadline. Must be an integer $\ge 1$.
677 \item \textbf{type.} Can be either $ROUND$ or $TIME$. If $ROUND$, the value is the number of rounds. If $TIME$, value is a time in seconds.
678 \end{itemize}
679\item \textbf{Data persistency}. The type of persistent data available to the parties. The next time a party of the same class and same profile runs in a tournament, it will receive the previously stored data. The options are
680 \begin{itemize}
681 \item \textbf{Disabled}. Parties do not receive any persistent data. This is the default.
682 \item \textbf{Serializable}. Parties can save anything serializable in the $PersistentDataContainer$.
683 \item \textbf{Standard}. Parties receive a prepared, read only StandardInfo object inside the $PersistentDataContainer$..
684 \end{itemize}
685\item \textbf{repeats} This is also called 'number of tournaments' and determines the number of times a complete tournament will be run.
686\item \textbf{Randomize Session Order} Whether all generated sessions within a tournament must be randomized.
687\item \textbf{Parties per session} The number of parties to draw for each session. This excludes a possible mediator.
688\item \textbf{Party Repetition} true if parties are to be drawn from the parties pool with return, false if they are to be drawn without return.
689\item \textbf{Parties and Profile pool for side A} A list from which parties and profiles will be drawn
690\item \textbf{Parties and Profile pool for side B} Another list of parties and profiles. Only used with bilateral generation (see below).
691\end{itemize}
692
693The tournament generation works as follows.
694
695If there are exactly 2 parties per session and the parties and profiles for side B have been set, then bilateral generation is used. Otherwise, multilateral generation is used. This generation method creates an ordered list of sessions for 1 tournament. If the 'Randomize Session Order' is set, the list is randomized. All sessions use the same protocol, mediator, deadline and data persistency.
696This generation is called repeatedly, as set in 'repeats', and all generated session lists are accumulated in a big session list. This is the final result of the tournament generation.
697
698\subsubsection{Multilateral generation}
699In multilateral generation, all possible combinations of parties and profiles (using pool A) are generated as follows. the indicated number of parties per session $N$ are drawn from party pool A, with our without return as specified in 'Party Repetition'. Also, $N$ profile items are drawn, ordered without return, from the profiles pool. These two lists are then paired into groups of $N$ party-profile pairs.
700
701\subsubsection{Bilateral generation}
702In bilateral generation, first a set of participants P of all combinations of 1 party and 1 profile are drawn from the side A pool. Similarly a set of participants Q is drawn for the B pool. Then, the sessions set consists of all combinations of one participant from P and another participant from Q .
703
704
705
706
707
708%=========================================================================================
709\section{Quality Measures}\label{sec:qm}
710
711Genius logs a large number of quality measures to log files~\cite{Baarslag12AI,Baarslag13AIT}. Logs are written both in \verb|.csv| and \verb|.xml| format.
712Logs are written to the \verb|log/| directory. Filenames contain the date and time the session/tournament started.
713
714The output of the log files differs, depending on whether you ran a tournament or a single session. The following subsections discuss the output for these.
715
716Party names are printed as follows. If the party is a normal NegotiationParty, then the party will print out as something like \verb|Atlas32016@2|. The part before the '@' is the party's name, the part after the '@' is added by the runner to make the name unique. If the party is a BOA party, the name is "boa-" followed by the concatenation of its offering strategy, acceptance condition, opponentmodel and omstrategy. For example you may get this as boa party name:
717
718\begin{verbatim}
719boa-genkus.core.boaframework.offeringstrategy.anac2012.CUHKAgent_Offering-
720genius.core.boaframework.acceptanceconditions.anac2012.AC_CUHKAgent-
721genius.core.boaframework.opponentmodel.CUHKFrequencyModelV2-
722genius.core.boaframework.omstrategy.TheFawkes_OMS@3
723\end{verbatim}
724
725
726\subsection{Session logs}
727Both the XML and CSV log files from a session get the filename \verb|Log-Session_| followed by day and time. The contents however differ.
728
729\subsubsection{Session CSV file}
730 The \verb|.csv| file contains one line for each turn, like this:
731\verb|1,1,0.0055248618784530384,AgentHP2_main@0,(Offer bid:Bid[Food: Chips and Nuts, ...ials, ])|
732
733The columns are, in order:
734\begin{enumerate}
735\item round number.
736\item turn number
737\item the time of agreement, in the range [0,1] where 0 means the start of the session and 1 the maximum time/number of rounds allowed for the negotiation.
738\item the party that acted.
739\item the action that the party did. The action consists of the action type name ("Offer", "Accept", "EndNegotiation", etc) and the bid details if available.
740\end{enumerate}
741
742
743\subsubsection{Session XML file}
744When running a session, the XML file contains only the details of the final outcome of the negotiation.
745
746The fields in the \verb|NegotiationOutcome| element:\label{table:NegotiationOutcome}
747\begin{enumerate}
748\item currentTime: the moment when the final outcome was available.
749\item timeOfAgreement, agreement time in the range [0,1] where 0 means the start of the session and 1 the maximum time/number of rounds allowed for the negotiation.
750\item lastAction: the last action that was done
751\item the domain that was being run
752\item bids: the total number of bids that have been done in this session
753\item the total run time in seconds
754\item the outcome : the final accepted bid , or "-" if there was no final agreement
755\item the startingAgent,
756\item the deadline = maximum amount of time/rounds for this session.
757\end{enumerate}
758
759and then, for each of the parties that participated a "resultsOfAgent" element containing:
760\begin{enumerate}
761\item the party's name.
762\item the party's description.
763\item the party's utilityspace filename.
764\item the full party class path.
765\item the user utility (the true performance of the agent: equal to the discounted final utility minus the total user bother)
766\item the final utility (un-discounted) of this party, or 0 if there was no agreement.
767\item the final utility (discounted).
768\item the value of discount(1,1). This is the remaining utility that a un-discounted utility of 1 would have at the end time (t=1). For default discount formulas, this equals the 'discount factor'.
769\item the total user bother. This quantifies how much the agent elicited the User in the uncertainty setting. Equal to 0 if the agent did not elicit anything or the negotiation did not take place under uncertainty.
770\end{enumerate}
771
772
773Here's an example
774\begin{verbatim}
775<?xml version="1.0"?>
776<Session>
777 <NegotiationOutcome currentTime="Mon Oct 14 11:51:49 CEST 2019"
778 timeOfAgreement="0.09836065573770492"
779 lastAction="(Accept bid:Bid[Food: Chips and Nuts, Drinks: Handmade Cocktails, Location: Party Room, ...
780 domain="etc/templates/partydomain/party_domain.xml" bids="10" runtime="0.023675353" finalOutcome="Bid[...
781 startingAgent="-" deadline="60rounds">
782 <resultsOfAgent agent="TOP_3_Agent" agentDesc="BOA(AC_Top3,O_S Top3,Default,Offer Best Bids)"
783 utilspace="etc/templates/partydomain/party1_utility.xml"
784 agentClass="genius.core.repository.boa.BoaPartyRepItem$1"
785 userUtility="0.7398203133659815" finalUtility="0.7848203133659816"
786 discountedUtility="0.7848203133659816" discount="1.0" totalUserBother="0.045">
787 </resultsOfAgent>
788 <resultsOfAgent agent="TimeDependentAgentLinear@1" agentDesc="concedes linearly with time"
789 utilspace="etc/templates/partydomain/party2_utility.xml"
790 agentClass="agents.TimeDependentAgentLinear"
791 userUtility="0.9285654723948509" finalUtility="0.9285654723948509"
792 discountedUtility="0.9285654723948509" discount="1.0" totalUserBother="0.0">
793 </resultsOfAgent>
794 </NegotiationOutcome>
795</Session>\end{verbatim}
796
797
798
799\subsection{Tournament logs}
800All log files from a tournament get the filename \verb|tournament-| followed by day and time followed by the domain name and an extension.
801There are 3 log files created: a log.csv file, a log.xml file and a logStats.xml file.
802
803If you terminate a tournament before it completes, the .log. files will be written up to the last completed session and there will be no logStats file.
804
805\subsubsection{Tournament log.csv file}
806
807tournament .csv files start with these a line containing \verb|sep=;| indicating that we use the comma as separator character for fields.
808Then there is a table header typically looking like this (if there are 3 parties in each session, and all this on 1 line)
809\begin{verbatim}
810Run time (s);Round;Exception;deadline;Agreement;Discounted;#agreeing;min.util.;max.util.;
811 Dist. to Pareto;Dist. to Nash;Social Welfare;
812 Agent 1;Agent 2;Agent 3;
813 Utility 1;Utility 2;Utility 3;
814 Disc. Util. 1;Disc. Util. 2;Disc. Util. 3;
815 Perceived. Util. 1;Perceived. Util. 2;Perceived. Util. 3;
816 User Bother 1;User Bother 2;User Bother 3;
817 User Util. 1;User Util. 2;User Util. 3
818 Profile 1;Profile 2;Profile 3
819\end{verbatim}
820
821The rest of the log file contains one line for each final session outcome, matching the columns in the header:
822
823\begin{enumerate}
824\item the run time of that session (seconds).
825\item the number of rounds that were completed
826\item the exception message, if an exception occured
827\item the deadline = maximum amount of time/rounds for this session.
828\item whether an agreement was reached (Yes) or not (No).
829\item whether there was a discount factor (i.e. discount(1,1) is not 1) (Yes or No).
830\item the final number of agreeing parties
831\item the minimum utility achieved by the parties
832\item the maximum utility achieved by the parties
833\item the distance to the pareto curve (the nearest bidpoint on the pareto)
834\item the distance to the nash optimum point
835\item the distance to the social welfare point
836\item the names of all parties
837\item the un-discounted utilities of all parties.
838\item the discounted utilities of all parties
839\item the perceived utilities of all parties.
840\item the user bother of all parties
841\item the user utility of all parties
842\item the profile names of all the parties
843\end{enumerate}
844
845If the profile is a Utilityspace, then the discounted and un-discounted utilities are as in the original utilityspace provided to the agent. The perceived utility in that case equals to the discounted utility. The user utility as well, and the user bother is equal to 0.
846If the profile is a partially ordered profile, the core (but not the agent) knows the utility in the AdditiveUtilitySpace that was used to create the profile. In that case, the un-discounded and discounted utilities are utilities as in the AdditiveUtilitySpace. The agent is provided with another AdditiveUtilitySpace that was generated based on the partially ordered profile, and usually will differ from the original AdditiveUtilitySpace. The perceived utility is the (discounted) utility of the bid in that estimated space.
847The perceived utility is available only in the CSV file in tournament logs, not in XML log files. The user bother represents how much the agent performed elicitation actions. The user utility represents the true performance of the agent, it is equal to the discounted utility minus the user bother.
848
849For example, one line of the output can look like this (all on 1 line)
850
851\begin{verbatim}
8524.965;173;;180rounds;Yes;No;3;0.58083;0.95256;0.00000;0.44991;2.13706;
853ClockworkAgent@14;Farma@15;Caduceus@16;
8540.5808333333333333;0.6036696609166442;0.9525594478616071;
8550.5808333333333333;0.6036696609166442;0.9525594478616071;
8560.5808333333333333;0.6036696609166442;0.9525594478616071;
8570.0;0.0;0.0;
8580.5808333333333333;0.6036696609166442;0.9525594478616071;
859party1_utility.xml;party2_utility.xml;party3_utility.xml
860\end{verbatim}
861
862\subsubsection{Tournament log.xml file}
863
864The .log.xml file contains one \verb|<NegotiationOutcome>| element for each completed round.
865These elements are formatted exactly as in \ref{table:NegotiationOutcome}.
866
867\subsubsection{Tournament logStats.xml file}
868The logStats.xml file contains for each of the parties that participated in the tournament statistical info:
869
870\begin{enumerate}
871\item agentname: the party's name (full class path)
872\item totalUndiscounted: the total sum of the un-discounted utilities that it achieved
873\item totalDiscounted: the total sum of the discounted utilities that it achieved
874\item numberOfSessions: the total number of sessions that it participated in
875\item totalNashDist: the accumulated distances to the Nash Point
876\item totalWelfare: the accumulated distances to the Social Welfare Point
877\item totalParetoDistance: the accumulated distances to the Pareto frontier
878\item meanDiscounted: totalDiscounted / numberOfSessions
879\item meanUndiscounted: totalUndiscounted / numberOfSessions
880\item meanNashDistance: totalNashDistance / numberOfSessions
881\item meanWelfare: totalWelfare / numberOfSessions
882\item meanPareto: totalPareto / numberOfSessions
883\end{enumerate}
884
885
886%
887%
888%\subsection{Analyzing Logs using Excel}~\label{sec:analysisExcel}
889%The logs are in XML and CSV format, so we can easily analyze them with Excel. Note that the following discussion does not apply to the starter edition of Excel, as it does not support Pivot tables.
890%
891%The XML data of the standard log can be converted to a normal table by importing the data into Excel using the default options. This results in a large table showing the result for both agents A and B for each session. Analyzing these results manually is complicated, therefore we recommend to use pivot tables. Pivot tables allow to summarize a large set of data using statistics and can be created by selecting ``Insert'' and then ``Pivot Table''. To illustrate, by dragging the \textit{agentName} in ``Row Labels'' and the \textit{discountedUtility} in ``Values'' (see Figure~\ref{fig:pivottable}), we can easily see which agent scored best in the tournament. If solely the amount of matches of each agent is displayed, you need to set the ``Value Field Settings'' of \textit{discountedUtility} to average instead of count.
892%
893%\begin{figure}[htb]
894% \centering
895% \includegraphics[width=0.4\textwidth]{media/PivotTable.png}
896%\caption{Configuration required to summarize the discounted utility of each agent.}\label{fig:pivottable}
897%\end{figure}
898
899
900%=========================================================================================
901
902\section{Creating a Negotiation Party}\label{sec:createagent}
903To create an negotiation party, we suggest to follow the instructions in the Appendix (Section \ref{sec:appendix}) and start with one of the examples.
904You can then proceed by changing the example.
905
906
907\subsection{Example Parties}
908The {\Genius} zip file contains a number of example parties: the bilateral examples, multiparty example, and the storage example. To compile an example, set up your workspace as in the appendix (Section \ref{sec:appendix}) and copy an example folder into \verb|src/|.
909
910\begin{enumerate}
911
912\item The bilateral examples illustrate how to develop agents for bilateral negotiations. They illustrate the use of the domain, preferences, offers, the BOA framework, and preference uncertainty:
913\begin{itemize}
914 \item The \textit{RandomBidderExample} is the easiest example to start with. This simple example agent makes random bids above a minimum target utility and demonstrates the core uses of offers and utility.
915 \item The \textit{BoaPartyExample} shows how to create an independent agent out of several BOA components and how to handle preference uncertainty.
916 \item The \textit{CustomUtilitySpacePartyExample} shows how a party can deal with preference uncertainty by defining a custom \textit{UtilitySpace} based on the closest known bid.
917\end{itemize}
918
919You can run all these agents with an UncertainAdditiveutilitySpace (for example the profiles with preference uncertainty defined on the \verb|party_domain.xml|, namely: \verb|party1_utility_u|$N$\verb|.xml| and \verb|party2_utility_u|$N$\verb|.xml|).
920
921\item The multiparty example just accepts any acceptable bid with a random probability of 0.5.
922
923\item The storage example demonstrates using the persistent data storage. This example is showing how the storage can be used to wait a little longer every next time the party is in a negotiation.
924
925To run this example, you need to set up {\Genius} to allow persistent data storage (the default is off). In the {\Genius} tournament setup panel, use the following settings
926\begin{itemize}
927\item number of tournaments= 20
928\item agents per session =2
929\item persistency=standard
930\item agent side A: GroupX, \verb|party1_utility.xml|
931\item agent side B: Random Party, \verb|party6_utility.xml|
932\end{itemize}
933
934and start the tournament and check the number of rounds till agreement: it will increase every session.
935
936Now run another tournament with the same settings but pick select both \verb|party1_utility.xml| and \verb|party2_utility.xml|. Run the tournament.
937Now you will see that the the number of rounds till agreement goes up every other run. This is because your party gets a different profile every other run and thus there are persistent data stores, one for each profile.
938
939
940
941\end{enumerate}
942
943\subsection{Implementing NegotiationParty}
944This section discusses details of implementing a NegotiationParty.
945
946Every party must at least implement the \texttt{genius.core.parties.NegotiationParty} interface (Table \ref{table:NegotiationPartyInterface}), Also the implementation must have a public default (no-argument) constructor. Please refer to the javadocs for details on the parameters.
947
948\begin{table*}[t]
949 \centering
950 \begin{tabular}{|p{4cm}|p{7cm}|}
951 \hline
952 Method & description \\
953 \hline\hline
954 init &Initializes the party, informing it of many negotiation details. This is be called exactly once by the negotiation system, immediately after construction of the class \\
955 chooseAction & When this function is called, it is expected that the Party chooses one of the actions from the possible action list and returns an instance of the chosen action. \\
956 receiveMessage & This method is called to inform the party that another NegotiationParty chose an Action.\\
957 getDescription & Returns a human-readable description for this party \\
958 getProtocol & The actual supported MultilateralProtocol. Usually this returns StackedAlternating\-Offers\-Protocol. Your party should override this if it supports a another protocol\\
959 negotiationEnded & This is called to inform the party that the negotiation has been ended. This allows the party to record some final conclusions about the run\\
960 \hline
961 \end{tabular}
962 \caption{Methods of NegotiationParty. Check the javadoc for all the details}
963 \label{table:NegotiationPartyInterface}
964\end{table*}
965
966
967For convenience, we recommend you extend the class \texttt{genius.core.parties.AbstractNegotiationParty} which is a basic implementation of NegotiationParty. This class also provides convenient support functions for building your party.
968
969Your party might need to check the exact type of the provided AbstractUtilitySpace (inside NegotiationInfo), for instance if your party supports for example only AdditiveutilitySpace. Also check the provided UserModel, if that is set (not null) then this overrides the value returned by getUtilitySpace..
970
971A number of useful classes is given in \ref{tab:agentclass}. The javadoc contains the full details of all available classes. We recommend to use the javadoc included with the distribution to check the details of all the involved classes. Notice that some classes, e.g. SortedOutcomeSpace, may take a long time and large amounts of memory to sort a large bid space, which may exceed the available time and space for your party. Therefore these methods should be used with caution.
972
973\begin{table}
974\begin{tabular}{m{0.9\textwidth}}
975\hline
976\texttt{NegotiationInfo}\\
977The context of the negotiation: the partial profile ("UserModel"), utility space, the timeline and deadline, the agentID and persistent data container.\\
978\hline
979\texttt{UtilitySpace}\\
980The preference profile of the scenario allocated to the party. It is recommended to use this class when implementing a model of the opponent's preference profile.\\
981\hline
982\texttt{Timeline }\\
983Use timeline for every time-related by using \texttt{getTime()}.\\
984\texttt{Action chooseAction(List<Class<? extends Action>> possibleActions)}\\
985This function should return the action your party wants to make next.\\
986\hline
987\texttt{Action}\\
988Superclass of negotiation actions like Offer, Accept and EndNegotiation..\\
989\hline
990\texttt{BidHistory}\\
991a structure to keep track of the bids presented by the party and the opponent.\\
992\hline
993\texttt{SortedOutcomeSpace}\\
994a structure which stores all possible bids and their utilities by using BidIterator. In addition, it implements search algorithms that can be used to search the space of possible bids for bids near a given utility or within a given utility range. WARNING (1) SortedOutcomeSpace iterates over all bids and thus might be unusable in large bidspaces (2) Some parties have created their own copy of SortedOutcomeSpace, so be careful to pick the genius.core version. \\
995\hline
996\texttt{BidIterator}\\
997a class used to enumerate all possible bids. Also refer to \textit{SortedOutcomeSpace}.\\
998\hline
999\texttt{BidDetails}\\
1000a structure to store a bid and its utility.\\
1001\hline
1002\end{tabular}
1003
1004\caption{Important classes used for creating a NegotiationParty.}
1005\label{tab:agentclass}
1006\end{table}
1007
1008\FloatBarrier
1009
1010\subsubsection{Receiving the Opponent's Action}\label{sec:receiveAction}
1011The \texttt{ReceiveMessage(Action opponentAction)} informs you that the opponent just performed the action \texttt{opponentAction}. The \texttt{opponentAction} may be \texttt{null} if you are the first to place a bid, or an \texttt{Offer}, \texttt{Accept} or \texttt{EndNegotiation} action.
1012The \texttt{chooseAction()} asks you to specify an \texttt{Action} to send to the opponent.
1013
1014In the SimpleAgent code, the following code is available for \texttt{receiveMessage}. The SimpleAgent stores the opponent's action to use it when choosing an action.
1015
1016\begin{lstlisting}
1017public void receiveMessage(Action opponentAction) {
1018 actionOfPartner = opponentAction;
1019}
1020\end{lstlisting}
1021
1022\subsubsection{Choosing an Action}\label{sec:chooseAction}
1023The code block below shows the code of the method \texttt{chooseAction} for SimpleAgent. For safety, all code was wrapped in a try-catch block, because if our code would accidentally contain a bug we still want to return a good action (failure to do so is a protocol error and results in a utility of 0.0).
1024
1025The sample code works as follows. If we are the first to place a bid, we place a random bid with sufficient utility (see the .java file for the details on that). Else, we determine the probability to accept the bid, depending on the utility of the offered bid and the remaining time. Finally, we randomly accept or pose a new random bid.
1026
1027While this strategy works, in general it will lead to suboptimal results as it does not take the opponent into account. More advanced parties try to model the opponent's strategy or preference profile.
1028
1029\begin{lstlisting}
1030public Action chooseAction() {
1031 Action action = null;
1032 Bid partnerBid = null;
1033 try {
1034 if (actionOfPartner == null)
1035 action = chooseRandomBidAction();
1036 if (actionOfPartner instanceof Offer) {
1037 partnerBid = ((Offer) actionOfPartner).getBid();
1038 double offeredUtilFromOpponent = getUtility(partnerBid);
1039 double time = timeline.getTime();
1040 action = chooseRandomBidAction();
1041 Bid myBid = ((Offer) action).getBid();
1042 double myOfferedUtil = getUtility(myBid);
1043 // accept under certain circumstances
1044 if (isAcceptable(offeredUtilFromOpponent, myOfferedUtil, time))
1045 action = new Accept(getAgentID(), partnerBid);
1046 }
1047 if (timeline.getType().equals(Timeline.Type.Time)) {
1048 sleep(0.005); // just for fun
1049 }
1050 } catch (Exception e) {
1051 // best guess if things go wrong. Notice this may still fail
1052 action = new Accept(getAgentID(), partnerBid);
1053 }
1054 return action;
1055}
1056\end{lstlisting}
1057
1058The method \textit{isAcceptable} implements the probabilistic acceptance function$P_\text{accept}$:
1059
1060\begin{equation}
1061 P_\text{accept} = \dfrac{u - 2ut + 2\left(t - 1 + \sqrt{(t - 1)^2 + u(2t - 1)}\right)}{2t - 1}
1062\end{equation}
1063where $u$ is the utility of the bid made by the opponent (as measured in our utility space), and $t$ is the current time as a fraction of the total available time. Figure~\ref{Fig:Paccept} shows how this function behaves depending on the utility and remaining time. Note that this function only decides if a bid is acceptable or not. More advanced acceptance strategies (cf.~\cite{Baarslag13AAMAS,Baarslag13DSS,ANAC2010KawExt} can also take into account other factors and actions such as \texttt{EndNegotiation}.
1064
1065\begin{figure}[htb]
1066 \centering
1067 \includegraphics[width=0.3\textwidth]{media/image21.png}
1068 \caption{$P_\text{accept}$ value as function of the utility and time (as a fraction of the total available time).}\label{Fig:Paccept}
1069\end{figure}
1070
1071
1072
1073
1074
1075\subsection{Implementing a party with preference uncertainty}
1076\label{sec:newUncertainAgent}
1077
1078In order to program an agent with preference uncertainty, we recommend that your agent extends the \textit{AbstractNegotiationParty} class. That class has some support functions that load the normal utilityspace with an approximation that is useful for plotting outcomes.
1079% This example is not yet there.
1080%An example of an agent that can work with uncertainty is the \textit{UncertaintyAgentExample}.
1081%When referring to code in this section, this will be code from either the \textit{AbstractNegotiationParty} class or the \textit{UncertaintyAgentExample}.
1082
1083\subsubsection{Overriding functions}
1084In order to change the way your agent handles preference uncertainty, you can override the \textit{estimateUtilitySpace()} function. This function in AbstractNegotiationParty returns an \textit{AbstractUtilitySpace} object. In the \textit{AbstractNegotiationParty} class, this code looks as follows:
1085 \begin{lstlisting}
1086public AbstractUtilitySpace estimateUtilitySpace() {
1087 Domain domain = getDomain();
1088 AdditiveUtilitySpaceFactory factory
1089 = new AdditiveUtilitySpaceFactory(domain);
1090 BidRanking bidRanking = userModel.getBidRanking();
1091 factory.estimateUsingBidRanks(bidRanking);
1092 return factory.getUtilitySpace();
1093}
1094\end{lstlisting}
1095
1096As can be seen from the function, a custom \textit{AbstractUtilitySpace} is created using the domain and the bid ranking. This function approximates the utility function using a simple counting heuristic. This heuristic does not perform very well, so there is need to implement your own function. An example is included in the \textit{UncertaintyAgentExample}. In this example, the \textit{AbstractNegotiationParty} class is extended and the \textit{estimateUtilitySpace()} function is overridden. Overriding this function can be done as follows:
1097\begin{lstlisting}
1098@Override
1099public AbstractUtilitySpace estimateUtilitySpace()
1100{
1101 return new AdditiveUtilitySpaceFactory(
1102 getDomain()).getUtilitySpace();
1103}
1104\end{lstlisting}
1105
1106This function overrides the standard function and implements its own method to estimate the Utility space. Currently, this returns a utility function with equal weights and values set to zero. To estimate the utility function, you can use the \textit{BidRanking} class. The bid ranking for the current session can be accessed using \textit{userModel.getBidRanking()}. The next section will show what information is included in the \textit{BidRanking}.
1107
1108\subsubsection{Bid Ranking}
1109When running an uncertain agent, all utility information is given through a bid ranking. This bid ranking consists of an ordering of different bids for the current domain. The ranking that the agent receives is ordered from low utility to high utility. This ranking can be used to estimate a utility function.
1110
1111The \textit{BidRanking} class consists of a list of \verb|Bid|s. To obtain the \textit{Bid} classes from the \textit{Bidranking}, you can use the \textit{getBidOrder()} function on the \textit{Bidranking} object. This object is obtained in the agent using \textit{userModel.getBidRanking()}. Check the javadoc for more details, and we suggest you check the source code of BidRanking, and makes it a little easier to compare the original utilityspace with the estimation.
1112
1113To access the list of \textit{Bid} objects directly, you can use the following snippet:
1114\begin{lstlisting}
1115List<Bid> bids = userModel.getBidRanking().getBidOrder();
1116\end{lstlisting}
1117
1118The bids that are obtained from the \textit{BidRanking} using the \textit{getBidOrder()} function are listed from low utility to high utility. This means that the first element in the list has the lowest utility score. When iterating over the list, every next bid will be either valued \textbf{higher or the same} as the current bid in the list.
1119
1120\textit{BidRanking} also contains the recommended utility values through \textit{getLowUtility()} and \textit{getHighUtility()}. These values can be used for the worst and best bid in the list.
1121
1122
1123\subsubsection{Elicitation through the User}
1124An agent working under preference uncertainty may elicit information about the true utility to improve its user model against an elicitation cost. All elicitation actions are implemented as methods in the \textit{User} class. As of right now, the only elicitation action an agent can make is \textit{elicitRank}. \textit{elicitRank} takes as input a bid $b$ and a User Model $userModel$, and returns an updated User Model corresponding to \textit{userModel} augmented with $b$ in the Bid Ranking. To call \textit{elicitRank}, an agent must call it through the User object in this way:
1125\begin{lstlisting}
1126userModel = user.elicitRank(b, userModel);
1127\end{lstlisting}
1128
1129\textit{elicitRank} is performed against an elicitation cost that the User holds as an attribute. To obtain the elicitation cost, an agent can use \textit{user.getElicitationCost()}. Each time \textit{elicitRank} is called by an agent, this cost is added to the total bother which is an attribute of User as well. To obtain the total bother, an agent can use \textit{user.getTotalBother()}.
1130A good thing to keep in mind when using \textit{elicitRank} is that the total bother won't get incremented it you are trying to call it with a bid that is already in the User Model.
1131
1132Note: As of right now, the total bother is only implemented as constant increments of the elicitation cost. In theory however, it could be a very different function. All such possibilities are what we call bother cost functions. Future developments will explore extensions of the User class to support different types of bother cost functions.
1133
1134
1135\subsubsection{Accessing the real utility space for debugging}
1136If the utiltity space was saved with the ``experimental setup'' checkbox enabled (Figure \ref{fig:utilcreated}) then your agent can access the real utility function. Such a utility space can be used to verify the utility function that your agent creates itself. In order to get access to this function, the userModel should be cast to an \textit{ExperimentalUserModel} object. This can be done as follows:
1137\begin{lstlisting}
1138ExperimentalUserModel e = (ExperimentalUserModel) userModel;
1139UncertainAdditiveUtilitySpace realUSpace = e.getRealUtilitySpace();
1140\end{lstlisting}
1141
1142Now, you will have access to the real utility space with \textit{realUSpace}.
1143
1144\subsubsection{Preference uncertainty agent checklist}
1145This section will give a short overview of what to do in order to enable your agent to work with preference uncertainty. You should take the following steps:
1146\begin{enumerate}
1147 \item Extend the \textit{BoaParty} or \textit{AbstractNegotiationParty} class (examples can be found in the \textit{bilateralexamples} folder).
1148 \item Override the \textit{estimateUtilitySpace()} function that returns an \textit{AbstractUtilitySpace} class.
1149 \item Using the \textit{getDomain()} function and the \textit{BidRanking}, create an estimation for the utility function. (E.g. Counting, Machine Learning, Statistical methods, etc.; see for example:~\cite{Ayd14,BaarslagValueOfInformation,UTAGMS,Ros16,Sri73,Tsi18,Zin18})
1150 \item Implement the normal methods necessary for the agent to do the bidding. This is the same as for normal agents; the preference uncertainty is only used on startup of the agent in order to estimate the utility function.
1151\end{enumerate}
1152
1153
1154\subsection{Loading a NegotiationParty}
1155
1156You need to load your custom party into the {\Genius} party repository in order to use it. After adding, your party will appear in the combo boxes in the multilateral tournament runner and session runner where you can select the party to use.
1157
1158Locate the Parties repository tab in the GUI (Figure \ref{fig:partiesrepo}). Right click in this area and select "Add Party". A file browser panel pops up. Browse to your compiled \verb|.class| file that implements the NegotiationParty and select it. Typically Eclipse compiles into \verb|bin|. Your party will appear at the bottom of the parties repository. The \verb|partyrepository.xml| file is automatically updated accordingly.
1159
1160\begin{figure}[h!]
1161 \center
1162 \includegraphics[width=10cm]{media/partiesrepo.png}
1163 \caption{The parties repository.}
1164 \label{fig:partiesrepo}
1165\end{figure}
1166
1167
1168To do this manually without using the GUI, quit {\Genius}, open the \verb|partyrepository.xml| file \footnote{This file is automatically created the first time you run {\Genius}} and add a section like this
1169
1170\begin{lstlisting}
1171<partyRepItem classPath="full.class.of.your.party" <properties/> />
1172\end{lstlisting}
1173
1174After that you can restart {\Genius} so that it loads the new party.
1175\FloatBarrier
1176
1177\subsection{Third party code}
1178You should not use maven or jars to add dependencies for your party. The reason is {\Genius} or other parties might already have another version of your library in use. Java 8 can not deal properly with multiple versions of the same library within a single JVM. The result would be inconsistent, incorrect or buggy behaviour, or even crashes.
1179
1180Instead, if you want to use a third party library, you will have to include all the source code of that library with your code, including all sub-dependencies. Also ensure the imports in all sources are renamed accordingly. The code should be copied inside the package name of your party, instead of using the original package name of that library (so do not use "org.apache" for instance). This is to ensure that we are really running your party on the specific version of the library that your party needs and to avoid version conflicts (java will run an unspecified version of the library in case of conficts).
1181
1182
1183%=========================================================================================
1184\section{Creating a BOA Party}\label{sec:boa}
1185Instead of implementing your negotiating party from scratch, you can create a BOA party using the \textit{BOA framework}~\cite{BaarslagBOA}.
1186The BOA negotiation party architecture allows to reuse existing components from other BOA parties. Many of the sophisticated party strategies that currently exist are comprised of a fixed set of modules. Generally, a distinction can be made between four different modules: one module that decides whether the opponent's bid is acceptable (\textit{acceptance strategy}); one that decides which set of bids could be proposed next (\textit{offering strategy}); one that tries to guess the opponent's preferences (\textit{opponent model}), and finally a component which specifies how the opponent model is used to select a bid for the opponent (\textit{opponent model strategy}). The overall negotiation strategy is a result of the interaction between these components.
1187
1188The advantages of separating the negotiation strategy into these four components (or equivalently, fitting a party into the BOA framework) are threefold: first, it allows to \textit{study the performance of individual components}; second, it allows to \textit{systematically explore the space of possible negotiation strategies}; third, the reuse of existing components \textit{simplifies the creation of new negotiation strategies}~\cite{BaarslagComponentAnalysis}.
1189
1190{\bf Warning:} Many of the provided BOA components currently assume a single opponent party, which will behave incorrectly when used with multiple opponents. We recommend checking the source code of the BOA components you want to use, or write your own components if you are creating a multilateral NegotiationParty.
1191
1192
1193\subsection{Components of the BOA Framework}
1194A negotiation party in the BOA framework, called a \textit{BOA party}, consists of four components:
1195\begin{description}
1196 \item[Offering strategy] An offering strategy is a mapping which maps a negotiation trace to a bid. The offering strategy can interact with the opponent model by consulting with it.%, passing one or multiple bids and see how they compare within the opponent's utility space.
1197
1198 \item[Opponent model] An opponent model is in the BOA framework a learning technique that constructs a model of the opponent's preference profile.% In our approach, the opponent model should be able to estimate the opponent's utility of a given bid.
1199 \item[Opponent model strategy] An opponent model strategy specifies how the opponent model is used to select a bid for the opponent and if the opponent model may be updated in a specific turn.
1200 \item[Acceptance strategy] The acceptance strategy determines whether the opponent's bid is acceptable and may even decide to prematurely end the negotiation.
1201\end{description}
1202The components interact in the following way (the full process is visualized in Figure~\ref{fig:flowchart}). When receiving a bid, the BOA party first updates the \textit{bidding history}. Next, the \textit{opponent model strategy} is consulted if the \textit{opponent model} may be updated this turn. If so, the \textit{opponent model} is updated.
1203
1204Given the opponent's bid, the \textit{offering strategy} determines the counter offer by first generating a set of bids with a similar preference for the party. The \textit{offering strategy} uses the \textit{opponent model strategy} to select a bid from this set taking the opponent's utility into account.
1205
1206Finally, the \textit{acceptance strategy} decides whether the opponent's action should be accepted. If the opponent's bid is not accepted by the acceptance strategy, then the generated bid is offered instead.
1207
1208\begin{figure}[t]
1209 \center
1210 \includegraphics[width=15.0cm]{media/BOAflow.png}
1211 \caption{The BOA Framework Architecture.}
1212 \label{fig:flowchart}
1213\end{figure}
1214
1215\FloatBarrier
1216
1217\subsection{Create a BOA Party}
1218A boa parties can be edited in the "Boa Parties" repository tab (Figure \ref{fig:boaparties}). Right-click in the panel to add items. Select an item and right-click to remove or edit an item.
1219
1220
1221\begin{figure}[!ht]
1222 \center
1223 \includegraphics[width=10.0cm]{media/boacomponants.png}
1224 \caption{The BOA Parties repository tab.}
1225 \label{fig:boaparties}
1226\end{figure}
1227
1228
1229After you selected to add or edit a BOA party (Figure \ref{fig:editboaparty}). Here you can select a different Offering Strategy, Acceptance Strategy, Opponent Model and Opponent Model Strategy by selecting the appropriate strategy with the combo boxes. If the strategy has parameters, the current parameter settings are shown and the respective "Change" button enables.
1230
1231
1232\begin{figure}[!ht]
1233 \center
1234 \includegraphics[width=10.0cm]{media/EditBoaParty.png}
1235 \caption{Editing a BOA party.}
1236 \label{fig:editboaparty}
1237\end{figure}
1238
1239If you click on the "Change" button, another panel pops up where you can edit the parameters (Figure \ref{fig:editparameters}). You can click directly in the table to edit values.
1240
1241\begin{figure}[!ht]
1242 \center
1243 \includegraphics[width=10.0cm]{media/EditParameters.png}
1244 \caption{Editing the Parameters of a BOA party.}
1245 \label{fig:editparameters}
1246\end{figure}
1247
1248When you have correctly set all strategies and their parameters, you can click the "OK" button in the BOA party editor (Figure \ref{fig:editboaparty}). Then, parties with the given name are generated, one for each permutation of the range of settings you set in the parameters. For example, if you set you want parameter m to have values 0,1 and 2 and x to have values 7 and 8, there will appear 6 new parties, with settings [0,7],[0,8],[1,7],[1,8],[2,7], and [2,8]. Be careful with this generation as it is easy to create an excessive amount of boa parties this way.
1249
1250
1251\subsection{Creating BOA Components} \label{sec:creating-boa-components}
1252This section discusses how create your own components. An example implementation of each component is included in the ``bilateralexamples/boacomponents'' folder. The next section discusses how these components can be added to the list of available components in the BOA framework GUI.
1253
1254The \verb|bilateralexamples/boacomponents| folder contains two acceptance components:
1255\begin{itemize}
1256\item \verb|AC_Next| which will accept an opponent bid if the utility is higher than the bid the agent is ready to present
1257\item \verb|AC_Uncertain| which can handle both normal and uncertain profiles.
1258\end{itemize}
1259
1260\subsubsection{Set up a Workspace}
1261BOA components must be compiled before they can be loaded into Genius.
1262To compile a BOA component, follow the steps in (Section \ref{sec:appendix}). Then, create your BOA code into \verb|src|. For a quick start, you can copy the bilateralexamples folder into \verb|src|. Eclipse automatically compiles your BOA components into \verb|bin|.
1263
1264Please refer to chapter \ref{sec:debugging} for instructions on running {\Genius} in debug mode to debug your components.
1265
1266\subsubsection{Add component to Genius}
1267After your component has been compiled, you need to tell Genius where to find it.
1268Go to the "BOA Components" tab and right click in the table. Select "Add new component". Enter the component name and click "Open". Browse to your compiled component and click "Open". Click ""Add component". After this, your component appears in the list and is ready for use.
1269
1270\subsubsection{Parameters}
1271All BOA components have the same mechanism to be tuned with parameters. They should have no constructor : the default empty constructor will be called. They initialize through a call to init().
1272
1273The parameters and their default parameters are indicated by the component by overriding the getParameters() function. This function should return a set of $BOAparameter$ objects, each parameter having a unique name, description and default value.
1274
1275
1276\begin{table}[h]
1277\begin{tabular}{m{0.9\textwidth}}
1278\hline
1279\texttt{public Set<BOAparameter> getParameterSpec() }\\
1280 Override this function to add parameters to the module.\\
1281\hline
1282\end{tabular}
1283\caption{The getParameters method. Override if your component has parameters.}
1284\label{tab:parameters}
1285\end{table}
1286
1287
1288When the component is actually used, the actual values for the parameters (which may differ from the default) are passed to the init function when the component is initialized.
1289
1290\subsubsection{Creating an Offering Strategy}
1291An offering strategy can be easily created by extending the \textit{OfferingStrategy} class. Table~\ref{tab:BOAbs} depicts the methods which need to be overridden. The \textit{init} method of the offering strategy is automatically called by the BOA framework with four parameters: the negotiation session, the opponent model, the opponent model strategy, and the parameters of the component. The negotiation session object keeps track of the negotiation state, which includes all offers made by both partiess, the timeline, the preference profile, and the domain. The parameters object specifies the parameters as specified in the GUI. In the previous section we specified the parameter $b$ for the acceptance strategy $Other - Next$ to be 0.0. In this case the party can retrieve the value of the parameter by calling \textit{parameters.get(``b'')}.
1292
1293An approach often taken by many offering strategies is to first generate all possible bids. This can be efficiently done by using the \textit{SortedOutcomeSpace} class. For an example on using this class see the \textit{TimeDependent\_Offering} class in the \textit{bilateralexamples/boacomponents} directory.
1294
1295\begin{table}[h]
1296\begin{tabular}{m{0.9\textwidth}}
1297\hline
1298\texttt{void init(NegotiationSession negotiationSession, OpponentModel opponentModel,
1299 OMStrategy omStrategy, Map<String, Double> parameters)}\\
1300Method directly called after creating the party which should be used to initialize the component.\\
1301\hline
1302\texttt{BidDetails determineOpeningBid()}\\
1303Method which determines the first bid to be offered to the component.\\
1304\hline
1305\texttt{BidDetails determineNextBid()}\\
1306Method which determines the bids offered to the opponent after the first bid.\\
1307\hline
1308\end{tabular}
1309\caption{The main methods of the offering strategy component.}
1310\label{tab:BOAbs}
1311\end{table}
1312
1313
1314\subsubsection{Creating an Acceptance Condition}
1315This section discusses how to create an acceptance strategy class by extending the abstract class \textit{AcceptanceStrategy}. Table~\ref{tab:BOAas} depicts the two methods which need to specified.
1316
1317\begin{table}[h]
1318\begin{tabular}{m{0.9\textwidth}}
1319\hline
1320\texttt{void init(NegotiationSession negotiationSession, OfferingStrategy offeringStrategy,
1321 OpponentModel opponentModel, Map<String, Double> parameters)}\\
1322Method directly called after creating the party which should be used to initialize the component.\\
1323\hline
1324\texttt{Actions determineAcceptability()}\\
1325Method which determines if the party should accept the opponent's bid (\textit{Actions.Accept}), reject it and send a counter offer (\textit{Actions.Reject}), or leave the negotiation (\textit{Actions.Break}).\\
1326\hline
1327\end{tabular}
1328\caption{The main methods of the acceptance strategy component.}
1329\label{tab:BOAas}
1330\end{table}
1331
1332\subsubsection{Creating an Opponent Model}
1333This section discusses how to create an opponent model by extending the abstract class \textit{OpponentModel}. Table~\ref{tab:BOAom} provides an overview of the main methods which need to specified. For performance reasons it is recommended to use the \textit{UtilitySpace} class.
1334
1335\begin{table}[h]
1336\begin{tabular}{m{0.9\textwidth}}
1337\hline
1338\texttt{void init(NegotiationSession negotiationSession, Map<String, Double> parameters)}\\
1339Method directly called after creating the party which should be used to initialize the component.\\
1340\hline
1341\texttt{double getBidEvaluation(Bid bid)}\\
1342Returns the estimated utility of the given bid.\\
1343\hline
1344\texttt{double updateModel(Bid bid)}\\
1345Updates the opponent model using the given bid.\\
1346\hline
1347\texttt{UtilitySpace getOpponentUtilitySpace()}\\
1348Returns the opponent's preference profile. Use the \textit{UtilitySpaceAdapter} class when not using the UtilitySpace class for the opponent's preference profile.\\
1349\hline
1350\end{tabular}
1351\caption{The main methods of the opponent model component.}
1352\label{tab:BOAom}
1353\end{table}
1354
1355\subsubsection{Creating an Opponent Model Strategy}
1356This section discusses how to create an opponent model strategy by extending the abstract class \textit{OMStrategy}. Table~\ref{tab:BOAoms} provides an overview of the main methods which need to specified.
1357
1358\begin{table}[h]
1359\begin{tabular}{m{0.9\textwidth}}
1360\hline
1361\texttt{void init(NegotiationSession negotiationSession, OpponentModel model, Map<String, Double> parameters)}\\
1362Method directly called after creating the party which should be used to initialize the component.\\
1363\hline
1364\texttt{BidDetails getBid(List<BidDetails> bidsInRange);}\\
1365This method returns a bid to be offered from a set of given similarly preferred bids by using the opponent model.\\
1366\hline
1367\texttt{boolean canUpdateOM();}\\
1368Determines if the opponent model may be updated this turn.\\
1369\hline
1370\end{tabular}
1371\caption{The main methods of the opponent model strategy component.}
1372\label{tab:BOAoms}
1373\end{table}
1374
1375
1376
1377% DISABLED: Boa framework sessiondata is not good, it should use PersistentDataStore.
1378
1379%\subsection{SessionData}
1380%The BOA framework stores an object \textit{SessionData} that includes the data saved by all three components. This object is loaded and saved automatically by the BOA framework. A component can easily access the data it saved by using the \textit{loadData} method. A component can at each moment during the negotiation update the saved information by using the \textit{storeData} method, although we recommend updating the information at the end of the negotiation by using the the \textit{endSession} method. The \textit{endSession} method of each method is automatically called at the end of the negotiation to inform the component of the result obtained and should be used to update the \textit{SessionData} object before it is automatically stored.
1381
1382\subsection{Advanced: Converting a BOA Party to a Party}
1383To convert a BOA party to a normal party you have to create a class that extends \textit{BoaParty} and override the \textit{init} method. Below is an example of a BOA party wrapped as a normal party. It's a bit hack-y because the BoaParty constructor assumes all components known while an party often can decide this only at init time.
1384
1385\begin{lstlisting}
1386public class SimpleBoaParty extends BoaParty {
1387
1388 public SimpleBoaParty() {
1389 super(null, new HashMap<String, Double>(), null,
1390 new HashMap<String, Double>(), null,
1391 new HashMap<String, Double>(), null,
1392 new HashMap<String, Double>());
1393 }
1394
1395 @Override
1396 public void init(NegotiationInfo info) {
1397 SessionData sessionData = null;
1398 if (info.getPersistentData()
1399 .getPersistentDataType() == PersistentDataType.SERIALIZABLE) {
1400 sessionData = (SessionData) info.getPersistentData().get();
1401 }
1402 if (sessionData == null) {
1403 sessionData = new SessionData();
1404 }
1405
1406 negotiationSession = new NegotiationSession(sessionData,
1407 info.getUtilitySpace(), info.getTimeline());
1408 opponentModel = new MyrequencyModel();
1409 opponentModel.init(negotiationSession, new HashMap<String, Double>());
1410 omStrategy = new NullStrategy(negotiationSession);
1411 offeringStrategy = new MyBiddingStrategy(negotiationSession,
1412 opponentModel, omStrategy);
1413
1414 acceptConditions = new AC_Next(negotiationSession, offeringStrategy, 1,
1415 0);
1416 // we have init'd all params here, don't call super init
1417 }
1418
1419 @Override
1420 public String getDescription() {
1421 return "Simple BOA Party";
1422 }
1423}
1424\end{lstlisting}
1425
1426\subsection{Advanced: Multi-Acceptance Criteria (MAC)}
1427The \textit{BOA framework} allows us to better explore a large space of negotiation strategies. MAC can be used to scale down the negotiation space, and thereby make it better computationally explorable.
1428
1429As discussed in the introduction of this chapter, the acceptance condition determines solely if a bid should be accepted. This entails that it does not influence the bidding trace, except for when it is stopped. In fact, the only difference between \textit{BOA parties} where only the acceptance condition vary, is the time of agreement (assuming that the computational cost of the acceptance conditions are negligible).
1430
1431Given this property, multiple acceptance criteria can be tested in parallel during the same negotiation trace. In practice, more than 50 variants of a simple acceptance condition as for example $\textbf{AC}_{next}$ can be tested in the same negotiation at a negligible computational cost.
1432
1433To create a multi-acceptance condition component you first need to extend the class \textit{Mulit Acceptance Condition}, this gives access to the ACList which is a list of acceptance conditions to be tested in parallel. Furthermore, the method \textit{isMac} should be overwritten to return \textit{true} and the name of the components in the repository should be \textit{Multi Acceptance Criteria}. An acceptance can be added to the MAC by appending it to the AClist as shown below.
1434
1435\begin{lstlisting}[language=Java, caption={Example code for Acceptance condition}]
1436public class AC_MAC extends Multi_AcceptanceCondition {
1437 @Override
1438 public void init(NegotiationSession negoSession,
1439 OfferingStrategy strat, OpponentModel opponentModel,
1440 HashMap<String, Double> parameters) throws Exception {
1441 this.negotiationSession = negoSession;
1442 this.offeringStrategy = strat;
1443 outcomes = new ArrayList<OutcomeTuple> ();
1444 ACList = new ArrayList<AcceptanceStrategy>();
1445 for (int e = 0; e < 5; e++) {
1446 ACList.add(new AC_Next(negotiationSession,
1447 offeringStrategy, 1, e * 0.01));
1448 }
1449 }
1450}
1451\end{lstlisting}
1452
1453
1454
1455
1456%=========================================================================================
1457
1458\section{Debugging}\label{sec:debugging}
1459This section explains how to debug your party using Eclipse. It is assumed you set up your party already as in Chapter \ref{sec:createagent}.
1460
1461You can place a breakpoint in your party (or any other place in {\Genius}) and run {\Genius} using the standard Eclipse methods (e.g. open a java file with Eclipse and click in the left border to add a breakpoint at that point).
1462
1463To debug your party as it runs in Genius, right click on your project root in the Navigator (or Project explorer, whichever you use) and select Debug As.../Java Application. Then select \verb|Application - genius| and click ok.
1464
1465
1466\subsection{Source code and javadocs}
1467The genius core source codes and javadocs are included in the genius.jar file. But if you like you can browse and download all sources at \url{https://tracinsy.ewi.tudelft.nl/pubtrac/Genius}.
1468
1469\FloatBarrier
1470
1471
1472
1473
1474
1475
1476\section{Conclusion}
1477This concludes the manual of {\Genius}. If you experience problems or have suggestions on how to improve {\Genius}, please send them to \url{negotiation@ii.tudelft.nl}.
1478
1479{\Genius} is actively used in academic research. If you want to use {\Genius} in your paper, please refer to \cite{Genius}.
1480
1481%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1482
1483\newpage
1484\section{Appendix}
1485This appendix describes how to set up Eclipse to create and debug your own party.
1486
1487\label{sec:appendix}
1488
1489\subsection{Connect Genius to Eclipse}
1490\label{sec:appendix-run-genius}
1491We expect that you installed Eclipse (Neon or higher) and Java version 8 on your computer.
1492\begin{enumerate}
1493
1494\item Open the Eclipse Navigator with the menu Window/Show View/Navigator. You can close the Package Explorer.
1495
1496\item Right click in the Navigator area and select New/Java Project. Create a new Java project. We name it \texttt{Group3assignment} but you can use any convenient name. Make sure you select "JavaSE-1.8" or equivalent to ensure your code will be java 8 compatible (Figure \ref{fig:run-genius-1}). Click Finish.
1497
1498\begin{figure}[h!]
1499 \centering
1500 \includegraphics[width=0.5\textwidth]{media/dialogNewJavaProject.png}
1501 \caption{Create a new java project with the proper name and settings.}
1502 \label{fig:run-genius-1}
1503\end{figure}
1504
1505\item Drag the genius.jar file (from your unzipped download) into the project in the Eclipse Navigator area. Select "Copy files" and press OK.
1506
1507\FloatBarrier
1508
1509\item{Connect \texttt{genius} Jar:
1510 \begin{enumerate}
1511 \item Right click on the \texttt{Group3assignment} icon and select "Properties".
1512 \item Select the Java Build Path.
1513 \item Select the Libraries Tab.
1514 \item Select "Add JARs", in the JAR Selection window (Figure \ref{fig:run-genius-3}).
1515 \item Open the \texttt{Group3assignment} folder and scroll down to select \texttt{genius.jar}.
1516 \item click a few times ok to close all dialog boxes.
1517 \end{enumerate}
1518 }
1519
1520\begin{figure}[h!]
1521 \centering
1522 \includegraphics[width=0.6\textwidth]{media/selectjar.png}
1523 \caption{Attach the {\Genius} jar to the project.}
1524 \label{fig:run-genius-3}
1525\end{figure}
1526
1527
1528
1529\item Now you can run G\textsc{enius} as a Java application, by launching it as a \texttt{Application} (Figure \ref{fig:startgenius}). To do this, right click on the project, select \texttt{Run As}, select \texttt{Java Application} and then in the browser select \texttt{Application - genius}.
1530
1531\begin{figure}[h!]
1532 \centering
1533 \includegraphics[width=0.6\textwidth]{media/startup.png}
1534 \caption{Starting {\Genius} in Eclipse.}
1535 \label{fig:startgenius}
1536\end{figure}
1537\end{enumerate}
1538
1539\FloatBarrier
1540
1541\subsection{Insert example party}
1542To compile an example party, just drag an example folder, eg \emph{bilateralexamples}, from your unzipped genius download entirely into the src folder in Eclipse. Select "Copy files and folders" and click ok.
1543
1544You can now work with these agents in {\Genius} by adding them to the repository (see Section~\ref{sec:creating-boa-components}).
1545
1546\subsection{Debugging}
1547Once you have Genius running in Eclipse, you can simply place a breakpoint in your party and run Genius from Eclipse in debug mode.
1548
1549
1550
1551
1552\bibliographystyle{plain}
1553\bibliography{genius}
1554
1555\end{document}
Note: See TracBrowser for help on using the repository browser.