src/programs/mdrun/tests/trajectorycomparison.h

   1 /*
   2  * This file is part of the GROMACS molecular simulation package.
   3  *
   4  * Copyright (c) 2016,2017,2018,2019,2020, 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.
   8  *
   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.
  13  *
  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.
  18  *
  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.
  23  *
  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.
  31  *
  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.
  34  */
  35
  36 /*! \internal \file
  37  * \brief Declares types and functions for comparing trajectories
  38  * produced by mdrun.
  39  *
  40  * \author Mark Abraham <mark.j.abraham@gmail.com>
  41  * \author Pascal Merz <pascal.merz@me.com>
  42  * \ingroup module_mdrun_integration_tests
  43  */
  44 #ifndef GMX_PROGRAMS_MDRUN_TESTS_TRAJECTORYCOMPARISON_H
  45 #define GMX_PROGRAMS_MDRUN_TESTS_TRAJECTORYCOMPARISON_H
  46
  47 #include "testutils/testasserts.h"
  48
  49 #include "comparison_helpers.h"
  50
  51 namespace gmx
  52 {
  53
  54 class TrajectoryFrame;
  55
  56 namespace test
  57 {
  58
  59 class TestReferenceChecker;
  60
  61 /*! \internal
  62  * \brief Helper struct for testing different trajectory components with different tolerances. */
  63 struct TrajectoryTolerances
  64 {
  65     /*!@{*/
  66     /*! \brief Tolerances for reproduction of different quantities. */
  67     FloatingPointTolerance box, coordinates, velocities, forces;
  68     /*!@}*/
  69 };
  70
  71 //! Enumeration controlling how data within trajectory frames are compared
  72 enum class ComparisonConditions : int
  73 {
  74     CompareIfBothFound,
  75     NoComparison,
  76     MustCompare,
  77     CompareIfReferenceFound,
  78     CompareIfTestFound,
  79     Count
  80 };
  81
  82 /*! \internal
  83  * \brief Helper struct to specify the expected behaviour of compareFrames().
  84  *
  85  * By default, nothing is required to be compared, but the comparer will
  86  * compare what it can with the frames it is given.
  87  *
  88  * Handling PBC refers to putting all the atoms in the simulation box,
  89  * which requires that both the PBC type and a simulation box are
  90  * available from the trajectory frame. */
  91 struct TrajectoryFrameMatchSettings
  92 {
  93     //! Whether boxes must be compared.
  94     bool mustCompareBox = false;
  95     //! Whether PBC will be handled if it can be handled.
  96     bool handlePbcIfPossible = true;
  97     //! Whether PBC handling must occur for a valid comparison.
  98     bool requirePbcHandling = false;
  99     //! Whether position coordinates must be compared.
 100     ComparisonConditions coordinatesComparison = ComparisonConditions::CompareIfBothFound;
 101     //! Whether velocities must be compared.
 102     ComparisonConditions velocitiesComparison = ComparisonConditions::CompareIfBothFound;
 103     //! Whether forces must be compared.
 104     ComparisonConditions forcesComparison = ComparisonConditions::CompareIfBothFound;
 105     //! How many frames will be compared.
 106     MaxNumFrames maxNumTrajectoryFrames = MaxNumFrames::compareAllFrames();
 107 };
 108
 109 /*! \internal
 110  * \brief Function object to compare the fields of two frames vs each others or one
 111  * frame vs reference data for equality given the \c matchSettings_ and \c tolerances_.
 112  *
 113  * If using two frames, they are required to have valid and matching values for
 114  * time and step. According to \c matchSettings_, box, position coordinates,
 115  * velocities and/or forces will be compared between frames, using the
 116  * \c tolerances_. Comparisons will only occur when both frames have
 117  * the requisite data, and will be expected to be equal within the
 118  * matching component of \c tolerances_. If a comparison fails, a
 119  * GoogleTest expectation failure will be given. If a comparison is
 120  * required by \c matchSettings_ but cannot be done because either (or
 121  * both) frames lack the requisite data, descriptive expectation
 122  * failures will be given.
 123  *
 124  * When comparing a frame to reference data, according to \c matchSettings_,
 125  * box, position coordinates, velocities and/or forces will be compared to
 126  * reference data, using the \c tolerances_. If a comparison fails, a
 127  * GoogleTest expectation failure will be given. If a comparison is
 128  * required by \c matchSettings_ but cannot be done because the
 129  * frame lacks the requisite data, descriptive expectation
 130  * failures will be given.
 131  */
 132 class TrajectoryComparison
 133 {
 134 public:
 135     //! Defaults for trajectory comparisons
 136     static const TrajectoryTolerances s_defaultTrajectoryTolerances;
 137     //! Constructor
 138     TrajectoryComparison(const TrajectoryFrameMatchSettings& matchSettings,
 139                          const TrajectoryTolerances&         tolerances);
 140     /*! \brief Compare reference with test given the \c
 141      * matchSettings_ within \c tolerances_ */
 142     void operator()(const TrajectoryFrame& reference, const TrajectoryFrame& test) const;
 143     /*! \brief Compare frame to reference given the \c
 144      * matchSettings_ within \c tolerances_ */
 145     void operator()(const TrajectoryFrame& frame, TestReferenceChecker* checker) const;
 146
 147 private:
 148     //! Specifies expected behavior in comparisons
 149     TrajectoryFrameMatchSettings matchSettings_;
 150     //! Trajectory fields to match with given tolerances.
 151     TrajectoryTolerances tolerances_;
 152     /*! \brief The number of frames that have been compared until now
 153      *
 154      * This field is mutable because the need to update the flag
 155      * when checking frames is merely an implementation detail,
 156      * rather than a proper change of internal state triggered
 157      * by the caller. */
 158     mutable unsigned int numComparedFrames_ = 0;
 159 };
 160
 161 /*! \internal
 162  * \brief Helper function comparing a trajectory to reference.
 163  *
 164  * This opens a trajectory file, loops over its frames, and uses the
 165  * \c trajectoryComparison and \c checker arguments to check each frame
 166  * to reference data.
 167  *
 168  * Optionally, the max number of trajectory frames to be compared can
 169  * be specified to allow to only test the first few frames of a
 170  * simulation, e.g. to avoid failures due to numerical divergence.
 171  */
 172 //! \{
 173 void checkTrajectoryAgainstReferenceData(const std::string&          trajectoryFilename,
 174                                          const TrajectoryComparison& trajectoryComparison,
 175                                          TestReferenceChecker*       checker);
 176 void checkTrajectoryAgainstReferenceData(const std::string&          trajectoryFilename,
 177                                          const TrajectoryComparison& trajectoryComparison,
 178                                          TestReferenceChecker*       checker,
 179                                          MaxNumFrames                maxNumFrames);
 180 //! \}
 181
 182 } // namespace test
 183 } // namespace gmx
 184
 185 #endif