source: trunk/doc/expgui.html @ 148

Last change on this file since 148 was 148, checked in by toby, 14 years ago

# on 2000/05/18 15:37:38, toby did:
add Tcl/tk logo, general editing
document atomic constraints section
keyboard shortcuts

  • Property rcs:author set to toby
  • Property rcs:date set to 2000/05/18 15:37:38
  • Property rcs:lines set to +157 -57
  • Property rcs:rev set to 1.10
  • Property rcs:state set to Exp
  • Property svn:keywords set to Author Date Revision Id
File size: 22.5 KB
3   <META NAME="Author" CONTENT="Brian H. Toby">
4   <title>EXPGUI</title>
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">
25A Graphical User Interface for
26<A Href="">
30EXPGUI is a graphical interface for the
31<A Href="">
32GSAS</A> package.
33It allows two types of actions:
34the different
36programs such as EXPEDT, GENLES, FOURIER,...
37can be run from a menu or by  pressing buttons,
38and it can be used to directly modify the GSAS
39experiment file without using EXPEDT.
40This document describes the functions in EXPGUI.
41Note that pictures on this page are not updated as frequently as the
45GSAS programs are invoked either through use of the menu bar
47<br>The menu bar.
48<br><img SRC="menubar.gif" BORDER=3 >
50or by "pressing" a button on the button bar. The button bar
51simply provides an easy way to access commonly used
52actions on the menu bar. Users can
53<A HREF="expgui_cfg.html">
54configure the menu bar</A> to include their own preferred actions and, with
55some knowledge of the program and Tcl/Tk,
56add their own commands to the menu bar or button bar.
59<br>The button bar.
60<br><img SRC="buttonbar.gif" BORDER=3 >
64Different sections of the .EXP file can be edited by selecting different
65panels or pages from the tabbed list.
67<br>The notebook panel tabs.
68<br><img SRC="panebar1.gif"  BORDER=3 >
71This documentation will describe the different actions that
72can be accomplished with the different panels and the
73contents of the menus. Other documents contain:
74<a name="installation"></A>
75<A HREF="expgui_Win_readme.html">
76Installation notes for Windows</A>,
77<A HREF="expgui_Unix_readme.html">
78Installation notes for UNIX</A> and
79<A HREF="expgui_cfg.html">
80Customization notes</A>.
83<h2>1. LS Controls panel</h2>
85<p>The LS Controls panel shows information about the
86current experiment, typically found in the EXPEDT "Least
87Squares Controls" options.
89Note that the order that histograms appear in this
90panel is determined by the "Sort histograms by" option in
91the Options Menu.
92<img SRC="1.gif" align=TEXTTOP>
95<h2>2. Phase panel</h2> 
97The phase panel is used to edit information
98about the phase or phases found in the experiment
99file. The cell and atomic damping and refinement
100flags can be changed here. Note that if a
101single atom is selected using the mouse, the information
102for that atom can be edited. If a group of atoms is
104<A href="#mouseactions">(see Mouse Actions)</A>
105the damping and refinement flags
106for all the selected atom can be changed at one time.
108If the EXPTOOL program
109<A href="#installation">(see the installation instructions)</A>
110is installed, buttons for adding phases and atoms will
111appear on this panel, as seen below. If the
112program is not properly installed, no errors occur, but the buttons
113do not appear.
115Note that the order that atoms appear in this panel is
116determined by the "Sort Atoms by" option in the Options
118<img SRC="2.gif" align=TEXTTOP>
121<h2>3. Histogram panel</h2> 
123The histogram panel is used to edit background
124and diffractometer constants for a histogram, as well as
125set damping and refinement flags for these parameters.
128<A href="#multiplehistogram">
129"Multiple Histogram Selection" mode</A> is set to "All",
130this panel is disabled. For other settings of this mode,
131groups of histograms can be selected and modified
134If the EXPTOOL program
135<A href="#installation">(see the installation instructions)</A>
136is installed, a button for adding histograms will
137appear on the bottom right on this panel, as seen below. If the
138program is not properly installed, no errors occur, but the button
139does not appear.
141Note that the order that histograms appear in this
142panel is determined by the "Sort histograms by" option in
143the Options Menu.
144<img SRC="3.gif" align=TEXTTOP>
147<h2>4. Scaling panel</h2> 
149The Scaling panel is used to edit the scale factor for a
150histogram as well as the phase fractions for each phase
151present in that histogram. Damping and refinement flags
152can also be set here.
155<A href="#multiplehistogram">
156"Multiple Histogram Selection" mode</A> is set to
157any value other than "Off,"
158groups of histograms can be selected and modified
161Note that the order that histograms appear in this
162panel is determined by the "Sort histograms by" option in
163the Options Menu.
164<img SRC="4.gif" align=TEXTTOP>
167<h2>5. Profile panel</h2> 
169The Profile panel is used to edit the profile values for
170each phase present in a histogram as well as set
171the refinement flags and a damping value for each phase.
174<A href="#multiplehistogram">
175"Multiple Histogram Selection" mode</A> is set to "All",
176this panel is disabled. For other settings of this mode,
177profile values and settings can be collectively
178modified for groups of histograms.
180Note that the order that histograms appear in this
181panel is determined by the "Sort histograms by" option in
182the Options Menu.
183<img SRC="5.gif" align=TEXTTOP>
186<h2>6. Constraints panel</h2>
188GSAS offers two types of restraints that can be included in a model.
189So called "soft constraints" or "restraints" penalize the fit if
190aspects of a model (for example, bond lengths) differ from selected values.
191So called "hard constraints" reduce the actual number of
192parameters in a model,
193by grouping parameters so that a single shift (possibly scaled) is
194applied to each parameter in the group.
195The constraints panel is used to set these "hard constraints."
196At this time the only constraints that can be set in EXPGUI are on atomic
197parameters (others can be set in EXPEDT).
199Note that these constraints are only applied to shifts, so that if two atoms
200are constrained so that the shift on their occupancy is the same, but
201the initial occupancies differ, the difference will be maintained as the
202values refine.
204<H4>Atom Constraints</H3>
205The atom constraints editing page appears below. Note that constraints can
206be listed sorted by constraint number, phase number, lowest atom number or
207variable by clicking on the buttons at the top of the page.
209To delete one or more constraints, click on the appropriate checkbuttons in the <B>Delete</B> column and the press the Delete button, below.
210<img SRC="mc.gif" align=TEXTTOP>
211Due to the way GSAS implements these constraints, a parameter can be included
212in only one constraint. Should one or more parameters be constrained twice,
213an error message is shown as shown below.
214Note that the constraint number is displayed as red, for constraints that
215have conflicts in the constraints editing page (see above.)
216<img SRC="mcerr.gif" align=TEXTTOP>
218<img SRC="mcedit.gif" align=LEFT>
219<img SRC="mcvar.gif" align=RIGHT>
220When the edit button for a constraint is pressed, the constraint is
221opened for editing. Controls are available to select the phase, variable,
222multiplier and atom(s). Note that for atom selection, use of the control key
223and the left mouse button allow individual atoms to be selected or deselected.
224Shift and the left mouse button allow ranges of atoms to be selected and the
225right mouse button selects all atoms
226<A href="#mouseactions">(see Mouse Actions)</A>.
228Note that it is inappropriate
229to constrain different types of parameters together, for example X and Uiso.
230The left-most variable button is the "master" which
231determines what variable are allowed in the
232other variable buttons.
234When the "New Constraint" button is pressed, a blank constraint editing
235window is opened. Note that any variable to the right may then be selected,
236including two special codes, Uxx and XYZU. XYZU creates four constraints,
237requiring the shifts on x, y, z and Uiso to be the same for all the selected
238atoms. Uxx does the same for the six anisotropic displacement parameters.
239These special codes are valuable for atoms that share a site.
241Note that only 100 parameters may be included in a constraint,
242with one exception. When shifts for Uiso for all atoms in a phase
243are constrained, this counts as a single parameter. If more than 100
244parameters are entered for a constraint, an error message is shown.
245Up to 2000 atomic constraints may be entered.
246EXPGUI does not warn if you exceed this limit.
249<a name="multiplehistogram">
250<h2>7. Multiple Histogram Selection</h2></a>
252This mode allows parameters to be changed for groups of
254When the "Multiple Histogram Selection" mode is off,
255it is possible to modify parameters
256and refinement flags for only a single histogram, but
257the other settings allow groups of histograms
258to be selected and modified.
259<A href="#mouseactions">(see Mouse Actions)</A>.
261It does not make sense, however, to globally modify
262instrument-related parameters and flags for different
263histogram types.
264So global actions can be limited to a single class
265of histogram types (e.g. TOF, CW Neutron,...), which
266allows these parameters to be set for groups of
267similar histograms. Thus, if this mode is set to "All"
268the Histogram and Profile panels are disabled.
270The setting for "Multiple Histogram Selection" mode is
271selected using the "Multiple Hist. Selection" item on the
272Options menu to create a submenu. Also on this submenu is an option
273"Group Phases Together" that controls how EXPGUI treats phases having
274the same profile type when multiple histograms are selected. If
275the "Group Phases Together" option is on, then the refinement flags for
276all phases with the same histogram types are grouped together, when possible.
277If this option is off, phases are treated separately.
279<a name="mouseactions">
281<h2>8. Mouse Actions</h2></a>
283A range of atoms or (in multiple selection mode) histograms may be
284selected by dragging (holding down) the left mouse button. It is also
285possible to select a range by using the Shift key with the left mouse
286button. To select or deselect individual entries, use the Control key
287with the left mouse button. Pressing the right mouse button selects all
288entries in a list.
291<h2>9. Menus</h2>
292A description of the EXPGUI menus follows along with a very
293brief description of the function of each menu option.
294Note that an option may appear under more than one menu.
295<H3>9.1 File Menu</H3>
297The options on the File menu as is the custom contains the commands
298for reading and writing experiment files, as well as starting
299and ending the program.
302        Select an existing GSAS experiment to be used. If a name is entered
303        that does not exists, it is possible to create a new
304        experiment file from scratch.
305<DT>Save<DD>Saves modifications to the current experiment file to disk (shortcut Alt-S).
306<DT>Save As<DD>Saves modifications to the current experiment file to disk
307        under a new file name
308<DT>Reread .EXP file<DD>Reread the last saved version of the experiment file from disk.
309<DT>EraseHistory<DD>Deletes old history records to speed reading of the .EXP file.
310<DT>convert<DD>Convert a standard ASCII file to the direct access format used by GSAS (and for UNIX, the reverse)
311<DT>exit<DD>Exit EXPGUI (shortcut Alt-X or ^C)
313<img SRC="m1.gif" BORDER=3 >
316<h3>9.2 Options Menu</h3>
318This menu contains options that determine how EXPGUI runs.
320<DT>archive EXP<DD>Toggles archiving of .EXP files. When on, files are
321        saved prior to each save or run of expedt in a file named
322        [expnam] where xxx = 000, 001 (UNIX)
323        or in a file named [expnam].ZIP or  [expnam].xxx (Windows)
324<DT>Use DISAGL Window<DD>When this option is set, results from DISAGL are
325         shown in a separate window. When it is not set, the results are
326        written in the .LST file.
327<DT>Sort atoms by<DD>   Determines the order that atoms are displayed on the "Phase" page
328        Atoms may be displayed sorted by atom number, atom type,
329        or by x, y or z
331<DT>Sort histograms by<DD>Determines the order that histograms are displayed on the
332        Histogram, Scaling and Profile pages
334        Histograms may be sorted by histogram number, histogram type,
335        original bank number, or diffraction angle/wavelength
336<DT><A href="#multiplehistogram">Multiple hist. selection</A><DD>
337        When this mode is off, it is possible to modify parameters
338        and refinement flags for only a single histogram. For other settings,
339        it is possible to modify parameters and flags for groups of
340        histograms (see help for Mouse actions).
342        It does not make sense, however, to globally modify
343        instrument-related parameters and flags for different histogram types.
344        So global actions can be limited to a single class of histogram types
345        (e.g. TOF, CW Neutron,...), which allows these parameters to be set
346        for groups of similar histograms. Thus, if this mode is set to "All"
347        the Histogram and Profile pages are disabled.
348<DT>Override backspace<DD>This option is available in UNIX only, as there are different
349        ways that backspace can be implemented. When option is set
350        as "On," the backspace key is overridden to send a "delete"
351        character. If backspace does not work in a program such as
352        EXPEDT, change try the other setting for this option.
353<DT>Autoupdate EXP<DD>Normally EXPGUI prompts before rereading the EXP
354file when GENLES, POWPREF,... are run (this is so that one can change
355the experiment file and rerun with the current input). If this option is
356set, the new file is automatically read without a prompt.
357This option is not available in Windows.
359<DT>SaveOptions<DD>Save the current values for "Override backspace",
360        "Sort atoms by", "Sort histograms by" and "archive EXP"
361        in file ~/.gsas_config (c:\.gsas_config on Windows).
362<DT>liveplot_options<DD>Used to set options for liveplot,
363for example, the histogram to be plotted
365<img SRC="m2.gif"  BORDER=3>
368<h3>9.3 Powder Menu</h3>
370This menu contains links to GSAS programs used for powder diffraction
373<DT>expedt<DD>Run GSAS experiment editor (shortcut Alt-E)
374<DT>powpref<DD>Powder data preparation (shortcut Alt-P)
375<DT>genles<DD>Run GSAS experiment editor (shortcut Alt-G)
376<DT>powplot<DD>Display powder patterns
377<DT>rawplot<DD>Plot powder data
378<DT>fitspec<DD>Fit a TOF vanadium scattering spectrum
379<DT>tofnorm<DD>Normalize a TOF spectrum
381<img SRC="m3.gif"  BORDER=3>
384<h3>9.4 Single Crystal Menu</h3>
386This menu contains links to GSAS programs used for
387single-rystal diffraction analysis.
389<DT>expedt<DD>Run GSAS experiment editor (shortcut Alt-E)
390<DT>genles<DD>Run GSAS experiment editor (shortcut Alt-G)
391<DT>scabs<DD>Single crystal absorption
392<DT>scmerge<DD>Sort and merge single crystal data
393<DT>sxtldata<DD>Prepare generic single crystal data
395<img SRC="m4.gif"  BORDER=3>
398<h3>9.5 Graphics Menu</h3>
400This menu contains links to several GSAS and
401two non-GSAS (liveplot and widplt)
402programs used for graphical display of data and results.
404<DT>forplot<DD>Display Fourier maps (set Fourier options in EXPEDT
405        and then compute with FOURIER
406<DT>polfplot<DD>Display polefigures
407<DT>powplot<DD>Display powder patterns
408<DT>ortep<DD>Draw crystal structure
409<DT>rawplot<DD>Plot powder data
410<DT>fourier<DD>Generate Fourier map
411<DT>forsrh<DD>Search Fourier map for peaks
412<DT>liveplot<DD>Create a plot of powder data
413with zooming, automatic update and other nice features.
414<DT>vrstplot<DD>Create a VRML 3-D file for viewing with 3rd party software
415<DT>widplt<DD>Displays the FWHM as a function of Q, 2Theta,... for UVWXY values input or read from an EXP file
417<img SRC="m5.gif"  BORDER=3>
420<h3>9.6 Results Menu</h3>
422This menu contains links to several GSAS and
423one non-GSAS (lstview)
424programs used for analysis of results.
426<DT>bijcalc<DD>Thermal parameter analysis
427<DT>disagl<DD>Distance/angle calculations
428<DT>reflist<DD>List reflection data
429<DT>geometry<DD>Molecular geometry calculations
430<DT>hstdmp<DD>List powder histogram data
431<DT>istats<DD>HKL Intensity statistics
432<DT>rcalc<DD>Compute reflection resuduals
433<DT>composition<DD>Computes the chemical composition of a unit cell
434accounting for site multiplicies and occupancies
435<DT>lstview<DD>Create a box with scrollbars containing the current .LST file
437<img SRC="m6.gif"  BORDER=3>
440<h3>9.7 Calculations Menu</h3>
442This menu contains programs for useful crystallographic computations.
444<DT>cllchg<DD>Transform unit cell
445<DT>fprime<DD>Compute f, f', f'' and mu/rho for an element for a range of x-ray wavelengths
446<DT>rducll<DD>Unit cell reduction
447<DT>spcgroup<DD>Space group symbol interpreter
448<DT>unimol<DD>Unique molecule assembler
450<img SRC="m7.gif" BORDER=3>
453<h3>9.8 Import/Export Menu</h3>
455This menu contains utilities for importing information into GSAS and
458<DT>exp2xtl<DD>Prepare a .XTL format file of atomic positions. This
459file is used in MSI software such as Cerius and InsightII.
460<DT>gsas2cif<DD>Prepare IUCr crystallographic information (CIF) file
461<DT>hklsort<DD>Prepare HKL tables
462<DT>pubtable<DD>Prepare atom parameter tables
463<DT>convert<DD>Convert a standard ASCII file to the direct access format used by GSAS (and for UNIX, the reverse)
464<DT>cad4rd<DD>Prepare CAD4 single crystal data
465<DT>dbwscnv<DD>Convert a powder diffraction data file from DBWS format
466<DT>x17bcnv<DD>Convert an energy dispersive diffractogram data file from NSLS X17b
467<DT>p3r3data<DD>Prepare Siemens/Brucker P3R3 single crystal data
468<DT>sxtldata<DD>Prepare generic single crystal data
470<img SRC="m8.gif"  BORDER=3>
473<h2>10. EXPGUI Utility Programs</h2></a>
477<P>lstview is used to browse through the GSAS output listing. It is
478invoked by the "lstview" command in the GUI.
479<CENTER><IMG SRC="textview.gif"></CENTER>
484<P>liveplot shows the observed, calculated and difference plots for powder
485refinements. The plot is updated as the refinement progresses. The mouse can
486be used to zoom in on sections of the plot.
487Liveplot uses the <A href="#blt">BLT</A> graphics package.
488<CENTER><IMG SRC="liveplot.gif"></CENTER>
489<IMG SRC="new.gif" HEIGHT=13 WIDTH=36>
490LIVEPLOT can now be enhanced to superimpose peak locations for
491input unit cells or peaks from JCPDS/ICDD entries.
492See the <A HREF="expgui_cfg.html#liveplot">
493LIVEPLOT customization information</A> 
494or read file <tt>expgui_cfg.html</tt> in the <tt>gsas/tcl/doc</tt> directory.
496LIVEPLOT gets the current diffraction information by running the TCLDUMP program, if installed, or
497HSTDUMP otherwise. The TCLDUMP program has been optimized for use with LIVEPLOT and offers a number of extra
498options that are not available when HSTDUMP is used: plots can be displayed in the native units (2Theta/TOF/KeV), or
499in d-space or Q; fixed plus fitted background curves are shown in green; if reflection tickmarks are displayed,
500reflection tickmarks can be displayed by holding the shift key while pressing the left mouse button.
501See the installation instructions for installing TCLDUMP.
504<P>WIDPLT can be used to plot the actual peak widths generated by the profile
505parameters used in GSAS.
506It is possible to define reference curves
507that are loaded automatically.
508WIDPLT uses the <A href="#blt">BLT</A> graphics package.
509<CENTER><IMG SRC="widplt.gif"></CENTER>
513<A name=blt>
516The BLT graphics package is used by the WIDPLT and LIVEPLOT routines. If the
517package can not be loaded these routines, an error message,
518"Error -- Unable to load the BLT package", will be displayed. A frequent
519problem is the package is installed, but not configured so that common
520support routines are loaded automatically. If this is the case,
521a message, "BLT Setup Error: could not access a Blt_ routine...",
522will be displayed.
523Please see
524<A HREF="">
526</A> for more information on installation of BLT.
530Praise to Larson and
531<A HREF="">
532Von Dreele</A> for GSAS, <A HREF="">Ousterhout</A>
533for Tcl/Tk,
534Przemek Klosowski</A>
535for convincing me to learn Tcl/Tk
536and Jonathan Wasserman for starting this project.
538<A Href="">
540is written by Allen C. Larson and <A HREF="">
541Robert B. Von Dreele</A>, MS-H805,
542Los Alamos National Laboratory, Los Alamos, NM 87545. Problems, questions
543or kudos concerning GSAS should be sent to Robert B. Von Dreele at
544<A HREF=""></A>
545<P>GSAS is Copyright, 1984-1997, The Regents of the University of California.
546The GSAS software was produced under a U.S. Government contract (W-7405-ENG-36)
547by the Los Alamos National Laboratory, which is operated by the University
548of California for the U.S. Department of Energy. The U.S. Government is
549licensed to use, reproduce, and distribute this software. Permission is
550granted to the public to copy and use this software without charge, provided
551that this notice and any statement of authorship are reproduced on all
552copies. Neither the Government nor the University makes any warranty, express
553or implied, or assumes any liability or responsibility for the use of this
555<P>EXPGUI is written by Brian H. Toby of the NIST Center for Neutron Research,
556<A HREF="MAILTO:Brian.Toby@NIST.GOV">Brian.Toby@NIST.GOV</A> 
557with help from Jonathan Wasserman.
559<P>EXPGUI is not subject to copyright. Have fun with it.
561<p>Neither the U.S. Government nor any author makes any warranty,
562expressed or implied, or assumes any liability or responsibility
563for the use of this information or the software described
564here. Brand names cited here are used for
565identification purposes and do not consitute an endorsement by NIST.
567<p><a href="">Brian Toby</a> (<a href="">Brian.Toby@NIST.GOV</a>)
569$Revision: 148 $ $Date: 2009-12-04 23:01:12 +0000 (Fri, 04 Dec 2009) $
Note: See TracBrowser for help on using the repository browser.