Chapter 2. ODIN

2.1. What changes need to be made to ODIN?

	Note
At the time of this writing (2006-04-28), the latest version of ODIN available is 0.2. If at the time you're reading this, there is a newer version of ODIN available (e.g. 0.3 or 1.0), you may not have to patch the ODIN source in any way. We anticipate that the changes we've made to the ODIN source will be incorporated back into the ODIN framework itself. If that's the case, compile using the documentation with the ODIN download, and then skip to the "Running ODIN Sample Applications" section below.

Note

At the time of this writing (2006-04-28), the latest version of ODIN available is 0.2. If at the time you're reading this, there is a newer version of ODIN available (e.g. 0.3 or 1.0), you may not have to patch the ODIN source in any way. We anticipate that the changes we've made to the ODIN source will be incorporated back into the ODIN framework itself. If that's the case, compile using the documentation with the ODIN download, and then skip to the "Running ODIN Sample Applications" section below.

The main distribution of ODIN does not output network events in a formatted way so as to be read by the preprocessor and network viewer. There are two changes necessary to the main distribution of ODIN version 0.1:

The class Message has a new virtual function, getVisString(), which by default returns null. In subclasses PeerQueryMessage and PeerQueryResultMessage, this function returns the search term and the number of search results, respectively.
A formatted line with the prefix "VIS" is sent to standard output on the occurrence of each of these network events:
- Node activation ("activate")
- Open connection between two nodes ("connect")
- Message sent over a connection between two nodes ("sendmessage").
  (The return value of getVisString() is printed with this line if it is not null.)
- Close connection between two nodes ("disconnect")
- Node deactivation ("deactivate")

While many software projects distribute a patch file created with diff -u, we are instead providing the changed files themselves. The changed files (relative to the odin-0.1/src directory):

peer/CommunicationManager.cc
peer/CommunicationManager.h
peer/Logger.h
peer/Message.cc
peer/Message.h
peer/Runtime.cc
rwalksim/main.cc (only change is to usage, noting that log level 4 is now the most verbose)
rwalksim/PeerMessages.cc
rwalksim/PeerMessages.h
rwalkpeer/main.cc (only change is to usage, noting that log level 4 is now the most verbose)

2.2. Integrating & Compiling

	Warning
Please note: If there is no ODIN version available with visualization support built-in at the time you're reading this, you must download and patch ODIN version 0.1. That is the version of ODIN these changes were made against. Patching newer versions of ODIN is unlikely to work. While our changes to ODIN introduce no extra system requirements, ODIN version 0.1 itself can not be compiled with newer versions of g++. g++ version 3.2.3 is known to work (i.e. to compile ODIN with only warnings) and can be found on the lokis (loki1 through loki12.cc.gatech.edu). g++ version 3.4.4 is known not to work (i.e. to return errors on an attempt to compile ODIN).

Warning

Please note:

If there is no ODIN version available with visualization support built-in at the time you're reading this, you must download and patch ODIN version 0.1. That is the version of ODIN these changes were made against. Patching newer versions of ODIN is unlikely to work.
While our changes to ODIN introduce no extra system requirements, ODIN version 0.1 itself can not be compiled with newer versions of g++. g++ version 3.2.3 is known to work (i.e. to compile ODIN with only warnings) and can be found on the lokis (loki1 through loki12.cc.gatech.edu). g++ version 3.4.4 is known not to work (i.e. to return errors on an attempt to compile ODIN).

Here are the main steps to integrating our changes and compiling an ODIN suitable for use with the preprocessor and network viewer:

Download ODIN version 0.1 from http://www.cc.gatech.edu/~cooperb/odin/download/.
Ungzip and untar the download.
Copy the files in the odin/newerfiles directory (provided by us) over the files in the odin-0.1/src directory (from the tarball).
For example: cp -rv ../newerfiles/* odin-0.1/src/
Now compile ODIN as you would normally (e.g. make clean && make && make randomwalksim && make randomwalkpeer && make client).

These steps are performed automatically when you run the dl_and_unzip_stuff.sh and patch_build_odin.sh shells scripts from the "odin" directory. ODIN will be patched and compiled within the created "build" directory.

2.3. Running ODIN Sample Applications

Running ODIN is no different that before, however in order to output visualization information ODIN must be run with at least Log Level 3. Also be sure to redirect standard output to a file, so that the visualization information can be supplied as an argument to preprocessor or gzipped and read by the network viewer.

The only lines of output required by the preprocessor/network viewer are prefixed with "VIS". If you would like to limit disk space usage, you can "grep" for these lines.

Example invocations (from the supplied odin_input_files/sim directory):

../../build/odin-0.1/src/randomwalksim -v 3 ./squarerootprop.dat 1 >| /tmp/sqrt.ona && gzip /tmp/sqrt.ona
../../build/odin-0.1/src/randomwalksim -v 3 ./minneighborsprop.dat 1 | grep '^VIS' >| /tmp/min.ona && gzip /tmp/min.ona

Example invocations for randomwalkpeer are a bit involved to show here, but again it stands that log level 3 or higher should be used and standard output from each peer should be captured to a file (filtered for VIS lines if desired).

2.4. Developing ODIN Applications

If you're developing a new ODIN application and want to support visualization event logging, you only need to allow logging with level 3 or higher to either standard out or to a file. The user will then be able to take the log output from your application and visualize the ODIN network activity.