*/
class Mdrunner
{
- public:
- /*! \brief Builder class to manage object creation.
- *
- * This class is a member of gmx::Mdrunner so that it can initialize
- * private members of gmx::Mdrunner.
- *
- * It is non-trivial to establish an initialized gmx::Mdrunner invariant,
- * so objects can be obtained by clients using a Builder or a move.
- * Clients cannot default initialize or copy gmx::Mdrunner.
- */
- class BuilderImplementation;
-
- ~Mdrunner();
-
- /*!
- * \brief Copy not allowed.
- *
- * An Mdrunner has unique resources and it is not clear whether any of
- * one of those resources should be duplicated or shared unless the
- * specific use case is known. Either build a fresh runner or use a
- * helper function for clearly indicated behavior. API clarification may
- * allow unambiguous initialization by copy in future versions.
- *
- * \{
- */
- Mdrunner(const Mdrunner &) = delete;
- Mdrunner &operator=(const Mdrunner &) = delete;
- /* \} */
-
- /*!
- * \brief Mdrunner objects can be passed by value via move semantics.
- *
- * \param handle runner instance to be moved from.
- * \{
- */
- Mdrunner(Mdrunner &&handle) noexcept;
- //NOLINTNEXTLINE(performance-noexcept-move-constructor) working around GCC bug 58265
- Mdrunner &operator=(Mdrunner &&handle) noexcept(BUGFREE_NOEXCEPT_STRING);
- /* \} */
-
- /*! \brief Driver routine, that calls the different simulation methods. */
- /*!
- * Currently, thread-MPI does not spawn threads until during mdrunner() and parallelism
- * is not initialized until some time during this call...
- */
- int mdrunner();
-
- /*!
- * \brief Add a potential to be evaluated during MD integration.
- *
- * \param restraint MD restraint potential to apply
- * \param name User-friendly plain-text name to uniquely identify the puller
- *
- * This implementation attaches an object providing the gmx::IRestraintPotential
- * interface.
- * \todo Mdrunner should fetch such resources from the SimulationContext
- * rather than offering this public interface.
- */
- void addPotential(std::shared_ptr<IRestraintPotential> restraint,
- const std::string &name);
-
- /*! \brief Prepare the thread-MPI communicator to have \c
- * numThreadsToLaunch ranks, by spawning new thread-MPI
- * threads.
- *
- * Called by mdrunner() to start a specific number of threads
- * (including the main thread) for thread-parallel runs. This
- * in turn calls mdrunner() for each thread. */
- void spawnThreads(int numThreadsToLaunch);
-
- /*! \brief Initializes a new Mdrunner from the master.
- *
- * Run this method in a new thread from a master runner to get additional
- * workers on spawned threads.
- *
- * \returns New Mdrunner instance suitable for thread-MPI work on new ranks.
- *
- * \internal
- * \todo clarify (multiple) invariants during MD runner start-up.
- * The runner state before and after launching threads is distinct enough that
- * it should be codified in the invariants of different classes. That would
- * mean that the object returned by this method would be of a different type
- * than the object held by the client up to the point of call, and its name
- * would be changed to "launchOnSpawnedThread" or something not including the
- * word "clone".
- */
- Mdrunner cloneOnSpawnedThread() const;
-
- private:
- /*! \brief Constructor. */
- explicit Mdrunner(std::unique_ptr<MDModules> mdModules);
-
- //! Parallelism-related user options.
- gmx_hw_opt_t hw_opt;
-
- //! Filenames and properties from command-line argument values.
- ArrayRef<const t_filenm> filenames;
-
- /*! \brief Output context for writing text files
- *
- * \internal
- * \todo push this data member down when the information can be queried from an encapsulated resource.
- */
- gmx_output_env_t *oenv = nullptr;
- //! Ongoing collection of mdrun options
- MdrunOptions mdrunOptions;
- //! Options for the domain decomposition.
- DomdecOptions domdecOptions;
-
- /*! \brief Target short-range interations for "cpu", "gpu", or "auto". Default is "auto".
- *
- * \internal
- * \todo replace with string or enum class and initialize with sensible value.
- */
- const char *nbpu_opt = nullptr;
-
- /*! \brief Target long-range interactions for "cpu", "gpu", or "auto". Default is "auto".
- *
- * \internal
- * \todo replace with string or enum class and initialize with sensible value.
- */
- const char *pme_opt = nullptr;
-
- /*! \brief Target long-range interactions FFT/solve stages for "cpu", "gpu", or "auto". Default is "auto".
- *
- * \internal
- * \todo replace with string or enum class and initialize with sensible value.
- */
- const char *pme_fft_opt = nullptr;
-
- /*! \brief Target bonded interations for "cpu", "gpu", or "auto". Default is "auto".
- *
- * \internal
- * \todo replace with string or enum class and initialize with sensible value.
- */
- const char *bonded_opt = nullptr;
-
- /*! \brief Target update calculation for "cpu", "gpu", or "auto". Default is "auto".
- *
- * \internal
- * \todo replace with string or enum class and initialize with sensible value.
- */
- const char *update_opt = nullptr;
-
- //! Command-line override for the duration of a neighbor list with the Verlet scheme.
- int nstlist_cmdline = 0;
- //! Parameters for replica-exchange simulations.
- ReplicaExchangeParameters replExParams;
- //! Print a warning if any force is larger than this (in kJ/mol nm).
- real pforce = -1;
-
- //! Handle to file used for logging.
- LogFilePtr logFileGuard = nullptr;
- //! \brief Non-owning handle to file used for logging.
- t_fileio *logFileHandle = nullptr;
-
- /*! \brief Non-owning handle to communication data structure.
- *
- * With real MPI, gets a value from the SimulationContext
- * supplied to the MdrunnerBuilder. With thread-MPI gets a
- * value after threads have been spawned. */
- MPI_Comm communicator = MPI_COMM_NULL;
-
- //! \brief Non-owning handle to multi-simulation handler.
- gmx_multisim_t *ms = nullptr;
-
- //! Whether the simulation will start afresh, or restart with/without appending.
- StartingBehavior startingBehavior = StartingBehavior::NewSimulation;
-
- /*!
- * \brief Handle to restraints manager for the current process.
- *
- * \internal
- * Use opaque pointer for this implementation detail.
- */
- std::unique_ptr<RestraintManager> restraintManager_;
-
- /*!
- * \brief Builder for stop signal handler
- *
- * Optionally provided through MdrunnerBuilder. Client may create a
- * StopHandlerBuilder and register any number of signal providers before
- * launching the Mdrunner.
- *
- * Default is an empty signal handler that will have local signal issuers
- * added after being passed into the integrator.
- *
- * \internal
- * We do not need a full type specification here, so we use an opaque pointer.
- */
- std::unique_ptr<StopHandlerBuilder> stopHandlerBuilder_;
- //! The modules that comprise mdrun.
- std::unique_ptr<MDModules> mdModules_;
+public:
+ /*! \brief Builder class to manage object creation.
+ *
+ * This class is a member of gmx::Mdrunner so that it can initialize
+ * private members of gmx::Mdrunner.
+ *
+ * It is non-trivial to establish an initialized gmx::Mdrunner invariant,
+ * so objects can be obtained by clients using a Builder or a move.
+ * Clients cannot default initialize or copy gmx::Mdrunner.
+ */
+ class BuilderImplementation;
+
+ ~Mdrunner();
+
+ /*!
+ * \brief Copy not allowed.
+ *
+ * An Mdrunner has unique resources and it is not clear whether any of
+ * one of those resources should be duplicated or shared unless the
+ * specific use case is known. Either build a fresh runner or use a
+ * helper function for clearly indicated behavior. API clarification may
+ * allow unambiguous initialization by copy in future versions.
+ *
+ * \{
+ */
+ Mdrunner(const Mdrunner&) = delete;
+ Mdrunner& operator=(const Mdrunner&) = delete;
+ /* \} */
+
+ /*!
+ * \brief Mdrunner objects can be passed by value via move semantics.
+ *
+ * \param handle runner instance to be moved from.
+ * \{
+ */
+ Mdrunner(Mdrunner&& handle) noexcept;
+ //NOLINTNEXTLINE(performance-noexcept-move-constructor) working around GCC bug 58265
+ Mdrunner& operator=(Mdrunner&& handle) noexcept(BUGFREE_NOEXCEPT_STRING);
+ /* \} */
+
+ /*! \brief Driver routine, that calls the different simulation methods. */
+ /*!
+ * Currently, thread-MPI does not spawn threads until during mdrunner() and parallelism
+ * is not initialized until some time during this call...
+ */
+ int mdrunner();
+
+ /*!
+ * \brief Add a potential to be evaluated during MD integration.
+ *
+ * \param restraint MD restraint potential to apply
+ * \param name User-friendly plain-text name to uniquely identify the puller
+ *
+ * This implementation attaches an object providing the gmx::IRestraintPotential
+ * interface.
+ * \todo Mdrunner should fetch such resources from the SimulationContext
+ * rather than offering this public interface.
+ */
+ void addPotential(std::shared_ptr<IRestraintPotential> restraint, const std::string& name);
+
+ /*! \brief Prepare the thread-MPI communicator to have \c
+ * numThreadsToLaunch ranks, by spawning new thread-MPI
+ * threads.
+ *
+ * Called by mdrunner() to start a specific number of threads
+ * (including the main thread) for thread-parallel runs. This
+ * in turn calls mdrunner() for each thread. */
+ void spawnThreads(int numThreadsToLaunch);
+
+ /*! \brief Initializes a new Mdrunner from the master.
+ *
+ * Run this method in a new thread from a master runner to get additional
+ * workers on spawned threads.
+ *
+ * \returns New Mdrunner instance suitable for thread-MPI work on new ranks.
+ *
+ * \internal
+ * \todo clarify (multiple) invariants during MD runner start-up.
+ * The runner state before and after launching threads is distinct enough that
+ * it should be codified in the invariants of different classes. That would
+ * mean that the object returned by this method would be of a different type
+ * than the object held by the client up to the point of call, and its name
+ * would be changed to "launchOnSpawnedThread" or something not including the
+ * word "clone".
+ */
+ Mdrunner cloneOnSpawnedThread() const;
+
+private:
+ /*! \brief Constructor. */
+ explicit Mdrunner(std::unique_ptr<MDModules> mdModules);
+
+ //! Parallelism-related user options.
+ gmx_hw_opt_t hw_opt;
+
+ //! Filenames and properties from command-line argument values.
+ ArrayRef<const t_filenm> filenames;
+
+ /*! \brief Output context for writing text files
+ *
+ * \internal
+ * \todo push this data member down when the information can be queried from an encapsulated resource.
+ */
+ gmx_output_env_t* oenv = nullptr;
+ //! Ongoing collection of mdrun options
+ MdrunOptions mdrunOptions;
+ //! Options for the domain decomposition.
+ DomdecOptions domdecOptions;
+
+ /*! \brief Target short-range interations for "cpu", "gpu", or "auto". Default is "auto".
+ *
+ * \internal
+ * \todo replace with string or enum class and initialize with sensible value.
+ */
+ const char* nbpu_opt = nullptr;
+
+ /*! \brief Target long-range interactions for "cpu", "gpu", or "auto". Default is "auto".
+ *
+ * \internal
+ * \todo replace with string or enum class and initialize with sensible value.
+ */
+ const char* pme_opt = nullptr;
+
+ /*! \brief Target long-range interactions FFT/solve stages for "cpu", "gpu", or "auto". Default is "auto".
+ *
+ * \internal
+ * \todo replace with string or enum class and initialize with sensible value.
+ */
+ const char* pme_fft_opt = nullptr;
+
+ /*! \brief Target bonded interations for "cpu", "gpu", or "auto". Default is "auto".
+ *
+ * \internal
+ * \todo replace with string or enum class and initialize with sensible value.
+ */
+ const char* bonded_opt = nullptr;
+
+ /*! \brief Target update calculation for "cpu", "gpu", or "auto". Default is "auto".
+ *
+ * \internal
+ * \todo replace with string or enum class and initialize with sensible value.
+ */
+ const char* update_opt = nullptr;
+
+ //! Command-line override for the duration of a neighbor list with the Verlet scheme.
+ int nstlist_cmdline = 0;
+ //! Parameters for replica-exchange simulations.
+ ReplicaExchangeParameters replExParams;
+ //! Print a warning if any force is larger than this (in kJ/mol nm).
+ real pforce = -1;
+
+ //! Handle to file used for logging.
+ LogFilePtr logFileGuard = nullptr;
+ //! \brief Non-owning handle to file used for logging.
+ t_fileio* logFileHandle = nullptr;
+
+ /*! \brief Non-owning handle to communication data structure.
+ *
+ * With real MPI, gets a value from the SimulationContext
+ * supplied to the MdrunnerBuilder. With thread-MPI gets a
+ * value after threads have been spawned. */
+ MPI_Comm communicator = MPI_COMM_NULL;
+
+ //! \brief Non-owning handle to multi-simulation handler.
+ gmx_multisim_t* ms = nullptr;
+
+ //! Whether the simulation will start afresh, or restart with/without appending.
+ StartingBehavior startingBehavior = StartingBehavior::NewSimulation;
+
+ /*!
+ * \brief Handle to restraints manager for the current process.
+ *
+ * \internal
+ * Use opaque pointer for this implementation detail.
+ */
+ std::unique_ptr<RestraintManager> restraintManager_;
+
+ /*!
+ * \brief Builder for stop signal handler
+ *
+ * Optionally provided through MdrunnerBuilder. Client may create a
+ * StopHandlerBuilder and register any number of signal providers before
+ * launching the Mdrunner.
+ *
+ * Default is an empty signal handler that will have local signal issuers
+ * added after being passed into the integrator.
+ *
+ * \internal
+ * We do not need a full type specification here, so we use an opaque pointer.
+ */
+ std::unique_ptr<StopHandlerBuilder> stopHandlerBuilder_;
+ //! The modules that comprise mdrun.
+ std::unique_ptr<MDModules> mdModules_;
};
/*! \libinternal
*/
class MdrunnerBuilder final
{
- public:
- /*!
- * \brief Constructor requires a handle to a SimulationContext to share.
- *
- * \param mdModules The handle to the set of modules active in mdrun
- * \param context Required handle to simulation context
- *
- * The calling code must guarantee that the
- * pointer remains valid for the lifetime of the builder, and that the
- * resources retrieved from the context remain valid for the lifetime of
- * the runner produced.
- */
- explicit MdrunnerBuilder(std::unique_ptr<MDModules> mdModules,
- compat::not_null<SimulationContext*> context);
-
- //! \cond
- MdrunnerBuilder() = delete;
- MdrunnerBuilder(const MdrunnerBuilder&) = delete;
- MdrunnerBuilder &operator=(const MdrunnerBuilder &) = delete;
- //! \endcond
-
- /*! \brief Allow transfer of ownership with move semantics.
- *
- * \param builder source object to transfer.
- *
- * \{
- */
- MdrunnerBuilder(MdrunnerBuilder && builder) noexcept;
- MdrunnerBuilder &operator=(MdrunnerBuilder &&builder) noexcept;
- //! \}
-
- /*!
- * \brief Get ownership of an initialized gmx::Mdrunner.
- *
- * After build() is called, the Builder object should not be used
- * again. It is an error to call build without first calling all builder
- * methods described as "required."
- *
- * \return A new Mdrunner.
- *
- * \throws APIError if a required component has not been added before calling build().
- */
- Mdrunner build();
-
- /*!
- * \brief Set up non-bonded short-range force calculations.
- *
- * Required. Director code must provide valid options for the non-bonded
- * interaction code. The builder does not apply any defaults.
- *
- * \param nbpu_opt Target short-range interactions for "cpu", "gpu", or "auto".
- *
- * Calling must guarantee that the pointed-to C string is valid through
- * simulation launch.
- *
- * \internal
- * \todo Replace with string or enum that we can have sensible defaults for.
- * \todo Either the Builder or modular Director code should provide sensible defaults.
- */
- MdrunnerBuilder &addNonBonded(const char* nbpu_opt);
-
- /*!
- * \brief Set up long-range electrostatics calculations.
- *
- * Required. Director code should provide valid options for PME electrostatics,
- * whether or not PME electrostatics are used. The builder does not apply
- * any defaults, so client code should be prepared to provide (e.g.) "auto"
- * in the event no user input or logic provides an alternative argument.
- *
- * \param pme_opt Target long-range interactions for "cpu", "gpu", or "auto".
- * \param pme_fft_opt Target long-range interactions FFT/solve stages for "cpu", "gpu", or "auto".
- *
- * Calling must guarantee that the pointed-to C strings are valid through
- * simulation launch.
- *
- * \internal
- * The arguments are passed as references to elements of arrays of C strings.
- * \todo Replace with modern strings or (better) enum classes.
- * \todo Make optional and/or encapsulate into electrostatics module.
- */
- MdrunnerBuilder &addElectrostatics(const char* pme_opt,
- const char* pme_fft_opt);
-
- /*!
- * \brief Assign responsibility for tasks for bonded interactions.
- *
- * Required. Director code should provide valid options for
- * bonded interaction task assignment, whether or not such
- * interactions are present. The builder does not apply any
- * defaults, so client code should be prepared to provide
- * (e.g.) "auto" in the event no user input or logic provides
- * an alternative argument.
- *
- * \param bonded_opt Target bonded interactions for "cpu", "gpu", or "auto".
- *
- * Calling must guarantee that the pointed-to C strings are valid through
- * simulation launch.
- *
- * \internal
- * The arguments are passed as references to elements of arrays of C strings.
- * \todo Replace with modern strings or (better) enum classes.
- * \todo Make optional and/or encapsulate into task assignment module.
- */
- MdrunnerBuilder &addBondedTaskAssignment(const char *bonded_opt);
-
- /*! \brief
- * Assign responsibility for tasks for update and constrain calculation.
- *
- * Required. Director code should provide valid options for
- * update and constraint task assignment. The builder does not apply any
- * defaults, so client code should be prepared to provide
- * (e.g.) "auto" in the event no user input or logic provides
- * an alternative argument.
- *
- * \param[in] update_opt Target update calculation for "cpu", "gpu", or "auto".
- *
- * Calling must guarantee that the pointed-to C strings are valid through
- * simulation launch.
- *
- * \internal
- * The arguments are passed as references to elements of arrays of C strings.
- * \todo Replace with modern strings or (better) enum classes.
- * \todo Make optional and/or encapsulate into task assignment module.
- */
- MdrunnerBuilder &addUpdateTaskAssignment(const char *update_opt);
-
- /*!
- * \brief Set MD options not owned by some other module.
- *
- * Optional. Override simulation parameters
- *
- * \param options structure to copy
- * \param forceWarningThreshold Print a warning if any force is larger than this (in kJ/mol nm) (default -1)
- * \param startingBehavior Whether the simulation will start afresh, or restart with/without appending.
- *
- * \internal
- * \todo Map these parameters to more appropriate encapsulating types.
- * Find a better way to indicate "unspecified" than a magic value of the parameter type.
- */
- MdrunnerBuilder &addSimulationMethod(const MdrunOptions &options,
- real forceWarningThreshold,
- StartingBehavior startingBehavior);
-
- /*!
- * \brief Set the domain decomposition module.
- *
- * Optional. Overrides default constructed DomdecOptions if provided.
- *
- * \param options options with which to construct domain decomposition.
- *
- * \internal
- * \todo revisit whether we should be passing this parameter struct or a higher-level handle of some sort.
- */
- MdrunnerBuilder &addDomainDecomposition(const DomdecOptions &options);
-
- /*!
- * \brief Set Verlet list manager.
- *
- * Optional. Neighbor list existence, type, and parameters are mostly determined
- * by the simulation parameters loaded elsewhere. This is just an override.
- *
- * \param rebuildInterval override for the duration of a neighbor list with the Verlet scheme.
- */
- MdrunnerBuilder &addNeighborList(int rebuildInterval);
-
- /*!
- * \brief Set replica exchange manager.
- *
- * Optional. For guidance on preparing a valid ReplicaExchangeParameters
- * value, refer to the details in mdrun.cpp, the `t_pargs pa[]` defined there,
- * and the action of parse_common_args() with regards to that structure.
- * If not provided by client, a default constructed ReplicaExchangeParameters
- * is used.
- *
- * \param params parameters with which to set up replica exchange.
- *
- * \internal
- * \todo revisit whether we should be passing this parameter struct or a higher-level handle of some sort.
- */
- MdrunnerBuilder &addReplicaExchange(const ReplicaExchangeParameters ¶ms);
-
- /*!
- * \brief Specify parameters determining hardware resource allocation.
- *
- * Optional. If not provided, default-constructed gmx_hw_opt_t will be used.
- *
- * \param hardwareOptions Parallelism-related user options.
- */
- MdrunnerBuilder &addHardwareOptions(const gmx_hw_opt_t &hardwareOptions);
-
- /*!
- * \brief Provide the filenames options structure with option values chosen
- *
- * Required. The object is assumed to have been updated by
- * parse_common_args or equivalent.
- *
- * \param filenames Filenames and properties from command-line argument values or defaults.
- *
- * \internal
- * \todo Modules should manage their own filename options and defaults.
- */
- MdrunnerBuilder &addFilenames(ArrayRef<const t_filenm> filenames);
-
- /*!
- * \brief Provide parameters for setting up output environment.
- *
- * Required. Handle is assumed to have been produced by output_env_init
- * as in parse_common_args.
- *
- * \param outputEnvironment Output context for writing text files.
- *
- * \internal
- * \todo Allow client code to set up output environment and provide as a resource.
- * This parameter is used to set up resources that are dependent on the execution
- * environment and API context. Such resources should be retrieved by the simulator
- * from a client-provided resource, but currently the resources are only fully
- * initialized in Mdrunner.
- */
- MdrunnerBuilder &addOutputEnvironment(gmx_output_env_t* outputEnvironment);
-
- /*!
- * \brief Provide the filehandle pointer to be used for the MD log.
- *
- * Required. Either nullptr if no log should be written, or
- * valid and open reading for writing.
- *
- * \param logFileHandle Non-owning handle to file used for logging.
- * \internal
- */
- MdrunnerBuilder &addLogFile(t_fileio *logFileHandle);
-
- /*!
- * \brief Provide a StopHandlerBuilder for the MD stop signal handling.
- *
- * Optional. Defaults to empty.
- *
- * Client may provide additional (non-default) issuers of simulation stop
- * signals by preconfiguring the StopHandlerBuilder used later when the
- * simulation runs.
- *
- * \param builder
- */
- MdrunnerBuilder &addStopHandlerBuilder(std::unique_ptr<StopHandlerBuilder> builder);
-
- ~MdrunnerBuilder();
-
- private:
- std::unique_ptr<Mdrunner::BuilderImplementation> impl_;
+public:
+ /*!
+ * \brief Constructor requires a handle to a SimulationContext to share.
+ *
+ * \param mdModules The handle to the set of modules active in mdrun
+ * \param context Required handle to simulation context
+ *
+ * The calling code must guarantee that the
+ * pointer remains valid for the lifetime of the builder, and that the
+ * resources retrieved from the context remain valid for the lifetime of
+ * the runner produced.
+ */
+ explicit MdrunnerBuilder(std::unique_ptr<MDModules> mdModules,
+ compat::not_null<SimulationContext*> context);
+
+ //! \cond
+ MdrunnerBuilder() = delete;
+ MdrunnerBuilder(const MdrunnerBuilder&) = delete;
+ MdrunnerBuilder& operator=(const MdrunnerBuilder&) = delete;
+ //! \endcond
+
+ /*! \brief Allow transfer of ownership with move semantics.
+ *
+ * \param builder source object to transfer.
+ *
+ * \{
+ */
+ MdrunnerBuilder(MdrunnerBuilder&& builder) noexcept;
+ MdrunnerBuilder& operator=(MdrunnerBuilder&& builder) noexcept;
+ //! \}
+
+ /*!
+ * \brief Get ownership of an initialized gmx::Mdrunner.
+ *
+ * After build() is called, the Builder object should not be used
+ * again. It is an error to call build without first calling all builder
+ * methods described as "required."
+ *
+ * \return A new Mdrunner.
+ *
+ * \throws APIError if a required component has not been added before calling build().
+ */
+ Mdrunner build();
+
+ /*!
+ * \brief Set up non-bonded short-range force calculations.
+ *
+ * Required. Director code must provide valid options for the non-bonded
+ * interaction code. The builder does not apply any defaults.
+ *
+ * \param nbpu_opt Target short-range interactions for "cpu", "gpu", or "auto".
+ *
+ * Calling must guarantee that the pointed-to C string is valid through
+ * simulation launch.
+ *
+ * \internal
+ * \todo Replace with string or enum that we can have sensible defaults for.
+ * \todo Either the Builder or modular Director code should provide sensible defaults.
+ */
+ MdrunnerBuilder& addNonBonded(const char* nbpu_opt);
+
+ /*!
+ * \brief Set up long-range electrostatics calculations.
+ *
+ * Required. Director code should provide valid options for PME electrostatics,
+ * whether or not PME electrostatics are used. The builder does not apply
+ * any defaults, so client code should be prepared to provide (e.g.) "auto"
+ * in the event no user input or logic provides an alternative argument.
+ *
+ * \param pme_opt Target long-range interactions for "cpu", "gpu", or "auto".
+ * \param pme_fft_opt Target long-range interactions FFT/solve stages for "cpu", "gpu", or "auto".
+ *
+ * Calling must guarantee that the pointed-to C strings are valid through
+ * simulation launch.
+ *
+ * \internal
+ * The arguments are passed as references to elements of arrays of C strings.
+ * \todo Replace with modern strings or (better) enum classes.
+ * \todo Make optional and/or encapsulate into electrostatics module.
+ */
+ MdrunnerBuilder& addElectrostatics(const char* pme_opt, const char* pme_fft_opt);
+
+ /*!
+ * \brief Assign responsibility for tasks for bonded interactions.
+ *
+ * Required. Director code should provide valid options for
+ * bonded interaction task assignment, whether or not such
+ * interactions are present. The builder does not apply any
+ * defaults, so client code should be prepared to provide
+ * (e.g.) "auto" in the event no user input or logic provides
+ * an alternative argument.
+ *
+ * \param bonded_opt Target bonded interactions for "cpu", "gpu", or "auto".
+ *
+ * Calling must guarantee that the pointed-to C strings are valid through
+ * simulation launch.
+ *
+ * \internal
+ * The arguments are passed as references to elements of arrays of C strings.
+ * \todo Replace with modern strings or (better) enum classes.
+ * \todo Make optional and/or encapsulate into task assignment module.
+ */
+ MdrunnerBuilder& addBondedTaskAssignment(const char* bonded_opt);
+
+ /*! \brief
+ * Assign responsibility for tasks for update and constrain calculation.
+ *
+ * Required. Director code should provide valid options for
+ * update and constraint task assignment. The builder does not apply any
+ * defaults, so client code should be prepared to provide
+ * (e.g.) "auto" in the event no user input or logic provides
+ * an alternative argument.
+ *
+ * \param[in] update_opt Target update calculation for "cpu", "gpu", or "auto".
+ *
+ * Calling must guarantee that the pointed-to C strings are valid through
+ * simulation launch.
+ *
+ * \internal
+ * The arguments are passed as references to elements of arrays of C strings.
+ * \todo Replace with modern strings or (better) enum classes.
+ * \todo Make optional and/or encapsulate into task assignment module.
+ */
+ MdrunnerBuilder& addUpdateTaskAssignment(const char* update_opt);
+
+ /*!
+ * \brief Set MD options not owned by some other module.
+ *
+ * Optional. Override simulation parameters
+ *
+ * \param options structure to copy
+ * \param forceWarningThreshold Print a warning if any force is larger than this (in kJ/mol nm) (default -1)
+ * \param startingBehavior Whether the simulation will start afresh, or restart with/without appending.
+ *
+ * \internal
+ * \todo Map these parameters to more appropriate encapsulating types.
+ * Find a better way to indicate "unspecified" than a magic value of the parameter type.
+ */
+ MdrunnerBuilder& addSimulationMethod(const MdrunOptions& options,
+ real forceWarningThreshold,
+ StartingBehavior startingBehavior);
+
+ /*!
+ * \brief Set the domain decomposition module.
+ *
+ * Optional. Overrides default constructed DomdecOptions if provided.
+ *
+ * \param options options with which to construct domain decomposition.
+ *
+ * \internal
+ * \todo revisit whether we should be passing this parameter struct or a higher-level handle of some sort.
+ */
+ MdrunnerBuilder& addDomainDecomposition(const DomdecOptions& options);
+
+ /*!
+ * \brief Set Verlet list manager.
+ *
+ * Optional. Neighbor list existence, type, and parameters are mostly determined
+ * by the simulation parameters loaded elsewhere. This is just an override.
+ *
+ * \param rebuildInterval override for the duration of a neighbor list with the Verlet scheme.
+ */
+ MdrunnerBuilder& addNeighborList(int rebuildInterval);
+
+ /*!
+ * \brief Set replica exchange manager.
+ *
+ * Optional. For guidance on preparing a valid ReplicaExchangeParameters
+ * value, refer to the details in mdrun.cpp, the `t_pargs pa[]` defined there,
+ * and the action of parse_common_args() with regards to that structure.
+ * If not provided by client, a default constructed ReplicaExchangeParameters
+ * is used.
+ *
+ * \param params parameters with which to set up replica exchange.
+ *
+ * \internal
+ * \todo revisit whether we should be passing this parameter struct or a higher-level handle of some sort.
+ */
+ MdrunnerBuilder& addReplicaExchange(const ReplicaExchangeParameters& params);
+
+ /*!
+ * \brief Specify parameters determining hardware resource allocation.
+ *
+ * Optional. If not provided, default-constructed gmx_hw_opt_t will be used.
+ *
+ * \param hardwareOptions Parallelism-related user options.
+ */
+ MdrunnerBuilder& addHardwareOptions(const gmx_hw_opt_t& hardwareOptions);
+
+ /*!
+ * \brief Provide the filenames options structure with option values chosen
+ *
+ * Required. The object is assumed to have been updated by
+ * parse_common_args or equivalent.
+ *
+ * \param filenames Filenames and properties from command-line argument values or defaults.
+ *
+ * \internal
+ * \todo Modules should manage their own filename options and defaults.
+ */
+ MdrunnerBuilder& addFilenames(ArrayRef<const t_filenm> filenames);
+
+ /*!
+ * \brief Provide parameters for setting up output environment.
+ *
+ * Required. Handle is assumed to have been produced by output_env_init
+ * as in parse_common_args.
+ *
+ * \param outputEnvironment Output context for writing text files.
+ *
+ * \internal
+ * \todo Allow client code to set up output environment and provide as a resource.
+ * This parameter is used to set up resources that are dependent on the execution
+ * environment and API context. Such resources should be retrieved by the simulator
+ * from a client-provided resource, but currently the resources are only fully
+ * initialized in Mdrunner.
+ */
+ MdrunnerBuilder& addOutputEnvironment(gmx_output_env_t* outputEnvironment);
+
+ /*!
+ * \brief Provide the filehandle pointer to be used for the MD log.
+ *
+ * Required. Either nullptr if no log should be written, or
+ * valid and open reading for writing.
+ *
+ * \param logFileHandle Non-owning handle to file used for logging.
+ * \internal
+ */
+ MdrunnerBuilder& addLogFile(t_fileio* logFileHandle);
+
+ /*!
+ * \brief Provide a StopHandlerBuilder for the MD stop signal handling.
+ *
+ * Optional. Defaults to empty.
+ *
+ * Client may provide additional (non-default) issuers of simulation stop
+ * signals by preconfiguring the StopHandlerBuilder used later when the
+ * simulation runs.
+ *
+ * \param builder
+ */
+ MdrunnerBuilder& addStopHandlerBuilder(std::unique_ptr<StopHandlerBuilder> builder);
+
+ ~MdrunnerBuilder();
+
+private:
+ std::unique_ptr<Mdrunner::BuilderImplementation> impl_;
};
-} // namespace gmx
+} // namespace gmx
#endif // GMX_MDRUN_RUNNER_H
biod.pnpi.spb.ru / alexxy / gromacs.git / blobdiff