%*********************************************
%*********************************************
\chapter{Software Design}
%*********************************************
%*********************************************

{\em Literature:}

\begin{itemize}

    \item   General software analysis and design: \cite[pages 741-822]{Strou98}

    \item   UML: \cite{Burk99}

    \item   Software pattern (Design pattern):  \cite{GAMMA_eng}, \cite{GAMMA_ger}, \cite{busch98}

\end{itemize}


%************************************
\section{General design aims}
%************************************

When designing our software to meet the requirements as described
in the section for system architecture (Section
\ref{Sect:SysArch}), we had to take care of several boundary
conditions:
\begin{itemize}

    \item Flexible implementation of agent movement control
    \item Use a NN-library but in a replaceable way
    \item Easy change of world representation
    \item Concentrate the agent creation process in a central
    module
    \item Information interchange between different system
    components should be based on calls and callbacks (avoid
    polling over process boundaries)
    \item Multi threaded agent training
    \item User interface should be separated from the agent controller
    \item Agent state extracted from implementation to reduce
    network traffic

\end{itemize}


\subsection{Naming conventions}
%************************************

As in every project where more than one developer is working on,
SatMAS needs naming conventions, too. We designed our style guide
to be not too strength (because most programmers don't like to be
told how to do their work). Although naming should be done by
general good software engineering practices, the most common
naming conventions are given here.

\subsubsection*{Interface Names}
In the SatMAS design all interface classes have the prefix {\em
I}. Example: {\em IWorld}.

\subsection*{Property methods}
In addition to the classes provided by the JDK all property
methods have set-, get-, is-, or update prefix followed by the
name of the controlled property. (e.\,g. getName or setParent).

\subsection*{Variables}
Our variable naming convention is nearly the same as the famous
{\em hungarian notation} in the Windows programming world. There,
all variables have a lower prefix with their corresponding type,
which can be one of the following:
\begin{description}
    \item[integer:]     Prefix: {\em n} (e.\,g. nIndex)
    \item[float:]       Prefix: {\em f} (e.\,g. fAverage)
    \item[String:]      Prefix: {\em str} (e.\,g. strFilePath)
    \item[boolean:]     Prefix: {\em b} (e.\,g. bResult)
\end{description}

\noindent If the type is none of these, you should give the
variable a really speaking name. For member variable it is
mandatory to put the prefix m\_ to it (e.\,g. m\_nArrayCounter).

\noindent {\em NOTE:} This naming conventions are not mandatory
for loop variables.


%************************************
\section{Component Diagramms}
%************************************

Components of the system and their responsibilities are shown
here:

%***** Include a picture *****
\begin{figure}[htp!]
    \begin{center}
        \footnotesize
        \ifpdf
            \includegraphics[width=0.9\columnwidth]{jpeg/CP_Main.jpg}  %Filename.jpg
        \else
            \includegraphics[width=0.9\columnwidth]{eps/CP_Main.eps}  %Filename.eps
        \fi
        \caption{Component diagram: System Components}
        \label{fig:SysComp}
    \end{center}
\end{figure}


\subsection{Management Client}
%************************************
The Management Client is the user interface of SatMAS.

\subsubsection{Responsibility}

\begin{itemize}

    \item Visualization
    \item Configuration

\end{itemize}

\subsubsection{Collaborators}
\begin{itemize}

    \item Controlling Master

\end{itemize}


\subsection{Controlling Master}
%************************************
The Controlling Master is SatMAS's central intelligence component.
Cooperation between Controlling Master and Working Slave is
implemented as Master-Slave design pattern as described in
\cite[pages 245-291]{busch98}.

\subsubsection{Responsibility}

\begin{itemize}

    \item Agent controller
    \item Disposition of agents
    \item Query results
    \item Creation of agents
    \item Input/Output of pattern/net files
    \item Notify client

\end{itemize}

\subsubsection{Collaborators}
\begin{itemize}

    \item Management Client
    \item Working Slave

\end{itemize}


\subsection{Working Slave}
%************************************
All time consuming operations of SatMAS are processed on a Working
Slave.

\subsubsection{Responsibility}

\begin{itemize}

    \item Provide infrastructure for agent training
    \item Notify master after training of an agent has finished

\end{itemize}

\subsubsection{Collaborators}
\begin{itemize}

    \item Controlling Master

\end{itemize}


%************************************
\section{Class diagrams}
%************************************


\subsection{Agent model}
%************************************
In order to give the Controlling Master the ability to build
agents with different behaviors, the agents are modeled as seen in
figure \ref{fig:AgentModel}.

%***** Include a picture *****
\begin{figure}[htp!]
    \begin{center}
        \footnotesize
        \ifpdf
            \includegraphics[width=1.0\columnwidth]{jpeg/CD_AgentModel.jpg}  %Filename.jpg
        \else
            \includegraphics[width=1.0\columnwidth]{eps/CD_AgentModel.eps}  %Filename.eps
        \fi
        \caption{Class diagram: Agent Model}
        \label{fig:AgentModel}
    \end{center}
\end{figure}

\subsubsection{Special design decisions:}
\begin{description}

    \item[IMovementController]     This interface enables flexible replacement of movement behavior of an
    agent

    \item[IAgentState]             Agent state extracted from implementation to reduce network

