Revised December 23, 2011

miniCarlo command language

[ This section is under construction. I will start with the absolutely required minimum, and then gradually extend it. ]

Examples of protocols
Index of commands and parameters
Default values of parameters
Command description

Overview

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 command line. 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 job

All 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
300

The following example is incorrect:


TEMP 300

In 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.

Index of commands and parameters

The commands without a link are not described yet. An asterisk denotes parameters that can be changed with ADDD, CHNG, or MULT.
In lower case are the commands that will be deleted in one of new versions.

ADDD	AVER	BEST	BLTZ	CAVE	CHNG	COMM	COMP*
COPY	CPAV	CTOF*	CVAL*	DIEL*	FAVE	FILE	FIND
FORN	FOUT	IJON	INCR	INCS	INFO	INPT	ITER
IVAR	labe	LDAV	loop	MAVE	MINI	MJMP	MMOL
MULT	MXPL	NBLS	NEXT	NUCL	OFST*	OH10	OUTP
PAIR	paus	PCSA	PDQ0*	PDQS*	PDQX	PHOS*	PLNE
PRES	PRNT	PROB	RATE	RDCR	REGH	REST	ROUT
RSAV	SAUP*	SHAK	STEP	STOR	SUG4	SYMM	TAUC*
TEMP*	TITL	UWND*	W12V*	W6VD*	WCSA*	WGAP*	WOBJ*
WPNL*	WPRE*	WRDC*	WRES*	XMOL

