---

cmtzlib.h

Go to the documentation of this file.

/*
     cmtzlib.h: header file for cmtzlib.c
     Copyright (C) 2001  CCLRC, Martyn Winn

     This library is free software and is distributed under the terms and
     conditions of the CCP4 licence agreement as `Part 0' (Annex 2)
     software, which is version 2.1 of the GNU Lesser General Public
     Licence (LGPL) with the following additional clause:

        `You may also combine or link a "work that uses the Library" to
        produce a work containing portions of the Library, and distribute
        that work under terms of your choice, provided that you give
        prominent notice with each copy of the work that the specified
        version of the Library is used in it, and that you include or
        provide public access to the complete corresponding
        machine-readable source code for the Library including whatever
        changes were used in the work. (i.e. If you make changes to the
        Library you must distribute those, but you do not need to
        distribute source or object code to those portions of the work
        not covered by this licence.)'

     Note that this clause grants an additional right and does not impose
     any additional restriction, and so does not affect compatibility
     with the GNU General Public Licence (GPL). If you wish to negotiate
     other terms, please contact the maintainer.

     You can redistribute it and/or modify the library under the terms of
     the GNU Lesser General Public License as published by the Free Software
     Foundation; either version 2.1 of the License, or (at your option) any
     later version.

     This library is distributed in the hope that it will be useful, but
     WITHOUT ANY WARRANTY; without even the implied warranty of
     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
     Lesser General Public License for more details.

     You should have received a copy of the CCP4 licence and/or GNU
     Lesser General Public License along with this library; if not, write
     to the CCP4 Secretary, Daresbury Laboratory, Warrington WA4 4AD, UK.
     The GNU Lesser General Public can also be obtained by writing to the
     Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
     MA 02111-1307 USA
*/

#ifndef __CMTZLib__
#define __CMTZLib__

static char rcsidhm[100] = "$Id: cmtzlib_8h-source.html,v 1.8 2004/07/05 14:36:56 mdw Exp $";

/* defines CCP4::CCP4File */
#include "ccp4_utils.h"

