include/histogram.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  * Written by David van der Spoel, Erik Lindahl, Berk Hess, and others.
  10  * Copyright (c) 1991-2000, University of Groningen, The Netherlands.
  11  * Copyright (c) 2001-2009, The GROMACS development team,
  12  * check out http://www.gromacs.org for more information.
  13
  14  * This program is free software; you can redistribute it and/or
  15  * modify it under the terms of the GNU General Public License
  16  * as published by the Free Software Foundation; either version 2
  17  * of the License, or (at your option) any later version.
  18  *
  19  * If you want to redistribute modifications, please consider that
  20  * scientific software is very special. Version control is crucial -
  21  * bugs must be traceable. We will be happy to consider code for
  22  * inclusion in the official distribution, but derived work must not
  23  * be called official GROMACS. Details are found in the README & COPYING
  24  * files - if they are missing, get the official version at www.gromacs.org.
  25  *
  26  * To help us fund GROMACS development, we humbly ask that you cite
  27  * the papers on the package - you can find them in the top README file.
  28  *
  29  * For more info, check our website at http://www.gromacs.org
  30  */
  31 /*! \file
  32  * \brief API for calculation of histograms with error estimates.
  33  *
  34  * The API is documented in more detail on a separate page:
  35  * \ref histograms
  36  *
  37  * The functions within this file can be used and developed independently of
  38  * the other parts of the library.
  39  * Other parts of the library do not reference these functions.
  40  */
  41 #ifndef HISTOGRAM_H
  42 #define HISTOGRAM_H
  43
  44 #include "typedefs.h"
  45
  46 #ifdef __cplusplus
  47 extern "C"
  48 {
  49 #endif
  50
  51 /** Type of histogram. */
  52 typedef enum
  53 {
  54     /*! \brief
  55      * Simple histogram.
  56      *
  57      * Use gmx_histogram_increment() or gmx_histogram_increment_bin()
  58      * to sample.
  59      */
  60     HIST_SIMPLE,
  61     /*! \brief
  62      * Weighted histogram where different points contribute different amounts.
  63      *
  64      * Use gmx_histogram_add() or gmx_histogram_add_to_bin() to sample.
  65      */
  66     HIST_WEIGHT,
  67     /*! \brief
  68      * Calculate averages within each bin.
  69      *
  70      * Use gmx_histogram_add_item() or gmx_histogram_add_item_to_bin() to sample.
  71      */
  72     HIST_BINAVER
  73 } e_histogram_t;
  74
  75 /** Whether bins are centered at integer values. */
  76 #define HIST_INTEGERBINS  1
  77 /** Whether the values outside the range should be included in the histogram. */
  78 #define HIST_ALL          2
  79 /** Whether the initialization used binwidths. */
  80 #define HIST_INITBW       128
  81
  82 /** Stores data for a histogram. */
  83 typedef struct gmx_histogram_t gmx_histogram_t;
  84
  85 /*! \name Initialization functions
  86  */
  87 /*@{*/
  88 /** Initialize calculation of a histogram. */
  89 int
  90 gmx_histogram_create(gmx_histogram_t **h, e_histogram_t type, int nbins);
  91 /** Initialize calculation of a histogram for a range. */
  92 int
  93 gmx_histogram_create_range(gmx_histogram_t **h, e_histogram_t type,
  94                            real start, real end, real binw, gmx_bool bIntegerBins);
  95 /** Clears the bins in the histogram. */
  96 void
  97 gmx_histogram_clear(gmx_histogram_t *h);
  98 /** Frees the memory allocated for a histogram. */
  99 void
 100 gmx_histogram_free(gmx_histogram_t *h);
 101 /** Sets histogram range using a starting point and a bin width. */
 102 int
 103 gmx_histogram_set_binwidth(gmx_histogram_t *h, real start, real binw);
 104 /** Sets histogram range using endpoint values. */
 105 int
 106 gmx_histogram_set_range(gmx_histogram_t *h, real start, real end);
 107 /** Sets histogram bins to center at integer values. */
 108 void
 109 gmx_histogram_set_integerbins(gmx_histogram_t *h, gmx_bool bIntegerBins);
 110 /** Sets histogram to include outlying values in the bins at the edges. */
 111 void
 112 gmx_histogram_set_all(gmx_histogram_t *h, gmx_bool bAll);
 113 /** Sets block size for histogram averaging. */
 114 int
 115 gmx_histogram_set_blocksize(gmx_histogram_t *h, int bsize);
 116 /** Sets output file for block histograms. */
 117 int
 118 gmx_histogram_set_block_output(gmx_histogram_t *h, FILE *fp);
 119 /*@}*/
 120
 121 /*! \name Access functions
 122  */
 123 /*@{*/
 124 /** Finds the histogram bin corresponding to a value. */
 125 int
 126 gmx_histogram_find_bin(gmx_histogram_t *h, real pos);
 127 /** Returns the number of bins in a histogram. */
 128 int
 129 gmx_histogram_get_nbins(gmx_histogram_t *h);
 130 /** Returns the bin width of a histogram. */
 131 real
 132 gmx_histogram_get_binwidth(gmx_histogram_t *h);
 133 /** Returns the value of the histogram at a certain position. */
 134 void
 135 gmx_histogram_get_value(gmx_histogram_t *h, real pos, double *val, double *err);
 136 /** Returns the value of the histogram in a certain bin. */
 137 void
 138 gmx_histogram_get_bin_value(gmx_histogram_t *h, int bin, double *val, double *err);
 139 /** Returns an array of values for the histogram. */
 140 double *
 141 gmx_histogram_get_values(gmx_histogram_t *h);
 142 /** Returns an array of error values for the histogram. */
 143 double *
 144 gmx_histogram_get_errors(gmx_histogram_t *h);
 145 /*@}*/
 146
 147 /*! \name Sampling functions
 148  */
 149 /*@{*/
 150 /** Increments the count in a histogram bin corresponding to \p pos. */
 151 void
 152 gmx_histogram_increment(gmx_histogram_t *h, real pos);
 153 /** Increments the count in a histogram bin. */
 154 void
 155 gmx_histogram_increment_bin(gmx_histogram_t *h, int bin);
 156
 157 /** Adds a value to a histogram bin corresponding to \p pos. */
 158 void
 159 gmx_histogram_add(gmx_histogram_t *h, real pos, double value);
 160 /** Adds a value to a histogram bin. */
 161 void
 162 gmx_histogram_add_to_bin(gmx_histogram_t *h, int bin, double value);
 163
 164 /** Adds a value to a histogram bin corresponding to \p pos. */
 165 void
 166 gmx_histogram_add_item(gmx_histogram_t *h, real pos, double value);
 167 /** Adds a value to a histogram bin. */
 168 void
 169 gmx_histogram_add_item_to_bin(gmx_histogram_t *h, int bin, double value);
 170
 171 /** Finishes histogram sampling for a frame. */
 172 void
 173 gmx_histogram_finish_frame(gmx_histogram_t *h);
 174 /** Normalizes a histogram. */
 175 void
 176 gmx_histogram_finish(gmx_histogram_t *h);
 177 /*@}*/
 178
 179
 180 /*! \name Post-processing functions
 181  */
 182 /*@{*/
 183 /** Creates a new histogram with double the binwidth. */
 184 void
 185 gmx_histogram_resample_dblbw(gmx_histogram_t **dest, gmx_histogram_t *src,
 186                              gmx_bool bIntegerBins);
 187 /** Makes a clone of a histogram. */
 188 void
 189 gmx_histogram_clone(gmx_histogram_t **dest, gmx_histogram_t *src);
 190 /** Normalizes a histogram to a probability distribution. */
 191 void
 192 gmx_histogram_normalize_prob(gmx_histogram_t *h);
 193 /** Scales a histogram with a custom normalization factor. */
 194 void
 195 gmx_histogram_scale(gmx_histogram_t *h, real norm);
 196 /** Scales a histogram with a custom non-uniform normalization factor. */
 197 void
 198 gmx_histogram_scale_vec(gmx_histogram_t *h, real norm[]);
 199 /** Writes a single histogram to a file. */
 200 void
 201 gmx_histogram_write(FILE *fp, gmx_histogram_t *h, gmx_bool bErrors);
 202 /** Writes a set of histograms to a file. */
 203 void
 204 gmx_histogram_write_array(FILE *fp, int n, gmx_histogram_t *h[],
 205                               gmx_bool bValue, gmx_bool bErrors);
 206 /** Writes a set of cumulative histograms to a file. */
 207 void
 208 gmx_histogram_write_cum_array(FILE *fp, int n, gmx_histogram_t *h[],
 209                               gmx_bool bValue, gmx_bool bErrors);
 210 /*@}*/
 211
 212 #ifdef __cplusplus
 213 }
 214 #endif
 215
 216 #endif