# README file

### This code is associated with the paper from Warren, Sin et al., "Spatiotemporal establishment of dense bacterial colonies growing on hard agar". eLife, 2019. http://dx.doi.org/10.7554/eLife.41093

###############################

# how to compile and run the cpp code?
# (1) compile the code:
# $> cd run_sim 
# $> g++ ../*.cpp -foepnmp -O3
# (2) run the code: 
# $> ./a.out in1.txt 2 /Direcotry/To/Output/Folder > /Redirect/Console/Output &
#### The command line argument in1.txt is the input txt file. 
#### The command line argument 2 means we run this code using 2 cores. You can change it to some other numbers. 
#### The command line argument "/Direcotry/To/Output/Folder" is the directory to output the data. 
#### The command line argument "> /Redirect/Console/Output &" means console outpout gets redirected to "/Redirect/Console/Output", and the program runs in background.

###############################

# don't blow up the memory
# If you run the code in a local machine, and you don't want to take up too much memory, you need to set the variable MaxCells to be small, say 100000. If you set it to be 3 millions, then it might take up a lot of memory. 
# To adjust MaxCells, you just go to in1.txt, and change the integer number that is next to "MaxCells".

###############################

# how is the data output?
# We have a global variable DirName (Defined in Constants.h), which takes in the 4th command line argument. The output is stored in the path given by DirName. 
# Under the DirName, there will be folders as the following:
# AgarField     Density       Density2      Height        Restart       RoughDensity1 WallDensity   WallDensity2  lineage
# Cells         Density1      Environment   Normal        RoughDensity  RoughDensity2 WallDensity1  WallField
# In each folder, there will be data files such as: 
# 0.txt   110.txt 123.txt 136.txt 149.txt 161.txt 174.txt 187.txt 2.txt   211.txt 224.txt 237.txt 25.txt  262.txt 275.txt 4.txt   52.txt  65.txt  78.txt  90.txt
# 1.txt   111.txt 124.txt 137.txt 15.txt  162.txt 175.txt 188.txt 20.txt  212.txt 225.txt 238.txt 250.txt 263.txt 28.txt  40.txt  53.txt  66.txt  79.txt  91.txt
# 10.txt  112.txt 125.txt 138.txt 150.txt 163.txt 176.txt 189.txt 200.txt 213.txt 226.txt 239.txt 251.txt 264.txt 29.txt  41.txt  54.txt  67.txt  8.txt   92.txt
# 100.txt 113.txt 126.txt 139.txt 151.txt 164.txt 177.txt 19.txt  201.txt 214.txt 227.txt 24.txt  252.txt 265.txt 3.txt   42.txt  55.txt  68.txt  80.txt  93.txt
# 101.txt 114.txt 127.txt 14.txt  152.txt 165.txt 178.txt 190.txt 202.txt 215.txt 228.txt 240.txt 253.txt 266.txt 30.txt  43.txt  56.txt  69.txt  81.txt  94.txt
# 102.txt 115.txt 128.txt 140.txt 153.txt 166.txt 179.txt 191.txt 203.txt 216.txt 229.txt 241.txt 254.txt 267.txt 31.txt  44.txt  57.txt  7.txt   82.txt  95.txt
# 103.txt 116.txt 129.txt 141.txt 154.txt 167.txt 18.txt  192.txt 204.txt 217.txt 23.txt  242.txt 255.txt 268.txt 32.txt  45.txt  58.txt  70.txt  83.txt  96.txt
# 104.txt 117.txt 13.txt  142.txt 155.txt 168.txt 180.txt 193.txt 205.txt 218.txt 230.txt 243.txt 256.txt 269.txt 33.txt  46.txt  59.txt  71.txt  84.txt  97.txt
# 105.txt 118.txt 130.txt 143.txt 156.txt 169.txt 181.txt 194.txt 206.txt 219.txt 231.txt 244.txt 257.txt 27.txt  34.txt  47.txt  6.txt   72.txt  85.txt  98.txt
# 106.txt 119.txt 131.txt 144.txt 157.txt 17.txt  182.txt 195.txt 207.txt 22.txt  232.txt 245.txt 258.txt 270.txt 35.txt  48.txt  60.txt  73.txt  86.txt  99.txt
# 107.txt 12.txt  132.txt 145.txt 158.txt 170.txt 183.txt 196.txt 208.txt 220.txt 233.txt 246.txt 259.txt 271.txt 36.txt  49.txt  61.txt  74.txt  87.txt
# 108.txt 120.txt 133.txt 146.txt 159.txt 171.txt 184.txt 197.txt 209.txt 221.txt 234.txt 247.txt 26.txt  272.txt 37.txt  5.txt   62.txt  75.txt  88.txt
# 109.txt 121.txt 134.txt 147.txt 16.txt  172.txt 185.txt 198.txt 21.txt  222.txt 235.txt 248.txt 260.txt 273.txt 38.txt  50.txt  63.txt  76.txt  89.txt
# 11.txt  122.txt 135.txt 148.txt 160.txt 173.txt 186.txt 199.txt 210.txt 223.txt 236.txt 249.txt 261.txt 274.txt 39.txt  51.txt  64.txt  77.txt  9.txt

