Improve naming and docs.

[alexxy/gromacs.git] / src / gromacs / mdrun / simulationcontext.h

diff --git a/src/gromacs/mdrun/simulationcontext.h b/src/gromacs/mdrun/simulationcontext.h
index 717b4f30a9f943488c153184fe6bdcdcee7549d2..0fb81b5865f9f99b613d4986f3d901ecd78a8f66 100644 (file)
--- a/src/gromacs/mdrun/simulationcontext.h
+++ b/src/gromacs/mdrun/simulationcontext.h
@@ -108,45 +108,67 @@ public:
     /*!
      * \brief Construct
      *
-     * \param worldCommunicator       MPI communicator for this simulation context
+     * \param communicator Communicator for all collaborating simulation processes.
      * \param 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 (GMX_LIB_MPI==1), the client promises that
+     * gmx::init() has called MPI_Init and the provided communicator is valid to use.
+     * 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.
      */
-    explicit SimulationContext(MPI_Comm                    worldCommunicator,
-                               ArrayRef<const std::string> multiSimDirectoryNames);
+    explicit SimulationContext(MPI_Comm communicator, ArrayRef<const std::string> multiSimDirectoryNames);
 
     /*!
-     * \brief MPI communicator object for this GROMACS instance.
+     * \brief MPI resources for the entire simulation context.
      *
-     * With real MPI,
-     *   the gmx wrapper binary has called MPI_Init, thus
-     *     MPI_COMM_WORLD is now valid to use, and
-     *   (in future) the gmxapi runner will handle such details
-     *     (e.g. via mpi4py) before creating its SimulationContext.
+     * With an external MPI library (GMX_LIB_MPI==1),
+     * 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 in both cases, the communicator is set up later
+     * With thread-MPI, 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.)
      */
-    MPI_Comm worldCommunicator_ = MPI_COMM_NULL;
+    MPI_Comm libraryWorldCommunicator_ = MPI_COMM_NULL;
 
     /*!
-     * \brief MPI communicator object for this simulation object.
+     * \brief MPI communicator object for this simulation.
      *
-     * With real MPI,
-     *   the gmx wrapper binary has called MPI_Init, thus
-     *     MPI_COMM_WORLD is now valid to use, and
-     *   (in future) the gmxapi runner will handle such details
-     *     (e.g. via mpi4py) before creating its SimulationContext.
+     * With an external MPI library (GMX_LIB_MPI==1),
+     * 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 in both cases, the communicator is set up later
+     * With thread-MPI, 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.)
+     * ranks.
      */
     MPI_Comm simulationCommunicator_ = MPI_COMM_NULL;
 
     /*!
      * \brief 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.
      */
     std::unique_ptr<gmx_multisim_t> multiSimulation_;
 };