%\documentclass[10pt,fleqn]{article}
%\usepackage{epsfig}
%\title{\textbf{World}}
%\author{Werner Gitschthaler,Philip Preuss}
%\date{March 29,2001}
%\begin{document}
%\maketitle
%\section{World}
\subsection{Introdcution}
This section, \textit{Introduction} should give you an overview
how the \textit{"World"} was created starting from the roots.It is
not only possible but sure that things changed a bit during the
programming process, but though most of our first ideas where
implemented in one or an other way.
\subsubsection{The different ways to create a
new world:}
\begin{enumerate}
   \item creating a new world using one of the given geometric forms
      e.g. circle, sphere, toroid, rectangle, triangle, pyramide..
   \item creating world providing explicit waypoints. this should be possible
    by reading a XML file, where the information must be already
    coded in the right way. e.g. coordinates (x,y), refering waypoints
    ( means all waypoints which can reached within a single "step" of the 
agent )
   \item providing the data by typing in each single waypoint, ist coordinates 
and
    its neighbors ( kind of hard work )
\end{enumerate}
\paragraph
  How to tell an agent if there whether is a way or not?
 There are 2 possibilities to handle the waypoints in a given environment. 
Though we
 want to provide random and user-defined environments it makes no sense to 
define a static grid like
 the programmers of ELC did. They implemented the world in a way that there 
are only 4 directions
 between an agent can choose and each step always costs an predefined amount 
of time. ( this means that
 an agent can't change its own speed and always reaches another waypoint with 
exact one step).
\paragraph
 In our case the user may define a waypoint with 5 or even more different 
neighbors. Therefore the agent must be able to
 choose between more than 4 different directions.
 One possible solution of this \texttt{"many different directions problem"} 
could be that the agent can choose between
 360 different directions ( complete circle). If there are 6 different 
neighbors and the agent wants to go lets
 say to the left its sensors should provide him with the nearest given 
neighbor in an angle between 70 to 290 degree.
 Then the agent chooses the direction which fits best and moves to the 
neighbor. If there are many different
 directions between the agent can choose, it should select randomly.
\paragraph
 Another problem is the \texttt{"different distance problem"}. Within an 
static grid each line has exactly the same length. In our
 case its nearly impossible that all lines ( ways) have the same lenght if the 
user provides the different waypoints. But
 on the predefined geometric forms a static grid could be used with easy. 
Though we can not use this static grid on a user
 defined environment, as we explained above it seems to be the better way to 
not use a static grid at all and handle the
 predefined forms and figures as user defined ones. But dynamic ways in a 
dynamic graph implies dynamic euklidic length
 of the edges. Should this dynamic length be ignored or should it be used to 
provide more accurate and even additional data?
 Not using this information makes it much easier to navigate in the world and 
makes sure that an agents always
 reaches all neighbor verticles. As we mentioned above a refering waypoint is 
a waypoint which can be reached within
 one step. In this case all waypoints with a edge between each other would be 
refering ones.
 An other possibility to handle different  euklidic length of the edges would 
be the native way. With native way we mean to
 handle shorter ( shorter means euklididc length ) edges as rising ones and 
create a world with "hills" and "valleys".
 In this scenario the agent can increase and decrease his speed ( not the 
agent himself but the environment, rising edge means
 slower ). The advantage of this  is that the agent will always reach all 
waypoint with a single step, like he does
 in the static grid.

\subsubsection{Information}
\textbf{Information we provide and information we need}
Which information do we need and when do we need this information? The only 
information we need is user dependent. Therefore
our information is meanly provided by the gui programmers and by the gui 
itself ( why meanly and not completly? as
far as i know there should also be a protected mode, without gui ). But which 
information do we need explicitly?

\textbf{We need to know:}
 \begin{enumerate}
  \item Information from the gui:
      \begin{enumerate}
    \item whether the user wants to define his own world or if he wants to use 
one of the predefined worlds..
    \item if the user wants to define his own world, we need to know how much 
waypoints, there coordinates and the neighbors
    ( edges and verticles if we think of the world as a graph )
    \item i don't know if this is from interest but I want to mention it at 
least one time, but how large should this world be?
    A rectangle e.g. could have 4 waypoints and eg 4 edges or ways.  But it 
also may have dozens and hundrets of verticles and
    a very very large amount of ways.
      \end{enumerate}
  \item Information form the Agents:
     \begin{enumerate}
       \item Where are you? The x,y coordinates from each agent.
       \item Where did you go to? the new x,y coordinates if the agent moved.
       \item Did you produce children? This information should be sent by the 
agent, after a reproduction. Though we don't know
        how the agents reproduce each other or even if they do this in a 
"sexual" way we can not know which information we need
    from whom. But we know for sure that we must be "contacted" if there 
appear new agents or if there die older ones.
     end{enumerate}
      \end{enumerate}
 \end{enumerate}
\textbf{We provide:}
 \begin{enumerate}
  \item Information for the gui (and for the user for sure, but the user isn't 
form great interest for us)
        This information consists of :\\
         \begin{enumerate}
        \item if a file was loaded, where we able to create a world with the 
