Clipper
Class Overview

Introduction

This page contains a brief outline of the types of classes provided by the Clipper libraries, followed by a more detailed description of the different classes.

  1. Ordinates and grids:

    Ordinates include Miller indices (clipper::HKL), orthogonal and fractional coordinates (clipper::Coord_orth, clipper::Coord_frac), and grid coordinates (clipper::Coord_grid).

    Grids describe the storage of 3D data: The basic grid class (clipper::Grid) describes the dimensions and indexing of a 3D rectangular arrays. The unit cell grid (clipper::Grid_sampling) also provides methods for converting between fractional and grid coordinates, and the map grid (clipper::Grid_range) describes a general sampled map, which is bounded by lower and upper grid coordinates.

  2. Crystal information

    A crystal is defined by two main classes: a unit cell (clipper::Cell) and a spacegroup (clipper::Spacegroup).

    These are complex classes which store derived information and provide optimised methods for handling it. Two smaller `descriptor' objects provide a more compact representation for storage and transmission: The cell descriptor (clipper::Cell_descr) holds just the cell edges and angles, and the spacegroup descriptor (clipper::Spgr_descr) hold the Hall code of the spacegroup.

  3. Data objects

    Data objects hold the actual crystallographic data. They include reciprocal space data (clipper::HKL_info, clipper::HKL_data), crystallographic and non-crystallographic maps (clipper::Xmap, clipper::NXmap), and FFT maps (clipper::FFTmap)

    The primary design goal of the data objects is that they hide all the bookkeeping associated with crystallographic symmetry (and in real space, cell repeat). Data can be written to and read from any region of real or reciprocal space, and the unique stored copy of the data will be modified correctly. This is all achieved in a computationally efficient manner.

    The data objects are templates which can hold data of any type. In the case of a map, this type will usually be `double' or `float', however in the case of reciprocal space data the types are often more complex, for example `magnitude and phase' (F_phi) or Hendrickson-Lattman coefficient (ABCD).

  4. Input/Output objects

    Input/Output objects are used to record the contents of an object in a file or restore the contents from a file. (MTZfile, MAPfile)

    The crystal descriptors and data objects may be used as stand-alone objects. However, the data objects are related to a particular crystal, and may be related to each other. In order to facilitate the organisation of information, all the objects have `container' variants.


Classes

The classes which a developer will commonly encounter are as follows:

Ordinates and grids:

Crystal information

Data objects

Reciprocal space data

The reciprocal space data object is divided into two parts: the first part (clipper::HKL_info) handles indexing of reflections and information derived from the Miller indices, and the second part contains the actual data. The reasons for this division are that it is common to have several lists of information for each reflection, so a single list of Miller indices can be used for several lists of data. This also allows the use of optimised tables for looking up reflections, without wasting space duplicating them for several data lists.

However, if reciprocal space data are stored which do not have the same list of Miller indices, it is quite possible to provide several clipper::HKL_info objects, one for each list of data.

Real space data

Other objects

Input/Output objects

Coordinate-reference types.

Coordinate-reference types are provided for accessing data in both real and reciprocal space. Data is commonly referred to in one of two ways:

  1. by index into a list of unique data, or
  2. by 3-dimensional coordinate. The coordinate-reference types are designed to make switching between the two forms of reference easier. Two coordinate-reference types are provided in each space - one which behaves more like an index, and one which behaves more like a coordinate. However, either may be asked to return either an index or a coordinate on request. References may also return other useful information, for example the HKL_reference types will return the resolution and reflection class of a reflection (i.e. centricity, phase restriction, multiplicity).

The coordinate reference types are as follows:

clipper::HKL_info::HKL_reference_index
clipper::HKL_info::HKL_reference_coord
clipper::XMap_base::Map_reference_index
clipper::XMap_base::Map_reference_coord
clipper::NXMap_base::Map_reference_index
clipper::NXMap_base::Map_reference_coord

The index-like reference is simply an index, and a pointer to the parent object, which allows the corresponding coordinate to be looked up. It provides a convenient way to access either every unique reflection in a list, or every unique map grid point in the asymmetric unit, in turn. The coordinate-reference type is usually initialised by assignment from the `first' method in the parent object. It may then be incremented by its own `next' method. Completion is tested by the `last' method. For example, if hklinfo is an object of type clipper::HKL_info and xmap is an object of type clipper::Xmap<double>, then the following loops could be used to access all the data:

  for ( clipper::HKL_info::HKL_reference_index ih = hklinfo.first(); !ih.last(); ih.next )

However, if the Miller indices of a reflection are are required, the reference type may be queried directly. Other information can also be obtained:

  HKL hkl = ih.hkl();
  int index = ih.index();
  ftype s = ih.invresolsq();
  HKL_class cls = ih.hkl_class();

Similarly, if hkldata is an object of type clipper::HKL_data<I_sigI>, then the following will loop over all non-missing data in the list:

  for ( clipper::HKL_info::HKL_reference_index ih = hkldata.first_data(); !ih.last(); ih.next_data(hkldata) )

The reference types in real space are equivalent:

  for ( clipper::Xmap_base::Map_reference_index ix = xmap.first(); !ix.last(); ix.next ) {
    int i = ix.index()
    Coord_grid coord = ix.coord();
  }

The coordinate-like types are more sophisticated. They hold a coordinate and a pointer to the parent object. However, the corresponding index is also stored (if it exists), along with the symmetry operator (and in reciprocal space the Friedel operator) used to obtain it. If an new coordinate is assigned to the reference, then this symmetry operator will be tried first, providing a significant performance gain.

The differences between the index-like and coordinate-like reference types can be summarised as follows:

Generally index-like types are used to loop through the stored data, whereas coordinate-like types are used to interact with data stored in a different way.