%CLD%Module SEARCH_SUBCOMMANDS
%CLD%
\Program SEARCH
%HLP%1 HELP
%HLP%          Information on commands within program SEARCH

 Program SEARCH is used to search the ICDD-JCPDS database to find 
 known phases matching a diffraction pattern from an unknown 
 materials, which may contain one or more phases. 

 When running program SEARCH, it is first necessary to set up the
 search by specifying the peak positions and the parameters which
 govern how the search will be performed. The |READ| command may
 be used to read in a peak/data file. As an alternative to supplying 
 peak positions from a file, peak positions may be input using the 
 |EDIT| command, which invokes the peak list editor. If SEARCH has 
 previously been run, the previous peaks and parameters may be 
 reloaded using command |LOAD|. 

 Search parameters may be modified using commands |SET|, |STARTFILE|, 
 and |TITLE| and displayed using command |SHOW|. 
 Peak positions and intensities may be modified using the |EDIT| command. 
 Units for peak positions may be d-spaces or \twotheta\ angles, as 
 selected using the |WAVELENGTH| command. 
 The inclusion of deleted patterns may be set using command |DELETED|.

 After the search parameters have been set, the search is performed
 using command |SEARCH|, which is equivalent to entering commands
 |REDUCE|, |MATCH| and |REPORT|. ICDD-JCPDS entries which have been 
 selected as potential ``hits'' are written onto a file which may be 
 read by the LOGIC program. Command |LOGIC| starts this program and
 passes the file of ``hits.''\par
\! Other commands available within SEARCH are: |DCL|, |HELP|, |FILE|, 
\!|EXIT| and |QUIT|.\par
%HLP% The entire list of available commands is given below. For additional
%HLP% information about any of these commands, enter the name at 
%HLP% the Topic? prompt. It is also possible to use the HELP command
%HLP% for help on a specific command from within SEARCH. Type
%HLP%        HELP command_name
%HLP% at the SEARCH> prompt (For example: SEARCH> help exit).
%HLP%1 Intro_to_search
 A search consists of four steps:
\TAB 1  Setting the scope of the search -- restricting the 
	search to the entries in a ICDD-JCPDS subfile or by using 
	chemistry to constrain the search (command |STARTFILE|);
\TAB 2  Reducing the extent of the search by dropping entries that
	are unlikely to be ``hits'' (command |REDUCE|):
\! \TAB{}
	  -- by eliminating entries that do not have at least one strong 
	  peak matching one of the observed strong peaks [``Required Lines''];
\! \TAB{}
	  -- by eliminating entries that have a strong peak in reqions 
	  of the observed pattern where no significant intensity 
	is present [``Forbidden Lines''];
\TAB 3  Matching the remaining ICDD-JCPDS entries against the list of
	observed peaks -- ICDD-JCPDS entries with too many unmatched peaks
	or not matching a sufficient number of observed peaks are
	dropped; the remaining entries are written as a user subfile
	(command |MATCH|);
\TAB 4  Evaluating the ``goodness of fit'' between each 
	remaining entries and the observed pattern -- optionally, 
	the remaining entries may be ranked and the entries with the 
	best fits may also be written as a user subfile (command REPORT).

  The |SEARCH| command performs steps 2, 3 and 4 and thus is equivalent 
  to using the |REDUCE|, |MATCH| and |REPORT| commands sucessively.
  These steps must be performed in order, but any step may be omitted.
%CLD%Define verb DCL 
%CLD%
\Command DCL\par
 Spawns a subprocess to execute DCL commands, type LOGOUT to 
 return back to SEARCH loss of the current work. 
 This command is useful for quick DCL ``errands'' such as answering a 
 mail message without exiting the program.
%CLD%Define verb EDIT
%CLD%
\Command DELETED\par
 Some of the entries in the database are marked as ``deleted'' by the
 editors of the database. If these entries are included in the database
 (using the ENCODE program, PDF1) it is possible to select that these
 entries will be included or excluded from the operations of this
 program. 

 This command causes logical name |PS_DELETED| to be set so that 
 subsequent operations with the program and with other programs in the
 Powder Suite package will use the same option. The default mode for
 the program is |DELETED/EXCLUDE|. However, if desired the |PS_DELETED|
 logical name may be predefined (see customization instructions) to change
 the default.
\Qualifiers
\qual 
/INCLUDE\par
 Specifies that deleted entries will be included in the logical operations.
\qual 
/EXCLUDE\par
 Specifies that deleted entries will be not be included in the logical operations.
%CLD%Define verb DELETED
%CLD%	Qualifier INCLUDE
%CLD%	Qualifier EXCLUDE
%CLD%
\Command EDIT\par
Used to edit the list of peaks. Peaks may be added, deleted or changed.
This operation must be done interactively. Note that intensities may 
be input with an arbitrary scale, but will be normalized internally 
before use.
%CLD%Define verb EXIT
%CLD%
\Command EXIT\par
 Type EXIT (which can be abbreviated to EX) to exit from the program.
 Alternately, pressing Control Z (|^Z|) will also cause the program 
 to exit. Either causes the current search information to be written 
 onto a load file (see commands |SET/NAME| and |LOAD|.)

 When the load file is written, logical device name |SEARCH_FILE| 
 is defined as the name of the load file. If program SEARCH is
 restarted in the same login session, the file defined by 
 |SEARCH_FILE| (if any) may be read. 
%CLD%Define verb FILE
%CLD%	Parameter P1, label file_name, value(type=$file)
%CLD%
\Command FILE\par
 Allows a series of commands to be input to the program from an external
 file. The file should be prepared before starting the program, or using
 the |DCL| command to invoke an editor. 
\Parameter
\parm
file_name\par
 A single file may be specified on the command line containing the name
 of the file with commands. If the file is not specified, a prompt will be
 given to request a file name. 

 If no file extension is supplied, the default extension is |.CMD|
