2 * This file is part of the GROMACS molecular simulation package.
4 * Copyright (c) 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.
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 * Tests to compare free energy simulations to reference
40 * \author Pascal Merz <pascal.merz@me.com>
41 * \ingroup module_mdrun_integration_tests
47 #include "gromacs/topology/ifunc.h"
48 #include "gromacs/utility/filestream.h"
49 #include "gromacs/utility/path.h"
50 #include "gromacs/utility/stringutil.h"
52 #include "testutils/mpitest.h"
53 #include "testutils/refdata.h"
54 #include "testutils/setenv.h"
55 #include "testutils/simulationdatabase.h"
56 #include "testutils/xvgtest.h"
58 #include "moduletest.h"
59 #include "simulatorcomparison.h"
66 /*! \brief Test fixture base for free energy calculations
68 * This test ensures that selected free energy perturbation calculations produce
69 * results identical to an earlier version. The results of this earlier version
70 * have been verified manually to ensure physical correctness.
72 using MaxNumWarnings = int;
73 using ListOfInteractionsToTest = std::vector<int>;
74 using FreeEnergyReferenceTestParams = std::tuple<std::string, MaxNumWarnings, ListOfInteractionsToTest>;
75 class FreeEnergyReferenceTest :
76 public MdrunTestFixture,
77 public ::testing::WithParamInterface<FreeEnergyReferenceTestParams>
80 struct PrintParametersToString
82 template<class ParamType>
83 std::string operator()(const testing::TestParamInfo<ParamType>& parameter) const
85 auto simulationName = std::get<0>(parameter.param);
86 std::replace(simulationName.begin(), simulationName.end(), '-', '_');
87 return simulationName + (GMX_DOUBLE ? "_d" : "_s");
92 TEST_P(FreeEnergyReferenceTest, WithinTolerances)
94 const auto& simulationName = std::get<0>(GetParam());
95 const auto maxNumWarnings = std::get<1>(GetParam());
96 const auto& interactionsList = std::get<2>(GetParam());
98 // TODO In similar tests, we are checking if the tests
99 // can be run with the number of MPI ranks available
101 SCOPED_TRACE(formatString("Comparing FEP simulation '%s' to reference", simulationName.c_str()));
103 // Tolerance set to pass with identical code version and a range of different test setups
104 const auto defaultEnergyTolerance = relativeToleranceAsFloatingPoint(50.0, GMX_DOUBLE ? 1e-5 : 1e-4);
106 EnergyTermsToCompare energyTermsToCompare{ { interaction_function[F_EPOT].longname,
107 defaultEnergyTolerance } };
108 for (const auto& interaction : interactionsList)
110 energyTermsToCompare.emplace(interaction_function[interaction].longname, defaultEnergyTolerance);
113 // Specify how trajectory frame matching must work (only testing forces).
114 TrajectoryFrameMatchSettings trajectoryMatchSettings{ false,
117 ComparisonConditions::NoComparison,
118 ComparisonConditions::NoComparison,
119 ComparisonConditions::MustCompare };
120 TrajectoryTolerances trajectoryTolerances = TrajectoryComparison::s_defaultTrajectoryTolerances;
122 // Build the functor that will compare reference and test
123 // trajectory frames in the chosen way.
124 TrajectoryComparison trajectoryComparison{ trajectoryMatchSettings, trajectoryTolerances };
126 // Set simulation file names
127 auto simulationTrajectoryFileName = fileManager_.getTemporaryFilePath("trajectory.trr");
128 auto simulationEdrFileName = fileManager_.getTemporaryFilePath("energy.edr");
129 auto simulationDhdlFileName = fileManager_.getTemporaryFilePath("dhdl.xvg");
132 runner_.tprFileName_ = fileManager_.getTemporaryFilePath("sim.tpr");
133 runner_.useTopGroAndMdpFromFepTestDatabase(simulationName);
134 runGrompp(&runner_, { SimulationOptionTuple("-maxwarn", std::to_string(maxNumWarnings)) });
137 runner_.fullPrecisionTrajectoryFileName_ = simulationTrajectoryFileName;
138 runner_.edrFileName_ = simulationEdrFileName;
139 runner_.dhdlFileName_ = simulationDhdlFileName;
142 // Currently used tests write trajectory (x/v/f) frames every 20 steps.
143 // Testing more than the first force frame is only feasible in double precision
144 // using a single rank.
145 // Note that this only concerns trajectory frames, energy frames are checked
147 const bool testAllTrajectoryFrames = (GMX_DOUBLE && (getNumberOfTestMpiRanks() == 1));
149 // Compare simulation results
150 TestReferenceData refData;
151 TestReferenceChecker rootChecker(refData.rootChecker());
152 // Check that the energies agree with the refdata within tolerance.
153 checkEnergiesAgainstReferenceData(simulationEdrFileName, energyTermsToCompare, &rootChecker);
154 // Check that the trajectories agree with the refdata within tolerance.
155 if (testAllTrajectoryFrames)
157 checkTrajectoryAgainstReferenceData(simulationTrajectoryFileName, trajectoryComparison, &rootChecker);
161 checkTrajectoryAgainstReferenceData(simulationTrajectoryFileName, trajectoryComparison,
162 &rootChecker, MaxNumFrames(1));
164 if (File::exists(simulationDhdlFileName, File::returnFalseOnError))
166 TextInputFile dhdlFile(simulationDhdlFileName);
167 auto settings = XvgMatchSettings();
168 settings.tolerance = defaultEnergyTolerance;
169 checkXvgFile(&dhdlFile, &rootChecker, settings);
173 // TODO: The time for OpenCL kernel compilation means these tests time
174 // out. Once that compilation is cached for the whole process, these
175 // tests can run in such configurations.
177 INSTANTIATE_TEST_CASE_P(
178 FreeEnergyCalculationsAreEquivalentToReference,
179 FreeEnergyReferenceTest,
181 FreeEnergyReferenceTestParams{ "coulandvdwsequential_coul",
183 { F_DVDL_COUL, F_DVDL_VDW } },
184 FreeEnergyReferenceTestParams{ "coulandvdwsequential_vdw",
186 { F_DVDL_COUL, F_DVDL_VDW } },
187 FreeEnergyReferenceTestParams{ "coulandvdwtogether", MaxNumWarnings(0), { F_DVDL } },
188 FreeEnergyReferenceTestParams{ "expanded", MaxNumWarnings(0), { F_DVDL_COUL, F_DVDL_VDW } },
189 // Tolerated warnings: No default bonded interaction types for perturbed atoms (10x)
190 FreeEnergyReferenceTestParams{ "relative",
192 { F_DVDL, F_DVDL_COUL, F_DVDL_VDW, F_DVDL_BONDED } },
193 // Tolerated warnings: No default bonded interaction types for perturbed atoms (10x)
194 FreeEnergyReferenceTestParams{
195 "relative-position-restraints",
197 { F_DVDL, F_DVDL_COUL, F_DVDL_VDW, F_DVDL_BONDED, F_DVDL_RESTRAINT } },
198 FreeEnergyReferenceTestParams{ "restraints", MaxNumWarnings(0), { F_DVDL_RESTRAINT } },
199 FreeEnergyReferenceTestParams{ "simtemp", MaxNumWarnings(0), {} },
200 FreeEnergyReferenceTestParams{ "transformAtoB", MaxNumWarnings(0), { F_DVDL } },
201 FreeEnergyReferenceTestParams{ "vdwalone", MaxNumWarnings(0), { F_DVDL } }),
202 FreeEnergyReferenceTest::PrintParametersToString());
204 INSTANTIATE_TEST_CASE_P(
205 DISABLED_FreeEnergyCalculationsAreEquivalentToReference,
206 FreeEnergyReferenceTest,
208 FreeEnergyReferenceTestParams{ "coulandvdwsequential_coul",
210 { F_DVDL_COUL, F_DVDL_VDW } },
211 FreeEnergyReferenceTestParams{ "coulandvdwsequential_vdw",
213 { F_DVDL_COUL, F_DVDL_VDW } },
214 FreeEnergyReferenceTestParams{ "coulandvdwtogether", MaxNumWarnings(0), { F_DVDL } },
215 FreeEnergyReferenceTestParams{ "expanded", MaxNumWarnings(0), { F_DVDL_COUL, F_DVDL_VDW } },
216 // Tolerated warnings: No default bonded interaction types for perturbed atoms (10x)
217 FreeEnergyReferenceTestParams{ "relative",
219 { F_DVDL, F_DVDL_COUL, F_DVDL_VDW, F_DVDL_BONDED } },
220 // Tolerated warnings: No default bonded interaction types for perturbed atoms (10x)
221 FreeEnergyReferenceTestParams{
222 "relative-position-restraints",
224 { F_DVDL, F_DVDL_COUL, F_DVDL_VDW, F_DVDL_BONDED, F_DVDL_RESTRAINT } },
225 FreeEnergyReferenceTestParams{ "restraints", MaxNumWarnings(0), { F_DVDL_RESTRAINT } },
226 FreeEnergyReferenceTestParams{ "simtemp", MaxNumWarnings(0), {} },
227 FreeEnergyReferenceTestParams{ "transformAtoB", MaxNumWarnings(0), { F_DVDL } },
228 FreeEnergyReferenceTestParams{ "vdwalone", MaxNumWarnings(0), { F_DVDL } }),
229 FreeEnergyReferenceTest::PrintParametersToString());
233 } // namespace gmx::test