EXPGUI

• readexp.tcl
• gsascmds.tcl
• gsasmenu.tcl

• localconfig
• .gsas_config

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). The localconfig and .gsas_config are intended to contain system-wide and user-level default values for parameters that are described in this document. Most routines have a "Save Options" command that writes some of the current parameters to file .gsas_config. Note that information in .gsas_config overrides that in localconfig. No error occurs if either of these files are not found.

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 overriding definitions in the localconfig or .gsas_config files. The important variables defined in the gsasmenu.tcl file are:

expgui(menunames)

This list defines the menu bar headings other than File, Options & Help

expgui_menulist

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.

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

expgui(buttonlist)

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.

expgui(scriptdir)

This determines where files such as readexp.tcl, etc. are located. This defaults to the location where expgui is located so it rarely needs to be changed.

expgui(gsasdir)

This contains the location of the GSAS directory, if it is not the parent director where expgui is found. This determines where a number of GSAS data files will be located. If expedt crashes when you try to add new atoms, this is probably wrong.

expgui(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.

expgui(coordfont)

Sets the font used for the coordinates scroll box

expgui(histfont)

Sets the font used for the histogram scroll box

liveplot(hst)

Sets the default histogram used for liveplot

liveplot(legend)

Sets the default value for display of the legend in liveplot

expgui(initstring)

Defines commands to be executed by EXPGUI after all other commands have been run. This is used to define initialization commands in the localconfig or .gsas_config files that cannot be run at the time when the files are sourced. (added in EXPGUI v1.21)

expgui(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 before a new version of the file is saved and before EXPEDT is run.

expgui(asorttype)

This determines the atom sort mode.

expgui(hsorttype)

This determines the histogram sort mode.

expgui(filesort)

This determines the default file sorting mode for the expnam command.

env(GSASBACKSPACE)

Used only for UNIX: 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 "Override Backspace" option on the file menu to see what works for you.

LSTVIEW

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 is ~1Mb for UNIX systems and ~200K for Windows.

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(font)

This sets the font used for LSTVIEW. See documentation on the font command in Tk for details on font naming.

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

LIVEPLOT

The following options are available for customization in these files:

peakinfo(flagn)

These variables define if peak positions will be shown for reflections in phase "n". Reflections will be shown if the value is non-zero.

peakinfo(colorn)

These variables define the default colors for reflections in phase "n"

peakinfo(dashesn)

These variables define if peaks will be dashed for reflections in phase "n" (UNIX only). Lines will be dashed if the value is non-zero.

peakinfo(minn) and peakinfo(maxn)

These variables dictate the placement vertical position for reflection markers, when manually placed (see expgui(autotick), below). To draw to the edge of the screen, use -Inf and Inf.

graph(printout)

This is set to 1 if PostScript files will be printed and 0 if they will be written to disk (for Windows all files should 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 (Unix only).

graph(legend)

Sets the default value for display of the legend in liveplot and widplt.

peakinfo(obssym)

Symbol for observed data points. Valid choices are square, circle, diamond, plus, cross, splus and scross.

peakinfo(obssize)

Size for the symbol for observed data points. A value of 1 corresponds to about 1/8 inch (about 3 mm).

expgui(pixelregion)

When hkl values are loaded (using tcldump) and reflections are labeled, reflections can be labeled using a Shift-Left-Mouse click. All labeled reflections within expgui(pixelregion) pixels of the mouse position are assumed to be overlapped and are labeled.

expgui(fadetime)

The time in seconds before reflection labels are removed. A value of zero means that reflections must be deleted manually (Shift-Right-Mouse).

expgui(lblfontsize)

A size for reflections labels in pixels.

expgui(hklbox)

If this variable is non-zero, reflection indices are shown in a box.

expgui(autotick)

If this variable is non-zero, reflection markers positions are set automatically.

Using TCLDUMP with LIVEPLOT. LIVEPLOT works with the standard GSAS program HSTDMP, but it works faster and is more powerful when used with the TCLDUMP program. Instructions for downloading this file can be found in the installation notes for Windows and UNIX. Note that as of the April 2000 releases, GSAS is now distributed with TCLDUMP.

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

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

Combining LOGIC and LIVEPLOT If you have LOGIC installed on your computer, you can 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 LOGIC downloaded after 4 May 1998 (see the LOGIC installation instructions.) For UNIX, 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 

WIDPLT

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 

The following variables are written to .gsas_config when "Save Options" is used. These variables are all set from the GUI and therefore do not need to be edited manually.

graph(printout)

This is set to 1 if PostScript files will be printed and 0 if they will be written to disk (for Windows all files should 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 (Unix only).

graph(legend)

Sets the default value for display of the legend in liveplot and widplt.

graph(plotunits)

Sets the units used for displaying the data. Values are "d", "q", "", for d-space, Q and 2-theta, respectively.

graph(equivwave)

Sets the wavelength used for displaying data, if blank, no conversion is done and data are shown in their original wavelength.

The code below can be used to define a new command, leBail. The first command adds a command to the button bar and the second one defines what will be done when it is invoked (the number of cycles is set to zero and GENLES is run three times). It also defines the help entry. Note that commands must start with a lower case letter even though Armel LeBail's last name does not.

    lappend expgui(buttonlist) leBail
    set expgui_cmdlist(leBail) {
	{set entryvar(cycles) 0; runGSASwEXP "genles genles genles"}
	{Converges GENLES with LeBail extractions; 
	  Sets the number of cycles to zero and runs GENLES 3 times.}
    }

Customizing Example 2: Putting DISAGL Results in a Separate Box

  set expgui(disaglSeparateBox) 1
  set expgui_cmdlist(disagl) {rundisagl {Hacked Distance/angle calculations}}
  proc rundisagl {} {
    global expgui txtvw tcl_version tcl_platform
    if {$expgui(disaglSeparateBox) && $tcl_platform(platform) != "windows"} {
	set root [file root $expgui(expfile)] 
	catch {file rename $root.LST $root.OLS}
	runGSASwEXP disagl
	catch {file rename $root.LST $root.DIS}
	catch {file rename $root.OLS $root.LST}

	# open a new window
	catch {toplevel .disagl}
	catch {eval grid forget [grid slaves .disagl]}
	text .disagl.txt -width 100 -wrap none \
		-yscrollcommand ".disagl.yscroll set" \
		-xscrollcommand ".disagl.xscroll set" 
	if {$tcl_version >= 8.0} {.disagl.txt config -font $txtvw(font)}
	scrollbar .disagl.yscroll -command ".disagl.txt yview"
	scrollbar .disagl.xscroll -command ".disagl.txt xview" -orient horizontal
	grid .disagl.xscroll -column 0 -row 2 -sticky ew
	grid .disagl.txt -column 0 -row 1 -sticky nsew
	grid .disagl.yscroll -column 1 -row 1 -sticky ns
	grid columnconfigure .disagl 0 -weight 1
	grid rowconfigure .disagl 1 -weight 1
	wm title .disagl "DISAGL results $expgui(expfile)"
	wm iconname .disagl "DISAGL $root"
	set in [open $root.DIS r]
	.disagl.txt insert end [read $in]
	close $in
	bind all  {destroy .disagl}
	bind .disagl  ".disagl.txt yview scroll -1 page"
	bind .disagl  ".disagl.txt yview scroll 1 page"
	bind .disagl  ".disagl.txt xview scroll 1 unit"
	bind .disagl  ".disagl.txt xview scroll -1 unit"
	bind .disagl  ".disagl.txt yview scroll -1 unit"
	bind .disagl  ".disagl.txt yview scroll 1 unit"
	bind .disagl  ".disagl.txt yview 0"
	bind .disagl  ".disagl.txt yview end"
	# don't disable in Win as this prevents the highlighting of selected text
	if {$tcl_platform(platform) != "windows"} {
	    .disagl.txt config -state disabled
	}
    } else {
	runGSASwEXP disagl
    }
  }

if {$tcl_platform(platform) != "windows"} {
  append expgui(initstring) {
      $expgui(fm).option.menu add checkbutton  -label "DISAGL window" \
	      -variable expgui(disaglSeparateBox) -underline 0;
  }
} 

Note that the expgui(initstring) option became available in EXPGUI version 1.21. (Previous versions will ignore this). This code must be executed after all the menus and other GUI code has been run. When executed, it creates a checkbutton on the Options menu to turn the "separate DISAGL window mode" mode on and off.

Customizing Example 3: Adding a new page to EXPGUI

1. Create a routine to read and write the appropriate records from the .EXP file. In this case, a new routine, constrinfo, was added to file readexp.tcl. This takes considerable care and manual testing.
2. Create a routine that places the appropriate widgets into a frame (in this case MakeAtomsConstraintsPane). This routine will be called only once. Note that in this example expcons(atommaster) is defined to be the name of the frame.
3. Create a routine to display and edit the information shown in the frame. In this case, DisplayAtomConstraints. This routine will be called each time the page is displayed. Note that this routine and the previous can be tested in a separate toplevel until they work well.
4. In this particular example, the previous frame is located on a notebook widget that in turn placed on a notebook page, so MakeConstraintsPane is used to create this inner notebook when the "Constraints" notebook page is first shown. This in turn calls MakeAtomsConstraintsPane and DisplayAtomConstraints. To update this page each time it is displayed, DisplayConstraintsPane is called.
5. Edit file expgui to make the following changes:

   • load the atomcons.tcl file:

     # commands for constraints
     source [file join $expgui(scriptdir) atomcons.tcl]
     

   • Define a notebook page for the option. The -createcmd option is used only once, but the -raisecmd option is used every time the page is exposed.

     set expgui(consFrame) [\
     	    .n insert end consPane -text Constraints \
     	    -raisecmd "set expgui(pagenow) consFrame; DisplayConstraintsPane"\
     	    -createcmd MakeConstraintsPane]
     lappend expgui(frameactionlist) "consFrame DisplayConstraintsPane"
     

     Note that if we were displaying the atoms constraint page directly on the main notebook widget, the previous command would have been -raisecmd DisplayAtomConstraints -createcmd MakeAtomsConstraintsPane

     Since the frame will need to be updated when information in the .EXP file changes, the name of the frame and a command to execute are added into list expgui(frameactionlist) using the lappend expgui(frameactionlist) command.

This 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: 144 $ $Date: 2009-12-04 23:01:08 +0000 (Fri, 04 Dec 2009) $