%CLD%Define verb HELP
%CLD%	parameter P1, value (type = $rest_of_line)
%CLD%
\!\Command HELP\par
\! Invokes the VAX/VMS online help facility for help on this program.
%CLD% 
%CLD%Define verb IGNORE
%CLD% 
\Command IGNORE\par
 This command is used to display and modify the range of angles/d-spaces 
 which are used when searching the ICDD-JCPDS database. The ranges that have 
 been set to be ignored are called ``excluded regions.'' Peaks in a 
 ICDD-JCPDS entry which are located in an excluded region are ignored,
 e.g. their presence will not disqualify the entry in the |REDUCE| step,
 nor will they be counted as unmatched peaks. Similarly, observed peaks 
 which fall inside an excluded area are not used for searching and are
 not counted toward the percentage of matched peaks.

 Two common applications which require use of excluded regions are:
 (1) to insure that only peaks on ICDD-JCPDS entries within the observed
 \twotheta\ region are used -- the regions below and above the measured
 diffraction pattern should be excluded. (2) to account for interference
 from known or identified phases. For example, if silicon is used as an
 internal standard, the silicon peaks could obscure a peak from an 
 unknown phase. Thus, the regions immediately surrounding the silicon 
 peaks should be treated as unknown and thus should be excluded from
 consideration.
 
 Qualifier |/EXCLUDE| is used to add or increase the size of an
 excluded region and |/INCLUDE| is used to reset a region
 so that it is no longer excluded. Qualifier |/PEAK| is used to 
 specify peaks to be excluded and qualifier |/RANGE| is used to 
 a region to exclude/include. Alternately, qualifier |/CARD| is used to 
 exclude all peaks in a ICDD-JCPDS entries above a threshold intensity.
 Qualifier |/DISPLAY| is used to display the current list of excluded
 regions.

 When a raw datafile is read into this program, regions outside the range
 of the collected data are excluded. If a list of peaks is read from 
 a peak file without a datafile, the regions below the lowest angle 
 and above the highest angle are excluded. These excluded ranges may be 
 extended using |/EXCLUDE| and reduced using |/INCLUDE|. 
%CLD%	Qualifier DISPLAY, nonnegatable
\qual
/DISPLAY\par
 Qualifier |/DISPLAY| produces a listing of the current ``excluded regions''. 
 If this qualifier is combined with other qualifiers, the excluded regions
 will be displayed after any changes.
%CLD%	Qualifier CARD, value(type=$number), nonnegatable
\qual
/CARD=jcpds_card\<
/CARD\par
 Qualifier |/CARD| excludes regions surrounding a ICDD-JCPDS entry. If 
 supplied, |jcpds_card| is the 5 or 6 digit ICDD-JCPDS set and entry number 
 (e.g. |/CARD=110011|). The width of the region around each peak may be 
 specified using qualifier |/WIDTH| and the intensity threshold for 
 ignored peaks may be specified using |/IMIN|.
 Qualifier |/CARD| cannot be used with |/INCLUDE| or |/EXCLUDE|.
%CLD%	Qualifier IMIN, value(type=$number,required), nonnegatable
\qual
/IMIN=min_inten\par
 |/IMIN| specifies the minimum intensity for ICDD-JCPDS peaks which will be 
 ``excluded''. Peaks with relative intensity below |min_inten| (in units of
 \% of the most intense peak) will not be used.
 Qualifier |/IMIN| cannot be used with |/INCLUDE| or |/EXCLUDE|.
%CLD%	Qualifier INCLUDE, nonnegatable
\qual
/INCLUDE\par
 Specifies that the region or list of peaks (see |/RANGE| and |/PEAK|)
 will be reset so that these areas will be used in (will not be 
 ``excluded'' from) the search.

 Note that if |/CARD| has been used previously, all peaks that lie 
 in the region to be included will be no longer be excluded.\par
 Qualifier |/INCLUDE| cannot be used with |/CARD| or |/EXCLUDE|.
%CLD%	Qualifier EXCLUDE, nonnegatable
\qual
/EXCLUDE\par
 Specifies that the region or list of peaks (see |/RANGE| and |/PEAK|)
 will be set so that these regions will be ``excluded'' from the 
 search.\par
 Qualifier |/EXCLUDE| cannot be used with |/INCLUDE| or |/CARD|.
%CLD%	Qualifier PEAK, value(list), nonnegatable
\qual
/PEAK=position_list\<
/PEAK\par
 Specifies a list of regions to be excluded or included in the search
 (see |/EXCLUDE| and |/INCLUDED|). The positions are the approximate centers 
 of the regions; the length of each region will depend on the value of 
 |DEL_2THETA| (see |/WIDTH|.)

 More than one position may be specified by enclosing the list in
 parentheses and separating the points by commas, e.g.
\TAB {}   |/PEAK=4.0| or
\TAB {}   |/PEAK=(4.0,6.0)|\par
 The units for |position_list| will be d-spaces in \AA, unless 
 a wavelength has be set, in which case the units will be degrees 
 \twotheta\ at the current wavelength.\par
 Qualifier |/PEAK| cannot be used with |/RANGE| or |/CARD|.
%CLD%	Qualifier WIDTH, value(required), nonnegatable	
\qual
/WIDTH=D_2THETA\par
 |D_2THETA| defines the half width to be allowed around a position 
 specified using the |/EXCLUDE| or the |/INCLUDE| qualifiers or the
 ICDD-JCPDS peaks from a entry specified using the |/CARD| qualifier. The
 units for |D_2THETA| are degrees \twotheta\ for Cu \Kalpha1\ 
 radiation.  |D_2THETA| may be a floating point number.
%CLD%	Qualifier RANGE, value(list), nonnegatable
\qual
/RANGE=(min,max)\<
/RANGE\par
 Specifies a single regions to be excluded or included in the search
 (see |/EXCLUDE| and |/INCLUDED|) by specifying an upper and lower limit. 
 The limits must specified by as a list inside parentheses and separated 
 by commas, e.g.
\TAB {}   |/RANGE=(4.0,6.0)|\par
 The units for |position_list| will be d-spaces in \AA, unless 
 a wavelength has be set, in which case the units will be degrees 
 \twotheta\ at the current wavelength.\par
 Qualifier |/RANGE| cannot be used with |/PEAK| or |/CARD|.
%CLD%	Disallow ANY2(CARD,INCLUDE,EXCLUDE)
%CLD%	Disallow ANY2(PEAK,RANGE)
%CLD%	Disallow WIDTH and RANGE
%CLD%	Disallow IMIN and (EXCLUDE or INCLUDE or PEAK or RANGE)
%CLD% 
%CLD%Define verb LOAD
%CLD%	Parameter P1, label file_name, value(type=$file)
%CLD%
\Command LOAD\par
 This command is used to reload the output file (``load file'') from 
 a previous run of SEARCH so that parameters may be easily 
 changed. Thus the search run may quickly repeated with a new set of 
 parameters, allowing the widening of a search that failed to find 
 any matching phases or narrowing of a search that yielded too many 
 unlikely matches.

 The ``search name'' (see command |SET /NAME|) is set as the name of 
 the LOAD file, after dropping the file extension, if one has been 
 supplied.