provided data?
        \item was the creation of a world a success? (yes,no,report) report: 
verticles,edges,size.
           or report: problem (e.g. not valid file )
        \item within which predefined worlds a user can select?
     \end{enumerate}
  \item Information for the Sensors and Agents. This information consists of:\\
         \begin{enumerate}
        \item Where can i go to? information for the agents respective for its 
sensor where the next "targets"
              are. The random selection should be done by the agent.
        \item Where are the other ones? Each agent should be tracked by the 
world.
          \item Statistics:\\
                  maybe we will provide the statistics with information how 
often one edge has been passed and which verticles have been
                  visited more or less often. I do not know if this 
information is 1: relevant 2: whished 3:provided by us
          \end{enumerate}
 \end{enumerate}
\subsubsection{Concrete Solutions} This section is much more
technical an describes not only the classes we used but some
methods too. But first I want to start with a brief description
how the problems mentioned above have been solved and how the
world works.
\subsubsection{Information}
 I think the managers already wrote a lot about this theme. I
 just want to remind that we use CNVLists ( PNVLists , whatever)
 to communicate and ,much more important, ALL information we need
 is provided by the manager. The world is created by the managers
 ( the manager creates a CWOD\_WOD object with the parameters the
 constructor of this class needs) and then we just need to know
 where each agent wants to go to... after getting this list we are
 just sending back a List with boolean values, whether an collision
 occured  or not. Our second job is to sending a CNV\_list with the
 information how often a point has been visited if the method
 get\_statistics is called. And thats it. Lets have a look at the
 classes, and some important methods.
 The World is a plain graph. This graph is represented by an Array of 
Waypoint. The Waypoint Class
 itself will be discussed later on, but nothing really important changed since 
the first mention
  of this pure data-type class. We will NOT provide the random created world, 
since it is nearly
  impossible to create a random and p l a i n graph. The userdefined worlds 
will both ( both :
  line by line input an file ) be opened as a XML file in special format, only 
the path to the
  XML file must be provided. We didn't add any predefined worlds except the 
square world, because we
  have to solve the communication problem first, before we will start to 
provide more than one predefined
  world.
  \paragraph
  How does it work?
  All information of one world is held in an Array of Waypoints. With 
information either the name of the
  waypoint or the name of the agent we can retrieve any information from this 
array, like neighbors,
  angles, free and so on. The information will then be transfered into CNV 
lists, for easier communication
  and one big standard. Nevertheless we can also provide any kind of 
Information as a XML file too, and can
  create XML files with the current state of the world at any time.The angles 
and distances will be calculated with the different
  given X and Y coordinates. For example the Waypoint wp1 and wp2. To get the 
distance between
  these waypoints we just have to a subtract the xcoods and the ycood and then 
calculate with
  Pythagoras after this we get the angles easily with 3 known side-lengthes 
and one angle ( 90
  degrees).
\subsection{Interfaces \& Parameters}
  Our Interfaces concern the \textit{Agents} and the
  \textit{Statistics} surely \textit{any} communication
  is handled by the manager group.
  \subsubsection{constructor}
  The most important is the
  creation of a new world, with the parameters:\\
  \begin{enumerate}
    \item User defined, boolean 1 means user defined 0 means
    predefined
    \item which, if predefined == 1, here you can select the
    predefined world with the right integer value. If predefined
    this parameter will not be used at all
    \item parameters, if \textit{predefined} the parameters for
    the predefined world, else not used.
    \item filename, if \textit{user defined} the filename goes
    here.
  \end{enumerate}
  \subsubsection{start values}
   gives back the initial values of the agents, where are the
   agents?
  \subsubsection{move}
   takes an cnv list argument, telling the world, where each
   agents \textit{wants} to move to, gives back a boolean CNV
   list, which agent moved or not moved
  \subsubsection{get statistics}
   gives back an cnv list with the waypoints and how often a
   waypoint has been visited, and a cnvlist which agent moved
   during the last moving period.
\subsection{Class Diagram}
\begin{figure}[hb]
\centerline{\epsfxsize=17cm
\epsfbox{\World/Pics/classdiag.eps}}
\end{figure}
\subsection{Classes}
 \begin{enumerate}
  \item CWOD\_Waypoint:  is a pure data type. It will be used for internal 
representation of the whole world, as an array of waypoint.
  It consists of the Integer Variables: xccod,ycood,free ( either the agents 
id or 0 ( stands for no agent , means : free )) and name
  ( The name or id number of the waypoint, the id numbers start with 0 and 
they are continuous numbered )
   The integer array neighs takes the id numbers of the neighbored waypoints
  \item CWOD\_Predefined: is an \textit{Interface}. All predefined worlds, 
will be subclasses of this interface class. The methods in this
  interface  must be implemented in each Subclass. This guarantees that all 
important methods are available for all subclasses
  and the user needs not to think about the specific type, and if a method can 
be called for one predefined type of world e.g. a square
  it will be available for any other predefined world too.
  \item CWOD\_Userdefined: is for both user defined worlds and predefined 
