/*! \mainpage The Clipper Project \author Kevin Cowtan There are currently two major pressures on crystallographic computing: - Increased automation to increase throughput in line with genomics applications. - Increased data complexity, as data from more sources is combined and carried through the whole calculation to solve more difficult problems. The Clipper project is an initiative to address these pressures. The aim of the project is to produce a set of object-oriented libraries for the organisation of crystallographic data and the performance of crystallographic computation. The libraries are designed as a framework for new crystallographic software, which will allow the full power of modern programming techniques to be exploited by the developer. This will lead to greater functionality from simpler code which will be easier to develop and debug. \section s_oop Object oriented programming The evolution of high level programing may be very imprecisely caricatured as follows: - Early high-level languages (Fortran): There is no structure to data or code. Variables are not grouped in any way or specially associated with any code. - Structured programming (C, Pascal, etc): Data structures are introduced, grouping related variables into compound objects, which can completely specify the state of some object. - Object-oriented programming (Smalltalk, C++, etc): Data structures may now contain code, and now describe not only the state of the object, but also its behavior and interactions. (In the general case, all code becomes part of an object.) Clipper is object-oriented. The main benefit of this approach is that code becomes much more reusable, since objects are self-contained, and may be reused, rewritten, or replaced without affecting other code. Additionally, the organisation of the code and data is generally much clearer. \section s_obj Clipper objects Clipper defines a wide range of objects. These fall into a number of groups, including: - \ref ss_cobj : Cell, Spacegroup, Metric, R/T operator, etc. - \ref ss_dobj : Reflection data, Crystallographic map, Non-crystallographic map, Coordinate model. - \ref ss_mobj : FFT arrays, Resolution functions, Conversion objects, Import/export objects The coordinate object is a substantial task in itself and is addressed by an interface to the CCP4 'MMDB' library, developed by Dr Eugene Krissinel. Some of the objects will be discussed in more detail: \subsection ss_cobj Crystallographic objects: These implements the fundamental properties of a crystal. <dl> <dt>The Cell object: <dd>This object describes a unit cell. It holds the cell parameters, and derived information including coordinate conversion matrices and metrics. Any cell object may be used to convert coordinates between orthogonal and fractional forms, and calculate distances in real space and resolutions in reciprocal space. <dt>The Spacegroup object: <dd>This object describes a spacegroup, using information from the 'cctbx' library of Dr Ralph Grosse-Kunstleve. It can be use to generate symmetry coordinates and reflections, phase shifts, centricity, asymmetric units, and so on. </dl> \subsection ss_dobj Data objects: These hold actual data. They are written as templates which can hold whatever type of data the developer requires. <dl> <dt>The reflection data object: <dd>It is commonly necessary to store several related items of reflection data. Therefore this object is split into two parts; a parent object which holds a list of Miller indices and related data, and then several data objects which hold the actual data associated with each Miller index. The data objects can hold data of arbitrary types: these types will usually consist of several values. For example, a structure factor magnitude and its variance, or all four Hendrickson-Lattman coefficients, are usually held in a single data object. To the user, the data appears to cover the whole of reciprocal space, however in practice only an asymmetric unit is stored. Data is transformed about reciprocal spaces as required. When a new data type is defined, its behavior under transformation is also be defined so that this mapping can be performed. <dt>The crystallographic map object: <dd>This object also implements crystallographic symmetry, and also cell repeat, in a manner which is transparent to the user. It may also hold arbitrary data types: common examples would include bits, real values, complex values, or orthogonal or fractional gradients. <dt>The non-crystallographic map object: <dd>This object is used for map data which does not have symmetry or cell repeat, for example an NCS averaging mask. </dl> \subsection ss_mobj Method objects: These are used to provide additional functionality commonly required in crystallographic calculations. Examples include: <dl> <dt>FFT map: <dd>This object holds data which may be represented in either real or reciprocal space. The data may be accessed in either form, and may be transformed between spaces as required. <dt>The resolution function evaluator: <dd>This object creates an arbitrary function of position in reciprocal space, by optimising the parameters of some basis function in order to minimise some target function. This is an extreme generalisation of the idea of 'resolution bins', and can be used for anything from <|F|<sup>2</sup>><sub>s</sub> to sigma-a and beyond. <dt>Import/export objects: <dd>The only import/export objects implemented so far are the MTZfile and MAPfile objects. These stand as proxies for an external file, and can transfer data between the Clipper objects and the file. </dl> \section s_scpt Scripting Automation of crystallographic tasks depends on being able to communicate between successive tasks, and by being able to execute control code to activate tasks and make protocol decisions. This functionality is provided through a scripting interface. A Python interface will be provided through the boost.python library. It is possible that interfaces to C and a range of scripting languages will be provided through other means. All the data and the full functionality of the methods will be available from the scripting layer, allowing full automation and full communication between tasks. Eventually the individual programs should disappear, rather exposing their functionality directly to the scripting layer. At the same time, data will have to move from traditional files into a database, so that each task has immediate access to all the information currently available. \section s_hier Partial class hierarchy (as of 1/2/2001) \image html hierarchy.png \image latex hierarchy.eps width=15cm \section s_ackn Acknowledgments: I would like to thank Ralph Grosse-Kunstleve, Airlie McCoy, Eugene Krissinel, Jan Zelinka and the CCP4 staff for their many and varied contributions to this effort. Clipper stands for 'Cross-crystal Likelihood Phase Probability Estimation and Refinement', which is what I hope to use it for. \section s_refr References: - 'Clipper' code and documentation (K. Cowtan): http://www.ysbl.york.ac.uk/~cowtan/clipper/clipper.html - 'mmdb' coordinate library (E. Krissinel): http://www.ebi.ac.uk/~keb/cldoc/ - 'cctbx' crystallography toolbox (R. Grosse-Kunstleve): http://cctbx.sourceforge.net See the following pages in the Clipper documentation for further information: - \ref p_class_overview (brief guide to classes) - \ref p_conventions (coding style) - \ref p_coords (Coodinate types) - \ref p_develop (initial example) - \ref p_develop_hkl (reflection data handling and examples) - \ref p_develop_map (map handling and examples) - \ref p_develop_model (model handling) - \ref p_wheretolook (thematic index) - \ref p_installation (and dependencies) */ /*! \namespace clipper All normal clipper objects except data objects are defined in this namespace. */ /*! \namespace clipper::datatypes This namespace is used for templates which will later be instantiated for float or double precision data. You would not normally reference a class from this namespace directly. */ /*! \namespace clipper::data32 This namespace contains instantiations of template classes for storage and manipulation of float data types. */ /*! \namespace clipper::data64 This namespace contains instantiations of template classes for storage and manipulation of double data types. */
