The Portable CMPR & LOGIC programs

New version, October 2003

Introduction

CMPR is a multipurpose program that can be used for displaying diffraction data, manual- & auto-indexing, peak fitting and other nifty stuff. I started writing this program as a replacement for a program by the same name that was part of my VAX Powder Suite package. This version of CMPR has evolved to have many features not present in the VAX program. I consider CMPR to be my "swiss army knife" for diffraction. Any useful manipulation that I need that does belong anywhere else will probably end up in CMPR.

The LOGIC program also dates back to the Powder Suite package. It is used to locate entries in the ICDD-JCPDS PDF-2 powder diffraction database that match specifed conditions, i.e. contain certain elements and not others, have peaks in certain locations, but do not have peaks in certain other locations. The database must be licensed from the International Centre for Diffraction Data for every computer where the database will be used. The VAX LOGIC program originated the concept of full Boolean logic searching of multiple database fields, which is now the basis for the ICDD PDF-4 product. Unlike the ICDD's PDF-4 product, LOGIC allows searching on only a very limited number of fields: chemical composition, number of unique elements, peak positions & intensities, subfiles and entry number. Entries can also be located that by matching text strings. The capabilities of LOGIC can also be accessed with in CMPR, which allows database patterns to be plotted along with experimental data.

Note that if access to the ICDD database is not purchased, the LOGIC program cannot be run, except with test data. No such requirements apply to the CMPR program, which is freely distributed.

Both CMPR and LOGIC should run on most common computer platforms, provided Tcl/Tk and (for CMPR) BLT are ported (see below). CMPR and LOGIC are developed and tested primarily in UNIX (SGI and Linux computers), and get limited testing in Windows (-95 through -XP). A distribution (or at least installation instructions) for Mac OS X binaries are planned for the near future (November or December of 2003). Copies of the Tcl/Tk and BLT packages, are included in the Windows distribution, but will need to be loaded separately on other all other platforms.

Program Documentation

The use of each program is documented in separate web pages: CMPR and LOGIC.

Acknowledgments

CMPR and LOGIC incorporate a number of FORTRAN/C programs written by others. Further, some of the programs written by me incorporate code from other people's programs, or were inspired by looking at code from others. Here are some of the sources:

• The reflection generation code traces back to the NIST AIDS*83 program (C. Hubbard, J. Stalick, A. Mighell & others),
• space group extinctions from NRC symmetry codes (A. C. Larson),
• peak fitting uses GPLSFTA (D. Cox, W. Hamilton, L. Finger & many others),
• Gaussian smoothing/peak search routines were supplied by R. Harlow and A. McGhie.
• Sections in LOGIC were inspired by the work of Ray Goehner, Mary Garbauskas, Gerry Johnson and Richard Harlow. Many subroutines used to parse and display PDF-2 (AIDS*83) entries were written by Mark Holomany.

The CMPR program provides a user interface to several auto-indexing programs that were written by other authors:

• the ITO autoindexing program was written by Jan W. Visser [J. Appl. Cryst. 2,89 (1969)], with contributions from Robin Shirley and Jerry G. Johnson, Jr.
• the DICVOL autoindexing program was written by A. Boultif and D. Louër, [J. Appl. Cryst. 24, 987-993 (1991)]
• the TREOR autoindexing program was written by Per-Erik Werner [J. Appl. Cryst. 18, 367-370 (1985)]. Note that a newer version of TREOR is due as part of the EXPO package soon, look for "Indexing by N-TREOR in EXPO" by C. Giacovazzo et al. in J. Appl. Cryst..

Mailing List

If you use CMPR, please drop me a line to get on the mailing list. (Click here.) By doing this, you will hear about updates (but not very often; nor will you get e-mail through this list about anything else). Having a list of users might help me show my management that these tools are valuable to the scientific community; this could result in more CMPR/LOGIC development.

Installation Instructions

Windows:

For Windows, CMPR, LOGIC and other required files are most easily installed by running a single self-installing executable file.

1. If you will be using the ICDD-JCPDS PDF-2 powder diffraction database, you should install that first.

