TCL Scripting Basics
====================

| Lauren Lerew\ :sup:`1` and Darrin M. York\ :sup:`1`
| :sup:`1`\ Laboratory 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

.. start-learning-objectives
.. end-learning-objectives

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:

.. code-block:: tcl

   command arg1 arg2 arg3

The core commands utilized in VMD can be seen in Figure 1. Please refer to the `VMD User's Guide <https://www.ks.uiuc.edu/Research/vmd/>`_ for a complete list of commands and their functionalities.

.. code-block:: tcl

   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:

.. code-block:: tcl

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


.. warning::

   Replace this block once image is available.

     
   .. code-block:: rst

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

.. code-block:: tcl

   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:

.. code-block:: tcl

   set sel [atomselect top "name C"]

Other simple selections:

.. code-block:: tcl

   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:

.. code-block:: tcl

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

.. contents::
   :local:
   :depth: 4

.. start-tutorial

Using a Script to Load a Molecule

.. end-tutorial