README file for DPRSim

DPRSim is the Dynamic Physical Rendering Simulator.  It provides a mechanism
to test distributed algorithms across networks of thousands of catom robots.
It also allows simple visualization of the simulated world.

DPRSim currently supports up to 32,000 catoms, each with their own thread of
execution and local data structures and networking.

*******************************************************************************

Usage
-----

> ./dprsim -e <experiment file>  [-w <world file>]

The experiment file is neccessary to run the simulation, and it can optionally 
reference a world file with the WORLD= tag.  If you specify a world file on the
commandline, that will overwrite the default world file specified in the
experiemnt file.

*******************************************************************************

File Formats
------------

DPR Simulator Files come in two classes, experiment files and world files.

World files are binary, with the following format:

[See the FILE-FORMAT file in this directory]

Experiment Files are human readable, plain text:

# This is a comment
TIMESTEPS=100
SAVE=10
VISUALIZE=true
MODULES=XYmelt
WORLD=cubephant.world
SAVEPOV=false
CAMERA=80,-100,80
CAMERALOOK=10,10,10
FOO=Bar!                 <-- non simulator supported key,value pairs will
                             be added to a seachable list at run time.

*******************************************************************************

Sample Output
-------------

[helfrich@dprsim]$ ./dprsim -e DATA/10_step_melt.exp

DPRSim: Parsing the commandline...
DPRSim: Loading Experiment File...
DPRSim: Loading World Data...
DPRSim: World Loaded. (8049 catoms)

DPRSim: Starting 10 step simulation.
DPRSim: Using world: DATA/cubephant.dpr
DPRSim: Running experiment: DATA/10_step_melt.exp
DPRSim: Running Modules: XYmelt
DPRSim: Saving every 1 time steps.

DPRSim: Running Simulation Step: (1/10)...
DPRSim: Running Simulation Step: (2/10)...
DPRSim: Running Simulation Step: (3/10)...
DPRSim: Running Simulation Step: (4/10)...
DPRSim: Running Simulation Step: (5/10)...
DPRSim: Running Simulation Step: (6/10)...
DPRSim: Running Simulation Step: (7/10)...
DPRSim: Running Simulation Step: (8/10)...
DPRSim: Running Simulation Step: (9/10)...
DPRSim: Running Simulation Step: (10/10)...

DPRSim: Simulation Ended.

[helfrich@dprsim]$

*******************************************************************************

Creating a new Code Module
--------------------------

Currently, to create a new code module, There are 4 things you (the developer)
must do.

1) In the CodeModules/ directory create your cxx/hxx pair for files, for this
   example, I will assume you are making a code module called "Life".  

   > touch CodeModules/Life.cxx; touch CodeModules/Life.hxx

   [of course at this point you want to fill in their content,
    which is outside of the scope of this document, look at XYMelt
    and Hierarchy as good examples]

2) Add this Module to the source list in the CodeModules/Makefile and the 
   main Makefile

   > emacs CodeModules/Makefile
   > [add Life.cxx to the COMOSRCS= list]
   > emacs Makefile
   > [add CodeModules/Life.cxx to the COMOSRCS= list]

3) Add this Module to the list of Possible Code Modules in the Simulator

   > emacs CodeModulesList.hxx
   > [add: #include "Life.hxx" where marked at the top]
   > [add: else if(*currentModule == "Life")
             codeModules.push_back(new Life(C.getID())); in the middle]

4) At this point you should be able to recompile the simulator and run an
   Experiment file that refences your new module in the MODULES= tag.

*******************************************************************************

