source: trunk/doc/expgui.html @ 462

Last change on this file since 462 was 456, checked in by toby, 12 years ago

# on 2001/10/14 05:33:15, toby did:
plug mailing list

  • Property rcs:author set to toby
  • Property rcs:date set to 2001/10/14 05:33:15
  • Property rcs:lines set to +8 -1
  • Property rcs:rev set to 1.20
  • Property rcs:state set to Exp
  • Property svn:keywords set to Author Date Revision Id
File size: 20.9 KB
[148]3   <META NAME="Author" CONTENT="Brian H. Toby">
4   <title>EXPGUI</title>
[148]8<A HREF=>
9<IMG SRC="" 
10alt="Link to NIST Center for Neutron Research home page"
12<A HREF=>
13<IMG SRC="" 
14alt="Link to National Institute of Standards & Technology home page"
17<A Href="">
18<IMG SRC="tcltklogo100.gif" 
19alt="Link to Tcl/Tk information">
[329]21<br clear=all><hr>
25A Graphical User Interface for
26<A Href="">
31Note that version 1.41 or later of EXPGUI should be used with the April 2001
32releases of GSAS on all platforms (Version 1.41 is currently the alpha
33release version), due to changes in file formats and locations.
34The "stable" release should be used
35with older versions of GSAS.
[148]38EXPGUI is a graphical interface for the
[408]39Los Alamos
[148]40<A Href="">
41GSAS</A> package.
[408]42EXPGUI does two things:
[202]43it can be used to directly modify the GSAS
44experiment file with a graphical user interface (GUI) and
45it can be used to invoke the programs inside the
46GSAS package such as EXPEDT, GENLES, FOURIER...
47These programs can be run from a menu or in many cases by pressing buttons.
[364]48EXPGUI is written using the
49<A href="#tcltk">Tcl/Tk</A> scripting language.
[408]51This web page describes the different actions that
[202]52can be accomplished with the different panes and the
[408]53contents of the menus. The table below contains links to the other
54web accessible documentation.
57<TR><TH BGCOLOR="#F0F0F0" rowspan=3>GUI Sections</TH>
58<TH><A Href="expgui1.html">Least Squares</A></TH>
59<TH><A Href="expgui2.html">Phase info</A></TH>
60<TH><A Href="expgui3.html">Histogram info</A></TH>
63<TH><A Href="expgui4.html">Scaling info</A></TH>
64<TH><A Href="expgui5.html">Profile terms</A></TH>
65<TH><A Href="expgui6.html">Constraints</A></TH>
68<TH><A Href="expgui7.html">Preferred Orientation</A></TH>
[445]69<TH><A Href="expguic.html">Menus</A></TH>
[445]72<TR><TH BGCOLOR="#F0F0F0">Utilities:</TH>
73<TH><A Href="liveplot.html">LIVEPLOT</A></TH>
74<TH><A Href="liveplot.html">BKGEDIT</A></TH>
75<TH><A Href="excledt.html">EXCLEDT</A></TH>
[408]77<TR><TH BGCOLOR="#F0F0F0">Installation Notes:</TH>
78<TH><A Href="expgui_Unix_readme.html">Unix</A></TH>
79<TH><A Href="expgui_Win_readme.html">Windows</A></TH>
80<TH><A Href="expgui_cfg.html">Customization</A></TH>
82<TR><TH BGCOLOR="#F0F0F0">Tutorials:</TH>
83<TH><A Href="">TOF</A></TH>
84<TH><A Href="">CW Neutron</A></TH>
87<TR><TH BGCOLOR="#F0F0F0">Messages:</TH>
88<TH><A Href="expguierr.html#Error">Error</A></TH>
89<TH><A Href="expguierr.html#Warn">Warning</A></TH>
90<TH><A Href="expguierr.html#Info">Informational</A></TH>
92<TR><TH BGCOLOR="#F0F0F0">Other:</TH>
93<TH><A Href="expgui_intro.html">Introduction</A></TH>
94<TH><A Href="wishlist.html">Recent & Planned<BR>Improvements</A></TH>
95<TH><A Href="">
96<I>J. Appl. Cryst.</i><BR>article</A></TH>
101The appropriate citations to be used for GSAS and EXPGUI are:
104A.C. Larson and R.B. Von Dreele, "General Structure Analysis System (GSAS)",
105Los Alamos National Laboratory Report LAUR 86-748 (2000).
106<A HREF="">
107[link to PDF file at Los Alamos ftp server]
110B. H. Toby, <i>EXPGUI</i>, a graphical user interface for <i>GSAS</i>,
111<i>J. Appl. Cryst.</i> <b>34</b>, 210-213 (2001).
112<A HREF="">
113[link to PDF file]
[456]117<B>Mailing List.</B>
118If you would like to get news about about new features
119& bug fixes in EXPGUI and also support
120the project by demonstrating how many people use it,
121please send e-mail to
122<a href=" Mailing List">Brian.Toby@NIST.GOV</a>.
[202]126<h2>A. Experiment file editing</h2>
129When an experiment (.EXP) file is read, a copy is made in local
[364]130computer memory. In most cases, values are changed in this
131"in memory" copy of the experiment file
132as this information is changed by the user on the screen.
133<img SRC="rederror.gif" align=LEFT BORDER=3 alt="EXPGUI Screen snapshot">
134<IMG SRC="new.gif" HEIGHT=13 WIDTH=36 alt="New!">
135If there is an error in the typed value, (for example if "1..0" is typed, or
136"1.5" is typed where an integer is expected), these values are
137not saved. In this case, the text is turned red, to indicate
138that an error is present, as shown in the figure to the left, where "90.000x"
139has been entered for alpha.
140The edited version of the experiment file is written back out to
141disk when the "File/Save" or "File/Save as"
142<A Href="expguic.html#1">menu bar options</A>
143are used. The File/Save operation is done automatically before any GSAS
144programs, such as GENLES or EXPEDT, are run.
[364]147Since the GSAS experiment file is quite complex,
148values are grouped together by function, approximately
149following the outline of the EXPEDT program.
150Each set of values is given a
151"tabbed pane" on a window that has the appearance of a notebook (see below).
[202]153<br>The notebook pane tabs.
[291]154<br><img SRC="panebar1.gif"  BORDER=3 alt="EXPGUI Screen snapshot">
[364]156In some cases, where values are
[436]157too numerous or complex to fit onto the notebook pane, one or more buttons
[364]158may be present on a pane that will create a separate window,
159where the associated values can be modified.
160These values are not recorded in the
161"in memory" copy of the experiment file unless the "Save" button on this window
162is pressed. If "Cancel" is pressed, no changes are made.
163Each notebook pane is listed below with a link to the web page documenting
164that pane.
[226]166<A Href="expgui1.html">
[202]167<h3>A.1 Least Squares (LS) Controls Pane</h3>
[226]168</A><A Href="expgui2.html">
[202]169<h3>A.2 Phase Pane</h3> 
[226]170</A><A Href="expgui3.html">
[202]171<h3>A.3 Histogram pane</h3> 
[226]172</A><A Href="expgui4.html">
[202]173<h3>A.4 Scaling pane</h3> 
[226]174</A><A Href="expgui5.html">
[202]175<h3>A.5 Profile pane</h3> 
[226]176</A><A Href="expgui6.html">
[202]177<h3>A.6 Constraints pane</h3>
[226]178</A><A Href="expgui7.html">
[291]179<h3>A.7 Preferential Orientation Pane</h3>
[291]181<br clear=all>
[202]183<h2>B. Shortcuts</h2></a>
[24]184<a name="multiplehistogram">
[202]185<h3>B.1 Multiple Histogram Selection</h3></a>
187This mode allows parameters to be changed for groups of
189When the "Multiple Histogram Selection" mode is off,
190it is possible to modify parameters
191and refinement flags for only a single histogram, but
192the other settings allow groups of histograms
193to be selected and modified.
194<A href="#mouseactions">(see Mouse Actions)</A>.
[24]196It does not make sense, however, to globally modify
197instrument-related parameters and flags for different
198histogram types.
199So global actions can be limited to a single class
200of histogram types (e.g. TOF, CW Neutron,...), which
201allows these parameters to be set for groups of
202similar histograms. Thus, if this mode is set to "All"
[202]203the Histogram and Profile panes are disabled.
205The setting for "Multiple Histogram Selection" mode is
[226]206displayed above each histogram selection box and is
[24]207selected using the "Multiple Hist. Selection" item on the
[226]208Options menu to create a submenu or by clicking on the display.
209Note that another option in this "Multiple Hist. Selection"
210submenu is an option "Group Phases Together" that controls how
211EXPGUI treats phases having
212the same profile type that is used when multiple histograms are selected. If
[115]213the "Group Phases Together" option is on, then the refinement flags for
214all phases with the same histogram types are grouped together, when possible.
215If this option is off, phases are treated separately.
[291]216<IMG SRC="new.gif" HEIGHT=13 WIDTH=36 alt="New!">
[226]217If the left mouse button is used to click on the selection mode display,
218the mode is cycled between the available modes. If the right mouse
219button is used, the mode is reset, to disable multiple histogram selection.
221<a name="mouseactions">
[202]223<h3>B.2 Mouse Actions</h3></a>
225A range of atoms or (in multiple selection mode) histograms may be
226selected by dragging (holding down) the left mouse button. It is also
227possible to select a range by using the Shift key with the left mouse
228button. To select or deselect individual entries, use the Control key
[96]229with the left mouse button. Pressing the right mouse button selects all
230entries in a list.
[202]233<h2>C. Menu Commands and Programs</h2>
235GSAS programs are invoked either through use of the menu bar
237<br>The menu bar.
[291]238<br><img SRC="menubar.gif" BORDER=3 alt="EXPGUI Screen snapshot">
240or by "pressing" a button on the button bar. The button bar
241simply provides an easy way to access commonly used
242actions on the menu bar. Users can
243<A HREF="expgui_cfg.html">
244configure the menu bar</A> to include their own preferred actions and, with
245some knowledge of the program and Tcl/Tk,
246add their own commands to the menu bar or button bar.
249<br>The button bar.
[291]250<br><img SRC="buttonbar.gif" BORDER=3 alt="EXPGUI Screen snapshot">
[364]253<h3>Invoking of GSAS programs</h3>
254When GSAS programs are invoked, in most cases EXPGUI is suspended while
255the GSAS program is run in a terminal (or DOS) window. When the terminal
256window is closed, EXPGUI is restarted. If desired (see the
257<A Href="expguic.html#Autoicon">
258"Iconify during GSAS"</A>
259option) while this occurs, EXPGUI can be made into an icon
260to save screen space.
262<img src="powpref4a.gif" align=left>
263Once the GSAS program has finished, if the program has modified
264the .EXP file,
265<a Href="expguierr.html#Overwrite">
266"File has been modified..."</a>message box
267similar to the one to the left is displayed (also see the more complete
268discussion on the <a Href="expguierr.html#Overwrite">messages page</A>.
269Note that this message can be avoided if the
270<A Href="expguic.html#Autoupdate">
271"Autoload EXP"</A>
272option is used.
273<BR clear=all>
275Note that in both Windows-95 and Windows-NT, a file named <tt>EXPGUI.LCK</tt>
276is created while the GSAS program runs. The presence of this file is used
277to suspend the LIVEPLOT program, since LIVEPLOT has sometimes crashed
278when run at the same time as GENLES (no such problem has been seen in Unix).
279This file is deleted when the GSAS program completes.
281<img src="lock.gif" align=left>
282In Windows-9x, the <a Href="expgui_Win_readme.html#Winexec">Winexec</a>
283package is used to execute a command that creates a DOS window.
284The GSAS programs are then run by a batch file in this DOS window.
285Due to limitations in Tcl/Tk & Windows, the DOS window runs independently
286of EXPGUI, so the lock file (<tt>EXPGUI.LCK</tt>) is also used to suspend
287EXPGUI. While EXPGUI is waiting, the
288<a Href="expguierr.html#lock">
289Please wait...
291window shown to the left is displayed. When the GSAS program completes, the
292lock file is deleted, the window automatically disappears and EXPGUI resumes.
293Should a problem arise where the file is not deleted, EXPGUI can be resumed by
294pressing the "Continue" button.
296<BR clear=all>
297<h3>GSAS menus</h3>
[226]299A description of the EXPGUI menus follows. Use the links to obtain
300more information, including a very
[24]301brief description of the function of each menu option.
302Note that an option may appear under more than one menu.
306<A Href="expguic.html#1">
[202]307<H3>C.1 File Menu</H3>
310The options on the File menu as is the custom contains the commands
311for reading and writing experiment files, as well as starting
312and ending the program.
[226]315<A Href="expguic.html#2">
[202]316<h3>C.2 Options Menu</h3>
319This menu contains options that determine how EXPGUI runs.
[226]322<A Href="expguic.html#3">
[202]323<h3>C.3 Powder Menu</h3>
326This menu contains links to GSAS programs used for powder diffraction
[226]330<A Href="expguic.html#4">
[202]331<h3>C.4 Single Crystal Menu</h3>
334This menu contains links to GSAS programs used for
[226]335single-crystal diffraction analysis.
[226]338<A Href="expguic.html#5">
[202]339<h3>C.5 Graphics Menu</h3>
342This menu contains links to several GSAS and
[408]343two non-GSAS (LIVEPLOT and WIDPLT)
[24]344programs used for graphical display of data and results.
[226]347<A Href="expguic.html#6">
[202]348<h3>C.6 Results Menu</h3>
351This menu contains links to several GSAS and
[436]352one non-GSAS (LSTVIEW)
[24]353programs used for analysis of results.
[226]356<A Href="expguic.html#7">
[202]357<h3>C.7 Calculations Menu</h3>
360This menu contains programs for useful crystallographic computations.
[226]363<A Href="expguic.html#8">
[202]364<h3>C.8 Import/Export Menu</h3>
367This menu contains utilities for importing information into GSAS and
[202]372<h2>D. EXPGUI Utility Programs</h2></a>
374<br clear=all>
[364]375<H3>D.1 LSTVIEW</H3>
[436]378LSTVIEW is used to browse through the GSAS output listing. It is
[26]379invoked by the "lstview" command in the GUI.
[291]380<CENTER><IMG SRC="textview.gif" alt="EXPGUI Screen snapshot"></CENTER>
[329]383<br clear=all>
[364]384<H3>D.2 LIVEPLOT</H3>
[408]386LIVEPLOT shows the observed, calculated and difference plots for powder
[26]387refinements. The plot is updated as the refinement progresses. The mouse can
388be used to zoom in on sections of the plot.
[436]389LIVEPLOT uses the <A href="#blt">BLT</A> graphics package.
[291]390<CENTER><IMG SRC="liveplot.gif" alt="EXPGUI Screen snapshot"></CENTER>
391<IMG SRC="new.gif" HEIGHT=13 WIDTH=36 alt="New!">
[26]392LIVEPLOT can now be enhanced to superimpose peak locations for
393input unit cells or peaks from JCPDS/ICDD entries.
[408]394See the <A HREF="liveplot.html#customize">
[26]395LIVEPLOT customization information</A> 
[37]396or read file <tt>expgui_cfg.html</tt> in the <tt>gsas/tcl/doc</tt> directory.
[329]400<br clear=all>
[364]401<H3>D.3 WIDPLT</H3>
403WIDPLT can be used to plot the actual peak widths generated by the profile
[148]404parameters used in GSAS.
405It is possible to define reference curves
406that are loaded automatically.
407WIDPLT uses the <A href="#blt">BLT</A> graphics package.
[291]408<CENTER><IMG SRC="widplt.gif" alt="EXPGUI Screen snapshot"></CENTER>
[329]411<br clear=all>
412<a name="ConvertUnix"></a>
[408]413<a name="ConvertWin"></a>
[364]414<h3>D.4 File Conversions</h3> 
[408]417GSAS data, experiment and instrument parameter files are
[329]418expected to have a format with exactly 80 characters per line followed
[408]419by a carriage return and then a linefeed (82 characters total per line).
420Files in this format can be read in "Direct Access" mode.
421Recent versions of GSAS will attempt to detect and repair files that
422are not in this format, but if the file is incorrectly formatted and
423by chance the length of the file is divisible by 82, the problem in the
424file format will not be detected.
425The Convert menu
426in can be used to convert files into the correct format.
427The original version of the
[329]428file is retained and renamed.
432<br clear=all>
433<a name="Composition"></a>
[364]434<h3>D.5 Compute Composition</h3> 
436The composition box shows the unit cell and asymmetric unit composition
437for all phases in a material. Site multiplicities and occupancies are
438taken into account.
441<br clear=all>
442<a name="ExportMSI"></a>
[364]443<h3>D.6 Export coordinates in MSI .xtl format</h3> 
445The Export/exp2xtl routine writes a .xtl file, as is used in Insight-II and
[436]446Cerius2 (Molecular Simulations, Inc.). Note that space groups are not named
[329]447exactly the same in the two programs and the origin may need to be specified
[436]448as "origin 2", for space groups where the center of symmetry is not at the
[329]449origin. It is up to the user to get things right.
452<br clear=all>
453<a name="DeleteHistoryRecords"></a>
[364]454<h3>D.7 Delete History Records</h3> 
456Every time a GSAS program (including EXPGUI) is run, an entry is added to
457the "history records" in the .EXP file. After 999 entries have been written,
458no more can be added to the file. Further, reading large numbers of history
459records can slow the GSAS programs
460(this is less of a problem on faster computers). For these reasons, it may be
461a good idea to prune the older history records from the file. If more than 100
462history records are found in an experiment file, EXPGUI suggests that the
463older history entries be deleted. Alternately the File/EraseHistory command
464can be used to invoke the this option.
466On the dialog the number of history records to be retained is specified.
467Also, after records have been deleted, the remaining records can be renumbered
468starting with 1, so that the 999 record limit is not reached.
[364]471<A name=tcltk>
473<A Href="">
476<A Href="">
477Tcl/Tk program</A> is a platform-independent scripting language that is
478used to implement most of EXPGUI. This software is available for free
479and must be loaded in order to use EXPGUI. See the
480installation notes for
481<A HREF="expgui_Win_readme.html">Windows</A>,
482and for
483<A HREF="expgui_Unix_readme.html">UNIX</A> for information on how to do this.
484While learning Tcl/Tk is a great thing to do, it is not a requirement
485for using or installing EXPGUI.
487<A name=winexec>
491The WINEXEC package is needed under Windows-95 and its offspring
492(-98 and -ME). See the <A HREF="expgui_Win_readme.html">Windows installation
493notes</A> for more details.
[148]496<A name=blt>
[148]500The BLT graphics package is used by the WIDPLT and LIVEPLOT routines. If the
[364]501package can not be found these routines, an error message,
502"Error -- Unable to load the BLT package", will be displayed. It is also
503possible for the package to be installed, but not configured properly.
504If this is the case, a message,
505"BLT Setup Error: could not access a Blt_ routine...", will be displayed.
506This is most common in UNIX and is discussed further in the
507<A HREF="expgui_Unix_readme.html">UNIX installation notes</A>. Also see
[148]508<A HREF="">
510</A> for more information on installation of BLT.
[66]515Praise to Larson and
[103]516<A HREF="">
517Von Dreele</A> for GSAS, <A HREF="">Ousterhout</A>
[37]518for Tcl/Tk,
[103]519Przemek Klosowski</A>
[37]520for convincing me to learn Tcl/Tk
[202]521and Jonathan Wasserman for helping get this project started.
[364]522Thanks also to
523Pamela Whitfield of the NRC (Canada) for writing large
524sections of the
525<A Href="expgui7.html">Preferential Orientation Pane</A>
526and the
527<A Href="expgui6.html">Profile Constraints pane</A>
[148]530<A Href="">
532is written by Allen C. Larson and <A HREF="">
[66]533Robert B. Von Dreele</A>, MS-H805,
[26]534Los Alamos National Laboratory, Los Alamos, NM 87545. Problems, questions
535or kudos concerning GSAS should be sent to Robert B. Von Dreele at
536<A HREF=""></A>
[202]537EXPGUI is written by Brian H. Toby of the NIST Center for Neutron Research,
538<A HREF="MAILTO:Brian.Toby@NIST.GOV">Brian.Toby@NIST.GOV</A> 
539with help from Jonathan Wasserman.
541<P>GSAS is Copyright, 1984-2000, by
542the Regents of the University of California.
[26]543The GSAS software was produced under a U.S. Government contract (W-7405-ENG-36)
544by the Los Alamos National Laboratory, which is operated by the University
545of California for the U.S. Department of Energy. The U.S. Government is
546licensed to use, reproduce, and distribute this software. Permission is
547granted to the public to copy and use this software without charge, provided
548that this notice and any statement of authorship are reproduced on all
549copies. Neither the Government nor the University makes any warranty, express
550or implied, or assumes any liability or responsibility for the use of this
[364]553<P>The author of EXPGUI is a U.S. Government employee which means that
554EXPGUI is not subject to copyright. Have fun with it. Modify it. Please write
[226]555new sections and make them available to the rest of the world.
557<p>Neither the U.S. Government nor any author makes any warranty,
[24]558expressed or implied, or assumes any liability or responsibility
559for the use of this information or the software described
[364]560here. Brand names cited herein are used for
[436]561identification purposes and do not constitute an endorsement by NIST.
[408]563<p><hr><a href="">Brian Toby</a> (<a href="">Brian.Toby@NIST.GOV</a>)
565$Revision: 456 $ $Date: 2009-12-04 23:06:28 +0000 (Fri, 04 Dec 2009) $
Note: See TracBrowser for help on using the repository browser.