source: trunk/doc/expgui.html @ 364

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

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