2. Download and run the CMPR/LOGIC self-installer (~7 Mb) from the NIST website: ftp://ftp.ncnr.nist.gov/pub/cryst/powdersuite/cmpr+logic.exe or one the CCP14 mirrors [(UK), (Canada), (US) or (Australia)].

   The self-installer program will take you through the usual process of installing a Windows application, including offering you several choices:

   • Where should the programs be installed on your computer?

     The default answer of c:\Program files\CMPR will be fine for most people.

   • Where in the startup menu should the shortcuts to CMPR and LOGIC be placed?

     The default answer of a folder named CMPR & LOGIC will be fine for most people.

   • Should the CMPR and LOGIC shortcuts also be placed on the desktop?

     This is a matter of personal preference.

   • Should the ENCODE program be run to create the files need by LOGIC from the ICDD PDF-2 file?

     The ENCODE program reads the ICDD-JCPDS PDF-2 powder diffraction database and creates the index and pointer files needed to use the LOGIC program. If the PDF-2 file is not available, a small amount of test data is distributed with the program to use in the ENCODE program to demonstrate how LOGIC works.

UNIX:

The process of installing CMPR and LOGIC on all types of Unix systems follows the same outline:

1. If you will be using the ICDD-JCPDS PDF-2 powder diffraction database, you should install that first.

   You will either need to use a Windows PC to unpack and install the database from CDROM and then move the file to your Unix system (note that you may not access the file from two computers on a single license), or you will need to get a copy of the database from the International Centre for Diffraction Data in a format that can be read on your system (for example, a CD-ROM with the database compressed using PKZIP/WINZIP or gzip).

2. Download and install the Tcl/Tk packages

   Note that Tcl/Tk is preinstalled in many versions of Unix, such as LINUX. It is available prepackaed for installation on many other operating systems. You may need (or prefer) to compile it yourself.

3. Download and install the BLT package

   While there are some versions of BLT prepackaged, it other cases you may need to compile it yourself. Perhaps someday, it may be integrated with Tcl/Tk which would make this part of life easier.

4. Download the CMPR & LOGIC distribution.

   Obtain the CMPR/LOGIC distribution from from the NIST website: ftp://ftp.ncnr.nist.gov/pub/cryst/powdersuite/cmpr_alpha.tar.gz (~1.4 Mb)
   or one the CCP14 mirrors [(UK), (Canada), (US) or (Australia)].

5. Compile the CMPR & LOGIC programs.

   Select compilation options by creating files src/make.inc and logic/Make.inc (see Makefile vars below) in an editor. Then compile the programs using

        make all
   

   On Linux and SGI computers, pre-made versions of the src/make.inc and logic/Make.inc files can be loaded and the compilation performed in a single step using the command

        make linux
   

   or

        make sgi
   

   Alternately for Linux and SGI platforms, the executable files (~1 Mb) can be downloaded using from the NIST website (also available on the CCP14 mirrors):
   ftp://ftp.ncnr.nist.gov/pub/cryst/powdersuite/cmpr_linux_binary.tar.gz
   or ftp://ftp.ncnr.nist.gov/pub/cryst/powdersuite/cmpr_sgi_binary.tar.gz

   Note that the script used by make (Makefile) use some conditional features of GNU make. If you only have access to your local system's version of make, you may need to uncomment the definition of SYSTEM and set the value of INSDIR manually.

6. Put CMPR, LOGIC and the ENCODE Tcl/Tk scripts, which are named respectively,

      .../cmpr/cmpr.tcl, 
      .../cmpr/logic/logic.tcl
      .../cmpr/logic/encode/encode.tcl
   

   into the path so they may easily be run. There are at least three ways to do this:

   • include the CMPR directories in the search path (not recommended)
   • create short shell scripts that call these Tcl/Tk scripts
   • create links in a system directory to the Tcl/Tk scripts

   This latter approach can be invoked using command:

       make install
   

   This creates links to the CMPR, LOGIC and ENCODE scripts in /usr/local/bin, /usr/bin or ~/bin (whichever is found in your path). You can force the install directory to be a different location by specifying the directory using make variable INSDIR, for example:

       make install INSDIR=/opt/bin
   

7. Index the PDF-2 database

   If you will use the ICDD-JCPDS PDF-2 powder diffraction database you will need to run the ENCODE script (see below). The script can be invoked using the "pdfencode" shortcut created above, or type command

        wish /my/install/path/cmpr/logic/encode/encode.tcl
   

   Repeat this when you upgrade the PDF-2 database.

