gmx::SimulationContext Class Reference

#include <gromacs/mdrun/simulationcontext.h>

Description

Simulation environment and configuration.

SimulationContext allows a simulation module () to retrieve runtime parameters and resources from client code. The client retains ownership of the context and its resources, with exceptions as noted.

A client must share ownership of some resources and transfer ownership of other resources to create or configure the context. The simulation may in turn consume or borrow some resources from the context. This is a new framework that will evolve in the contexts of https://gitlab.com/gromacs/gromacs/-/issues/2375 https://gitlab.com/gromacs/gromacs/-/issues/2587

The public interface of SimulationContext is not yet well-specified. Client code can create an instance with gmx::createSimulationContext()

Warning

The SimulationContext does not yet encapsulate the resources allocated to the simulator. See https://gitlab.com/gromacs/gromacs/-/issues/3650

On thread-MPI code paths, the SimulationContext does not represent constraints on the number of simulation ranks, nor does it represent initialized communication resources.

Todo:

Clarify and strengthen the invariant represented by SimulationContext.

Todo:

This class should also handle aspects of simulation environment such as working directory and environment variables.

This is a minimal placeholder for a more complete implementation. Interfaces for different API levels are not yet final.

Todo:

Impose sensible access restrictions. Either the SimulationContext should be passed to the Mdrunner as logically constant or a separate handle class can provide access to resources that have been allocated by (negotiated with) the client for the current simulation (or simulation segment). Non-const accessors to shared resources need to be associated with update signals that the simulation components (modules and runner) can subscribe to.

Also reference https://gitlab.com/gromacs/gromacs/-/issues/2587

Public Member Functions
	SimulationContext ()=delete
	Object must be initialized with non-default constructor.
	SimulationContext (MPI_Comm communicator, ArrayRef< const std::string > multiSimDirectoryNames)
	Initialize from borrowed communicator. More...

Public Attributes
MPI_Comm	libraryWorldCommunicator_ = MPI_COMM_NULL
	MPI resources for the entire simulation context. More...
MPI_Comm	simulationCommunicator_ = MPI_COMM_NULL
	MPI communicator object for this simulation. More...
std::unique_ptr< gmx_multisim_t >	multiSimulation_
	Multi-sim handler (if required by e.g. gmx mdrun -multidir; only supported with real MPI) More...

Constructor & Destructor Documentation

gmx::SimulationContext::SimulationContext ( MPI_Comm  communicator, ArrayRef< const std::string >  multiSimDirectoryNames  )

explicit

Initialize from borrowed communicator.

Parameters

communicator	Communicator for all collaborating simulation processes.
multiSimDirectoryNames	Names of any directories used with -multidir

Caller is responsible for keeping communicator valid for the life of SimulationContext, and then freeing the communicator, if appropriate.

With an external MPI library (non-thread-MPI chosen when configuring with CMake), the client promises that MPI has been initialized (such as by calling gmx::init()). This communicator is "borrowed" (not duplicated) from the caller. Additional communicators may be split from the provided communicator during the life of the SimulationContext or its consumers.

With thread-MPI, communicator must be MPI_COMM_NULL. The communicator is set up later during the process of spawning the threads that will be the MPI ranks. (Multi-simulation is not supported with thread-MPI.)

Todo:

Refine distribution of environment management. There should be a context level at which only the current simulator directory matters, and a level above which encapsulates multisim details in a specialized type.

Member Data Documentation

MPI_Comm gmx::SimulationContext::libraryWorldCommunicator_ = MPI_COMM_NULL

MPI resources for the entire simulation context.

With an external MPI library (non-thread-MPI chosen when configuring with CMake), gmx::init() has called MPI_Init and the provided communicator is valid to use. The communicator is "borrowed" (not duplicated) from the caller.

With thread-MPI, the communicator is set up later during the process of spawning the threads that will be the MPI ranks.

std::unique_ptr<gmx_multisim_t> gmx::SimulationContext::multiSimulation_

Multi-sim handler (if required by e.g. gmx mdrun -multidir; only supported with real MPI)

If a multi-simulation is in use, then its communicator(s) are found in multiSimulation_. This communicator is that of all ranks from all simulations, and will later be split into one for each simulation. TODO: Perhaps (for simplicity) communicator splitting can be undertaken during multi-sim setup (acquisition of the multisim resource).

Multi-simulation is not supported with thread-MPI.

MPI_Comm gmx::SimulationContext::simulationCommunicator_ = MPI_COMM_NULL

MPI communicator object for this simulation.

With an external MPI library (non-thread-MPI chosen when configuring with CMake), gmx::init() has called MPI_Init and the provided communicator is valid to use. The communicator is "borrowed" (not duplicated) from the caller.

With thread-MPI, the communicator is set up later during the process of spawning the threads that will be the MPI ranks.

---

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

• src/gromacs/mdrun/simulationcontext.h
• src/gromacs/mdrun/simulationcontext.cpp