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, 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 "gromacs/utility/classhelpers.h"
  54 #include "gromacs/utility/gmxmpi.h"
  55
  56 #include "testutils/cmdlinetest.h"
  57 #include "testutils/testfilemanager.h"
  58
  59 struct gmx_hw_info_t;
  60
  61 namespace gmx
  62 {
  63 namespace test
  64 {
  65
  66 /*! \internal
  67  * \brief How the mdp file of the SimulationRunner is defined
  68  */
  69 enum class SimulationRunnerMdpSource
  70 {
  71     //! The default behavior. Will result in an empty mdp file.
  72     Undefined,
  73     //! Mdp options are set via string using SimulationRunner::useStringAsMdpFile
  74     String,
  75     //! Mdp options are read from a file set in SimulationRunner::useTopGroAndMdpFromFepTestDatabase
  76     File,
  77     //! Signals the last enum entry
  78     Count
  79 };
  80
  81 /*! \internal
  82  * \brief Helper object for running grompp and mdrun in
  83  * integration tests of mdrun functionality
  84  *
  85  * Objects of this class must be owned by objects descended from
  86  * MdrunTestFixtureBase, which sets up necessary infrastructure for
  87  * it. Such an object may own more than one SimulationRunner.
  88  *
  89  * The setup phase creates various temporary files for input and
  90  * output that are common for mdrun tests, using the file manager
  91  * object of the fixture that owns this object. Individual tests
  92  * should create any extra filenames similarly, so that the test
  93  * users's current working directory does not get littered with files
  94  * left over from tests.
  95  *
  96  * Any method in this class may throw std::bad_alloc if out of memory.
  97  *
  98  * By default, the convenience methods callGrompp() and callMdrun()
  99  * just prepare and run a default call to mdrun. If there is a need to
 100  * customize the command-line for grompp or mdrun (e.g. to invoke
 101  * -maxwarn n, or -reprod), then make a CommandLine object with the
 102  * appropriate flags and pass that into the routines that accept such.
 103  *
 104  * \ingroup module_mdrun_integration_tests
 105  */
 106 class SimulationRunner
 107 {
 108 public:
 109     //! Initializes a runner with given manager for temporary files.
 110     explicit SimulationRunner(TestFileManager* fileManager);
 111
 112     //! Use an empty .mdp file as input to grompp
 113     void useEmptyMdpFile();
 114     //! Use a given string as input to grompp
 115     void useStringAsMdpFile(const char* mdpString);
 116     //! Use a given string as input to grompp
 117     void useStringAsMdpFile(const std::string& mdpString);
 118     //! Use a string as -n input to grompp
 119     void useStringAsNdxFile(const char* ndxString);
 120     //! Use a standard .top and .g96 file as input to grompp
 121     void useTopG96AndNdxFromDatabase(const std::string& name);
 122     //! Use a standard .top and .gro file as input to grompp
 123     void useTopGroAndNdxFromDatabase(const std::string& name);
 124     //! Use a standard .gro file as input to grompp
 125     void useGroFromDatabase(const char* name);
 126     //! Use .top, .gro, and .mdp from FEP test database
 127     void useTopGroAndMdpFromFepTestDatabase(const std::string& name);
 128     //! Calls grompp (on rank 0, with a customized command line) to prepare for the mdrun test
 129     int callGrompp(const CommandLine& callerRef);
 130     //! Convenience wrapper for a default call to \c callGrompp
 131     int callGrompp();
 132     //! Calls grompp (on this rank, with a customized command line) to prepare for the mdrun test
 133     int callGromppOnThisRank(const CommandLine& callerRef);
 134     //! Convenience wrapper for a default call to \c callGromppOnThisRank
 135     int callGromppOnThisRank();
 136     //! Calls nmeig for testing
 137     int callNmeig();
 138     //! Calls mdrun for testing with a customized command line
 139     int callMdrun(const CommandLine& callerRef);
 140     /*! \brief Convenience wrapper for calling mdrun for testing
 141      * with default command line */
 142     int callMdrun();
 143     //! Calls convert-tpr on this rank to set a new number of steps in the tpr.
 144     int changeTprNsteps(int nsteps);
 145
 146     //@{
 147     /*! \name Names for frequently used grompp and mdrun output files
 148      *
 149      * These strings can be set to point to files present in the
 150      * source tree, or to temporary files created for the test
 151      * fixture. In the latter case,
 152      * IntegrationTestFixture::fileManager_ should be used to fill
 153      * these strings with paths to files, so that they are created
 154      * in a temporary directory and (by default behaviour of
 155      * TestFileManager) deleted when the test is complete.
 156      */
 157     std::string topFileName_;
 158     std::string groFileName_;
 159     std::string mdpFileName_;
 160     std::string fullPrecisionTrajectoryFileName_;
 161     std::string reducedPrecisionTrajectoryFileName_;
 162     std::string groOutputFileName_;
 163     std::string ndxFileName_;
 164     std::string mdpOutputFileName_;
 165     std::string tprFileName_;
 166     std::string logFileName_;
 167     std::string edrFileName_;
 168     std::string mtxFileName_;
 169     std::string cptFileName_;
 170     std::string swapFileName_;
 171     std::string dhdlFileName_;
 172     int         nsteps_;
 173     //@}
 174     //! How the mdp options are defined
 175     SimulationRunnerMdpSource mdpSource_;
 176     //! What will be written into a temporary mdp file before the grompp call
 177     std::string mdpInputContents_;
 178
 179 private:
 180     //! The file manager used to manage I/O
 181     TestFileManager& fileManager_;
 182
 183     GMX_DISALLOW_COPY_AND_ASSIGN(SimulationRunner);
 184 };
 185
 186 /*! \internal
 187  * \brief Declares test fixture base class for
 188  * integration tests of mdrun functionality
 189  *
 190  * Heavyweight resources are set up here and shared
 191  * across all tests in the test case fixture, e.g.
 192  * the MPI communicator for the tests and the hardware
 193  * detected that is available to it.
 194  *
 195  * \ingroup module_mdrun_integration_tests
 196  */
 197 class MdrunTestFixtureBase : public ::testing::Test
 198 {
 199 public:
 200     //! Per-test-case setup for lengthy processes that need run only once.
 201     static void SetUpTestCase();
 202     //! Per-test-case tear down
 203     static void TearDownTestCase();
 204
 205     MdrunTestFixtureBase();
 206     ~MdrunTestFixtureBase() override;
 207
 208     //! Communicator over which the test fixture works
 209     static MPI_Comm communicator_;
 210     /*! \brief Hardware information object
 211      *
 212      * Detected within \c communicator_ and available to re-use
 213      * over all tests in the test case of this text fixture. */
 214     static std::unique_ptr<gmx_hw_info_t> hwinfo_;
 215 };
 216
 217 /*! \internal
 218  * \brief Declares test fixture class for integration
 219  * tests of mdrun functionality that use a single call of mdrun
 220  *
 221  * Any method in this class may throw std::bad_alloc if out of memory.
 222  *
 223  * \ingroup module_mdrun_integration_tests
 224  */
 225 class MdrunTestFixture : public MdrunTestFixtureBase
 226 {
 227 public:
 228     MdrunTestFixture();
 229     ~MdrunTestFixture() override;
 230
 231     //! Manages temporary files during the test.
 232     TestFileManager fileManager_;
 233     //! Helper object to manage the preparation for and call of mdrun
 234     SimulationRunner runner_;
 235 };
 236
 237 /*! \internal
 238  * \brief
 239  * Parameterized test fixture for mdrun integration tests
 240  */
 241 class ParameterizedMdrunTestFixture :
 242     public gmx::test::MdrunTestFixture,
 243     public ::testing::WithParamInterface<const char*>
 244 {
 245 };
 246
 247 } // namespace test
 248 } // namespace gmx
 249
 250 #endif