Tutorial - PNNL-CompBio/Boltzmann GitHub Wiki

Compiling Unpack the archive if necessary. Then at the command line run:

./configure ./make The code should then successfully compile into an executable. Input Files Four input files are needed to initiate a simulation in Boltzmann: (1) a file of the reactions to be simulated, a file containing the initial concentrations of each chemical, (3) a file containing the standard free energies of formation in solution, and (4) a file containing the simulation run parameters such as the length of the simulation and where to put the output. Example input files The TCA cycle of E. coli: tca_redox1-2_concs.in tca_redox1-2.dat pseudoisomer_dg0f.txt tca_redox1-2.in Formats sample.in .in files are input files used to initialize Boltzmann simulation. Typical command-line usage is "boltzmann sample.in" RXN_FILE [ String ] Specifies file name of the reaction file (sample.dat file). INIT_FILE [ String ] Specifies file name of the concentration file (sample_conc.in file). The file can be used to restart a simulation by using the concentration output from the last step of the previous simulation. LOG_FILE [ String ] Specifies file name of the log file (sample.log file). OUT_FILE [ String ] Specifies file name of the log file (sample.out file). NOTE: Currently a bug in the code redirects all output to counts.out, and the name specified here is not being used. WARMUP_STEPS [ Number ] Specifies the number of warmup simulation steps (i.e. equilibration run). RECORD_STEPS [ Number ] Specifies the number of recorded simulation steps (i.e. production run). TEMP_KELVIN [ Number ] Specifies the temperature, used in calculating free energy of formation and/or reaction (see J. Phys. Chem. B for details). PH [ Number ] Specifies the pH, used in calculating free energy of formation and/or reaction (see J. Phys. Chem. B for details). IONIC_STRENGTH [ Number ] Specifies the ionic strength, used in calculating free energy of formation and/or reaction (see J. Phys. Chem. B for details). PRINT_OUTPUT [ 0 | 1 ] Disable (0) or enable (1) the printing of output. RXN_VIEW_FREQ [ Number ] Specifies the frequency of printing the output to the rxns.view file. CONC_VIEW_FREQ [ Number ] Specifies the frequency of printing the output to the ???? file. LKLHD_VIEW_FREQ [ Number ] Specifies the frequency of printing the output to the rxns.lklhd file. USE_METROPOLIS [ 0 | 1 ] Disable (0) or enable (1) metropolis criteria. NOTE: For some reason setting it to 0 will printout time-series details in the main log file. USE_ACTIVITIES [ 0 | 1 ] Disable (0) or enable (1) activity scaling. USE_PSEUDOISOMERS [ 0 | 1 ] Disable (0) or enable (1) the use of a precalculated "database" of free energy of formation of various metabolites obtained from eQuilibrator (refer to file pseudoisomer_dg0f.txt). NUM_METABOLIC_GROUPS [ Number ] Doesn't do anything, old code artifact. sample.dat .dat files contain the reaction data. REACTION [ String ] Specifies the name of the reaction. LEFT [ String ] Specifies the "left side" of the reaction (i.e. reactants) RIGHT [ String ] Specifies the "right side" of the reaction (i.e. products) ACTIVITY [ Number ] Multiplier/coefficient that scales the likelihood value. NOTE: Needs to have USE_ACTIVTIES flag enabled in the .in file for this to work, setting it to 0 will effectively disable a reaction. DGZERO [ Number ] Specifies the free energy of formation of the reaction. NOTE: The values specified here will be overwritten with the USE_PSEUDOISOMERS flag in the .in file.(???) DGZERO-UNITS [ KJ/mol | Kcal/mol ] Specifies the units of free energy. NOTE: Only KJ/mol has been tested up to this point. COMMENT [ String ] Comments are added in this line. // The double slash denotes the end of a reaction. sample_concs.in This file contain the data for the initial concentration for initializing the simulation. VOLUME [ Number ] Specifies the volume of the reactor (i.e. cell) in liters. Typical bacterial cell has a volume of 1 fL (i.e. 1E-15). CONC_UNITS [ Number ] Specifies the units for concentration. Typically set to 1E-0 to denote 1 mol/L as the normalized unit. SPECIES [ String ] CONC [ Number ] FLAG [ F | V ] Each row specifies the chemical species, and its initial concentration. The flag at the end determines if the concentration is fixed (F) or variable (V). pseudoisomer_dg0f.txt This file contains a list of free energy of formations (dG0_f) of an exhuastive list of metabolites obtained from eQuilibrator. This file is used when USE_PSEUDOISOMERS is enabled in the sample.in file. Output Files sample.log This is the main log file for the simulation. Description of each section (that are delineated by a string of "xxxxxxxxxxxxx") is as follows: Free energy of formations (dG0_f) used for various metabolites. Ensure that all values are nonzero Information on dG0_f mapping to index(???) Calculation of the molecular partition function for each species. NOTE: Appears as 0 and 1 because ATP tends to dominate. Not a very useful feature as of right now. Details of the reactions simulated, including stoichiometry, free energy of formation, and overall free energy of the reaction. Time-series of the simulation, in the format: Timestep, Reaction Choice, Likelihood of Forward Reaction, Likelihood of Reverse Reaction. sample.out .out files contain the data for counts. Generates a time-series of the count for each reactant/product. The first "Init" row indicate the count before warmup. The next "0" row indicate the count for step 0 of the recorded run. NOTE: These are numerical counts not concentration, the values can be converted to concentration by using Count / ( Avagrado * Cell Volume ). rxns.lklhd This file contains the data for likelihood of various reactions. Generates a time-series of the reaction likelihood, in the format: Timestep, Forward Reaction of Reaction #1, Backward Reaction of Reaction #1, Forward Reaction of Reaction #2, Backward Reaction of Reaction #2, etc... rxns.mat This file contains the stoichiometric matrix of each reaction simulated. rxns.view This file contains the data on each reaction firings and likelihood. The first row is a "no reaction" scenario, which is currently deprecated. Subsequent rows alternate between the forward reaction and backward reaction of the various reactions simulated, in the format: Reaction Name, Reaction Description, Total Number of Firings for Reaction, Net Firings for the Reaction (accounting for both forward and backward), Likelihoods at every RXN_VIEW_FREQ specified steps, starting with step 0. rxns.echo This file contains data on the actual reactions that are simulated. It should be identical to sample.dat if the simulation is working properly. rxns_dg0_ke.txt This file contains the the free energy of reaction (dG0_rxn) and the associated equilibrium constant (Ke) used for every reaction in the simulation. dG0_rxn would have been calculated from the free energy of formation (dG0_f) values entered into the simulation. boundary_flux.txt This file contains output on the number of times fixed chemical species (F option in sample_concs.in) are being consumed (negative) or produced (positive). This is helpful as a quick sanity check to ensure the metabolic process simulated is "making sense". Deterministic Simulations The executable for deterministic simulations is deq, not boltzmann. It takes the same input files as boltzman and prints out a .rstrt file that can be used as an initial concentrations file. In the .in file add the keyword DELTA_CONCS_CHOICE 0 You will get the default use of likelihood ratios in determining the concentration rates of change. Those concentration rates are computed in lr_approximate_delta_concs.c (called by approximate_delta_concs called by num_jac_col called by ode23tb to numerically approximate the jacobian). In that routine you can see where we compute the product_term and reactant_term variables as products of the species counts in each reaction and we only take contributions from the likelihood approximations, when those quantities are nonzero so as not to allow production from species that are nonexistent due to are reverse reaction likelihood assumption. To use the ode23tb with boltzmann instead of warm up iterations add to the .in file the line USE_DEQ 1 The DELTA_CONCS_CHOICE still applies there as well. (default is 0 if you don't specify).