include/statutil.h

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