A Graphical User Interface for
Note that version 1.41 or later of EXPGUI should be used with the April 2001
releases of GSAS on all platforms (Version 1.41 is currently the alpha
release version), due to changes in file formats and locations.
The "stable" release should be used
with older versions of GSAS.
EXPGUI is a graphical interface for the
EXPGUI does two things:
it can be used to directly modify the GSAS
experiment file with a graphical user interface (GUI) and
it can be used to invoke the programs inside the
GSAS package such as EXPEDT, GENLES, FOURIER...
These programs can be run from a menu or in many cases by pressing buttons.
EXPGUI is written using the
Tcl/Tk scripting language.
This web page describes the different actions that
can be accomplished with the different panes and the
contents of the menus. The table below contains links to the other
web accessible documentation.
The appropriate citations to be used for GSAS and EXPGUI are:
If you would like to get news about about new features
& bug fixes in EXPGUI and also support
the project by demonstrating how many people use it,
please send e-mail to
A. Experiment file editing
When an experiment (.EXP) file is read, a copy is made in local
computer memory. In most cases, values are changed in this
"in memory" copy of the experiment file
as this information is changed by the user on the screen.
If there is an error in the typed value, (for example if "1..0" is typed, or
"1.5" is typed where an integer is expected), these values are
not saved. In this case, the text is turned red, to indicate
that an error is present, as shown in the figure to the left, where "90.000x"
has been entered for alpha.
The edited version of the experiment file is written back out to
disk when the "File/Save" or "File/Save as"
menu bar options
are used. The File/Save operation is done automatically before any GSAS
programs, such as GENLES or EXPEDT, are run.
Since the GSAS experiment file is quite complex,
values are grouped together by function, approximately
following the outline of the EXPEDT program.
Each set of values is given a
"tabbed pane" on a window that has the appearance of a notebook (see below).
The notebook pane tabs.
In some cases, where values are
too numerous or complex to fit onto the notebook pane, one or more buttons
may be present on a pane that will create a separate window,
where the associated values can be modified.
These values are not recorded in the
"in memory" copy of the experiment file unless the "Save" button on this window
is pressed. If "Cancel" is pressed, no changes are made.
Each notebook pane is listed below with a link to the web page documenting
A.1 Least Squares (LS) Controls Pane
A.2 Phase Pane
A.3 Histogram pane
A.4 Scaling pane
A.5 Profile pane
A.6 Constraints pane
A.7 Preferential Orientation Pane
B.1 Multiple Histogram Selection
This mode allows parameters to be changed for groups of
When the "Multiple Histogram Selection" mode is off,
it is possible to modify parameters
and refinement flags for only a single histogram, but
the other settings allow groups of histograms
to be selected and modified.
(see Mouse Actions).
It does not make sense, however, to globally modify
instrument-related parameters and flags for different
So global actions can be limited to a single class
of histogram types (e.g. TOF, CW Neutron,...), which
allows these parameters to be set for groups of
similar histograms. Thus, if this mode is set to "All"
the Histogram and Profile panes are disabled.
The setting for "Multiple Histogram Selection" mode is
displayed above each histogram selection box and is
selected using the "Multiple Hist. Selection" item on the
Options menu to create a submenu or by clicking on the display.
Note that another option in this "Multiple Hist. Selection"
submenu is an option "Group Phases Together" that controls how
EXPGUI treats phases having
the same profile type that is used when multiple histograms are selected. If
the "Group Phases Together" option is on, then the refinement flags for
all phases with the same histogram types are grouped together, when possible.
If this option is off, phases are treated separately.
If the left mouse button is used to click on the selection mode display,
the mode is cycled between the available modes. If the right mouse
button is used, the mode is reset, to disable multiple histogram selection.
B.2 Mouse Actions
A range of atoms or (in multiple selection mode) histograms may be
selected by dragging (holding down) the left mouse button. It is also
possible to select a range by using the Shift key with the left mouse
button. To select or deselect individual entries, use the Control key
with the left mouse button. Pressing the right mouse button selects all
entries in a list.
C. Menu Commands and Programs
GSAS programs are invoked either through use of the menu bar
The menu bar.
or by "pressing" a button on the button bar. The button bar
simply provides an easy way to access commonly used
actions on the menu bar. Users can
configure the menu bar to include their own preferred actions and, with
some knowledge of the program and Tcl/Tk,
add their own commands to the menu bar or button bar.
The button bar.
Invoking of GSAS programs
When GSAS programs are invoked, in most cases EXPGUI is suspended while
the GSAS program is run in a terminal (or DOS) window. When the terminal
window is closed, EXPGUI is restarted. If desired (see the
"Iconify during GSAS"
option) while this occurs, EXPGUI can be made into an icon
to save screen space.
Once the GSAS program has finished, if the program has modified
the .EXP file,
"File has been modified..."message box
similar to the one to the left is displayed (also see the more complete
discussion on the messages page.
Note that this message can be avoided if the
option is used.
Note that in both Windows-95 and Windows-NT, a file named EXPGUI.LCK
is created while the GSAS program runs. The presence of this file is used
to suspend the LIVEPLOT program, since LIVEPLOT has sometimes crashed
when run at the same time as GENLES (no such problem has been seen in Unix).
This file is deleted when the GSAS program completes.
In Windows-9x, the Winexec
package is used to execute a command that creates a DOS window.
The GSAS programs are then run by a batch file in this DOS window.
Due to limitations in Tcl/Tk & Windows, the DOS window runs independently
of EXPGUI, so the lock file (EXPGUI.LCK) is also used to suspend
EXPGUI. While EXPGUI is waiting, the
window shown to the left is displayed. When the GSAS program completes, the
lock file is deleted, the window automatically disappears and EXPGUI resumes.
Should a problem arise where the file is not deleted, EXPGUI can be resumed by
pressing the "Continue" button.
A description of the EXPGUI menus follows. Use the links to obtain
more information, including a very
brief description of the function of each menu option.
Note that an option may appear under more than one menu.
C.1 File Menu
The options on the File menu as is the custom contains the commands
for reading and writing experiment files, as well as starting
and ending the program.
C.2 Options Menu
This menu contains options that determine how EXPGUI runs.
C.3 Powder Menu
This menu contains links to GSAS programs used for powder diffraction
C.4 Single Crystal Menu
This menu contains links to GSAS programs used for
single-crystal diffraction analysis.
C.5 Graphics Menu
This menu contains links to several GSAS and
two non-GSAS (LIVEPLOT and WIDPLT)
programs used for graphical display of data and results.
C.6 Results Menu
This menu contains links to several GSAS and
one non-GSAS (LSTVIEW)
programs used for analysis of results.
C.7 Calculations Menu
This menu contains programs for useful crystallographic computations.
C.8 Import/Export Menu
This menu contains utilities for importing information into GSAS and
D. EXPGUI Utility Programs
LSTVIEW is used to browse through the GSAS output listing. It is
invoked by the "lstview" command in the GUI.
LIVEPLOT shows the observed, calculated and difference plots for powder
refinements. The plot is updated as the refinement progresses. The mouse can
be used to zoom in on sections of the plot.
LIVEPLOT uses the BLT graphics package.
LIVEPLOT can now be enhanced to superimpose peak locations for
input unit cells or peaks from JCPDS/ICDD entries.
LIVEPLOT customization information
or read file expgui_cfg.html in the gsas/tcl/doc directory.
WIDPLT can be used to plot the actual peak widths generated by the profile
parameters used in GSAS.
It is possible to define reference curves
that are loaded automatically.
WIDPLT uses the BLT graphics package.
D.4 File Conversions
GSAS data, experiment and instrument parameter files are
expected to have a format with exactly 80 characters per line followed
by a carriage return and then a linefeed (82 characters total per line).
Files in this format can be read in "Direct Access" mode.
Recent versions of GSAS will attempt to detect and repair files that
are not in this format, but if the file is incorrectly formatted and
by chance the length of the file is divisible by 82, the problem in the
file format will not be detected.
The Convert menu
in can be used to convert files into the correct format.
The original version of the
file is retained and renamed.
D.5 Compute Composition
The composition box shows the unit cell and asymmetric unit composition
for all phases in a material. Site multiplicities and occupancies are
taken into account.
D.6 Export coordinates in MSI .xtl format
The Export/exp2xtl routine writes a .xtl file, as is used in Insight-II and
Cerius2 (Molecular Simulations, Inc.). Note that space groups are not named
exactly the same in the two programs and the origin may need to be specified
as "origin 2", for space groups where the center of symmetry is not at the
origin. It is up to the user to get things right.
D.7 Delete History Records
Tcl/Tk program is a platform-independent scripting language that is
used to implement most of EXPGUI. This software is available for free
and must be loaded in order to use EXPGUI. See the
installation notes for
UNIX for information on how to do this.
While learning Tcl/Tk is a great thing to do, it is not a requirement
for using or installing EXPGUI.
Every time a GSAS program (including EXPGUI) is run, an entry is added to
the "history records" in the .EXP file. After 999 entries have been written,
no more can be added to the file. Further, reading large numbers of history
records can slow the GSAS programs
(this is less of a problem on faster computers). For these reasons, it may be
a good idea to prune the older history records from the file. If more than 100
history records are found in an experiment file, EXPGUI suggests that the
older history entries be deleted. Alternately the File/EraseHistory command
can be used to invoke the this option.
On the dialog the number of history records to be retained is specified.
Also, after records have been deleted, the remaining records can be renumbered
starting with 1, so that the 999 record limit is not reached.
The WINEXEC package is needed under Windows-95 and its offspring
(-98 and -ME). See the Windows installation
notes for more details.
The BLT graphics package is used by the WIDPLT and LIVEPLOT routines. If the
package can not be found these routines, an error message,
"Error -- Unable to load the BLT package", will be displayed. It is also
possible for the package to be installed, but not configured properly.
If this is the case, a message,
"BLT Setup Error: could not access a Blt_ routine...", will be displayed.
This is most common in UNIX and is discussed further in the
UNIX installation notes. Also see
for more information on installation of BLT.
Praise to Larson and
Von Dreele for GSAS, Ousterhout
for convincing me to learn Tcl/Tk
and Jonathan Wasserman for helping get this project started.
Thanks also to
Pamela Whitfield of the NRC (Canada) for writing large
sections of the
Preferential Orientation Pane
Profile Constraints pane
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
EXPGUI is written by Brian H. Toby of the NIST Center for Neutron Research,
with help from Jonathan Wasserman.
GSAS is Copyright, 1984-2000, by
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
The author of EXPGUI is a U.S. Government employee which means that
EXPGUI is not subject to copyright. Have fun with it. Modify it. Please write
new sections and make them available to the rest of the world.
Neither the U.S. Government nor any author makes any warranty,
expressed or implied, or assumes any liability or responsibility
for the use of this information or the software described
here. Brand names cited herein are used for
identification purposes and do not constitute an endorsement by NIST.
Brian Toby (Brian.Toby@NIST.GOV)
$Revision: 456 $ $Date: 2009-12-04 23:06:28 +0000 (Fri, 04 Dec 2009) $