Revised February 15, 2001
[ 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,
|Parameters changeable with ADDD/CHNG/MULT|
|PAIR||0.0||all PAIR parameters|
|STEP||0.0||all STEP parameters|
|CTOF||8.0||cutoff for non-bonded interactions|
|CVAL||50.0||force constant for bond angles|
|OFST||0||offset for PAIR and STEP selection|
|WOBJ||1.0||weight of relaxation rates-based objective function|
|WRES||1.0||weight of distance restraints||Some other parameters (not changeable with ADDD/CHNG/MULT)|
|IJON||0||mode of backbone closure|
|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 DIEL times distance between partial charges.
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.
This is an obsolete keyword. In pre-released versions it had a purely syntaxis function; it was used with MINI and SHAK commands to indicate that the selection of STEP or PAIR parameters will follow. For consistency with old protocols, this keyword is still recognized, but is no longer necessary.
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_var>, <num_cycles> PAIR or STEP <num>, <num_list>, <list of PAIR or STEP parameters' ID numbers> <list of maximum increments for selected parameters> ... PAIR or STEP <num>, <num_list>, <list of PAIR or STEP parameters' ID numbers> <list of maximum increments for selected parameters>It runs <num_cycles> cycles of minimization using <num_var> selected variables (internal coordinates); non-selected variables are not changed during the minimization. Variables are selected with sequential PAIR or STEP commands. Each PAIR or STEP command selects <num_list> variables specified with the list of
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.
This is a parameter changeable by CHNG, ADDD and MULT. Default value zero. It modifies the number of a pair or a step during PAIR or STEP selection: it is added to the pair and step number specified in the PAIR or STEP command.
See Example 4, Example 5.
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.
Selection of PAIR parameters. Usage:
PAIR <num>, <num_list>, <list of PAIR parameters' ID numbers> <list of values>This command selects <num_list> variables from pair # <num> + OFST. The variables (internal coordinates) are specified in the list using their
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.|
Parameter modifying the output during STOR command. Default value: 0. Usage:
PRNT <value>Allowed values:
|0||Normal STOR output.|
|1||In addition to output of internal coordinates, STOR will output individual energy terms corresponding to the current list of non-bonded interactions.|
PRNT 0 FOUT separate_file.inp STOR 1
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).
Outputs distances and distance deviations in the file set with FOUT. Usage:
ROUT <integer>When <integer> = 1, ROUT produces short output (a number of distance deviation indexes). When <integer> = 2, ROUT also outputs all individual distances corresponding to distance restraints.
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 <num_var> PAIR or STEP <num>, <num_list>, <list of PAIR or STEP parameters' ID numbers> <list of maximum increments for selected parameters> ... PAIR or STEP <num>, <num_list>, <list of PAIR or STEP parameters' ID numbers> <list of maximum increments for selected parameters>This command randomly changes <num_var> 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).
Selection of STEP parameters. Usage:
STEP <num>, <num_list>, <list of STEP parameters' ID numbers> <list of values>This command selects <num_list> variables from step # <num> + OFST. The variables (internal coordinates) are specified in the list using their
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.
Temperature (in Kelvins). Usage: parameter changeable with ADDD/CHNG/MULT. Default value 300K.
See Example 9.
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 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.