2 * This file is part of the GROMACS molecular simulation package.
4 * Copyright (c) 2015,2016,2017,2018, by the GROMACS development team, led by
5 * Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl,
6 * and including many others, as listed in the AUTHORS file in the
7 * top-level source directory and at http://www.gromacs.org.
9 * GROMACS is free software; you can redistribute it and/or
10 * modify it under the terms of the GNU Lesser General Public License
11 * as published by the Free Software Foundation; either version 2.1
12 * of the License, or (at your option) any later version.
14 * GROMACS is distributed in the hope that it will be useful,
15 * but WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
17 * Lesser General Public License for more details.
19 * You should have received a copy of the GNU Lesser General Public
20 * License along with GROMACS; if not, see
21 * http://www.gnu.org/licenses, or write to the Free Software Foundation,
22 * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
24 * If you want to redistribute modifications to GROMACS, please
25 * consider that scientific software is very special. Version
26 * control is crucial - bugs must be traceable. We will be happy to
27 * consider code for inclusion in the official distribution, but
28 * derived work must not be called official GROMACS. Details are found
29 * in the README & COPYING files - if they are missing, get the
30 * official version at http://www.gromacs.org.
32 * To help us fund GROMACS development, we humbly ask that you cite
33 * the research papers on the package. Check out http://www.gromacs.org.
38 * Implements functions in grid.h.
40 * \author Viveca Lindahl
41 * \author Berk Hess <hess@kth.se>
55 #include "gromacs/math/functions.h"
56 #include "gromacs/math/utilities.h"
57 #include "gromacs/mdtypes/awh-params.h"
58 #include "gromacs/utility/cstringutil.h"
59 #include "gromacs/utility/exceptions.h"
60 #include "gromacs/utility/gmxassert.h"
61 #include "gromacs/utility/smalloc.h"
62 #include "gromacs/utility/stringutil.h"
71 * Modify x so that it is periodic in [-period/2, +period/2).
73 * x is modified by shifting its value by a +/- a period if
74 * needed. Thus, it is assumed that x is at most one period
75 * away from this interval. For period = 0, x is not modified.
77 * \param[in,out] x Pointer to the value to modify.
78 * \param[in] period The period, or 0 if not periodic.
80 void centerPeriodicValueAroundZero(double *x,
83 GMX_ASSERT(period >= 0, "Periodic should not be negative");
85 const double halfPeriod = period*0.5;
91 else if (*x < -halfPeriod)
98 * If period>0, retrun x so that it is periodic in [0, period), else return x.
100 * Return x is shifted its value by a +/- a period, if
101 * needed. Thus, it is assumed that x is at most one period
102 * away from this interval. For this domain and period > 0
103 * this is equivalent to x = x % period. For period = 0,
106 * \param[in,out] x Pointer to the value to modify, should be >= 0.
107 * \param[in] period The period, or 0 if not periodic.
108 * \returns for period>0: index value witin [0, period), otherwise: \p x.
110 int indexWithinPeriod(int x,
113 GMX_ASSERT(period >= 0, "Periodic should not be negative");
120 GMX_ASSERT(x > -period && x < 2*period, "x should not be more shifted by more than one period");
137 * Get the length of the interval (origin, end).
139 * This returns the distance obtained by connecting the origin point to
140 * the end point in the positive direction. Note that this is generally
141 * not the shortest distance. For period > 0, both origin and
142 * end are expected to take values in the same periodic interval,
143 * ie. |origin - end| < period.
145 * \param[in] origin Start value of the interval.
146 * \param[in] end End value of the interval.
147 * \param[in] period The period, or 0 if not periodic.
148 * \returns the interval length from origin to end.
150 double getIntervalLengthPeriodic(double origin,
154 double length = end - origin;
157 /* The interval wraps around the +/- boundary which has a discontinuous jump of -period. */
161 GMX_RELEASE_ASSERT(length >= 0, "Negative AWH grid axis length.");
162 GMX_RELEASE_ASSERT(period == 0 || length <= period, "Interval length longer than period.");
168 * Get the deviation x - x0.
170 * For period > 0, the deviation with minimum absolute value is returned,
171 * i.e. with a value in the interval [-period/2, +period/2).
172 * Also for period > 0, it is assumed that |x - x0| < period.
174 * \param[in] x From value.
175 * \param[in] x0 To value.
176 * \param[in] period The period, or 0 if not periodic.
177 * \returns the deviation from x to x0.
179 double getDeviationPeriodic(double x,
187 centerPeriodicValueAroundZero(&dev, period);
195 double getDeviationFromPointAlongGridAxis(const Grid &grid,
200 double coordValue = grid.point(pointIndex).coordValue[dimIndex];
202 return getDeviationPeriodic(value, coordValue, grid.axis(dimIndex).period());
205 void linearArrayIndexToMultiDim(int indexLinear, int numDimensions, const awh_ivec numPointsDim, awh_ivec indexMulti)
207 for (int d = 0; d < numDimensions; d++)
211 /* Workaround for bug in clang */
212 #ifndef __clang_analyzer__
213 for (int k = d + 1; k < numDimensions; k++)
215 stride *= numPointsDim[k];
219 indexMulti[d] = indexLinear/stride;
220 indexLinear -= indexMulti[d]*stride;
224 void linearGridindexToMultiDim(const Grid &grid,
228 awh_ivec numPointsDim;
229 const int numDimensions = grid.numDimensions();
230 for (int d = 0; d < numDimensions; d++)
232 numPointsDim[d] = grid.axis(d).numPoints();
235 linearArrayIndexToMultiDim(indexLinear, numDimensions, numPointsDim, indexMulti);
239 int multiDimArrayIndexToLinear(const awh_ivec indexMulti,
241 const awh_ivec numPointsDim)
245 for (int d = numDimensions - 1; d >= 0; d--)
247 indexLinear += stride*indexMulti[d];
248 stride *= numPointsDim[d];
257 /*! \brief Convert a multidimensional grid point index to a linear one.
259 * \param[in] axis The grid axes.
260 * \param[in] indexMulti Multidimensional grid point index to convert to a linear one.
261 * \returns the linear index.
263 int multiDimGridIndexToLinear(const std::vector<GridAxis> &axis,
264 const awh_ivec indexMulti)
266 awh_ivec numPointsDim = { 0 };
268 for (size_t d = 0; d < axis.size(); d++)
270 numPointsDim[d] = axis[d].numPoints();
273 return multiDimArrayIndexToLinear(indexMulti, axis.size(), numPointsDim);
278 int multiDimGridIndexToLinear(const Grid &grid,
279 const awh_ivec indexMulti)
281 return multiDimGridIndexToLinear(grid.axis(), indexMulti);
288 * Take a step in a multidimensional array.
290 * The multidimensional index gives the starting point to step from. Dimensions are
291 * stepped through in order of decreasing dimensional index such that the index is
292 * incremented in the highest dimension possible. If the starting point is the end
293 * of the array, a step cannot be taken and the index is not modified.
295 * \param[in] numDim Number of dimensions of the array.
296 * \param[in] numPoints Vector with the number of points along each dimension.
297 * \param[in,out] indexDim Multidimensional index, each with values in [0, numPoints[d] - 1].
298 * \returns true if a step was taken, false if not.
300 bool stepInMultiDimArray(int numDim,
301 const awh_ivec numPoints,
304 bool haveStepped = false;
306 for (int d = numDim - 1; d >= 0 && !haveStepped; d--)
308 if (indexDim[d] < numPoints[d] - 1)
310 /* Not at a boundary, just increase by 1. */
316 /* At a boundary. If we are not at the end of the array,
317 reset the index and check if we can step in higher dimensions */
329 * Transforms a grid point index to to the multidimensional index of a subgrid.
331 * The subgrid is defined by the location of its origin and the number of points
332 * along each dimension. The index transformation thus consists of a projection
333 * of the linear index onto each dimension, followed by a translation of the origin.
334 * The subgrid may have parts that don't overlap with the grid. E.g. the origin
335 * vector can have negative components meaning the origin lies outside of the grid.
336 * However, the given point needs to be both a grid and subgrid point.
338 * Periodic boundaries are taken care of by wrapping the subgrid around the grid.
339 * Thus, for periodic dimensions the number of subgrid points need to be less than
340 * the number of points in a period to prevent problems of wrapping around.
342 * \param[in] grid The grid.
343 * \param[in] subgridOrigin Vector locating the subgrid origin relative to the grid origin.
344 * \param[in] subgridNpoints The number of subgrid points in each dimension.
345 * \param[in] point Grid point to get subgrid index for.
346 * \param[in,out] subgridIndex Subgrid multidimensional index.
348 void gridToSubgridIndex(const Grid &grid,
349 const awh_ivec subgridOrigin,
350 const awh_ivec subgridNpoints,
352 awh_ivec subgridIndex)
354 /* Get the subgrid index of the given grid point, for each dimension. */
355 for (int d = 0; d < grid.numDimensions(); d++)
357 /* The multidimensional grid point index relative to the subgrid origin. */
359 indexWithinPeriod(grid.point(point).index[d] - subgridOrigin[d],
360 grid.axis(d).numPointsInPeriod());
362 /* The given point should be in the subgrid. */
363 GMX_RELEASE_ASSERT((subgridIndex[d] >= 0) && (subgridIndex[d] < subgridNpoints[d]),
364 "Attempted to convert an AWH grid point index not in subgrid to out of bounds subgrid index");
369 * Transform a multidimensional subgrid index to a grid point index.
371 * If the given subgrid point is not a grid point the transformation will not be successful
372 * and the grid point index will not be set. Periodic boundaries are taken care of by
373 * wrapping the subgrid around the grid.
375 * \param[in] grid The grid.
376 * \param[in] subgridOrigin Vector locating the subgrid origin relative to the grid origin.
377 * \param[in] subgridIndex Subgrid multidimensional index to get grid point index for.
378 * \param[in,out] gridIndex Grid point index.
379 * \returns true if the transformation was successful.
381 bool subgridToGridIndex(const Grid &grid,
382 const awh_ivec subgridOrigin,
383 const awh_ivec subgridIndex,
386 awh_ivec globalIndexDim;
388 /* Check and apply boundary conditions for each dimension */
389 for (int d = 0; d < grid.numDimensions(); d++)
391 /* Transform to global multidimensional indexing by adding the origin */
392 globalIndexDim[d] = subgridOrigin[d] + subgridIndex[d];
394 /* The local grid is allowed to stick out on the edges of the global grid. Here the boundary conditions are applied.*/
395 if (globalIndexDim[d] < 0 || globalIndexDim[d] > grid.axis(d).numPoints() - 1)
397 /* Try to wrap around if periodic. Otherwise, the transformation failed so return. */
398 if (!grid.axis(d).isPeriodic())
403 /* The grid might not contain a whole period. Can only wrap around if this gap is not too large. */
404 int gap = grid.axis(d).numPointsInPeriod() - grid.axis(d).numPoints();
408 if (globalIndexDim[d] < 0)
410 bridge = -globalIndexDim[d];
411 numWrapped = bridge - gap;
414 globalIndexDim[d] = grid.axis(d).numPoints() - numWrapped;
419 bridge = globalIndexDim[d] - (grid.axis(d).numPoints() - 1);
420 numWrapped = bridge - gap;
423 globalIndexDim[d] = numWrapped - 1;
434 /* Translate from multidimensional to linear indexing and set the return value */
435 (*gridIndex) = multiDimGridIndexToLinear(grid, globalIndexDim);
442 bool advancePointInSubgrid(const Grid &grid,
443 const awh_ivec subgridOrigin,
444 const awh_ivec subgridNumPoints,
447 /* Initialize the subgrid index to the subgrid origin. */
448 awh_ivec subgridIndex = { 0 };
450 /* Get the subgrid index of the given grid point index. */
451 if (*gridPointIndex >= 0)
453 gridToSubgridIndex(grid, subgridOrigin, subgridNumPoints, *gridPointIndex, subgridIndex);
457 /* If no grid point is given we start at the subgrid origin (which subgridIndex is initialized to).
458 If this is a valid grid point then we're done, otherwise keep looking below. */
459 /* TODO: separate into a separate function (?) */
460 if (subgridToGridIndex(grid, subgridOrigin, subgridIndex, gridPointIndex))
466 /* Traverse the subgrid and look for the first point that is also in the grid. */
467 while (stepInMultiDimArray(grid.numDimensions(), subgridNumPoints, subgridIndex))
469 /* If this is a valid grid point, the grid point index is updated.*/
470 if (subgridToGridIndex(grid, subgridOrigin, subgridIndex, gridPointIndex))
480 * Returns the point distance between from value x to value x0 along the given axis.
482 * Note that the returned distance may be negative or larger than the
483 * number of points in the axis. For a periodic axis, the distance is chosen
484 * to be in [0, period), i.e. always positive but not the shortest one.
486 * \param[in] axis Grid axis.
487 * \param[in] x From value.
488 * \param[in] x0 To value.
489 * \returns (x - x0) in number of points.
491 static int pointDistanceAlongAxis(const GridAxis &axis, double x, double x0)
495 if (axis.spacing() > 0)
497 /* Get the real-valued distance. For a periodic axis, the shortest one. */
498 double period = axis.period();
499 double dx = getDeviationPeriodic(x, x0, period);
501 /* Transform the distance into a point distance by rounding. */
502 distance = gmx::roundToInt(dx/axis.spacing());
504 /* If periodic, shift the point distance to be in [0, period) */
505 distance = indexWithinPeriod(distance, axis.numPointsInPeriod());
512 * Query if a value is in range of the grid.
514 * \param[in] value Value to check.
515 * \param[in] axis The grid axes.
516 * \returns true if the value is in the grid.
518 static bool valueIsInGrid(const awh_dvec value,
519 const std::vector<GridAxis> &axis)
521 /* For each dimension get the one-dimensional index and check if it is in range. */
522 for (size_t d = 0; d < axis.size(); d++)
524 /* The index is computed as the point distance from the origin. */
525 int index = pointDistanceAlongAxis(axis[d], value[d], axis[d].origin());
527 if (!(index >= 0 && index < axis[d].numPoints()))
536 bool Grid::covers(const awh_dvec value) const
538 return valueIsInGrid(value, axis());
541 int GridAxis::nearestIndex(double value) const
543 /* Get the point distance to the origin. This may by an out of index range for the axis. */
544 int index = pointDistanceAlongAxis(*this, value, origin_);
546 if (index < 0 || index >= numPoints_)
550 GMX_RELEASE_ASSERT(index >= 0 && index < numPointsInPeriod_,
551 "Index not in periodic interval 0 for AWH periodic axis");
552 int endDistance = (index - (numPoints_ - 1));
553 int originDistance = (numPointsInPeriod_ - index);
554 index = originDistance < endDistance ? 0 : numPoints_ - 1;
558 index = (index < 0) ? 0 : (numPoints_ - 1);
566 * Map a value to the nearest point in the grid.
568 * \param[in] value Value.
569 * \param[in] axis The grid axes.
570 * \returns the point index nearest to the value.
572 static int getNearestIndexInGrid(const awh_dvec value,
573 const std::vector<GridAxis> &axis)
577 /* If the index is out of range, modify it so that it is in range by choosing the nearest point on the edge. */
578 for (size_t d = 0; d < axis.size(); d++)
580 indexMulti[d] = axis[d].nearestIndex(value[d]);
583 return multiDimGridIndexToLinear(axis, indexMulti);
586 int Grid::nearestIndex(const awh_dvec value) const
588 return getNearestIndexInGrid(value, axis());
595 * Find and set the neighbors of a grid point.
597 * The search space for neighbors is a subgrid with size set by a scope cutoff.
598 * In general not all point within scope will be valid grid points.
600 * \param[in] pointIndex Grid point index.
601 * \param[in] grid The grid.
602 * \param[in,out] neighborIndexArray Array to fill with neighbor indices.
604 void setNeighborsOfGridPoint(int pointIndex,
606 std::vector<int> *neighborIndexArray)
608 const int c_maxNeighborsAlongAxis = 1 + 2*static_cast<int>(Grid::c_numPointsPerSigma*Grid::c_scopeCutoff);
610 awh_ivec numCandidates = {0};
611 awh_ivec subgridOrigin = {0};
612 for (int d = 0; d < grid.numDimensions(); d++)
614 /* The number of candidate points along this dimension is given by the scope cutoff. */
615 numCandidates[d] = std::min(c_maxNeighborsAlongAxis,
616 grid.axis(d).numPoints());
618 /* The origin of the subgrid to search */
619 int centerIndex = grid.point(pointIndex).index[d];
620 subgridOrigin[d] = centerIndex - numCandidates[d]/2;
623 /* Find and set the neighbors */
624 int neighborIndex = -1;
625 bool aPointExists = true;
627 /* Keep looking for grid points while traversing the subgrid. */
630 /* The point index is updated if a grid point was found. */
631 aPointExists = advancePointInSubgrid(grid, subgridOrigin, numCandidates, &neighborIndex);
635 neighborIndexArray->push_back(neighborIndex);
642 void Grid::initPoints()
644 awh_ivec numPointsDimWork = { 0 };
645 awh_ivec indexWork = { 0 };
647 for (size_t d = 0; d < axis_.size(); d++)
649 /* Temporarily gather the number of points in each dimension in one array */
650 numPointsDimWork[d] = axis_[d].numPoints();
653 for (auto &point : point_)
655 for (size_t d = 0; d < axis_.size(); d++)
657 point.coordValue[d] = axis_[d].origin() + indexWork[d]*axis_[d].spacing();
659 if (axis_[d].period() > 0)
661 /* Do we always want the values to be centered around 0 ? */
662 centerPeriodicValueAroundZero(&point.coordValue[d], axis_[d].period());
665 point.index[d] = indexWork[d];
668 stepInMultiDimArray(axis_.size(), numPointsDimWork, indexWork);
672 GridAxis::GridAxis(double origin, double end,
673 double period, double pointDensity) :
677 length_ = getIntervalLengthPeriodic(origin_, end, period_);
679 /* Automatically determine number of points based on the user given endpoints
680 and the expected fluctuations in the umbrella. */
685 else if (pointDensity == 0)
691 /* An extra point is added here to account for the endpoints. The
692 minimum number of points for a non-zero interval is 2. */
693 numPoints_ = 1 + static_cast<int>(std::ceil(length_*pointDensity));
696 /* Set point spacing based on the number of points */
699 /* Set the grid spacing so that a period is matched exactly by an integer number of points.
700 The number of points in a period is equal to the number of grid spacings in a period
701 since the endpoints are connected. */
702 numPointsInPeriod_ = length_ > 0 ? static_cast<int>(std::ceil(period/length_*(numPoints_ - 1))) : 1;
703 spacing_ = period_/numPointsInPeriod_;
705 /* Modify the number of grid axis points to be compatible with the period dependent spacing. */
706 numPoints_ = std::min(static_cast<int>(round(length_/spacing_)) + 1,
711 numPointsInPeriod_ = 0;
712 spacing_ = numPoints_ > 1 ? length_/(numPoints_ - 1) : 0;
716 GridAxis::GridAxis(double origin, double end,
717 double period, int numPoints) :
720 numPoints_(numPoints)
722 length_ = getIntervalLengthPeriodic(origin_, end, period_);
723 spacing_ = numPoints_ > 1 ? length_/(numPoints_ - 1) : period_;
724 numPointsInPeriod_ = static_cast<int>(std::round(period_/spacing_));
727 Grid::Grid(const std::vector<DimParams> &dimParams,
728 const AwhDimParams *awhDimParams)
730 /* Define the discretization along each dimension */
733 for (size_t d = 0; d < dimParams.size(); d++)
735 double origin = dimParams[d].scaleUserInputToInternal(awhDimParams[d].origin);
736 double end = dimParams[d].scaleUserInputToInternal(awhDimParams[d].end);
737 period[d] = dimParams[d].scaleUserInputToInternal(awhDimParams[d].period);
738 static_assert(c_numPointsPerSigma >= 1.0, "The number of points per sigma should be at least 1.0 to get a uniformly covering the reaction using Gaussians");
739 double pointDensity = std::sqrt(dimParams[d].betak)*c_numPointsPerSigma;
740 axis_.emplace_back(origin, end, period[d], pointDensity);
741 numPoints *= axis_[d].numPoints();
744 point_.resize(numPoints);
746 /* Set their values */
749 /* Keep a neighbor list for each point.
750 * Note: could also generate neighbor list only when needed
751 * instead of storing them for each point.
753 for (size_t m = 0; m < point_.size(); m++)
755 std::vector<int> *neighbor = &point_[m].neighbor;
757 setNeighborsOfGridPoint(m, *this, neighbor);
761 void mapGridToDataGrid(std::vector<int> *gridpointToDatapoint,
762 const double* const *data,
764 const std::string &dataFilename,
766 const std::string &correctFormatMessage)
768 /* Transform the data into a grid in order to map each grid point to a data point
769 using the grid functions. */
771 /* Count the number of points for each dimension. Each dimension
772 has its own stride. */
774 int numPointsCounted = 0;
775 std::vector<int> numPoints(grid.numDimensions());
776 for (int d = grid.numDimensions() - 1; d >= 0; d--)
778 int numPointsInDim = 0;
780 double firstValue = data[d][pointIndex];
784 pointIndex += stride;
786 while (pointIndex < numDataPoints &&
787 !gmx_within_tol(firstValue, data[d][pointIndex], GMX_REAL_EPS));
789 /* The stride in dimension dimension d - 1 equals the number of points
791 stride = numPointsInDim;
793 numPointsCounted = (numPointsCounted == 0) ? numPointsInDim : numPointsCounted*numPointsInDim;
795 numPoints[d] = numPointsInDim;
798 if (numPointsCounted != numDataPoints)
800 std::string mesg = gmx::formatString("Could not extract data properly from %s. Wrong data format?"
802 dataFilename.c_str(), correctFormatMessage.c_str());
803 GMX_THROW(InvalidInputError(mesg));
806 std::vector<GridAxis> axis_;
807 axis_.reserve(grid.numDimensions());
808 /* The data grid has the data that was read and the properties of the AWH grid */
809 for (int d = 0; d < grid.numDimensions(); d++)
811 axis_.emplace_back(data[d][0], data[d][numDataPoints - 1],
812 grid.axis(d).period(), numPoints[d]);
815 /* Map each grid point to a data point. No interpolation, just pick the nearest one.
816 * It is assumed that the given data is uniformly spaced for each dimension.
818 for (size_t m = 0; m < grid.numPoints(); m++)
820 /* We only define what we need for the datagrid since it's not needed here which is a bit ugly */
822 if (!valueIsInGrid(grid.point(m).coordValue, axis_))
825 gmx::formatString("%s does not contain data for all coordinate values. "
826 "Make sure your input data covers the whole sampling domain "
827 "and is correctly formatted. \n\n%s",
828 dataFilename.c_str(), correctFormatMessage.c_str());
829 GMX_THROW(InvalidInputError(mesg));
831 (*gridpointToDatapoint)[m] = getNearestIndexInGrid(grid.point(m).coordValue, axis_);