This file provides documentation for the source code for 2DSOLM, a program
for Green's function reaction dynamics (GFRD) simulation of binding
reactions in crowded media.  For a full explanation of the code and
citations to relevant literature, please see the primary reference:

B. Lee, P. R. LeDuc, and R. Schwartz.  ``Stochastic Off-Lattice Modeling of Molecular Self-Assembly in Crowded Environments by Greenís Function Reaction Dynamics,'' Physical Review E 78, 031911 (2008)

Additional references, movie files demonstrating the code, and future
updates will be found at

http://www.cs.cmu.edu/~russells/projects/crowding/crowding.html

------------------------

Source code name: 2DSOLM.cpp

Operating System: GNU/Linux, Beowulf

The code is self-contained and compilable by any standard C++ compiler.
For example, with Gnu g++, one can build the executable as follows:

g++ -O4 -o 2dsolmv6 2DSOLM.cpp -lm

Run the output file (2dsolm) with following command line parameters:

1. Concentration of reactant monomer: 0 for 0% to 1 for 100%
   Initially, all reactants are monomers.
   The concentration is the area ratio of particles to simulation space
   (100nm x 100nm). 
   0.45 (45%) is in practice the maximum value possible before the
   simulator will be unable to randomly place all particles 
   in the simulation space without overlapping.
   
2. Total concentration: 0 for 0% to 1 for 100%
   The total concentation = the concentration of reactant monomer + the concentration of inert crowding particle

3. Alpha parameter: area ratio of dimer to monomer
   e.g., alpha=1 then the area of a dimer is the same as the area of a monomer.
        alpha=2 then the area of a dimer is two times of the area of a monomer.
        
4. Radius of a reactant monomer: unit is nm.
   e.g., 2.5 = 2.5nm 

5. Beta parameter: area ratio of inert crowding particle to reactant monomer
   e.g., beta=1 implies the area of a crowder is the same as the area of a
   monomer.

6. C: diffusion coefficient 
   The diffusion factor from Stokes-Einstein diffusion theory is
   d=kT/(6pinr), where d is diffusion coefficient, k is Boltzmann's constant,
   T is the absolute temperature of the solution, pi is 3.141592,
   n is the viscosity of the solute, and r is the radius of the solute molecule.
   The parameter used here is C = 100nm / (3*sqrt(2d)), 
   to make the calcuation of a diffusion limit circle easy in the simulation area    (100nm x 100nm).
   e.g., d=13.9x10^-11 m^2 s^-1, then C=0.002

7. Binding probability upon a collision event: 0 for no binding 1 for 100% for binding

8. Mean time for a dissociation event (unit is seconds)
   e.g., 0.000000001 = 1ns
   The smaller value is the faster dissociation event occurs for a dimer.

9. Simulation time (unit is seconds)
   e.g. 0.000025 = 2DSOLM simulation runs for 25 micro-seconds. 

10. D_th value for the threshold distance
    This is a simulation parameter describing the maximum distance at which 
    two particles can interact with each other. 
    The parameter used here is the converted value in the simulation area, 
    where the unit box (0-1) is assigned to the simulation area (0-100nm)
    D_th = threshold distance (nm) / 100nm
    e.g., D_th value (the threshold distance = 0.5nm) 
         = 0.5nm / 100nm = 0.005
    

For example:    
2dsolmv6 0.1 0.45 2.0 2.5 1.0 0.002 0.7 0.000000001 0.000025 0.005
reactant concentration: 10%
inert particle concentration: 35% (so, total concentration = 0.1 + 0.35)
alpha: 2
radius of a reactant monomer: 2.5nm
beta: 1
diffusion coefficient: 13.9x10^-11 m^2 s^-1
binding probability: 70%
dissociation mean time: 1ns
simulation running time: 25us
threshold distance: 0.5nm 

160 data points per each simulation run are saved (25us/160= for every 0.15625us) in output files. 
There are 30 independent simulation runs.
The main output file name is the total concentraion (%) with ".dat" extension.
For the simulation case above, "45.dat" contains dimer counts for 160 rows and 30 columns.