Merge branch 'master' of git://git.gromacs.org/gromacs
[gromacs/adressmacs.git] / include / histogram.h
blobdd751685f693b5214de708d134ec49ee5fa03a28
1 /*
3 * This source code is part of
5 * G R O M A C S
7 * GROningen MAchine for Chemical Simulations
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.
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.
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.
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.
29 * For more info, check our website at http://www.gromacs.org
31 /*! \file
32 * \brief API for calculation of histograms with error estimates.
34 * The API is documented in more detail on a separate page:
35 * \ref histograms
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.
41 #ifndef HISTOGRAM_H
42 #define HISTOGRAM_H
44 #include "typedefs.h"
46 #ifdef __cplusplus
47 extern "C"
49 #endif
51 /** Type of histogram. */
52 typedef enum
54 /*! \brief
55 * Simple histogram.
57 * Use gmx_histogram_increment() or gmx_histogram_increment_bin()
58 * to sample.
60 HIST_SIMPLE,
61 /*! \brief
62 * Weighted histogram where different points contribute different amounts.
64 * Use gmx_histogram_add() or gmx_histogram_add_to_bin() to sample.
66 HIST_WEIGHT,
67 /*! \brief
68 * Calculate averages within each bin.
70 * Use gmx_histogram_add_item() or gmx_histogram_add_item_to_bin() to sample.
72 HIST_BINAVER
73 } e_histogram_t;
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
82 /** Stores data for a histogram. */
83 typedef struct gmx_histogram_t gmx_histogram_t;
85 /*! \name Initialization functions
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. */
103 gmx_histogram_set_binwidth(gmx_histogram_t *h, real start, real binw);
104 /** Sets histogram range using endpoint values. */
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. */
115 gmx_histogram_set_blocksize(gmx_histogram_t *h, int bsize);
116 /** Sets output file for block histograms. */
118 gmx_histogram_set_block_output(gmx_histogram_t *h, FILE *fp);
119 /*@}*/
121 /*! \name Access functions
123 /*@{*/
124 /** Finds the histogram bin corresponding to a value. */
126 gmx_histogram_find_bin(gmx_histogram_t *h, real pos);
127 /** Returns the number of bins in a histogram. */
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 /*@}*/
147 /*! \name Sampling functions
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);
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);
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);
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 /*@}*/
180 /*! \name Post-processing functions
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 /*@}*/
212 #ifdef __cplusplus
214 #endif
216 #endif