source: trunk/doc/expgui.html @ 436

Last change on this file since 436 was 436, checked in by toby, 11 years ago

# on 2001/09/04 23:07:02, toby did:
links to EXCLEDT & BKGEDIT
spelling
  • Property rcs:author set to toby
  • Property rcs:date set to 2001/09/04 23:07:02
  • Property rcs:lines set to +10 -10
  • Property rcs:rev set to 1.18
  • Property rcs:state set to Exp
  • Property svn:keywords set to Author Date Revision Id
File size: 20.6 KB
Line 
1<html>
2<head>
3   <META NAME="Author" CONTENT="Brian H. Toby">
4   <title>EXPGUI</title>
5</head>
6<BODY BGCOLOR="#FFFFFF">
7
8<A HREF=http://www.ncnr.nist.gov>
9<IMG SRC="http://www.ncnr.nist.gov/images/ncnrtrans.gif" 
10alt="Link to NIST Center for Neutron Research home page"
11ALIGN=RIGHT></A>
12<A HREF=http://www.nist.gov>
13<IMG SRC="http://www.ncnr.nist.gov/images/webidblue_2lineright.gif" 
14alt="Link to National Institute of Standards & Technology home page"
15ALIGN=LEFT></A>
16<CENTER>
17<A Href="http://www.ncnr.nist.gov/programs/crystallography/software/tclpkgs.html">
18<IMG SRC="tcltklogo100.gif" 
19alt="Link to Tcl/Tk information">
20</CENTER></A>
21<br clear=all><hr>
22
23<center><h1>
24EXPGUI<BR>
25A Graphical User Interface for
26<A Href="http://www.ncnr.nist.gov/programs/crystallography/software/gsas.html">
27GSAS</A>
28</h1></center>
29<P><P>
30<I><B>
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.
36</I></B>
37<P><P>
38EXPGUI is a graphical interface for the
39Los Alamos
40<A Href="http://www.ncnr.nist.gov/programs/crystallography/software/gsas.html">
41GSAS</A> package.
42EXPGUI does two things:
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.
48EXPGUI is written using the
49<A href="#tcltk">Tcl/Tk</A> scripting language.
50<P>
51This web page describes the different actions that
52can be accomplished with the different panes and the
53contents of the menus. The table below contains links to the other
54web accessible documentation.
55<P>
56<TABLE BORDER BGCOLOR="#FFFF40" ALIGN=CENTER>
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>
61</TR>
62<TR>
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>
66</TR>
67<TR>
68<TH><A Href="expgui7.html">Preferred Orientation</A></TH>
69<TH>&nbsp;</TH>
70<TH>&nbsp;</TH>
71</TR>
72<TR><TH BGCOLOR="#F0F0F0">Installation Notes:</TH>
73<TH><A Href="expgui_Unix_readme.html">Unix</A></TH>
74<TH><A Href="expgui_Win_readme.html">Windows</A></TH>
75<TH><A Href="expgui_cfg.html">Customization</A></TH>
76</TR>
77<TR><TH BGCOLOR="#F0F0F0">Tutorials:</TH>
78<TH><A Href="http://www.ncnr.nist.gov/xtal/software/expgui/tutorial1/index.html">TOF</A></TH>
79<TH><A Href="http://www.ncnr.nist.gov/xtal/software/expgui/tutorial2/index.html">CW Neutron</A></TH>
80<TH>&nbsp;</TH>
81</TR>
82<TR><TH BGCOLOR="#F0F0F0">Utilities:</TH>
83<TH><A Href="liveplot.html">LIVEPLOT</A></TH>
84<TH><A Href="liveplot.html">BKGEDIT</A></TH>
85<TH><A Href="excledt.html">EXCLEDT</A></TH>
86</TR>
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>
91</TR>
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="http://www.ncnr.nist.gov/xtal/software/EXPGUI_reprint.pdf">
96<I>J. Appl. Cryst.</i><BR>article</A></TH>
97</TR>
98</TABLE><BR CLEAR=ALL>
99<P>
100<B>Citations.</B>
101The appropriate citations to be used for GSAS and EXPGUI are:
102<UL>
103<LI>
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="ftp://ftp.lanl.gov/public/gsas/manual/GSASManual.pdf">
107[link to PDF file at Los Alamos ftp server]
108</A>
109<LI>
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="http://www.ncnr.nist.gov/xtal/software/EXPGUI_reprint.pdf">
113[link to PDF file]
114</A>
115</UL>
116<P>
117<hr>
118
119<h2>A. Experiment file editing</h2>
120<P>
121<DL><DL>
122When an experiment (.EXP) file is read, a copy is made in local
123computer memory. In most cases, values are changed in this
124"in memory" copy of the experiment file
125as this information is changed by the user on the screen.
126<img SRC="rederror.gif" align=LEFT BORDER=3 alt="EXPGUI Screen snapshot">
127<IMG SRC="new.gif" HEIGHT=13 WIDTH=36 alt="New!">
128If there is an error in the typed value, (for example if "1..0" is typed, or
129"1.5" is typed where an integer is expected), these values are
130not saved. In this case, the text is turned red, to indicate
131that an error is present, as shown in the figure to the left, where "90.000x"
132has been entered for alpha.
133The edited version of the experiment file is written back out to
134disk when the "File/Save" or "File/Save as"
135<A Href="expguic.html#1">menu bar options</A>
136are used. The File/Save operation is done automatically before any GSAS
137programs, such as GENLES or EXPEDT, are run.
138<P>
139
140Since the GSAS experiment file is quite complex,
141values are grouped together by function, approximately
142following the outline of the EXPEDT program.
143Each set of values is given a
144"tabbed pane" on a window that has the appearance of a notebook (see below).
145<center><B>
146<br>The notebook pane tabs.
147<br><img SRC="panebar1.gif"  BORDER=3 alt="EXPGUI Screen snapshot">
148</center></B>
149In some cases, where values are
150too numerous or complex to fit onto the notebook pane, one or more buttons
151may be present on a pane that will create a separate window,
152where the associated values can be modified.
153These values are not recorded in the
154"in memory" copy of the experiment file unless the "Save" button on this window
155is pressed. If "Cancel" is pressed, no changes are made.
156Each notebook pane is listed below with a link to the web page documenting
157that pane.
158
159<A Href="expgui1.html">
160<h3>A.1 Least Squares (LS) Controls Pane</h3>
161</A><A Href="expgui2.html">
162<h3>A.2 Phase Pane</h3> 
163</A><A Href="expgui3.html">
164<h3>A.3 Histogram pane</h3> 
165</A><A Href="expgui4.html">
166<h3>A.4 Scaling pane</h3> 
167</A><A Href="expgui5.html">
168<h3>A.5 Profile pane</h3> 
169</A><A Href="expgui6.html">
170<h3>A.6 Constraints pane</h3>
171</A><A Href="expgui7.html">
172<h3>A.7 Preferential Orientation Pane</h3>
173</A>
174<br clear=all>
175</DL></DL>
176<h2>B. Shortcuts</h2></a>
177<a name="multiplehistogram">
178<h3>B.1 Multiple Histogram Selection</h3></a>
179<DL><DL>
180This mode allows parameters to be changed for groups of
181histograms.
182When the "Multiple Histogram Selection" mode is off,
183it is possible to modify parameters
184and refinement flags for only a single histogram, but
185the other settings allow groups of histograms
186to be selected and modified.
187<A href="#mouseactions">(see Mouse Actions)</A>.
188<P>
189It does not make sense, however, to globally modify
190instrument-related parameters and flags for different
191histogram types.
192So global actions can be limited to a single class
193of histogram types (e.g. TOF, CW Neutron,...), which
194allows these parameters to be set for groups of
195similar histograms. Thus, if this mode is set to "All"
196the Histogram and Profile panes are disabled.
197<P>
198The setting for "Multiple Histogram Selection" mode is
199displayed above each histogram selection box and is
200selected using the "Multiple Hist. Selection" item on the
201Options menu to create a submenu or by clicking on the display.
202Note that another option in this "Multiple Hist. Selection"
203submenu is an option "Group Phases Together" that controls how
204EXPGUI treats phases having
205the same profile type that is used when multiple histograms are selected. If
206the "Group Phases Together" option is on, then the refinement flags for
207all phases with the same histogram types are grouped together, when possible.
208If this option is off, phases are treated separately.
209<IMG SRC="new.gif" HEIGHT=13 WIDTH=36 alt="New!">
210If the left mouse button is used to click on the selection mode display,
211the mode is cycled between the available modes. If the right mouse
212button is used, the mode is reset, to disable multiple histogram selection.
213<p>
214<a name="mouseactions">
215</DL></DL>
216<h3>B.2 Mouse Actions</h3></a>
217<DL><DL>
218A range of atoms or (in multiple selection mode) histograms may be
219selected by dragging (holding down) the left mouse button. It is also
220possible to select a range by using the Shift key with the left mouse
221button. To select or deselect individual entries, use the Control key
222with the left mouse button. Pressing the right mouse button selects all
223entries in a list.
224</DL></DL>
225
226<h2>C. Menu Commands and Programs</h2>
227<p>
228GSAS programs are invoked either through use of the menu bar
229<center><B>
230<br>The menu bar.
231<br><img SRC="menubar.gif" BORDER=3 alt="EXPGUI Screen snapshot">
232</center></B>
233or by "pressing" a button on the button bar. The button bar
234simply provides an easy way to access commonly used
235actions on the menu bar. Users can
236<A HREF="expgui_cfg.html">
237configure the menu bar</A> to include their own preferred actions and, with
238some knowledge of the program and Tcl/Tk,
239add their own commands to the menu bar or button bar.
240
241<center><B>
242<br>The button bar.
243<br><img SRC="buttonbar.gif" BORDER=3 alt="EXPGUI Screen snapshot">
244</center></B>
245
246<h3>Invoking of GSAS programs</h3>
247When GSAS programs are invoked, in most cases EXPGUI is suspended while
248the GSAS program is run in a terminal (or DOS) window. When the terminal
249window is closed, EXPGUI is restarted. If desired (see the
250<A Href="expguic.html#Autoicon">
251"Iconify during GSAS"</A>
252option) while this occurs, EXPGUI can be made into an icon
253to save screen space.
254<P>
255<img src="powpref4a.gif" align=left>
256Once the GSAS program has finished, if the program has modified
257the .EXP file,
258<a Href="expguierr.html#Overwrite">
259"File has been modified..."</a>message box
260similar to the one to the left is displayed (also see the more complete
261discussion on the <a Href="expguierr.html#Overwrite">messages page</A>.
262Note that this message can be avoided if the
263<A Href="expguic.html#Autoupdate">
264"Autoload EXP"</A>
265option is used.
266<BR clear=all>
267<P>
268Note that in both Windows-95 and Windows-NT, a file named <tt>EXPGUI.LCK</tt>
269is created while the GSAS program runs. The presence of this file is used
270to suspend the LIVEPLOT program, since LIVEPLOT has sometimes crashed
271when run at the same time as GENLES (no such problem has been seen in Unix).
272This file is deleted when the GSAS program completes.
273<P>
274<img src="lock.gif" align=left>
275In Windows-9x, the <a Href="expgui_Win_readme.html#Winexec">Winexec</a>
276package is used to execute a command that creates a DOS window.
277The GSAS programs are then run by a batch file in this DOS window.
278Due to limitations in Tcl/Tk & Windows, the DOS window runs independently
279of EXPGUI, so the lock file (<tt>EXPGUI.LCK</tt>) is also used to suspend
280EXPGUI. While EXPGUI is waiting, the
281<a Href="expguierr.html#lock">
282Please wait...
283</a>
284window shown to the left is displayed. When the GSAS program completes, the
285lock file is deleted, the window automatically disappears and EXPGUI resumes.
286Should a problem arise where the file is not deleted, EXPGUI can be resumed by
287pressing the "Continue" button.
288
289<BR clear=all>
290<h3>GSAS menus</h3>
291
292A description of the EXPGUI menus follows. Use the links to obtain
293more information, including a very
294brief description of the function of each menu option.
295Note that an option may appear under more than one menu.
296
297<DL><DL>
298
299<A Href="expguic.html#1">
300<H3>C.1 File Menu</H3>
301</A>
302<DL><DL>
303The options on the File menu as is the custom contains the commands
304for reading and writing experiment files, as well as starting
305and ending the program.
306</DL></DL>
307
308<A Href="expguic.html#2">
309<h3>C.2 Options Menu</h3>
310</A>
311<DL><DL>
312This menu contains options that determine how EXPGUI runs.
313</DL></DL>
314
315<A Href="expguic.html#3">
316<h3>C.3 Powder Menu</h3>
317</A>
318<DL><DL>
319This menu contains links to GSAS programs used for powder diffraction
320analysis.
321</DL></DL>
322
323<A Href="expguic.html#4">
324<h3>C.4 Single Crystal Menu</h3>
325</A>
326<DL><DL>
327This menu contains links to GSAS programs used for
328single-crystal diffraction analysis.
329</DL></DL>
330
331<A Href="expguic.html#5">
332<h3>C.5 Graphics Menu</h3>
333</A>
334<DL><DL>
335This menu contains links to several GSAS and
336two non-GSAS (LIVEPLOT and WIDPLT)
337programs used for graphical display of data and results.
338</DL></DL>
339
340<A Href="expguic.html#6">
341<h3>C.6 Results Menu</h3>
342</A>
343<DL><DL>
344This menu contains links to several GSAS and
345one non-GSAS (LSTVIEW)
346programs used for analysis of results.
347</DL></DL>
348
349<A Href="expguic.html#7">
350<h3>C.7 Calculations Menu</h3>
351</A>
352<DL><DL>
353This menu contains programs for useful crystallographic computations.
354</DL></DL>
355
356<A Href="expguic.html#8">
357<h3>C.8 Import/Export Menu</h3>
358</A>
359<DL><DL>
360This menu contains utilities for importing information into GSAS and
361exporting.
362</DL></DL>
363</DL></DL>
364
365<h2>D. EXPGUI Utility Programs</h2></a>
366
367<br clear=all>
368<H3>D.1 LSTVIEW</H3>
369
370<DL><DL>
371LSTVIEW is used to browse through the GSAS output listing. It is
372invoked by the "lstview" command in the GUI.
373<CENTER><IMG SRC="textview.gif" alt="EXPGUI Screen snapshot"></CENTER>
374</DL></DL>
375
376<br clear=all>
377<H3>D.2 LIVEPLOT</H3>
378<DL><DL>
379LIVEPLOT shows the observed, calculated and difference plots for powder
380refinements. The plot is updated as the refinement progresses. The mouse can
381be used to zoom in on sections of the plot.
382LIVEPLOT uses the <A href="#blt">BLT</A> graphics package.
383<CENTER><IMG SRC="liveplot.gif" alt="EXPGUI Screen snapshot"></CENTER>
384<IMG SRC="new.gif" HEIGHT=13 WIDTH=36 alt="New!">
385LIVEPLOT can now be enhanced to superimpose peak locations for
386input unit cells or peaks from JCPDS/ICDD entries.
387See the <A HREF="liveplot.html#customize">
388LIVEPLOT customization information</A> 
389or read file <tt>expgui_cfg.html</tt> in the <tt>gsas/tcl/doc</tt> directory.
390<P>
391</DL></DL>
392
393<br clear=all>
394<H3>D.3 WIDPLT</H3>
395<DL><DL>
396WIDPLT can be used to plot the actual peak widths generated by the profile
397parameters used in GSAS.
398It is possible to define reference curves
399that are loaded automatically.
400WIDPLT uses the <A href="#blt">BLT</A> graphics package.
401<CENTER><IMG SRC="widplt.gif" alt="EXPGUI Screen snapshot"></CENTER>
402</DL></DL>
403
404<br clear=all>
405<a name="ConvertUnix"></a>
406<a name="ConvertWin"></a>
407<h3>D.4 File Conversions</h3> 
408<DL><DL>
409<P>
410GSAS data, experiment and instrument parameter files are
411expected to have a format with exactly 80 characters per line followed
412by a carriage return and then a linefeed (82 characters total per line).
413Files in this format can be read in "Direct Access" mode.
414Recent versions of GSAS will attempt to detect and repair files that
415are not in this format, but if the file is incorrectly formatted and
416by chance the length of the file is divisible by 82, the problem in the
417file format will not be detected.
418The Convert menu
419in can be used to convert files into the correct format.
420The original version of the
421file is retained and renamed.
422<P>
423</DL></DL>
424
425<br clear=all>
426<a name="Composition"></a>
427<h3>D.5 Compute Composition</h3> 
428<DL><DL>
429The composition box shows the unit cell and asymmetric unit composition
430for all phases in a material. Site multiplicities and occupancies are
431taken into account.
432</DL></DL>
433
434<br clear=all>
435<a name="ExportMSI"></a>
436<h3>D.6 Export coordinates in MSI .xtl format</h3> 
437<DL><DL>
438The Export/exp2xtl routine writes a .xtl file, as is used in Insight-II and
439Cerius2 (Molecular Simulations, Inc.). Note that space groups are not named
440exactly the same in the two programs and the origin may need to be specified
441as "origin 2", for space groups where the center of symmetry is not at the
442origin. It is up to the user to get things right.
443</DL></DL>
444
445<br clear=all>
446<a name="DeleteHistoryRecords"></a>
447<h3>D.7 Delete History Records</h3> 
448<DL><DL>
449Every time a GSAS program (including EXPGUI) is run, an entry is added to
450the "history records" in the .EXP file. After 999 entries have been written,
451no more can be added to the file. Further, reading large numbers of history
452records can slow the GSAS programs
453(this is less of a problem on faster computers). For these reasons, it may be
454a good idea to prune the older history records from the file. If more than 100
455history records are found in an experiment file, EXPGUI suggests that the
456older history entries be deleted. Alternately the File/EraseHistory command
457can be used to invoke the this option.
458<P>
459On the dialog the number of history records to be retained is specified.
460Also, after records have been deleted, the remaining records can be renumbered
461starting with 1, so that the 999 record limit is not reached.
462</DL></DL>
463
464<A name=tcltk>
465<H2>
466<A Href="http://www.ncnr.nist.gov/programs/crystallography/software/tclpkgs.html">
467Tcl/Tk</A></H2>
468The
469<A Href="http://www.ncnr.nist.gov/programs/crystallography/software/tclpkgs.html">
470Tcl/Tk program</A> is a platform-independent scripting language that is
471used to implement most of EXPGUI. This software is available for free
472and must be loaded in order to use EXPGUI. See the
473installation notes for
474<A HREF="expgui_Win_readme.html">Windows</A>,
475and for
476<A HREF="expgui_Unix_readme.html">UNIX</A> for information on how to do this.
477While learning Tcl/Tk is a great thing to do, it is not a requirement
478for using or installing EXPGUI.
479
480<A name=winexec>
481<H3>
482WINEXEC</H3>
483<UL>
484The WINEXEC package is needed under Windows-95 and its offspring
485(-98 and -ME). See the <A HREF="expgui_Win_readme.html">Windows installation
486notes</A> for more details.
487</UL>
488
489<A name=blt>
490<H3>
491BLT</H3>
492<UL>
493The BLT graphics package is used by the WIDPLT and LIVEPLOT routines. If the
494package can not be found these routines, an error message,
495"Error -- Unable to load the BLT package", will be displayed. It is also
496possible for the package to be installed, but not configured properly.
497If this is the case, a message,
498"BLT Setup Error: could not access a Blt_ routine...", will be displayed.
499This is most common in UNIX and is discussed further in the
500<A HREF="expgui_Unix_readme.html">UNIX installation notes</A>. Also see
501<A HREF="http://www.ncnr.nist.gov/programs/crystallography/software/tclpkgs.html">
502http://www.ncnr.nist.gov/programs/crystallography/software/tclpkgs.html
503</A> for more information on installation of BLT.
504</UL>
505
506<H2>
507Acknowledgments</H2>
508Praise to Larson and
509<A HREF="http://www.nist.gov/cgi-bin/exit_nist.cgi?url=http://lansce.lanl.gov/lujan/staff12/vondreele.htm">
510Von Dreele</A> for GSAS, <A HREF="http://www.nist.gov/cgi-bin/exit_nist.cgi?url=http://www.scriptics.com/">Ousterhout</A>
511for Tcl/Tk,
512Przemek Klosowski</A>
513for convincing me to learn Tcl/Tk
514and Jonathan Wasserman for helping get this project started.
515Thanks also to
516Pamela Whitfield of the NRC (Canada) for writing large
517sections of the
518<A Href="expgui7.html">Preferential Orientation Pane</A>
519and the
520<A Href="expgui6.html">Profile Constraints pane</A>
521code.
522<P>
523<A Href="http://www.ncnr.nist.gov/programs/crystallography/software/gsas.html">
524GSAS</A>
525is written by Allen C. Larson and <A HREF="http://www.nist.gov/cgi-bin/exit_nist.cgi?url=http://lansce.lanl.gov/lujan/staff12/vondreele.htm">
526Robert B. Von Dreele</A>, MS-H805,
527Los Alamos National Laboratory, Los Alamos, NM 87545. Problems, questions
528or kudos concerning GSAS should be sent to Robert B. Von Dreele at
529<A HREF="MAILTO:vondreele@lanl.gov">vondreele@lanl.gov</A>
530EXPGUI is written by Brian H. Toby of the NIST Center for Neutron Research,
531<A HREF="MAILTO:Brian.Toby@NIST.GOV">Brian.Toby@NIST.GOV</A> 
532with help from Jonathan Wasserman.
533
534<P>GSAS is Copyright, 1984-2000, by
535the Regents of the University of California.
536The GSAS software was produced under a U.S. Government contract (W-7405-ENG-36)
537by the Los Alamos National Laboratory, which is operated by the University
538of California for the U.S. Department of Energy. The U.S. Government is
539licensed to use, reproduce, and distribute this software. Permission is
540granted to the public to copy and use this software without charge, provided
541that this notice and any statement of authorship are reproduced on all
542copies. Neither the Government nor the University makes any warranty, express
543or implied, or assumes any liability or responsibility for the use of this
544software.
545
546<P>The author of EXPGUI is a U.S. Government employee which means that
547EXPGUI is not subject to copyright. Have fun with it. Modify it. Please write
548new sections and make them available to the rest of the world.
549
550<p>Neither the U.S. Government nor any author makes any warranty,
551expressed or implied, or assumes any liability or responsibility
552for the use of this information or the software described
553here. Brand names cited herein are used for
554identification purposes and do not constitute an endorsement by NIST.
555
556<p><hr><a href="http://www.ncnr.nist.gov/staff/toby/">Brian Toby</a> (<a href="mailto:brian.toby@nist.gov">Brian.Toby@NIST.GOV</a>)
557<br>
558$Revision: 436 $ $Date: 2009-12-04 23:06:08 +0000 (Fri, 04 Dec 2009) $
559</body>
560</html>
Note: See TracBrowser for help on using the repository browser.