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

#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_tmultiSimulation_
 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
communicatorCommunicator for all collaborating simulation processes.
multiSimDirectoryNamesNames 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: