Table of Contents
What is scripting     The "scripting::" scripts     The XCrySDen generated scripts         How to plot many molecular orbitals

What is scripting

In some circumstances it would be desirable to perform particular tasks in some automatic way without any user interactivity. In such a case the executive operations are encapsulated inside a script. Typical use of scripting is when several similar jobs have to be performed, such as, for example, plotting all the valence molecular orbitals (MO) of a give molecule. Typically in all MO plots one would like to keep the same display parameters. It would really be cumbersome and a pure waste of time to perform, for example, 15 alike jobs interactively. In such cases scripts would be much more convenient as all operations would then be performed in automatic way. XCrySDen have specially designed programming scripting interface for achieving above mentioned goal. XCrySDen scripts use the Tcl syntax. Technically speaking XCrySDen scripts are Tcl scripts. The specially designed scripting functions use the scripting:: namespace. However one can use any XCrySDen Tcl function in such scripts. XCrySDen scripts can be either loaded from command line as xcrysden -s scriptFile or xcrysden --script scriptFile, or alternatively from menu File-->Open Structure ...-->Open XCrySDen Scripting File .

The "scripting::" scripts

In scripts that were manually written the scripting:: functions most likely represent the majority of the commands. Here you can found documentation about the scripting:: interface, together with hypertext examples. The documentation was automatically generated from the source code. The easiest way to learn "how to write" such scripts is to start with examples. The basic knowledge of Tcl-syntax is welcome here. The examples are well documented, and since they are written in hypertext manner, they have hypertext references to all used functions.

• Scripting interface documentation
• Scripting examples

XCrySDen distribution contains several scripting examples. See the $XCRYSDEN_TOPDIR/examples/Scripting/ directory. They can be also accessed using the File-->XCrySDen Examples ...-->Scripting Files menu. Here is a list and short description of several scripting examples:

animation.tcl	-- a simple example for animating a molecular structure
atomic_labels.tcl	-- shows how to edit atomic labels
build_crystal.tcl	-- animates and builds a crystal structure
colorplane_animation.tcl	-- a simple example for animating a contour plots
contours.tcl	-- plots contours+colorplane from XSF file
g98cube.tcl	-- a simple example for display of MO from Gaussian cube file
isosurface+colorplane+print.tcl	-- plots and prints isosurface and contours
movie.tcl	-- a simple example for making a MPEG movie
multiScript.tcl	-- a simple example of multi-job script

The XCrySDen generated scripts

There exists another type of XCrySDen scripts. This type of files is created by XCrySDen via either File-->Save Current State or File-->Save Current State and Structure menus. The default file-extension of these files is *.xcrysden. Such a script contains the structure and the majority of the display parameters. When the script are loaded (i.e. as xcrysden -s script) the structure is displayed in the same way as it was saved, i.e., having the same orientation, zoom, colors, and other display parameters. These scripts do not use the scripting:: interface, hence they are messy although somewhat documented.

It is possible to use part of these scripts together with the manually created scripts. A typical use would be: display a structure and set proper display parameters. Save with File-->Save Current State . Then use this saved script inside the manually created scripting:: script.

Here is an example of *.xcrysden script.
 

How to plot many molecular orbitals

With XCrySDen scripting capability, it is easy to plot many molecular orbitals automatically with the same display settings for all the orbitals. Here is the recipe:

1. calculate the orbitals and save them into, say, mo-*.xsf files
2. load a given orbital, e.g, xcrysden --xsf mo-1.xsf and produce a desired display
3. save display settings via File-->Save Current State, say, into state.xcrysden
4. execute the following shell script:

    for xsf in mo-*.xsf; do
       xcrysden --xsf $xsf --script state.xcrysden --print ${xsf%.xsf}.png
    done