TCL Scripting Basics

Lauren Lerew1 and Darrin M. York1
1Laboratory for Biomolecular Simulation Research, Institute for Quantitative Biomedicine and Department of Chemistry and Chemical Biology, Rutgers University, Piscataway, NJ 08854, USA

Learning Objectives

  • Understand the basics of Tcl scripting language

Tutorial

What is Tcl in VMD?

VMD uses the string-based command language Tcl. It is meant to be simple so that users can easily write scripts to automate tasks in VMD. Anything that can be done from the menus in VMD can also be done using Tcl commands.

Using Tcl in the VMD TK Console

Users can interactively enter Tcl commands in the VMD TK Console, create Tcl script files that can be loaded into VMD during the VMD session via the terminal, or modify the vmd.rc file to automatically run specific Tcl commands at VMD startup, such as turning menus on or off, setting specific visualization options, or adding personalized keyboard shortcuts.

The basic syntax for a Tcl command is:

command arg1 arg2 arg3

The core commands utilized in VMD can be seen in Figure 1. Please refer to the VMD User’s Guide for a complete list of commands and their functionalities.

set variable value   ;# sets the value of the variable
puts $variable       ;# prints out the value of the variable

Brackets can be used to embed Tcl commands into others. If an expression is inside the brackets, it will automatically be substituted by the return value of the command. For example:

set result [ expr -3 * 10 ]
puts $result

Warning

Replace this block once image is available.

.. image:: _static/tcl_text_commands.png
   :alt: List of Core Text Commands in VMD. Screenshot taken from the VMD User’s Guide, “Tcl Scripting”, University of Illinois Urbana-Champaign.
   :align: center
   :width: 400px

The contents of this tutorial will focus on Tcl commands within the TK console.

If you are already in a VMD session, navigate to the TK Console by going to Extensions -> TK Console. You can enter Tcl commands directly into the console and see the results immediately.

Atom Selections

The basic syntax of atom selections is created using the atomselect command:

atomselect molid selection  ;# creates a new atom selection

  • molid is the first argument and it is the molecule ID, which is shown to the very left of the VMD main window.

  • top refers to the currently active molecule.

  • "selection text" is a selection string that specifies which atoms to select.

  • sel is a variable that stores the atom selection.

Atoms can be selected based on various criteria, such as atom name, residue name, chain ID, etc. For example, to select all carbon atoms in a molecule:

set sel [atomselect top "name C"]

Other simple selections:

set protein [atomselect top "protein"]
set resid10 [atomselect top "resid 10"]

Moving Atoms

Often times, you may want to move atoms in your selection. This can be done using the moveby command:

$sel moveby {x y z}

x, y, and z are the distances to move the atoms in the respective directions. For example, to move the selected atoms 1 angstrom in the x direction.

Measuring distances

# (Add content here if needed)

Calculating RMSD

# (Add content here if needed)

Simple Visualization Example

# (Add content here if needed)

Writing a VMD TCL Script

Basic Script Structure

# (Add content here if needed)

Running a TCL Script in VMD

Method 1 - From the Terminal

  • Open your terminal

  • Navigate to the directory containing your script

  • Type: vmd -e your_script_name.tcl. The -e command line flag tells VMD to execute the script upon startup.

Method 2 - From the VMD TK Console

  • Open TK Console

  • Type: source your_script_name.tcl

  • Press Enter

Anything that can be done in VMD using the graphical user interface can also be done using TCL scripts. This tutorial introduces the basics of TCL scripting in VMD, including how to write and execute scripts, use variables and control structures, and interact with VMD’s built-in commands and functions.

Using a Script to Load a Molecule