gpp4 1.3.1

src/cmtzlib.h

Go to the documentation of this file.
00001 /*
00002      cmtzlib.h: header file for cmtzlib.c
00003      Copyright (C) 2001  CCLRC, Martyn Winn
00004 
00005      This library is free software: you can redistribute it and/or
00006      modify it under the terms of the GNU Lesser General Public
00007      License as published by the Free Software Foundation, either
00008      version 3 of the License, or (at your option) any later version.
00009 
00010      This library is distributed in the hope that it will be useful,
00011      but WITHOUT ANY WARRANTY; without even the implied warranty of
00012      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
00013      Lesser General Public License for more details.
00014 
00015      You should have received a copy of the GNU Lesser General Public
00016      License along with This library.  If not, see
00017      <http://www.gnu.org/licenses/>.
00018 
00019 */
00020 
00101 #ifndef __CMTZLib__
00102 #define __CMTZLib__
00103 
00104 
00105 /* defines CCP4::CCP4File */
00106 #include "ccp4_utils.h"
00107 
00108 #ifdef  __cplusplus
00109 namespace CMtz {
00110 extern "C" {
00111 typedef CCP4::CCP4File CCP4File;
00112 #endif
00113 
00114 /* needs to be here for C++ to use CCP4File typedef */
00115 #include "mtzdata.h"
00116 
00117 /**** MTZ i/o ****/
00118 
00125 MTZ *MtzGet(const char *logname, int read_refs);
00126 
00138 MTZ *MtzGetUserCellTolerance(const char *logname, int read_refs, const double cell_tolerance);
00139 
00146 int MtzRrefl(CCP4File *filein, int ncol, float *refldata);
00147 
00154 int MtzPut(MTZ *mtz, const char *logname);
00155 
00163 CCP4File *MtzOpenForWrite(const char *logname);
00164 
00172 int MtzWhdrLine(CCP4File *fileout, int nitems, char buffer[]);
00173 
00181 int MtzWrefl(CCP4File *fileout, int ncol, float *refldata);
00182 
00189 int MtzDeleteRefl(MTZ *mtz, int iref);
00190 
00195 void MtzRewdInput(MTZ *mtz);
00196 
00197 /**** Memory allocation ****/
00198 
00210 MTZ *MtzMalloc(int nxtal, int nset[]);
00211 
00216 int MtzFree(MTZ *mtz);
00217 
00224 MTZCOL *MtzMallocCol(MTZ *mtz, int nref);
00225 
00230 int MtzFreeCol(MTZCOL *col);
00231 
00235 MTZBAT *MtzMallocBatch(void);
00236 
00241 int MtzFreeBatch(MTZBAT *batch);
00242   
00247 char *MtzCallocHist(int nhist);
00248 
00253 int MtzFreeHist(char *hist);
00254 
00260 void MtzMemTidy(void);
00261 
00262 /**** Header operations ****/
00263   
00268 int MtzNbat(const MTZ *mtz);
00269 
00274 int MtzNref(const MTZ *mtz);
00275 
00280 int MtzSpacegroupNumber(const MTZ *mtz);
00281 
00289 int MtzResLimits(const MTZ *mtz, float *minres, float *maxres);
00290 
00291 /**** Crystal operations ****/
00292 
00297 int MtzNxtal(const MTZ *mtz);
00298 
00303 int MtzNumActiveXtal(const MTZ *mtz);
00304 
00309 MTZXTAL **MtzXtals(MTZ *mtz);
00310 
00316 MTZXTAL *MtzIxtal(const MTZ *mtz, const int ixtal);
00317 
00324 char *MtzXtalPath(const MTZXTAL *xtal);
00325 
00331 MTZXTAL *MtzXtalLookup(const MTZ *mtz, const char *label);
00332 
00340 MTZXTAL *MtzAddXtal(MTZ *mtz, const char *xname, const char *pname,
00341                   const float cell[6]);
00342 
00347 int MtzNsetsInXtal(const MTZXTAL *xtal);
00348 
00353 int MtzNumActiveSetsInXtal(const MTZ *mtz, const MTZXTAL *xtal);
00354 
00360 MTZSET **MtzSetsInXtal(MTZXTAL *xtal);
00361 
00368 MTZSET *MtzIsetInXtal(const MTZXTAL *xtal, const int iset);
00369 
00370 /**** Dataset operations ****/
00371 
00376 int MtzNset(const MTZ *mtz);
00377 
00382 int MtzNumActiveSet(const MTZ *mtz);
00383 
00391 MTZXTAL *MtzSetXtal(const MTZ *mtz, const MTZSET *set);
00392 
00401 char *MtzSetPath(const MTZ *mtz, const MTZSET *set);
00402 
00409 MTZSET *MtzSetLookup(const MTZ *mtz, const char *label);
00410 
00418 MTZSET *MtzAddDataset(MTZ *mtz, MTZXTAL *xtl, const char *dname,
00419                     const float wavelength);
00420 
00427 int MtzNcolsInSet(const MTZSET *set);
00428 
00433 int MtzNumActiveColsInSet(const MTZSET *set);
00434 
00440 int MtzNumSourceColsInSet(const MTZSET *set);
00441 
00447 int MtzNbatchesInSet(const MTZ *mtz, const MTZSET *set);
00448 
00454 MTZCOL **MtzColsInSet(MTZSET *set);
00455 
00463 MTZCOL *MtzIcolInSet(const MTZSET *set, const int icol);
00464 
00465 /**** Column operations ****/
00466 
00474 MTZCOL *MtzAddColumn(MTZ *mtz, MTZSET *set, const char *label,
00475                    const char *type);
00476 
00481 int MtzAssignHKLtoBase(MTZ *mtz);
00482 
00495 int MtzAssignColumn(MTZ *mtz, MTZCOL *col, const char crystal_name[],  
00496              const char dataset_name[]);
00497 
00504 int MtzToggleColumn(MTZCOL *col);
00505 
00512 MTZSET  *MtzColSet(const MTZ *mtz, const MTZCOL *col);
00513 
00518 int MtzNcol(const MTZ *mtz);
00519   
00524 int MtzNumActiveCol(const MTZ *mtz);
00525   
00531 int MtzNumSourceCol(const MTZ *mtz);
00532 
00540 char *MtzColPath(const MTZ *mtz, const MTZCOL *col);
00541 
00548 int MtzRJustPath(char *path, const char *partial, const int njust);
00549 
00555 int MtzPathMatch(const char *path1, const char *path2);
00556 
00562 MTZCOL *MtzColLookup(const MTZ *mtz, const char *label);
00563 
00568 char *MtzColType(MTZCOL *col);
00569 
00575 void MtzDebugHierarchy(const MTZ *mtz);
00576 
00584 int MtzListColumn(const MTZ *mtz, char clabs[][31], char ctyps[][3], int csetid[]);
00585 
00593 int MtzListInputColumn(const MTZ *mtz, char clabs[][31], char ctyps[][3], int csetid[]);
00594 
00595 /**** helper functions ****/
00596 
00605 int MtzFindInd(const MTZ *mtz, int *ind_xtal, int *ind_set, int ind_col[3]);
00606 
00613 float MtzInd2reso(const int in[3], const double coefhkl[6]);
00614 
00620 int MtzHklcoeffs(const float cell[6], double coefhkl[6]);
00621 
00628 int MtzArrayToBatch(const int *intbuf, const float *fltbuf, MTZBAT *batch);
00629 
00636 int MtzBatchToArray(MTZBAT *batch, int *intbuf, float *fltbuf);
00637 
00646 MTZBAT *sort_batches(MTZBAT *batch, int numbat);
00647 
00648 /**** pseudo-mtzlib routines ****/
00649 
00656 int ccp4_lrtitl(const MTZ *mtz, char *title);
00657 
00664 int ccp4_lrhist(const MTZ *mtz, char history[][MTZRECORDLENGTH], int nlines);
00665 
00671 int ccp4_lrsort(const MTZ *mtz, int isort[5]);
00672 
00679 int ccp4_lrbats(const MTZ *mtz, int *nbatx, int batchx[]);
00680 
00686 int ccp4_lrcell(const MTZXTAL *xtl, float cell[]);
00687 
00697 int ccp4_lrsymi(const MTZ *mtz, int *nsympx, char *ltypex, int *nspgrx, 
00698        char *spgrnx, char *pgnamx);
00699 
00711 int ccp4_lrsymi_c(const MTZ *mtz, int *nsympx, char *ltypex, int *nspgrx, 
00712        char *spgrnx, char *pgnamx, char *spgconf);
00713 
00723 int ccp4_lrsymm(const MTZ *mtz, int *nsymx, float rsymx[192][4][4]);
00724 
00734 int MtzParseLabin(char *labin_line, const char prog_labels[][31], 
00735            const int nlprgi, char user_labels[][2][31]);
00736 
00750 MTZCOL **ccp4_lrassn(const MTZ *mtz, const char labels[][31], const int nlabels, 
00751                 char types[][3]);
00752 
00766 int ccp4_lridx(const MTZ *mtz, const MTZSET *set, char crystal_name[64], 
00767             char dataset_name[64], char project_name[64], int *isets, 
00768             float datcell[6], float *datwave);
00769 
00785 int ccp4_lrrefl(const MTZ *mtz, float *resol, float adata[], int logmss[], int iref);
00786 
00803 int ccp4_lrreff(const MTZ *mtz, float *resol, float adata[], int logmss[],
00804                 const MTZCOL *lookup[], const int ncols, const int iref);
00805 
00813 int ccp4_ismnf(const MTZ *mtz, const float datum);
00814 
00820 int ccp4_lhprt(const MTZ *mtz, int iprint);
00821 
00828 int ccp4_lhprt_adv(const MTZ *mtz, int iprint);
00829 
00837 int ccp4_lrbat(MTZBAT *batch, float *buf, char *charbuf, int iprint);
00838 
00843 int MtzPrintBatchHeader(const MTZBAT *batch);
00844 
00852 int ccp4_lwtitl(MTZ *mtz, const char *ftitle, int flag);
00853 
00863 int MtzSetSortOrder(MTZ *mtz, MTZCOL *colsort[5]);
00864 
00871 int MtzAddHistory(MTZ *mtz, const char history[][MTZRECORDLENGTH], const int nlines);
00872 
00888 int ccp4_lwsymm(MTZ *mtz, int nsymx, int nsympx, float rsymx[192][4][4], 
00889                 char ltypex[], int nspgrx, char spgrnx[], char pgnamx[]);
00890 
00908 int ccp4_lwsymm_c(MTZ *mtz, int nsymx, int nsympx, float rsymx[192][4][4], 
00909                          char ltypex[], int nspgrx, char spgrnx[], char pgnamx[], 
00910                   char spgconf[]);
00911 
00917 int ccp4_lwsymconf(MTZ *mtz, char spgconf[]);
00918 
00919 /* Assign columns for writing. Check to see if columns already exist,
00920  * else create them. New columns are assigned to the base dataset if it 
00921  * exists, else the first dataset.
00922  * @param mtz pointer to MTZ struct
00923  * @param labels Input array of column labels to be assigned.
00924  * @param nlabels Number of columns.
00925  * @param types Input array of column types of columns.
00926  * @param iappnd If iappnd = 0, then deactivate columns which are
00927  *   not selected (allows one to write out a subset of columns). Else
00928  *   if iappnd = 1, append these columns to existing ones.
00929  * @return Array of pointers to columns in MTZ struct.
00930  */
00931 MTZCOL **ccp4_lwassn(MTZ *mtz, const char labels[][31], const int nlabels, 
00932              const char types[][3], const int iappnd);
00933 
00934 /* Add or update a dataset in the MTZ structure. If the crystal name is
00935  * not recognised, then a new crystal is created containing a single
00936  * dataset. If the crystal name is recognised, then the parameters of
00937  * the crystal are updated. The child dataset is then created if necessary
00938  * or an existing dataset updated.
00939  * Note that this function is used to update crystal parameters, as well
00940  * as add crystals. If a duplicate crystal name is used by mistake, then 
00941  * the old crystal parameters are lost.
00942  * @param mtz pointer to MTZ struct
00943  * @param crystal_name Crystal name
00944  * @param dataset_name Dataset name
00945  * @param project_name Project name
00946  * @param datcell Cell dimensions of crystal that dataset belongs to.
00947  * @param datwave X-ray wavelength associated with dataset.
00948  * @return 1 on success, 0 on failure
00949  */
00950 int ccp4_lwidx(MTZ *mtz, const char crystal_name[],  const char dataset_name[],
00951         const char project_name[], const float datcell[6], const float *datwave);
00952 
00953 
00971 int ccp4_lwrefl(MTZ *mtz, const float adata[], MTZCOL *lookup[], 
00972                  const int ncol, const int iref);
00973 
00987 int ccp4_lwbat(MTZ *mtz, MTZBAT *batch, const int batno, const float *buf, const char *charbuf);
00988 
00989 int ccp4_lwbsetid(MTZ *mtz, MTZBAT *batch, const char xname[], const char dname[]);
00990 
00991 /* -- Below here there are no implementations -- */
00992 
00993 /* COMPLEX HLToSF(float hla, float hlb, float hlc, float hld, BOOLEAN centric); */
00994 /* Returns the mean structure factor as a complex number from a structure
00995    factor probability distribution described by Hendrickson/Lattman
00996    coefficients. If `centric == TRUE`, the coefficients describe a centric
00997    distribution. */
00998 
00999 /* MTZ *MtzSort(MTZ *mtz, char *ident); */
01000 /* Sorts `mtz` using the identifiers (separated by spaces) in `ident` as
01001    keys. Sorting can be done on up to 200 columns. A pointer to `*mtz` is
01002    returned. */
01003 
01004 /* MTZ *HLCombine (MTZ *to, float toscale, MTZ *frm, float frmscale); */
01005 /* Combines extra phase information for common reflections between 'frm'
01006    and 'to' into the phase information of 'to'. The phase probabilities
01007    are described by Hendrickson Lattman coefficients, with the identifiers
01008    "HLA", "HLB", HLC", and "HLD", the indices are identified by "H", "K" 
01009    and "L". HL-coeffs from 'to' are scaled by 'toscale', the coeffs from
01010    'frm' are scaled by 'frmscale'. A pointer to `to` is returned. */
01011 
01012 /* void MtzPhiFom(MTZ *mtz); */
01013 /* Calculates the best phase and the figure of from Hendrickson Lattman
01014    coefficients. The following columns should be present in `mtz`:
01015    "H", "K" & "L" (indices); "PHIB" & "FOM" (best phase (degrees) and figure of
01016    merit); "HLA", "HLB", "HLC" & "HLD" (Hendrickson Lattman coefficients). */
01017 
01018 /* MTZ *MtzCopy(MTZ *frm); */
01019 /* Produces an exact copy of `frm` and returns a pointer to it. */
01020 
01021 /* MTZ *MtzColAppend(MTZ *mtz, char *ident, char type); */
01022 /* Appends a column to `*mtz` with identity `ident` and type `type`, provided
01023    no column with identity `ident` exists. */
01024 
01025 /* MTZ *MtzColRemove(MTZ *mtz, char *ident); */
01026 /* Removes a column from `*mtz` with identity `ident`. */
01027 
01028 /* MTZ *MtzUpdateRanges(MTZ *mtz); */
01029 /* Updates ranges of all columns in `mtz` and returns `mtz`. */
01030 
01031 /* MTZCOL *MtzColNewRange(MTZCOL *col, int nref); */
01032 /* Updates the minimum & maximum values in `col` and returns `col`. */
01033 
01034 /* int *MtzUnique(MTZ *mtz, char *ident); */
01035 /* Returns an array (k) of indices: k[j] returns the first occurrence of a set
01036    of idents, eg. MtzUnique(mtz, "H K L") returns an array from which all the 
01037    unique reflections can be determined by indexing with k: k[i] is the index
01038    of the last relection of a set which all have the same hkl indices. It is
01039    assumed that `mtz` is sorted, using `ident` as keys. */
01040 
01041 /* float PhaseProb(float phase, float hla, float hlb, float hlc, float hld,
01042                 BOOLEAN centric); */
01043 /* Returns the probability of `phase` (expressed in radians) as determined by
01044    the Hendrickson-Lattman coefficients `hla`, `hlb`, `hlc` and `hld`. If
01045    `centric == TRUE`, the coefficients describe a centric distribution. */
01046 
01047 #ifdef __cplusplus
01048 } }
01049 #endif
01050 #endif