Pre-recorded Script Lesson, Input File

The precoded command input file used in this tutorial consists of a BTCL script (below) that controls the Discover run.

This example file contains links to the complete descriptions of the BTCL commands. The BTCL language. Added comments that were not part of the original file are in italics.

Default values that are not specified in the command input file are shown in the output file. 

#BIOSYM btcl 3
First, we define a handy BTCL procedure to echo a range of items in an object array...some of those below have hundreds of items, too many to conveniently echo them all. You may find procedures like this one useful for testing and debugging your own BTCL scripts. 

proc echoRange { obj first last } \
{
    # create `rng' containing `obj' items `first' to `last'
    object rng range $obj $first $last

    # print `rng' to a string, then echo that string
    echo [object rng print]
}
Define a BTCL procedure to multiply the temperature of all the atoms within radius of the center of the periodic cell by a factor of temperatureRatio, heating the molecules in the central part of the cell in order to analyze heat diffusion during dynamics. 

proc raiseTemperature { temperatureRatio radius } \
{
In the context of a Discover 95.0 script, ``database'' simply means a self-contained collection of interrelated tables. The Molecular System database is a description of a molecule or molecules as read in from the .car and .mdf files, possibly modified thereafter by script commands. A Dynamics database is derived in part from a Molecular System, but contains only the information necessary to simulate dynamics (for example, fixed atoms are removed).

In this example, there is only one system and one dynamics database, so there is no need for a database name after the dot in the database handle commands below. 

    # create "handles" to the Molecular System and Dynamics databases
    database handle molsys   system.
    database handle dynamics dynamics.
Next is an example of retrieving information from a table. The $handle get command (handle being replaced by a handle to a particular database) creates a new object array (third word) and reads information from a column of a table (fourth word, the names joined by a dot as Table.Column) into it. An optional fifth word can be used to specify particular rows of the table; when it is not present, the entire column (that is, all its rows) are retrieved.

Also note the temporary use of the echo command to follow the progress of the script during development. The command vector matrix is executed first--that is the effect of the brackets--and the result (here, a string with the contents of the matrix) is printed. 

    # get coordinates of periodic cell
    $molsys get matrix Cell.Fractional2Cartesian
    echo [vector matrix]
The vector command provides a large selection of arithmetic operations on vectors and matrices. The second word is a new variable name that is created to hold the result of the operation. The third word is the desired operation, in this example, the inner (dot) product of matrix with the vector { 0.5 0.5 0.5 }, which, being the product of a 3x3 matrix and a 3-element vector, produces a 3-element coordinate for the center of the periodic cell.

Note the { ... } notation in BTCL to represent an array or vector of any desired length. The double quotes are necessary to prevent the braces from being interpreted as a conditional or loop (if{}, for{}, etc.) script command. 

    # compute its center
    vector center dot $matrix "{ 0.5 0.5 0.5 }"
    echo [vector center]
The database handle select command searches a column of a table for a given value or values and returns a list of the rows that contained that value. The third word is the value or an array of values being selected for. The fourth word is the Table.Column to look in. The fifth word is the returned array of row numbers--since it is not prefixed by a $ to indicate an existing variable, a new variable is created for the result.

As mentioned above, the database handle get command can take an optional fifth word, the list of rows whose values should be retrieved. Here, we use $atom, the list of Atom-table rows returned by the select command, so that we retrieve the atom coordinates (Atom.Coord) only for those atoms whose Movability column contains 1.

We use the echoRange{} procedure, instead of the echo command, to verify that the first few entries of $coord are what we expect. In this example, $coord contains hundreds of entries, so it would not be convenient to print them all. 

    # get coordinates of all movable (i.e., not fixed) atoms
    $molsys select 1 Atom.Movability atom
    $molsys get coord Atom.Coord $atom
    echoRange $coord 0 10
Similar to the vector command, the geometry command can perform a large variety of geometrical calculations on vectors and matrices. The second word is a new variable name that is created to hold the result of the operation. The third word is the desired operation, in this example, the Euclidean distance between (fourth word) the array of the atoms' 3-dimensional Cartesian coordinates and (fifth word) the center of the periodic cell. We again use the echoRange{} procedure to make part of the interim results visible. 

    # compute their distance from the cell center
    geometry fromCenter distance $coord $center
    echoRange $fromCenter 0 10
Among the vector operations are equality and inequality comparisons. Here, we want to know which of the atoms are within $radius angstroms of the periodic-cell center, so we use the comparison operation le, putting the result into the new variable inSphere. 

    # make a true/false vector: which are within "radius" of center
    vector inSphere le $fromCenter $radius
    echoRange $inSphere 0 10
The object command performs operations on the value-arrays or row-lists returned by Table commands such as get or select; many of the operations can also be applied to vectors and matrices. In this example, the object ... filter command removes any entries in the atom list for which the corresponding entry in the $inSphere list is false. Note that in the object command, the second word has a special syntax: it is never preceded by $. 

    # prune the list of atoms according to the true/false vector
    object atom filter $inSphere
Although we use ``database'' in the Discover 95.0 program to mean a self-contained collection of interrelated tables, in fact, there are sometimes relationships between tables in different databases. For example, the rows of the Coord table in a Dynamics database are derived from the non-fixed atoms in the Atom table in a corresponding Molecular System database--each row in the former is related to a specific row in the latter.

The Discover 95.0 program does not directly support interdatabase relationships. The next two lines, using the object ... cast command are used to convert Atom table row numbers in the Molecular System database to their corresponding Coord table row numbers in the Dynamics database. The numbers are converted from row IDs to integers, then back to row IDs--but in a different database and table. You won't need to do this often, but with knowledge of the correspondences between tables in separate databases, you can make reliable conversions by this method. 

    # convert the list of atoms in the Molecular System database
    # to a list of rows in the Coord table in the Dynamics database
    object dynCoord get  $atom
    object dynCoord cast  int
    object dynCoord cast -database $dynamics rid Coord
The remaining operations in the procedure should be easy to understand, since most are variations of the commands described above. The new elements are the built-in sqrt() operation, and the database handle set command whose syntax is similar to the database handle get command. 

    # get the current velocities
    $dynamics get velocity Coord.Velocity $dynCoord
    echoRange $velocity 0 10

    # temperature is proportional to the square of the velocity
    $velocityRatio = sqrt($temperatureRatio)

    # multiply by velocityRatio and set results back into the table
    vector velocity multiply $velocity $velocityRatio
    echoRange $velocity 0 10
    $dynamics set $velocity Coord.Velocity $dynCoord
}
Now the execution of the Discover 95.0 script begins, after the script-procedures above have been read in and stored for later use. For this example, the most interesting point below is the execute +before ... command = ... option in the dynamics command. It is here that the raiseTemperature{} procedure is invoked before the beginning of the dynamics simulation. [ frequency = 0 means that the command is not repeated during the simulation; the next line, execute frequency = 50 ... is an example of a script command that is to be executed at intervals, in this example, every 50 femtoseconds.] 

  # run dynamics, executing the raiseTemperature{} procedure
  # before beginning ("frequency = 0" means that the procedure
  # will not be repeated during dynamics)
  dynamics \
    time = 100.0 timestep = 0.25 \
    execute +before frequency = 0 command = { raiseTemperature 16 5.0 } \
    execute frequency = 50 command = { print history } \
    initial_temperature = 298.0 +boltzmann \
    ensemble = nve \
    deviation = 500000

  writeFile coordinate filename = .cor
Main access page Insight UIF access Insight UIF - Tutorial access.

Pre-recorded Script Lesson, Introduction Pre-recorded Script Lesson, Lesson

Copyright Biosym/MSI