This file provides documentation for the source code for 3DSOLM (Three Dimensional Stochastic Off-Lattice Model), a program for Green's function reaction dynamics (GFRD) simulation of binding reactions in crowded media. 3DSOLM was adapted from our previous 2DSOLM code for two-dimensional GFRD simulation of test reaction systems. For a full explanation of the code and citations to relevant literature, please see the references: B. Lee, P. R. LeDuc, and R. Schwartz. ``Three-dimensional stochastic off-lattice model of binding chemistry for crowded environments,'', in review 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: 3DSOLM.cpp Language/Operating System: The code is written in C++ use with any standard C++ compiler. Internal testing was done with GNU compiler tools on Linux stand-alone workstations and Beowulf clusters. Exact compilation instructions will vary by system, but should be adaptable to any standard C++ compiler. With Gnu g++, one can build the executable as follows: g++ -O4 -o 3dsolm 3DSOLM.cpp -lm The output executable (3dsolm) takes the following command line parameters: 1. Concentration of reactant monomers: 0 for 0% to 1 for 100% Initially, all reactants are monomers. The concentration is the volume ratio of particles to simulation space 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 overlap. 2. Total concentration: 0 for 0% to 1 for 100% The total concentration = the concentration of reactant monomer + the concentration of inert crowding particle 3. Alpha: volume ratio of dimer to monomer e.g., alpha=1 means that the volume of a dimer is the same as the volume of a monomer. alpha=2 means that the volume of a dimer is two times of the volume of a monomer. 4. Radius of a reactant monomer: unit is [nm]. e.g., 2.5 = 2.5nm 5. Beta: volume ratio of inert crowding particle to reactant monomer e.g., beta=1 implies the volume of a crowder is the same as the volume of a monomer. 6. d: diffusion coefficient, unit is [10^-11 m^2 s^-1] 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. 7. Binding probability upon a collision event: 0 for no binding 1 for 100% probability of binding on a collision 8. Mean time for a dissociation event: unit is [ns] Smaller value correspond to faster dissociation events for dimers. The mean time for dissociation is the inverse of the rate constant of dissociation. 9. Simulation time (unit is seconds) e.g., 0.000025 = 3DSOLM simulation runs for 25 micro-seconds. 10. d_th value for the threshold distance: unit is [nm]. 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 volume, where the unit cubic box ([0,0,0]-[1,1,1]) is assigned to the simulation box (50nm x 50nm x 50nm) for default cases. If the simulation box (length x width x height) is 50nm x 50nm x 25nm, then the assigned unit box is [0,0,0]-[1,1,0.5]. 11. check_snapshots: A flag to specify whether the simulator saves information to produce simulation snapshots. 1: save snapshot data, 0: do not save snapshot data 12. random_option: A flag to specify decides whether the simulator uses the system time as a seed value for the random function. 1: use system time to seed the random number generator, 0: use a default seed 13. simN: the number of independent simulation runs 14. boxlength: the side length of the square box, [nm], e.g. 50 = 50nm x 50nm x boxheight nm (length x width x height) 15. boxheight: the height of the simulation box, unit is [nm] For example, the following command line: 3dsolm 0.1 0.45 2.0 2.5 1.0 4.63. 0.7 1.0 0.000025 0.125 0 1 10 50.0 50.0 will run the program with the following parameters: 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: 4.63x10^-11 m^2 s^-1 binding probability: 70% dissociation mean time: 1 ns simulation running time: 25 micro-seconds (us) threshold distance: 0.125nm no information files are saved for simulation snapshots. the current system time is used to seed the random number generator. The simulator will execute 10 independent simulation runs for these input parameter values The length and width of the simulation box is 50nm x 50nm The height of the simulation box is 50nm. ------------------------ Simulation output files The simulation produces a set of output files useful for analyzing or visualizing simulation results. The even output files of 3DSOLM simulations use a matrix structure [rows, columns]. The number of rows is the number of data points per simulation run, which is hardcoded to 160. For example, if the simulation time (#9 in the command line parameter) is set to 25us, then 25 us/160 = 0.15625 us, so the time interval for saving each data points is 0.15625 us. The number of columns is the number of independent simulation runs. For example, if simN (the 13th command line parameter) is set to 10, then the output file is a matrix of 160 rows and 10 columns. The following seven file types are produced: 1. Dimer counts, in units of [molecules]. The main output file name is the total concentration (%) with ".dat" extension, which save dimer counts. For the simulation above, the file "45.dat" will contain dimer counts. 2. Successful and unsuccessful binding events, in units of [counts]. Because of excluded volume effects and steric hindrance, a collision of two reactant monomers that was randomly determined to be a binding event chosen to be a successful collision may nonetheless fail to produce a dimer due to overlap of the resulting dimer with surrounding particles. Two file types keep track of the numbers of successful and unsuccessful events to allow one to quantify the effect of steric hindrance on this aspect of the forward rate. The total concentration followed by a ".sbi" extension will count the number of successful binding events, and a similar file with a ".ubi" extension will count the number of discarded binding events. For the sample simulation above, for instance, the file "45.sbi" will contain the number of successful binding events, and "45.ubi" will contain the number of unsuccessful, discarded events. 3.Successful and unsuccessful dissociation events, in units of [counts]. Because of excluded volume effects and steric hindrance, the dissociation event for a dimer may also fail to produce two reactant dimers due to overlap of the resulting dimers with surrounding particles. Successful dissociation events are recorded in a file named by the total concentration followed by a ".sbr" extension and unsuccessful dissociation events by a file named by the total concentration followed by a ".ubi" extension. For the sample simulation above, for instance, the file "45.sbr" will contain the number of successful dissociation events, and "45.ubr" will contain the number of unsuccessful, discarded dissociation events. 4. Simulation running time, in units of [seconds] A file names by the total concentration followed by a ".sec" extension will measure the run time of the simulation. For the sample simulation above, the file "45.sec" will record the amount of compute time required per recording interval for the simulation. 5. Number of iterations, in units of [counts] The total concentration with ".itr" extension will show the number of iterations. For the simulation above, the file "45.itr" will contains the number of simulator iterations per recording interval. 6. Simulation snapshots These files provide a text format useful for generating visualizations of simulation progress. Due to the large file size, these must be enabled by the check_snapshots command-line flag. The output file name is "simR" followed by the concentration of reactant (%), the letter "T", the total concentration (%), an underscore, and a file count, with a ".txt" extension. For the simulation above, for example, files "simR10T45_0.txt", "simR10T45_1.txt", "simR10T45_2.txt", ... , "simR10T45_202.txt" will be produced, each providing particle positions for a single simulation time point. Each file will contain one row per particle with each row providing a position (in x, y, and z coordinated), an indicator of whether the particle is a monomer or dimer, the last sampled time at which the particle's diffusion limit sphere was updated, and an indicator for whether the particle is a reactant or inert crowding agent. The last row of the file will contain the simulation time at the recorded step. 7.Running time during initialization, unit is [seconds] A single file named by the total concentration with a ".int" extension records the running time during the initialization. For the simulation above, the file "45.int" will contain the running time for the initialization process.