Introduction ------------ This directory contains a demonstration copy of BioWar, a city scale simulation of the effects of disease and chemical incidents on a population of individual agents. The demonstration has been prepared for systems running the Linux operating system. Specifically, this demonstration was prepared for Fedora Core 3 systems. Unpacking the Demonstration --------------------------- The demonstration is distributed as a tar archive and must be unpacked before use. 1. Copy the file biowar_demonstration.tar to disk. 2. Uncompress and expand the archive using the tar command: tar -xvjf biowar_demonstration.tar This will create the subdirectory "biowar_demonstration" in the current directory. While unpacking the archive, you may receive about trailing garbage (e.g. "trailing garbage after EOF ignored"). This warning message can be ignored. The tar archive was created using: tar -cvj biowar_demonstration >biowar_demonstration.tar Help and Further Information ---------------------------- For general information on BioWar, the Center for Computational Analysis of Social and Organizational Systems (CASOS) and simulation contact: Dr. Kathleen Carley CASOS Director 2323 Wean Hall Carnegie Mellon University 5000 Forbes Ave. Pittsburgh, PA 15213-3890 Phone: (412) 268-6016 Email: kathleen.carley@cmu.edu For technical assistance with installing or running BioWar and information BioWar program details contact: Neal Altman Senior Programmer 1317 Wean Hall Carnegie Mellon University 5000 Forbes Ave. Pittsburgh, PA 15213-3890 Phone: (412) 268-6628 Email: na@cmu.edu Directories/Folders ------------------- The demonstration includes the following sub-directories: biowar - program executables and default configuration files simenv - simulation environment files and support routines norfolk_series - sample city The Sample City --------------- The demonstration uses the Norforlk, VA area as a sample city. The norfolk_series directory contains separate 4 instances of the city in four directories: Completed simulations for study: - Completed 10% scale simulation of city in "norfolk_10%_sample" - Completed 100% scale simulation of city "norfolk_100%_sample" Skeletons for experimentation and practice usage: - Skeleton 10% scale simulation of city "norfolk_10%_practice" - Skeleton 100% scale simulation of city norfolk_100%_practice" The directory also contains a symbolic link to "simenv" which is a library of data and procedures for the simulation. Data which is not city specific and base data needed to generate a city instance reside here. Running the Simulation ---------------------- The simulation is performed in two steps: 1. Use gensim to create an instance of the city. This step takes counts of locations and population tabulations and creates specific locations and demographically distinct individuals with customary locations (home, work, school) and social networks. Once created the city instance can be used and reused; it does not have to be recreated each time the simulaiton is run. 2. Use biowar to execute the simulation proper. This step runs the simulation, moving agents, spreading and curing disease and resolving attacks. In this example, the 10% practice Norfolk directory is employed for a simulation run. - Change directory to the norfolk_series directory. - Run gensim: ../biowar/gensim norfolk_10%_practice | tee gensim.log - Run biowar: ../biowar/biowar norfolk_10%_practice | tee biowar.log Note that the convention of saving a copy of the console output to a file (" | tee biowar.log") is useful for debugging but is not required. Examining the Simulation Results -------------------------------- The primary simulation outputs are in the form of reports (text files) written into two subdirectories of the scenario directory. The sample directories already include examples of the output reports. For instance, example output for the 10% scale simulation is contained in: - norfolk_10%_sample/outputs - norfolk_10%_sample/debug Use of two ouput directories is a carryover from the early versions of the simulation and not otherwise significant. Configuring the Simulation -------------------------- BioWar provides literally hundreds of parameters which may be adjusted and a detailed description is beyond the scope of this demonstration. The most commonly altered parameters are contained in files within the scenario directory: - sim.cfg - common parameters for both instantiation and simulation. - biowar.cfg - parameters for the simulation step (biowar). - gensim.cfg - parameters for the city instantiation step (gensim). - report.cfg - controls which output reports are created. - attacksdef.txt - user created biological and chemical incidents. - responsedef.txt - user specified event triggered response rules. The default files contain commented examples. Creating Additional City Instances ---------------------------------- This section briefly describes the city creation procedure. For additional details, please contact the BioWar team. To recreate the 10% practice version: - Create the series directory (assumes user is currently in the biowar_demonstration directory). Note that this will delete the existing norfolk_series directory if one exists: simenv/support/scripts/mkseries.csh norfolk_series simenv - Create the scenario directories (user must move into the series directory). Note that this will, again, overwrite any existing directory. cd norfolk_series ../simenv/support/scripts/mkscen.csh norfolk norfolk_10%_practice Note that the support scripts creates symbolic links using the fully qualified directory path. For portability relative links were substituted in the demonstration archive.