src/programs/mdrun/tests/moduletest.h

   1 /*
   2  * This file is part of the GROMACS molecular simulation package.
   3  *
   4  * Copyright (c) 2013,2014,2015,2016,2017 by the GROMACS development team.
   5  * Copyright (c) 2018,2019,2020,2021, by the GROMACS development team, led by
   6  * Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl,
   7  * and including many others, as listed in the AUTHORS file in the
   8  * top-level source directory and at http://www.gromacs.org.
   9  *
  10  * GROMACS is free software; you can redistribute it and/or
  11  * modify it under the terms of the GNU Lesser General Public License
  12  * as published by the Free Software Foundation; either version 2.1
  13  * of the License, or (at your option) any later version.
  14  *
  15  * GROMACS is distributed in the hope that it will be useful,
  16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  18  * Lesser General Public License for more details.
  19  *
  20  * You should have received a copy of the GNU Lesser General Public
  21  * License along with GROMACS; if not, see
  22  * http://www.gnu.org/licenses, or write to the Free Software Foundation,
  23  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA.
  24  *
  25  * If you want to redistribute modifications to GROMACS, please
  26  * consider that scientific software is very special. Version
  27  * control is crucial - bugs must be traceable. We will be happy to
  28  * consider code for inclusion in the official distribution, but
  29  * derived work must not be called official GROMACS. Details are found
  30  * in the README & COPYING files - if they are missing, get the
  31  * official version at http://www.gromacs.org.
  32  *
  33  * To help us fund GROMACS development, we humbly ask that you cite
  34  * the research papers on the package. Check out http://www.gromacs.org.
  35  */
  36 /*! \defgroup module_mdrun_integration_tests Integration test utilities
  37  * \ingroup group_mdrun
  38  *
  39  * \brief Functionality for testing mdrun as a whole
  40  */
  41 /*! \internal \file
  42  * \brief
  43  * Declares test fixtures for general mdrun functionality.
  44  *
  45  * \author Mark Abraham <mark.j.abraham@gmail.com>
  46  * \ingroup module_mdrun_integration_tests
  47  */
  48 #ifndef GMX_MDRUN_TESTS_MODULETEST_H
  49 #define GMX_MDRUN_TESTS_MODULETEST_H
  50
  51 #include <gtest/gtest.h>
  52
  53 #include <memory>
  54
  55 #include "gromacs/utility/classhelpers.h"
  56 #include "gromacs/utility/gmxmpi.h"
  57
  58 #include "testutils/cmdlinetest.h"
  59 #include "testutils/testfilemanager.h"
  60
  61 struct gmx_hw_info_t;
  62
  63 namespace gmx
  64 {
  65 namespace test
  66 {
  67
  68 /*! \internal
  69  * \brief How the mdp file of the SimulationRunner is defined
  70  */
  71 enum class SimulationRunnerMdpSource
  72 {
  73     //! The default behavior. Will result in an empty mdp file.
  74     Undefined,
  75     //! Mdp options are set via string using SimulationRunner::useStringAsMdpFile
  76     String,
  77     //! Mdp options are read from a file set in SimulationRunner::useTopGroAndMdpFromFepTestDatabase
  78     File,
  79     //! Signals the last enum entry
  80     Count
  81 };
  82
  83 /*! \internal
  84  * \brief Helper object for running grompp and mdrun in
  85  * integration tests of mdrun functionality
  86  *
  87  * Objects of this class must be owned by objects descended from
  88  * MdrunTestFixtureBase, which sets up necessary infrastructure for
  89  * it. Such an object may own more than one SimulationRunner.
  90  *
  91  * The setup phase creates various temporary files for input and
  92  * output that are common for mdrun tests, using the file manager
  93  * object of the fixture that owns this object. Individual tests
  94  * should create any extra filenames similarly, so that the test
  95  * users's current working directory does not get littered with files
  96  * left over from tests.
  97  *
  98  * Any method in this class may throw std::bad_alloc if out of memory.
  99  *
 100  * By default, the convenience methods callGrompp() and callMdrun()
 101  * just prepare and run a default call to mdrun. If there is a need to
 102  * customize the command-line for grompp or mdrun (e.g. to invoke
 103  * -maxwarn n, or -reprod), then make a CommandLine object with the
 104  * appropriate flags and pass that into the routines that accept such.
 105  *
 106  * \ingroup module_mdrun_integration_tests
 107  */
 108 class SimulationRunner
 109 {
 110 public:
 111     //! Initializes a runner with given manager for temporary files.
 112     explicit SimulationRunner(TestFileManager* fileManager);
 113
 114     //! Use an empty .mdp file as input to grompp
 115     void useEmptyMdpFile();
 116     //! Use a given string as input to grompp
 117     void useStringAsMdpFile(const char* mdpString);
 118     //! Use a given string as input to grompp
 119     void useStringAsMdpFile(const std::string& mdpString);
 120     //! Use a string as -n input to grompp
 121     void useStringAsNdxFile(const char* ndxString) const;
 122     //! Use a standard .top and .g96 file as input to grompp
 123     void useTopG96AndNdxFromDatabase(const std::string& name);
 124     //! Use a standard .top and .gro file as input to grompp
 125     void useTopGroAndNdxFromDatabase(const std::string& name);
 126     //! Use a standard .gro file as input to grompp
 127     void useGroFromDatabase(const char* name);
 128     //! Use a standard .ndx as input to grompp
 129     void useNdxFromDatabase(const std::string& name);
 130     //! Use .top, .gro, and .mdp from FEP test database
 131     void useTopGroAndMdpFromFepTestDatabase(const std::string& name);
 132     //! Calls grompp (on rank 0, with a customized command line) to prepare for the mdrun test
 133     int callGrompp(const CommandLine& callerRef);
 134     //! Convenience wrapper for a default call to \c callGrompp
 135     int callGrompp();
 136     //! Calls grompp (on this rank, with a customized command line) to prepare for the mdrun test
 137     int callGromppOnThisRank(const CommandLine& callerRef);
 138     //! Convenience wrapper for a default call to \c callGromppOnThisRank
 139     int callGromppOnThisRank();
 140     //! Calls nmeig for testing
 141     int callNmeig() const;
 142     //! Calls mdrun for testing with a customized command line
 143     int callMdrun(const CommandLine& callerRef);
 144     /*! \brief Convenience wrapper for calling mdrun for testing
 145      * with default command line */
 146     int callMdrun();
 147     //! Calls convert-tpr on this rank to set a new number of steps in the tpr.
 148     int changeTprNsteps(int nsteps) const;
 149
 150     //@{
 151     /*! \name Names for frequently used grompp and mdrun output files
 152      *
 153      * These strings can be set to point to files present in the
 154      * source tree, or to temporary files created for the test
 155      * fixture. In the latter case,
 156      * IntegrationTestFixture::fileManager_ should be used to fill
 157      * these strings with paths to files, so that they are created
 158      * in a temporary directory and (by default behaviour of
 159      * TestFileManager) deleted when the test is complete.
 160      */
 161     std::string topFileName_;
 162     std::string groFileName_;
 163     std::string mdpFileName_;
 164     std::string fullPrecisionTrajectoryFileName_;
 165     std::string reducedPrecisionTrajectoryFileName_;
 166     std::string groOutputFileName_;
 167     std::string ndxFileName_;
 168     std::string mdpOutputFileName_;
 169     std::string tprFileName_;
 170     std::string logFileName_;
 171     std::string edrFileName_;
 172     std::string mtxFileName_;
 173     std::string cptFileName_;
 174     std::string swapFileName_;
 175     std::string dhdlFileName_;
 176     int         nsteps_;
 177     //@}
 178     //! How the mdp options are defined
 179     SimulationRunnerMdpSource mdpSource_;
 180     //! What will be written into a temporary mdp file before the grompp call
 181     std::string mdpInputContents_;
 182
 183 private:
 184     //! The file manager used to manage I/O
 185     TestFileManager& fileManager_;
 186
 187     GMX_DISALLOW_COPY_AND_ASSIGN(SimulationRunner);
 188 };
 189
 190 /*! \internal
 191  * \brief Declares test fixture base class for
 192  * integration tests of mdrun functionality
 193  *
 194  * Heavyweight resources are set up here and shared
 195  * across all tests in the test case fixture, e.g.
 196  * the MPI communicator for the tests and the hardware
 197  * detected that is available to it.
 198  *
 199  * \ingroup module_mdrun_integration_tests
 200  */
 201 class MdrunTestFixtureBase : public ::testing::Test
 202 {
 203 public:
 204     //! Per-test-case setup for lengthy processes that need run only once.
 205     static void SetUpTestCase();
 206     //! Per-test-case tear down
 207     static void TearDownTestCase();
 208
 209     MdrunTestFixtureBase();
 210     ~MdrunTestFixtureBase() override;
 211
 212     //! Communicator over which the test fixture works
 213     // NOLINTNEXTLINE(cppcoreguidelines-avoid-non-const-global-variables)
 214     static MPI_Comm communicator_;
 215     /*! \brief Hardware information object
 216      *
 217      * Detected within \c communicator_ and available to re-use
 218      * over all tests in the test case of this text fixture. */
 219     // NOLINTNEXTLINE(cppcoreguidelines-avoid-non-const-global-variables)
 220     static std::unique_ptr<gmx_hw_info_t> hwinfo_;
 221 };
 222
 223 /*! \internal
 224  * \brief Declares test fixture class for integration
 225  * tests of mdrun functionality that use a single call of mdrun
 226  *
 227  * Any method in this class may throw std::bad_alloc if out of memory.
 228  *
 229  * \ingroup module_mdrun_integration_tests
 230  */
 231 class MdrunTestFixture : public MdrunTestFixtureBase
 232 {
 233 public:
 234     MdrunTestFixture();
 235     ~MdrunTestFixture() override;
 236
 237     //! Manages temporary files during the test.
 238     TestFileManager fileManager_;
 239     //! Helper object to manage the preparation for and call of mdrun
 240     SimulationRunner runner_;
 241 };
 242
 243 /*! \internal
 244  * \brief
 245  * Parameterized test fixture for mdrun integration tests
 246  */
 247 class ParameterizedMdrunTestFixture :
 248     public gmx::test::MdrunTestFixture,
 249     public ::testing::WithParamInterface<const char*>
 250 {
 251 };
 252
 253 } // namespace test
 254 } // namespace gmx
 255
 256 #endif