---
title: "README"
author: "Chris Rice"
date: "March 23, 2018"
output: html_document
---

## Installation:

The program has two prerequisites: the CMake meta build system and the Eigen C++ library. If you want to compile it locally on your Mac, you can install these using Homebrew:

```brew install boost cmake```

## Directions:

Aside from the main source file (simulation.cpp), the program also calls on a header file (individual.h), which has to be located in the same directory.

Build the simulator with CMake.

```
cd /home/analysis/path/to/sim
cmake .
make -j
```

Run the simulation using GNU parallel so that each set of output files gets its own suffix. For each suffix, the simulation outputs 3 files: one that follows the population as it evolves, one recording the parameters used, and one recording endpoint data. 

Example: params_035.txt, parameters_035.txt, endpoints_035.txt

In this example, the simulation will be run 100 times:
  
```parallel --joblog readme_example_log --delay=3 ./simulation --start_lb=2.0 --min_lb=1.0 --max_lb=3.0 --popSize=500 --output_suffix {} ::: 001 002 003 004 005 006 007 008 009 010 011 012 013 014 015 016 017 018 019 020 021 022 023 024 025 026 027 028 029 030 031 032 033 034 035 036 037 038 039 040 041 042 043 044 045 046 047 048 049 050 051 052 053 054 055 056 057 058 059 060 061 062 063 064 065 066 067 068 069 070 071 072 073 074 075 076 077 078 079 080 081 082 083 084 085 086 087 088 089 090 091 092 093 094 095 096 097 098 099 100```

When using parallel, several relevant options are available:  
--delay: set a few second delay between each replication of the simulation (for random number generation purposes)  
--joblog: create a logfile that stores progress information on each replication  
--dry-run: prints a list of individual commands that are all being made instead of in parallel (for checking that the syntax used will produce the right results)  

For the simulation in particular, several variables can be manipulated directly from the terminal:  
--start_lb: log(body size) value the simulation starts at (in this example, 2.0, corresponding to 100 grams)  
--max_lb: maximum allowed log(body size) value for the simulation to explore (in this example, one order of magnitude greater than the starting value)  
--min_si: minimum allowed log(body size) value for the simulation to explore (in this example, one order of magnitude smaller than the starting value)  
--endpointsensitivity: measure of how close the population needs to get to the target log(body size) value to complete the simulation  
--mutCount: number of mutations in the population  
--popSize: population size  
--gen_limit: maximum number of generations of evolution before the simulation terminates 
--burnLength: minimum length of the burnin period, during which the population converges onto the specified starting value from a random U(min_lb, max_lb) draw
 
In addition to outputting files, the simulation also prints results to the terminal, recording the average log(body size) and fitness every 50 generations:  
 
```
simulation rep:  ------------------------------------------------------------------------
 
burnin generation: 0
Avg body size: 228.457   Avg fitness: 0.983446
 
burnin generation: 50
Avg body size: 202.034   Avg fitness: 0.973064
 
burnin generation: 100
Avg body size: 170.794   Avg fitness: 0.95482
```

(skip)

```
burnin generation: 4650
Avg body size: 113.421   Avg fitness: 0.992333
 
generation: 0   Avg body size: 100.624   Avg fitness: 0.98148
generation: 50   Avg body size: 131.033   Avg fitness: 0.963444
generation: 100   Avg body size: 122.791   Avg fitness: 0.978776
generation: 150   Avg body size: 104.93   Avg fitness: 0.986534
generation: 200   Avg body size: 104.558   Avg fitness: 0.984476
```

(skip)

```
generation: 3350   Avg body size: 166.653   Avg fitness: 0.987866
generation: 3400   Avg body size: 157.692   Avg fitness: 0.993693
ending simulation
 
final stats: 
avg body size: 149.994    generations: 3428
total time: 9 seconds
```