src/gromacs/trajectoryanalysis/cmdlinerunner.h

   1 /*
   2  * This file is part of the GROMACS molecular simulation package.
   3  *
   4  * Copyright (c) 2010,2011,2012,2013,2014 by the GROMACS development team.
   5  * Copyright (c) 2015,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 /*! \file
  37  * \brief
  38  * Declares gmx::TrajectoryAnalysisCommandLineRunner.
  39  *
  40  * \author Teemu Murtola <teemu.murtola@gmail.com>
  41  * \inpublicapi
  42  * \ingroup module_trajectoryanalysis
  43  */
  44 #ifndef GMX_TRAJECTORYANALYSIS_CMDLINERUNNER_H
  45 #define GMX_TRAJECTORYANALYSIS_CMDLINERUNNER_H
  46
  47 #include <functional>
  48 #include <memory>
  49
  50 #include "gromacs/trajectoryanalysis/analysismodule.h"
  51
  52 namespace gmx
  53 {
  54
  55 class CommandLineModuleManager;
  56 class ICommandLineOptionsModule;
  57
  58 /*! \brief
  59  * Runner for command-line trajectory analysis tools.
  60  *
  61  * This class provides static methods to implement a command-line analysis
  62  * program, given a TrajectoryAnalysisModule object (or a factory of such).
  63  * It takes care of common command-line parameters, initializing and evaluating
  64  * selections, and looping over trajectory frames.
  65  *
  66  * \inpublicapi
  67  * \ingroup module_trajectoryanalysis
  68  */
  69 class TrajectoryAnalysisCommandLineRunner
  70 {
  71 public:
  72     /*! \brief
  73      * Factory method type for creating a trajectory analysis module.
  74      *
  75      * This method allows the module creation to be postponed to the point
  76      * where the module is needed, reducing initialization costs in, e.g.,
  77      * the `gmx` binary, and simplifying exception handling.
  78      */
  79     typedef std::function<TrajectoryAnalysisModulePointer()> ModuleFactoryMethod;
  80
  81     /*! \brief
  82      * Implements a main() method that runs a given module.
  83      *
  84      * \tparam ModuleType  Trajectory analysis module.
  85      * \param  argc        \c argc passed to main().
  86      * \param  argv        \c argv passed to main().
  87      *
  88      * This method abstracts away all the logic required to implement a
  89      * main() method in user tools, allowing that to be changed without
  90      * requiring changes to the tools themselves.
  91      *
  92      * \p ModuleType should be default-constructible and derive from
  93      * TrajectoryAnalysisModule.
  94      *
  95      * Does not throw.  All exceptions are caught and handled internally.
  96      */
  97     template<class ModuleType>
  98     static int runAsMain(int argc, char* argv[])
  99     {
 100         return runAsMain(argc, argv, &createModule<ModuleType>);
 101     }
 102     /*! \brief
 103      * Implements a main() method that runs a given module.
 104      *
 105      * \param  argc        \c argc passed to main().
 106      * \param  argv        \c argv passed to main().
 107      * \param  factory     Function that creates the module on demand.
 108      *
 109      * Implements the template runAsMain(), but can also be used
 110      * independently.
 111      *
 112      * Does not throw.  All exceptions are caught and handled internally.
 113      */
 114     static int runAsMain(int argc, char* argv[], const ModuleFactoryMethod& factory);
 115     /*! \brief
 116      * Registers a command-line module that runs a given module.
 117      *
 118      * \param  manager     Manager to register the module to.
 119      * \param  name        Name of the module to register.
 120      * \param  description One-line description for the module to register.
 121      * \param  factory     Function that creates the module on demand.
 122      *
 123      * \p name and \p descriptions must be string constants or otherwise
 124      * stay valid for the duration of the program execution.
 125      */
 126     static void registerModule(CommandLineModuleManager*  manager,
 127                                const char*                name,
 128                                const char*                description,
 129                                const ModuleFactoryMethod& factory);
 130     /*! \brief
 131      * Create a command-line module that runs the provided analysis module.
 132      *
 133      * \param[in]  module     Module to run.
 134      * \returns    Command-line module that runs the provided analysis
 135      *      module.
 136      * \throws std::bad_alloc if out of memory.
 137      *
 138      * This is mainly provided for testing purposes that want to bypass
 139      * CommandLineModuleManager.
 140      */
 141     static std::unique_ptr<ICommandLineOptionsModule> createModule(TrajectoryAnalysisModulePointer module);
 142
 143 private:
 144     // Prevent instantiation.
 145     TrajectoryAnalysisCommandLineRunner() {}
 146
 147     /*! \brief
 148      * Creates a trajectory analysis module of a given type.
 149      *
 150      * \tparam ModuleType  Module to create.
 151      */
 152     template<class ModuleType>
 153     static TrajectoryAnalysisModulePointer createModule()
 154     {
 155         return TrajectoryAnalysisModulePointer(new ModuleType());
 156     }
 157 };
 158
 159 } // namespace gmx
 160
 161 #endif