\end{description}


\subsection{Management Client}
%************************************
A smart and simple console interface is sufficient for this design
stage (diagram \ref{fig:ManagerModel}).


%***** Include a picture *****
\begin{figure}[htp!]
    \begin{center}
        \footnotesize
        \ifpdf
            \includegraphics[width=0.6\columnwidth]{jpeg/CD_ManagerModel.jpg}  %Filename.jpg
        \else
            \includegraphics[width=0.6\columnwidth]{eps/CD_ManagerModel.eps}  %Filename.eps
        \fi
        \caption{Class diagram: Manager Model}
        \label{fig:ManagerModel}
    \end{center}
\end{figure}


\subsection{Controlling Master}
%************************************
Class modeling of the central intelligence component is in figure
\ref{fig:MasterModel}.


%***** Include a picture *****
\begin{figure}[htp!]
    \begin{center}
        \footnotesize
        \ifpdf
            \includegraphics[width=1.0\columnwidth]{jpeg/CD_ControllingMaster.jpg}  %Filename.jpg
        \else
            \includegraphics[width=1.0\columnwidth]{eps/CD_ControllingMaster.eps}  %Filename.eps
        \fi
        \caption{Class diagram: Master Model}
        \label{fig:MasterModel}
    \end{center}
\end{figure}

\subsubsection{Special design decision:}

\begin{description}

    \item[IAgentFactory]    Separate modeling of an agent creation
    interface leads into a looser coupling between the agent
    controller and the working slave. Additionally variation of
    agent components is facilitated.

\end{description}


\subsection{Working Slave}
%************************************

Figure \ref{fig:SlaveModel} is a working slave's class diagram.


%***** Include a picture *****
\begin{figure}[htp!]
    \begin{center}
        \footnotesize
        \ifpdf
            \includegraphics[width=1.0\columnwidth]{jpeg/CD_WorkingSlave.jpg}  %Filename.jpg
        \else
            \includegraphics[width=1.0\columnwidth]{eps/CD_WorkingSlave.eps}  %Filename.eps
        \fi
        \caption{Class diagram: Slave Model}
        \label{fig:SlaveModel}
    \end{center}
\end{figure}

\subsubsection{Special design decisions:}

\begin{description}

    \item[IANNFacade]   To minimize dependency on a distinct
    ANN-package, an abstraction level is introduced. Realized with
    the Facade design pattern from \cite[pages 189-198]{GAMMA_ger}.

    \item[JFroehlichANNFacade]  Due to lack of free available
    ANN-package J\"org Fr\"ohlich wrote his own implementation,
    which fitted best for SatMAS at first glance.

\end{description}


\subsection{World modeling}
%************************************
As discussed in section \ref{Sect:SysArch}, best selection of a
concrete world model needs to be researched. Therefore an abstract
model for worlds and their data is needed, as seen in diagram
\ref{fig:WorldModel}.

%***** Include a picture *****
\begin{figure}[htp!]
    \begin{center}
        \footnotesize
        \ifpdf
            \includegraphics[width=0.7\columnwidth]{jpeg/CD_WorldModel.jpg}  %Filename.jpg
        \else
            \includegraphics[width=0.7\columnwidth]{eps/CD_WorldModel.eps}  %Filename.eps
        \fi
        \caption{Class diagram: World Model}
        \label{fig:WorldModel}
    \end{center}
\end{figure}

\subsubsection{Special design decisions:}

\begin{description}

    \item[IWorld]       Abstract description of a real world model. After creation a world model is
    immutable.
    \item[IWorldPoint]  Represents a concrete position on a world
    model, including data access methods.
    \item[IWorldRect]   A rectangular region on a world model.
    \item[IWorldCursor] Mobile position marker on a world model.

\end{description}

\subsubsection{Concrete implementation of a world}

This implementation example of a discrete world models a plane 2D
area, on which each raster point is reachable.

%***** Include a picture *****
\begin{figure}[htp!]
    \begin{center}
        \footnotesize
        \ifpdf
            \includegraphics[width=1.0\columnwidth]{jpeg/CD_ConcreteWorld.jpg}  %Filename.jpg
        \else
            \includegraphics[width=1.0\columnwidth]{eps/CD_ConcreteWorld.eps}  %Filename.eps
        \fi
        \caption{Class diagram: Concrete implementation of a world}
        \label{fig:ConcWorld}
    \end{center}
\end{figure}



%************************************
\section{Sequence diagrams}
%************************************

\subsection{Agent training and result evaluation - overview}

Diagram \ref{fig:ATE_O} gives a rough overview how agents are
trained, and after finishing their learning phase the whole result
is queried.

\begin{figure}[htp!]
    \begin{center}
        \footnotesize
        \ifpdf
            \includegraphics[width=1.0\columnwidth]{jpeg/SD_AgentTrainNEval.jpg}  %Filename.jpg
        \else
            \includegraphics[width=1.0\columnwidth]{eps/SD_AgentTrainNEval.eps}  %Filename.eps
        \fi
        \caption{Sequence diagram: Agent training and result evaluation - overview}
        \label{fig:ATE_O}
    \end{center}
\end{figure}
