README.1st 	                                                       Robin Shirley
V3.01	                                                                   27Jul99

                Getting Started with the CRYSFIRE System

Installation

Since you're reading this, you have probably already downloaded and installed CRYSFIRE, but here are some suggestions, anyway.

1) Install it in its own directory.  C:\CRYSFIRE is suggested, but the name and path are not referred to anywhere in the software, so the particular choice is up to you.

2) However, if you want to run the system from elsewhere, such as from a data sub-directory (recommended to help keep things tidy), the CRYSFIRE directory must be on the MSDOS execution path.  Thus you will need either to edit AUTOEXEC.BAT and append the relevant directory to its PATH line, so that CRYSFIRE will be accessible automatically, or create a small preliminary script to do this before each CRYSFIRE session.

3) It is also a good idea to make sure you have sufficient DOS environment space free, since CRYSFIRE makes heavy use of DOS environment variables to communicate between its various components.  The default allocation may not be enough, and 1024 or 2048 is safer.  This can be provided by editing CONFIG.SYS and creating or modifying a SHELL line so as to specify the DOS environment size via its /e parameter (e.g. /e:1024 for 1024 bytes).

Thus, to provide 1024 bytes of environment space, insert the one of the following "shell=" lines in your CONFIG.SYS file, as appropriate:

	(Windows 95)	shell=C:\WINDOWS\COMMAND.COM C:\WINDOWS /e:1024 /p
	(DOS/Windows 3.1)	shell=C:\COMMAND.COM C:\DOS /e:1024 /p


CRYSFIRE Manual

Now is a good time to print yourself a copy of the 20-page CRYSFIRE manual, which is in the file CRYSFIRE.rtf.  If you don't feel like reading it yet, you'll still find it helpful to refer to.  The manual has been formatted for 10pt New Century Schoolbook on a postscript printer, but, if that isn't available, 10pt Times Roman should make a satisfactory substitute.

In particular, please make sure you've understood the terms on which the CRYSFIRE system is distributed and licensed for non-profit use (reproduced below).  They are not at all onerous but should be respected:  you are only licensed to use the system if you agree to them.


Copyright and Licensing

The CRYSFIRE system is freely available for non-profit use, but it is not public domain.  Copyright in all its parts is asserted by and reserved by the relevant authors.  Thus the CRYSFIRE system as a whole, including its scripts and associated programs (CRYS, QDAT, ITLOG, DVLOG, TRLOG, VRATIO, QHEAD, WF2CRYS and XF2CRYS) listed above , are all (c) R.Shirley, 1999.

Similarly, copyright is reserved by the various authors of the indexing programs (including myself).  The derivative copyright in my adaptations and extensions to the indexing programs is (c) R.Shirley, 1999, subject to the permission of the authors of the relevant base versions of the programs.

For commercial licences covering any material for which I hold the copyright, and for confidential consultancy, please contact me at R.Shirley@surrey.ac.uk.


Distribution and Tutorial

The CRYSFIRE suite is distributed free for non-profit use via the CCP14 web site (http://www.ccp14.ac.uk), where several detailed tutorials have been provided by Lachlan Cranswick.  It is also hoped to be included in subsequent versions of the CCP14 CD-ROM.  For commercial distribution, please contact me at R.Shirley@surrey.ac.uk.


Conditions of Use

For non-profit use, the following conditions apply:

1)	This software may only be distributed on the same terms that it was received, which is freely for non-profit use. Neither the original versions nor any derived or modified versions may be sold or incorporated in any commercially distributed system, without the express permission in writing of the relevant copyright holders.  These terms shall be binding on all subsequent recipients.

2) If use of the CRYSFIRE suite makes possible a published paper, then both the CRYSFIRE suite itself and any indexing programs that contributed materially to this result should be cited in the references section of the paper (some sources are given in the CRYSFIRE manual).


What is CRYSFIRE?

CRYSFIRE is a suite of inter-communicating scripts and programs that run on an ordinary PC under MSDOS or in a DOS window under Windows 3.x or 95, etc.  Collectively these form a sort of powder-indexing wizard, that leads non-specialist users very simply from an observed set of powder diffraction line positions to a probable unit cell.

Using the powder diffraction support program CRYS as a facilitator and front-end, any or all of eight major indexing programs can be called (including the classic trio of ITO, DICVOL and TREOR, but supplemented here by new versions of TAUP, KOHL, FJZN6, LZON and LOSHFZRF).  Their results are automatically consolidated into a cumulative summary of all the solutions found for that dataset, sorted into descending order of lines indexed and figure of merit achieved.  At the end of each run, the latest state of this summary is displayed.


General Conventions

1)	Help  If you want help on running any program or script within the CRYSFIRE system that would normally take a dataset name as its parameter, it is usually sufficient to just type its name (without any following parameter).  Brief usage notes and other help will then be displayed.

	For help with the WF2CRYS or XF2CRYS data converters, type their name followed by /? or /h as a parameter.

	For help with CRYS, start it up and type in the HE (HElp) command.

	Only the overall CRYSFIRE script does not provide specific online help, since it does not expect parameters and is essentially self-documenting as it proceeds.  For further help, see the section below on "Getting Started".

2) Program Abbreviations  Each indexing program ("target") has been given a 2-letter mnemonic code which is used consistently both to call it and to label all files associated with it.

	Thus, for example, the code for the DICVOL91 program is "DV", so DV is used to specify DICVOL91 as an indexing target within CRYS.  Scripts Q2DV and RUNDV are used to call it respectively from a QDAT translator datafile or a native-format datafile (however, you are not obliged to know this if you leave all such matters to CRYSFIRE).  Each of its associated files will also be labelled systematically with DV, so that DVO is its main output file, DVG is its logfile, etc.

	Thus if you encounter a file with DV in its extension, you can be pretty sure that it is associated with DICVOL91.  To find out exactly what it does, type Q2DV without any parameters, as described in (1) above, and you will be presented with a checklist of all the file types used with DICVOL91.

