|
Gromacs
2025.0-dev-20241011-013a99c
|
All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
|
Gromacs
2025.0-dev-20241011-013a99c
|
#include <gromacs/mdrun/runner.h>
Build a gmx::Mdrunner.
Client code (such as gmx mdrun) uses this builder to get an initialized Mdrunner.
A builder allows the library to ensure that client code cannot obtain an uninitialized or partially initialized runner by refusing to build() if the client has not provided sufficient or self-consistent direction. Director code can be implemented for different user interfaces, encapsulating any run-time functionality that does not belong in the library MD code, such as command-line option processing or interfacing to external libraries.
The initial Builder implementation is neither extensible at run time nor at compile time. Future implementations should evolve to compose the runner, rather than just consolidating the parameters for initialization, but there is not yet a firm design for how flexibly module code will be coupled to the builder and how much of the client interface will be in this Builder versus Builders provided by the various modules.
The named components for the initial builder implementation are descriptive of the state of mdrun at the time, and are not intended to be prescriptive of future design. The probable course of GROMACS development is for the modular components that support MD simulation to independently express their input parameters (required and optional) and to provide some sort of help to the UI for input preparation. If each module provides or aids the instantiation of a Director for the client code, the Directors could be constructed with a handle to this Builder and it would not need a public interface.
As the modules are more clearly encapsulated, each module can provide its own builder, user interface helpers, and/or composable Director code. The runner and client code will also have to be updated as appropriate default behavior is clarified for (a) default behavior of client when user does not provide input, (b) default behavior of builder when client does not provide input, and (c) default behavior of runner when builder does not provide input.
Public Member Functions | |
| MdrunnerBuilder (std::unique_ptr< MDModules > mdModules, compat::not_null< SimulationContext * > context) | |
| Constructor requires a handle to a SimulationContext to share. More... | |
| Mdrunner | build () |
| Get ownership of an initialized gmx::Mdrunner. More... | |
| MdrunnerBuilder & | addHardwareDetectionResult (const gmx_hw_info_t *hwinfo) |
| Supply the result of hardware detection to the gmx::Mdrunner. More... | |
| MdrunnerBuilder & | addNonBonded (const char *nbpu_opt) |
| Set up non-bonded short-range force calculations. More... | |
| MdrunnerBuilder & | addElectrostatics (const char *pme_opt, const char *pme_fft_opt) |
| Set up long-range electrostatics calculations. More... | |
| MdrunnerBuilder & | addBondedTaskAssignment (const char *bonded_opt) |
| Assign responsibility for tasks for bonded interactions. More... | |
| MdrunnerBuilder & | addUpdateTaskAssignment (const char *update_opt) |
| Assign responsibility for tasks for update and constrain calculation. More... | |
| MdrunnerBuilder & | addSimulationMethod (const MdrunOptions &options, real forceWarningThreshold, StartingBehavior startingBehavior) |
| Set MD options not owned by some other module. More... | |
| MdrunnerBuilder & | addDomainDecomposition (const DomdecOptions &options) |
| Set the domain decomposition module. More... | |
| MdrunnerBuilder & | addNeighborList (int rebuildInterval) |
| Set Verlet list manager. More... | |
| MdrunnerBuilder & | addReplicaExchange (const ReplicaExchangeParameters ¶ms) |
| Set replica exchange manager. More... | |
| MdrunnerBuilder & | addHardwareOptions (const gmx_hw_opt_t &hardwareOptions) |
| Specify parameters determining hardware resource allocation. More... | |
| MdrunnerBuilder & | addFilenames (ArrayRef< const t_filenm > filenames) |
| Provide the filenames options structure with option values chosen. More... | |
| MdrunnerBuilder & | addOutputEnvironment (gmx_output_env_t *outputEnvironment) |
| Provide parameters for setting up output environment. More... | |
| MdrunnerBuilder & | addLogFile (t_fileio *logFileHandle) |
| Provide the filehandle pointer to be used for the MD log. More... | |
| MdrunnerBuilder & | addStopHandlerBuilder (std::unique_ptr< StopHandlerBuilder > builder) |
| Provide a StopHandlerBuilder for the MD stop signal handling. More... | |
| MdrunnerBuilder & | addInput (SimulationInputHandle input) |
| Acquire a handle to the SimulationInput. More... | |
| MdrunnerBuilder (MdrunnerBuilder &&builder) noexcept | |
| Allow transfer of ownership with move semantics. More... | |
| MdrunnerBuilder & | operator= (MdrunnerBuilder &&builder) noexcept |
|
explicit |
Constructor requires a handle to a SimulationContext to share.
| mdModules | The handle to the set of modules active in mdrun |
| 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.
|
defaultnoexcept |
Allow transfer of ownership with move semantics.
| builder | source object to transfer. |
| MdrunnerBuilder & gmx::MdrunnerBuilder::addBondedTaskAssignment | ( | const char * | bonded_opt | ) |
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.
| bonded_opt | Target bonded interactions for "cpu", "gpu", or "auto". |
Calling must guarantee that the pointed-to C strings are valid through simulation launch.
The arguments are passed as references to elements of arrays of C strings.
Replace with modern strings or (better) enum classes.
Make optional and/or encapsulate into task assignment module.
| MdrunnerBuilder & gmx::MdrunnerBuilder::addDomainDecomposition | ( | const DomdecOptions & | options | ) |
Set the domain decomposition module.
Optional. Overrides default constructed DomdecOptions if provided.
| options | options with which to construct domain decomposition. |
| MdrunnerBuilder & gmx::MdrunnerBuilder::addElectrostatics | ( | const char * | pme_opt, |
| const char * | pme_fft_opt | ||
| ) |
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.
| pme_opt | Target long-range interactions for "cpu", "gpu", or "auto". |
| 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.
The arguments are passed as references to elements of arrays of C strings.
Replace with modern strings or (better) enum classes.
Make optional and/or encapsulate into electrostatics module.
| MdrunnerBuilder & gmx::MdrunnerBuilder::addFilenames | ( | ArrayRef< const t_filenm > | filenames | ) |
Provide the filenames options structure with option values chosen.
Required. The object is assumed to have been updated by parse_common_args or equivalent.
| filenames | Filenames and properties from command-line argument values or defaults. |
| MdrunnerBuilder & gmx::MdrunnerBuilder::addHardwareDetectionResult | ( | const gmx_hw_info_t * | hwinfo | ) |
Supply the result of hardware detection to the gmx::Mdrunner.
| hwinfo | Non-owning not-null handle to result of hardware detection. |
| MdrunnerBuilder & gmx::MdrunnerBuilder::addHardwareOptions | ( | const gmx_hw_opt_t & | hardwareOptions | ) |
Specify parameters determining hardware resource allocation.
Optional. If not provided, default-constructed gmx_hw_opt_t will be used.
| hardwareOptions | Parallelism-related user options. |
| MdrunnerBuilder & gmx::MdrunnerBuilder::addInput | ( | SimulationInputHandle | input | ) |
Acquire a handle to the SimulationInput.
Required. SimulationInput will be taking responsibility for some of the input provided through other methods, such as addFilenames.
See also issue https://gitlab.com/gromacs/gromacs/-/issues/3374
| input | Shared ownership of a SimulationInput. |
| MdrunnerBuilder & gmx::MdrunnerBuilder::addLogFile | ( | t_fileio * | logFileHandle | ) |
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.
| logFileHandle | Non-owning handle to file used for logging. |
| MdrunnerBuilder & gmx::MdrunnerBuilder::addNeighborList | ( | int | rebuildInterval | ) |
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.
| rebuildInterval | override for the duration of a neighbor list with the Verlet scheme. |
| MdrunnerBuilder & gmx::MdrunnerBuilder::addNonBonded | ( | const char * | nbpu_opt | ) |
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.
| 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.
Replace with string or enum that we can have sensible defaults for.
Either the Builder or modular Director code should provide sensible defaults.
| MdrunnerBuilder & gmx::MdrunnerBuilder::addOutputEnvironment | ( | gmx_output_env_t * | outputEnvironment | ) |
Provide parameters for setting up output environment.
Required. Handle is assumed to have been produced by output_env_init as in parse_common_args.
| outputEnvironment | Output context for writing text files. |
| MdrunnerBuilder & gmx::MdrunnerBuilder::addReplicaExchange | ( | const ReplicaExchangeParameters & | params | ) |
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.
| params | parameters with which to set up replica exchange. |
| MdrunnerBuilder & gmx::MdrunnerBuilder::addSimulationMethod | ( | const MdrunOptions & | options, |
| real | forceWarningThreshold, | ||
| StartingBehavior | startingBehavior | ||
| ) |
Set MD options not owned by some other module.
Optional. Override simulation parameters
| options | structure to copy |
| forceWarningThreshold | Print a warning if any force is larger than this (in kJ/mol nm) (default -1) |
| startingBehavior | Whether the simulation will start afresh, or restart with/without appending. |
| MdrunnerBuilder & gmx::MdrunnerBuilder::addStopHandlerBuilder | ( | std::unique_ptr< StopHandlerBuilder > | builder | ) |
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.
| builder |
| MdrunnerBuilder & gmx::MdrunnerBuilder::addUpdateTaskAssignment | ( | const char * | update_opt | ) |
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.
| [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.
The arguments are passed as references to elements of arrays of C strings.
Replace with modern strings or (better) enum classes.
Make optional and/or encapsulate into task assignment module.
| Mdrunner gmx::MdrunnerBuilder::build | ( | ) |
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."
1.8.5