Mac OS X:

The general directions for installing CMPR follow those of the above Unix directions. These instructions assume you have X11 and Fink already installed on your computer. If you wish to compile the programs, you will also need to have gcc and g77 installed.

1. If you will be using the ICDD-JCPDS PDF-2 powder diffraction database, you should install that first.

   You will either need to use a Windows PC to unpack and install the database from CDROM and then move the file to your Mac (note that you may not access the file from two computers on a single license), or you will need to get a copy of the database from the International Centre for Diffraction Data in a format that can be read on your system (for example, a CD-ROM with the database compressed using PKZIP/WINZIP or gzip).

2. Download and install the Tcl/Tk & BLT packages

   On the Mac this is easy: use command

        sudo apt-get install tcltk blt
   

3. Download the CMPR & LOGIC programs.

   Obtain the CMPR distribution from the NIST website: ftp://ftp.ncnr.nist.gov/pub/cryst/powdersuite/cmpr_alpha.tar.gz (~1.4 Mb) as well as the OS X executables: ftp://ftp.ncnr.nist.gov/pub/cryst/powdersuite/cmpr_osx10.2_binary.tar.gz (~3 Mb) (skip this if you will compile the files yourself in the next step). These files can also be downloaded from the CCP14 mirrors [(UK), (Canada), (US) or (Australia)].

   Assuming that you downloaded the above file to your desktop and wish to install the files in directory /Users/[me]/Programs/cmpr (where [me] is your username), you will use commands like this:

        cd 
        mkdir Programs
        cd Programs
        tar xvzf ~/Desktop/cmpr_alpha.tar.gz
        tar xvzf ~/Desktop/cmpr_osx10.2_binary.tar.gz
   

4. Compile the CMPR & LOGIC programs (skip if exectables were downloaded).

   Configure and compile the programs using command

          make osx
   

5. Add shortcuts to the applications menu (or whatever)

   I need advice here from an expert...

6. Make command line shortcuts for the CMPR, LOGIC and the ENCODE Tcl/Tk scripts (optional)

   The scripts that need to be run are named

        .../cmpr/cmpr.tcl, 
        .../cmpr/logic/logic.tcl
        .../cmpr/logic/encode/encode.tcl
   

   
   for CMPR, LOGIC and ENCODE, respectively. If you want to run them from the command line they need to be inserted into the path so they may easily be run. There are at least three ways to do this:

   • include the CMPR directories in the search path (not recommended)
   • create short shell scripts that call these Tcl/Tk scripts
   • create links in a system directory to the Tcl/Tk scripts

   This latter approach can be invoked using command:

       sudo make install
   

   This should creates links to the CMPR, LOGIC and ENCODE scripts in /usr/local/bin. You can force the install directory to be a different location by specifying the directory using make variable INSDIR, for example:

       sudo make install INSDIR=/opt/bin
   

7. Index the PDF-2 database

   If you will use the ICDD-JCPDS PDF-2 powder diffraction database you will need to run the ENCODE script (see below). The script can be invoked using the "pdfencode" shortcut created above, or type

       /sw/bin/wish /my/install/path/cmpr/logic/encode/encode.tcl
   

   Repeat this when you upgrade the PDF-2 database.

Using the ENCODE program

Three programs must be run to read the ICDD-JCPDS PDF-2 powder diffraction database and create a series of "index" files that allow the LOGIC program to rapidly search and access records in the database. It also creates a file (Unix, ~/.icdd_files_loc or Windows, c:\icddloc.txt) that specifies the location of the database files. If this file is not present, the LOGIC program will not run and the LOGIC panel will not be available in the CMPR. Note that the LOGIC programs actually looks in additional locations as well, see below, but the ENCODE script writes either in ~/.icdd_files_loc or c:\icddloc.txt.

To faciliate running these programs, the CMPR/LOGIC package includes a script (encode.tcl) that obtains file locations as input and then runs these programs and creates the required files. This script can be run as part of the self-installation program on Windows or from the start menu. On Unix, the shortcut "pdfencode" is created to this script.

The menu produced by the ENCODE program appears to the right. Note that there are six input fields:

Output directory

Where files will be written; users should not need to change this.

Input PDF2 file

The location of the ICDD PDF-2 database, pdf2.dat. This may default correctly in Windows, but will need to be set on other platforms.

