1/*
2 * This file is part of the GROMACS molecular simulation package.
3 *
4 * Copyright (c) 1991-2000, University of Groningen, The Netherlands.
5 * Copyright (c) 2001-2004, The GROMACS development team.
6 * Copyright (c) 2011-2019, by the GROMACS development team, led by
7 * Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl,
8 * and including many others, as listed in the AUTHORS file in the
9 * top-level source directory and at http://www.gromacs.org.
10 *
11 * GROMACS is free software; you can redistribute it and/or
12 * modify it under the terms of the GNU Lesser General Public License
13 * as published by the Free Software Foundation; either version 2.1
14 * of the License, or (at your option) any later version.
15 *
16 * GROMACS is distributed in the hope that it will be useful,
17 * but WITHOUT ANY WARRANTY; without even the implied warranty of
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
19 * Lesser General Public License for more details.
20 *
21 * You should have received a copy of the GNU Lesser General Public
22 * License along with GROMACS; if not, see
23 * http://www.gnu.org/licenses, or write to the Free Software Foundation,
24 * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA.
25 *
26 * If you want to redistribute modifications to GROMACS, please
27 * consider that scientific software is very special. Version
28 * control is crucial - bugs must be traceable. We will be happy to
29 * consider code for inclusion in the official distribution, but
30 * derived work must not be called official GROMACS. Details are found
31 * in the README & COPYING files - if they are missing, get the
32 * official version at http://www.gromacs.org.
33 *
34 * To help us fund GROMACS development, we humbly ask that you cite
35 * the research papers on the package. Check out http://www.gromacs.org.
36 */
37/*! \libinternal \file
38 *
39 * \brief This file declares helper functionality for legacy option handling for mdrun
40 *
41 * \author Berk Hess <hess@kth.se>
42 * \author David van der Spoel <david.vanderspoel@icm.uu.se>
43 * \author Erik Lindahl <erik@kth.se>
44 * \author Mark Abraham <mark.j.abraham@gmail.com>
45 *
46 * \ingroup module_mdrun
47 * \inlibraryapi
48 */
49#ifndef GMX_MDRUN_LEGACYMDRUNOPTIONS_H
50#define GMX_MDRUN_LEGACYMDRUNOPTIONS_H
51
52#include "gromacs/commandline/filenm.h"
53#include "gromacs/commandline/pargs.h"
54#include "gromacs/domdec/options.h"
55#include "gromacs/hardware/hw_info.h"
56#include "gromacs/mdtypes/mdrunoptions.h"
57
58#include "replicaexchange.h"
59
60namespace gmx
61{
62
63/*! \libinternal
64 * \brief This class provides the same command-line option
65 * functionality to both CLI and API sessions.
66 *
67 * This class should not exist, but is necessary now to introduce
68 * support for the CLI and API without duplicating code. It should be
69 * eliminated following the TODOs below.
70 *
71 * \todo Modules in mdrun should acquire proper option handling so
72 * that all of these declarations and defaults are local to the
73 * modules.
74 *
75 * \todo Contextual aspects, such as working directory
76 * and environment variable handling are more properly
77 * the role of SimulationContext, and should be moved there */
78class LegacyMdrunOptions
79{
80public:
81    //! Ongoing collection of mdrun options
82    MdrunOptions mdrunOptions;
83    //! Options for the domain decomposition.
84    DomdecOptions domdecOptions;
85    //! Parallelism-related user options.
86    gmx_hw_opt_t hw_opt;
87    //! Command-line override for the duration of a neighbor list with the Verlet scheme.
88    int nstlist_cmdline = 0;
89    //! Parameters for replica-exchange simulations.
90    ReplicaExchangeParameters replExParams;
91
92    //! Filename options to fill from command-line argument values.
93    std::vector<t_filenm> filenames = { { { efTPR, nullptr, nullptr, ffREAD },
94                                          { efTRN, "-o", nullptr, ffWRITE },
95                                          { efCOMPRESSED, "-x", nullptr, ffOPTWR },
96                                          { efCPT, "-cpi", nullptr, ffOPTRD | ffALLOW_MISSING },
97                                          { efCPT, "-cpo", nullptr, ffOPTWR },
98                                          { efSTO, "-c", "confout", ffWRITE },
99                                          { efEDR, "-e", "ener", ffWRITE },
100                                          { efLOG, "-g", "md", ffWRITE },
101                                          { efXVG, "-dhdl", "dhdl", ffOPTWR },
102                                          { efXVG, "-field", "field", ffOPTWR },
103                                          { efXVG, "-table", "table", ffOPTRD },
104                                          { efXVG, "-tablep", "tablep", ffOPTRD },
105                                          { efXVG, "-tableb", "table", ffOPTRDMULT },
106                                          { efTRX, "-rerun", "rerun", ffOPTRD },
107                                          { efXVG, "-tpi", "tpi", ffOPTWR },
108                                          { efXVG, "-tpid", "tpidist", ffOPTWR },
109                                          { efEDI, "-ei", "sam", ffOPTRD },
110                                          { efXVG, "-eo", "edsam", ffOPTWR },
111                                          { efXVG, "-px", "pullx", ffOPTWR },
112                                          { efXVG, "-pf", "pullf", ffOPTWR },
113                                          { efXVG, "-ro", "rotation", ffOPTWR },
114                                          { efLOG, "-ra", "rotangles", ffOPTWR },
115                                          { efLOG, "-rs", "rotslabs", ffOPTWR },
116                                          { efLOG, "-rt", "rottorque", ffOPTWR },
117                                          { efMTX, "-mtx", "nm", ffOPTWR },
118                                          { efRND, "-multidir", nullptr, ffOPTRDMULT },
119                                          { efXVG, "-awh", "awhinit", ffOPTRD },
120                                          { efDAT, "-membed", "membed", ffOPTRD },
121                                          { efTOP, "-mp", "membed", ffOPTRD },
122                                          { efNDX, "-mn", "membed", ffOPTRD },
123                                          { efXVG, "-if", "imdforces", ffOPTWR },
124                                          { efXVG, "-swap", "swapions", ffOPTWR } } };
125
126    //! Print a warning if any force is larger than this (in kJ/mol nm).
127    real pforce = -1;
128
129    //! The value of the -append option
130    bool appendOption = true;
131
132    /*! \brief Output context for writing text files
133     *
134     * \todo Clarify initialization, ownership, and lifetime. */
135    gmx_output_env_t* oenv = nullptr;
136
137    /*! \brief Command line options, defaults, docs and storage for them to fill. */
138    /*! \{ */
139    rvec        realddxyz                                                    = { 0, 0, 0 };
140    const char* ddrank_opt_choices[static_cast<int>(DdRankOrder::Count) + 1] = {
141        nullptr, "interleave", "pp_pme", "cartesian", nullptr
142    };
143    const char* dddlb_opt_choices[static_cast<int>(DlbOption::Count) + 1] = { nullptr, "auto", "no",
144                                                                              "yes", nullptr };
145    const char* thread_aff_opt_choices[static_cast<int>(ThreadAffinity::Count) + 1] = {
146        nullptr, "auto", "on", "off", nullptr
147    };
148    const char* nbpu_opt_choices[5]    = { nullptr, "auto", "cpu", "gpu", nullptr };
149    const char* pme_opt_choices[5]     = { nullptr, "auto", "cpu", "gpu", nullptr };
150    const char* pme_fft_opt_choices[5] = { nullptr, "auto", "cpu", "gpu", nullptr };
151    const char* bonded_opt_choices[5]  = { nullptr, "auto", "cpu", "gpu", nullptr };
152    const char* update_opt_choices[5]  = { nullptr, "auto", "cpu", "gpu", nullptr };
153    const char* gpuIdsAvailable        = "";
154    const char* userGpuTaskAssignment  = "";
155
156
157    ImdOptions& imdOptions = mdrunOptions.imdOptions;
158
159    t_pargs pa[48] = {
160
161        { "-dd", FALSE, etRVEC, { &realddxyz }, "Domain decomposition grid, 0 is optimize" },
162        { "-ddorder", FALSE, etENUM, { ddrank_opt_choices }, "DD rank order" },
163        { "-npme",
164          FALSE,
165          etINT,
166          { &domdecOptions.numPmeRanks },
167          "Number of separate ranks to be used for PME, -1 is guess" },
168        { "-nt",
169          FALSE,
170          etINT,
171          { &hw_opt.nthreads_tot },
172          "Total number of threads to start (0 is guess)" },
173        { "-ntmpi",
174          FALSE,
175          etINT,
176          { &hw_opt.nthreads_tmpi },
177          "Number of thread-MPI ranks to start (0 is guess)" },
178        { "-ntomp",
179          FALSE,
180          etINT,
181          { &hw_opt.nthreads_omp },
182          "Number of OpenMP threads per MPI rank to start (0 is guess)" },
183        { "-ntomp_pme",
184          FALSE,
185          etINT,
186          { &hw_opt.nthreads_omp_pme },
187          "Number of OpenMP threads per MPI rank to start (0 is -ntomp)" },
188        { "-pin",
189          FALSE,
190          etENUM,
191          { thread_aff_opt_choices },
192          "Whether mdrun should try to set thread affinities" },
193        { "-pinoffset",
194          FALSE,
195          etINT,
196          { &hw_opt.core_pinning_offset },
197          "The lowest logical core number to which mdrun should pin the first thread" },
198        { "-pinstride",
199          FALSE,
200          etINT,
201          { &hw_opt.core_pinning_stride },
202          "Pinning distance in logical cores for threads, use 0 to minimize the number of threads "
203          "per physical core" },
204        { "-gpu_id",
205          FALSE,
206          etSTR,
207          { &gpuIdsAvailable },
208          "List of unique GPU device IDs available to use" },
209        { "-gputasks",
210          FALSE,
211          etSTR,
212          { &userGpuTaskAssignment },
213          "List of GPU device IDs, mapping each PP task on each node to a device" },
214        { "-ddcheck",
215          FALSE,
216          etBOOL,
217          { &domdecOptions.checkBondedInteractions },
218          "Check for all bonded interactions with DD" },
219        { "-ddbondcomm",
220          FALSE,
221          etBOOL,
222          { &domdecOptions.useBondedCommunication },
223          "HIDDENUse special bonded atom communication when [TT]-rdd[tt] > cut-off" },
224        { "-rdd",
225          FALSE,
226          etREAL,
227          { &domdecOptions.minimumCommunicationRange },
228          "The maximum distance for bonded interactions with DD (nm), 0 is determine from initial "
229          "coordinates" },
230        { "-rcon",
231          FALSE,
232          etREAL,
233          { &domdecOptions.constraintCommunicationRange },
234          "Maximum distance for P-LINCS (nm), 0 is estimate" },
235        { "-dlb", FALSE, etENUM, { dddlb_opt_choices }, "Dynamic load balancing (with DD)" },
236        { "-dds",
237          FALSE,
238          etREAL,
239          { &domdecOptions.dlbScaling },
240          "Fraction in (0,1) by whose reciprocal the initial DD cell size will be increased in "
241          "order to "
242          "provide a margin in which dynamic load balancing can act while preserving the minimum "
243          "cell size." },
244        { "-ddcsx",
245          FALSE,
246          etSTR,
247          { &domdecOptions.cellSizeX },
248          "HIDDENA string containing a vector of the relative sizes in the x "
249          "direction of the corresponding DD cells. Only effective with static "
250          "load balancing." },
251        { "-ddcsy",
252          FALSE,
253          etSTR,
254          { &domdecOptions.cellSizeY },
255          "HIDDENA string containing a vector of the relative sizes in the y "
256          "direction of the corresponding DD cells. Only effective with static "
257          "load balancing." },
258        { "-ddcsz",
259          FALSE,
260          etSTR,
261          { &domdecOptions.cellSizeZ },
262          "HIDDENA string containing a vector of the relative sizes in the z "
263          "direction of the corresponding DD cells. Only effective with static "
264          "load balancing." },
265        { "-nb", FALSE, etENUM, { nbpu_opt_choices }, "Calculate non-bonded interactions on" },
266        { "-nstlist",
267          FALSE,
268          etINT,
269          { &nstlist_cmdline },
270          "Set nstlist when using a Verlet buffer tolerance (0 is guess)" },
271        { "-tunepme",
272          FALSE,
273          etBOOL,
274          { &mdrunOptions.tunePme },
275          "Optimize PME load between PP/PME ranks or GPU/CPU" },
276        { "-pme", FALSE, etENUM, { pme_opt_choices }, "Perform PME calculations on" },
277        { "-pmefft", FALSE, etENUM, { pme_fft_opt_choices }, "Perform PME FFT calculations on" },
278        { "-bonded", FALSE, etENUM, { bonded_opt_choices }, "Perform bonded calculations on" },
279        { "-update", FALSE, etENUM, { update_opt_choices }, "Perform update and constraints on" },
280        { "-v", FALSE, etBOOL, { &mdrunOptions.verbose }, "Be loud and noisy" },
281        { "-pforce", FALSE, etREAL, { &pforce }, "Print all forces larger than this (kJ/mol nm)" },
282        { "-reprod",
283          FALSE,
284          etBOOL,
285          { &mdrunOptions.reproducible },
286          "Try to avoid optimizations that affect binary reproducibility" },
287        { "-cpt",
288          FALSE,
289          etREAL,
290          { &mdrunOptions.checkpointOptions.period },
291          "Checkpoint interval (minutes)" },
292        { "-cpnum",
293          FALSE,
294          etBOOL,
295          { &mdrunOptions.checkpointOptions.keepAndNumberCheckpointFiles },
296          "Keep and number checkpoint files" },
297        { "-append",
298          FALSE,
299          etBOOL,
300          { &appendOption },
301          "Append to previous output files when continuing from checkpoint instead of adding the "
302          "simulation part number to all file names" },
303        { "-nsteps",
304          FALSE,
305          etINT64,
306          { &mdrunOptions.numStepsCommandline },
307          "Run this number of steps (-1 means infinite, -2 means use mdp option, smaller is "
308          "invalid)" },
309        { "-maxh",
310          FALSE,
311          etREAL,
312          { &mdrunOptions.maximumHoursToRun },
313          "Terminate after 0.99 times this time (hours)" },
314        { "-replex",
315          FALSE,
316          etINT,
317          { &replExParams.exchangeInterval },
318          "Attempt replica exchange periodically with this period (steps)" },
319        { "-nex",
320          FALSE,
321          etINT,
322          { &replExParams.numExchanges },
323          "Number of random exchanges to carry out each exchange interval (N^3 is one suggestion). "
324          " -nex zero or not specified gives neighbor replica exchange." },
325        { "-reseed",
326          FALSE,
327          etINT,
328          { &replExParams.randomSeed },
329          "Seed for replica exchange, -1 is generate a seed" },
330        { "-imdport", FALSE, etINT, { &imdOptions.port }, "HIDDENIMD listening port" },
331        { "-imdwait",
332          FALSE,
333          etBOOL,
334          { &imdOptions.wait },
335          "HIDDENPause the simulation while no IMD client is connected" },
336        { "-imdterm",
337          FALSE,
338          etBOOL,
339          { &imdOptions.terminatable },
340          "HIDDENAllow termination of the simulation from IMD client" },
341        { "-imdpull",
342          FALSE,
343          etBOOL,
344          { &imdOptions.pull },
345          "HIDDENAllow pulling in the simulation from IMD client" },
346        { "-rerunvsite",
347          FALSE,
348          etBOOL,
349          { &mdrunOptions.rerunConstructVsites },
350          "HIDDENRecalculate virtual site coordinates with [TT]-rerun[tt]" },
351        { "-confout",
352          FALSE,
353          etBOOL,
354          { &mdrunOptions.writeConfout },
355          "HIDDENWrite the last configuration with [TT]-c[tt] and force checkpointing at the last "
356          "step" },
357        { "-stepout",
358          FALSE,
359          etINT,
360          { &mdrunOptions.verboseStepPrintInterval },
361          "HIDDENFrequency of writing the remaining wall clock time for the run" },
362        { "-resetstep",
363          FALSE,
364          etINT,
365          { &mdrunOptions.timingOptions.resetStep },
366          "HIDDENReset cycle counters after these many time steps" },
367        { "-resethway",
368          FALSE,
369          etBOOL,
370          { &mdrunOptions.timingOptions.resetHalfway },
371          "HIDDENReset the cycle counters after half the number of steps or halfway "
372          "[TT]-maxh[tt]" }
373    };
374    /*! \} */
375
376    //! Parses the command-line input and prepares to start mdrun.
377    int updateFromCommandLine(int argc, char** argv, ArrayRef<const char*> desc);
378
379    ~LegacyMdrunOptions();
380};
381
382} // end namespace gmx
383
384#endif
385