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);
 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 .top, .gro, and .mdp from FEP test database
 129     void useTopGroAndMdpFromFepTestDatabase(const std::string& name);
 130     //! Calls grompp (on rank 0, with a customized command line) to prepare for the mdrun test
 131     int callGrompp(const CommandLine& callerRef);
 132     //! Convenience wrapper for a default call to \c callGrompp
 133     int callGrompp();
 134     //! Calls grompp (on this rank, with a customized command line) to prepare for the mdrun test
 135     int callGromppOnThisRank(const CommandLine& callerRef);
 136     //! Convenience wrapper for a default call to \c callGromppOnThisRank
 137     int callGromppOnThisRank();
 138     //! Calls nmeig for testing
 139     int callNmeig();
 140     //! Calls mdrun for testing with a customized command line
 141     int callMdrun(const CommandLine& callerRef);
 142     /*! \brief Convenience wrapper for calling mdrun for testing
 143      * with default command line */
 144     int callMdrun();
 145     //! Calls convert-tpr on this rank to set a new number of steps in the tpr.
 146     int changeTprNsteps(int nsteps);
 147
 148     //@{
 149     /*! \name Names for frequently used grompp and mdrun output files
 150      *
 151      * These strings can be set to point to files present in the
 152      * source tree, or to temporary files created for the test
 153      * fixture. In the latter case,
 154      * IntegrationTestFixture::fileManager_ should be used to fill
 155      * these strings with paths to files, so that they are created
 156      * in a temporary directory and (by default behaviour of
 157      * TestFileManager) deleted when the test is complete.
 158      */
 159     std::string topFileName_;
 160     std::string groFileName_;
 161     std::string mdpFileName_;
 162     std::string fullPrecisionTrajectoryFileName_;
 163     std::string reducedPrecisionTrajectoryFileName_;
 164     std::string groOutputFileName_;
 165     std::string ndxFileName_;
 166     std::string mdpOutputFileName_;
 167     std::string tprFileName_;
 168     std::string logFileName_;
 169     std::string edrFileName_;
 170     std::string mtxFileName_;
 171     std::string cptFileName_;
 172     std::string swapFileName_;
 173     std::string dhdlFileName_;
 174     int         nsteps_;
 175     //@}
 176     //! How the mdp options are defined
 177     SimulationRunnerMdpSource mdpSource_;
 178     //! What will be written into a temporary mdp file before the grompp call
 179     std::string mdpInputContents_;
 180
 181 private:
 182     //! The file manager used to manage I/O
 183     TestFileManager& fileManager_;
 184
 185     GMX_DISALLOW_COPY_AND_ASSIGN(SimulationRunner);
 186 };
 187
 188 /*! \internal
 189  * \brief Declares test fixture base class for
 190  * integration tests of mdrun functionality
 191  *
 192  * Heavyweight resources are set up here and shared
 193  * across all tests in the test case fixture, e.g.
 194  * the MPI communicator for the tests and the hardware
 195  * detected that is available to it.
 196  *
 197  * \ingroup module_mdrun_integration_tests
 198  */
 199 class MdrunTestFixtureBase : public ::testing::Test
 200 {
 201 public:
 202     //! Per-test-case setup for lengthy processes that need run only once.
 203     static void SetUpTestCase();
 204     //! Per-test-case tear down
 205     static void TearDownTestCase();
 206
 207     MdrunTestFixtureBase();
 208     ~MdrunTestFixtureBase() override;
 209
 210     //! Communicator over which the test fixture works
 211     static MPI_Comm communicator_;
 212     /*! \brief Hardware information object
 213      *
 214      * Detected within \c communicator_ and available to re-use
 215      * over all tests in the test case of this text fixture. */
 216     static std::unique_ptr<gmx_hw_info_t> hwinfo_;
 217 };
 218
 219 /*! \internal
 220  * \brief Declares test fixture class for integration
 221  * tests of mdrun functionality that use a single call of mdrun
 222  *
 223  * Any method in this class may throw std::bad_alloc if out of memory.
 224  *
 225  * \ingroup module_mdrun_integration_tests
 226  */
 227 class MdrunTestFixture : public MdrunTestFixtureBase
 228 {
 229 public:
 230     MdrunTestFixture();
 231     ~MdrunTestFixture() override;
 232
 233     //! Manages temporary files during the test.
 234     TestFileManager fileManager_;
 235     //! Helper object to manage the preparation for and call of mdrun
 236     SimulationRunner runner_;
 237 };
 238
 239 /*! \internal
 240  * \brief
 241  * Parameterized test fixture for mdrun integration tests
 242  */
 243 class ParameterizedMdrunTestFixture :
 244     public gmx::test::MdrunTestFixture,
 245     public ::testing::WithParamInterface<const char*>
 246 {
 247 };
 248
 249 } // namespace test
 250 } // namespace gmx
 251
 252 #endif