Gromacs  2020.4
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
List of all members | Public Member Functions
gmx::MdrunnerBuilder Class Referencefinal

#include <gromacs/mdrun/runner.h>

Description

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...
 
MdrunnerBuilderaddNonBonded (const char *nbpu_opt)
 Set up non-bonded short-range force calculations. More...
 
MdrunnerBuilderaddElectrostatics (const char *pme_opt, const char *pme_fft_opt)
 Set up long-range electrostatics calculations. More...
 
MdrunnerBuilderaddBondedTaskAssignment (const char *bonded_opt)
 Assign responsibility for tasks for bonded interactions. More...
 
MdrunnerBuilderaddUpdateTaskAssignment (const char *update_opt)
 Assign responsibility for tasks for update and constrain calculation. More...
 
MdrunnerBuilderaddSimulationMethod (const MdrunOptions &options, real forceWarningThreshold, StartingBehavior startingBehavior)
 Set MD options not owned by some other module. More...
 
MdrunnerBuilderaddDomainDecomposition (const DomdecOptions &options)
 Set the domain decomposition module. More...
 
MdrunnerBuilderaddNeighborList (int rebuildInterval)
 Set Verlet list manager. More...
 
MdrunnerBuilderaddReplicaExchange (const ReplicaExchangeParameters &params)
 Set replica exchange manager. More...
 
MdrunnerBuilderaddHardwareOptions (const gmx_hw_opt_t &hardwareOptions)
 Specify parameters determining hardware resource allocation. More...
 
MdrunnerBuilderaddFilenames (ArrayRef< const t_filenm > filenames)
 Provide the filenames options structure with option values chosen. More...
 
MdrunnerBuilderaddOutputEnvironment (gmx_output_env_t *outputEnvironment)
 Provide parameters for setting up output environment. More...
 
MdrunnerBuilderaddLogFile (t_fileio *logFileHandle)
 Provide the filehandle pointer to be used for the MD log. More...
 
MdrunnerBuilderaddStopHandlerBuilder (std::unique_ptr< StopHandlerBuilder > builder)
 Provide a StopHandlerBuilder for the MD stop signal handling. More...
 
 MdrunnerBuilder (MdrunnerBuilder &&builder) noexcept
 Allow transfer of ownership with move semantics. More...
 
MdrunnerBuilderoperator= (MdrunnerBuilder &&builder) noexcept
 

Constructor & Destructor Documentation

gmx::MdrunnerBuilder::MdrunnerBuilder ( std::unique_ptr< MDModules mdModules,
compat::not_null< SimulationContext * >  context 
)
explicit

Constructor requires a handle to a SimulationContext to share.

Parameters
mdModulesThe handle to the set of modules active in mdrun
contextRequired 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.

gmx::MdrunnerBuilder::MdrunnerBuilder ( MdrunnerBuilder &&  builder)
defaultnoexcept

Allow transfer of ownership with move semantics.

Parameters
buildersource object to transfer.

Member Function Documentation

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.

Parameters
bonded_optTarget 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.

Todo:

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.

Parameters
optionsoptions with which to construct domain decomposition.
Todo:
revisit whether we should be passing this parameter struct or a higher-level handle of some sort.
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.

Parameters
pme_optTarget long-range interactions for "cpu", "gpu", or "auto".
pme_fft_optTarget 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.

Todo:

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.

Parameters
filenamesFilenames and properties from command-line argument values or defaults.
Todo:
Modules should manage their own filename options and defaults.
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.

Parameters
hardwareOptionsParallelism-related user options.
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.

Parameters
logFileHandleNon-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.

Parameters
rebuildIntervaloverride 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.

Parameters
nbpu_optTarget short-range interactions for "cpu", "gpu", or "auto".

Calling must guarantee that the pointed-to C string is valid through simulation launch.

Todo:

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.

Parameters
outputEnvironmentOutput context for writing text files.
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 & 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.

Parameters
paramsparameters with which to set up replica exchange.
Todo:
revisit whether we should be passing this parameter struct or a higher-level handle of some sort.
MdrunnerBuilder & gmx::MdrunnerBuilder::addSimulationMethod ( const MdrunOptions options,
real  forceWarningThreshold,
StartingBehavior  startingBehavior 
)

Set MD options not owned by some other module.

Optional. Override simulation parameters

Parameters
optionsstructure to copy
forceWarningThresholdPrint a warning if any force is larger than this (in kJ/mol nm) (default -1)
startingBehaviorWhether the simulation will start afresh, or restart with/without appending.
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 & 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.

Parameters
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.

Parameters
[in]update_optTarget 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.

Todo:

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."

Returns
A new Mdrunner.
Exceptions
APIErrorif a required component has not been added before calling build().

The documentation for this class was generated from the following files: