Customizing EXPGUI and Associated Programs

The EXPGUI GSAS graphical user interface can be modified in many ways quite easily. This document describes how the GUI works and how to modify the menus without significant reprogramming.


The main GUI is created by file expgui, which in turn uses the following files sequentially: Two additional files are read if they are found:

The first three files, (readexp.tcl, gsascmds.tcl, gsasmenu.tcl) must be located in the same directory where the expgui file is found. The localconfig file also is read from this directory, if it exists. The final file, .gsas_config, is read from the user's login directory (UNIX) or C:\ (Windows). No error occurs if either localconfig or .gsas_config is not present.

The readexp.tcl and gsascmds.tcl files contain tcl procedures that are used for more than one application, so it is convenient to place them in separate files. They are only of interest to someone trying to debug or add new functionality to expgui.

The gsasmenu.tcl file defines the contents of the menu bar, the contents of the button bar and definitions for each command. The contents of this file are designed to be modified and extended by users, either by editing the file, or by overridding definitions in the localconfig or .gsas_config files. The variables in the gsasmenu.tcl are:

This list defines the menu bar headings other than File, Options & Help
Each array element, e.g. expgui_menulist(file) and expgui_menulist(powder), defines commands to be added to a menu heading. Each command will appear as an array element in expgui_cmdlist.
Each array element, e.g. expgui_cmdlist(Save) or expgui_cmdlist(expnam) contains two items. The first defines a tcl procedure to be executed when the command is invoked, or "-" if no command will be invoked and the second contains help information describing what the command does. Note that when menu item is selected the variable cmd is set to the name of the command, so
    expgui_cmdlist(powpref) {{runGSASwEXP $cmd} {Powder data preparation}}
means that "runGSASwEXP powpref" will be invoked when powpref is invoked. . For example, when powpref is selected, the tcl command "runGSASwEXP $cmd" is invoked, where variable cmd is set to "powpref".
This list defines the commands that will appear on the button bar where each item that appears on the button bar must have a matching pair of entries in expgui_cmdlist. Thus if the command
   set expgui(buttonlist) {expnam expedt genles ortep fourier forsrh forplot lstview}
