include/statutil.h

   1 /*
   2  *
   3  *                This source code is part of
   4  *
   5  *                 G   R   O   M   A   C   S
   6  *
   7  *          GROningen MAchine for Chemical Simulations
   8  *
   9  *                        VERSION 3.2.0
  10  * Written by David van der Spoel, Erik Lindahl, Berk Hess, and others.
  11  * Copyright (c) 1991-2000, University of Groningen, The Netherlands.
  12  * Copyright (c) 2001-2004, The GROMACS development team,
  13  * check out http://www.gromacs.org for more information.
  14
  15  * This program is free software; you can redistribute it and/or
  16  * modify it under the terms of the GNU General Public License
  17  * as published by the Free Software Foundation; either version 2
  18  * of the License, or (at your option) any later version.
  19  *
  20  * If you want to redistribute modifications, please consider that
  21  * scientific software is very special. Version control is crucial -
  22  * bugs must be traceable. We will be happy to consider code for
  23  * inclusion in the official distribution, but derived work must not
  24  * be called official GROMACS. Details are found in the README & COPYING
  25  * files - if they are missing, get the official version at www.gromacs.org.
  26  *
  27  * To help us fund GROMACS development, we humbly ask that you cite
  28  * the papers on the package - you can find them in the top README file.
  29  *
  30  * For more info, check our website at http://www.gromacs.org
  31  *
  32  * And Hey:
  33  * Gromacs Runs On Most of All Computer Systems
  34  */
  35
  36 #ifndef _statutil_h
  37 #define _statutil_h
  38
  39 #ifdef HAVE_CONFIG_H
  40 #include <config.h>
  41 #endif
  42
  43
  44 #include <stdio.h>
  45 #include "typedefs.h"
  46 #include "filenm.h"
  47 #include "readinp.h"
  48 #include "wman.h"
  49 #include "pdbio.h"
  50 #include "oenv.h"
  51 #include "gmxfio.h"
  52
  53
  54 #ifdef __cplusplus
  55 extern "C" {
  56 #endif
  57 #if 0 /* avoid screwing up indentation */
  58 }
  59 #endif
  60
  61
  62 /* The code below is to facilitate controlled begin and end of
  63  trajectory reading. Corresponding routines in
  64  src/gmxlib/tcontrol.c
  65  */
  66 enum { TBEGIN, TEND, TDELTA, TNR };
  67
  68 extern bool bTimeSet(int tcontrol);
  69
  70 extern real rTimeValue(int tcontrol);
  71
  72 extern void setTimeValue(int tcontrol,real value);
  73
  74 /* End trajectory time control */
  75
  76 /* a dedicated status type contains fp, etc. */
  77 typedef struct t_trxstatus t_trxstatus;
  78
  79 typedef int t_first_x(t_trxstatus **status,const char *fn,real *t,rvec **x,
  80                       matrix box);
  81
  82 typedef bool t_next_x(t_trxstatus *status,real *t,int natoms,rvec x[],
  83                       matrix box);
  84
  85 /* I/O function types */
  86
  87
  88 /* LEGACY FUNCTIONS
  89
  90    The program names, command lines, etc. are now also set in the output_env
  91    structure. That is now the preferred location, but the functions here
  92    are still available as legacy functions. Because they all act on inherently
  93    global informaion, their existence in a multi-threaded environment is not
  94    a real problem. */
  95
  96 /* Return the name of the program */
  97 extern const char *command_line(void);
  98 extern void set_command_line(int argc, char *argv[]);
  99
 100 /* set the program name to the provided string, but note
 101  * that it must be a real file - we determine the library
 102  * directory from its location!
 103  */
 104 extern const char *Program(void);
 105 extern void set_program_name(const char *argvzero);
 106 /* Id. without leading directory */
 107 extern const char *ShortProgram(void);
 108
 109 /************************************************
 110  *             Trajectory functions
 111  ************************************************/
 112
 113 extern int prec2ndec(real prec);
 114 /* Convert precision in 1/(nm) to number of decimal places */
 115
 116 extern void clear_trxframe(t_trxframe *fr,bool bFirst);
 117 /* Set all content booleans to FALSE.
 118  * When bFirst = TRUE, set natoms=-1, all pointers to NULL
 119  *                     and all data to zero.
 120  */
 121
 122 extern void set_trxframe_ePBC(t_trxframe *fr,int ePBC);
 123 /* Set the type of periodic boundary conditions, ePBC=-1 is not set */
 124
 125 extern int nframes_read(t_trxstatus *status);
 126 /* Returns the number of frames read from the trajectory */
 127
 128 int write_trxframe_indexed(t_trxstatus *status,t_trxframe *fr,int nind,
 129                            atom_id *ind, gmx_conect gc);
 130 /* Write an indexed frame to a TRX file, see write_trxframe. gc may be NULL */
 131
 132 int write_trxframe(t_trxstatus *status,t_trxframe *fr,gmx_conect gc);
 133 /* Write a frame to a TRX file.
 134  * Only entries for which the boolean is TRUE will be written,
 135  * except for step, time, lambda and/or box, which may not be
 136  * omitted for certain trajectory formats.
 137  * The precision for .xtc and .gro is fr->prec, when fr->bPrec=FALSE,
 138  * the precision is set to 1000.
 139  * gc is important for pdb file writing only and may be NULL.
 140  */
 141
 142 int write_trx(t_trxstatus *status,int nind,atom_id *ind,t_atoms *atoms,
 143               int step,real time,matrix box,rvec x[],rvec *v,
 144               gmx_conect gc);
 145 /* Write an indexed frame to a TRX file.
 146  * v can be NULL.
 147  * atoms can be NULL for file types which don't need atom names.
 148  */
 149
 150 void close_trx(t_trxstatus *status);
 151 /* Close trj file as opened with read_first_x, read_frist_frame
 152  * or open_trx. Identical to close_trj.
 153  */
 154
 155 t_trxstatus *open_trx(const char *outfile,const char *filemode);
 156 /* Open a TRX file and return an allocated status pointer */
 157
 158 /* get a fileio from a trxstatus */
 159 t_fileio *trx_get_fileio(t_trxstatus *status);
 160
 161
 162 extern bool bRmod_fd(double a, double b, double c,bool bDouble);
 163 /* Returns TRUE when (a - b) MOD c = 0, using a margin which is slightly
 164  * larger than the float/double precision.
 165  */
 166
 167 #ifdef GMX_DOUBLE
 168 #define bRmod(a,b,c) bRmod_fd(a,b,c,TRUE)
 169 #else
 170 #define bRmod(a,b,c) bRmod_fd(a,b,c,FALSE)
 171 #endif
 172
 173 extern int check_times2(real t,real t0,real tp,real tpp,bool bDouble);
 174 /* This routine checkes if the read-in time is correct or not;
 175  * returns -1 if t<tbegin or t MOD dt = t0,
 176  *          0 if tbegin <= t <=tend+margin,
 177  *          1 if t>tend
 178  * where margin is 0.1*min(t-tp,tp-tpp), if this positive, 0 otherwise.
 179  * tp and tpp should be the time of the previous frame and the one before.
 180  * The mod is done with single or double precision accuracy depending
 181  * on the value of bDouble.
 182  */
 183
 184 extern int check_times(real t);
 185 /* This routine checkes if the read-in time is correct or not;
 186  * returns -1 if t<tbegin,
 187  *          0 if tbegin <= t <=tend,
 188  *          1 if t>tend
 189  */
 190
 191
 192
 193
 194
 195 /* For trxframe.flags, used in trxframe read routines.
 196  * When a READ flag is set, the field will be read when present,
 197  * but a frame might be returned which does not contain the field.
 198  * When a NEED flag is set, frames not containing the field will be skipped.
 199  */
 200 #define TRX_READ_X    (1<<0)
 201 #define TRX_NEED_X    (1<<1)
 202 #define TRX_READ_V    (1<<2)
 203 #define TRX_NEED_V    (1<<3)
 204 #define TRX_READ_F    (1<<4)
 205 #define TRX_NEED_F    (1<<5)
 206 /* Useful for reading natoms from a trajectory without skipping */
 207 #define TRX_DONT_SKIP (1<<6)
 208
 209 /* For trxframe.not_ok */
 210 #define HEADER_NOT_OK (1<<0)
 211 #define DATA_NOT_OK   (1<<1)
 212 #define FRAME_NOT_OK  (HEADER_NOT_OK | DATA_NOT_OK)
 213
 214 extern int read_first_frame(const output_env_t oenv,t_trxstatus **status,
 215                             const char *fn, t_trxframe *fr,int flags);
 216   /* Read the first frame which is in accordance with flags, which are
 217    * defined further up in this file.
 218    * Returns natoms when succeeded, 0 otherwise.
 219    * Memory will be allocated for flagged entries.
 220    * The flags are copied to fr for subsequent calls to read_next_frame.
 221    * Returns TRUE when succeeded, FALSE otherwise.
 222    */
 223
 224 extern bool read_next_frame(const output_env_t oenv,t_trxstatus *status,
 225                             t_trxframe *fr);
 226   /* Reads the next frame which is in accordance with fr->flags.
 227    * Returns TRUE when succeeded, FALSE otherwise.
 228    */
 229
 230 extern int read_first_x(const output_env_t oenv,t_trxstatus **status,
 231                         const char *fn, real *t,rvec **x,matrix box);
 232 /* These routines read first coordinates and box, and allocates
 233  * memory for the coordinates, for a trajectory file.
 234  * The routine returns the number of atoms, or 0 when something is wrong.
 235  * The integer in status should be passed to calls of read_next_x
 236  */
 237
 238 extern bool read_next_x(const output_env_t oenv,t_trxstatus *status,real *t,
 239                         int natoms, rvec x[],matrix box);
 240 /* Read coordinates and box from a trajectory file. Return TRUE when all well,
 241  * or FALSE when end of file (or last frame requested by user).
 242  * status is the integer set in read_first_x.
 243  */
 244
 245 extern void close_trj(t_trxstatus *status);
 246 /* Close trj file as opened with read_first_x, read_frist_frame
 247  * or open_trx. Identical to close_trx.
 248  */
 249
 250 extern void rewind_trj(t_trxstatus *status);
 251 /* Rewind trj file as opened with read_first_x */
 252
 253 extern t_topology *read_top(const char *fn,int *ePBC);
 254 /* Extract a topology data structure from a topology file.
 255  * If ePBC!=NULL *ePBC gives the pbc type.
 256  */
 257
 258 /*****************************************************
 259  *         Some command line parsing routines
 260  *****************************************************/
 261
 262 #define PCA_CAN_VIEW       (1<<5)
 263 /* add option -w to view output files (must be implemented in program) */
 264 #define PCA_CAN_BEGIN      (1<<6)
 265 #define PCA_CAN_END        (1<<7)
 266 #define PCA_CAN_DT         (1<<14)
 267 #define PCA_CAN_TIME       (PCA_CAN_BEGIN | PCA_CAN_END | PCA_CAN_DT)
 268 /* adds options -b and -e for begin and end time for reading trajectories */
 269 #define PCA_TIME_UNIT      (1<<15)
 270 /* set time unit for output */
 271 #define PCA_KEEP_ARGS      (1<<8)
 272 /* keep parsed args in argv (doesn't make sense without NOEXIT_ON_ARGS) */
 273 #define PCA_SILENT         (1<<9)
 274 /* don't print options by default */
 275 #define PCA_CAN_SET_DEFFNM (1<<10)
 276 /* does something for non-master mdrun nodes */
 277 #define PCA_NOEXIT_ON_ARGS (1<<11)
 278 /* no fatal_error when invalid options are encountered */
 279 #define PCA_QUIET          (1<<12)
 280 /* does something for non-master mdrun nodes */
 281 #define PCA_BE_NICE        (1<<13)
 282 /* Default to low priority, unless configured with --disable-nice */
 283 #define PCA_NOT_READ_NODE  (1<<16)
 284 /* Is this node not reading: for parallel all nodes but the master */
 285
 286 extern int iscan(int argc,char *argv[],int *i);
 287 /* Scan an int from the argument at *i. If the argument length
 288  * is > 2, the int is assumed to be in the remainder of the arg,
 289  * eg: -p32, else the int is assumed to be in the next argument
 290  * eg: -p 32. If neither is the case the routine exits with an error,
 291  * otherwise it returns the value found. If the value is in the next
 292  * argument *i is incremented. You typically would want to pass
 293  * a loop variable to this routine.
 294  */
 295 extern gmx_large_int_t istepscan(int argc,char *argv[],int *i);
 296 /* Same as above, but for large integer values */
 297
 298 extern double dscan(int argc,char *argv[],int *i);
 299 /* Routine similar to the above, but working on doubles. */
 300
 301 extern char *sscan(int argc,char *argv[],int *i);
 302 /* Routine similar to the above, but working on strings. The pointer
 303  * returned is a pointer to the argv field.
 304  */
 305
 306 extern void vscan(int argc,char *argv[],int *i,rvec *vec);
 307 /* Routine similar to the above, but working on rvecs. */
 308
 309 extern int nenum(const char *const enumc[]);
 310 /* returns ordinal number of selected enum from args
 311  * depends on enumc[0] pointing to one of the other elements
 312  * array must be terminated by a NULL pointer
 313  */
 314
 315 extern void parse_common_args(int *argc,char *argv[],unsigned long Flags,
 316                               int nfile,t_filenm fnm[],int npargs,t_pargs *pa,
 317                               int ndesc,const char **desc,
 318                               int nbugs,const char **bugs,
 319                               output_env_t *oenv);
 320 /* Get arguments from the arg-list. The arguments extracted
 321  * are removed from the list. If manual is NULL a default message is displayed
 322  * when errors are encountered. The Flags argument, when non-0 enables
 323  * some input checks. Using this routine also means that the arguments
 324  * -b and -e will be used for begin and end time, whether this is
 325  * appropriate or not!
 326  */
 327
 328 #ifdef __cplusplus
 329 }
 330 #endif
 331
 332 #endif