README.txt Robin Shirley V3.1 7 June 2000 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 full 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, in which form it just fits into 20 pages, 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 particularly onerous and 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 overall CRYSFIRE system and user interfaces, including its scripts and its associated programs (CRYS, QDAT, ITLOG, DVLOG, TRLOG, VRATIO, QHEAD, WF2CRYS and XF2CRYS) as listed above (but excluding indexing programs contributed by other authors) are (c) R.Shirley, 2000. Similarly, copyright is reserved by the various authors of the indexing programs (including myself, where applicable). Derivative copyright in the adaptations and extensions to the indexing programs made to support the user interfaces within CRYSFIRE is (c) R.Shirley, 2000, subject to the rights of the authors of the relevant base versions of the programs. Licensing fees for commercial use of CRYSFIRE cover my user interfaces to those indexing programs, and expressly exclude charges for any contributed code. For commercial licences covering use of the user interfaces and adaptations in the CRYSFIRE system 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 detailed tutorials have been provided by Lachlan Cranswick. It is also included in the CCP14 Xtal Nexus 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 powder-indexing wizard (in the Microsoft sense), aimed at leading non-specialist users relatively painlessly 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 overall CRYSFIRE script or with the WF2CRYS or XF2CRYS data converters, type their name followed by /? or /h as a parameter. For help with CRYS, start up CRYSFIRE and, when the CRYS command prompt appears, type in the HE (HElp) command. 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 (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 whenever you encounter a file within CRYSFIRE, which has DV in its extension, it will be associated with DICVOL91. To discover what it does, type Q2DV without any parameters, as described in (1) above, and you will be shown a checklist of all the file types used with DICVOL91. 3) Dataset names Just as a specific 2-letter code is used to label all files associated with a particular indexing program, so an 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, and 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 make 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 (without reading the manual) However, 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 rather than the main CRYSFIRE directory, to avoid confusion. This can be done either by converting a peaks-list file from WinFit or XFIT using the translators WF2CRYS or XF2CRYS provided, or by running 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 then 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 good starting point. 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. Data quality is crucial for indexing. 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 can 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 go directly to its 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 is on the left of each line and will already be visible on the screen. 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). CRYSFIRE simply shows you what the indexing programs have found, and leaves issues such as the best choice of cell to you (and CHEKCELL - see below) 8) Now try again from step 2 above, this time trying another indexing program as target, for example TR for TREOR90 or KL for KOHL. 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. Q2TR to launch TREOR90, Q2KL to launch KOHL, 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. These solutions will not necessarily be in their simplest or most symmetrical settings, and different indexing programs may have used different settings for the same solution (which will thus have related or identical V/V1 ratios). Consider using the Laugier & Bochu CHEKCELL program to clarify such issues and to assign probable space groups - this is also available from the CCP14 website. 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 reasons 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 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). Assuming that you are a student or academic, or other non-profit user, the only reward I would ask is that, if I am able to find a cell that in due course makes possible a published paper, then I will be listed as one of its authors. Good luck. Robin Shirley 7 June 2000