CIFtbx, Cyclops, cif2cif, cif2xml, cif2pdb README FIRST Information

ALTERNATIVELY YOU MAY REDISTRIBUTE THE CBFLIB API UNDER THE TERMS OF THE LGPL.

Before using this software, please read the

and please read the IUCr

on the Use of the Crystallographic Information File (CIF)

Compiled binaries for some architectures (ix86 Linux, Sun Sparc, SGI) are available from the
Accessible Retired Computers in Biology (ARCiB) project at http://arcib.dowling.edu

CIFtbx is a tool box of Fortran routines for manipulating CIF data. CYCLOPS2, cif2cif, cif2xml and cif2pdb are open source Fortran programs based on CIFtbx. CYCLOPS2 checks STAR data names against data name dictionaries. cif2cif copies a CIF to a CIF 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. cif2xml is a variant of cif2cif which produces XML output. cif2pdb converts mmCIF files to a PDB or WPDB .

In order to ensure continuing availability of source code and documentation most programs and documents on this site are subject to copyright. This does not prevent you from using the programs, from making copies and changes, but prevents the creation of "closed source" versions out of the open source versions. See NOTICE.

Science is best served when the tools we use are fully understood by those who wield those tools and by those who make used of results obtained with those tools. When a scientific tool exists as software, access to source code is an important element in achieving full understanding of that tool. As our field evolves and new versions of software are required, access to source allows us to adapt our tools quickly and effectively.

In the early days of software development, most scientific software source code was freely and openly shared with a minimum of formalities. These days, it appears that carefully drawn legal documents are necessary to protect free access to the source code of scientific software. We are all deeply indebted to Richard Stallman for showing us how a creative combination of copyrights and seemingly restrictive licenses could give us truly unfettered freedom to use programs, to read their source code and to develop new versions. The GNU project, and the Linux project have shown that an open source approach works. We use the GNU General Public License (the "GPL") for our programs starting with the release of CIFtbx3. Older versions use the license from OpenRasmol. The OpenRasMol conditions for use have correctly been called "GPL-like".

If you are a user of these programs, you will find that the copyrights and notices ask little more of you than that you avoid mistakes by others by keeping the notices with copies, display scientific integrity by citing your sources properly and treating this like other shared scientific developments by not inferring a warranty. If you are a software developer and wish to incorporate what you find here into new code, or to pick up bits and pieces and use them in another context, the situation becomes more complex. Read the notices carefully. You will find that they are "infectious". Whatever you make from our Open Source code must itself be offered as Open Source code. In addition, in order to allow users to understand what has changed and to ensure orderly development you have to describe your changes.

In order to get a complete release of CIFtbx4, CYCLOPS2, cif2cif, cif2xml you will need either a C-shell archive or a shell archive of each package. That is, you need either

ciftbx.cshar.Z, cyclops.cshar.Z, cif2cif.cshar.Z, cif2xml.cshar.Z and cif2pdb.cshar.Z or

ciftbx.shar.Z, cyclops.shar.Z, cif2cif.shar.Z, cif2xml.shar.Z and cif2pdb.shar.Z

You do not need both sets. If you cannot decompress files at your end, then you may wish to have ciftbx.cshar, cyclops.cshar, cif2cif.cshar, cif2xml.cshar and cif2pdb.cshar

In order to test the programs, you will need at least the following CIF dictionaries: cif_core.dic.Z cif_mm.dic.Z and cif_mm_pdbx.dic.Z Check the IUCr web page at http://www.iucr.org for latest versions.

The directory structure within which you will work is

 
                                 top level directory
                                 -------------------
                                         |
                                         |
     --------------------------------------------------------------------------
     |              |             |              |              |             |
dictionaries   ciftbx.src     cyclops.src   cif2cif.src   cif2xml.src   cif2pdb.src
------------   ----------     -----------   -----------   -----------   -----------

In order to save space and transmission time, it is possible that each archive will be compressed before you pick it up. Place the archives in the top level directory and the dictionaries into the 'dictionaries' directory. Be sure to uncompress the archives before trying to unpack them. If you are on a UNIX system, leave the dictionaries compressed.

Each archive contains a detailed README file for the package involved. Please do read the README. The general approach is:

1. unpack the archive

2. make all

3. make tests

Since all this code depends on CIFtbx, you must install CIFtbx before installing CYCLOPS2, cif2cif, cif2xml or cif2pdb. If you don't need CYCLOPS2 or cif2cif or cif2xml or cif2pdb, you may leave them out, but they are good examples of working CIFtbx applications, so we suggest taking a look at them if you are new to CIFtbx.