Introduction ============ COPASI is a very powerful open-source program that can be employed for running a huge range of kinetic simulations of coupled chemical reactions, see http://copasi.org It comes with a nice graphical user interface. Rhis is very convenient and in many cases sufficient, but if lots of simulations are to be run, syshrtematically varying parameters or intial concentrations, using the graphical user interface alone can become cumersome and error-prone. This is what 'copd' (short for "COPASI driver") tries to address. Instead of having to set everything up via the GUI of COPASI a simple text file can be created, containing the relevant informations about the simulation to be performed. This text file is converted vy 'copd' into an 'XML' format and the command line cersion of COPASI is run with the result. Results are writing into files as also specified in the input text file. The 'copd' program also may create graphic representations of the results. The text file may also be used for running larger sets of COPASI simulations by defining paramters and concentrations as ranges, either in linear or logarithmic steps. For each element of each range a COPASI calculation is run automatically, and results are written to files with names clearly identifying the values of parameters and concentrations used. With this explorating large sets of COPASI inputs can be performed without supervision or changes via the GUI interface. For each run the XML input file COPASI was started with is retained and can be used to start the GUI version of COPASI. Another application has been to create an interactive web page, were users edit paramters and initial concentrations, which are used to create an input file for 'copd' from a template file for the model used, which then is runs with COPASI. The results in graphical form are then shown on a new page, which also allows download of all result files. Installation ============ As 'copd' is written in Perl you need a working Perl interpreter to also be installed on your system. Typically a reasonable Perl installation will come with all external modules required for running 'copd'. As 'copd' is a wrapper for COPASI you need to have COPASI installed somewhere where it can be started from 'copd'. For converting result data into graphics you also need to install the 'gnuplot' program, see http//www.gnuplot.info Download the 'copd' package (either as supplied or using git) somewhere on your computer. The paclet contains the 'copd' program and several "internal" modules it's based on. It's probably best to keep the 'copd' program in this directory together with its modules, otherwise you have to do a bit more of set-up. There are three variables that may need to be sett, 'COPD', 'COPASI' and 'HNIPLOT', to tell 'cpd' wjere to look for its modules and where to find (the command line version of) COPASI and 'gnuplot'. When set they miust be full, absolute paths. 'COPD' tells 'copd' the directory where its submodules are located. Only set it if 'copd' resides in a place apart from its submodules. The 'COPASI' variable is the full path of the command line version of COPASU (a executable named 'CopasiSI' or, under Windows, 'CopasiSI.exe'). If it's in a directory that's in the 'PATH' environment variable this variable doesn't need setting. Finally, 'GNUPLOT' is the full path of the 'gnuplt' executable (namd 'gnuplot' or 'gnuplot.exe' under Windows). Again, if it resides in airectory in 'PATH' setting the variabl is unnecesart. These variables can either be set by ceatung environment variables with their names or by setting them in a configuration file 'copd' will try to read. The configuration file has to have the name '.copd' (note the ;eading dot) and be either located in your home directory )as specpecified by the 'HOME' environment variable) or in the same sirectory the 'copd' program itself is located in. The format of the configuration file is simple - the relevant lines are those containing the name of one of the cariables, followed by anequal sign ('=') and then the path the variable is to be set to. Empty lines and lines starting with a '#' are skipped. For an example see the ',copd.examole' file coming with the packet. When 'copd' is started it first checks for ebvironmane variables. then for the configuration file in the home directory and finally in the directory the 'copd' program resides in. Once the value of a variable has been found it won't be changed anymore (even another setting is found in later steps). This out of the way you can start 'copd', for example using one of the inout files from the 'Examples' directory, which is also part of the packet. Command line options ==================== There are two command line options, '-r' and '-p'. The first one, '-r', requests that the output file contains not only concentrations but also rates for the species. The second one instructs copd to generate files with graphics of the results. Format of the Input File ======================== Please note that most of the terminology used in the following is, unsurprisingly, directly derived from the one used by COPASI. Thus a goof working knowledge of COPASI and the way things are specified in COPASU is required. The input file gets read in line by line, and each line must contain complete information, i.e. it's not possible to split information about an item to be defined into two or more lines. The file may contain comments, when reading in the file everything following the first hash mark character ('#') in a line is discarded. There are several example input files (all with extension '.cin') in the Examle direcory. Sections -------- The input file is subdived into a number of sections. Each section starts with a keyword, followed by a colon (':'), on its own line. Section keywords are Model Compartment Constants Functions Species Reactions Task Report Plots Please supply the sections in this order since the content of some of the sections depends on that of preceeding sections (e.g. in the 'Reactions' section only species can be used that have been declared in the 'Species' section before). Model section ------------- The only purpose of this section is to define a name for a model. This name is used for the COPASI XML input file name (with the extension '.cps') and, if no name is set, also for the output files. If not specified the name of the model defaults to 'Model'. Compartment section ------------------- In this section you can set the volume of the compartment (in liter) and also a thickness (in m), which is sometimes useful when the "compartment" is a membrane. You do this by assigning the words 'Volume' and 'Thickness' a value like this Volume = 1e-3 # one cubic centimeter Thichness = 1e-5 # 10 um, i.e. one hundreth of a mm These settings have no direct effect on the calculations. Constants section ----------------- This section can be used to define symbolic names to values to be used in the following sections. Each line consists of the name, followed by an equal sign ('=') and, in the simplest case, the numberical value to be associated with the name. Example XYZ = 1.3e-4 Instead of a single number a range can be specified. A range is always enclosed in square brackets ('[' and ']') which enclose information about the range. In the simplest case the range consists of a set of values to be assumed, separated by spaces, e.g. T = [280 290 300 310 320] This leads to COPASI being run as many times as there are values in the range, each time with a new value from that list. The output file names will contain strings like '_T=280' etc. to indicate which of the values was used in the calculation that produced the file. Another way to specify a range is by giving its start and end value, plus into how many values the interval is to be divided. The three values must be separated by colons (':'). The range defined bbove canthus also be specified by T = [280 : 320 : 5] This tells 'copd' to split up the range, starting with the first given value (280) and ending with the second (320) into equal intervals, so that 5 points (the third value of the range) are created. Sometimes you may want a logarithmic spacing instead. You then can qualify the number of values in the range by adding 'log' after it. E.g. Q = [1e0 : 1e5 : 6 log] This results in 'Q' being set to 1e0, 1e1, 1e2, 1e3, 1e4 and 1e5 in the subsequent calculations. Functions section ----------------- The 'copd' script only knows two functions, the irreversible and reversible "Mass action" functions. The first one is a constant named 'k1' times the prodduct of the concentrations of all educts, the second a constant named 'k1' times the product of the concentrations of all educts minus a second constant named 'k2' times the product of the conenctrations of all products. Functions to be used for other types of reactions have to be defined in this section. A function declaration consists of a name for the function, followed by a colon (':') and a formula. Such a formula is an arithmetic expression, using the operators '+', '-', '*', '/' , '%' (modulo) and '^' (power) and also functions predefined by COPASI, and constants and (concentrations of) educts ("substrates") and products. Here's an example: My function: 2 * q * Substrate_1 / sub2 - (1 - prod1^2 / (r - prod_2)) This defines a new function, named 'My function',q that is defined by the formula on the right hand side of the colon. The formula contains two constants, 'q' and 'r' (which have to be specified with the reaction for which the function is used later on) and uses the concentrations of the first and second "substrate" (educt) and the first and second product. Each name in the formula starting with 'sub' (case-insensitive) is interpeted as a substrate, each name starting with 'prod' as a product. The number at the end of the name corresponds to the position of the educt or product of the reaction. A function may also contain the initial concentration of one or more species (with the species name enclosed in square brachets and followed by '_0'): Ny function2: kx * [H2O]_0 * substrate1 The term '[H2O]_0' for the initial concentration of the species named 'H2O' will be replaced in the generated '.cps' file by the numeric value of the corresponding concentration (in mol/l). Finally, a function may followed by another comma and one of the keywords 'irrev' or 'rev' to mark the function as an irreversible or reversible reaction. Species section --------------- In this section all species used in all reactions have to be declared. A declaration consists of the species name, followed by a comma (',') and then its initial concentration, a concentration range, or a formula for calculating the concentration of the species. A line with simple initial concentration looks like this H20, 1e-3 Concentrations are in mol/l. If the concentration is to be kept constant (i.g. unchanged no mater how much of the species is consumed or produced by the reations) append the 'fixed' keyword: H20, 1e-3, fixed (the comma between the initial concentration and the 'fixed' keywork is optional). A range of initial concentrations can have several forms H2O2, [1e-3 2e-3 3e-3 6e-3] Here the range is a simple list of numbers and for each of them a new COPASI calculation will be done. As explained before ranges cam also be specified in the form [ start : end : count ] e.g. H2O2, [1e-3 : 5e-3 : 5] This will trigger calculations for 5 initial concentrations if H2O2, 1e-3, 2e-3, 3e-3, 4e-3 and 5e-3 (mol/l). You may also add the keyworld 'log' at the end of the range to get values of the initial concentration that are not evenly spaced but in exponential increments. E.g. H2O2, [1e-3 : 1e-6 : 4 log] would result in calculations for the initial concentrations 1e-3, 1e-4, 1e-5 and 1e-6 (mol/l). Also ranges can be qualified as 'fixed' to keep them constant in the calculations. Just add 'fixed' (with or without a comma) after the closing square bracket (']') of the range. Finally, a concentration may also be given by a formula that uses an arithmetic expression involving concentrations of specie previously declared in the 'Species' sectopn. Here's an example Fe2+, 1e-4 Fe3+ 0 total iron, [Fe2++] + [Fe3+] The concentration of the third pseudo-species ("total iron") will be the sum of the transient concentrations of the Fe2+ and Fe3+ species. Such an assignment may contain transient concentrations, indicated by the species name in square bracketss ('[' and ']') and also initial concentrations when the concentration expression is followed (without a space) by '_0'. I.e. [CH4]_0 stands for the initial concentrations of the species named 'CH4'. The assignment may also contain all operators and most functions and constants COPASI knows about (see the "User Defined Functions" section of the COPASI manual). You may also declare species that don't appear in any of the reactions. The 'total iron' pseudo-species is an example: it's just declared to be included in the 'Report' section (see below) in order to ascertain that the total iron concentration will appear in the output file. Reaction section ---------------- A reaction declaratoion consists of up to 4 elements. It may start with an optional name for the reaction, followed by a colon (':'). If no name is specified reactions are named 'R0', 'R1', 'R2' etc. Next comes the chemical reaction, with the educt and product side separated by '->'. A '+' is to be used between the species of the educt and product side, and each species may be preceeded by an integer number and '*' to describe the stochiometric ratios. E.g. 2 * H2 + O2 -> 2 * H2O Each species in a reaction must have been defined in the 'Species' section. The end of the chemical reaction must be marked by a comma (','). It may be followed by the name of a function defined in the 'Functions' section, and another comma. This has to be followed by assignments for all constants used by the function, separated by commas. So a reaction declaration may look like this My reaction, 3 * H2 + 2 * CH4 -> 5 * X + 3 * Y, My function, r = 1e3, q = 23 using the 'My function' declared previously in the Functions section (which had 2 constants, 'r' and 'q'). The exception from this scheme are the predefined "Mass action" functions, for these functions no name is to be specified. If the 'irreversible' function is to be used just soecify its 'k1' varuanle, for the 'reversible' function both 'k1' and 'k2', Please note: a) The educt and product side of the reaction must contain at least as many atoms/ions/molecules as are used in the function for the reaction b) Each constant used in a function for a reaction must have a specified value. As in the case of initial constants and concentrations, a constant assignment for a function parameter can be either a simple number or a range of values. Again, you can use a list of values or a computed set of values. Here are three examples 2 * H2 + O2 -> 2 * H2O, k1 = [17 11 25 13] 2 * H2 + O2 -> 2 * H2O, k1 = [1e3 : 1e8 : 1001] 2 * H2 + O2 -> 2 * H2O, k1 = [1e3 : 1e8 : 61 log] They would result in 4, 1001 or 61 calculations, using different values of the reaction constant with the irreversible Mass action function. Task section ------------- This section is very simple. All you can specify is a number, the number of seconds the calculation(s) are to be done for. So a line with 3.6e3 means that the simulation will cover a time of one hour. Report section -------------- The main purpose of this section is to specify which concentrations (and rates, if the program was started with the '-r' option) are to be included in the report file from the COPASI calculation. You simply can specify a list of all the species (each on its own line) you want to have writted into the report, using the names declared in the 'Species' section. If this section is missing or empty then the concentrations of all species not marked as 'fixed' in the 'Species' section will appear in the COPASI output file (a file with the extension '.crp', short for "COPASI report). In this section you can also set a name for the output file(s): the first line with an entry that is not a species name is used for the name of the output files. Such file names can include an absolute or relative path, so /home/jens/COPASI-Results/XyZ ../COPASI-Results/XyZ or C:\My Files\COPASI Results\xYz should all be fine As just mentioned the name of the output file(s) can be set in the 'Report' section (it defaults to the model name if not specified). In case you use ranges for initial concentrations or reaction constants etc. the names of these concentrations or constants and their values will be appended to the file names to make them unique and easy to distinguish. An example: if you had two ranges, one for an initial concentration of a species named 'KCN' and one for a constant named 'Kx' in the reaction named 'R6', and set the file name to be '/home/jens/my_result' then the COPASI input and a result file name will be something like /home/jens/my_result_[KCN]=1e-3_Kx(R6)=0.123.cps and /home/jens/my_result_[KCN]=1e-3_Kx(R6)=0.123.crp to indicate that these are the files for the initial concentation of the 'KCN' species of 1 mol/l and calculated with a reaction constant 'Kx' of 0.123 for the reaction named 'R6'. Plot section ------------ Into the file instructions for plotting the results of the COPASI calculation can be included. This isn't dpne via COPASI itself but instead the result file just written by COPASI is read in abd then using the 'gnuplot' program to create graphic representations (in JPG format) of the data. The files created can contain either concentrations of rates (if they were written to the COPASI output file by starting 'copd' with the '-r' option). For each file to be created you need a sub-section, startung with either "Concentrations:" or "Rates:", optionally followed by the title to be printed at the top of the graphic. This title also becomes the final part of the name of the file generated. Without ant further information in these sub-sections all concentrations or rates from the result file are plotted. Alternatively, the sub-section may contain a list of the species from te result file that are to be shown. E.g. Concentrations: Radical Concentrations H. OH. Rates: Radical Formation Rates H. OH. Keep in mind that only concentrations (and rates) can be plotted that appear in the COPASI report file. Per default the data are drawn using linear axis. It's also possible to use logarithmic scales for the x- and/or y-axis. Use Concentrations: My data [logx] [logy] "My date" becomes, as usual, part of the file name and is used as the title of the plot. With '[logx]' you request a logarithmic x-axis and with [logy] the same for the y-axis. Acknowledgments =============== Without the excellent work of the authors of COPASI and making it available 'copd' would never have been written. The most relevant publication about COPASI is Hoops S., Sahle S., Gauges R., Lee C., Pahle J., Simus N., Singhal M., Xu L., Mendes P. and Kummer U. (2006). COPASI: A COmplex PAthway SImulator. Bioinformatics 22, 3067-74. The 'copd' program was develped in cooperation with Prof. G. Gescheidt and Dr. P. Frühwirt, Institute of Physical and Theoretical Chemistry at the Technical University Graz (Austria). I'm indepted to them for initializing the development, teaching me lots about chemistry, helpful discussions and testing many versions, making me aware of bugs and suggesting improvements. Financial support by the Austrian Research Promotion Agency (FFG) is gratefully acknowledged. The program was developed in connection with the SOH4PEM (State of Health Monitoring for Proton Exchange Membrane Fuel Cell Stacks) project. License ======= The 'copd' package is distributed under the conditions of the General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version. The full text of the license can be found in the file 'COPYING'. Note: this license does not restrict the use of the program or the results you created with its use. Only if you distribute the program itself (as is or with modifications) you have to make the sources available. 2023-05-22 Jens Thoms Törring