source: trunk/doc/expgui_cfg.html @ 84

Last change on this file since 84 was 81, checked in by toby, 13 years ago

# on 1999/04/08 20:39:33, toby did:
Add new liveplot features
refer to tcldump

  • Property rcs:author set to toby
  • Property rcs:date set to 1999/04/08 20:39:33
  • Property rcs:lines set to +63 -7
  • Property rcs:rev set to 1.5
  • Property rcs:state set to Exp
  • Property svn:keywords set to Author Date Revision Id
File size: 15.2 KB
Line 
1<HTML>
2<TITLE>
3Customizing EXPGUI and Associated Programs
4</TITLE>
5<HEAD>
6</HEAD>
7<BODY>
8
9<CENTER>
10<H2>
11Customizing EXPGUI and Associated Programs</H2></CENTER>
12
13The EXPGUI GSAS graphical user interface can be modified in many
14ways quite easily.
15This document describes how the GUI works and how to modify the menus without
16significant reprogramming.
17<P>
18<H3>EXPGUI</H3>
19The main GUI is created by file expgui, which in turn uses the following files
20sequentially:
21<UL>
22<LI><TT>readexp.tcl</TT>
23<LI><TT>gsascmds.tcl</TT>
24<LI><TT>gsasmenu.tcl</TT>
25</UL>
26Two additional files are read if they are found:
27<UL>
28<LI><TT>localconfig</TT>
29<LI><TT>.gsas_config</TT>
30</UL>
31<P>The first three files,
32(<TT>readexp.tcl</TT>, <TT>gsascmds.tcl</TT>, <TT>gsasmenu.tcl</TT>)
33must be located in the same directory where the <TT>expgui</TT> file is found.
34The <TT>localconfig</TT> file also is read from this directory, if it exists.
35The final file, <TT>.gsas_config</TT>, is read from the user's login directory (UNIX) or <TT>C:\</TT> (Windows).
36The <TT>localconfig</TT> and <TT>.gsas_config</TT> are intended to
37contain system-wide and user-level default values for parameters
38that are described in this document. Most routines have
39a "Save Options" command that writes some of the current parameters to
40file  <TT>.gsas_config</TT>. Note that information in <TT>.gsas_config</TT>
41overrides that in <TT>localconfig</TT>.
42No error occurs if either of these files are not found.
43
44<P>
45The <TT>readexp.tcl</TT> and <TT>gsascmds.tcl</TT> files contain
46tcl procedures that are
47used for more than one application, so it is convenient to place them
48in separate files. They are only of interest to someone trying to debug
49or add new functionality to expgui.
50<P>
51The <TT>gsasmenu.tcl</TT> file defines the contents of the
52menu bar, the contents of the
53button bar and definitions for each command. The contents of this file
54are designed to be modified and extended by users, either by editing the file,
55or by overridding definitions in the <TT>localconfig</TT> or
56<TT>.gsas_config</TT> files.
57
58The important variables defined in the <TT>gsasmenu.tcl</TT> file are:
59<DL><DL>
60<DT>expgui(menunames)<DD>
61This list defines the menu bar headings other than File, Options & Help
62<DT>expgui_menulist<DD>
63Each array element, e.g. expgui_menulist(file) and expgui_menulist(powder),
64defines commands to be added to a menu heading. Each command will appear
65as an array element in expgui_cmdlist.
66<DT>expgui_cmdlist<DD>
67Each array element, e.g. expgui_cmdlist(Save) or expgui_cmdlist(expnam)
68contains two items. The first defines a tcl procedure to be executed
69when the command is invoked, or "-" if no command will be invoked and
70the second contains help information describing what the command does.
71Note that when menu item is selected the variable cmd is set to the
72name of the command, so
73<PRE>
74    expgui_cmdlist(powpref) {{runGSASwEXP $cmd} {Powder data preparation}}
75</PRE>
76means that "runGSASwEXP powpref" will be invoked when powpref is invoked.
77. For example, when powpref is selected, the tcl command
78"runGSASwEXP $cmd" is invoked, where variable cmd is set to "powpref".
79<DT>expgui(buttonlist)<DD>
80This list defines the commands that will appear on the button bar where
81each item that appears on the button bar must have a matching pair of entries
82in expgui_cmdlist.
83Thus if the command
84<PRE>
85   set expgui(buttonlist) {expnam expedt genles ortep fourier forsrh forplot lstview}
86</PRE>
87is placed in the <TT>localconfig</TT> or <TT>.gsas_config</TT> files this will
88redefine the contents of the button bar.
89</DL></DL>
90
91In addition to the variables defined in the previous file, expgui, uses
92a small number of array for other configuration options. They are:
93<DL><DL>
94
95<DT>expgui(scriptdir)<DD>
96This determines where files such as <TT>readexp.tcl</TT>, etc.
97are located. This defaults to the location where <TT>expgui</TT> is located so
98it rarely needs to be changed.
99
100<DT>expgui(gsasdir)<DD>
101This contains the location of the GSAS directory, if it is not the
102parent director where expgui is found.
103This determines where a number of GSAS data files will be located. If expedt
104crashes when you try to add new atoms, this is probably wrong.
105
106<DT>expgui(gsasexe)<DD>
107This determines where the GSAS executable files are located.
108You might want to change this is you keep multiple versions of GSAS
109around or if you keep the GSAS files in a different location than
110the default or want to keep the tcl files somewhere other than
111in a subdirectory of the GSAS files.
112
113<DT>expgui(coordfont)<DD>
114Sets the font used for the coordinates scroll box
115
116<DT>expgui(histfont)<DD>
117Sets the font used for the histogram scroll box
118
119<DT>liveplot(hst)<DD>
120Sets the default histogram used for liveplot
121
122<DT>liveplot(legend)<DD>
123Sets the default value for display of the legend in liveplot
124
125</DL></DL>
126
127The following variables are written to <tt>.gsas_config</tt> when
128"Save Options" is used. These variables are all set from the GUI and therefore
129do not need to be edited manually.
130
131<DL><DL>
132<DT>expgui(archive)<DD>
133This defines the default state for the archive flag,
134where 0 is off and 1 is on. When archive is on, a copy of the .EXP file
135is saved before a new version of the file is saved and before EXPEDT is run.
136
137<DT>expgui(asorttype)<DD>
138This determines the atom sort mode.
139
140<DT>expgui(hsorttype)<DD>
141This determines the histogram sort mode.
142
143<DT>expgui(filesort)<DD>
144This determines the default file sorting mode for the expnam command.
145
146<DT>env(GSASBACKSPACE)<DD>
147Used only for UNIX: This determines if the default definition
148for the backspace key is overridden; some UNIX systems need this so that
149expedt and other terminal-oriented programs work correctly and
150other systems do not. You can toggle this option using the "sets an environment variable needed by the "Override Backspace" option on the file menu.
151
152</DL></DL>
153
154<HR><H3>LSTVIEW</H3>
155The <TT>localconfig</TT> and <TT>.gsas_config</TT> files are read, if present.
156The following options are available for customization in these files:
157<DL><DL>
158<DT>txtvw(menulength)<DD>
159This limits the number of entries that can
160exist in a menu. For example, the default is 25, so when more than 25 cycles
161are found in a .LST file, only the last 25 are listed in the
162"Go To"/cycle submenu.
163<DT>txtvw(maxchars)<DD>
164This limits the maximum number of
165characters that will be read from an existing .LST file to speed
166the start of the program. The default is ~1Mb
167for UNIX systems and ~200K for Windows.
168</DL></DL>
169
170The following variables are written to <tt>.gsas_config</tt> when
171"Save Options" is used. These variables can be set from the GUI and therefore
172do not need to be edited manually.
173
174<DL><DL>
175<DT>txtvw(followcycle)<DD>
176This sets the initial value for the
177"Auto Advance" button in the "Go To" menu. When this is true,
178the program will show the last cycle in the file. As new cycles are
179added, the "view" is advanced.
180
181<DT>txtvw(font)<DD>
182This sets the font used for LSTVIEW. See documentation on the font command in
183Tk for details on font naming.
184</DL></DL>
185
186One additional variable is present that I don't suggest using at present:
187<UL>
188<LI>plotvars: I am in the process of developing code that tracks
189and plots shifts and R values as a function cycle number. Setting plotvars to 1
190allows this code to be tested.
191</LI></UL>
192
193<hr><H3>LIVEPLOT</H3><A NAME="liveplot"></A>
194The <TT>localconfig</TT> and <TT>.gsas_config</TT> files are read, if present.
195Note that some of these options are relevant only if the tcldump program is
196present.
197<P>
198The following options are available for customization in these files:
199<DL><DL>
200<DT>peakinfo(flag<i>n</i>)<DD>
201These variables define if peak positions will be shown
202for reflections in phase "<i>n</i>". Reflections will be shown if
203the value is non-zero.
204
205<DT>peakinfo(color<i>n</i>)<DD>
206These variables define the default colors for
207reflections in phase "<i>n</i>"
208
209<DT>peakinfo(dashes<i>n</i>)<DD>
210These variables define if peaks will be dashed for
211reflections in phase "<i>n</i>" (UNIX only). Lines will be dashed if
212the value is non-zero.
213
214<DT>peakinfo(min<i>n</i>) and peakinfo(max<i>n</i>)<DD>
215These variables dictact the placement vertical position for reflection
216markers, when manually placed (see expgui(autotick), below). To draw
217to the edge of the screen, use -Inf and Inf.
218</DL></DL>
219
220The following variables are written to <tt>.gsas_config</tt> when
221"Save Options" is used. These variables are all set from the GUI and therefore
222do not need to be edited manually.
223
224<DL><DL>
225<DT>graph(printout)<DD>
226This is set to 1 if PostScript files
227will be printed and 0 if they will be written to disk (for Windows all
228files should be written to disk).
229
230<DT>graph(outname)<DD>
231This is the default for the file name used
232when PostScript files will be written to disk.
233
234<DT>graph(outcmd)<DD>
235This is the default for the command used
236to print PostScript files (Unix only).
237
238<DT>graph(legend)<DD>
239Sets the default value for display of the legend in liveplot and widplt.
240
241<DT>peakinfo(obssym)<DD>
242Symbol for observed data points. Valid choices are square, circle, diamond,
243plus, cross, splus and scross.
244
245<DT>peakinfo(obssize)<DD>
246Size for the symbol for observed data points. A value of 1 corresponds to about 1/8 inch
247(about 3 mm).
248
249<DT>expgui(pixelregion)<DD>
250When hkl values are loaded (using tcldump) and reflections are labeled, reflections
251can be labeled using a Shift-Left-Mouse click. All labeled reflections within expgui(pixelregion)
252pixels of the mouse position are assumed to be overlapped and are labeled.
253
254<DT>expgui(fadetime)<DD>
255The time in seconds before reflection labels are removed. A value of zero means that reflections
256must be deleted manually (Shift-Right-Mouse).
257
258<DT>expgui(lblfontsize)<DD>
259A size for reflections labels in pixels.
260
261<DT>expgui(hklbox)<DD>
262If this variable is non-zero, reflection indices are shown in a box.
263
264<DT>expgui(autotick)<DD>
265If this variable is non-zero, reflection markers positions are
266set automatically.
267</DL></DL>
268
269<P>
270<B>Using TCLDUMP with LIVEPLOT.</B>
271LIVEPLOT works with the standard GSAS program HSTDMP, but it works faster and is more
272powerful when used with the TCLDUMP program. Instructions for downloading this file can
273be found in the installation notes for
274<A HREF="http://www.ncnr.nist.gov/~toby/expgui/expgui_Win_readme.html">
275Windows</A> and
276<A HREF="http://www.ncnr.nist.gov/~toby/expgui/expgui_Unix_readme.html">
277UNIX</A>.
278<P>
279<B>Combining CMPR and LIVEPLOT.</B>
280If you have <A HREF="http://www.ncnr.nist.gov/~toby/cmpr.html">CMPR</A>
281installed on your computer, you can use superimpose on the GSAS results
282the peaks for an arbitrary unit cell. If desired, space group extinctions
283can even be shown.
284This is pretty neat! To enable this feature, you must have a version
285of CMPR downloaded after 4 May 1998
286<A HREF="http://www.ncnr.nist.gov/~toby/cmpr.html">
287(see the CMPR installation instructions.)</A>
288For UNIX, create a link from in the expgui
289directory to file cellgen.tcl in the CMPR directory. For example:
290<PRE>
291         ln -s /usr/local/cmpr/cellgen.tcl /usr/local/gsas/expgui/cellgen.tcl
292</PRE>
293For Windows, copy all the CMPR .tcl and .exe files into the expgui directory.
294<P>
295<B>Combining LOGIC and LIVEPLOT</B>
296If you have <A HREF="http://www.ncnr.nist.gov/~toby/logic.html">LOGIC</A>
297installed on your computer, you can superimpose peaks
298for a entry from the ICDD/JCPDS database on a pattern in LIVEPLOT.
299This is also pretty neat!
300To enable this feature, you must have
301a version of LOGIC downloaded after 4 May 1998
302<A HREF="http://www.ncnr.nist.gov/~toby/logic.html">
303(see the LOGIC installation instructions.)</A>
304For UNIX, create a link from in the GSAS GUI
305directory to file icddcmd.tcl in the LOGIC directory. For example:
306<PRE>
307         ln -s /usr/local/powdersuite/icddcmd.tcl /usr/local/gsas/tcl/icddcmd.tcl
308</PRE>
309For Windows, copy all the LOGIC files into the expgui directory.
310<HR>
311<H3>WIDPLT</H3>
312The widplt script is used to display the FWHM for one or more histograms
313from a .EXP file.
314At this point it only works for CW data.
315It is often convenient to add for reference the expected
316instrumental curves as options to the menu. This can be done by creating a
317file called widplot_<i>name</i>. For example, renaming the
318<tt>example_widplt_BT1</tt> file supplied with the distribution to
319<tt>widplt_BT1</tt> will cause the FWHM curves for the NIST BT-1 instrument
320to be added to the menu of defined FWHM values.
321<P>
322Creating such a file is easy. To add a entry define the following
323five array elements using a single, unique element name and then append that
324element name to variable datalist.
325Define
326<PRE>
327    set UVWP(Ge15) {398.5 -343.2  163.0 0}
328    set XY(Ge15) {0 0}
329    set wave(Ge15) 2.0775
330    set lblarr(Ge15) "BT-1 Ge(311) 15'"
331    set ttrange(Ge15) "5 160"
332    lappend datalist Ge15
333</PRE>
334Array element UVWP(item) contains the (Gaussian) GU, GV, GW and GP values,
335while XY(item) contains the (Lorentzian) LX and LY terms. Array element
336wave(item) contains a wavelength, array element lblarr(item) contains
337the text to be shown on the "Plot Contents" menu and ttrange(item)
338defines the range the function is valid.
339<P>
340The following variables are written to <tt>.gsas_config</tt> when
341"Save Options" is used. These variables are all set from the GUI and therefore
342do not need to be edited manually.
343
344<DL><DL>
345<DT>graph(printout)<DD>
346This is set to 1 if PostScript files
347will be printed and 0 if they will be written to disk (for Windows all
348files should be written to disk).
349
350<DT>graph(outname)<DD>
351This is the default for the file name used
352when PostScript files will be written to disk.
353
354<DT>graph(outcmd)<DD>
355This is the default for the command used
356to print PostScript files (Unix only).
357
358<DT>graph(legend)<DD>
359Sets the default value for display of the legend in liveplot and widplt.
360
361<DT>graph(plotunits)<DD>
362Sets the units used for displaying the data. Values are "d", "q", "",
363for d-space, Q and 2-theta, respectively.
364<DT>graph(equivwave)<DD>
365Sets the wavelength used for displaying data, if blank, no conversion is
366done and data are shown in their original wavelength.
367</DL></DL>
368
369<hr>
370GSAS is written by Allen C. Larson and <A HREF="http://lansce.lanl.gov/lujan/staff12/vondreele.htm">
371Robert B. Von Dreele</A>, MS-H805,
372Los Alamos National Laboratory, Los Alamos, NM 87545. Problems, questions
373or kudos concerning GSAS should be sent to Robert B. Von Dreele at <A HREF="MAILTO:vondreele@lanl.gov">vondreele@lanl.gov</A>
374
375<P>This GUI is written by Brian H. Toby of the NIST Center for Neutron Research,
376<A HREF="MAILTO:Brian.Toby@NIST.GOV">Brian.Toby@NIST.GOV</A>.
377
378<P>GSAS is Copyright, 1984-1997, The Regents of the University of California.
379The GSAS software was produced under a U.S. Government contract (W-7405-ENG-36)
380by the Los Alamos National Laboratory, which is operated by the University
381of California for the U.S. Department of Energy. The U.S. Government is
382licensed to use, reproduce, and distribute this software. Permission is
383granted to the public to copy and use this software without charge, provided
384that this notice and any statement of authorship are reproduced on all
385copies. Neither the Government nor the University makes any warranty, express
386or implied, or assumes any liability or responsibility for the use of this
387software.
388
389<P>The GUI is not subject to copyright. Have fun.
390
391<P>Brian Toby (<A HREF="MAILTO:Brian.Toby@NIST.GOV">Brian.Toby@NIST.GOV)</A>
392<BR>
393$Revision: 81 $ $Date: 2009-12-04 23:00:05 +0000 (Fri, 04 Dec 2009) $
394</BODY>
395</HTML>
Note: See TracBrowser for help on using the repository browser.