Print this page

A simple example of a Tcl script follows. The script is stored in a file, usually with the extension .tcl, and is executed using the Utilities/Playback Script within Cerius². This particular example calculates the distance between all pairs of sulphur atoms in a structure.

One straightforward way of doing this would be:

foreach atom1 [MODEL/GET ATOMS] { foreach atom2 [MODEL/GET ATOMS] { if {[ATOM/GET ELEMENT $atom1] == "S"} { if {[ATOM/GET ELEMENT $atom2] == "S"} { if { $atom1 > $atom2 } { set distance [ATOM/GET DISTANCE $atom1 $atom2] puts $distance } } } } }

Use the following commands to build a structure for testing this script. You can either copy these lines into a file called build.log or cut and paste them directly into the Cerius² textport.

SKETCHER/TEMPLATE_FILE "./Cerius2-Models/combichem/amino-acids/cys.msi" SKETCHER/ADD_TEMPLATE AT 5.310 7.917 -3.723 SKETCHER/ADD_TEMPLATE AT 4.234 6.273 -2.961 SKETCHER/ADD_TEMPLATE AT 3.247 4.632 -2.238 SKETCHER/ADD_TEMPLATE AT 2.034 2.643 -1.353 SKETCHER/CHANGE_BOND ATOMS Atom(19) Atom(1) SKETCHER/CHANGE_BOND ATOMS Atom(32) Atom(14) SKETCHER/CHANGE_BOND ATOMS Atom(45) Atom(27) SKETCHER/HYDROGEN_FILL ALL SKETCHER/ONE_SHOT_CLEAN YES SKETCHER/CLEAN START

Tcl control structures are used to loop over all the atoms in the system and compare atom types. Cerius² commands are used to retrieve data from the data model. Cerius² commands generally obey the syntax APPLICATION/COMMAND_NAME ARGUMENTS and can as such be executed from the Cerius² command line.

MODEL/GET ATOMS retrieves all the atom names in the current model and assigns them to a variable atom1. This reference name can then be used to retrieve atomic properties such as the element type or manipulate the atom using Cerius² commands. In this case, a Cerius² command is used to calculate the distance between the two atoms, and print that to the text port. Alternatively, one can, for instance, CPK a particular atom using:

SELECT/ATOM RESTART $atom VIEW/ATOM_STYLE BALL

The selected atoms determine the application range of the selected command. This is the same way this would be done in the Cerius² interface.

If you are not sure what the syntax is for a particular Cerius2 command, there is a very quick way of finding out: within Cerius2, switch on the Command Tracing option in Utilities/Command Tracing. Every command that you from now on execute, will be echoed to the textport. For example, select an atom and switch to ball representation. The textport will echo the following two commands:

SELECT/ATOM RESTART Atom(1) VIEW/ATOM_STYLE BALL

You can cut andd paste these commands straight into a C2.Tcl script! This is actually the recommended way of using C2 commands in a script. It is much easier than looking up commands in reference manuals, while it is immediately clear what the effect is of a particular command.

One more tip: don't forget to switch command tracing of when you are done. Especially when you are using macro's, the amount of output to the textport can be quite overwhelming

Back to our first example. Although it works fine for small systems, the algorithm that is used is not efficient enough to deal with large systems such as proteins that typically consist of 1000+ atoms. For a system such as DHFR, with 1294 atoms, finding all the sulphur pairs this way takes more than 20 minutes! With a few changes, however, you can make the script much more efficient. The algorithm currently uses a double loop over all the atoms. In principle, however, it need only loop over all the atoms once to find the sulphur atoms, then loop over that smaller list to calculate the distances between all the pairs. We can make use of powerful data structures in Tcl to store intermediate information such as the atom names.

# Generate a list of sulphur atoms set i 0 foreach atom [MODEL/GET ATOMS] { if {[ATOM/GET ELEMENT $atom] == "S"} { set "satoms($i)" $atom incr i } } set natoms $i # Display the distances between all pairs of sulphur atoms for {set i 0} {$i<$natoms} {incr i} { for {set j [expr $i + 1]} {$j<$natoms} {incr j} { EVALUATE/DISTANCE ATOMS $satoms($i) $satoms($j) SELECT/ATOM RESTART $satoms($i) SELECT/ATOM TOGGLE $satoms($j) VIEW/ATOM_STYLE BALL SELECT/DESELECT }} puts "Done"

With this algorithm it takes only some 10 seconds to calculate all sulphur-sulphur distances in a medium sized protein. To test this out, download and use the following protein structure. Note that you can also execute this script by selecting all the lines in the script with the mouse and copying it into the textport. This is sometimes convenient when your are testing a new script.

There are, of course, instances in which scripts such as these are still too slow to be of practical use. The best solution then is to write an SDK application to accomplish the task. SDK applications consist of real code, and are equivalent in terms of structure, speed and flexibility to native Cerius² applications. For a demonstration, see the Distance Check application example.

[1] J.K. Ousterhout, Tcl and the Tk Toolkit, Addison-Wesley, Reading (1994).