diff --git a/doc/report/fsm.tex b/doc/report/fsm.tex
index e4918335c3caa361bdb65b9c5ac7a6e5e5964313..0ad148890b82dcaf3902f60c10d47312e1b2b618 100644
--- a/doc/report/fsm.tex
+++ b/doc/report/fsm.tex
@@ -1,14 +1,17 @@
\section{FSM modeling}
-\subsection{Agent behaviour}
-According to the multi-agent approach, values of variables are discussed among agents who come to local agreements and iteratively repeat the process to finally yield a satisfying global result.
+\subsection{Outline}
+According to the multi-agent approach, values of variables are discussed among agents who come to local agreements and iteratively repeat the process to finally yield a satisfying global assignment.
Agents systematically base their decision on their local knowledge.
-The process is triggered by a supervisor agent who invites other agents to begin their rounds of interactions.
+The process is triggered by a supervisor agent which invites other agents to begin their rounds of interactions.
Each agent $a_i$ is sent a \beginAlgo{} message by the supervisor and initiates its variable's value at random in the variable's domain.
The behaviour of each agent is defined by a finite state automata (see Figure~\ref{full_agent} for the big picture and Figures~\ref{beginning}, \ref{offerer}, \ref{receiver}, \ref{committed} and \ref{uncommitted} for focused extracts ).
-\subsection{ Agent States}
+Communication of potential moves and their corresponding potential gains helps agents determine who should act. A single move is an action wherevy an agent changes the current value of its variable to another possible value belonging to the variable's domain.
+A coordinated move is similar but involves two agents changing the values of their variables. Note that a move can also be static if the change to \texti{another} value of the domain happens to be the current value of the variable.
+
+\subsection{Agent States}
\subsubsection{General overview}
\begin{itemize}
@@ -17,16 +20,16 @@ The behaviour of each agent is defined by a finite state automata (see Figure~\r
\item \waitingForRole{}: agent awaits for the role assignment which will tell it whether it will be an Offerer or a Receiver for this round.
\item The Offerer's side:
\begin{itemize}
- \item \offWaitingValues{}: the Offerer agent collects all of its neighbours values before it can choose a neighbour at random and compute a joint offer for it.
- \item \offMakingOff{}: the Offerer selects one neighbour and computes an offer with that neighbour's value which is then sent, no matter the positive or negative response only a single offer will be made.
+ \item \offWaitingValues{}: the offerer agent collects all of its neighbours values before it can choose a neighbour at random and select a joint offer for it.
+ \item \offMakingOff{}: the Offerer selects one neighbour and selects an offer with that neighbour's value which is then sent. No matter the response given by the selected partner, only one offer can be made, hence if rejected the offerer will move on to act on its own.
\end{itemize}
\item The Receiver's side:
\begin{itemize}
- \item \recWaitingOffers{}: the Receiver agent gathers all offers he receives
+ \item \recWaitingOffers{}: the receiver agent gathers all offers he receives
\item \recHavingRecAllOff{}: the Receiver has received all offers from its neighbourhood and now chooses the best offer among those.
\end{itemize}
- \item \uncommitted{}: Receivers who have not received any acceptable offer (or no offer at all) and Offerer's whose offer has been rejected join back in this state and wait for their neighbours deltas while computing their own deltas and informing their neighbourhood.
- \item \committed{}: Offerers which offers have been accepted and Receiver which have received at least one acceptable offer become committed with their respective partners.
+ \item \uncommitted{}: receivers who have not received any acceptable offer (or no offer at all) and Offerer's whose offer has been rejected join back in this state and wait for their neighbours deltas while computing their own deltas and informing their neighbourhood.
+ \item \committed{}: offerers which offers have been accepted and Receiver which have received at least one acceptable offer become committed with their respective partners.
\item \actSolo{}: uncommited agents evaluate their neighbourhood and decide whether they should act or not depending on the neighbourhood's winner.
\item \givingPartnerGNG{}: committed agents evaluate their neighbourhood and decide whether they should act or not depending on the neighbourhood's winner.
\item \handlingGNG{}: committed agents which can act check whether their partner can act too.
@@ -69,7 +72,7 @@ This artificial trigger of \continueAlgo{} is used only once, at the begining of
\subsubsection{\continue{}}
-This state can be reached either via \init or via \givingPartnerGNG{} or \linebreak \handlingGNG{}, it should be considered as the central state from which is sparked each round.
+This state can be reached either via \init, \givingPartnerGNG{} or \handlingGNG{}, it should be considered as the central state from which is sparked each round.
Messages received in this state: \begin{itemize}
\item \informVal{someVal}: neighbour's \informVal{someVal} are stashed to be dealt with when leaving \waitingForRole{}.
\item \giveGo{}: If the agent has reached this state after completing a round where it had been committed but could not act because it did not win the neighbourhood's delta competition, it will receive its partners' \giveGo{} or \giveNoGo{} here, but nothing should be done about it.
@@ -121,7 +124,7 @@ Messages received in this state: \begin{itemize}
\end{figure}
\subsubsection{\recWaitingValues{}}
-In this state the Receiver agent waits until it has been informed of all its neighbours' values.
+In this state the receiver agent waits until it has been informed of all its neighbours' values.
Messages received in this state: \begin{itemize}
\item \informVal{someVal}: are stored in the \neighbourValues{} map and become relevant only if the receiver does not get any acceptable offer.
Once all of them have been received, the agent transitions to \recWaitingOffers{}.
@@ -212,31 +215,33 @@ Messages received in this state: \begin{itemize}
This state is reached coming from \continue{} in the case where the Supervisor sent \stopAlgo{}.
No messages are sent nor received here, it merely represents the end of the algorithm.
-
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Agent's Mind}
The agent's mental state can be considered as the variables which hold the agent's perception of its surroundings and of its inner state.
-In our case, each agent possesses several \textit{personal} variables and several other \textit{interpersonal} variables.
+In our case, each agent possesses several \textit{personal} beliefs and several other \textit{interpersonal}.
-\subsubsection{Personal variables}
+\subsubsection{Personal beliefs}
\begin{itemize}
- \item \neighbourValues{} : the current assingments of values to variables in the vicinity including its own variable.
- \item \commitment{}: a binary flag indicating whether an agent is committed or not, makes the variable \partner{} relevant.
- \item \partner{}: the neighbouring agent with which the agent is committed, only relevant when committed is set to true.
- \item \receivedOffers{}: all offers receives by the agent during this turn, potentially empty ones.
- \item \nbReceivedOffers{}: the counter for all offers received in the current turn.
- \item \neighbourDeltas{}: a map containing the agent's and all its neighbours' current deltas.
- \item \currentBestOffer{} : the potential best offer the agent has as of now, might be empty.
+ \item \neighbourValues{} : is the current beliefs about variables in the vicinity including its own variable.
+ \item \commitment{}: is a boolean indicating whether an agent is committed or not, makes the variable \partner{} relevant.
+ \item \partner{}: is the neighbouring agent with which the agent is committed, only relevant when committed is set to true.
+ \item \receivedOffers{}: are the offers receives by the agent during this turn, potentially empty ones.
+ \item \nbReceivedOffers{}: is the number of all offers received in the current turn.
+ \item \neighbourDeltas{}: is a map containing the agent's and all its neighbours' current deltas.
+ \item \currentBestOffer{} : is the potential best offer the agent has, eventually none.
\end{itemize}
\subsection{Messages}
In order to carry out negotiations, exchange information and coordiante themselves, agents can opt for a variety of messages.
-Each message can only be handled in dedicated states and will therefore be stashed for later use when received in a non-dedicated state.
+Each message can only be handled in dedicated states and will therefore be stashed to be processed later on.
\subsubsection{Standard agent messages}
\begin{itemize}
- \item \kickStart{}: is sent by the agent at the very begining of the process to indicate to the Supervisor that it needs to send it the initial \continueAlgo{} message.
+ \item \kickStart{}: is sent by the agent at the very begining of the first round of the process to indicate to the Supervisor that it needs to send it the initial \continueAlgo{} message.
\item \chooseSubset{Offerer/Receiver}: is sent by the agent to itself, sent in the \waitingForRole{} state and then causing the transition towards either \offWaitingValues{} or \recWaitingOffers{}. This message determines the path the agent threads for the next two states before joigning again in the \uncommitted{}/\uncommitted{} states.
- \item \informVal{someVal}: is sent by an agent to all neighbouring agents in state \waitingForRole{}.
+ \item \informVal{someVal}: is sent by an agent to all neighbouring agents in order to inform them about the current value of the variable controlled by the sender agent.
\item \informDelta{\neighbourDeltas.get(self.variable)}: is sent by an agent which has computed its solo or joint delta to its neighbourhood upon transitioning to either \uncommitted{} or \uncommitted{} states.
\item \makeOff{someOffer/None}: is sent by an offerer.
An offer contains all coordinated moves between the offerer and the designated receiver with their respective delta from the offerer's perspective.
@@ -244,7 +249,7 @@ Each message can only be handled in dedicated states and will therefore be stash
\item \reject{}: is sent by a receiver to all the non-chosen offerers.
It can also be sent by an offerer if it has been made an offer, in this case no computation is needed since the offer is declined straight away.
\item \accept{someCoordinatedMove}: is sent by a receiver to the best offerer upon having computed the best offer from all the received ones.
- It contains a couple consisting of the desired coordinated move and the delat achieved by it.
+ It contains a couple consisting of the desired coordinated move and the delta achieved by it.
\item \bestOfferFM{someOffer}: is sent by the receiver agent to itself after having received all offers from its neighbourhood.
This message contains the offer which must be selected.
\item \shouldAct{}: is sent by an agent, either offerer or receiver, it is sent when transitioning either from \uncommitted{} or \uncommitted{} to \givingPartnerGNG{}.
@@ -257,7 +262,7 @@ Each message can only be handled in dedicated states and will therefore be stash
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{Supervisor behaviour}
+\subsection{Outline}
The supervisor has a simple behaviour based on mainly two states.
In one of them, it awaits for all the agent's values.
Once all values have been collected, it switches to the second state, evaluating whether the full process had ended or not.