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