is placed in the localconfig or .gsas_config files this will redefine the contents of the button bar.
In addition to the variables defined in the previous file, expgui, uses a small number of array for other configuration options. They are:
set expgui(coordfont) "-*-courier-bold-r-normal--12-*" set expgui(histfont) "-*-courier-bold-r-normal--12-*" set liveplot(hst) 1 set liveplot(legend) 1 set expgui(filesort) 1 set expgui(scriptdir) [file dirname $expgui(script) ] set expgui(gsasdir) [file dirname $expgui(scriptdir)] set expgui(gsasexe) [file join $expgui(gsasdir) exe] set expgui(asorttype) $expgui(asorttype)" set expgui(hsorttype) $expgui(hsorttype)" set expgui(filesort) $expgui(filesort)" set env(GSASBACKSPACE) $env(GSASBACKSPACE)" This determines where files menulist, cmdlist, helplist and buttonlist, as well as widplt and lstview are located. Rarely needs to be changed.
  • gsasexe: This determines where the GSAS executable files are located. You might want to change this is you keep multiple versions of GSAS around or if you keep the GSAS files in a different location than the default or want to keep the tcl files somewhere other than in a subdirectory of the GSAS files.
  • env(GSASEXE): This sets an environment variable which is probably not used.
  • env(ATOMDATA): This sets an environment variable which defines the location of a data file (.../gsas/data/atomdata.dat) needed by EXPEDT and probably other programs.
  • env(ATMXSECT): This sets an environment variable which defines the location of a data file (.../gsas/data/atmxsect.dat) needed by program FPRIME.
  • env(LENPAGE): This sets an environment variable which defines the number of lines per page used in the .LST file. You may want to change this to match your favorite print format to save paper.
  • env(PGPLOT_DIR): This sets an environment variable needed by the PGPLOT graphics library.
  • env(GSASBACKSPACE): This determines if the default definition for the backspace key is overridden; some UNIX systems need this so that expedt and other terminal-oriented programs work correctly and other systems do not. You can toggle this option using the "sets an environment variable needed by the "Override Backspace" option on the file menu. To set the variable to default as "off" use
            setenv GSASBACKSPACE 0
    in your ~/.cshrc file or include
            set env(GSASBACKSPACE) 0
    in your ~/.gsas_config or localconfig file.
  • archive: This defines the default state for the archive flag, where 0 is off and 1 is on. When archive is on, a copy of the .EXP file is saved as .EXP.nnn and compressed before EXPEDT is run.
  • compressprog: This defines a compression program used to reduce the size of archived .EXP files.
  • debug: Setting debug to 1 turns on a number of annoying warning messages.
  • lstview

    The following options are available for customization
    • txtvw(followcycle): This sets the initial value for the "Auto Advance" button in the "Go To" menu. When this is true, the program will show the last cycle in the file. As new cycles are added, the "view" is advanced.
    • txtvw(menulength): This limits the number of entries that can exist in a menu. For example, the default is 25, so when more than 25 cycles are found in a .LST file, only the last 25 are listed in the "Go To"/cycle submenu.
    • txtvw(maxchars): This limits the maximum number of characters that will be read from an existing .LST file to speed the start of the program. The default for txtvw(maxchars) is ~1Mb for UNIX systems and ~200K for Windows.
    One additional variable is present that I don't suggest using:
    • plotvars: I am in the process of developing code that tracks and plots shifts and R values as a function cycle number. Setting plotvars to 1 allows this code to be tested.


    This program can be customized by overriding definitions for the following variables in file ~/.liveplotrc.
    • graph(printout): This is set to 1 if PostScript files will be printed and 0 if they will be written to disk.
    • graph(outname): This is the default for the file name used when PostScript files will be written to disk.
    • graph(outcmd): This is the default for the command used to print PostScript files.
    • peakinfo(colorn): These variables define the default colors for reflections in phase "n"

    If you have CMPR installed on your computer, you can use superimpose on liveplot the peaks for an arbitrary unit cell with space group extinctions show, if desired. This is pretty neat! To enable this feature, you must have a version of the GSAS GUI routines downloaded after 4 May 1998 and have installed a version of CMPR downloaded after 4 May 1998 (see the CMPR installation instructions.) Then create a link from in the GSAS GUI directory to file cellgen.tcl in the CMPR directory. For example:

             ln -s /usr/local/cmpr/cellgen.tcl /usr/local/gsas/tcl/cellgen.tcl 

    If you have LOGIC installed on your computer, you can use superimpose peaks for a entry from the ICDD/JCPDS database on a pattern in LIVEPLOT. This is also pretty neat! To enable this feature, you must have a version of the GSAS GUI routines downloaded after 4 May 1998 and have installed a version of LOGIC downloaded after 4 May 1998 (see the LOGIC installation instructions.) Then create a link from in the GSAS GUI directory to file icddcmd.tcl in the LOGIC directory. For example:

             ln -s /usr/local/powdersuite/icddcmd.tcl /usr/local/gsas/tcl/icddcmd.tcl 


    The widplt script is used to display the FWHM for one or more histograms from a .EXP file. It is often convenient to add for reference the expected instrumental curves as options to the menu. This can be done by creating a file called widplot_name. For example, renaming the example_widplt_BT1 file supplied with the distribution to widplt_BT1 will cause the FWHM curves for the NIST BT-1 instrument to be added to the menu of defined FWHM values.

    Creating such a file is easy. To add a entry define the following five array elements using a single, unique element name and then append that element name to variable datalist. Define

        set UVWP(Ge15) {398.5 -343.2  163.0 0}
        set XY(Ge15) {0 0}
        set wave(Ge15) 2.0775
        set lblarr(Ge15) "BT-1 Ge(311) 15'"
        set ttrange(Ge15) "5 160"
        lappend datalist Ge15 
    Array element UVWP(item) contains the (Gaussian) GU, GV, GW and GP values, while XY(item) contains the (Lorentzian) LX and Ly terms. Array element wave(item) contains a wavelength, array element lblarr(item) contains the text to be shown on the "Plot Contents" menu and ttrange(item) defines the range the function is valid.

    Note that this script will probably need some work to be used with TOF diffraction.

    GSAS is written by: Allen C. Larson and Robert B. Von Dreele MS-H805, Los Alamos National Laboratory, Los Alamos, NM 87545. Problems, questions or kudos concerning GSAS should be sent to Robert B. Von Dreele at

    The GUI is written by Brian H. Toby of the NIST Center for Neutron Research, Brian.Toby@NIST.GOV.

    GSAS is Copyright, 1984-1997, The Regents of the University of California. The GSAS software was produced under a U.S. Government contract (W-7405-ENG-36) by the Los Alamos National Laboratory, which is operated by the University of California for the U.S. Department of Energy. The U.S. Government is licensed to use, reproduce, and distribute this software. Permission is granted to the public to copy and use this software without charge, provided that this notice and any statement of authorship are reproduced on all copies. Neither the Government nor the University makes any warranty, express or implied, or assumes any liability or responsibility for the use of this software.

    The GUI is not subject to copyright. Have fun.

    Brian Toby (Brian.Toby@NIST.GOV)
    $Revision: 36 $ $Date: 2009-12-04 22:59:18 +0000 (Fri, 04 Dec 2009) $