3) Dataset names  Just as its specific 2-letter code is used to label all files associated with a particular indexing program, so its 8-character dataset filename is used to label all files associated with work on a particular dataset.  Thus, if you had a dataset called XA10, then XA10.DVO would be the DICVOL91 main output for dataset XA10, XA10.SUM would be its cumulative summary file, etc.

Each dataset has some associated files that are not tied to any specific target program, such as its CRYS dataset (.CDT), cumulative logfile (.LOG) and cumulative sorted summary of results (.SUM, as already mentioned).  Thus it's helpful to keep the dataset name unchanged, so that its log and summary files will get updated automatically with each new development.

However, if it should become necessary to fork off variants of a particular dataset, then their summary files at least can be merged again with the MERGESUM script (again, just type MERGESUM without any parameters to learn more).


Getting Started

That's "getting started without reading the manual", though I recommend that actually you do read it at an early opportunity!  And also check out Lachlan Cranswick's online CRYSFIRE tutorial at the CCP14 website - see above for the relevant URL..

1) Create a CRYS dataset for your data, preferably in a separate data directory, not the main CRYSFIRE directory, to avoid confusion.  This can be done either by converting a peaks-list file from either WinFit or XFIT using the translators WF2CRYS or XF2CRYS provided, or by starting up CRYSFIRE and typing your data into CRYS, using the OB (input OBserved pattern) command.  CRYS offers various commands, of which only the first 2 letters are significant.  To learn more, type HE (for HElp), as discussed above.

2) If you haven't already done so, type CRYSFIRE to start up the system.  You will find yourself within CRYS.  If your dataset is not already loaded, load it now using the LO (LOad) command.

3) Now issue the SA (SAve) command, specifying Q (for QDAT) as the chosen format.

4) Next, specify an appropriate indexing target.  If this is your first run, I suggest IT (for ITO12) as a suitable choice.  It will run very fast (a few seconds on a Pentium 200) and may well yield a good result straight off, if your data are well measured and calibrated.

When asked, I suggest that you accept a run with all-default values, and press ENTER to accept the existing dataset name.  Type in a suitable title line for the dataset when asked, if one has not been provided already (in which case you could just press ENTER)..

5) When you are back at the CRYS command-prompt, type QU (i.e. QUit) to leave CRYS, and then ENTER to proceed with the rest of the run.

6) The indexing run will then proceed automatically, too fast for the eye to follow in the case of ITO12, and within a couple of seconds you will be looking at ITO's short output file in an editor program of your choice (by default, MSDOS EDIT).  Page down through the output file, (or, if feeling impatient, press Cntrl-End to shortcut through to the end).  If you are in luck, a promising solution will head the list of "most probable solutions".

7) Press Alt-F then X to exit.  You will then be presented with the summary of all results so far for this dataset, which of course will only contain those from ITO12, at one line per solution.  The table is too wide to see everything without scrolling to the right, but the most important information should already be visible, to the left of each line.

	Look for a solution with I20=20, a high figure of merit in the "Merit" column (over 25 would be nice) and a relatively low cell volume.  Check out the "V/V1" column, which compares the volume of each proposed cell with that for the solution at the top of the list.  Derivative versions of the same solution will either show this ratio as 1.00 or as a simple multiple (or sub-multiple).

8) Now try again from step 2 above, this time trying another indexing program as target, for example TR for TREOR90 or TA for TAUP.  Note that it is possible to save datafiles for several different targets before quitting from CRYS.  If you do that, only the last one saved will run automatically, and you will need to type the appropriate Q2xx script names to launch the others afterwards (e.g. Q2TP to launch TAUP, etc).

9) Suppose that you chose TR for TREOR90.  Within a minute or so you will probably be looking, as before, at its short output file, and, on typing Alt-F, X, seeing the updated summary.  This will now show the solutions from both the ITO12 and TREOR90 runs, sorted together into descending order of likelihood, with recalculated V/V1 ratios, etc.

10) From this point it's basically up to you.  You can go on to assemble results from various indexing programs, which hopefully will be in good general agreement, so that a clear picture starts to emerge.  If it doesn't, the reason will very probably lie with your data.

	Perhaps it wasn't really a single solid phase - check out the possibility that it contains a number of impurity lines, or is a mixture.

	Alternatively, perhaps its calibration is actually a bit off, so that you have an unexpectedly large 2Theta zero error - in that case consider using CRYS' self-calibration option (via the SC command).

	Even if everything went well, you should still think carefully about the proposed cell before accepting it as the last word on the matter.  Does it make good sense chemically and crystallographically?  For example, is the volume reasonable?  If the material is molecular, can the molecules actually to fit in?  Does it lead to a sensible multiple of the likely formula-volume, and agree with any available density information?  Does it suggest a space group, and, if so, is it one of the commonly occurring ones?


But if all this fails...

Finally, if your sample was pure and your data really were measured carefully, but you still haven't succeeded in coming up with a good solution, then I'm willing to take a look at your problem (depending, of course, on my workload).  Although CRYSFIRE has made indexing more accessible, some experience and cunning is sometimes still useful.  Assuming that you are a student or academic, or other non-profit user, the only reward I would ask is that, if I'm able to find a cell that in due course makes possible a published paper, then I should be included as one of its authors.

Good luck.	                                                      Robin Shirley
		                                                      27 July 1999