#ifdef  __cplusplus
namespace CMtz {
extern "C" {
typedef CCP4::CCP4File CCP4File;
#endif

/* needs to be here for C++ to use CCP4File typedef */
#include "mtzdata.h"

/**** MTZ i/o ****/

MTZ *MtzGet(const char *logname, int read_refs);

int MtzRrefl(CCP4File *filein, int ncol, float *refldata);

int MtzPut(MTZ *mtz, const char *logname);

CCP4File *MtzOpenForWrite(const char *logname);

int MtzWhdrLine(CCP4File *fileout, int nitems, char buffer[]);

int MtzWrefl(CCP4File *fileout, int ncol, float *refldata);

int MtzDeleteRefl(MTZ *mtz, int iref);

/**** Memory allocation ****/

MTZ *MtzMalloc(int nxtal, int nset[]);

int MtzFree(MTZ *mtz);

MTZCOL *MtzMallocCol(MTZ *mtz, int nref);

int MtzFreeCol(MTZCOL *col);

MTZBAT *MtzMallocBatch(void);

int MtzFreeBatch(MTZBAT *batch);
  
char *MtzCallocHist(int nhist);

int MtzFreeHist(char *hist);

void MtzMemTidy(void);

/**** Header operations ****/
  
int MtzNbat(const MTZ *mtz);

int MtzNref(const MTZ *mtz);

int MtzSpacegroupNumber(const MTZ *mtz);

int MtzResLimits(const MTZ *mtz, float *minres, float *maxres);

/**** Crystal operations ****/

int MtzNxtal(const MTZ *mtz);

int MtzNumActiveXtal(const MTZ *mtz);

MTZXTAL **MtzXtals(MTZ *mtz);

MTZXTAL *MtzIxtal(const MTZ *mtz, const int ixtal);

char *MtzXtalPath(const MTZXTAL *xtal);

MTZXTAL *MtzXtalLookup(const MTZ *mtz, const char *label);

MTZXTAL *MtzAddXtal(MTZ *mtz, const char *xname, const char *pname,
                  const float cell[6]);

int MtzNsetsInXtal(const MTZXTAL *xtal);

int MtzNumActiveSetsInXtal(const MTZ *mtz, const MTZXTAL *xtal);

MTZSET **MtzSetsInXtal(MTZXTAL *xtal);

MTZSET *MtzIsetInXtal(const MTZXTAL *xtal, const int iset);

/**** Dataset operations ****/

int MtzNset(const MTZ *mtz);

int MtzNumActiveSet(const MTZ *mtz);

MTZXTAL *MtzSetXtal(const MTZ *mtz, const MTZSET *set);

char *MtzSetPath(const MTZ *mtz, const MTZSET *set);

MTZSET *MtzSetLookup(const MTZ *mtz, const char *label);

MTZSET *MtzAddDataset(MTZ *mtz, MTZXTAL *xtl, const char *dname,
                    const float wavelength);

int MtzNcolsInSet(const MTZSET *set);

int MtzNumActiveColsInSet(const MTZSET *set);

int MtzNumSourceColsInSet(const MTZSET *set);

int MtzNbatchesInSet(const MTZ *mtz, const MTZSET *set);

MTZCOL **MtzColsInSet(MTZSET *set);

MTZCOL *MtzIcolInSet(const MTZSET *set, const int icol);

/**** Column operations ****/

MTZCOL *MtzAddColumn(MTZ *mtz, MTZSET *set, const char *label,
                   const char *type);

int MtzAssignHKLtoBase(MTZ *mtz);

int MtzAssignColumn(MTZ *mtz, MTZCOL *col, const char crystal_name[],  
             const char dataset_name[]);

int MtzToggleColumn(MTZCOL *col);

MTZSET  *MtzColSet(const MTZ *mtz, const MTZCOL *col);

int MtzNcol(const MTZ *mtz);
  
int MtzNumActiveCol(const MTZ *mtz);
  
int MtzNumSourceCol(const MTZ *mtz);

char *MtzColPath(const MTZ *mtz, const MTZCOL *col);

int MtzRJustPath(char *path, const char *partial, const int njust);

int MtzPathMatch(const char *path1, const char *path2);

MTZCOL *MtzColLookup(const MTZ *mtz, const char *label);

char *MtzColType(MTZCOL *col);

void MtzDebugHierarchy(const MTZ *mtz);

int MtzListColumn(const MTZ *mtz, char clabs[][31], char ctyps[][3], int csetid[]);

int MtzListInputColumn(const MTZ *mtz, char clabs[][31], char ctyps[][3], int csetid[]);

/**** helper functions ****/

int MtzFindInd(const MTZ *mtz, int *ind_xtal, int *ind_set, int ind_col[3]);

float MtzInd2reso(const int in[3], const double coefhkl[6]);

int MtzHklcoeffs(const float cell[6], double coefhkl[6]);

int MtzArrayToBatch(const int *intbuf, const float *fltbuf, MTZBAT *batch);

int MtzBatchToArray(MTZBAT *batch, int *intbuf, float *fltbuf);

MTZBAT *sort_batches(MTZBAT *batch, int numbat);

/**** pseudo-mtzlib routines ****/

int ccp4_lrtitl(const MTZ *mtz, char *title);

int ccp4_lrhist(const MTZ *mtz, char history[][MTZRECORDLENGTH], int nlines);

int ccp4_lrsort(const MTZ *mtz, int isort[5]);

int ccp4_lrbats(const MTZ *mtz, int *nbatx, int batchx[]);

int ccp4_lrcell(const MTZXTAL *xtl, float cell[]);

int ccp4_lrsymi(const MTZ *mtz, int *nsympx, char *ltypex, int *nspgrx, 
       char *spgrnx, char *pgnamx);

int ccp4_lrsymm(const MTZ *mtz, int *nsymx, float rsymx[192][4][4]);

int MtzParseLabin(char *labin_line, const char prog_labels[][31], 
           const int nlprgi, char user_labels[][2][31]);

MTZCOL **ccp4_lrassn(const MTZ *mtz, const char labels[][31], const int nlabels, 
                char types[][3]);

int ccp4_lridx(const MTZ *mtz, const MTZSET *set, char crystal_name[64], 
            char dataset_name[64], char project_name[64], int *isets, 
            float datcell[6], float *datwave);

int ccp4_lrrefl(const MTZ *mtz, float *resol, float adata[], int logmss[], int iref);

int ccp4_lrreff(const MTZ *mtz, float *resol, float adata[], int logmss[],
                const MTZCOL *lookup[], const int ncols, const int iref);

int ccp4_ismnf(const MTZ *mtz, const float datum);

int ccp4_lhprt(const MTZ *mtz, int iprint);

int ccp4_lhprt_adv(const MTZ *mtz, int iprint);

int ccp4_lrbat(MTZBAT *batch, float *buf, char *charbuf, int iprint);

int MtzPrintBatchHeader(const MTZBAT *batch);

int ccp4_lwtitl(MTZ *mtz, const char *ftitle, int flag);

int MtzSetSortOrder(MTZ *mtz, MTZCOL *colsort[5]);

int MtzAddHistory(MTZ *mtz, const char history[][MTZRECORDLENGTH], const int nlines);

int ccp4_lwsymm(MTZ *mtz, int nsymx, int nsympx, float rsymx[192][4][4], 
                char ltypex[], int nspgrx, char spgrnx[], char pgnamx[]);

/* Assign columns for writing. Check to see if columns already exist,
 * else create them. New columns are assigned to the base dataset if it 
 * exists, else the first dataset.
 * @param mtz pointer to MTZ struct
 * @param labels Input array of column labels to be assigned.
 * @param nlabels Number of columns.
 * @param types Input array of column types of columns.
 * @param iappnd If iappnd = 0, then deactivate columns which are
 *   not selected (allows one to write out a subset of columns). Else
 *   if iappnd = 1, append these columns to existing ones.
 * @return Array of pointers to columns in MTZ struct.
 */
MTZCOL **ccp4_lwassn(MTZ *mtz, const char labels[][31], const int nlabels, 
             const char types[][3], const int iappnd);

/* Add or update a dataset in the MTZ structure. If the crystal name is
 * not recognised, then a new crystal is created containing a single
 * dataset. If the crystal name is recognised, then the parameters of
 * the crystal are updated. The child dataset is then created if necessary
 * or an existing dataset updated.
 * Note that this function is used to update crystal parameters, as well
 * as add crystals. If a duplicate crystal name is used by mistake, then 
 * the old crystal parameters are lost.
 * @param mtz pointer to MTZ struct
 * @param crystal_name Crystal name
 * @param dataset_name Dataset name
 * @param project_name Project name
 * @param datcell Cell dimensions of crystal that dataset belongs to.
 * @param datwave X-ray wavelength associated with dataset.
 * @return 1 on success, 0 on failure
 */
int ccp4_lwidx(MTZ *mtz, const char crystal_name[],  const char dataset_name[],
        const char project_name[], const float datcell[6], const float *datwave);


int ccp4_lwrefl(MTZ *mtz, const float adata[], MTZCOL *lookup[], 
                 const int ncol, const int iref);

int ccp4_lwbat(MTZ *mtz, MTZBAT *batch, const int batno, const float *buf, const char *charbuf);

int ccp4_lwbsetid(MTZ *mtz, MTZBAT *batch, const char xname[], const char dname[]);

/* -- Below here there are no implementations -- */

/* COMPLEX HLToSF(float hla, float hlb, float hlc, float hld, BOOLEAN centric); */
/* Returns the mean structure factor as a complex number from a structure
   factor probability distribution described by Hendrickson/Lattman
   coefficients. If `centric == TRUE`, the coefficients describe a centric
   distribution. */

/* MTZ *MtzSort(MTZ *mtz, char *ident); */
/* Sorts `mtz` using the identifiers (separated by spaces) in `ident` as
   keys. Sorting can be done on up to 200 columns. A pointer to `*mtz` is
   returned. */

/* MTZ *HLCombine (MTZ *to, float toscale, MTZ *frm, float frmscale); */
/* Combines extra phase information for common reflections between 'frm'
   and 'to' into the phase information of 'to'. The phase probabilities
   are described by Hendrickson Lattman coefficients, with the identifiers
   "HLA", "HLB", HLC", and "HLD", the indices are identified by "H", "K" 
   and "L". HL-coeffs from 'to' are scaled by 'toscale', the coeffs from
   'frm' are scaled by 'frmscale'. A pointer to `to` is returned. */

/* void MtzPhiFom(MTZ *mtz); */
/* Calculates the best phase and the figure of from Hendrickson Lattman
   coefficients. The following columns should be present in `mtz`:
   "H", "K" & "L" (indices); "PHIB" & "FOM" (best phase (degrees) and figure of
   merit); "HLA", "HLB", "HLC" & "HLD" (Hendrickson Lattman coefficients). */

/* MTZ *MtzCopy(MTZ *frm); */
/* Produces an exact copy of `frm` and returns a pointer to it. */

/* MTZ *MtzColAppend(MTZ *mtz, char *ident, char type); */
/* Appends a column to `*mtz` with identity `ident` and type `type`, provided
   no column with identity `ident` exists. */

/* MTZ *MtzColRemove(MTZ *mtz, char *ident); */
/* Removes a column from `*mtz` with identity `ident`. */

/* MTZ *MtzUpdateRanges(MTZ *mtz); */
/* Updates ranges of all columns in `mtz` and returns `mtz`. */

/* MTZCOL *MtzColNewRange(MTZCOL *col, int nref); */
/* Updates the minimum & maximum values in `col` and returns `col`. */

/* int *MtzUnique(MTZ *mtz, char *ident); */
/* Returns an array (k) of indices: k[j] returns the first occurrence of a set
   of idents, eg. MtzUnique(mtz, "H K L") returns an array from which all the 
   unique reflections can be determined by indexing with k: k[i] is the index
   of the last relection of a set which all have the same hkl indices. It is
   assumed that `mtz` is sorted, using `ident` as keys. */

/* float PhaseProb(float phase, float hla, float hlb, float hlc, float hld,
                BOOLEAN centric); */
/* Returns the probability of `phase` (expressed in radians) as determined by
   the Hendrickson-Lattmann coefficients `hla`, `hlb`, `hlc` and `hld`. If
   `centric == TRUE`, the coefficients describe a centric distribution. */

#ifdef __cplusplus
} }
#endif
#endif