Local PDF2 file

The location of local PDF-2 entries, if any: It is possible to include extra entries to the LOGIC program, provided these entries are coded in the NIST AIDS*83 format. If this is done, the entries are included with the ICDD-JCPDS entries for searches and display. Please note, this capability has not been tested in many years. Contact the program author, if problems are noted.

Deleted pattern treatment: Include deleted patterns

The ICDD-JCPDS database includes entries that the editors have later flagged as "deleted" when better patterns have been obtained. Some users wish to see these entries, some do not. If these patterns are included in the index files, it is possible to eliminate them from any search later. Note that if deleted patterns are included, their entry numbers are flagged with a suffix "D".

Deleted pattern treatment: Include peak positions for deleted patterns

If deleted patterns are included, using the previous option, you have the choice to include only chemical and reference information. Alternately, peak positions may also be included for deleted patterns, in which case they will be found during peak location searches.

Write peak indexes at

Peak index files: LOGIC can be used to search for entries with peaks in particular locations and with specified intensities, referenced as a percentage of the maximum peak height. The user can select which index files are written. Two index files are always written: one containing the three strongest peaks and one with all peaks. Specify here the index files you want created, where 70 and 30 (the defaults) specify an index to peaks 70% and 30%, or greater, respectively. Any number of index files can be written.

After all input has been supplied, the "Install PDF-2" button should be pressed. This starts the three programs, which can take a few minutes to a few hours to run.

---

LOGIC looks in the following locations for database locations:

1. a file pointed to by an environmental variable, LOGIC_LOC,
2. if not successful, then file .icdd_files_loc in the user's Home directory ("C:\" in earlier versions of Windows and "C:\Documents and Settings\[user]" and in later versions of Windows.)
3. if not successful, then /usr/local/icdd_files_loc.txt
4. if not successful, then file icddloc.txt in the current working directory
5. finally, if not previously read, then C:\icddloc.txt

If the file is not found, an error message is generated in program LOGIC, but the CMPR does not generate any error messages.

---

Makefile variables

The following Makefile variables may need to be set, to adapt compilation to suit your flavor of Unix.

Symbols in file src/make.inc

FC

FORTRAN compiler name (g77, f77, etc.)

FFLAGS

FORTRAN compiler command-line options

EXESUFFIX

suffix on executable files (.EXE for windows and usually blank in Unix)

Symbols in file logic/Make.inc

FC

FORTRAN compiler name (g77, f77, etc.)

CC

C compiler (gcc, cc, etc.)

F2CLIB

extra libraries needed by FORTRAN programs, if any

FFLAGS

FORTRAN compiler command-line options

CFLAGS

C compiler command-line options

LIB

name of logic subroutine library, usually ../logic.a

EXESUFFIX

suffix on executable files (.EXE for windows and usually blank in Unix)

RANLIB

set to ranlib, if needed with ar; set to echo otherwise

NAMEOPTION

Compiler flags that determine the naming conventions used in C for FORTRAN subroutines. (See below)

Options for the NAMEOPTION variable

There are differences the naming and length conventions by different FORTRAN and C compilers. To allow the code to be used on different platforms, several C macros must be defined to within a C header file (srclogic/logicmap.h and encode/logicmap.h). One of each set of values must be passed to the compiler (for example, "NAMEOPTION = -DTWOSCORE -DBIT32").

Three different methods are defined to map between FORTRAN and C names, according the value of NAMEOPTION:

ONESCORE

where one _ character is appended
The SGI f77 compilier adds an underscore (_) to the names of FORTRAN subroutines.

TWOSCORE

where one or two _ characters are appended
The GNU g77 compilier adds an underscore to the names of FORTRAN subroutines except in the case of names that already contain an underscore, g77 adds two.

NOSCORE

where no _ are appended
The HP fort77 compilier does not add any underscores.

If you see error messages of with undefined references to subroutines named ps_* or psl_* you have likely selected the wrong option here.

Three options are defined for the mapping of variable types between FORTRAN and C (for example, does INTEGER*4 correspond to long or int or even short in C).

BIT16

used for 16 bit operating systems (are there any left?)

BIT32

used for 32 bit operating systems

BIT64

used for 64 bit operating systems (none have been tested)

---

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@NIST.GOV)
10/2003