###############################

# how to visualize the output data?
# We visualize the data using MATLAB, and in this section, we will write MATLAB commands:
# You can load the data by something like the following:
# $> dir_cells='/Direcotry/To/Output/Folder';
# $> i_cells=250;
# $> cells=load(sprintf('%s/Cells/%d.txt',dir_cells,i_cells));
# You can find out the indices of the cells whose center of mass has height less than 2um by the following command:
# $> dh = 2;
# $> i_btm = find((cells(:,6)+cells(:,9))/2<dh);
# You can find out the indices of cells whose center of mass has height less than 2um, with type 1 and type 2 by the following command:
# $> i1 = find(cells(i_btm,3)==1);
# $> i2 = find(cells(i_btm,3)==2);
# You can plot all such cells with stick representation and different color by the following command:
# $> quiver3(cells(i_btm(i1),4), cells(i_btm(i1),5), cells(i_btm(i1),6), cells(i_btm(i1),7)-cells(i_btm(i1),4), cells(i_btm(i1),8)-cells(i_btm(i1),5), cells(i_btm(i1),9)-cells(i_btm(i1),6), 'b', 'ShowArrowHead','off', 'Autoscale','off');
# $> hold on;
# $> quiver3(cells(i_btm(i2),4), cells(i_btm(i2),5), cells(i_btm(i2),6), cells(i_btm(i2),7)-cells(i_btm(i2),4), cells(i_btm(i2),8)-cells(i_btm(i2),5), cells(i_btm(i2),9)-cells(i_btm(i2),6), 'r', 'ShowArrowHead','off', 'Autoscale','off');
# You can adjust the view angles of the plot by:
# $> view(0,90);

###############################

# where is the information about cell division, cell age stored?
# Cell ages and division time of the two ends are stored in columns 24-27 of the output files under Cells folder. You may refer to the last a few lines of InputOutput.cpp for more details. 

##############################

# how do I set the level of grids and choose the Box_x, Box_y, Box_z, and Box_z_agar?
# There is a parameter maxLevels in in1.txt file that specifies the level of grids. I usually choose maxLevels to be 2~4. Usually we want Box_x=Box_y with mod(Box_x,4)=0, and mod(Box_z_agar,4)=0. 

##############################

# how shall I properly read the AgarField and WallField data? (Let's assume that we have Box_x=Box_y=128 and Box_z_agar=20)
# Read the AgarField data:
# $> agar=load(sprintf('%s/AgarField/%d.txt',dir_cells,i_cells));
# break the data into trunks (corresponds to different levels of the grid): 
# $> agar0=agar(1:end/4,:);
# $> agar1=agar(1+end/4:end/2,:);
# $> agar2=agar(1+end/2:end*3/4,:);
# $> agar3=agar(1+end*3/4:end,:);
# reshape the matrices:
# $> agar0=reshape(agar0, Box_y, 2*Box_z_agar, Box_x);
# $> agar1=reshape(agar1, Box_y, 2*Box_z_agar, Box_x);
# $> agar2=reshape(agar2, Box_y, 2*Box_z_agar, Box_x);
# $> agar3=reshape(agar3, Box_y, 2*Box_z_agar, Box_x);
# Define the carbon fields:
# $> carb0=agar0(:,1:end/2,:);
# $> carb1=agar1(:,1:end/2,:);
# $> carb2=agar2(:,1:end/2,:);
# $> carb3=agar3(:,1:end/2,:);
# Then we fill in the part of higher level grid that should be covered by the lower level grid:
# $> carb1(Box_y/4+1:Box_y*3/4, 1:Box_z_agar/2, Box_x/4+1:Box_x*3/4)=carb0(1:2:Box_y, 2:2:Box_z_agar, 1:2:Box_x);
# $> carb2(Box_y/4+1:Box_y*3/4, 1:Box_z_agar/2, Box_x/4+1:Box_x*3/4)=carb1(1:2:Box_y, 2:2:Box_z_agar, 1:2:Box_x);
# $> carb3(Box_y/4+1:Box_y*3/4, 1:Box_z_agar/2, Box_x/4+1:Box_x*3/4)=carb2(1:2:Box_y, 2:2:Box_z_agar, 1:2:Box_x);
# Then you can visualize the carbon field data in different levels, for example:
# $> imagesc(reshape(carb1(:,1,:), Box_y, Box_x));
# $> imagesc(reshape(carb2(Box_y/2,:,:), Box_z_agar, Box_x));