Miscellaneous Commands The commands described in this section are generally more simple in nature than those of previous sections. Some are perhaps obsolete, but included for the sake of completeness. * Menu: * Syntax:: Syntax of the miscellaneous commands * Function:: Purpose of each of the commands * Substitute:: List of all command line substitution parameters
Syntax of miscellaneous commands --------------------------------------------------------------------------- File handling: OPEN UNIT integer NAME filename [WRITe ] [UNFORMatted] [READ ] [FILE] [APPEnd] [FORMatted] [CARD] LOWEr ! Force the case of output file names UPPEr ! " CLOSe UNIT integer [DISPosition KEEP ] [DISPosition DELEte] REWInd UNIT integer INQUire ! get a list of open files and their qualifiers, only from CHARMM ! possible STREam [ UNIT integer ] ! Call another input file [ file_specification ] OUTUnit integer ! Redirect output to a different unit. RETUrn ! Return to the previous unit --------------------------------------------------------------------------- DEFIne keyname SELE atom_selection END SYSTem shell-cmd ! Execute a shell command (Unix) STOP ! Terminate CHARMM USER .... ! Invoke a user supplied subroutine (USERSB) --------------------------------------------------------------------------- TITLe manipulation: TITLe [COPY] ! Specify the main "write" title WRITe TITLe [UNIT int] ! output a title to the specified unit without ! closing the file and without initial "*"s. ! ***** (only from main command parser) --------------------------------------------------------------------------- Control levels: TIME {integer} ! Specify the timing level for performance evaluation {NOW } ! Show current time. {DIFF } ! Show elapsed time since last timed event WRNLev integer ! Set the warning print level. Higher values mean ! more warnings printed (default: 5). PRNLev integer ! Set the print level. Higher values mean ! more printout (default: 5). BOMBlev integer ! Set the error termination level NOBOmb ! Don't bomb on typing errors (same as BOMBlev -1). FASTer [integer] ! Specify efficiency level [OFF ] ! Disable fast routines [DEFAult] ! Use fast routines if possible. [ON ] ! Use fast routines, otherwise error. [SCALar ] ! Use scalar fast routines. [VECTor ] ! Use vector fast routines. [VPAR ] ! Use vector/parallel fast routines. [CRAYvec] ! Use vectorized CRAY fast routines. LONG ! specify long line output (<256 characters) SHORT ! specify short line output (<80 characters) --------------------------------------------------------------------------- Quick and simple structure analysis: QUICK repeat(integer) ! one atom # - position and type Q ! two atoms - distance ! three atoms - angle ! four atoms - dihedral ! five or more - average position --------------------------------------------------------------------------- RANDom specifications: RANDom UNIForm [SCALe scale] [OFFSet offset] [ASIN] [ISEEd iseed] GAUSsian sigma [ACOS] --------------------------------------------------------------------------- Run control: Command line sustitutions: SET parameter string ! Define a parameter CALC parameter arithmetic_expression ! Evaluate an arithmetic expression command ........ @parameter ........ ! use a parameter in a command command ........ @?parameter ........ ! existance of parameter command ........ ?energy-term ........ ! use an energy value in a command command ........ ?corman-value ........ ! use a corman value in a command SHOW [BUILtins] ! list all "?" substitution values. SHOW PARAmeters [VERBose] ! list contents of parameter table IF [parameter] [ EQ ] [ string] [THEN] command ! process a conditional [string** ] [ NE ] ! (**= single character not allowed [.EQ.] unless from @ or ? variables) [.NE.] ! IF [parameter] [ GT ] [ value ] [THEN] command ! process a conditional [value** ] [ LT ] ! (**= single character not allowed [ GE ] unless from @ or ? variables) [ LE ] [ AE ] ! AE = almost equal (diff<0.0001) [.GT.] [.LT.] [.GE.] [.LE.] [.AE.] GOTO label ! A branching command LABEL label ! Label (up to 20 characters) that may be branched to LET parameter assgnOp [ unaryOp ] arg [ binaryOp arg ] ! Modify parameter assignOp:== = |+=|-=|*=|/= unaryOp:== SINE|COSI|TANG|EXPO|LOG1|LOGE|SQRT| ABSO|INTE|NINT|ASIN|ACOS|ATAN|MAXI|MINI| binaryOp:== * |/ |- |+ |**|% arg:== real | integer INCRement parameter [ BY value ] ! Do an addition DECRement parameter [ BY value ] ! Do a subtraction MULTiply parameter [ BY value ] ! Do a multiplication DIVIde parameter [ BY value ] ! Do a division EXPOnent parameter ! Do an exponentiation GET parameter UNIT int ! read a parameter string FORMat [ (format_spec) ] ! Specify a format for encoding. TRIM parameter [ FROM integer ] [ TO integer ] ! Take a substring --------------------------------------------------------------------------- MMQM [atom-selection] [UNIT integer] ! Write selected QM atoms together GAUSSIAN_HEADER ! with the rest of atoms as charges <gaussian commands> ! as input to GAUSSIAN program END GAUSSIAN_BASIS <optional gaussian general basis set specification or other input> END --------------------------------------------------------------------------- DEADline commands: DEADline [CPU real] [CLOCk real] ! Time limits for job [SYNTAX ATLImit] ATLIimit alternate_command ! Execute if limits reached --------------------------------------------------------------------------- For assignment: parameter::= string containing alphanumeric or non-alphanumeric characters (no white-space (blanks or tabs) For substitution: parameter::= string-containing- alphanumeric-characters parameter::= {string containing lphanumeric or non-alphanumeric characters} energy-term::= see *note eterm:(energy.doc)Skipe. --------------------------------------------------------------------------- Convex ONLY: SPECIfy specify-keywords specify-keywords ::= PARAllel [NCPU integer-number-of-cpus] | FLUSh | NOFLush | NBFActor real-nonbond-memory-factor | FNBL { ON | OFF } EWEX { ON | OFF }
Purpose of the various miscellaneous commands 1) The OPEN command is used to open logical units to specific files specified from the input file rather than logical name aasignements made prior to the run. This is the recommended procedure to access a file within the program. OPEN can be used to redirect the output that appears on unit 6 to different files by opening unit 6 in the middle of a run. The APPEnd keyword causes output to be appended to the output file; useful if you want to get back to your normal output file without sacrificing the first part of it. The case of filenames opened for WRITE access may be specified with the LOWEr or UPPEr commands. 2) The CLOSe command closes a logical unit. This frees the associated file and logical unit so that they can be used for other purposes. The default disposition of the file is KEEP. 3) The REWInd command The REWInd command causes the requested logical unit to be rewound. When used with the STREam command, a particular sequence can be used more than once. 4) The STREam command The steam command allows the input of command sequence to be shifted to another file. This is useful when parts of an input file are to be used many times or used by many different calculations. The only input value is the unit number to transfer to. In place of a unit number, a file may be specified. Stream files must be card format and should begin with a title. 5) The RETUrn command The return command causes the input of command sequence to return to the stream that called the current stream. Streams may be nested to upto 20 calls. There are no parameters for this command --------------------------------------------------------------------------- 6) The DEFIne command This command allows the user to specify selection keywords. This command must contain a keyword and an atom selection. The keyword may then be used in subsequent atom selections. The keywords may not be abbreviated. 7) The SYSTem command Allows shell commands (sh, csh, ksh, etc.) to be executed from within CHARMM. 8) The STOP command The STOP command causes the program to terminate and to ignore all command that follow this command. This is useful for making temporary modifications to input files. Note: this command is only available from the main program. 9) The USER command, see *note user:(usage.doc)Interface. --------------------------------------------------------------------------- 10) The TITle command is used to modify TITLEA which is used whenever a file is written. This title is normally filled only in the CHARMM startup procedure. If the COPY keyword is used, then the TITLEB (the title from the most recently read file) is copied to TITLEA. Otherwise, a valid title specification should follow this command. --------------------------------------------------------------------------- 11) The TIMEr command sets the value of TIMER in COMMON /TIMER/ to the specified value. This variable is used to time different functions in the program. 1 will print out the time to evaluate ENERGY. 2 will print out individual component times in ENERGY, and the times for various components of the EXEL nbonds update. 12) The WRNLEV command sets the value of the WRNLEV variable in COMMON /TIMER/ to the specified value. This is used in WRNDIE and elswhere. Suggested values for future use: -5,5 warnings associated with fatal errors (see BOMBlev). 5 default should print brief warning and error messages for conditions that will affect outcome. 6 more extensive information on errors and some information on normal partial results and conditions 7 verbose error messages and more normal processing information for debugging 8 all information that might be relevent to an error condition plus checking results 9,10 debugging levels for anything you might concievably want. 10 or higher for term by term outputs from energy routines, or other tasks where huge amounts of data useful only in debugging might be generated. 13) The BOMBlev command sets the level which determines the types of errors which will terminate the program. The default is zero. A value of -1 is suggested for interactive use. Suggested values are; -5,-4 Limit exceeded type of errors. Run only as debug. -3,-2 Severe errors where results will be incorrect if continued. -1 Moderatetly severe errors, results may be bad. 0 Parsing type errors. Some important warnings. 1,2 Serious warnings. 3,4,5 Assorted minor warnings (see WARNlev for their suppresion). 14) The FASTer command controls when and whic fast energy routines will be used. the associated integer variable is decoded as follows: FASTer -1 : Always use slow routines FASTer 0 : Use fast routine if possible, no error if cannot (default) FASTer 1 : Use scalar optimized routine for some machines (error message if cannot use fast routines) FASTer 2 : Use fast scalar routine (only for testing) FASTer 3 : Use fast vector routine (only for testing) Certain conditions must be met in order to use the fast routines. If the fast routines are requested and cannot be used, an error message will be issued and the slow routines will be substituted. Also, there is less error checking for the fast routines. See *note fast: (energy.doc)fast. --------------------------------------------------------------------------- 15) The SET command sets up a command line parameter. The command line parameters will be substituted into the command line by the command line reader when it encounters the symbol "@". A command line parameter token can now be a string rather than just one of the single characters 0-9,a-z,A-Z. For substitution a token is indicated by the use of the @ character as before. The token is end-delimited by any non-alphanumeric character. In the case that the token is not found in the parameter table, a check is made to see if the first character of the token is itself a token in the parameter table. If this single character token is in the table, the corresponding value is substituted -- this is the necessary scheme to allow backwards compatibilty with the old parameter substitution, which allowed parameters embedded in strings. For unambiguous token detection, "protect" the token with brackets {} --- this allows for the use of non alphanumerics in tokens such as -,_. To test whether a token is in the parameter table, use @?token. This will substitute 1 if token is in the table, 0 if not. This is useful (in conjuction with the IF command) for setting defaults. (Note thar @? takes precedence over any of the built-in parameters such as ?ENER etc. --- it is parsed first). eg. SET outfile = myjob OPEN UNIT 1 WRITE CARD NAME @outfile.dat In the above example the token is delimited by the "." in the filename and the value "myjob" is substituted in place of "@outfile", resulting in an unit 1 being attached to the file "myjob.dat". To protect a token from surrounding alphanumerics, use brackets, eg. OPEN UNIT 1 WRITE CARD NAME @{outfile}today.dat File name becomes "myjobtoday.dat". The token is taken to be whatever is delimited by the brackets --- thus the token may in this case may also contain non-alphanumerics. eg. SET max-temp = 500. DYNA VERLET FINALT = @{max-temp} ... etc... For backwards compatibility, get token, check in table, if not present, then drop back to first character of token and check again. Substitute appropriately. eg. SET 1 rdie OPEN UNIT 1 WRITE CARD NAME @15.dat will result in a file named rdie5.dat Substitution operator @? To test the presence of a token in the parameter table use the @? operator. If the token is present, the value substituted is 1, if not 0. This is useful for setting defaults: eg. if @?{max-temp} .eq. 0 set max-temp 300. At present the parameter table is dimensioned as follows: Maximum number of parameters: 256 Maximum token length: 32 Maxiumum value length: 128 For current sizes use command SHOW PARAmeters VERBose (see below). --------------------------------------------------------------------------- 16) The SHOW command prints the available command line substitution parameters. SHOW by itself or with BUILtin keyword prints the parameters set internally by the program functions, such as ?ENER, ?RMS etc. SHOW PARAmeters lists the user defined @ command substitution parameter table. The VERBose keyword prints table limits on string sizes for tokens and values. 17) The IF command will optionally execute a command based on the value of the parameter used. Example; IF 1 GT 25.0 PRINT COOR The "EQ" and "NE" operations only compare strings. Thus the string "2.00" would not be equal to "2.0" with these conditions. The options requesting a value, do a value comparison. The AE option will test if two values are almost equal (difference less than 0.0001). This avoids the problem of round off error in loop counters (i.e. values like 3.999999). 18) The GOTO command will rewind the current input stream and search for the requested label. For the sake of efficiency, frequent use of this command (i.e. looping) should not be used with long input files. 19) The LABEL command does nothing except mark the presence of a label (up to 20 characters in length) to be used by the GOTO command. 20) The LET command can be used for simple command line parameter manipulation (but see also the CALC command below). An extension to the parameter manipulation commands such as INCR,DECR,MULT etc. has been made in the form of a rudimentary expression evaluator, accessible through the LET command (one of the miscallaneous commands). It has a VERY SIMPLE syntax definition, it is not a recursive descent parser! The command is *NOT* a general purpose calculator, ie. it cannot be given arbitrary arguments and deal with precedence etc. --- it has a simple syntax for simple expressions. The LHS must be a current token in the parameter table. There is no parameter lookup on the RHS of the expression, therefore parameters must be substituted through the use of @ or ?. It supports compound assignment operators +=,-=,*= etc.., It has some functions SQRT,SIN,MAX,MIN,ACOS,INT etc... It supports the usual binary operators, +,-,*,/ and % (MOD). Simple assignments: eg. LET count = 1 ! set count to 1 (count must have been SET) LET count += @incr ! count = @count + @incr A number of functions are supported, such as SQRT, COS, MAX, MIN: eg. LET sd = SQRT @var ! LET maxener = MAX maxener ?ENER ! maximum of two args for the MAX/MIN functions Binary operations use the simple operators *,/,+,-,**,% (mod) eg. LET count = @count + 1 ! self explanatory LET nmod = @count % 3 ! nmod = MOD(@count,3) if count=4, nmod = 1 There are no precedence rules, so you have to split the expressions appropriately. eg. The following expression: a = (( @a + max( @b, 4) ) ** sqrt(@area) ) / acos(-1) needs to be dealt with as follows: SET tmp ! all variables on LHS of a LET statement need to be defined. LET a += max @b 4 LET tmp = sqrt @area LET a = @a ** @tmp LET a /= acos -1 The LET command is robust wrt argument,operator and range errors. --------------------------------------------------------------------------- 21) The INCRement command will modify the selected parameter. If a value is not specified, then a value of 1.0 will be used. Example INCR 1 BY 2.0 22) The DECRement command is identical to the INCRement command except that a subtraction is done. The purpose of this command is to allow the subtraction of parameters. For example, the sequence; SET 1 ?ENER DECR 1 BY ?HARM WRITE TITLE UNIT 30 * @1 * will compute the total energy less the constraint energy and write it to a file. 23) The FORMat command allows the user to specify the format for ALL subsequent calls to ENCODF. This can be used to format the output of titles or other internal strings. Here are some examples; FORMat (I5) - All values will be integers. Good for looping and such. FORMat (F12.4) - Just what it says. FORMat - Reverts to current scheme for ENCODF (1PG14.6) followed by trimmimg FORMat (A12) - Won't work... If an integer format is used, the real value will be rounded to the nearest integer. The parenthesies are required around the format specified. If several different formats are needed, then the FORMat command should preceed each different required usage. NOTE: Not all string manipulation commands call ENCODF. The SET/LET commands do not. The INCRement command does, so the sequence; FORMat (f10.5) ! specify the format INCRement a by 0.0 ! apply the format to variable "a" may be used to format a particular variable without modifying its value. --------------------------------------------------------------------------- 24) The TRIM command allows a substring of a parameter to replace the same parameter. The FROM value determines the first character to be kept (default 1), and the TO value determins the last character to be kept (default current length). If a TO value that is larger than the length of the current parameter is used, blanks will be padded at the end. Preceding blanks may be added by; SET 5 ! set parameter five to the null string TRIM 5 to 10 ! convert parameter five to a string with 10 blanks SET 6 @5@6 ! add these 10 blanks to parameter six This command may be used for general formatting. --------------------------------------------------------------------------- 25) The DEADline command sets CPU and/or clock-time limits. These limits are checked in DCNTRL,ECNTRL, and GAUSHS (the parameter-fitting routine) at regular intervals. When a deadline has been reached the routine exits normally. This is useful when you have to stop computing before a given time of day (taking advantage of lower charge during the night or some such) or when you want to get some useful results and you are not sure that you can actually stay within the CPUlimit in a given batch queue. Keyword CPU <real> specifies that <real> CPUminutes from the time the command is given is to be one deadline. Keyword CLOCk <real> sets the time HH.MM (in 24-hour format) as one deadline. The routine assumes that if the command is issued after the specified time, you mean the following day. (If at 6 pm you start a job containing the line DEAD CLOC 13.00 CPU 600. your minimization will run until 600 CPU-minutes have been used, or until 1 pm the next day, whichever comes first.) 26) The ATLImit command can be given at any point in the input file. CHARMM checks before reading each command if either of the DEADlines (CPU or CLOCk) has been reached. If this is the case the alternate_command of the most recent ATLImit command is executed. This would typically be a GOTO SHUTdown or some other simple thing, but could be any CHARMM command. Currently the alternate_command is limited to 80 characters. 27) Substitutions and punctuation in command input. "!" Ignore this and all subsequent characters on this line "-" If this is the last character of a line then the following line is a continuation "*" As a first character indicates a title line. Alone on a line indicates a title terminator. "$" The default delimiter "* % # +" Atom selection wildcards, alone or in a word "@" Command parameter substitution "?" Energy value substitution --------------------------------------------------------------------------- 28) File inquiry. The inquiry command (from CHARMM) may be used to get a list of currently open files. This is very useful in interactive sessions when one has forgotten which FORTRAN units are already assigned. The command won't work if the files are assigned outside of CHARMM. 29) Random number generation. The expression ?RAND will have a random number substituted for it during command line evaluation. The default is to provide a number from a uniform distribution, between 0.0 and 1.0; the RANDom command allows modification of the distribution type and specification of other factors. The only required keyword is the distribution type, which must be second; for a GAUSsian distribution, a value for sigma is required; the default mean is 0.0. RANDom UNIForm [SCALe scale] [OFFSet offset] [ASIN] [ISEEd iseed] GAUSsian sigma [ACOS] Additional keywords: SCALe scale multiply the number by scale OFFSet offset add offset to the number ACOS treat the number as a cosine and return the angle (deg) ASIN treat the number as a sine and return the angle (deg) ISEEd iseed specify a new random seed (integer) Examples: RANDOM GAUSS 0.2 SCALE 10.0 ! gaussian mean of 0.0 with a sigma of 2. RANDOM UNIFORM SCALE 360. ! uniform 0. to 360 RANDOM UNIFORM ACOS SCALE .5 ! uniform angles with cosines from 0. to .5 RAND GAUS 5. OFFS 60. ! gaussian mean of 60. with a sigma of 5. RAND UNIF ISEED 7734 ! uniform new random seed Subsequent use of ?RAND will substitute a number from the appropriate distribution. --------------------------------------------------------------------------- 30) The CALC command allows the evaluation of any fortran-admissible arithmetic expression. It supports most of the normal fortran functions such as COS, SIN, TAN, EXP, LN, LOG, TANH, etc... Any number of parenthesis nesting is allowed. The substitution parameters @ is allowed directly. The substitution parameters ? can also be used but the character chain must be surrounded by blanks to be properly recognized; e.g., COS( ?pi ) is ok but not COS(?pi). Otherwise, there can be any number of blanks between the quantities involved in the arithmetic expression. See the testcase calc.inp for examples. --------------------------------------------------------------------------- 31) Writing input for GAUSSIAN series of programs. Selected atoms are treated as quantum atoms while the rest of the system is put at the end of the file in a format ready for CHARGE command within GAUSSIAN (must be at least version 92) Gaussian commands are specified after GAUSSIAN_HEADER keyword ended by the END keyword, and other input is optionally specified after GAUSSIAN_BASIS keyword. If none of the two is specified both END keywords must still be present. There is no check for the names of atoms not specified according to periodic table of elements. Use RENAme ATOM command to rename CA atoms for example. Charges are taken from RTF. MMQM [atom-selection] [UNIT integer] GAUSSIAN_HEADER # 6-31g** charge scf=direct mp2=fulldirect gen END GAUSSIAN_BASIS <optional gaussian general basis set specification or other input> END --------------------------------------------------------------------------- 32) SPECIfy specify-keywords ! Convex ONLY specify-keywords ::= PARAllel [NCPU integer-number-of-cpus] | FLUSh | NOFLush | NBFActor real-nonbond-memory-factor | FNBL { ON | OFF } EWEX { ON | OFF } description: 1. PARAllel - Tells CHARMm to run parallel (where possible). The optional NCPU keyword specifies the maximum number of processors to use. If a number is specified that is greater than the maximum allowed for the particular machine, a warning message is printed and the number of cpu's is set to the maximum. Note that at startup CHARMm senses the number of cpu's and sets NCPU accordingly. 2. FLUSh - Specifies the that trajectory; coordinate; dynamics restart and other output files should be flushed after each data set is written. See below. This is the default action. The command is provided to reset 4. NBFActor - When the parallel non-bond list generators allocate memory for the temporary arrays used by each thread, the predicted size of list array (MXJNB and the like), is divided by the number of cpu's and multiplied by NBFACT. The default is 1.5 and has worked well so far. If it doesn't the SPECIfy NBFACT <num> command is available to adjust it. 5. FNBL - FastNonBondListgeneration - Specifies whether or not to use the new non-bond list generation routines. Just included for testing and timing purposes. 6. EWEX - Ewald Exclusions - Specifies whether to generate special exclusion pair lists needed for Ewald calculations where there are non-bond exclusions. Default is on. If Ewald is not used the memory can be saved and some small amount of execution time skipped. See discussion of Ewald below.
Command Line Substitution Parameters The following are substitution parameters available within CHARMM; General: 'PI ' - Pi, 3.141592653589793 'KBLZ' - The Boltzmann factor (0.001987191) 'NSEG' - Number of segments 'NRES' - Number of residues 'NATO' - Number of atoms 'NGRP' - Number of groups 'NBON' - Number of bonds 'NTHE' - Number of angles 'NPHI' - Number of dihedrals 'NIMP' - Number of improper dihedrals 'NACC' - Number of acceptors 'NDON' - Number of donors Coordinate manipulation parameters: 'XAXI' - vector and length of defined axis form the COOR AXIS command. 'YAXI' 'ZAXI' 'RAXI' 'XCEN' - origin of axis vector 'YCEN' 'ZCEN' 'XMIN' - Extreem values from the COOR STAT command 'YMIN' 'ZMIN' 'WMIN' 'XMAX' 'YMAX' 'ZMAX' 'WMAX' 'XAVE' - Average values from the COOR STAT command 'YAVE' 'ZAVE' 'WAVE' 'MASS' 'RMS ' - Root mean squared difference between two structures. 'XMOV' - displacement of atoms from best fit. 'YMOV' - 'ZMOV' - 'THET' - Angle of rotation from best fit 'VOLUME' - Volume from COOR VOLUme command 'MIND' - minimum distance from the COOR MIND command. 'RGYR' - Radius of gyration for the COOR RGYR command. 'XCM ' - Center of mass 'YCM ' 'ZCM ' SCALar STATistics command substitution parameters: 'SMIN' - Minimum value 'SMAX' - Maximum value 'SAVE' - Average value 'SWEI' - Total weight used in the averaging 'STOT' - Total of selected atoms 'NSEL' - Number of selected atoms Quick command substitution paramteters: 'XVAL' - X position of group of atoms 'YVAL' - X position of group of atoms 'ZVAL' - X position of group of atoms 'DIST' - Distance between two atom analysis 'THET' - Angle for three atom analysis 'PHI ' - Dihedral for four atom analysis Atom selection parameters: 'NSEL' - Number of selected atoms from the most recent atom selection. Vibrational analysis of thermodynamic properties: 'FTOT' - Vibrational free energy. 'STOT' - Vibrational entropy. 'HTOT' - Vibrational enthalpy. 'CTOT' - Vibrational heat capacity. 'ZTOT' - Zero point correction energy. 'FCTO' - Classical vibrational free energy. 'ETOT' - Total harmonic limit classical free energy (to compare with free energy perturbation simulations). See (energy.doc) for the energy related substitution parameters.
NIH/DCRT/Laboratory for Structural Biology
FDA/CBER/OVRR Biophysics Laboratory