README.cif2cif Information for cif2cif 0.0.8, 2 April 1998 _________________________________________________________________ Before using this software, please read the NOTICE and please read the IUCr Policy on the Use of the Crystallographic Information File (CIF) _________________________________________________________________ \ | / \ | / \|/ \|/ -- -->>>>>>-- -- c i f 2 c i f ...... CIF COPY PROGRAM /|\ /|\ / | \ / | \ Version 0.0.8 - beta 2 April 1998 cif2cif is a fortran program using CIFtbx2 to copy a CIF on standard ------- input to an equivalent CIF on standard output, while checking data names against dictionaries and reformating numbers with esd's to conform to the rule of 19. A request list may be specified cif2cif by Herbert J. Bernstein (yaya@bernstein-plus-sons.com) Bernstein + Sons 5 Brewster Lane Bellport, NY 11713, U.S.A. based on suggestions by Sydney R. Hall (syd@crystal.uwa.edu.au) Crystallography Centre University of Western Australia Nedlands 6009, AUSTRALIA with the request list handling suggested by the program QUASAR by Sydney R. Hall and Rolf Sievers (unc411@dbnrhrz1.bitnet) Institut fuer Anorganische-Chemisches der Universitaet Gerhard-Domagk-Str. Bonn, GERMANY cif2cif reads the input CIF from the standard input device (normally device 5). An optional STAR data name dictionary (in DDL ) is opened. A reformatted copy of the input CIF is written to standard output (device 6). Messages are output to the standard error device (normally device 0). Note that the PARAMETER 'MAXBUF' should contain the maximum number of char- acters contained on a single text line. The default value is 200. In a unix-like environment, the program is run as: cif2cif [-i input_cif] [-o output_cif] [-d dictionary] \ [-f command_file] [-e esdlim_] [-a aliaso_] [-p prefix]\ [-t tabl_] [-q request_list] \ [[[input_cif] [[output_cif] [[dictionary] [request_list]]]] where: input_cif defaults to $CIF2CIF_INPUT_CIF or stdin output_cif defaults to $CIF2CIF_OUTPUT_CIF or stdout dictionary defaults to $CIF2CIF_CHECK_DICTIONARY (multiple dictionaries may be specified) request_list defaults to $CIF2CIF_REQUEST_LIST input_cif of "-" is stdin, output_cif of "-" is stdout request_list of "-" is stdin -e has integer values (e.g. 9, 19(default) or 29) -a has values of t or 1 or y vs. f or 0 or n -p has string values in which "_" is replaced by blank -t has values of t or 1 or y vs. f or 0 or n (default n) 1. INSTALLATION Here is the recommended procedure for implementing and testing this version of cif2cif. 1.0. Before you try to install this version of cif2cif *** ========================================================== *** *** ========================================================== *** *** ==>>> You must have ciftbx version 2.6 or greater <<<== *** *** ==>>> installed in a directory named ciftbx.src. <<<== *** *** ==>>> The scripts mkdecompln and rmdecompln, which <<<== *** *** ==>>> come with ciftbx, must be installed in the <<<== *** *** ==>>> top level directory and executable. <<<== *** *** ==>>> To test cif2cif, you must have a compressed <<<== *** *** ==>>> copy of the dictionary cif_mm.dic in a <<<== *** *** ==>>> directory named dictionaries. <<<== *** *** ========================================================== *** *** ========================================================== *** The directory structure within which you will work is top level directory ------------------- | | ------------------------------ | | | dictionaries ciftbx.src cif2cif.src ------------ ---------- ----------- You may have acquired this package in one of several forms. The most likely are as a "C-shell Archive," a "Shell Archive", or as separate files. The idea is to get to separate files, all in the same directory, named cif2cif.src, parallel to the directory ciftbx.src, but let's start with the possibility that you got the package as one big file, i.e. in one of the archive file formats. Place the archive in the top level directory. *** ========================================================== *** *** ========================================================== *** *** ==>>> The files in this kit will unpack into a <<<== *** *** ==>>> directory named cif2cif.src. It is a good idea<<<== *** *** ==>>> to save the current contents of cif2cif.src <<<== *** *** ==>>> and then to make the directory empty <<<== *** *** ========================================================== *** *** ========================================================== *** If you are on a machine which does not provide a unix-like shell, you will need to take apart the archive by hand using a text editor. We'll get to that in a moment. 1.1. ON A UNIX MACHINE If you have the shell archive on a unix machine, follow the instructions at the front of the archive, i.e. save the uncompressed archive file as "file", then, if the archive is a "Shell Archive" execute "sh file". If the archive is a "C-Shell Archive" execute "csh file". 1.2. IF YOU DON'T HAVE UNIX If sh or csh are not available, then it is best to start with the "C-Shell Archive" and do the steps that follow. If you must use the "Shell Archive" you should be aware that the lines you want to extract have been prefixed with "X", while most of the lines you want to discard have not. For a "C-Shell Archive" such prefixes are rare and the file is easier to read. Assume you have a "C-Shell Archive". Use your editor to separate the different parts of the file into individual files in your workspace. Each part starts with a lot of unixisms, then several blank lines and then two lines which identify the file, and most importantly, contain the text "CUT_HERE_CUT_HERE_CUT_HERE" You can look at the line before and the line after to see if you are at the head or tail of a file. Use your editor to search for the "CUT_HERE" lines. Each part is carefully labeled and indicates the recommended filename for the separated file. On some machines these filenames may need to be altered to suit the OS or compiler. 1.3. MANIFEST The partitions are as follows: part filename description 1 cif2cif.src/README.cif2cif additional information on cif2cif 2 cif2cif.src/MANIFEST a list of files in the kit 3 cif2cif.src/Makefile a preliminary control file for make 4 cif2cif.src/4ins.cif example mmcif file used to test cif2cif 5 cif2cif.src/4ins.out example mmcif output from test of cif2cif 6 cif2cif.src/4ins.prt example mmcif list file from test of cif2cif 7 cif2cif.src/cif2cif.cmn cif2cif common block 8 cif2cif.src/cif2cif.f cif2cif fortran source 9 cif2cif.src/qtest.cif quasar mode test input cif 10 cif2cif.src/qtest.out quasar mode test output cif 11 cif2cif.src/qtest.req quasar mode test request file 12 cif2cif.src/qtest.prt example cif file used to test cif2cif 13 cif2cif.src/xtalt2.cif example cif file used to test cif2cif 14 cif2cif.src/xtalt2.out example cif output from test of cif2cif 15 cif2cif.src/xte29.out example cif output from test of cif2cif 16 cif2cif.src/xttne9.out example cif output from test of cif2cif 2. COMPILING AND EXECUTING Here are the recommended steps for a UNIX system. Vary this according to the requirements of your OS and compiler. You will simplest to work if you place the cif2cif files together in a common subdirectory named 'cif2cif.src'. Be very careful if you place them in a directory with other files, since some of the build and test instructions remove or overwrite existing files, especially with extensions such as '.o', '.lst', or '.diff'. On a UNIX system, most of what you need to do to build and test cif2cif is laid out in Makefile. *** Be sure to examine and edit this file appropriately before using it.*** But, once properly edited, all you should need to do is 'make clean' to remove old object files, 'make all' to build new version of 'cif2cif' and 'make tests' to test what you have built. For non-UNIX-like environments, you will have to provide replacements for iargc, getarg and getenv. The following are reasonable possibilities: integer function iargc(dummy) iargc=0 return end subroutine getarg(narg,string) integer narg character*(*) string string=char(0) return end subroutine getenv(evar,string) character*(*) evar,string string=char(0) if(evar.eq."CIF2CIF_INPUT_CIF") * string='INPCIF.CIF'//char(0) if(evar.eq."CIF2CIF_OUTPUT_CIF") * string='OUTCIF.CIF'//char(0) if(evar.eq."CIF2CIF_CHECK_DICTIONARY") * string='CIF_CORE.DIC'//char(0) return end This combination of substitute routines would "wire-in" cif2cif to read its input cif from a file named INPCIF.CIF, write its output cif to a file named OUTCIF.CIF, and check names against CIF_CORE.DIC FILES USED dictionary input input on device 2 Reformatted CIF output on device 6 ('stdout') Input CIF input on device 2, if a file, 5 if 'stdin' Message device output on device 0 ('stderr') Direct access in/out on device 3 TEST files Three test CIFs are provided. xtal2.cif is a test file borrowed from xtal_gx (file xtest2.cif at ftp://ftp.crystal.uwa.edu.au/free/test., provided by S. R. Hall. 4ins.cif is an mmCIF file created from the PDB entry 4INS by G.G. Dodson, E. J. Dodson, D. C. Hodgkin, N.W. Isaacs and M. Vijayan (1989) by the program pdb2cif (P.E. Bourne, F.C. Bernstein and H.J. Bernstein, 1996, see http://ndbserver.rutgers.edu/software). qtest.cif is the test cif from the quasar release by Hall and Sievers (1994). A modified version of the request list, qtest.req, is also included. xtalt2.cif provides good test cases for the conversion of esd's. The command cif2cif -t y < xtalt2.cif > xtalt2.new ensures that all esd's follow the rule of 19, while cif2cif -t y -e 29 < xtalt2.cif > xte29.new converts esd's to the rule of 29. The difference between the two rules is that for the rule of 19, all esd's lie between 2 and 19, so that an esd of (1) has to be converted to (10), while for the rule of 29, all esd's lie between 3 and 29, so that an esd of (2) also has to be converted, in this case to (20). The option "-t y" tidies the output to tab stops. One last test with this file is to use the command cif2cif -e 9 < xtalt2.cif > xttne9.new to copy the original cif spacing and to use the rule of 9 on esd's 4ins.cif has many comments, text fields and dense loops. The test in the Makefile tests handling of these items and adds the additional complication of processing a prefix ".._" with the command cif2cif -t y -p .._ < 4ins.cif > 4ins.new The output spacing is controlled by the program. The quasar mode may be tested by the command cif2cif -i qtest.cif -o qtest.new -q qtest.req CHANGES Version 0.0.8 (2 April 1998) added code to preserve the distinction between esds which are numerically identical but presented with varying numbers of trailing zeros. To enable this feature, the command line argument -e must be given a negative value large enough to span the desired range, e.g. "-e -19" to allow both .6870(10) and .687(1) to be handled. The variables esddig_ and pesddig_ introduced with ciftbx 2.6 are used. A bug in the preserving leading zeros of unlooped numeric values was also fixed. Version 0.0.7 (7 August 1997) added support for quasar-style request lists. In addition, a special form of request for "data_which_contains:" will find the data block which contains at least one of the following tags. Version 0.0.6 (12 May 1997) added support of negative values of esdlim_, indicating a range of esd's from 1 to -esdlim_. The practical use of this change is to use the command line parameter -e-9999 to copy most esds unchanged. The new ciftbx variables decp_, pdecp_, lzero_ and plzero_ are used internally to copy decimal points and leading zeros more faithfully. The 4ins example has been updated to use cif_mm.dic (0.9.01). The command-line option "-c catck" was added. The default is not to check categories. Version 0.0.5 (2 December 96) adds support for copying of global_ sections and corrects a typo in the error message issued when the output CIF cannot be opened. Version 0.0.4 (24 September 96) adapts to the 'ciftbx.cmn' and 'ciftbx.sys' reorganization in ciftbx 2.5.1. Version 0.0.3 (24 July 96) used ciftbx 2.5.0 to preserve tabs, fixed a case in which string quoted in the input cif may not have been quoted in the output cif, preserved more white space, and copied comments within loop headers. The lateral position of "loop_" is preserved. A bug in copying final comments which caused the a comment to be duplicated or some final comments to be lost was fixed. Version 0.0.2 (24 June 96) changed the default for -t to n instead of y, and used ciftbx 2.4.6 to increase the faithfulness of the copy. KNOWN PROBLEMS cif2cif does not copy white space exactly, and will reformat some data values. Always compare the original to the output. _________________________________________________________________ Updated 21 June 1998 yaya@bernstein-plus-sons.com NOTICE Creative endeavors depend on the lively exchange of ideas. There are laws and customs which establish rights and responsibilities for authors and the users of what authors create. This notice is not intended to prevent you from using the software and documents in this package, but to ensure that there are no misunderstandings about terms and conditions of such use. Please read the following notice carefully. If you do not understand any portion of this notice, please seek appropriate professional legal advice before making use of the software and documents included in this software package. In addition to whatever other steps you may be obliged to take to respect the intellectual property rights of the various parties involved, if you do make use of the software and documents in this package, please give credit where credit is due by citing this package, its authors and the URL or other source from which you obtained it, or equivalent primary references in the literature with the same authors. Some of the software and documents included within this software package are the intellectual property of various parties, and placement in this package does not in any way imply that any such rights have in any way been waived or diminished. With respect to any software or documents for which a copyright exists, ALL RIGHTS ARE RESERVED TO THE OWNERS OF SUCH COPYRIGHT. Even though the authors of the various documents and software found here have made a good faith effort to ensure that the documents are correct and that the software performs according to its documentation, and we would greatly appreciate hearing of any problems you may encounter, the programs and documents any files created by the programs are provided **AS IS** without any warrantee as to correctness, merchantability or fitness for any particular or general use. THE RESPONSIBILITY FOR ANY ADVERSE CONSEQUENCES FROM THE USE OF PROGRAMS OR DOCUMENTS OR ANY FILE OR FILES CREATED BY USE OF THE PROGRAMS OR DOCUMENTS LIES SOLELY WITH THE USERS OF THE PROGRAMS OR DOCUMENTS OR FILE OR FILES AND NOT WITH AUTHORS OF THE PROGRAMS OR DOCUMENTS. THE IUCR POLICY ON THE USE OF THE CRYSTALLOGRAPHIC INFORMATION FILE (CIF) [This is a text printout of the IUCr web page at http://http://www.iucr.ac.uk/iucr-top/ipr.html as of 26 January 1997. Please consult the IUCr for current policy] The Crystallographic Information File (Hall, Allen & Brown, 1991) is, as of January 1992, the recommended method for submitting publications to Acta Crystallographica Section C. The International Union of Crystallography holds the Copyright on the CIF, and has applied for Patents on the STAR File syntax which is the basis for the CIF format. It is a principal objective of the IUCr to promote the use of CIF for the exchange and storage of scientific data. The IUCr's sponsorship of the CIF development was motivated by its responsibility to its scientific journals, which set the standards in crystallographic publishing. The IUCr intends that CIFs will be used increasingly for electronic submission of manuscripts to these journals in future. The IUCr recognises that, if the CIF and the STAR File are to be adopted as a means for universal data exchange, the syntax of these files must be strictly and uniformly adhered to. Even small deviations from the syntax would ultimately cause the demise of the universal file concept. Through its Copyrights and Patents the IUCr has taken the steps needed to ensure strict conformance with this syntax. The IUCr policy on the use of the CIF and STAR File processes is as follows: _________________________________________________________________ * 1 CIFs and STAR Files may be generated, stored or transmitted, without permission or charge, provided their purpose is not specifically for profit or commercial gain, and provided that the published syntax is strictly adhered to. * 2 Computer software may be developed for use with CIFs or STAR files, without permission or charge, provided it is distributed in the public domain. This condition also applies to software for which a charge is made, provided that its primary function is for use with files that satisfy condition 1 and that it is distributed as a minor component of a larger package of software. * 3 Permission will be granted for the use of CIFs and STAR Files for specific commercial purposes (such as databases or network exchange processes), and for the distribution of commercial CIF/STAR software, on written application to the IUCr Executive Secretary, 2 Abbey Square, Chester CH1 2HU, England. The nature, terms and duration of the licences granted will be determined by the IUCr Executive and Finance Committees. _________________________________________________________________ In summary, the IUCr wishes to promote the use of the STAR File concepts as a standard universal data file. It will insist on strict compliance with the published syntax for all applications. To assist with this compliance, the IUCr provides public domain software for checking the logical integrity of a CIF, and for validating the data name definitions contained within a CIF. Detailed information on this software, and the associated dictionaries, may be obtained from the IUCr Office at 5 Abbey Square, Chester CH1 2HU, England. _________________________________________________________________ IUCr Webmaster