Revised December 23, 2011
[ This section is under construction. I will start with the
absolutely required minimum, and then gradually extend it. ]
The flow of calculations by miniCarlo is controlled by a user-specified
protocol. The protocol ("way-file") consists of a sequence of
commands, which invoke
simulation steps (i/o, energy minimization, Monte Carlo), control the flow of the
protocol, or modify various parameters (both parameters of simulations, and
independent parameters determining the nucleic acid structure). The protocol
file must be specified with the "-w" option in the miniCarlo
The command language allows loops (which
can be nested) and calls of files with sub-protocols. At the start of miniCarlo
the sequence of commands is compiled to minimize communications with disk.
Commands in the protocol are specified with four-character keywords. Empty lines in the protocol file and lines starting with the pound sign ("#") are ignored. Left white space (spaces and tabs) in each line is ignored, which allows using indentation. For each command only four first characters are interpreted and the rest of the line is ignored. All three following examples are equivalent:
TITL TITLE TITLE this is a command specifying the title of the jobAll required numeric data are in free format, but such data must be supplied on lines different from commands. The following is the correct example of setting temperature to 300K:
TEMP 300The following example is incorrect:
TEMP 300In the following, commands (keywords) will be shown in boldcase; <file> will stand for a valid unix file name, <data> will stand for numeric data; <integer> - for integer numeric data, etc.
The commands without a link are not described yet.
An asterisk denotes parameters that can be changed with ADDD, CHNG,
In lower case are the commands that will be deleted in one of new versions.
|Parameters changeable with ADDD/CHNG/MULT|
|parameter||default||description||all independent variables:|
all NUCLeotide parameters
|PAIR||0.0||all PAIR parameters|
|STEP||0.0||all STEP parameters|
|SAUP||0.0|| five elements of Saupe matrix
|CTOF||8.0||cutoff for non-bonded interactions|
|CVAL||50.0||force constant for bond angles|
|INCS||1.0||scale for SHAKE increments|
|OFST||0||offset for PAIR and STEP selection|
|PHOS||100 %||Neutralization degree of the phosphate group|
|WPNL||1.0||weight of all penalty terms|
|WCSA||1.0||weight of CSA restraints|
|WOBJ||1.0||weight of relaxation rates-based objective function|
|WPRE||1.0||weight of sugar pseudorotation restraints|
|WRDC||1.0||weight of RDC restraints|
|WRES||1.0||weight of distance restraints||Some other parameters (not changeable with ADDD/CHNG/MULT)|
|BEST||0||Controls output during Monte Carlo|
|CAVE||3||exponential for distance averaging among different copies|
|IJON||0||mode of backbone closure|
|MAVE||3||exponential for methyl averaging|
|MJMP||0||number of jump sites for methyl averaging|
|MXPL||0||mode of methyl averaging|
|PRNT||0||controls the details of STOR output|
|REGH||0||modifies energy calculation for regular helices|
ADDD, CHNG, MULT
Commands modifying selected parameter(s). Usage:
ADDD, CHNG, or MULT <selection of parameter(s)> <list of values>Each of these three commands modifies the selected parameters using specified <values>. CHNG sets the parameters to <values>, ADDD adds <values> to the current values of parameters, and MULT multiplies the current values of parameters by <values>.
CHNG CTOF 10.0and
CTOF 10will change the cutoff value for non-bonded interactions to 10 angstrom.
MULT WRES 1.2will multiply the current weight of distance restraints by 1.2.
ADDD TEMP 100will add 100K to the current value of temperature.
CHNG CTOF TEMP 10 400the above is incorrect: each parameter must be changed with a separate CHNG.
Calculating and outputting mean and std values for Metropolis Monte Carlo simulation. Usage:
AVERStrictly speaking, the usage of this command is not restricted to Monte Carlo simulations, but this is where it is most useful. Each time the command ITER appears in the protocol, a number of structural parameters for the current structure (including its internal coordinates) are added to the running sums for the mean and std values. AVER simply averages these running sums and outputs results in the file set with FAVE.
Commentary line. Usage:
COMMThis line is ignored. Useful to insert commentaries in the protocol.
Averages internal coordinates among all current copies of the molecule. This command is used only when miniCarlo is run with multiple copies (with the option "-m"). Usage:
CPAV <copy number>Internal coordinates are averaged among all current copies of the molecule taking into account current probabilities of each copy. The result is loaded into the copy <copy number>. The resulting probabilities are also modified: the new copy <copy number> gets a probability of 1.0 and the rest of copies get probabilities of 0.0.
Dielectric constant. Usage: parameter changeable with ADDD/CHNG/MULT. Default value -1.
When DIEL = 0, electrostatic interactions are ignored.
When DIEL is positive, dielectric constant is distance independent; electrostatic interactions are divided over DIEL.
When DIEL is negative, dielectric is distance dependent; electrostatic interactions are divided over the absolute value of DIEL times distance between the partial charges.
Percent of neutralization of the phosphate group. Changeable with ADDD/CHNG/MULT. When the neutralization is 100% (default), the total charge on each nucleotide is zero, and atoms O1P and O2P have partial charges of -0.33. When the neutralization is 0%, the total charge on each nucleotide is -1, and O1P and O2P have partial charges of -0.83.
Cutoff distance for non-bonded interactions. Usage: parameter changeable with ADDD/CHNG/MULT. Default value 8 Å.
List of non-bonded interactions is calculated and stored as a list of residue pairs rather than atom pairs. All interactions between two residues are calculated if at least a pair of atoms from these residues are at a distance below the cutoff value. This scheme of energy calculations combined with the usage of internal coordinates has an advantage of not having to evaluate energy terms that have not changed. If, e.g., only the roll parameter of step # 5 in a 10-bp duplex has changed, than the energy terms for the first four base pairs are not necessary to calculate again.
See also NBLS.
Sets file for output of mean and std values. Usage:
FAVE <file>Any output created by AVER command will be written to this file. If no file was set with FAVE, the output will be written in the file "fort.22". Existing files are overwritten with AVER without warning. Any new FAVE will close the previously opened file and open a new one.
Specifies file with a sub-protocol (subprogram). Usage:
FILE <file>Executes protocol from <file>. Nesting of FILE calls is allowed (maximum depth of nesting is 10).
FORN and NEXT
Specify loop in the protocol. Usage:
FORN <integer> <commands> ... NEXTPart of the protocol between FORN and NEXT is repeated <integer> number of times. Nested loops are allowed. No more than 20 FORN ... NEXT pairs are allowed in protocol.
Opens the output file for the internal coordinates. Usage:
FOUT <file>Any output created by STOR or ROUT commands will be written to this file. If no file was set with the FOUT command, the output will be written in the file "fort.50". Any new FOUT command will close the previously opened file and open a new one.
Sets the output file for short info. Usage:
INFO <file>The output created by the OUTP will be written in this file. This file is overwritten during each output. This file is useful during long Monte Carlo simulations when miniCarlo is run in background.
Input internal coodinates. Usage:
INPT <file> <integer record>This command inputs internal coordinates using record # <integer record> of file <file>; the previous internal coordinates are overwritten. Format of the input file is explained in other section; it is exactly the same as output written by STOR command. If multiple copies were set in the miniCarlo command line with the
Defines the completion of one iteration of Metropolis Monte Carlo simulation. Usage:
ITERStrictly speaking, the usage of this command is not restricted to Monte Carlo simulations, but this is where it is most useful. Each time this command appears in the protocol, a number of structural parameters for the current structure (including its internal coordinates) are added to the running sums for the mean and std values; this is called an "iteration". Then, AVER can be used to average these running sums and to output the results in the file set with FAVE.
Averages internal coordinates for the segment of Monte Carlo and loads them into the current structure. Usage:
LDAVSee Example 10.
Energy minimization. Usage:
MINI <num_cycles> PAIR, STEP, PLNE, NUCL, or SAUP <num> [IVAR] [<num_list>, <list of selected parameters' ID numbers>] [INCR] [<list of maximum increments for selected parameters>] ... PAIR, STEP, PLNE, NUCL, or SAUP <num> [IVAR] [<num_list>, <list of selected parameters' ID numbers>] [INCR] [<list of maximum increments for selected parameters>]It runs <num_cycles> cycles of minimization using selected variables (internal coordinates); non-selected variables are not changed during the minimization. Variables are selected with sequential keywords PAIR, STEP, PLNE, NUCL, or SAUP, each of which selects an appropriate group of variables. Selection of variables continues until any keyword is read which is not relevant to the selection. In the cases of PAIR, STEP, PLNE, or NUCL, <num> refers to the number of the group of variables (such as the first PAIR or second STEP). In the case of SAUP, <num> refers to the set number of the RDC restraints. Selection of each group of variables is expalined in more detail below.
Output of pdb file. Usage:
XMOL <file>When the number of copies of the molecule (which is set with the "-m" option in the command line) equals one, then the two keywords are equivalent. When the number of copies is greater than one, MMOL outputs structures of all copies into a single file; individual structures in the pdb file are separated by MODEL and ENDMDL records. XMOL in that case creates separate pdb files for each copy, with file names derived from <file>.
Update list of non-bonded interactions. Usage:
NBLSCalculates new list of non-bonded interactions using the current value of cutoff distance CTOF and current structure. In case of multiple copies of the molecule, each has its own list of non-bonded interactions. Also, this command writes on disk file "non-bonded.list", mostly for debugging purposes.
Short output of structure info. Usage:
OUTP <integer>This command is useful during long Monte Carlo simulations. If <integer> = 0, a short output is written onto stdio; if <integer> = 10, it is written into the file set with the command INFO (default name of this file is "info_current."; this file is overwritten each time). The latter is useful when miniCarlo is run in background.
Inputs spt-file with experimental cross-relaxation rates and sets the mode for the pdqpro/RELAX calculations. This command is used only when miniCarlo is run with multiple copies (with the option "-m"). Usage:
PDQX <mode value> <spt-file>or
PDQX <mode value>Allowed values for the <mode value>:
|-1||No pdqpro/RELAX calculations (this is a default value for this parameter when no PDQX command was executed).|
|0||Probabilities are calculated each time when objective function Qr is evaluated (i.e., during each energy call). This is the most common usage of PDQX.|
|1||Probabilities are not calculated, even though the objective function Qr is still evaluated.|
In multiple-copy simulations (miniCarlo must be started with the option "-m"), select active copies. Usage:
COPY <number of copies>, <list of copies>All manipulations with the molecule (such as minimization, Monte Carlo steps, changes in helical parameters) will be performed only on active copies, sequentially, in the order specified by the <list of copies>. By default, all copies are active, and the order is sequential from 1 to the total number of copies specified by miniCarlo "-m" option.
In multiple-copy simulations (miniCarlo must be started with the option "-m"), set populations (probabilities) of specified copies. Usage:
PROB <number of copies>, <copy number, probability> <copy number, probability> ...By default, all copies have equal probabilities.
Parameter modifying the output during STOR command. Default value: 0. Usage:
PRNT <value>Allowed values:
|0||Normal STOR output (default).|
|1||In addition to output of internal coordinates, STOR will output individual energy terms corresponding to the current list of non-bonded interactions.|
|2||Another set of energy terms for a duplex.|
These options must be used only with ndupl >= 3, i.e., with at least 3 planes. (Although it is not checked currently by the code)
Parameter used for calculation of regular or bi-regular helices.
REGH <value>Allowed values:
|0||Normal behavior (default).|
|1||For regular (heteronomous) helices.|
|2||For bi-regular helices, such as poly(dA-dT):poly(dA-dT).|
|3||For bi-regular helices, such as poly(dA-dG):poly(dC-dT).|
|4||The same as REGH = 1, but the energy is calculated for the full molecule, not per bp (for debugging purposes).|
REGH = 2 and 3 works for duplexes only. This two options not tested currectly!
Input distance restraints. Usage:
REST <file>Distance restraints are input from the <file>; see a description of the format of this file. Only one file of distance restraints can be input (files of distance restraints specified later in protocol will overwrite the previous ones).
Input residual dipolar constant (RDC) restraints. Usage:
RDCR <file>RDC restraints are input from the <file>; format of this file is similar to the distance restraints (atom name - residue number - atom name - residue number - lower bound - upper bound - lower force constant - upper force constant). In addition, the ninth column can optionally contain 1 ("one"), indicating that only the absolute value of RDC must be used. Unlike distance restraints, several files of RDC restraints can be input by separate RDCR commands, which could correspond to, e.g., RDC measured at different concentrations of alignment media.
Input 31-P chemical shift anisotropy (PCSA) restraints. Restraints must be in parts per billion (ppb) units. Usage:
PCSA <set #> <file>PCSA restraints are input from the <file>; file has a free format: each line must contain residue number - lower bound - upper bound - lower force constant - upper force constant. Set # is a number referring to a particular alignment condition, specifying the Saupe alignment tensor, which may be shared with RDC restraints. Note that in contrast to RDC restraints, this set number must be explicitly specified, while during input of RDC restraints, this set number is auto-incremented. Similar to other restraints, if there is only one copy of the molecule, actual PCSA values are used to calculate Erestraint. In the case of multiple copies, PCSA values are linearly ensemble averaged proportionally to the probability of each copy. In the latter case the term Erestraint is common for all copies of the molecule.
Input sugar pseudorotation restraints. Usage:
PRES <file>Sugar pseudorotation restraints are input from the <file>. Only one file of sugar restraints can be input (files of sugar restraints specified later in protocol will overwrite the previous ones). Each line in the file specifies a restraint for one residue; five numbers in each line, in a free format, are: residue number, lower bound, upper bound, lower force constant, upper force constant, e.g.,
# nucl P_lower P_upper c_lower c_upper 1 5.0 40.0 20.0 20.0 12 90.0 180.0 10.0 10.0
Sets parameter ir3r6 which controls type of distance averaging among various copies in multiple-copy refinement. Allowed values: 3 (default) for the 3rd-root averaging and 6 for the 6th-root averaging.
Sets parameter ir3r6_methyl which controls type of distance averaging among three methyl protons. Allowed values: 3 (default) for the 3rd-root averaging and 6 for the 6th-root averaging.
MAVE <integer>Note: The MAVE value has effect both on distances input as distance restraints, and distances involved in the residual dipolar coupling (RDC) definition. If RDC restraints involving methyl groups are used, then MAVE=3 must be used (the default value).
Sets the number of jump sites for averaging of distances involving methyl groups. When MJMP is set to zero (default), no averaging is done; instead, a pseudoatom in the center of the methyl group is used to calculate the distances. When MJMP is between 1 and 3, three sites are used, defined by the coordinates of three methyl protons. When
d = [ SUM_ij dij^(-MAVE) / Nij ] ^ (-1/MAVE)
where dij are individual distances, and Nij is the number of distances.
When parameter MXPL is set to one, the distance is calculated according to
d = [ SUM_ij dij^(-MAVE) ] ^ (-1/MAVE)
This option corresponds to AveType = 'sum' in XPLOR-NIH (which is
default in XPLOR-NIH), and it requires a corresponding treatment
during calibration of NOE distances involving methyls.
When MJMP is negative, the minimum distance is used instead of averaging; an absolute value of MJMP is used for RDC calculations in such a case. This is not a recommended option, use only for testing.
Type of averaging (3rd or 6th-root) is defined by the keyword MAVE.
Note: The MJMP value has effect both on distances input as distance
restraints, and distances involved in the residual dipolar coupling (RDC)
definition. If RDC restraints involving methyl groups are used, then
MJMP greater or equal to 3 is recommended, even though it is not a default
See also: MXPL, MAVE, REST, WPNL, WRES, RDCR, WRDC, and format of restraints.
Sets the mode of calculation of distances involving methyl groups similar to the XPLOR-NIH AveType = 'sum'. Useful for distance restraints imported from Xplor. For the distance restraints calculated with MARDIGRAS, the default value of 0 must be used.
Output restrained distances and residual dipolar contants (RDC) and their deviations in the file set with FOUT. Usage:
ROUT <integer>When <integer> = 1, ROUT produces short output (a number of deviation indexes). When <integer> = 2, ROUT also outputs all individual restrained distances and RDCs.
Restarts the Metropolis Monte Carlo chain. Usage:
RSAVThis commands zeroes all internal variables accumulated during previous execution of the IVAR command.
A single Metropolis Monte Carlo step (shake). Usage:
SHAK PAIR, STEP, PLNE, NUCL, or SAUP <num> [IVAR] [<num_list>, <list of selected parameters' ID numbers>] [INCR] [<list of maximum increments for selected parameters>] ... PAIR, STEP, PLNE, NUCL, or SAUP <num> [IVAR] [<num_list>, <list of selected parameters' ID numbers>] [INCR] [<list of maximum increments for selected parameters>]This command randomly changes values of selected variables within the limits of specified maximum increments and performs a single trial in the Metropolis algorithm (the new structure is accepted or rejected based on comparison of delta energy with the Boltzmann factor).
Scale factor for maximum increments during Monte Carlo steps. Usage: parameter changeable with ADDD/CHNG/MULT. Default value 1.0.
Selection of NUCLeotide parameters: sugar parameters, glycosidic angle, methyl group rotation for T, hydroxyl group rotation for ribo. Also, an appropriate part of the PLNE parameters in the cases when this residue belongs to the "third" or "fourth" strand in a triplex or a quadruplex, i.e., the six parameters defining the position of the base in this NUCLeotide.
(1) Select all variables in a NUCL # <residue_number>:
NUCL <residue_number> IVAR <num_list>, <list of NUCLeotide parameters' ID numbers>
NUCL <residue_number> IVAR <num_list>, <list of NUCLeotide parameters' ID numbers> INCR <list of values>This command selects residue # <residue_number> + OFST. If nothing else is done (1), all variables of this residue will be selected, and the default increment values will be used with MINI or SHAK. Instead, a specific list of variables can be selected (2), using IVAR. Further, default values of increments can be changed (3) with INCR.
Selection of PAIR parameters. Usage:
(1) Select all variables in a step # <step_number>:
PAIR <pair_number> IVAR <num_list>, <list of PAIR parameters' ID numbers>
PAIR <pair_number> IVAR <num_list>, <list of PAIR parameters' ID numbers> INCR <list of values>This command selects pair # <pair_number> + OFST. If nothing else is done (1), all variables of this pair will be selected, and the default increment values will be used with MINI or SHAK. Instead, a specific list of variables can be selected (2), using IVAR. Further, default values of increments can be changed (3) with INCR.
Selection of PLANE parameters: pair parameters in the plane, plus parameters of all residues ascribed to this plane (e.g., sugar parameters, glycosidic angles, rotations of methyl groups, if any exist, rotations of hydroxyl groups for ribo.
PLNE <plane_number>This command selects all varibales in a plane # <plane_number> + OFST and sets the default increment values for MINI and SHAK. Note, that in contrast to commands PAIR, STEP and NUCL, selection of a partial list of variables is not allowed (a combination of PAIR and NUCL commands can be used for this purpose. Changing the default increments with INCR is allowed but discouraged, because INCR requires the exact number of increment values to be provided, and this number may vary from a plane to plane, this could be easily a source of error in the protocol file. See also a description of pair and step numbers.
Selection of STEP parameters. Usage:
(1) Select all variables in a step # <step_number>:
STEP <step_number> IVAR <num_list>, <list of STEP parameters' ID numbers>
STEP <step_number> IVAR <num_list>, <list of STEP parameters' ID numbers> INCR <list of values>This command selects step # <step_number> + OFST. If nothing else is done (1), all variables of this step will be selected, and the default increment values will be used with MINI or SHAK. Instead, a specific list of variables can be selected (2), using IVAR. Further, default values of increments can be changed (3) with INCR.
Selection and setting of Saupe matrix elements Axx, Ayy, Axy, Axz, Ayz for calculation of a set of residual dipolar constants (RDC). Similar to AMBER, Saupe matrix elements are input & output scaled up 1E+5 times; makes numbers reasonable when the distanses are in angstrom. Usage:
(1) Select all Saupe matrix elements for the RDC set <set_number>:
SAUP <set_number> IVAR <num_list>, <list of Saupe matrix' ID numbers (from 1 to 5)>
SAUP <set_number> IVAR <num_list>, <list of Saupe matrix' ID numbers (from 1 to 5)> INCR <list of values>This command selects Saupe matrix elements for use within MINI or SHAK. Note that unlike NUCL, PAIR, PLNE or STEP, variables defined by SAUP do not have the pair or residue number, and OFST does not have an effect on this command. If nothing else is done (1), all variables of this step will be selected, and the default increment values will be used with MINI or SHAK. Instead, a specific list of variables can be selected (2), using IVAR. Further, default values of increments can be changed (3) with INCR.
SAUP <list of five values>
This is a parameter changeable by CHNG and ADDD. Default value zero. It adds to the STEP, PAIR, PLNE or NUCL number during the selection of variables. It is useful to, e.g., set a loop minimizing consecutive base pairs in the molecule.
See Example 4, Example 5.
This command can be used only after one of NUCL, PAIR or STEP was selected. It selects <num_list> variables specified in the list, e.g.,
STEP <step_number> IVAR <num_list>, <list of STEP parameters' ID numbers>
This command can be used only after a set of variables was selected; it changes the default increment values for the selected variables, e.g.,
STEP <step_number> INCR <list of increment values>or
STEP <step_number> IVAR <num_list>, <list of STEP parameters' ID numbers> INCR <list of increment values>Note that there must be enough of increment values provided for all selected variables. For example, both
STEP 3 INCR 99,99,99,99,99,99and
STEP 3 INCR 99,99,99,99,99,99,99are correct. There are only six variables in a step. In the second case, the extra "99" will not be read from the line 99,99,99,99,99,99,99. However, the following example will likely cause a core dump:
STEP 3 IVAR 5, 1,2,4,5,6 INCR 99,99,99,99because five variables were selected in the step #3 and only four increment values were provided. The program will attempt to read the fifth increment value from the next line of the protocol.
Output of internal coodinates. Usage:
STOR <integer>Internal coordinates of all copies will be sequentially output into a file set by the FOUT command. If such a file already existed, miniCarlo will abort with error status, unless the "-O" option ("overwrite") was specified in the command line. If the file was never set with FOUT, the output will appear in the file "fort.50". The value of <integer> will appear in the output file prior to the sequence of the molecule. It can be used to facilitate the search in long output files, but it does not have any function within miniCarlo. Each new STOR will append internal coordinates in the end of this file.
Controls output during Monte Carlo simulations. Usage:
BEST <integer>Allowed values are 0 (default) and 1. When this parameter is set to 1, it triggers the output of internal coordinates (as after the STOR command) each time when the total energy decreased after the SHAK. Useful only for the single-copy simulations.
Temperature (in Kelvins). Usage: parameter changeable with ADDD/CHNG/MULT. Default value 300K.
See Example 9.
Correlation time (in ns; default 0.0). Used only in output of pdb files, so that they could be directly used with Corma/Mardigras. Usage:
Sets the title of the job. Usage:
TITL <string>The first 50 characters of <string> will appear in the first line of the output file set by FOUT. It does not have any other function.
Weight of cross-relaxation rates-based objective function Qr. Usage: parameter changeable with ADDD/CHNG/MULT. Default value 1.0.
See Example 11.
See also: PDQX, format of spt-file.
Weight of sugar pseudorotation restraints. Usage: parameter changeable with ADDD/CHNG/MULT. Default value 1.0.
See also: PRES, ROUT.
Weight of distance restraints. Usage: parameter changeable with ADDD/CHNG/MULT. Default value 1.0.
See Example 8, Example 9.
See also: REST, ROUT, format of distance restraints.
Weight of RDC restraints. Usage: parameter changeable with ADDD/CHNG/MULT. Default value 1.0.
See also: RDCR, ROUT, format of restraints.
Weight of CSA restraints. Usage: parameter changeable with ADDD/CHNG/MULT. Default value 1.0.
See also: PCSA, ROUT.
Weight of all penalty terms. Usage: parameter changeable with ADDD/CHNG/MULT. Default value 1.0.