Documentation for Program CMPR
Why use CMPR?
CMPR is a multipurpose program for powder diffraction data that provides the following features:
- Any type of diffraction data may be used
- Read support for many ASCII data formats; more can be added simply & quickly without recompilation
- Write support for a few ASCII data formats; more can be added simply & quickly without recompilation
- Multiple datasets may be plotted at one time with easy control over how (color, symbol type...) data are displayed
- Facile zoom capability for easy magnification of sections of datasets.
- WYSIWYG graphics export to GRACE for publication-quality output with ability to add annotations, etc.
- Rescaling data (multipliers & offsets) for visual comparison of data sets
- Data conversion features for comparison of different data types (example: plot synchrotron or TOF data as if collected at Cu K alpha or vice-versa)
X-axis conversions:
- d-space
- Q
- two-theta at arbitrary wavelength
- Change intensity scaling to extract pattern details
Intensity conversions:
- Linear
- Sqrt(I)
- Log(I)
- I/sigma(I)
- I^2/sigma(I)^2
- Weighted addition and subtraction of patterns
- Generate lists of reflection positions, optionally omitting reflections that are not allowed by space group extintions or selected symmetry operation(s).
- Graphically superimpose generated reflection positions on data, optionally omitting or highlighting reflections that are not allowed by space group extintions or selected symmetry operation(s).
- Fit up to 8 diffraction peaks using a single pseudo-Voigt peak shape, optionally using a Finger-Cox-Jephcoat asymmetry correction.
- Smooth, take derivatives & extract peak positions from data (beta software contributed by R. Harlow)
- Interface with ITO, TREOR & DICVOL autoindexing programs; view reflection positions for resulting superimposed on diffraction data.
- Interpolate and add overlapping datasets to form a single scan (beta software contributed by R. Harlow)
- Search for matching entries in the ICDD-JCPDS database, with graphical superposition of peaks on diffraction patterns.
Fit GSAS profile terms to a set of peak widths
The following sections of this web page describe the various modes within the program. Most sections have links to screen dumps of the GUI with a link marked "View panel" or something similar. The most recent additions are noted with the "new"
image, while other changes that have been added in the previous few versions are flagged with this image:
.
For installation information, see the CMPR/LOGIC overview.
Mouse shortcuts
Zoom
It is possible to enlarge the size of the plot window by dragging the frame of (the border surrounding) the plot window. The scale of the plot will adapt to show the same range of data, but now expanded to fit in the larger window. It is possible to change scale by "zooming in" and display a smaller region of the data in the plot window by clicking in two opposite corners of the region to be shown with the left mouse button (a left-click) (View before and after examples). Zooming in can be done multiple times. It is also possible to "zoom out" and show the previous view of the data by clicking on the right mouse button (a right-click). Note that in Mac OS X, if you have a traditional Mac one-button mouse, you can simulate the middle mouse button by holding down the "Option" (Alt) button and can simulate the right mouse button by holding down the "Command" (Apple) key.Pressing the "z" or "Z" key (Z for Zoom) allows the zoom to be set manually by entering minimum and maximum values for the x- and y-axes.
Live Cursor
Pressing the "l" or "L" key (L for Live cursor) in the plot window creates a panel below the plot that shows the coordinates of the mouse. Pressing "l" or "L" again, or pressing the "Close cursor display" button causes this panel to be removed.Buffer Selection
Most modes within CMPR display a list of datasets that have been created or read in. I call these in-memory datasets buffers.
- left-click Buffers are selected by clicking on them with the left mouse button
- control-left-click The control and shift keys can be used to modify which buffers are selected. Holding the control key down and clicking the left mouse button causes the buffer to be selected or unselected.
- shift-left-drag Holding the shift key down and dragging the left mouse button across part of the list of buffers causes those buffers to be selected.
- double-left click causes the current buffer(s) to be plotted (can be combined with shift or control).
- triple-left click or a right-click (single) causes all buffers to be selected and plotted. (Mac OS X, use mouse + the "Command" (Apple) key.)
Deleting Buffers
Control-right-click (Mac: control+Command+mouse) causes the selected buffers to be removed from the program file list (not deleted from disk). You are prompted to confirm before any buffers are removed. Note that buffers can be deleted or renamed on the EditFile panel.Reordering Buffers
See keyboard shortcuts
Keyboard Shortcuts
![]()
There are a number of shortcuts implemented by pressing keyboard keys. A list of them follows. Note that either upper or lower case letters may be used. Some of these keys will function only in certain sections of CMPR.
Overall
in any window/any panel:
- control+C
- exits the program
- F1 key
- show help on current panel
Plot display
In plot window/any panel:
- L
- shows "live" cursor position
- Z
- set zoom scaling manually
- left click
- zoom in
- right click
- zoom out (Mac: Command+click)
Reflection Labeling
In the EditCell section of the program, it is possible to label the generated reflection position by clicking in or pressing a key with the mouse in the plot window:
- shift+left click
- label nearby reflections
- shift+double left click
- label all reflections
- shift+right click
- delete reflection labels (Mac: shift+Command+click)
- pressing the "H" key
- labels individual reflections (also Shift key+left mouse click)
- pressing the "A" key
- labels all reflections (also shift+left double-click)
- pressing the "D" key
- deletes all reflection labels (also shift+left-doubleclick). Note that individual reflection labels will be typically be erased automatically after a given number of seconds, as set in the Display options page.
Fit range management
In the plot window only when the fit panel is selected:
- control+double left click
- add peak at current position
- S
- set fit range to current zoom
- F
- scroll the fit region forward
- B
- scroll the fit region backward
- E
- expand the scroll fit region
- P
- define peak position
Reordering Buffers
![]()
(note that these options only work if a single data set is selected). Also see Buffer Selection tricks
- The + key
- causes the selected buffer to be moved up in the list
- The - key
- causes the selected buffer to be moved down in the list
CMPR Program Sections
CMPR consists of a number of program sections (panels) that are selected using the "notebook tabs" directly below the menu bar.
Read (View panel)
This panel is used to read diffraction data in a number of formats.
To read a file into a buffer, select the format on the right and then select a file on either the window that pops up (Windows) or on the central pane (UNIX). Note that files can be read either by double-clicking (with the left button) on them or by pressing the Open (or Read) button.
After a file has been read, it appears in the plot window and if the legend is active (see the Display options panel) the name appears in the legend. Also see the buffer selection section to see how one or more buffers can be plotted.
It is quite easy to extend CMPR to support additional formats as well. (No compiler is needed). For information on creating a new routine for reading data, or changing the order of entries in the list, see the Customizing instructions, below.
Write (View panel)
This causes the selected buffer(s) to be written. The box at the top shows the directory where files will be written. Note that forward slash characters (/) are used, even for Win-95 and -NT.
It is quite easy to extend CMPR to support writing additional formats as well. (No compiler is needed). For information on creating a new routine for writing data, or changing the order of entries in the list, see the Customizing instructions, below.
Plot (View panel or view sample plot)
The plot panel is used to display one or more buffers. To select a single buffer, click on the buffer name. A range of buffers can be selected by dragging with the mouse. Individual buffers can be selected or deselected by holding the control key and clicking on the buffer name. The plot is updated when the "Update Plot" button is pressed or with a mouse double-click.
The "Postscript out" button causes a postscript copy of the plot window to be created. Settings on the Display options panel determine where the file is created or how it is printed.
Plots can be exported to grace, a publication-quality graphics package where the displayed plot can be enchanced and annotated. This works very nicely. Alternately, the information on the plot can be exported as a .CSV (comma separated variable) file that can be read by lots of graphic programs, but it will be up to you to supply the formatting.
On Windows, there is also an option to export the plot to the windows clipboard so that it can be pasted into any windows application that can accept graphics.
The two buttons labeled "Reorder" change the order that buffers are shown in the list. The + button causes the selected buffer to be moved up in the list and the - button causes the selected buffer to be moved down in the list
The "Line", "Color" and "Symbol Type/Size" sections of this panel are used to change the way a buffer is displayed. This is done by selecting the entries(s) to be changed and then using the appropriate checkboxes to select the color, line type, symbol type and size. The changes will be made when the "Apply all Changes" button is pressed to all selected buffers.
It is also possible to change the colors in sequence to a set of selected buffers. If the "Set Color Sequence" button os pressed, the first selected buffer will be assigned the selected color, the next buffer will be assigned the next color in the list...
Rescale (View panel)
This panel is used to modify the stored values in one or more buffers. One can specify constants to multiply the x and y values and two sets of constants to add to the x and y values (addition is done after multiplication). The X and Y offset values are added directly to the x and y values respectfully. The X and Y stagger values are percentages of the x and y axis lengths (at the current zoom setting) or if the "Reset to original values" option is selected, the y-axis length is assumed to encompass the entire data range for the selected buffers. The stagger amounts are not applied to the first buffer to be rescaled, are added times 1 to the second buffer, times 2 for the third buffer... This option effectively causes the plots to be staggered vertically (Y) and/or horizontally (X).
It is also possible to transform the x and y scales. The x-axis can be transformed between Q, d-space and 2-theta units for an arbitrary wavelength. Intensities (y values) can be transformed to square roots [Sqrt(I)], base 10 logarithms [Log(I)]. The I/sig(I) divides each intensity by its estimated error, providing an estimate of the signal-to-noise and the
I2/sig(I)2 mode scales each intensity value so that that estimated error is the square-root of the intensity, thus showing raw counts prior to scaling (or the equivalent). Conversion is done before constants are added or multiplied.
If more than one scaling or transformation is applied, the operation is applied to the results from the previous operation. However, if the "Reset to original values" checkbox is selected, the x and y values are reset to the values that were read in, before any scaling or transformation is done. Changes are applied when the "Rescale" button is pressed.
Combine (View panel)
The Combine panel is used to create a new buffer by adding or subtracting up other buffers. The buffers must have the same number of data points. No attempt is made to offset buffers, so they must all start (and end) with the same x value.
HKLGEN (View panel)
This panel generates a list of the allowed reflections for a given set of unit cell constants and extinction conditions. It is possible to specify symmetry by space group or by selecting individual translational symmetry operations.
Space groups should be entered as specified in GSAS: Enter the centering condition or cell type (P, R, A, B, C, I or F) and then the symmetry along each appropriate axis, with spaces between each axis. Append a final "R" for rhombohedral settings. Some examples are: "P 1 21/c 1" or "P 21/c" for P21/c and "R 3 m" and "R 3 m R" for the hexagonal and rhombohedral settings of R3m, respectively. If an incorrect space group is entered, no error message is generated, but no extinctions are generated.
Unit cells may be input with either direct or reciprocal cell parameters. The reflections are generated and placed in a separate window when the "Compute" button is pressed. This table can be saved to a disk file by entering a file name and pressing the "Save as" button.
EditCell (View panel or view sample plot)
This panel generates a stick-figure plot of the allowed reflections for a given set of unit cell constants. Reflections can be omitted or highlighted if extinct due to symmetry.
Unit cells may be input with either direct or reciprocal cell parameters. Use of reciprocal cell parameters has proven valuable for indexing powder diffraction data with low symmetry unit cells where some reciprocal unit cell vectors are known from electron diffraction.
Symmetry can be specifed by space group or by selecting individual translational symmetry operations. Space groups are entered as used in GSAS. Enter the centering condition and then the symmetry along each appropriate axis, with spaces between each axis. Append a final "R" for rhombohedral settings. Some examples are: "P 1 21/c 1" or "P 21/c" for P 21/c and "R 3 m" for and "R 3 m R" for the hexagonal and rhombohedral settings of R 3 m, respectively. If an incorrect space group is entered, no error message is generated, but no extinctions are generated.
After the unit cell parameters have been entered and the "Compute" button is pressed, reflections are generated and displayed as a stick figure. At this point list of buffers is then displayed. If symmetry information was entered before the compute button was pressed, the extinct reflections are not included in the reflection list. If symmetry information is entered after the compute button is pressed, the extinct reflections are highlighted in yellow. To superimpose the stick figure on one or more buffers, select the buffers and press "Update Plot" button.
The plot will respond to changes in the unit cell parameters or zero correction made either by typing value(s) into the entry boxes or by sliding the bars to the left of each number. The zero correction is added to two-theta values. Unit cell symmetry can be raised by selecting a higher symmetry cell from the list in the middle. To lower the symmetry, a new peaklist must be created.
To redisplay a previously generated set of reflections, select the appropriate buffer using the "Select peaklist" button in the upper left of the panel. Note that this recenters the unit cell sliders and recomputes the reflections within the requested angular range (see Options).
Individual reflections can be labeled by holding the Shift key and clicking on the reflection position with the left mouse button (shift-left-click). All reflections can be labeled by holding Shift key and double-clicking anywhere in the plot with the left mouse button (shift-left-doubleclick). Individual reflection labels will be typically be erased automatically after a given number of seconds, set in the Options panel; an erase time of 0 means that reflections labels are not automatically erased. Holding the Shift key and clicking anywhere with the right mouse button (shift-right-click) clears labels for all reflections (Mac: Command+shift+mouse). The size of reflection labels can be changed on the Options panel. (see Options).
Note that the size for the reflection markers, with respect to the Y axis, is determined by the "Maximum and Minimum Y values" on the right side of the screen.
In the example images, (View panel or plot), the reflection list was generated using space group R -3 but then space extinctions for R -3c are labeled. Thus, the reflections made extinct by the c-glide are shown in yellow. Reflections extinct in R -3 are not shown.
Fit (View panel or View sample plot)
Fit is used for profile fitting of selected regions of a pattern. Peaks are fit with a pseudo-Voigt where eta is the "mixing term." A value of 0.0 for eta selects a completely Gaussian peak shape and a value of 1.0 selects a completely Lorenztian peak shape.
Once a refinement has been done, the peak positions in the peak list buffer are updated also a "Undo last cycle" button is shown. Pressing this button resets the values in the various boxes to their values from before the refinement (it does not change the values in the peak list buffer).To fit peaks:
- A buffer to fit is selected using the "Select Dataset" button in the upper left. If only one appropriate dataset is present, it is selected automatically.
- A buffer to record the peak positions is selected. The first peak list (if any) is the default, but it is also possible select "new" which will add peaks to an empty list.
- Select a data range to be fit. The range must contain less than 1000 data points. The range can be set using the mouse to zoom and the S/Z/F/B/E keyboard shortcuts or use the "Set range to fit" submenu. This creates a dialog box (view) to set the data range with three options:
When a range of data is selected, any peaks found in the peakfile in that data range are displayed on the plot and are added to the peak list menu to the right.
- use the mouse to zoom in on a region and press the "Set from zoom" button, or
- type an upper and lower two-theta value in the "Fit Range" boxes, or
- shift the range using an increment and "Add increment to limits" button.
- There are two methods for adding new peaks to the menu:
- by pressing the "P" key (P for Peak) while positioning the mouse to the location of the peak maximum (shift+double-left-click also works)
- by pressing the "set" button in any row of the peak table and then pressing the "P" key, after moving the desired peak maximum. This "set" button can also be used to redefine peaks in the table.
- Select parameters to refine: Once at least one peak has been entered, and a suitable range has been selected, a "Run GPLSFT" button appears. Select the parameters to be refined by clicking on the appropriate boxes to the right of the parameters
- Optimize parameters by pressing the "Run GPLSFT" button. The least-squares algorithm in the program is far from robust. It is wise to first refine the peak areas and FWHM terms and then add background and eta and peak positions after reasonable fits are obtained. If the fit blows uo, refine fewer parameters at a time or decrease the damping value.
If you want to save the fitted curve, the "Store Fit" button creates a buffer with the current fit result.
The GPLSFT program can use the Finger-Cox-Jephcoat correction for peak asymmetry. For this correction, three terms must be known: the diffractometer radius, the half-height (or half-width) of the sample and of the detector. Values may be specified in any consistent units. (NIST would prefer that you use metric units, of course.) While these values can be refined, do so with care: do not refine too many variables at the same time, use a small number of cycles and set the damping factor to a small number.
By default fit results are shown superimposed on the plot of the fit, but the results can be placed in a separate window by deselecting the "Report fit results in plot window" checkbox on the Options panel.
Peaks/Smooth
(View panel)
This panel is used to smooth one or more diffraction patterns with a Gaussian. The smoothed results can be used to compute a first and second derivative of the data as well. Peak positions, as well as height and area estimates can be made using the second derivative. Once the peak positions are determined, sections of data away from the peak positions are used to construct an estimate of the background.
The "FWHM" setting controls the width of the Gaussian convolution function for all of the above computations. It seems that it is best to set this to the approximate FWHM seen for peaks in the data.
The "Sensitivity" and "ESD" settings are used only for peak searching. Both are used to reject peaks below signal-to-noise criteria, but the exact functioning of these settings is not well understood.
This code is still under development and comments and suggestions can be offered to Dick Harlow.
Index (View panel or Results Window)
This page is used to prepare input to three autoinexing programs, ITO, TREOR and DICVOL. These programs attempt to find unit cells that index a set of diffraction peaks. Please cite the appropriate reference should you publish a result from one of these programs.
The list of peaks is compiled into a buffer by using Peaks and/or using Fit (Fit is recommended for the most accurate peak positions). The peak list is then selected with the button on the upper left. A list of peaks is then shown to the right, where it is possible to select which peaks are used for autoindexing.
Input files are created for all programs that are selected via the checkboxes to the left when the "Run programs(s)" button is pressed. Note that the programs can be in "foreground" (CMPR pauses while the indexing run(s) complete) or in "background" (CMPR continues). If the foreground option is selected, a message is displayed when the run(s) complete and then the output from each program is displayed. Any cells that are located are also summarized in a table. Use of the View button causes the output file to be displayed at the location where the cell is reported and causes the cell to be displayed graphically. This allows the proposed unit cell to be compared to either the input list of peaks or an observed diffraction pattern. If background is selected, then a message is displayed when the runs complete. The "Review Output" button can be used to load the results from all programs, as above, or the output from individual programs can be loaded.
Note that each of the three programs have options that will aid in indexing data where the default options fail. It is possible to override these values from this section. For example, on the index panel example, the maximum cell length allowed by TREOR is increased to 30 Angstrom. Reading the manuals: ITO, DICVOL, NTREOR and cited references for each program is strongly encouraged. values for various program options are provided in the center section of the this page.
Logic (View panel)
This feature is not supported, since the ICDD-JCPDS database is no longer available in the appropriate format. It provided an interface to the ICDD-JCPDS PDF-2 powder diffraction database, when the database has been installed on the local computer. It provides most of the functionality of the LOGIC program, which is documented elsewhere.
If the database is not installed, the Logic notebook tab will be omitted. (See the ENCODE program for information on installing the database.)
After performing a search, the located entries are shown in the index in the lower section of the panel. Note that the fields shown in the index can be changed using the Logic options/index contents menu command. Double-clicking on an entry in the index will show more information about that entry in a separate window (see Browse in the Logic documentation.) A single mouse click causes an entry to be selected (highlighted). After one or more entries have been highlighted, peak positions can be plotted by pressing the "Read in Selected Entries" button.
Interp (View panel)
This panel was initially developed primarily by Dick Harlow with later work from Peter Lee and Brian Toby. It is used to combine and interpolate overlapping datafiles. These routines are still under development, so users should review the output carefully and report problems.
Regions for files that should not be included in the merged file can be specified by pressing the "Add Region" button and then typing the start and ending two-theta value into the boxes. Alternately, pressing the "N" key in the plot window will add a region and pressing the "D" key at the starting and ending two-theta values will enter the cursor position into the boxes.
When the Run button is pressed, a wavelength shift is applied to each file and points are deleted, as requested. The changes are show in the plot window, if the files are displayed. When the merge/rebin is complete, the resulting file is also added to the plot. Note that to restore the data to the original wavelength or to recover the missing points, the rescale panel should be used, selecting "Reset to original values" the X & Y axes.
FitWidths (View panel)
The FitWidth panel is used to fit a set of profile coefficients to a set of peak widths. Most commonly, the peak widths will be dethermined using the Fit panel, but widths can be input from a file or can be input manually.
One a set of peaks have been loaded, GSAS profile terms: U,V & W (centidegrees**2) and X & Y (centidegrees) can then be fit to the widths. The routine will not allow X or Y to be negative, but places no constraints on U, V or W.
The plot range can be changed to show how the function behaves outside of the region where it has been fit.
EditFile (View panel)
The EditFile panel is used to view and possibly change the data & parameters associated with either a diffraction data (xy) file or a set of peaks. Note that this routine (at least at present) only accesses the data values as they were read in and not rescaled values (as computed in the a href="#rescale">Rescale panel).
Once a buffer has been selected, the EditFile panel displays buttons to delete that buffer or to rename it.
Display options (View panel)
The Options entry on the menu bar is used to change the appearance of the program on your screen. By selecting the "Display Options" menu item, a window is created where many options within the program can be selected, see below.
The "Screen Font" menu item can be used to change the sizes of fonts used throughout the program. (See below for information on how to modify the default value for the screen font).
Selecting the "Display Options" menu item opens a window used to set values used in other parts of the program (click here to view). The sections within this window are:
- "Plot options"
- determine how data are displayed and recorded
- "Plot legend" determines if a legend is shown on the right-hand side of the plot.
- "Use Title for Legend" option determines what is shown in the legend. The legend box will list the name of the dataset, unless the "Use Title for Legend" option is selected. When the title is blank, the legend for the dataset is omitted.
Note that clicking on the legend for a file causes that graph to be highlighted. Also, the title for a dataset can be edited in the EditFile panel.
- "Write PostScript" and "Print PostScript" options determine what is done when the the "PostScript out" button is pressed in sections of the program, such as Fit and Plot.
- If "Write" is selected, a file name is specified as the "Postscript file name".
- If "Print" is selected, a UNIX command for processing the file is specified as the "Command to print files" (this option is not available in Windows).
- If "Plot in listed order" is selected, this causes the curves to be overlaid (plotted) in the order they are listed in the file window. This means that the second selected data set will be plotted "on top of" (obscuring) the first. The third obscures the first and second, etc. When this box is unchecked, the overlay order is reversed, with the first selected on top of all the rest.
- "Peak Fit Options"
- are used for the Fit section of the program.
- The "Report fit results in plot window" option controls if the fitted parameters are shown in the plot window or in a separate window.
- "EditCell options"
- are used in the EditCell section of the program.
- "2theta max" determines the maximum hkl value computed by the program
- "max change in cell parameter" controls the range and thus the sensitivity of the sliders
- "HKL label erase time" specifies the number of seconds before reflection labels are erased in seconds. A value of 0 or less means that these labels are not automatically erased.
- "HKL label size" specifies the size of the reflection labels in pixels (or points for negative values).
- "Help Options"
- determine how help information is displayed. Help can be displayed in a browser (Netscape must installed for UNIX systems) or in a help window.
Set working directory
Save WD as starting directoryThe "Set working directory" item in the Options menu allows one to select where CMPR looks for files to read and write, by default. While running it will write certain working files for internal use. The intention is that these working files will be deleted when no longer needed.
If the "Save WD as starting directory" option is used, the current working directory, as set by the "Set working directory" option, will be saved in the file [UNIX] ~/.cmpr_init or [Windows] cmpr.init and CMPR will automatically work in this directory in future sessions.
Help (View panel)
Help can be used to find out more about a section of CMPR. Help can be displayed on a web browser or in a separate window, depending on the setting on the options panel. The web help is more complete, but may be more cumbersome.
Help is invoked by pressing the F1 key or using "Help on current page" in the Help section of the menubar. The help is somewhat context-sensitive help as the section of help information relevant to the current panel is displayed.
When CMPR is properly configured, the program can update itself using the "Updates CMPR" option in the Help menu. If this does not appear in the menu, the prerequisite information is not present. See the Update section for more details.
Update
![]()
The CMPR code is maintained in a subversion (svn) server. At least two versions of CMPR are kept in the repository (at times these versions may be the same.) The development version, at location https://subversion.xor.aps.anl.gov/CMPR/trunk/ has the latest updates to the program but testing of the changes may be incomplete. The standard distribution version, at location https://subversion.xor.aps.anl.gov/CMPR/tags/stable/ has usually gotten more testing. This is the version that is usually distributed. The CMPR project management page https://subversion.xor.aps.anl.gov/trac/CMPR is useful to see what has changed in CMPR and to leave information on bugs and enhancement requests.
The svn program can be used to update the CMPR code as the versions on the repository are updated and a CMPR help option (Update CMPR) has been supplied to do this for you. For this to work, the CMPR distribution must include the hidden subversion (.svn) directories; the svn software must be installed on the computer (svn is included in the standard Windows distribution) and the computer must have an internet connection. Minimal web bandpass is needed unless a very extensive update will be performed.
A second menu command, "Select CMPR version", allows the user to update the CMPR package to the Development version or return to the Standard version. These changes can require datafile transfers of 5 Mb or more and require patience or a faster internet connection.
Note that any locally created files will not be changed by the update procedure. Where svn can patch updates to modified files, it will do so, but on occasion further edits may be needed to resolve conflicts.
CMPR is designed to be expanded. Read the code and send me any extensions you create. Have fun!
Customizing
Customization files
CMPR reads three files when the program starts that can be used for local settings and customization. The files are
These files are used in the order listed above so that .cmpr_defaults/cmpr.defaults will override values placed in .cmpr_init/cmpr.init, which in turn will override values placed in localcmds.tcl/localconfig.tcl. The files that are actually used are listed in the Help/About window.
- localcmds.tcl or localconfig.tcl from the directory where CMPR is installed and then
- file ~/.cmpr_init from the user's home directory [Unix/Mac] or cmpr.init in the Windows home directory (typically c:\Documents and Settings\{username}).
- file ~/.cmpr_defaults from the user's home directory [Unix/Mac] or cmpr.defaults in the Windows home directory (typically c:\Documents and Settings\{username}).
Tcl routines and executable commands can be placed in the first two sets of files (local/.init) but the .defaults file should only be used for setting variables. This file will be written by the Save Options button on the Options/Display options window and/or the Options/Save WS as Starting Directory and the Help/Select CMPR version buttons.
By default the following variables are included in the file: cellparm(alphabeta_tol), cellparm(abc_tol), cellparm(sens), cellparm(fontsize), cellparm(fadetime), gpls(fitinnewplot), gpls(fitonplot), graph(outcmd), graph(outname), graph(printout), graph(font), graph(legend), command(helpmode), which are the contents of the Options/Display options window. Optionally command(initwd) and command(cmprversion) may also be included. Any variable settings added by the user will be retained in this file when the file is written. These files are not required and will only be read if present. An error message is shown if invalid commands are read from a file.
Various Tcl commands can be placed in this file. One example is:
set graph(font) 18This command overrides the default value for the screen font from 14 point (set in the cmpr.tcl file) to 18 point.
set command(maxlines) 100000This command overrides the default value for how many lines can be read from most types of data files. This number is typically not that high so that if by accident a very large non-data file is read, CMPR will not keep reading until memory is exhausted and bad things happen. Change to 100,000 or larger if you use very large diffraction datasets.
Many other options can be modified in this fashion. See the Customize the format list instructions, below for other examples. Users are referred to the CMPR code to find them and see how they work.
Reading directly from GSAS experiments
The read_gsasexp.tcl file reads diffraction data (observed and computed) as well as reflection positions from the GSAS .EXP, .Pxx and .Rxx files. To do this, it must locate the directory containing the GSAS programs tcldump or hstdmp. This is done by searching the directory defined by environment variable GSAS (if defined) and then sequentially the directory below where cmpr is loaded (../gsas), /usr/local/gsas/exe, c:\gsas\exe and ~/gsas/exe. If you do not see a checkbox labeled "GSAS EXP file" for a file format, define the environment variable GSAS to define the location where GSAS is stored or else you can define tcl variable gsaspath to the location where the GSAS executables are found (for example, set gsaspath c:/NCNRfiles/GSAS/exe) in the localcmds.tcl, localconfig.tcl or ~/.cmpr_init (C:\.cmpr_init) files.
Defining File Formats
When CMPR is downloaded, there are a fair number of file formats available for use. If you would like to change the order that files are included or include only specific read or write formats, see the Customize the format list instructions, below. To define new formats for reading a file create a file called read_????.tcl where you supply a name of your choice for '????'. Likewise, to support a new output format, create a write_????.tcl file. Follow one of the other read_*.tcl or write_*.tcl files as an example. Place the file in the same directory as the cmpr.tcl file (and the other .tcl files).
Notes on coding a read_????.tcl file
- Define a commandline option to read a file (optional) using command(cmdopt) and defining a routine associated with the command option for example:
lappend command(cmdopt) -xxx set command(-xxx) readxxxdatadefines that commandcmpr.tcl -xxx yyy.xxxcan be used to read file yyy.xxx using read routine readxxxdata (see below)You can define as many options as you want or none, but be sure to define them in pairs, as above. If you don't want to support reading this type of file from the command line, you don't need to include these two statements.
- Define the dialog access define the text to be shown
lappend command(readtypes) "LHPM/RIET7"define a command to read the datalappend command(readproc) ReadLHPMdefine a list of allowed datatype suffixeslappend command(filterlist) {dat}If you will have upper and lower case versions for Unix, you might want to do the following:if {$tcl_platform(platform) == "windows"} { lappend command(filterlist) {dat} } else { lappend command(filterlist) {dat DAT} }Define a datatype listing (not used at present) to describe the suffix:set command(ReadLHPM_dat_type) "LHPM/RIET7 data" set command(ReadLHPM_DAT_type) "LHPM/RIET7 data"Note that the info in parentheses corresponds to the name used for command(readproc) followed by each value used for command(filterlist).- Define a dialog box read routine This almost always looks the same, except for the readXXXXdata line which refers to the real proc used to read the data.
proc ReadLHPM {file} { global command if {$file == ""} return pleasewait "reading file $file" set ret [readLHPMdata $file] donewait if {$ret != ""} {return $ret} showlastentry $command(read_filelist) }- Define a routine to actually read the data. Try to imagine how the routine will crash and burn when a user specifies a data file with the wrong format.
Look at the other read routines to see examples.
The CMPR program will automatically include the new format the next time it is started. One can to remove a format from the list by changing the file name so that it starts with something other than read_ or end with something other than .tcl, but the file will be restored during the next upgrade, so it is better to customize the format list, as shown below.
Notes on coding a write_????.tcl file
- add the format name to command(writetypes) and the procedure name to command(writeproc)
lappend command(writetypes) ".csv (Spreadsheet)" lappend command(writeproc) writelistcsv- Write a proc to write the data/peaks Note that you can use the statement
if {[set ${data}(type)] == "peaks"} {to take different action depending on if a peak file is being written Likewise, you can use the statementif {$command(writeunits) == 0} {to take different action if scaled values or original values should be written.Look at the other write routines to see examples.
The CMPR program will automatically include the new format the next time it is started. One can to remove a format from the list by changing the the file name so that it starts with something other than write_ or end with something other than .tcl, but the file will be restored during the next upgrade, so it is better to customize the format list, as shown below.
Customize the format lists
There are two methods used to influence what file formats are displayed in the lists for reading and writing formats. The actual lists of files to be read are contained in global variables command(readlist) and command(writelist). The better way to organize file formats is to define variables command(prefreadlist) and/or command(prefwritelist) for files to be listed first and command(skipreadlist) and/or command(skipwritelist) for files that should not be displayed at all. These variables contain a list of fragments for the file names that should be matched. In the match step, letter case is ignored and wildcards * and ? can be used. The formats defined in read_* or write_* files that match the fragments listed in the command(pref*list) lists will be included on the file format list first, while the fragments listed in the command(skip*list) lists will be ommitted from the file format lists.
For example, placed in the localcmds.tcl or cmpr.init (etc.) files:
set command(prefreadlist) "1bm gsas" set command(prefwritelist) "1bm gsas"will cause files read_11bmEpics.tcl, read_1BM.tcl, read_live11BM.tcl, read_gsasexp.tcl, and read_gsasraw.tcl to be ordered first in the read format list and likewise write_gsas.tcl and write_gsasfxye.tcl will be placed first in the write format list (the "1bm" string does not at present match any files). However, all read_*.tcl and write_*.tcl files are placed into the respective format lists. Commandsset command(skipreadlist) "gsas" set command(skipwritelist) "gsas"would be used at an anti-GSAS site, where GSAS read and write options should not even show up in the read/write options. Note if used in both places, pref* will take precidence over skip* options.Alternately, if you only want to have specified formats included, this list can be reordered or redefined. For example, placed in the localcmds.tcl or cmpr.init (etc.) files:
set command(readlist) [list \ [file join $scriptdir read_cmpr.tcl] \ [file join $scriptdir read_gsasraw.tcl] \ ~/mycmprreadfmt.tcl]causes three formats to be used, with the third found in the current user's home directory. One can also use the "lappend" command to add to the list.Note that some files will not appear in the list even when referenced, unless certain prerequisites are met (for example, read_gsasexp.tcl requires that CMPR be able to find a GSAS installation.)
Grace
Grace (xmgrace) is a nice WYSIWYG 2D plotting tool for X Windows. Many UNIX users will be familiar with a prior version of grace, known as xmgr. It is distributed under the terms of the Free Software Foundation public license, and may be downloaded for free. XMGrace runs nicely on the Mac (and is in the Fink and Darwin Ports distributions) and is ususally packaged for most Linux distributions. It probably can be compiled for any version of Unix. It can be installed as part of the cygwin package in Windows. See the grace homepage for more information.
I would like to find a native-Windows program that accepts ASCII input and control files that can be used to generate publication-quality graphics, so that I can generate input files in that format as well.
CMPR Mailing List
If you find CMPR useful, and what to get occasional e-mails on updates and discuss possible upgrades, you are encouraged to join the CMPR mailing list. See the instructions at http://www.aps.anl.gov/mailman/listinfo/cmpr.
Neither the author nor the U.S. Government makes any warranty, expressed or implied, or assumes any liability or responsibility for the use of this information or the software described here. Brand names cited here are used for identification purposes and do not constitute an endorsement by NIST.Brian Toby (brian.toby@anl.gov)
$Revision: 421 $ $Date: 2010-09-03 14:58:59 -0500 (Fri, 03 Sep 2010) $
lastmod(); ?>