source: trunk/doc/expgui_cfg.html @ 504

Last change on this file since 504 was 461, checked in by toby, 12 years ago

# on 2001/10/18 23:17:12, toby did:
update archiving

  • Property rcs:author set to toby
  • Property rcs:date set to 2001/10/18 23:17:12
  • Property rcs:lines set to +2 -2
  • Property rcs:rev set to 1.20
  • Property rcs:state set to Exp
  • Property svn:keywords set to Author Date Revision Id
File size: 24.8 KB
[143]2   <META NAME="Author" CONTENT="Brian H. Toby">
3   <TITLE>Customizing EXPGUI and Associated Programs</TITLE>
[143]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"
[144]17<A Href="">
18<IMG SRC="tcltklogo100.gif" 
19alt="Link to Tcl/Tk information">
[338]21<br clear=all><hr>
24<TR><TH><A  Href="expgui.html">EXPGUI top</A> 
29Customizing EXPGUI and Associated Programs</H1></CENTER>
31The EXPGUI GSAS graphical user interface can be modified in many
32ways quite easily.
33This document describes how the GUI works and how to modify the menus without
[144]34significant reprogramming. A little bit of programming in Tcl/Tk can go a
[114]35long way in adding new features. See the
36<a HREF="#Customizing">Customizing</A> examples, below.
[36]39The main GUI is created by file expgui, which in turn uses the following files
46Two additional files are read if they are found:
51<P>The first three files,
52(<TT>readexp.tcl</TT>, <TT>gsascmds.tcl</TT>, <TT>gsasmenu.tcl</TT>)
53must be located in the same directory where the <TT>expgui</TT> file is found.
54The <TT>localconfig</TT> file also is read from this directory, if it exists.
55The final file, <TT>.gsas_config</TT>, is read from the user's login directory (UNIX) or <TT>C:\</TT> (Windows).
[41]56The <TT>localconfig</TT> and <TT>.gsas_config</TT> are intended to
57contain system-wide and user-level default values for parameters
58that are described in this document. Most routines have
59a "Save Options" command that writes some of the current parameters to
60file  <TT>.gsas_config</TT>. Note that information in <TT>.gsas_config</TT>
61overrides that in <TT>localconfig</TT>.
62No error occurs if either of these files are not found.
65The <TT>readexp.tcl</TT> and <TT>gsascmds.tcl</TT> files contain
66tcl procedures that are
67used for more than one application, so it is convenient to place them
68in separate files. They are only of interest to someone trying to debug
69or add new functionality to expgui.
71The <TT>gsasmenu.tcl</TT> file defines the contents of the
72menu bar, the contents of the
73button bar and definitions for each command. The contents of this file
74are designed to be modified and extended by users, either by editing the file,
[144]75or by overriding definitions in the <TT>localconfig</TT> or
[36]76<TT>.gsas_config</TT> files.
[41]78The important variables defined in the <TT>gsasmenu.tcl</TT> file are:
[36]81This list defines the menu bar headings other than File, Options & Help
[36]83Each array element, e.g. expgui_menulist(file) and expgui_menulist(powder),
84defines commands to be added to a menu heading. Each command will appear
85as an array element in expgui_cmdlist.
[36]87Each array element, e.g. expgui_cmdlist(Save) or expgui_cmdlist(expnam)
88contains two items. The first defines a tcl procedure to be executed
89when the command is invoked, or "-" if no command will be invoked and
90the second contains help information describing what the command does.
91Note that when menu item is selected the variable cmd is set to the
92name of the command, so
94    expgui_cmdlist(powpref) {{runGSASwEXP $cmd} {Powder data preparation}}
96means that "runGSASwEXP powpref" will be invoked when powpref is invoked.
97. For example, when powpref is selected, the tcl command
98"runGSASwEXP $cmd" is invoked, where variable cmd is set to "powpref".
[36]100This list defines the commands that will appear on the button bar where
101each item that appears on the button bar must have a matching pair of entries
102in expgui_cmdlist.
103Thus if the command
105   set expgui(buttonlist) {expnam expedt genles ortep fourier forsrh forplot lstview}
107is placed in the <TT>localconfig</TT> or <TT>.gsas_config</TT> files this will
108redefine the contents of the button bar.
111In addition to the variables defined in the previous file, expgui, uses
[143]112a small number of array elements for other configuration options. They are:
[41]116This determines where files such as <TT>readexp.tcl</TT>, etc.
117are located. This defaults to the location where <TT>expgui</TT> is located so
118it rarely needs to be changed.
[41]121This contains the location of the GSAS directory, if it is not the
122parent director where expgui is found.
123This determines where a number of GSAS data files will be located. If expedt
124crashes when you try to add new atoms, this is probably wrong.
[36]127This determines where the GSAS executable files are located.
128You might want to change this is you keep multiple versions of GSAS
129around or if you keep the GSAS files in a different location than
130the default or want to keep the tcl files somewhere other than
131in a subdirectory of the GSAS files.
134Sets the background color for the bottom box on the phase pane.
135The default value, #fdf, is a light violet that
136will probably drive some folks nuts, but is a good contrast to the yellow
137of the refinement flags.
[41]140Sets the default histogram used for liveplot
[41]143Sets the default value for display of the legend in liveplot
[143]146Defines commands to be executed by EXPGUI after all other commands
147have been run. This is used to define initialization commands in
148the <TT>localconfig</TT> or <TT>.gsas_config</TT> files that cannot be
149run at the time when the files are sourced. <I>(added in EXPGUI v1.21)</I>
152The following variables are written to <tt>.gsas_config</tt> when
153"Save Options" is used. These variables are all set from the GUI and therefore
154do not need to be edited manually.
[41]158This defines the default state for the archive flag,
159where 0 is off and 1 is on. When archive is on, a copy of the .EXP file
[461]160is saved before a new version of the file is saved in EXPGUI.
163This determines the base font used in the programs. You conceivably
164could want to use an integer value not present in the
165"Options/Screen Font" menu command.
[41]168This determines the atom sort mode.
[41]171This determines the histogram sort mode.
[81]174This determines the default file sorting mode for the expnam command.
177If set to 1, the experiment file is automatically reread after
178GSAS programs modify it.
179(UNIX only)
182If set to 1, output from EXPTOOL is shown after the program is run.
183This is probably needed only for debugging purposes.
[41]186Used only for UNIX: This determines if the default definition
[36]187for the backspace key is overridden; some UNIX systems need this so that
188expedt and other terminal-oriented programs work correctly and
[143]189other systems do not. You can toggle this option using the
190"Override Backspace" option on the file menu to see what works for you.
195<HR><H3><A NAME="import">Coordinate import routines for EXPGUI</A>
[299]196<IMG SRC="new.gif" HEIGHT=13 WIDTH=36 alt="New!">
[282]198Currently two formats are supported, the Crystallographic Information File (CIF)
199and .CEL files from PowderCell.
[270]200It is possible to define new formats for EXPGUI to use for importing
201phase/coordinate information. This is done by creating a file named
[282]202<TT>import_</TT><I>xxxx</I><TT>.tcl</TT> (where <I>xxxx</I> is arbitrary)
203in the EXPGUI directory. See the file <TT>import_cell.tcl</TT> as an example.
205The file must contain four items:
208A description for the type of file to be read.
210set description "PowderCell .CEL file"
[282]212The text should not be too long, but use a return (\n) if needed:
214set description "My favorite coordinate\nfile from the GIGO pkg"
[282]216This description text shows up on the button for selecting a format.
[282]219A list of preferred file extensions.
221set extensions .cel
225set extensions {.jnk .junk}
[282]227In UNIX upper and lower case
228versions will be generated automatically, so do not worry about
229the case of the extension. Note that "*" (all files) is always added as well.
232The name of the routine that will read the data file
234set procname ReadPowderCellFile
237A routine that takes the file name as an argument
239proc ReadPowderCellFile {filename} {
[282]241and returns a list containing the following four items
[282]243<P><LI>Space Group
245The space group should be named and spaced appropriately for GSAS,
246e.g. P 21/c or P 21 21 21, not P21/c or P212121.
[282]248Note that GSAS requires that if a center of symmetry is present,
249this center defines the origin (Origin 2 settings, where more than one setting
250is given in the International Tables).
251<P><LI>Cell parameters
253All six parameters should be specified in a list
[282]255<P><LI>Atom Coordinates
257The atom coordinates should be specified as a list with a list element
258for each atom.
259The list contains the following items:
261<LI>Atom label
265<LI>Atom type
269If an item is not specified, it is left blank in the atom table, except for
270Occupancy and U<sub>iso</sub>, which default to 1.0 and 0.025, respectively.
271However, one must specify a null value, if an item will be skipped over.
272For example, use:
274    "Li1 0 0 0 li 0.5"
278    "{} 0 0 0 li 0.5"
280but not
282    "0 0 0 li 0.5"
[282]286<P><LI>Warning Message (optional)
288The warning message is displayed at the bottom of the
289Replace Atoms and Add Atoms box after the file is read. This can be used
290to warn the user about problems reading the file, for example if
291the space group symbol needs attention.
297The <TT>localconfig</TT> and <TT>.gsas_config</TT> files are read, if present.
298The following options are available for customization in these files:
[41]301This limits the number of entries that can
[36]302exist in a menu. For example, the default is 25, so when more than 25 cycles
303are found in a .LST file, only the last 25 are listed in the
304"Go To"/cycle submenu.
[41]306This limits the maximum number of
[36]307characters that will be read from an existing .LST file to speed
[41]308the start of the program. The default is ~1Mb
[36]309for UNIX systems and ~200K for Windows.
[81]312The following variables are written to <tt>.gsas_config</tt> when
313"Save Options" is used. These variables can be set from the GUI and therefore
314do not need to be edited manually.
[41]318This sets the initial value for the
319"Auto Advance" button in the "Go To" menu. When this is true,
320the program will show the last cycle in the file. As new cycles are
321added, the "view" is advanced.
[81]324This sets the font used for LSTVIEW. See documentation on the font command in
325Tk for details on font naming.
328One additional variable is present that I don't suggest using at present:
[41]330<LI>plotvars: I am in the process of developing code that tracks
[36]331and plots shifts and R values as a function cycle number. Setting plotvars to 1
332allows this code to be tested.
335<hr><H3>LIVEPLOT</H3><A NAME="liveplot"></A>
[410]336A description of the customization options for LIVEPLOT can be
337found in the
338<A HREF="liveplot.html#customize">
339LIVEPLOT description</A>.
[36]344The widplt script is used to display the FWHM for one or more histograms
[41]345from a .EXP file.
346At this point it only works for CW data.
347It is often convenient to add for reference the expected
[36]348instrumental curves as options to the menu. This can be done by creating a
349file called widplot_<i>name</i>. For example, renaming the
350<tt>example_widplt_BT1</tt> file supplied with the distribution to
351<tt>widplt_BT1</tt> will cause the FWHM curves for the NIST BT-1 instrument
352to be added to the menu of defined FWHM values.
354Creating such a file is easy. To add a entry define the following
355five array elements using a single, unique element name and then append that
356element name to variable datalist.
359    set UVWP(Ge15) {398.5 -343.2  163.0 0}
360    set XY(Ge15) {0 0}
361    set wave(Ge15) 2.0775
362    set lblarr(Ge15) "BT-1 Ge(311) 15'"
363    set ttrange(Ge15) "5 160"
364    lappend datalist Ge15
366Array element UVWP(item) contains the (Gaussian) GU, GV, GW and GP values,
[41]367while XY(item) contains the (Lorentzian) LX and LY terms. Array element
[36]368wave(item) contains a wavelength, array element lblarr(item) contains
369the text to be shown on the "Plot Contents" menu and ttrange(item)
370defines the range the function is valid.
[41]372The following variables are written to <tt>.gsas_config</tt> when
373"Save Options" is used. These variables are all set from the GUI and therefore
374do not need to be edited manually.
[41]378This is set to 1 if PostScript files
379will be printed and 0 if they will be written to disk (for Windows all
380files should be written to disk).
[41]383This is the default for the file name used
384when PostScript files will be written to disk.
[41]387This is the default for the command used
388to print PostScript files (Unix only).
[41]391Sets the default value for display of the legend in liveplot and widplt.
[41]394Sets the units used for displaying the data. Values are "d", "q", "",
395for d-space, Q and 2-theta, respectively.
[41]397Sets the wavelength used for displaying data, if blank, no conversion is
398done and data are shown in their original wavelength.
[114]402<a name="Customizing"><H2>
403Customizing Example 1: Adding a new button to the button bar
405When a LeBail extraction is used to refine lattice constants, profile
406terms, ... It is always a good idea to run GENLES a few times after running
407POWPREF. This is because GENLES sets the extracted intensities back to their
408crystallographic values, during the first GENLES cycle after POWPREF has been
409run. Refining anything until the extracted intensities return to reasonable
410values is a really bad idea. Forturnately, running GENLES with the number of
411cycles set to zero gives the Le Bail extraction a head start.
413The code below can be used to define a new command, <tt>leBail</tt>. The first
414command adds a command to the button bar and the second one defines what will
415be done when it is invoked (the number of cycles is set to zero and
416GENLES is run three times). It also defines the help entry. Note that commands must start with a lower case letter even though Armel LeBail's last name
417does not.
420    lappend expgui(buttonlist) leBail
421    set expgui_cmdlist(leBail) {
422        {set entryvar(cycles) 0; runGSASwEXP "genles genles genles"}
423        {Converges GENLES with LeBail extractions;
424          Sets the number of cycles to zero and runs GENLES 3 times.}
425    }
428To make this customization, put the above in the <TT>localconfig</TT> 
429file or the
430<TT>~/.gsas_config</TT> or (or <TT>C:\GSAS\EXPGUI\.gsas_config</TT>)
[143]434Customizing Example 2: Putting DISAGL Results in a Separate Box
436Barbara Reisner has been asking me to put the output from DISAGL in a separate
[143]437window. Sounds like a pretty reasonable request. Here is an example with code
438to do that as a customization option. Please note that this has now been
439incorporated into EXPGUI, so do not use this example.
441  set expgui(disaglSeparateBox) 1
442  set expgui_cmdlist(disagl) {rundisagl {Hacked Distance/angle calculations}}
443  proc rundisagl {} {
444    global expgui txtvw tcl_version tcl_platform
[143]445    if {$expgui(disaglSeparateBox) && $tcl_platform(platform) != "windows"} {
[114]446        set root [file root $expgui(expfile)]
447        catch {file rename $root.LST $root.OLS}
448        runGSASwEXP disagl
449        catch {file rename $root.LST $root.DIS}
450        catch {file rename $root.OLS $root.LST}
452        # open a new window
453        catch {toplevel .disagl}
454        catch {eval grid forget [grid slaves .disagl]}
455        text .disagl.txt -width 100 -wrap none \
456                -yscrollcommand ".disagl.yscroll set" \
457                -xscrollcommand ".disagl.xscroll set"
458        if {$tcl_version >= 8.0} {.disagl.txt config -font $txtvw(font)}
459        scrollbar .disagl.yscroll -command ".disagl.txt yview"
460        scrollbar .disagl.xscroll -command ".disagl.txt xview" -orient horizontal
461        grid .disagl.xscroll -column 0 -row 2 -sticky ew
462        grid .disagl.txt -column 0 -row 1 -sticky nsew
463        grid .disagl.yscroll -column 1 -row 1 -sticky ns
464        grid columnconfigure .disagl 0 -weight 1
465        grid rowconfigure .disagl 1 -weight 1
466        wm title .disagl "DISAGL results $expgui(expfile)"
467        wm iconname .disagl "DISAGL $root"
468        set in [open $root.DIS r]
469        .disagl.txt insert end [read $in]
470        close $in
471        bind all <Control-KeyPress-c> {destroy .disagl}
472        bind .disagl <KeyPress-Prior> ".disagl.txt yview scroll -1 page"
473        bind .disagl <KeyPress-Next> ".disagl.txt yview scroll 1 page"
474        bind .disagl <KeyPress-Right> ".disagl.txt xview scroll 1 unit"
475        bind .disagl <KeyPress-Left> ".disagl.txt xview scroll -1 unit"
476        bind .disagl <KeyPress-Up> ".disagl.txt yview scroll -1 unit"
477        bind .disagl <KeyPress-Down> ".disagl.txt yview scroll 1 unit"
478        bind .disagl <KeyPress-Home> ".disagl.txt yview 0"
479        bind .disagl <KeyPress-End> ".disagl.txt yview end"
480        # don't disable in Win as this prevents the highlighting of selected text
481        if {$tcl_platform(platform) != "windows"} {
482            .disagl.txt config -state disabled
483        }
484    } else {
485        runGSASwEXP disagl
486    }
487  }
[143]489if {$tcl_platform(platform) != "windows"} {
490  append expgui(initstring) {
491      $expgui(fm) add checkbutton  -label "DISAGL window" \
492              -variable expgui(disaglSeparateBox) -underline 0;
493  }
497To make this customization, put the above in the <TT>localconfig</TT> 
498file or the
499<TT>~/.gsas_config</TT> or (or <TT>C:\GSAS\EXPGUI\.gsas_config</TT>)
[143]502Note that the <tt>expgui(initstring)</tt> option became available in EXPGUI
503version 1.21. (Previous versions will ignore this). This code must be executed
504after all the menus and other GUI code has been run. When executed, it
505creates a checkbutton on the Options menu to
506turn the "separate DISAGL window mode" mode on and off.
509Customizing Example 3: Adding a new page to EXPGUI
511The steps for creating support for additional functionality, implementation
512of atom constraints, is outlined here. Routines described here can be found in
513file <tt>atomcons.tcl</tt> unless otherwise noted.
515<LI>Create a routine to read and write the appropriate records
516from the .EXP file. In this case, a new routine, constrinfo,
517was added to file <tt>readexp.tcl</tt>.
518This takes considerable care and manual testing.
519<LI>Create a routine that places the appropriate widgets into a frame
520(in this case MakeAtomsConstraintsPane). This routine will be called only once.
521Note that in this example expcons(atommaster) is defined to be the name of the
523<LI>Create a routine to display and edit the information shown in the
524frame. In this case, DisplayAtomConstraints. This routine will be called each
525time the page is displayed. Note that this routine and the previous can be
526tested in a separate toplevel until they work well.
527<LI>In this particular example, the previous frame is located on a notebook
528widget that in turn placed on a notebook page, so MakeConstraintsPane is used
529to create this inner notebook when the "Constraints" notebook page is first
530shown. This in turn calls MakeAtomsConstraintsPane and DisplayAtomConstraints.
[144]531To update this page each time it is displayed, DisplayConstraintsPane is
[143]533<LI>Edit file <tt>expgui</tt> to make the following changes:
535<P><LI>load the <tt>atomcons.tcl</tt> file:
[144]537# commands for constraints
[143]538source [file join $expgui(scriptdir) atomcons.tcl]
[143]540<P><LI>Define a notebook page for the option. The -createcmd option
541is used only once, but the -raisecmd option is used every time
542the page is exposed.
544set expgui(consFrame) [\
545            .n insert end consPane -text Constraints \
[144]546            -raisecmd "set expgui(pagenow) consFrame; DisplayConstraintsPane"\
[143]547            -createcmd MakeConstraintsPane]
[144]548lappend expgui(frameactionlist) "consFrame DisplayConstraintsPane"
550Note that if we were displaying the atoms constraint page directly on
551the main notebook widget, the previous command would have been
552<tt>-raisecmd DisplayAtomConstraints -createcmd MakeAtomsConstraintsPane</tt>
[144]554Since the frame will need to be updated when information in the .EXP file
555changes, the name of the frame and a command to execute are added into list
556expgui(frameactionlist) using the <TT>lappend expgui(frameactionlist)</TT>
563Customizing Example 4: Changing the fonts used in the GUI
565<B>Question: </B>
[423]566<I>I am not happy with the fonts available via the Option/Screen Font
567menu option. Is there a way to select different font size(s)/families?
570<B>Answer: </B>
571The fonts used in EXPGUI can be customized by adding some code to the
572<TT>localconfig</TT> file or the
573<TT>~/.gsas_config</TT> or (or <TT>C:\GSAS\EXPGUI\.gsas_config</TT>) file.
574By default, fonts are 14 point for the menus, buttons, labels,... and
57512 point for the histogram and atom lists.
[423]577If you add a command like this:
[423]579option add *Coord.Listbox.Font "Courier -18 bold italic" 20
[423]582you will override the menu command and force the atom coordinates
583to be displayed at 18 points in a bold & italicied Courier font.
584(See the Tk documentation if this is not clear). The value 20 is a
585priority, which overrides the priority value of 10 in the
586standard initialization. Here are the options that can be specified:
588<DT><TT>*Graph*Font</TT><DD>Used for Graph labels
589<DT><TT>*Graph.font</TT><DD>Used for Graph title
590<DT><TT>*Canvas.font</TT><DD>Used for notebook tabs
591<DT><TT>*Button.font</TT><DD>Used on most buttons
592<DT><TT>*Menu.font</TT><DD>Used on menu commands
593<DT><TT>*Menubutton.font</TT><DD>Used on "menu buttons" (e.g. Print options)
594<DT><TT>*Label.font</TT><DD>Used on labels
595<DT><TT>*Scale.font</TT><DD>Used on sliders (e.g. Marquardt damping)
596<DT><TT>*TitleFrame.font</TT><DD>Used on title frames (e.g. box labels such as
597the "Diffractometer Constants" label
598<DT><TT>*SmallFont.Button.font</TT><DD>Used for buttons with smaller letters
599<DT><TT>*Coord.Listbox.font</TT><DD>Used for coordinate listings, best as a
600mono-spaced font, such as Courier
601<DT><TT>*HistList.Listbox.font</TT><DD>Used for histogram listings
602<DT><TT>*MonoSpc.Label.font</TT><DD>Used in other places where a mono-spaced
603font is required
[347]605It should be noted that the appearance of fonts depends on many factors --
606the fonts installed on your computer, the screen size and resolution and your
[423]607eyes, so it is wise to experiment with different values.
611<TR><TH><A  Href="expgui.html">EXPGUI top</A> 
[144]614<A Href="">
616is written by Allen C. Larson and <A HREF="">
[67]617Robert B. Von Dreele</A>, MS-H805,
[36]618Los Alamos National Laboratory, Los Alamos, NM 87545. Problems, questions
619or kudos concerning GSAS should be sent to Robert B. Von Dreele at <A HREF=""></A>
[67]621<P>This GUI is written by Brian H. Toby of the NIST Center for Neutron Research,
[36]622<A HREF="MAILTO:Brian.Toby@NIST.GOV">Brian.Toby@NIST.GOV</A>.
624<P>GSAS is Copyright, 1984-1997, The Regents of the University of California.
625The GSAS software was produced under a U.S. Government contract (W-7405-ENG-36)
626by the Los Alamos National Laboratory, which is operated by the University
627of California for the U.S. Department of Energy. The U.S. Government is
628licensed to use, reproduce, and distribute this software. Permission is
629granted to the public to copy and use this software without charge, provided
630that this notice and any statement of authorship are reproduced on all
631copies. Neither the Government nor the University makes any warranty, express
632or implied, or assumes any liability or responsibility for the use of this
635<P>The GUI is not subject to copyright. Have fun.
637<P>Brian Toby (<A HREF="MAILTO:Brian.Toby@NIST.GOV">Brian.Toby@NIST.GOV)</A>
639$Revision: 461 $ $Date: 2009-12-04 23:06:33 +0000 (Fri, 04 Dec 2009) $
Note: See TracBrowser for help on using the repository browser.