\Parameter
\parm
file_name\par
 A single file may be specified on the command line containing the name
 of the file to be read. If the file is not specified, a prompt will be
 given requesting a file name to read. 

 The default file extension for the ``load file'' is |.SEA_IN|. 
%CLD%Define verb LOGIC
%CLD%
\Command LOGIC\par
 This command causes the SEARCH run to be terminated and program 
 LOGIC to be started. The results from the most recent search will 
 be passed to program LOGIC. The program will save the current SEARCH 
 parameters on a load file for future use before transferring control 
 to program LOGIC.
%CLD%Define verb MATCH
%CLD%
\Command MATCH\par
 This command causes the program to invoke the |MATCH| step in the 
 search procedure. In this step peaks in the observed pattern are 
 compared line-by-line to the peaks in each possible hit remaining 
 after the |REDUCE| step (or in the starting subfile, if the |REDUCE| 
 step will be omitted). If the positions of two peaks (as \twotheta\ 
 values for Cu\Kalpha1) agree within |DEL_2THETA|, the peaks are 
 considered to ``match'' (see |SET/ERROR|).

 For a JCPDS-ICDD entry to be retained by the |MATCH| step as a ``hit'' 
 all but |DB_max_miss| of ICDD-JCPDS peaks above |DB_min_int| percent
 relative intensity must be matched (see |SET/DB_IMIN| and |SET/MAXDBMISS|). 
 Also, at least |OBS_min_lines| percent of the lines above |OBS_min_int|
 percent relative intensity must be matched (see |SET/MATCHOBS| and
 |SET/OBS_IMIN|.
%CLD%Define verb QUIT
%CLD%
\Command QUIT\par
 Type QUIT to exit from the program without writing a load file or 
 updating logical name |SEARCH_FILE|.
%CLD%Define verb READ
%CLD%	Parameter P1, label file_name, value(type=$file)
%CLD%
\Command READ\par
 Reads a list of peak positions and optionally a raw data file. Peaks 
 in the peak list that are assigned to the \Kalpha2\ wavelength will be 
 ignored all others will be converted to d-spaces. 

 The ``excluded regions'', the ranges of d-spaces which are ignored 
 during searching, are reset by the READ command. (See command |IGNORE|  
 for more information about excluded regions). If peaks are input 
 without a data file, the regions of d-spaces outside the range of 
 peaks will be excluded. If a diffractogram is input as well, the regions 
 outside the range of collected data will be excluded rather than the 
 range of the data points (the collected data will usually cover a 
 signifcantly larger region than the range of peaks). If the 
 diffractogram will be used for FOM computations (see |SET/FOM| and
 |REPORT|), the background should be subtracted, prior to reading it in
 to SEARCH.

 The search name is defined from the peak file name (including 
 the device and directory if specified), but the file extension is 
 dropped. This file name is used to define the names of the ``load 
 file,'' which is used for temporary storage of the current 
 SEARCH settings; the ``search output file,'' which will contain
 a user subfile created with the matches from the search; a 
 ``search report,'' if command |REPORT| is used to prioritize the 
 matches; and a ``starting subfile,'' if the |STARTFILE| command is 
 used to spawn program LOGIC to create a subfile to narrow down the
 search using chemistry. See information on the |SET /NAME| 
 subcommand, for more information on file naming.\par
%HLP% More information on peak and data files can be found in the 
%HLP% File_formats help entry.
\! See the section on File Formats in the first chapter for more
\! information on formats for peak and data files.
\Parameter
\parm
file_name\par
 A single file may be specified on the command line containing the name
 of the file to be read. If the file is not specified, the program will 
 prompt for a file name to read.

 It is usually preferable to supply the file name without a file 
 extension, as the default extension will then depend on the file
 format. This improves the speed that the program has available 
 when searching for the file.
%HLP% See the help entry on File_formats for more information.
 The subroutines which read data and peak files, (subroutines 
 |READDATA| and |READPEAK| respectively), will attempt to determine 
 the format of the file from the file contents and the extension.
\Qualifier
\qual 
%CLD%	Qualifier FORMAT, value(required), nonnegatable	
/FORMAT=fileform\par
 This optional qualifier may be used to specify the file format that will
 be used for reading the file.
\! (See the information on File Formats for the |fileform| codes).
%HLP% (See the help entry on File_formats for the |fileform| codes).
 In most cases it is not necessary to specify the file format, as the 
 program will discern the file format from the file. However, in certain
 cases where problems are encountered, it may be necessary to use the 
 format option.
%CLD%Define verb REDUCE
%CLD%
\Command REDUCE\par
 This command causes the program to reduce the number of ICDD-JCPDS 
 entries that will be considered during the search by dropping entries 
 that are unlikely to be ``hits'' by performing two screening steps:
\! \itemitem{$\bullet$}
	entries are eliminated if they do not have at least one strong 
	peak matching one of the observed strong peaks [``Required Lines''];
\! \itemitem{$\bullet$}
	entries are eliminated if they have a strong peak in reqions 
	of the observed pattern where no significant intensity 
	is present [Forbidden Lines];\par
 The screening steps improve the speed of searching the database because they
 use the bitmap indices to eliminate rapidly from consideration entries that 
 cannot match the observed pattern. 
 
 The ``Required Lines'' screening step is governed by variables 
 |Req_Index|, |R_Imin| and |DEL_2THETA|, which are changed using command 
 |SET| (see qualifiers |/R_INDEX|, |/Rmin| and |/Error|). 
 This step looks up each peak in the observed pattern above 
 |R_Imin|\% relative intensity in a peak index file selected by |Req_Index|.
 The peak positions in observed pattern and database must be within
 |DEL_2THETA| to match. Thus, patterns which do not have an observed peak 
 matching some peak in the JCPDS-ICDD database within |DEL_2THETA| will be 
 eliminated from further consideration as a potential match. 
 This screening step may be skipped, if desired, by setting |Req_Index| 
 to a value of 100 or greater.

 The ``Forbidden Lines'' screening step is governed by variables 
 |Forbid_Index|, |F_Imin| and |DEL_2THETA|, which are changed using command 
 |SET| (see qualifiers |/F_INDEX|, |/Fmin| and |/Error|). 
 This step elminates from further consideration entries in the JCPDS-ICDD 
 database that have strong peaks where no intensity has been observed. The
 peak index selected by |Forbid_Index| is searched for peaks in the regions
 of the observed pattern where there are no peaks above |F_Imin|/% relative 
 intensity within |DEL_2THETA| and that have not been ``excluded''. 
 Any JCPDS-ICDD entry with a peak in one of these regions will be 
 eliminated from further consideration as a potential match. 
 This screening step may be skipped, if desired, by setting |Forbid_Index| 
 to a value of 100 or greater.

 The |REDUCE| command need not be used, but if it will be used it must 
 be specified before |MATCH| (or |REPORT|, if |MATCH| will also be omitted.)
 Command |SEARCH| performs the |REDUCE|, |MATCH| and |REPORT| steps 
 sequentially.
%CLD%Define verb REPORT
%CLD%
\Command REPORT\par
 Used to print a report on the matches from the previous search and/or
 creates a graph with the observed pattern and likely matching patterns.
 If the |MATCH| step was not performed first, the report may be run 
 using all entries in the current subfile (or those remaining after  
 removing entries in the |REDUCE| step). Note that the REPORT step 
 is usually rapid, but may take several minutes if more than a 
 thousand entries will be considered.

 For each entry, if two or more peaks match the observed pattern, 
 three or four figures of merit (FOM) are computed based on how 
 close the patterns match. The angle FOM reflects the descrepancies
 between matching observed and ICDD-JCPDS peak positions; the intensity
 FOM reflects the descrepancies between matching observed and ICDD-JCPDS 
 peak intensities; a full-pattern FOM is computed if a raw data file
 is input to this program; the overall FOM is computed from the 
 above FOM values.\par
\! The formulae used for FOM computation are:
\!$$\rm FOM\sb I = {1\over n} \sum {\vert I\sb {obs} - I\sb {JCPDS}\vert\over
\!	I\sb {obs} + I\sb {JCPDS}}$$
\!$$\rm FOM\sb D = \sqrt{\displaystyle 
\!	n \sum \Delta A^2 + \left(\sum \vert \Delta A \vert\right)^2
\!	\over n(n-1)}$$
\!$$\rm FOM\sb {FP} = {1\over \sum I\sb{JCPDS}}\sqrt{\displaystyle
\!   \sum{I\sb{JCPDS} - I\sb{raw} {\sum{I\sb{raw}} \over \sum{I\sb{JCPDS}}}
\!      }}$$ 
\!Where n is the number of matched peaks, m is the number of missed peaks,
\!$\Delta A$ is 100 times the closest JCPDS and observed peak positions
\!in degrees \twotheta\ at Cu \Kalpha1.
\!Where $\rm I\sb{JCPDS}$ and $\rm I\sb{obs}$ are the JCPDS and observed peak 
\!intensities, respectively and $\rm I\sb{raw}$ is the intensity of the raw,
\!background subtracted pattern at the specified position. 

 The formula used for the overall FOM depends on the setting for 
 |Calc_type| (see command |SET/FOM|).\par
\! \noindent |Calc_type = 0|
\!$$\rm FOM\sb {overall} = FOM\sb D FOM\sb I \left({n+m\over n}\right)^2
\!	\sqrt{n\sb {obs}\over n}$$\par
\! \noindent |Calc_type = 1|
\! \TAB {} (differences between observed and JCPDS peak intensities do not 
\!affect the overall FOM.)\par
\!$$\rm FOM\sb {overall} = FOM\sb I \left({n+m\over n}\right)^2
\!	\left({n\sb {obs}\over n}\right)$$\par
\! \noindent |Calc_type = 2|
\! \TAB {} (differences between matching observed and ICDD-JCPDS peak positions 
\!do not affect the overall FOM.)\par
\!$$\rm FOM\sb {overall} = FOM\sb D \left({n+m\over n}\right)^2
\!	\sqrt {n\sb {obs}\over n}$$\par
\! \noindent |Calc_type = 3|
\! \TAB {} 
\!$$\rm FOM\sb {overall} = FOM\sb {FP}.$$

  Following the computation of the FOM values and the optional sort
step, it is possible to display stick diagrams for the matching patterns
along with the observed peaks or the observed diffractogram for each pattern.
Patterns will be displayed by order of FOM, if sorted.

  The graphical display shows the observed peaks or diffractogram and 
an adjustable number of ``hits.'' At the bottom of the page, the excluded
regions of the pattern and the ``forbidden'' regions of the pattern are
shown as two lines. If the graphics device supports display of more than 
one color on the screen. Different colors will be used to show excluded 
peaks. Otherwise, different line styles will be used.
\Qualifiers
%CLD%	Qualifier PRINT, nonnegatable
\qual
/PRINT\par
 Causes the report to be printed rather than displayed first on the
 terminal.
%CLD%Define verb SEARCH
%CLD%
\Command SEARCH\par
 This command causes the program to invoke the search procedure.
 The search may be performed interactively or in batch mode.
 If batch mode is selected, a load file will be written, 
 a batch job will be submitted and the program will then exit.
 The |SEARCH| command performs the equivalent of the following
 three commands: |REDUCE|, |MATCH| and |REPORT| 
\Qualifiers
%CLD%	Qualifier BATCH, nonnegatable
\qual
/BATCH\par
 This option causes the search to be performed in batch mode.
%CLD%	Qualifier INTERACTIVE, nonnegatable
\qual
/INTERACTIVE\par
 This option causes the search to be performed interactively.
%CLD%	Qualifier PRINT, nonnegatable
\qual
/PRINT\par
 Causes the report to be printed rather than displayed first on the
 terminal. Ignored if used with the |/BATCH| option.
%CLD%
%CLD%Define verb SET
\Command SET\par
 This command is used to set parameters which govern the search.
 If SET is called with one or more qualifiers, the specified 
 parameters are updated and no prompts are generated. However, if
 SET is used with no qualifiers, prompts are generated which allow
 all parameters to be updated.

 When the search is performed (commands |REDUCE|, |MATCH| and |REPORT|), 
 peak positions from each appropriate entry in the ICDD-JCPDS database 
 are compared to positions from the list of peaks in the observed pattern. 
 Two peaks are considered to ``match'', if the \twotheta\ values 
 agree within |DEL_2THETA| (see |/ERROR|). 

 In the |MATCH| step, observed and database entries are compared 
 peak-by-peak. If no observed peak matches for a ICDD-JCPDS peak and 
 the relative intensity of that peak is above |DB_min_int| percent, 
 (see |/DB_IMIN|), the peak is counted as a ``miss.'' If more than 
 |DB_max_miss| ICDD-JCPDS peaks are not ``missed''(see |/MAXDBMISS|), 
 the entry will be rejected. 
 Also in the |MATCH| step, the number of peaks in the observed pattern 
 which have been matched to ICDD-JCPDS are also counted. If fewer than 
 |OBS_min_lines| percent of the total observed peaks above |OBS_min_int| 
 percent relative intensity are matched, the entry is rejected. 
 Note that an observed peak may be matched by several ICDD-JCPDS lines, 
 and a ICDD-JCPDS line can be matched by several observed peaks.

 The speed of the search is improved through three optional steps.
 The first is by restricting the search to a ICDD-JCPDS or user subfile 
 created in program LOGIC (see command |STARTFILE|). The other two 
 methods utilize the strong peak indices to eliminate entries quickly 
 which have strong peaks where no intensity is observed (see |/F_INDEX| 
 and |/Fmin|, below) and/or to restrict the search to entries having at 
 least one strong line matching the an observed line in the pattern 
 (see |/R_INDEX| and |/Rmin|, below). The strong peak choices are utilized 
 in the |REDUCE| step, thus these parameters are ignored unless either 
 command |REDUCE| or |SEARCH| is used.
\Qualifiers
%CLD%	Qualifier ERROR,value(required),nonnegatable
\qual
/Error=DEL_2THETA\par
   |DEL_2THETA| defines the allowed discrepancy between peak positions 
   in the observed pattern and those in the database used in the 
   |MATCH| and |REPORT| steps.
   These steps match the peak positions using peak positions transformed 
   to angles for Cu \Kalpha1\ radiation. Thus, |DEL_2THETA| defines a
   discrepancy in units of degrees \twotheta\ for Cu \Kalpha1\ radiation, 
   regardless of the wavelength mode (see command |WAVELENGTH|) used for 
   input of the peak positions.
 
   |DEL_2THETA| will typically be in the range 0.05 to 0.20 for most 
   searches. For materials where the lattice dimensions may vary (i.e. 
   solid solutions), or where either the observed peaks or the database 
   are presumed inaccurate, larger values may be needed.
%CLD%	Qualifier R_INDEX, value(type=$number,required),nonnegatable
%CLD%	Qualifier Rmin, value(type=$number,required),nonnegatable
\qual
/R_INDEX=Req_Index\<
/Rmin=R_Imin\par
 |Req_Index| and |R_Imin| determine how the ``Required Lines'' screening
 step in the |REDUCE| command is performed. In this step, entries from the 
 the starting subfile (see command |STARTFILE|) are dropped from 
 consideration unless one of the observed peaks matches a peak from 
 a peak index.
 This screening step may be skipped, if desired, by setting |Req_Index| 
 to a value of 100 or greater.

 Each non-excluded peak in the observed pattern with intensity above 
 |R_Imin|\% of the strongest non-excluded observed peak will be checked 
 in this step to see if matches within |DEL_2THETA| of a peak in the 
 peak index selected by |Req_Index|. Thus, this step will reject from 
 further consideration as a potential match patterns that do not have at 
 least one observed peak matching some peak in the JCPDS-ICDD database.

 The allowed values for |R_Imin| are between 0 and 99. The allowed values 
 for |Req_Index| are between -1 and 100 and have the following meaning:
\TAB	|100| Skip the ``Required Line'' step.
\TAB	|-1|  Use the ``Three Strongest'' Peak Index file.
\TAB	|n|   Use the ``|n|\% and Above'' Peak Index file (n = 0 to 99).
		   Note that if the requested index file is not available, 
		   the next smallest file (at 10\% increments) will be used.\par

 |R_Imin| will typically be a fairly small number, 5-10\%. For 
 patterns with many peaks, where the |REDUCE| step does not eliminate 
 many entries from consideration, it may be desirable to raise |R_Imin|
 up to the range of 25\% or higher.

 |Req_Index| will typically be 70\% or -1 (``Three Strongest'') so that 
 only patterns with reasonably strong matching peaks will be located. 
 If there is fairly strong preferred orientation or other errors which 
 increase the likelyhood that strong peaks will not match between patterns,
 it may be necessary to use a lower value, 30\% or 0\%, for |Req_Index|.

 Likewise, when the range of excluded regions in the search becomes large,
 the probability that the excluded regions will contain all of the strong 
 peaks in the desired matching phase and thus the pattern will not be found.
 The likely situations where this may occur is when data were collected only
 over a small region of \twotheta or when looking for a minor phase, where
 a large number of peaks in the pattern have already been identified.
 In these circumstances, if finding appropriate matches becomes difficult,
 lower |Req_Index| or even turn off this step (by setting |Req_Index| to 100).

%CLD%	Qualifier F_INDEX, value(type=$number,required), nonnegatable
%CLD%	Qualifier Fmin, value(type=$number,required), nonnegatable
%CLD%	Qualifier FWidth, value(type=$number,required), nonnegatable
\qual
/F_INDEX=Forbid_Index\<
/FWidth=FWHM\<
/Fmin=F_Imin\par
 |Forbid_Index| and |F_Imin| determine how the ``Forbidden Lines'' screening
 step in the |REDUCE| command is performed. In this step, entries from the 
 the starting subfile (see command |STARTFILE|) are dropped from 
 consideration if there is a peak in a peak index that falls in an area
 of the pattern where no peaks greater than |F_Imin|\% are observed.

 In this step, the pattern is broken up into approximately 260 regions.
 Each region is checked to ensure that there are no peaks greater than 
 |F_Imin|\% of the strongest non-excluded observed peak within |FWHM|
 degrees and that the region has not been marked as excluded. If there 
 are no peaks and no excluded regions, the peak index selected by 
 |Forbid_Index| is checked for peaks in this region. Any peak found 
 in the region will eliminate the entry from further consideration.

 The pattern is processed using using peak positions transformed 
 to angles for Cu \Kalpha1\ radiation. Thus, |FWHM| defines a width
 in units of degrees \twotheta\ for Cu \Kalpha1\ radiation, 
 regardless of the wavelength mode (see command |WAVELENGTH|) used for 
 input of the peak positions.

 The allowed values for |F_Imin| are between 0 and 99. The allowed values 
 for |Forbid_Index| are between -1 and 100 and have the following meaning:
\TAB	|100| Skip the ``Forbidden Line'' step.
\TAB	|-1|  Use the ``Three Strongest'' Peak Index file.
\TAB	|n|   Use the ``|n|\% and Above'' Peak Index file (n = 0 to 99).
		   Note that if the requested index file is not available, 
		   the next smallest file (at 10\% increments) will be used.

 |F_Imin| will usually be a fairly small number, 1-4\%, and
 |Forbid_Index| will typically be in the range of 30-50\%. This implies that
 a JCPDS-ICDD peak in the range of 30-50\% will be observed in the 
 experimental pattern at least at the 4\% range. This may not be true
 if the specimen has extreme preferred orientation or is composed of several
 phases where no phase constitutes a majority of the sample or if the
 JCPDS-ICDD pattern has preferred orientation. In these cases, where the 
 |REDUCE| step leaves no reasonable materials as potential ``hits'', one 
 should lower |F_Imin|, perhaps as low as 0\% and/or raise |Forbid_Index| 
 to 70-90\% or -1. In extreme cases, for example, where one want to find
 matches to JCPDS-ICDD patterns where stong peaks may be completely missing 
 from the observed pattern, it may be necessary to skip this step (by setting
 |Forbid_Index| to 100.) For materials where the |REDUCE| step does not eliminate 
 enough entries from consideration, it may be desirable to raise |F_Imin| up 
 to the range of 10-15\% and set |Forbid_Index| to 30\%.
%CLD%	Qualifier MAXDBMISS,value(type=$number,required), nonnegatable
%CLD%	Qualifier DB_IMIN,value(type=$number,required),nonnegatable
\qual
/MAXDBMISS=DB_max_miss\<
/DB_IMIN=DB_min_int\par
 In the |MATCH| step, the JCPDS-ICDD entries are compared one at at
 time to the observed peaks. The number of peaks in the JCPDS-ICDD
 pattern that must be matched for the entry to be given further 
 consideration is dictated by the values of |DB_max_miss| and
 |DB_min_int|. All JCPDS-ICDD entries that do not match this
 criteron are removed from the list of possible ``hits.''

 For a pattern to be considered a likely match for an entry one 
 expects most if not all of the strong peaks in the JCPDS-ICDD entry 
 to be observed. Weak peaks may not always be seen depending on the 
 relative amount of the phase and the quality of the sample and the 
 pattern. A pattern will be discarded if more than |DB_max_miss| peaks 
 above |DB_min_int|\% relative intensity are not within |DEL_2THETA| 
 of an observed peak. Thus |DB_min_int|\% determines the threshold 
 for what is considered to be an observable intensity level. If the 
 material is believed to be single phase, |DB_min_int| should be a 
 fairly larger number, 10-20\%. But for identifying phases in a material
 with many phases, it may be necessary to raise |DB_min_int| as high as
 50\%. Under circumstances, the observed peaks should match all of the
 JCPDS-ICDD peaks and |DB_max_miss| should be 0 or at most 1. However, 
 any of the following conditions can lead to strong JCPDS-ICDD peaks
 to be missing from an observed pattern: severe preferred orientation
 in the observed (or database!) pattern; an impurity in the database
 pattern (rare but sometimes occurs); peak shifts due to instrumental 
 errors. 

 In general it makes sense to start with small values for both
 |DB_max_miss| and |DB_min_int|. If no appropriate ``hits''
 are found. It is advisible to raise first |DB_min_int| and then 
 |DB_max_miss|. Both values must be integers.
%CLD%	Qualifier MATCHOBS,value(type=$number,required),nonnegatable
%CLD%	Qualifier OBS_IMIN,value(type=$number,required),nonnegatable
\qual
/MATCHOBS=OBS_min_lines\<
/OBS_IMIN=OBS_min_int\par
 In the |MATCH| step, the JCPDS-ICDD entries are compared one at at
 time to the observed peaks and patterns that do not match the observed
 pattern are removed from further consideration. Entries are removed
 unless at least |OBS_min_lines| percent of the lines above |OBS_min_int|
 percent relative intensity are matched.

 In general it makes sense to start with values in the range of 50\% for 
 |OBS_min_lines| and 25\% for |OBS_min_int|. Meaning that a database entry
 must match at least half of the observed lines above 25\% relative 
 intensity. If the |MATCH| step fails to find any likely ``hits,'' it is
 wise to lower |OBS_min_lines| and/or raise |OBS_min_int| so that fewer lines
 need to be matched for a hit to be obtained. Lower |OBS_min_lines| first, 
 if a multiphase mixture is suspected. 

 If too many ``hits'' are found to review conveniently, it is 
 wise to increase |OBS_min_lines| and/or lower |OBS_min_int|. If a 
 multiphase mixture is suspected, lower |OBS_min_lines| first.
 %CLD%	Qualifier MAXCARDS,value(type=$number,required),nonnegatable
\qual
/MAXCARDS=MAX_hits\par
 The |MATCH| step will be ended early if more than |MAX_hits| entries are 
 found in the search. This can be used to prevent ``run-away'' searches
 which turn up too many entries to comfortably review. When the search
 is performed interactively, the search can either be continued or
 abandoned if the |MAX_hits| threshold is reached.

 The default value for |MAX_hits| is 999. If this many entries are
 located, it is likely that the criteria for the |REDUCE| and |MATCH|
 are too broad and the run will need to be repeated. For very slow 
 computer systems or where CPU time is at a premium, it may be wise
 to lower this value. Under most conditions the value of |MAX_hits|
 is unimportant.
%CLD%	Qualifier SORT,value(type=$number)
\qual
/SORT=Num_Sort\<
/SORT\<
/NOSORT\par
 This controls sorting of entries by figure of merit (FOM) in the 
 |REPORT| (or |SEARCH|) command. If |Num_Sort| is positive, the step 
 will list the |Num_Sort| ICDD-JCPDS entries with the best FOM and a subfile 
 with these entries will be written. If |Num_Sort| is zero or |/SORT| 
 is specified without a number for |Num_Sort| the sort will be performed 
 but all ``hits'' from the |MATCH| (or |REDUCE| step, if |MATCH| is 
 skipped) will be listed in the report. Using a negative value for 
 |Num_Sort| or specifying |/NOSORT| prevents sorting, speeding the |REPORT|
 step. 
%CLD%	Qualifier FOM,value(type=$number,required),nonnegatable
\qual
/FOM=Calc_type\par
 Determines how the overall figure of merit (FOM) is computed in the
 Report command. 

 If |Calc_type| is 1, differences between matching observed and 
 ICDD-JCPDS peak positions do not affect the overall FOM. 

 If |Calc_type| is 2, differences between observed and ICDD-JCPDS 
 peak intensities do not affect the overall FOM. 

 If |Calc_type| is 3, the full-pattern FOM formula is used for the 
 overall FOM. This option is appropriate only if a raw data file has been 
 input to the program and also requires that the background be subtracted
 from the data before it is read into the program.
\!\par See the previous section on the |REPORT| command for more details
\!on the computation of figures of merit.
%CLD%	Qualifier NAME,value(type=$file,required),nonnegatable
\qual
/NAME=search_name\par
 This qualifier is used to to define the names that will be used 
 for files that will be created during the run. While this name may
 be as long as 40 or more characters (VMS allows very long filenames),
 for convenience, the name will typically be 4 to 10 characters. The
 search name is subject to the normal VMS conventions governing 
 file names: all letters, numbers and some symbols (notably _ and -)
 are allowed, but spaces and most other symbols are not allowed. 
 
 If files are to be written in a directory or disk other than the
 current default, device specifications may be included in the 
 |search_name|. File extensions are allowed, but their use is 
 not recommended. If supplied, the file extension will be used for 
 naming the ``load file'' only.\par
%HLP%  
%HLP%  See help on File_names for more information on file naming. 
%HLP%1 File_names
 The following files are created by program SEARCH:
 
\TAB {} The ``load file'' is used for temporary storage of the current 
	SEARCH settings. This file may be reread by a later run of
	SEARCH and will also be used if SEARCH is run as a batch job.
	The file name is taken from the search name. File extension
 	|.SEA_IN| is used, if none is specified in the search name.

\TAB {} The ``starting subfile'' is created if the |STARTFILE| command 
	is used to narrow down the number of entries to be considered  
	during the search by creating a user supplied subfile. 
	The file is written by program LOGIC. The subfile to be written 
	will be named using the current search name, however, the 
	device/directory will be changed to the scratch directory, 
	|PS_TMP|, the string ``|_SEARCH|'' will be appended to the 
	search name, and the file extension will be set as |.USRPDF|.

\TAB {} The ``search output file''is a user subfile with the 
	matches (hits) from the search. This file may be read by 
	program LOGIC. The file will be named directly from the 
	search name; the file extension will be |.USRPDF|.
	
\TAB {} The ``top hits output file''is a user subfile with 
	the best ranked matches from the |SEARCH| or |REPORT|
	command if sorting has been requested. The file is the
	same as ``search output file'' except |_TOPxx| is appended
	to the search name (|xx| is the number of sorted entries).
%CLD%
%CLD%Define verb SHOW
\Command SHOW\par
 This command is used to display the parameters which govern the 
 search, as established by command |SET|.
%CLD%
%CLD%Define verb STARTFILE
\Command STARTFILE\par
 This command is used to select the entries in the ICDD-JCPDS database that
 will be considered when performing the search. The entire database
 may be searched or the search may be restricted to a smaller section 
 (subfile). A number of standard subfiles have been prepared by the
 ICDD-JCPDS; alternately program LOGIC may be used to prepare a 
 user-defined subfile. 

 Use of a subfile (any option other than |/SUBPDF=FULL|) reduces
 the number of entries that need be examined, which can greatly speed the 
 search. For example, if it can be assumed that no elements heavier 
 than iodine are present in the unknown, program LOGIC can be used to 
 eliminate approximately one-third of the entries in the database from 
 consideration. (This is performed using command
 \TAB {} 	|CULL/E_SP=(Xe,Lr)/OR|\par
 within program LOGIC.)
 
 Program LOGIC is most commonly used to specify chemistry constraints.
 To call program LOGIC from within SEARCH, enter command |STARTFILE/LOGIC|.
 To read a subfile previously prepared by LOGIC and stored in a 
 user-defined file, use command |STARTFILE/USERFILE=file_name| to select 
 that file. The user-defined subfiles created at the end of SEARCH run 
 may also be used as a starting point.

 Only one of the following three options may be specified. 
\Qualifiers
\qual
/LOGIC\par
%CLD%	Qualifier LOGIC, nonnegatable
Specify this qualifier to call program LOGIC to create a new 
user-supplied subfile to be used in the search. When the LOGIC 
program is exited, a subfile will automatically be written and 
program SEARCH will be resumed. 
The subfile to be written will be named using the current search 
name, however, the device/directory will be changed to the scratch 
directory, |PS_TMP|, the string ``|_SEARCH|'' will be appended to 
the search name, and the file extension will be set as |.USRPDF|. 
\qual
/USERPDF=file_name\par
%CLD%	Qualifier USERPDF, value(type=$file,required), nonnegatable
Use a previously written user-supplied subfile with name |file_name|. 
The default file extension is |.USRPDF|.
\qual
/SUBPDF=sub_file\par
%CLD%	Qualifier SUBPDF, value(required, type=sub_pdf), nonnegatable
 Use this option to start from one of the standard subfiles, such as the
 the inorganic subfile.

 The available subfiles are: 
\TAB   FULL         all entries in the database
\TAB   NULL         null table (a table without any entries)
\TAB   INORGANICS   Inorganic materials
\TAB   ORGANICS     Materials with a C-H bond
\TAB   COMMON       commonly found materials or phases
\TAB   MINERALS     Minerals, natural and synthetic
\TAB   METALS       metals, alloys and related materials
\TAB   NIST         patterns recorded by NIST (NBS)
\TAB   FORENSIC     materials of forensic interest
\TAB   ZEOLITES     zeolites and molecular sieves
\TAB   DELETED      superceeded but not removed patterns (if any)
\TAB   LOCAL        locally defined patterns (if any)
\TAB   SUPERCON     superconductors and related materials
\TAB   EXPLOSIVES   explosives and related materials
\TAB   EDUCATION    educationally relevant materials
\TAB   CEMENT       materials related to cement production
\TAB   CORROSION    corrosion products and related materials
 Only one subfile may be specified. To search two subfiles, (for 
 example the MINERALS and METALS subfiles) use program LOGIC 
 (see |/LOGIC|) to |OR| (|ADD|) together these two subfiles.\par
  Note that the |sub_file| name may be abbreviated by only including
  the initial letters as long as the name is uniquely specified. Also
  note that ``DELETED'' patterns are not used unless the |DELETED/INCLUDE|
  command is used to force inclusion of these patterns.
%CLD%	Disallow any2(SUBPDF,LOGIC,USERPDF)
%CLD%Define type SUB_PDF
%CLD%	keyword FULL,       keyword NULL
%CLD%	keyword DELETED,    keyword LOCAL
%CLD%	keyword INORGANICS, keyword ORGANICS,  keyword COMMON
%CLD%	keyword MINERALS,   keyword METALS,    keyword NIST  
%CLD%	keyword FORENSICS,  keyword ZEOLITES,  keyword SUPERCON
%CLD%	keyword EXPLOSIVES, keyword EDUCATION, keyword CEMENT
%CLD%	keyword CORROSION
%CLD%
%CLD%Define verb TITLE
%CLD% 	parameter P1, label=new_title
%CLD% 		value (type = $REST_OF_LINE)
\Command TITLE\par
 Used to change the ``search title.'' The only purpose of the search 
 title is to provide a mechanism for saving comments and other 
 information from a search in the ``load file.''

 The format of this command is:\par
|      TITLE title|\par
 The title can be specified on the command line or will be prompted.
 If the title is put on the command line, any lower case letters used 
 in the title will be converted to uppercase.
\Examples
\exam
|TITLE This is the new title for the search|\par
			Note that the title will be converted to all 
			capital letters.
\exam
|TITLE|\par
			The user will be prompted to specify a title.
%CLD%
%CLD%Define verb WAVELENGTH
%CLD% 	parameter P1, label=wave_length
%CLD%	Qualifier TARGET, value(type=TARGET_TYPE), syntax=NO_PARAMS
%CLD%	Qualifier WTYPE, nonnegatable,value(type=$number)
%CLD%	Define type TARGET_TYPE
%CLD%		keyword CU, keyword MO, keyword NI, keyword CO
%CLD%		keyword FE, keyword CR, keyword AG, keyword SY, keyword NU
%CLD% 	Define syntax NO_PARAMS, noparameters
\Command WAVELENGTH\par
 Peaks positions may be input or output as d-spacings (in \AA) or 
 as \twotheta\ (Bragg) angles corresponding to a given x-ray or neutron 
 wavelength. This command is used to select between d-spacings 
 and angles and to select a wavelength for the latter option.

 The current mode of the program is displayed in the header line at the
 top of the computer screen. The default when the program is started 
 is determined by logical name |PS_WAVELENGTH|. If this logical name
 is not defined, the default is to operate in d-space mode. When
 the |WAVELENGTH| command is used logical name |PS_WAVELENGTH|
 is redefined and this becomes the new default mode.
\Parameter
\parm
wave_length\par
  A single wavelength value may be specified directly, where |wave_length| 
  is the x-ray or neutron wavelength in \AA. (The |target_type| will be 
  assumed to be |SY| for synchrotron radiation).

  If |0.0| is used for the |wave_length|, the program will enter d-space 
  mode (equivalent to specifying (|WAVELENGTH/NOTARGET|).

  If |wave_length| is used, |/TARGET| and |/WTYPE| should not. 
\Qualifiers
\qual 
/TARGET=target_type\<
/TARGET\<
/NOTARGET\par
 Specifies an x-ray target for conventional x-ray sources. 
 The choices for targets are:
	 |Cu|, |Mo|, |Ni|, |Co|, |Fe|, |Cr|, |Ag|, |NU|, or |SY|. 
 Specifying |/TARGET| without a |target_type| is equivalent to 
 |/TARGET=CU|. (Capitalization of the target type is ignored.)\par
 If |NU| or |SY| (for neutron or synchrotron radiation) is used, 
 the program prompts for a wavelength. 

 For input/output using d-spacings specify |/NOTARGET|\par

 The |/TARGET| option cannot be specified with a |wave_length| value.\par
\qual
/WTYPE=wave_type\par
   |wave_type| may be either 1, 2 or 3 which determines 
   the exact value used for the wavelength specified with |/TARGET|.
   The choices are:
\TAB	1 to use \Kalpha1\ radiation 
\TAB	2 to use \Kalpha2\ radiation 
\TAB	3 to use the intensity weighted average of \Kalpha1\ and \Kalpha2\ 
	  radiation.\par
   Specifying |/WTYPE| without a value for |wave_type| is equivalent 
   to specifying |/WTYPE=1|.\par
   This qualifier is ignored if the radiation source has a single 
   wavelength, (e.g. |/TARGET=NU| or |/TARGET=SY|) or a 
   |wave_length| is specified.
\Examples
\exam
|WAVELENGTH/TARGET=CU/WTYPE=3|\par
	The wavelength will be set to the average of Cu \Kalpha1\ and 
	\Kalpha2.
\exam
|WAVELENGTH/TARGET|\par
	The wavelength will be set to Cu \Kalpha1.
\exam
|WAVE/NOTAR|\par
	Peaks positions, etc. will be displayed as d-spaces.
\exam
|WAVE 0.0|\par
	Peaks positions, etc. will be displayed as d-spaces.
\exam
|WAVE 2.5401|\par
	The wavelength will be set to 2.5401\AA.
\exam
|WAVE|\par
	The user will be prompted to choose a wavelength or two use
	d-spacings. 
\exam
|WAVELENGTH/TARGET=NU/WTYPE=3|\par
	The user will be prompted to enter a wavelength; the |/WTYPE=3|
	qualifier will be ignored.

