source: trunk/doc/expgui.html @ 213

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

# on 2000/06/09 03:53:28, toby did:
Add Pref Orientation Section
Renumber and reorganize sections
quick revisions

  • Property rcs:author set to toby
  • Property rcs:date set to 2000/06/09 03:53:28
  • Property rcs:lines set to +145 -101
  • Property rcs:rev set to 1.12
  • Property rcs:state set to Exp
  • Property svn:keywords set to Author Date Revision Id
File size: 24.6 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:
34it can be used to directly modify the GSAS
35experiment file with a graphical user interface (GUI) and
36it can be used to invoke the programs inside the
37GSAS package such as EXPEDT, GENLES, FOURIER...
38These programs can be run from a menu or in many cases by pressing buttons.
41This documentation describes the different actions that
42can be accomplished with the different panes and the
43contents of the menus. Other documents about EXPGUI are:
44<a name="installation"></A>
45<A HREF="expgui_Win_readme.html">
46Installation notes for Windows</A>,
47<A HREF="expgui_Unix_readme.html">
48Installation notes for UNIX</A>,
49<A HREF="expgui_cfg.html">
50Customization notes</A> and two example tutorials: for
51<A HREF="tutorial1/index.html">
54<A HREF="tutorial2/index.html">
55constant-wavelength neutron</A>.
56Note that screen images in this document are not updated as frequently as the
60<h2>A. Experiment file editing</h2>
62Different sections of the .EXP file can be edited by selecting different
63panes ("pages" or "panels") from the tabbed list.
65<br>The notebook pane tabs.
66<br><img SRC="panebar1.gif"  BORDER=3 >
70<h3>A.1 Least Squares (LS) Controls Pane</h3>
72<p>The LS Controls pane shows information about the
73current experiment, typically found in the EXPEDT "Least
74Squares Controls" options.
76Note that the order that histograms appear in this
77pane is determined by the
78<a href="http:#sorthist">"Sort histograms by"</a> option in
79the Options Menu.
80<img SRC="1.gif" align=TEXTTOP>
84<h3>A.2 Phase Pane</h3> 
86The phase pane is used to edit information
87about the structural model(s) found in the experiment
88file. The flags for refining the unit cell and atomic parameters,
89as well as ther damping values,
90can be set  on this pane. Note that if a
91single atom is selected using the mouse, the information
92for that atom can be edited. If a group of atoms is
94<A href="#mouseactions">(see Mouse Actions)</A>
95the damping and refinement flags
96for all the selected atoms are changed.
98If the EXPTOOL program
99<A href="#installation">(see the installation instructions)</A>
100is installed, buttons for adding phases and atoms will
101appear on this pane, as seen below. If the
102program is not properly installed, no errors occur, but the buttons
103do not appear.
105Note that the order that atoms appear in this pane is
106determined by the
107<a href="http:#sortatoms">"Sort Atoms by"</a> option in the Options Menu.
108<img SRC="2.gif" align=TEXTTOP>
111<h3>A.3 Histogram pane</h3> 
113The histogram pane is used to edit background
114and diffractometer constants for a histogram, as well as
115set damping and refinement flags for these parameters.
118<A href="#multiplehistogram">
119"Multiple Histogram Selection" mode</A> is set to "All",
120this pane is disabled. For other settings of this mode,
121groups of histograms can be selected and modified
124If the EXPTOOL program
125<A href="#installation">(see the installation instructions)</A>
126is installed, a button for adding histograms will
127appear on the bottom right on this pane, as seen below. If the
128program is not properly installed, no errors occur, but the button
129does not appear.
131Note that the order that histograms appear in this
132pane is determined by the <a href="http:#sorthist">"Sort histograms by"</a> option in
133the Options Menu.
134<img SRC="3.gif" align=TEXTTOP>
137<h3>A.4 Scaling pane</h3> 
139The Scaling pane is used to edit the scale factor for a
140histogram as well as the phase fractions for each phase
141present in that histogram. Damping and refinement flags
142for the scaling terms can also be set here.
145<A href="#multiplehistogram">
146"Multiple Histogram Selection" mode</A> is set to
147any value other than "Off,"
148groups of histograms can be selected and modified
151Note that the order that histograms appear in this
152pane is determined by the <a href="http:#sorthist">"Sort histograms by"</a> option in
153the Options Menu.
154<img SRC="4.gif" align=TEXTTOP>
157<h3>A.5 Profile pane</h3> 
159The Profile pane is used to edit the profile values for
160each phase present in a histogram as well as set
161the refinement flags and a damping value for each phase.
164<A href="#multiplehistogram">
165"Multiple Histogram Selection" mode</A> is set to "All",
166this pane is disabled. For other settings of this mode,
167profile values and settings can be collectively
168modified for groups of histograms.
170Note that the order that histograms appear in this
171pane is determined by the
172<a href="http:#sorthist">"Sort histograms by"</a> option in
173the Options Menu.
174<img SRC="5.gif" align=TEXTTOP>
177<h3>A.6 Constraints pane</h3>
179GSAS offers two types of restraints that can be included in a model.
180So called "soft constraints" or "restraints" penalize the fit if
181aspects of a model (for example, bond lengths) differ from selected values.
182So called "hard constraints" reduce the actual number of
183parameters in a model,
184by grouping parameters so that a single shift (possibly scaled) is
185applied to each parameter in the group.
186The constraints pane is used to set these "hard constraints."
187At this time the only constraints that can be set in EXPGUI are on atomic
188parameters (others can be set in EXPEDT).
190Note that these constraints are only applied to shifts but not to the
191actual values. This means that, for example,
192if two atoms
193are constrained so that the shift on their occupancy is the same, but
194the initial occupancies differ, the in occupancy difference will not change
195as the values refine.
197<H4>Atom Constraints</H4>
198The atom constraints editing pane appears below. Note that constraints can
199be listed sorted by constraint number, phase number, lowest atom number or
200variable by clicking on the buttons at the top of the pane.
202To delete one or more constraints, click on the appropriate checkbuttons in the <B>Delete</B> column and the press the Delete button, below.
203<img SRC="mc.gif" align=TEXTTOP>
204Due to the way GSAS implements these constraints, a parameter can be included
205in only one constraint. Should one or more parameters be constrained twice,
206an error message is shown as shown below.
207Note that the constraint number is displayed as red, for constraints that
208have conflicts in the constraints editing pane (see above.)
209<img SRC="mcerr.gif" align=TEXTTOP>
211<img SRC="mcedit.gif" align=LEFT>
212<img SRC="mcvar.gif" align=RIGHT>
213When the edit button for a constraint is pressed, the constraint is
214opened for editing. Controls are available to select the phase, variable,
215multiplier and atom(s). Note that for atom selection, use of the control key
216and the left mouse button allow individual atoms to be selected or deselected.
217Shift and the left mouse button allow ranges of atoms to be selected and the
218right mouse button selects all atoms
219<A href="#mouseactions">(see Mouse Actions)</A>.
221Note that it is inappropriate
222to constrain different types of parameters together, for example X and Uiso.
223The left-most variable button is the "master" which
224determines what variable are allowed in the
225other variable buttons.
227When the "New Constraint" button is pressed, a blank constraint editing
228window is opened. Note that any variable to the right may then be selected,
229including two special codes, Uxx and XYZU. XYZU creates four constraints,
230requiring the shifts on x, y, z and Uiso to be the same for all the selected
231atoms. Uxx does the same for the six anisotropic displacement parameters.
232These special codes are valuable for atoms that share a site.
234Note that only 100 parameters may be included in a constraint,
235with one exception. When shifts for Uiso for all atoms in a phase
236are constrained, this counts as a single parameter. If more than 100
237parameters are entered for a constraint, an error message is shown.
238Up to 2000 atomic constraints may be entered.
239EXPGUI does not warn if you exceed this limit.
243<h3>A.7 Preferential Orientation Pane</h3></a>
244The Preferential Orientation Pane is used to control parameters related
245to fitting parameters using the March-Dollase formulation
246for preferred orientation. In this model one or more axes are designated
247as directions [designated by (<i>hkl</i>)] where crystallites are over
248(Ratio > 1) or underrepresented (Ratio < 1).
249The checkbox to the right of the Ratio value determines if it will 
250be refined.
251<img SRC="po1.gif" align=TEXTTOP>
252If more than one axis is present, one must define the relative fraction
253of preferred orientation for each direction. These fractions are normalized,
254so do not vary the fractions for all directions in a phase.
255<img SRC="po2.gif" align=TEXTTOP>
257<A href="#multiplehistogram">
258"Multiple Histogram Selection" mode</A> is set to any value other than
259"Off", all terms are displayed for all selected histograms.
260No attempt is made to group terms or flags.
262Note that the other model for treating preferred orientation -- the orientation
263distribution function (spherical harmonics) is not yet implemented
264in EXPGUI and must be accessed from EXPEDT.
267<h2>B. Shortcuts</h2></a>
268<a name="multiplehistogram">
269<h3>B.1 Multiple Histogram Selection</h3></a>
271This mode allows parameters to be changed for groups of
273When the "Multiple Histogram Selection" mode is off,
274it is possible to modify parameters
275and refinement flags for only a single histogram, but
276the other settings allow groups of histograms
277to be selected and modified.
278<A href="#mouseactions">(see Mouse Actions)</A>.
280It does not make sense, however, to globally modify
281instrument-related parameters and flags for different
282histogram types.
283So global actions can be limited to a single class
284of histogram types (e.g. TOF, CW Neutron,...), which
285allows these parameters to be set for groups of
286similar histograms. Thus, if this mode is set to "All"
287the Histogram and Profile panes are disabled.
289The setting for "Multiple Histogram Selection" mode is
290selected using the "Multiple Hist. Selection" item on the
291Options menu to create a submenu. Also on this submenu is an option
292"Group Phases Together" that controls how EXPGUI treats phases having
293the same profile type when multiple histograms are selected. If
294the "Group Phases Together" option is on, then the refinement flags for
295all phases with the same histogram types are grouped together, when possible.
296If this option is off, phases are treated separately.
298<a name="mouseactions">
300<h3>B.2 Mouse Actions</h3></a>
302A range of atoms or (in multiple selection mode) histograms may be
303selected by dragging (holding down) the left mouse button. It is also
304possible to select a range by using the Shift key with the left mouse
305button. To select or deselect individual entries, use the Control key
306with the left mouse button. Pressing the right mouse button selects all
307entries in a list.
310<h2>C. Menu Commands and Programs</h2>
312GSAS programs are invoked either through use of the menu bar
314<br>The menu bar.
315<br><img SRC="menubar.gif" BORDER=3 >
317or by "pressing" a button on the button bar. The button bar
318simply provides an easy way to access commonly used
319actions on the menu bar. Users can
320<A HREF="expgui_cfg.html">
321configure the menu bar</A> to include their own preferred actions and, with
322some knowledge of the program and Tcl/Tk,
323add their own commands to the menu bar or button bar.
326<br>The button bar.
327<br><img SRC="buttonbar.gif" BORDER=3 >
330A description of the EXPGUI menus follows along with a very
331brief description of the function of each menu option.
332Note that an option may appear under more than one menu.
333<H3>C.1 File Menu</H3>
335The options on the File menu as is the custom contains the commands
336for reading and writing experiment files, as well as starting
337and ending the program.
340        Select an existing GSAS experiment to be used. If a name is entered
341        that does not exists, it is possible to create a new
342        experiment file from scratch.
343<DT>Save<DD>Saves modifications to the current experiment file to disk (shortcut Alt-S).
344<DT>Save As<DD>Saves modifications to the current experiment file to disk
345        under a new file name
346<DT>Reread .EXP file<DD>Reread the last saved version of the experiment file from disk.
347<DT>EraseHistory<DD>Deletes old history records to speed reading of the .EXP file.
348<DT>convert<DD>Convert a standard ASCII file to the direct access format used by GSAS (and for UNIX, the reverse)
349<DT>exit<DD>Exit EXPGUI (shortcut Alt-X or ^C)
351<img SRC="m1.gif" BORDER=3 >
354<h3>C.2 Options Menu</h3>
356This menu contains options that determine how EXPGUI runs.
358<DT>archive EXP<DD>Toggles archiving of .EXP files. When on, files are
359        saved prior to each save or run of expedt in a file named
360        [expnam] where xxx = 000, 001 (UNIX)
361        or in a file named [expnam].ZIP or  [expnam].xxx (Windows)
362<DT>Use DISAGL Window<DD>When this option is set, results from DISAGL are
363         shown in a separate window. When it is not set, the results are
364        written in the .LST file.
365<a name="sortatoms"></a><DT>Sort atoms by<DD>   Determines the order that atoms are displayed on the "Phase" pane
366        Atoms may be displayed sorted by atom number, atom type,
367        or by x, y or z
369<a name="sorthist"></a><DT>Sort histograms by<DD>Determines the order that histograms are displayed on the
370        Histogram, Scaling and Profile panes
372        Histograms may be sorted by histogram number, histogram type,
373        original bank number, or diffraction angle/wavelength
374<DT><A href="#multiplehistogram">Multiple hist. selection</A><DD>
375        When this mode is off, it is possible to modify parameters
376        and refinement flags for only a single histogram. For other settings,
377        it is possible to modify parameters and flags for groups of
378        histograms (see help for Mouse actions).
380        It does not make sense, however, to globally modify
381        instrument-related parameters and flags for different histogram types.
382        So global actions can be limited to a single class of histogram types
383        (e.g. TOF, CW Neutron,...), which allows these parameters to be set
384        for groups of similar histograms. Thus, if this mode is set to "All"
385        the Histogram and Profile panes are disabled.
386<DT>Override backspace<DD>This option is available in UNIX only, as there are different
387        ways that backspace can be implemented. When option is set
388        as "On," the backspace key is overridden to send a "delete"
389        character. If backspace does not work in a program such as
390        EXPEDT, change try the other setting for this option.
391<DT>Autoupdate EXP<DD>Normally EXPGUI prompts before rereading the EXP
392file when GENLES, POWPREF,... are run (this is so that one can change
393the experiment file and rerun with the current input). If this option is
394set, the new file is automatically read without a prompt.
395This option is not available in Windows.
397<DT>SaveOptions<DD>Save the current values for "Override backspace",
398        <a href="http:#sortatoms">"Sort atoms by"</a>,
399        <a href="http:#sorthist">"Sort histograms by"</a> and "archive EXP"
400        in file ~/.gsas_config (c:\.gsas_config on Windows).
401<DT>liveplot_options<DD>Used to set options for liveplot,
402for example, the histogram to be plotted
404<img SRC="m2.gif"  BORDER=3>
407<h3>C.3 Powder Menu</h3>
409This menu contains links to GSAS programs used for powder diffraction
412<DT>expedt<DD>Run GSAS experiment editor (shortcut Alt-E)
413<DT>powpref<DD>Powder data preparation (shortcut Alt-P)
414<DT>genles<DD>Run GSAS experiment editor (shortcut Alt-G)
415<DT>powplot<DD>Display powder patterns
416<DT>rawplot<DD>Plot powder data
417<DT>fitspec<DD>Fit a TOF vanadium scattering spectrum
418<DT>tofnorm<DD>Normalize a TOF spectrum
420<img SRC="m3.gif"  BORDER=3>
423<h3>C.4 Single Crystal Menu</h3>
425This menu contains links to GSAS programs used for
426single-rystal diffraction analysis.
428<DT>expedt<DD>Run GSAS experiment editor (shortcut Alt-E)
429<DT>genles<DD>Run GSAS experiment editor (shortcut Alt-G)
430<DT>scabs<DD>Single crystal absorption
431<DT>scmerge<DD>Sort and merge single crystal data
432<DT>sxtldata<DD>Prepare generic single crystal data
434<img SRC="m4.gif"  BORDER=3>
437<h3>C.5 Graphics Menu</h3>
439This menu contains links to several GSAS and
440two non-GSAS (liveplot and widplt)
441programs used for graphical display of data and results.
443<DT>forplot<DD>Display Fourier maps (set Fourier options in EXPEDT
444        and then compute with FOURIER
445<DT>polfplot<DD>Display polefigures
446<DT>powplot<DD>Display powder patterns
447<DT>ortep<DD>Draw crystal structure
448<DT>rawplot<DD>Plot powder data
449<DT>fourier<DD>Generate Fourier map
450<DT>forsrh<DD>Search Fourier map for peaks
451<DT>liveplot<DD>Create a plot of powder data
452with zooming, automatic update and other nice features.
453<DT>vrstplot<DD>Create a VRML 3-D file for viewing with 3rd party software
454<DT>widplt<DD>Displays the FWHM as a function of Q, 2Theta,... for UVWXY values input or read from an EXP file
456<img SRC="m5.gif"  BORDER=3>
459<h3>C.6 Results Menu</h3>
461This menu contains links to several GSAS and
462one non-GSAS (lstview)
463programs used for analysis of results.
465<DT>bijcalc<DD>Thermal parameter analysis
466<DT>disagl<DD>Distance/angle calculations
467<DT>reflist<DD>List reflection data
468<DT>geometry<DD>Molecular geometry calculations
469<DT>hstdmp<DD>List powder histogram data
470<DT>istats<DD>HKL Intensity statistics
471<DT>rcalc<DD>Compute reflection resuduals
472<DT>composition<DD>Computes the chemical composition of a unit cell
473accounting for site multiplicies and occupancies
474<DT>lstview<DD>Create a box with scrollbars containing the current .LST file
476<img SRC="m6.gif"  BORDER=3>
479<h3>C.7 Calculations Menu</h3>
481This menu contains programs for useful crystallographic computations.
483<DT>cllchg<DD>Transform unit cell
484<DT>fprime<DD>Compute f, f', f'' and mu/rho for an element for a range of x-ray wavelengths
485<DT>rducll<DD>Unit cell reduction
486<DT>spcgroup<DD>Space group symbol interpreter
487<DT>unimol<DD>Unique molecule assembler
489<img SRC="m7.gif" BORDER=3>
492<h3>C.8 Import/Export Menu</h3>
494This menu contains utilities for importing information into GSAS and
497<DT>exp2xtl<DD>Prepare a .XTL format file of atomic positions. This
498file is used in MSI software such as Cerius and InsightII.
499<DT>gsas2cif<DD>Prepare IUCr crystallographic information (CIF) file
500<DT>hklsort<DD>Prepare HKL tables
501<DT>pubtable<DD>Prepare atom parameter tables
502<DT>convert<DD>Convert a standard ASCII file to the direct access format used by GSAS (and for UNIX, the reverse)
503<DT>cad4rd<DD>Prepare CAD4 single crystal data
504<DT>dbwscnv<DD>Convert a powder diffraction data file from DBWS format
505<DT>x17bcnv<DD>Convert an energy dispersive diffractogram data file from NSLS X17b
506<DT>p3r3data<DD>Prepare Siemens/Brucker P3R3 single crystal data
507<DT>sxtldata<DD>Prepare generic single crystal data
509<img SRC="m8.gif"  BORDER=3>
512<h2>D. EXPGUI Utility Programs</h2></a>
516<P>lstview is used to browse through the GSAS output listing. It is
517invoked by the "lstview" command in the GUI.
518<CENTER><IMG SRC="textview.gif"></CENTER>
523<P>liveplot shows the observed, calculated and difference plots for powder
524refinements. The plot is updated as the refinement progresses. The mouse can
525be used to zoom in on sections of the plot.
526Liveplot uses the <A href="#blt">BLT</A> graphics package.
527<CENTER><IMG SRC="liveplot.gif"></CENTER>
528<IMG SRC="new.gif" HEIGHT=13 WIDTH=36>
529LIVEPLOT can now be enhanced to superimpose peak locations for
530input unit cells or peaks from JCPDS/ICDD entries.
531See the <A HREF="expgui_cfg.html#liveplot">
532LIVEPLOT customization information</A> 
533or read file <tt>expgui_cfg.html</tt> in the <tt>gsas/tcl/doc</tt> directory.
535LIVEPLOT gets the current diffraction information by running the TCLDUMP program, if installed, or
536HSTDUMP otherwise. The TCLDUMP program has been optimized for use with LIVEPLOT and offers a number of extra
537options that are not available when HSTDUMP is used: plots can be displayed in the native units (2Theta/TOF/KeV), or
538in 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>
539reflection tickmarks can be displayed by pressing "H" or "h" while the
540mouse is near a reflection (holding the shift key while
541pressing the left mouse button also works).
542See the installation instructions for installing TCLDUMP.
545<P>WIDPLT can be used to plot the actual peak widths generated by the profile
546parameters used in GSAS.
547It is possible to define reference curves
548that are loaded automatically.
549WIDPLT uses the <A href="#blt">BLT</A> graphics package.
550<CENTER><IMG SRC="widplt.gif"></CENTER>
554<A name=blt>
557The BLT graphics package is used by the WIDPLT and LIVEPLOT routines. If the
558package can not be loaded these routines, an error message,
559"Error -- Unable to load the BLT package", will be displayed. A frequent
560problem is the package is installed, but not configured so that common
561support routines are loaded automatically. If this is the case,
562a message, "BLT Setup Error: could not access a Blt_ routine...",
563will be displayed.
564Please see
565<A HREF="">
567</A> for more information on installation of BLT.
571Praise to Larson and
572<A HREF="">
573Von Dreele</A> for GSAS, <A HREF="">Ousterhout</A>
574for Tcl/Tk,
575Przemek Klosowski</A>
576for convincing me to learn Tcl/Tk
577and Jonathan Wasserman for helping get this project started.
578Large sections of the Preferred Orientation GUI were written by
579Pamela Whitfield of the NRC (Canada).
581<A Href="">
583is written by Allen C. Larson and <A HREF="">
584Robert B. Von Dreele</A>, MS-H805,
585Los Alamos National Laboratory, Los Alamos, NM 87545. Problems, questions
586or kudos concerning GSAS should be sent to Robert B. Von Dreele at
587<A HREF=""></A>
588EXPGUI is written by Brian H. Toby of the NIST Center for Neutron Research,
589<A HREF="MAILTO:Brian.Toby@NIST.GOV">Brian.Toby@NIST.GOV</A> 
590with help from Jonathan Wasserman.
592<P>GSAS is Copyright, 1984-2000, by
593the Regents of the University of California.
594The GSAS software was produced under a U.S. Government contract (W-7405-ENG-36)
595by the Los Alamos National Laboratory, which is operated by the University
596of California for the U.S. Department of Energy. The U.S. Government is
597licensed to use, reproduce, and distribute this software. Permission is
598granted to the public to copy and use this software without charge, provided
599that this notice and any statement of authorship are reproduced on all
600copies. Neither the Government nor the University makes any warranty, express
601or implied, or assumes any liability or responsibility for the use of this
604<P>EXPGUI is not subject to copyright. Have fun with it. Modify it. Write
605new sections and make them available to the reset of the world.
607<p>Neither the U.S. Government nor any author makes any warranty,
608expressed or implied, or assumes any liability or responsibility
609for the use of this information or the software described
610here. Brand names cited here are used for
611identification purposes and do not consitute an endorsement by NIST.
613<p><a href="">Brian Toby</a> (<a href="">Brian.Toby@NIST.GOV</a>)
615$Revision: 202 $ $Date: 2009-12-04 23:02:06 +0000 (Fri, 04 Dec 2009) $
Note: See TracBrowser for help on using the repository browser.