xml-files. The XML file must be in a special format. If the user wants to 
create
  a world by typing in all waypoints, neighbors and so on a file with the same 
format must be created by the gui.
  There is no back-checking if the graph the user defined in his file is 
whether valid or not.
  \item CWOD\_World: this is the main class. Objects of this class
  will be created by the managers, therefore it is \textbf{public}
  This class also holds all the important methods for moving
  agents, more about those methods later on.
  \item CWOD\_Showgraph
 \end{enumerate}
\subsubsection{Subclasses}
  \begin{enumerate}
   \item Square: is a nxn Square. The argument is takes is a integer number 
which stands for the length or the height. e.g a Square with argument 5
   initialized will be a world with 5*5 waypoints and 5*(4+4) edges.
   \item more will follow...
  \end{enumerate}
\subsubsection{Methods}
  I think only the methods of the CWOD\_World.class are really
  important, although all methods for each class are listed.
  But just the really important methods are explained.
  \begin{itemize}
   \item Methods for CWOD\_Waypoint:
      none, only data type. Maybe from interest a waypoint looks like this:\\
       \begin{verbatim}
   class CWOD_Waypoint {
      int name;
      int xcood;
      int ycood;
      int free;
      int[] neighs;
      CWOD_Waypoint(int n){
         name  = 0;
         xcood = 0;
         ycood = 0;
         free  = -1;
         neighs = new int[n];
      \end{verbatim}
   \item Methods for CWOD\_Predefined:
     is an interface
     \begin{verbatim}
      interface CWOD_Predefined {
        int getcoodx(int x, int n);
        int getcoody(int y, int n);
        int getid(int x,int y, int n);
        boolean initagents(CWOD_Waypoint[] arr,int n);
        CWOD_Waypoint[] initneigh(CWOD_Waypoint[] arr);
        CWOD_Waypoint[] mk(int n);
     \end{verbatim}
    \item Methods for CWOD\_Userdefined:
      \begin{verbatim}
       public static CWOD_Waypoint[] create(String filename)
      \end{verbatim}
    \item Methods for CWOD\_World:
     \begin{verbatim}
      int number_agents(CWOD_Waypoint[] wparr)
      double getMaxDis(CWOD_Waypoint[] world)
      int[] agents(CWOD_Waypoint[] wparr)
      double getanglewp(CWOD_Waypoint wp,CWOD_Waypoint wp2)
      double getdiswp(CWOD_Waypoint wp,CWOD_Waypoint wp2)
      int[] get1neigh(CWOD_Waypoint wp)
      boolean isneigh(CWOD_Waypoint wp1,CWOD_Waypoint wp2)
      public CNVList getLocalWorld(CWOD_Waypoint[] world)
      public CNVList move(CNVList moves)
      public CWOD_Waypoint[] CWOD\_World(CNVList info)
      public CNVList getStatistics(CWOD_Waypoint[] world);
     \end{verbatim}
    \end{itemize}
As I promised above, we will have a closer look at the
\textbf{public}methods of the CWOD\_World.class. The most
important method isn't a method, but a constructor. It takes
arguments to determine whether a user-defined or a predefined
world will be created. After this it needs arguments for the
construction method, either a filename or information about the
size of e.g. a square. After this the world will be created, using
several different initialization methods for the world.\\
The getLocalWorld method returns a CNVList just in the format the
agent group wanted to have this CNVList. It returns for each agent
a complete local world, means all points which are in the sensor
range of the agent. The calculating of this sensor range is based
a the distance between two  random waypoints multiplied with 1,5.
( At least at the moment) I think it would make sense if the user
can adjust this sensor range, himself. This is a cutting of an
email from the agents group and we implemented this method in a
way to create just this list:
\begin{verbatim}
 aid[m]pid[n]distance = CNVPair.DOUBLE
 (distance to point with local id n for agent m)
 aid[m]pid[n]angle = CNVPair.DOUBLE
 (angle)
 aid[m]pid[n]agent = CNVPair.INT
 (agent_id of the agent which is at the point with local id n
 ( for agent m))
 aid[m]pid[n]point = CNVPair.INT
 (point_id  of the  point with the local id n for agent m )
 aid[m]pid[n]neighbour = CNVPair.INT ( 0 if neighbour 0 if not )
 pid = point_id (local)
 aid = agent_id
\end{verbatim}
The move method takes a CNVList Argument. In this CNV\_list all
the moves the agents want to do are listed. The method tries to
move the agents , ordered by id, if one agent wants to move to a
point another agent already moved to this agent will not moved at
all, and if an agent wanted to move to his position ( because he
\textit{"thought"} that this waypoint will be free soon, this
agent will not move too, and so on.. ( worst case : only one agent
will move... )
\subsection{Visualization}
  A java bean is in work which will draw the Graph ( starting at point 0 , 
drawing lines to all neighbors
  then go to point 1 drawing lines to all neighbors > than 1  and so on ). The 
visualization of the
  Agents will be done by the Agent-Group as far as I know.
%\end{document}