Default values Parameters changeable with ADDD/CHNG/MULT parameter default description all independent variables: NUCL 0.0 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 DIEL -1.0 dielectric constant INCS 1.0 scale for SHAKE increments OFST 0 offset for PAIR and STEP selection PHOS 100 % Neutralization degree of the phosphate group PDQ0 0.0 PDQS 0.0 TEMP 300.0 temperature TAUC 0.0 correlation time UWND 0.0 WGAP 1.0 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 SUG4 1 sugar model Commands description 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>. Two types of parameters can be selected for modification: Internal coordinates can be selected with PAIR or STEP commands in the same manner as they are selected for MINI or SHAK. In this case, <list of values> should correspond exactly to the list of selected parameters. Certain parameters controlling the flow of calculations can be selected by specifying their name CTOF, CVAL, DIEL, OFST, PDQ0, PDQS, TEMP, UWND, WGAP, WOBJ, WRES). Each of these parameters has its default value at the start of miniCarlo; each parameter must be changed with a separate ADDD, CHNG, or MULT command. Command CHNG can be omitted for the change of these parameters (but not for the change of PAIR or STEP). Examples: Both CHNG CTOF 10.0 and CTOF 10 will change the cutoff value for non-bonded interactions to 10 angstrom. MULT WRES 1.2 will multiply the current weight of distance restraints by 1.2. ADDD TEMP 100 will add 100K to the current value of temperature. CHNG CTOF TEMP 10 400 the above is incorrect: each parameter must be changed with a separate CHNG. It does not seem very useful to multiply such parameters as PAIR, STEP, OFST, but it is not disallowed. See Example 4, Example 6. AVER Calculating and outputting mean and std values for Metropolis Monte Carlo simulation. Usage: AVER Strictly 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. See Example 9. See also FAVE, ITER, RSAV, LDAV. COMM Commentary line. Usage: COMM This line is ignored. Useful to insert commentaries in the protocol. See Example 3. CPAV 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. This operation is different from that performed with LDAV. LDAV averages the accumulated segment of the Monte Carlo chain, and it can be used in both single- and multi-copy mode. (In a multi-copy mode, the Monte Carlo chain is averaged for each copy separately). See also: LDAV, COPY, PROB, BLTZ, PDQX. DIEL 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. PHOS 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. CTOF 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. FAVE 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. See Example 9. See also AVER, ITER. FILE 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). See Example 5, Example 8. FORN and NEXT Specify loop in the protocol. Usage: FORN <integer> <commands> ... NEXT Part 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. Loops are required for Monte Carlo simulations and simulated annealings. They are also convenient to run repeated similar operations, such as simulations of large molecules, organizing grid searches, and in many other cases. Bugs: Currently, the code does not check if the number of FORN ... NEXT pairs exceeded their maximum allowed number (currently, 20). See Example 3. FOUT 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. By default, existing files are not overwritten with FOUT, so that if FOUT tries to open the existing file, miniCarlo will abort with error message. To allow overwriting, use the "-O" option in the miniCarlo command line. See Example 1, Example 7, Example 8. INFO 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. The default name of this file is "info_current.". It is useful to change this name when several copies of miniCarlo are run simultaneously from the same directory. INPT 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 "-m <integer copies>", then internal coordinates will be input for each copy, starting with the record number <integer record> of <file>. In case if total number of record in <file> is less than number of multiple copies, the last record of <file> will be used to fill in internal coordinates of all remaining copies. For example, if the protocol of Example 1 is executed with the following command miniCarlo -m 2 -O -s aaa.seq -w aaa_1.way then both copies will have identical internal coordinates input from "aaa.inp". The format of input file depends on the value of parameter SUG4. Input file with internal coordinates can be also specified in the command line. Input from the protocol overwrites input from the command line. miniCarlo does not check if the internal coordinates are input at least once. If they have never been input, they are all zero by default. Bugs: If the input file was prepared using STOR with parameter PRNT set to 1, then INPT will be able to read only first record of this file. See Example 1, Example 6, Example 11. ITER Defines the completion of one iteration of Metropolis Monte Carlo simulation. Usage: ITER Strictly 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. There is a flexibility as to where ITER can appear in the protocol. Most logically, ITER must appear after the whole molecule has been randomly tried with the SHAK command(s). Iterations normally must be repeated using the FORN ... NEXT construction. During output of the current internal coordinates with STOR, the current iteration number is printed as parameter "RITER". Also it appears during the output with OUTP. See Example 9. See also FAVE, AVER, SHAK, OUTP, RSAV, LDAV. LDAV Averages internal coordinates for the segment of Monte Carlo and loads them into the current structure. Usage: LDAV See Example 10. See also RSAV, ITER. MINI 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. The maximum allowed number of selected variables is hard-coded, parameter 'MAXMN' in files "duplsize" and "dupz2.f". Don't try to minimize all independent coordinates at once; often it is more effective to split variables into several (possibly overlapping) subsets, and minimize them sequentially. After the minimization is finished, all variables are automatically deselected. In the case of multiple copies, all selected copies are minimized sequentially (see keyword COPY). See Example 2, Example 3. MMOL/XMOL Output of pdb file. Usage: MMOL <file> or 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>. See Example 3, Example 11. NBLS Update list of non-bonded interactions. Usage: NBLS Calculates 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. List of non-bonded interactions is updated in the following cases: when new structure is input when cutoff distance CTOF is changed when NBLS appears in the protocol See Example 9. See also: CTOF. OUTP 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. See Example 9. PDQX 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 Q^r 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 Q^r is still evaluated. When the PDQX mode is set to "0" or "1" for the first time, the file name for the spt-file must be provided. Once the spt-file is input, and the PDQX mode is not "-1", the objective function Q^r, scaled by the parameter WOBJ, is always added as penalty to the total energy of each conformer in the ensemble (copy of the molecule). See also: WOBJ, COPY, PROB, RATE, PDQ0, PDQS. See Example 11. COPY 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. See also: PDQX, PROB, miniCarlo command line options PROB 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. See also: PDQX, COPY, miniCarlo command line options PRNT 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. REGH 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! REST 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). After the distance restraints were input, the penalty E_restraint is always added to the total energy, scaled by two factors: WRES, a specific factor for distance restraints, and WPNL, a factor for all penalty terms. If there is only one copy of the molecule, actual distances r are used to calculate E_restraint(r). In the case of multiple copies, distances are third-root ensemble averaged proportionally to the probability of each copy. In the latter case the term E_restraint is common for all copies of the molecule. See Example 8. See also: WPNL, WRES, ROUT. RDCR 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. After the RDC restraints are input, the flat-well potential penalty E_restraint is always added to the total energy, scaled by two factors: WRDC, a specific factor for RDC restraints, and WPNL, a factor for all penalty terms. Factor WRDC is common for all sets of RDC restraints. If there is only one copy of the molecule, actual RDC are used to calculate E_restraint. In the case of multiple copies, RDC values are linearly ensemble averaged proportionally to the probability of each copy. In the latter case the term E_restraint is common for all copies of the molecule. Examples will come... See also: WPNL, WRDC, ROUT. PCSA 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 E_restraint. 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 E_restraint is common for all copies of the molecule. After the PCSA restraints are input, the flat-well potential penalty E_restraint is always added to the total energy, scaled by two factors: WCSA, a specific factor for CSA restraints, and WPNL, a factor for all penalty terms. Factor WCSA is common for all sets of RDC restraints. Examples will come... See also: WPNL, WCSA, RDCR, ROUT. PRES 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 Lines with "#" in the first position are ignored. After the sugar pseudorotation restraints were read, the flat-well penalty E_restraint is always added to the total energy, scaled by two factors: WPRE, a specific factor for sugar pseudorotation restraints, and WPNL, a factor for all penalty terms. In the case of multiple-copy refinement, sugar pseudorotation restraint energy is calculated for each copy separately, and NOT ensemble-averaged (this is in contrast to to distance and RDC restraints). See also: WPNL, WPRE, ROUT. CAVE 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. CAVE <integer> See also: REST, WPNL, WRES, RDCR, WRDC, and format of restraints. MAVE 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). See also: MJMP, REST, WPNL, WRES, RDCR, WRDC, and format of restraints. MJMP 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 MJMP is greater than 3, methyl proton is rotated through MJMP jump sites, starting with its original position. The average distance is calculated according to 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. MJMP <integer> 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 value. See also: MXPL, MAVE, REST, WPNL, WRES, RDCR, WRDC, and format of restraints. MXPL 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. MXPL 1 See also: MJMP, MAVE ROUT 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. See Example 8. See also: REST, WPNL, WRES, RDCR, WRDC, and format of restraints. RSAV Restarts the Metropolis Monte Carlo chain. Usage: RSAV This commands zeroes all internal variables accumulated during previous execution of the IVAR command. See Example 10. See also LDAV, ITER. SHAK 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). Selection of variables is done in the same way as during minimization during MINI, and it explained in more detail below. The selection is done immediately after the keyword SHAK, using any of the following 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. If the maximum increments are not explicitly specified with INCR, the default maximum increments are used, scaled by the constant INCS (default value 1.0). Total number of selected variables for a single shake and the maximum increments should not be very big, otherwise, most of new structures will be rejected. To make the protocols less cumbersome, the maximum increments are divided inside the program by the total number of selected variables, so usually it is not necessary to specify the maximum increments explicitly with INCR. In practice, it is believed that the Metropolis is the most efficient, if about 50% of all trials are rejected (reported in various outputs as parameter "NO"). If parameter "NO" is too low in trial simulations, scale factor INCS needs to be increased, and if "NO" is too high, INCS needs to be decreased. In the case of multiple copies, all selected copies are shaked sequentially (see keyword COPY). See Example 9. See also FAVE, AVER, ITER, RSAV, LDAV, INCR, INCS. INCS Scale factor for maximum increments during Monte Carlo steps. Usage: parameter changeable with ADDD/CHNG/MULT. Default value 1.0. Selection of variables: NUCL, PAIR, PLNE, STEP, SAUP NUCL 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. Usage: (1) Select all variables in a NUCL # <residue_number>: NUCL <residue_number> (2) Select <num_list> variables specified in the list: NUCL <residue_number> IVAR <num_list>, <list of NUCLeotide parameters' ID numbers> (3) All of the above, plus set the increments for the MINI or SHAK: 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. The variables (internal coordinates) are specified in the list using their ID numbers. See also a description of pair and step numbers. This command together with PAIR, PLNE and STEP, is used within the context of MINI, SHAK, CHNG, ADDD, or MULT commands. See Example 2. PAIR Selection of PAIR parameters. Usage: (1) Select all variables in a step # <step_number>: PAIR <pair_number> (2) Select <num_list> variables specified in the list: PAIR <pair_number> IVAR <num_list>, <list of PAIR parameters' ID numbers> (3) All of the above, plus set the increments for the MINI or SHAK: 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. The variables (internal coordinates) are specified in the list using their ID numbers. See also a description of pair and step numbers. This command together with STEP, PLNE and NUCL, is used within the context of MINI, SHAK, CHNG, ADDD, or MULT commands. New examples will come.. See Example 2, Example 3. PLNE 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. Usage: 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. This command together with PAIR, STEP and NUCL, is used within the context of MINI, SHAK, CHNG, ADDD, or MULT commands. Examples will come.. STEP Selection of STEP parameters. Usage: (1) Select all variables in a step # <step_number>: STEP <step_number> (2) Select <num_list> variables specified in the list: STEP <step_number> IVAR <num_list>, <list of STEP parameters' ID numbers> (3) All of the above, plus set the increments for the MINI or SHAK: 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. The variables (internal coordinates) are specified in the list using their ID numbers. See also a description of pair and step numbers. This command together with PAIR, PLNE and NUCL, is used within the context of MINI, SHAK, CHNG, ADDD, or MULT commands. New examples will come.. See Example 2, Example 3. SAUP 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> (2) Select <num_list> Saupe matrix elements specified in the list: SAUP <set_number> IVAR <num_list>, <list of Saupe matrix' ID numbers (from 1 to 5)> (3) All of the above, plus set the increments for the MINI or SHAK: 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. (4) Also this command can be used to set the Saupe matrix values: SAUP <list of five values> Examples will come.. OFST 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. IVAR 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> INCR 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,99 and STEP 3 INCR 99,99,99,99,99,99,99 are 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,99 because 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. STOR 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. The format of the output file is generally consistent with the input file, so it can be used for input with INPT (but see bugs). Some features of the output file depend on values of parameters SUG4, PRNT, PDQX. Command ROUT also produces output into the file set with FOUT. Bugs: See Example 1, Example 3, Example 4. BEST 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. TEMP Temperature (in Kelvins). Usage: parameter changeable with ADDD/CHNG/MULT. Default value 300K. See Example 9. TAUC 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: TAUC <value> See also: MMOL/XMOL. TITL 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. See Example 1. WOBJ Weight of cross-relaxation rates-based objective function Q^r. Usage: parameter changeable with ADDD/CHNG/MULT. Default value 1.0. See Example 11. See also: PDQX, format of spt-file. WPRE Weight of sugar pseudorotation restraints. Usage: parameter changeable with ADDD/CHNG/MULT. Default value 1.0. See also: PRES, ROUT. WRES 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. WRDC Weight of RDC restraints. Usage: parameter changeable with ADDD/CHNG/MULT. Default value 1.0. See also: RDCR, ROUT, format of restraints. WCSA Weight of CSA restraints. Usage: parameter changeable with ADDD/CHNG/MULT. Default value 1.0. See also: PCSA, ROUT. WPNL Weight of all penalty terms. Usage: parameter changeable with ADDD/CHNG/MULT. Default value 1.0.

-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 Q^r 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 Q^r is still evaluated.

Parameters changeable with ADDD/CHNG/MULT
parameter	default	description
all independent variables:
NUCL	0.0	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
DIEL	-1.0	dielectric constant
INCS	1.0	scale for SHAKE increments
OFST	0	offset for PAIR and STEP selection
PHOS	100 %	Neutralization degree of the phosphate group
PDQ0	0.0
PDQS	0.0
TEMP	300.0	temperature
TAUC	0.0	correlation time
UWND	0.0
WGAP	1.0
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
SUG4	1	sugar model

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.

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).