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.
Keyboard Shortcuts
|
There are a number of shortcuts implemented by pressing
keyboard keys. A list of them follows, either upper or lower case may be used.
Some of these case will function only in certain sections of CMPR.
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)
in plot window/EditCell panel only
-
shift+left click -- label nearby reflections
-
shift+double left click -- label all reflections
-
shift+right click -- delete reflection labels (Mac: shift+Command+click)
-
H -- label nearby reflections
-
A -- label all reflections
-
D -- delete reflection labels
in plot window/fit panel only
-
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
in any window/any panel:
-
control+C -- exits the program
-
F1 key -- show help on current panel
Also see
Buffer Selection tricks
CMPR consists of a number of program sections (panels) that are
selected using the "notebook tabs" directly below the menu bar.
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, see the Customizing section, below.
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, see the Customizing section, below.
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 designate the formatting.
This panel is also used to change the way a file is displayed.
This is done by selecting the file(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 Changes" button is pressed.
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 constants to add to
the x and y values (addition is done after multiplication).
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.
Changes are applied when the "Rescale" button is pressed.
If more than one scaling or transformation is applied, the
operation is applied to the results from the previous operation.
However, if the "Reset previously applied scaling" checkbox is selected,
the x and y values are reset to the values that were read in,
before any scaling or transformation is done.
The Combine panel is used to create a new buffer set by adding or
subtracting up to five 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.
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.
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 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.
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:
-
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.
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.
-
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.
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).
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.
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.
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.
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 that are selected via the checkboxes to the
left when the "Write file(s) & Run" button is pressed. For each selected
program, it is then possible to select that the program be run in "foreground"
(CMPR pauses while the run progresses) or in "background" (CMPR continues).
Note that values for various program options are provided in the center section
of the this page. Defaults values are used for all program options. However,
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.
Once any of the programs have been run, the output file can be examined
using the "Review Output" button. Two windows are created: the first
shows the output file from the indexing program in a scrollable window and
the second window shows the unit cells that
have been located. Pressing the "Set" button to the left of
any cell parameters causes those values to be loaded into EditCell.
This allows the unit cell to be compared to an observed diffraction pattern.
This panel provides 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.
This panel was developed primarily by Dick Harlow.
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.
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.
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
Rescale 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.
-
"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).
- "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.
The "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] C:\cmpr.init
and CMPR will automatically work in this directory in future sessions.
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.
CMPR is designed to be expanded. Read the code and send me any extensions
you create. Have fun!
Customization files
CMPR reads options for customization sourcing file localcmds.tcl
from the directory where CMPR is installed and then
[UNIX] file .cmpr_init from the user's home directory
or [Windows] C:\cmpr.init. There are no
errors if either or both files do not exist. Various Tcl commands can be
placed in this file. One example is:
set graph(font) 18
This command overrides the default value for the screen font from 14 point
(set in the cmpr.tcl file) to 18 point.
Many other options can be modified
in this fashion. 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 localconfig or
Using the Example File Formats
When CMPR is downloaded, there are a fair number of file formats available
for use. Some are incorporated by default and others do not appear unless you
specifically include them. To access the file formats that are included as
"Example_read_*.tcl" files, you need to either rename them to "read_*.tcl",
create a link to these files (in UNIX) or specifically cause them to be loaded.
Renaming them is simplest, but has the disadvantage that the files will not be
updated if you update CMPR.
I recommend creating a reference to the desired files in your
localcmds.tcl or ~/.cmpr_init (C:\.cmpr_init) file,
as this method works on either platform. Create (or append) to either file
a line like this:
source $scriptdir/Example_read_cpi.tcl
to have the appropriate file format included.
Supporting Additional File Formats
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.
Note that formats are listed on the menu alphabetically by file name.
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) readxxxdata
defines that command
cmpr.tcl -xxx yyy.xxx
can 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 data
lappend command(readproc) ReadLHPM
define a list of allowed datatype suffixes
lappend 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. Likewise, to remove a format all that need be done is to change
the file name so that it starts with something other than read_ or end with
something other than .tcl, for example note the files named Example_read_*.tcl.
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 statement
if {$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. Likewise, to remove a format all that need be done is to change
the file name so that it starts with something other than write_ or end with
something other than .tcl.
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.
Grace runs on practically any version of Unix.
As well, it has been successfully ported to VMS, OS/2 and
Win9*/NT.
Use in Windows may be somewhat clumsy, as a X-Windows package is required.
See the
grace homepage at http://plasma-gate.weizmann.ac.il/Grace/ for more
information.
I would like to find a 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.
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: 1.11 $ $Date: 2006/01/08 23:33:35 $
Last modified 08-January-2006 by website owner: NCNR (attn: Craig Brown)
