/usr/include/gromacs/random/tabulatednormaldistribution.h is in libgromacs-dev 2016.1-2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 | /*
* This file is part of the GROMACS molecular simulation package.
*
* Copyright (c) 2015,2016, by the GROMACS development team, led by
* Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl,
* and including many others, as listed in the AUTHORS file in the
* top-level source directory and at http://www.gromacs.org.
*
* GROMACS is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public License
* as published by the Free Software Foundation; either version 2.1
* of the License, or (at your option) any later version.
*
* GROMACS is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with GROMACS; if not, see
* http://www.gnu.org/licenses, or write to the Free Software Foundation,
* Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
*
* If you want to redistribute modifications to GROMACS, please
* consider that scientific software is very special. Version
* control is crucial - bugs must be traceable. We will be happy to
* consider code for inclusion in the official distribution, but
* derived work must not be called official GROMACS. Details are found
* in the README & COPYING files - if they are missing, get the
* official version at http://www.gromacs.org.
*
* To help us fund GROMACS development, we humbly ask that you cite
* the research papers on the package. Check out http://www.gromacs.org.
*/
/*! \file
* \brief Tabulated normal distribution
*
* A very fast normal distribution, but with limited resolution.
*
* \author Erik Lindahl <erik.lindahl@gmail.com>
* \inpublicapi
* \ingroup module_random
*/
#ifndef GMX_RANDOM_TABULATEDNORMALDISTRIBUTION_H
#define GMX_RANDOM_TABULATEDNORMALDISTRIBUTION_H
#include <cmath>
#include <limits>
#include <vector>
#include "gromacs/math/functions.h"
#include "gromacs/math/utilities.h"
#include "gromacs/utility/basedefinitions.h"
#include "gromacs/utility/classhelpers.h"
#include "gromacs/utility/gmxassert.h"
#include "gromacs/utility/real.h"
namespace gmx
{
namespace
{
//! Number of bits that determines the resolution of the lookup table for the normal distribution.
const int c_TabulatedNormalDistributionDefaultBits = 14;
}
/*! \brief Tabulated normal random distribution
*
* Random distribution compatible with C++11 distributions - it can be
* used with any C++11 random engine.
*
* \tparam RealType Type of the return value. Float or double. Note that
* GROMACS uses "real" type by default in contrast to the C++11
* standard library, to avoid double/float conversions.
* \tparam tableBits Size of the table, specified in bits. The storage
* space required is sizeof(RealType)*2^tableBits. To
* keep things sane this is limited to 24 bits.
*
* Some stochastic integrators depend on drawing a lot of normal
* distribution random numbers quickly, but in many cases the only
* important property is the distribution - given the noise in forces
* we do not need very high resolution.
* This distribution uses an internal table to return samples from a
* normal distribution with limited resolution. By default the table
* uses c_TabulatedNormalDistributionDefaultBits bits, but this is
* specified with a template parameter.
*
* Since this distribution only uses tableBits bits per value generated,
* the values draw from the random engine are used for several results.
* To make sure you get a reproducible result when using counter-based
* random engines (such as ThreeFry2x64), remember to call the reset()
* method to cancel the internal memory of the distribution.
*
* \note For modern NUMA systems, you likely want to use separate
* distributions for each thread, and make sure they are initialized
* on the CPU where they will run, so the table is placed in that
* NUMA memory pool.
* \note The finite table resolution means this distribution will NOT
* return arbitrarily small/large values, but with e.g. 14 bits
* the results are limited to roughly +/- 4 standard deviations.
*/
template<class RealType = real, unsigned int tableBits = c_TabulatedNormalDistributionDefaultBits>
class TabulatedNormalDistribution
{
static_assert(tableBits <= 24, "Normal distribution table is limited to 24bits (64MB in single precision)");
public:
/*! \brief Type of normal distribution results */
typedef RealType result_type;
/*! \brief Normal distribution parameter class (mean and stddev) */
class param_type
{
public:
/*! \brief The type of distribution the parameters describe */
typedef TabulatedNormalDistribution distribution_type;
/*! \brief Constructor. Default is classical distr. with mean 0, stddev 1.
*
* \param mean Expectation value.
* \param stddev Standard deviation.
*
*/
explicit param_type(result_type mean = 0.0, result_type stddev = 1.0)
: mean_(mean), stddev_(stddev) {}
/*! \brief Return mean parameter of normal distribution */
result_type
mean() const { return mean_; }
/*! \brief Return standard deviation parameter of normal distribution */
result_type
stddev() const { return stddev_; }
/*! \brief True if two sets of normal distributions parameters are identical
*
* \param x Instance to compare with.
*/
bool
operator==(const param_type &x) const
{
return (mean_ == x.mean_ && stddev_ == x.stddev_);
}
/*! \brief True if two sets of normal distributions parameters are different.
*
* \param x Instance to compare with.
*/
bool
operator!=(const param_type &x) const { return !operator==(x); }
private:
/*! \brief Internal storage for mean of normal distribution */
result_type mean_;
/*! \brief Internal storage for standard deviation of normal distribution */
result_type stddev_;
};
/*! \brief Fill the table with values for the normal distribution
*
* This routine returns a new a std::vector with the table data.
*
* This routine is used to help construct objects of this class,
* and is exposed only to permit testing. Normal code should not
* need to call this function.
*/
static const
std::vector<RealType>
// cppcheck-suppress unusedPrivateFunction
makeTable()
{
/* Fill the table with the integral of a gaussian distribution, which
* corresponds to the inverse error function.
* We avoid integrating a gaussian numerically, since that leads to
* some loss-of-precision which also accumulates so it is worse for
* larger indices in the table. */
std::size_t tableSize = 1 << tableBits;
std::size_t halfSize = tableSize/2;
double invHalfSize = 1.0/halfSize;
std::vector<RealType> table(tableSize);
// Fill in all but the extremal entries of the table
for (std::size_t i = 0; i < halfSize-1; i++)
{
double r = (i + 0.5) * invHalfSize;
double x = std::sqrt(2.0) * erfinv(r);
table.at(halfSize-1-i) = -x;
table.at(halfSize+i) = x;
}
// We want to fill in the extremal table entries with
// values that make the total variance equal to 1, so
// measure the variance by summing the squares of the
// other values of the distribution, starting from the
// smallest values.
double sumOfSquares = 0;
for (std::size_t i = 1; i < halfSize; i++)
{
double value = table.at(i);
sumOfSquares += value * value;
}
double missingVariance = 1.0 - 2.0*sumOfSquares/tableSize;
GMX_RELEASE_ASSERT(missingVariance > 0, "Incorrect computation of tabulated normal distribution");
double extremalValue = std::sqrt(0.5*missingVariance*tableSize);
table.at(0) = -extremalValue;
table.back() = extremalValue;
return table;
}
public:
/*! \brief Construct new normal distribution with specified mean & stdddev.
*
* \param mean Mean value of tabulated normal distribution
* \param stddev Standard deviation of tabulated normal distribution
*/
explicit TabulatedNormalDistribution(result_type mean = 0.0, result_type stddev = 1.0 )
: param_(param_type(mean, stddev)), savedRandomBits_(0), savedRandomBitsLeft_(0)
{
}
/*! \brief Construct new normal distribution from parameter type.
*
* \param param Parameter class containing mean and standard deviation.
*/
explicit TabulatedNormalDistribution( const param_type ¶m )
: param_(param), savedRandomBits_(0), savedRandomBitsLeft_(0)
{
}
/*! \brief Smallest value that can be generated in normal distrubiton.
*
* \note The smallest value is not -infinity with a table, but it
* depends on the table resolution. With 14 bits, this is roughly
* four standard deviations below the mean.
*/
result_type
min() const
{
return c_table_[0];
}
/*! \brief Largest value that can be generated in normal distribution.
*
* \note The largest value is not infinity with a table, but it
* depends on the table resolution. With 14 bits, this is roughly
* four standard deviations above the mean.
*/
result_type
max() const
{
return c_table_[c_table_.size()-1];
}
/*! \brief Mean of the present normal distribution */
result_type
mean() const
{
return param_.mean();
}
/*! \brief Standard deviation of the present normal distribution */
result_type
stddev() const
{
return param_.stddev();
}
/*! \brief The parameter class (mean & stddev) of the normal distribution */
param_type
param() const
{
return param_;
}
/*! \brief Clear all internal saved random bits from the random engine */
void
reset()
{
savedRandomBitsLeft_ = 0;
}
/*! \brief Return normal distribution value specified by internal parameters.
*
* \tparam Rng Random engine type used to provide uniform random bits.
* \param g Random engine of class Rng. For normal GROMACS usage
* you likely want to use ThreeFry2x64.
*/
template<class Rng>
result_type
operator()(Rng &g)
{
return (*this)(g, param_);
}
/*! \brief Return normal distribution value specified by given parameters
*
* \tparam Rng Random engine type used to provide uniform random bits.
* \param g Random engine of class Rng. For normal GROMACS usage
* you likely want to use ThreeFry2x64.
* \param param Parameters used to specify normal distribution.
*/
template<class Rng>
result_type
operator()(Rng &g, const param_type ¶m)
{
if (savedRandomBitsLeft_ < tableBits)
{
// We do not know whether the generator g returns 64 or 32 bits,
// since g is not known when we construct this class.
// To keep things simple, we always draw one random number,
// store it in our 64-bit value, and set the number of active bits.
// For tableBits up to 16 this will be as efficient both with 32
// and 64 bit random engines when drawing multiple numbers
// (our default value is
// c_TabulatedNormalDistributionDefaultBits == 14). It
// also avoids drawing multiple 32-bit random numbers
// even if we just call this routine for a single
// result.
savedRandomBits_ = static_cast<gmx_uint64_t>(g());
savedRandomBitsLeft_ = std::numeric_limits<typename Rng::result_type>::digits;
}
result_type value = c_table_[savedRandomBits_ & ( (1ULL << tableBits) - 1 ) ];
savedRandomBits_ >>= tableBits;
savedRandomBitsLeft_ -= tableBits;
return param.mean() + value * param.stddev();
}
/*!\brief Check if two tabulated normal distributions have identical states.
*
* \param x Instance to compare with.
*/
bool
operator==(const TabulatedNormalDistribution<RealType, tableBits> &x) const
{
return (param_ == x.param_ &&
savedRandomBits_ == x.savedRandomBits_ &&
savedRandomBitsLeft_ == x.savedRandomBitsLeft_);
}
/*!\brief Check if two tabulated normal distributions have different states.
*
* \param x Instance to compare with.
*/
bool
operator!=(const TabulatedNormalDistribution<RealType, tableBits> &x) const
{
return !operator==(x);
}
private:
/*! \brief Parameters of normal distribution (mean and stddev) */
param_type param_;
/*! \brief Array with tabluated values of normal distribution */
static const std::vector<RealType> c_table_;
/*! \brief Saved output from random engine, shifted tableBits right each time */
gmx_uint64_t savedRandomBits_;
/*! \brief Number of valid bits remaining i savedRandomBits_ */
unsigned int savedRandomBitsLeft_;
GMX_DISALLOW_COPY_AND_ASSIGN(TabulatedNormalDistribution);
};
// MSVC does not handle extern template class members correctly even in MSVC 2015,
// so in that case we have to instantiate in every object using it. In addition,
// doxygen is convinced this defines a function (which leads to crashes in our python
// scripts), so to avoid confusion we hide it from doxygen too.
#if !defined(_MSC_VER) && !defined(DOXYGEN)
// Declaration of template specialization
template<>
const std::vector<real> TabulatedNormalDistribution<real, c_TabulatedNormalDistributionDefaultBits>::c_table_;
extern template
const std::vector<real> TabulatedNormalDistribution<real, c_TabulatedNormalDistributionDefaultBits>::c_table_;
#endif
// Instantiation for all tables without specialization
template<class RealType, unsigned int tableBits>
const std::vector<RealType> TabulatedNormalDistribution<RealType, tableBits>::c_table_ = TabulatedNormalDistribution<RealType, tableBits>::makeTable();
} // namespace gmx
#endif // GMX_RANDOM_TABULATEDNORMALDISTRIBUTION_H
|