parameters: (original_comm, requested_size: int = None)
docstring: Manage the lifecycle of a new communicator.
  
      Get a Python context manager that produces a new communicator
      in a ``with`` statement and frees it afterwards.
  
      The new communicator is a sub-communicator of *original_comm*, if provided.
  
      Args:
          original_comm: parent communicator, or *None* to determine automatically.
          requested_size: number of ranks requested, or *None* for all available.
  
      *original_comm* is required if *requested_size* is not *None*.
  
      If *requested_size* is less than the size of *original_comm*, the type of object
      produced on higher-numbered (non-participating) ranks is unspecified. Callers
      should use ``original_comm.Get_rank()`` to decide whether to use the new comm.
docstring_summary: Manage the lifecycle of a new communicator.
docstring_tokens: Manage the lifecycle of a new communicator .
function: def scoped_communicator(original_comm, requested_size: int = None):
      """Manage the lifecycle of a new communicator.
  
      Get a Python context manager that produces a new communicator
      in a ``with`` statement and frees it afterwards.
  
      The new communicator is a sub-communicator of *original_comm*, if provided.
  
      Args:
          original_comm: parent communicator, or *None* to determine automatically.
          requested_size: number of ranks requested, or *None* for all available.
  
      *original_comm* is required if *requested_size* is not *None*.
  
      If *requested_size* is less than the size of *original_comm*, the type of object
      produced on higher-numbered (non-participating) ranks is unspecified. Callers
      should use ``original_comm.Get_rank()`` to decide whether to use the new comm.
      """
      from gmxapi.simulation.context import (_acquire_communicator,
                                             _get_ensemble_communicator,
                                             )
      global _current_communicator
      if original_comm is None:
          original_comm = _current_communicator
  
      if requested_size is None:
          communicator = _acquire_communicator(communicator=original_comm)
  
      else:
          if original_comm is None or not hasattr(original_comm, 'Get_size'):
              error = f'Cannot get Comm size {requested_size} from {repr(original_comm)}.'
              logger.error(
                  error + ' '
                  + 'To get a scoped communicator of a specific size, provide a parent '
                  + 'communicator supporting the mpi4py.MPI.Comm interface.'
              )
              raise exceptions.UsageError(error)
          original_comm_size = original_comm.Get_size()
          if original_comm_size < requested_size:
              raise exceptions.FeatureNotAvailableError(
                  'Cannot produce a subcommunicator of size {} from a communicator of size {}.'.format(
                      requested_size,
                      original_comm_size
                  ))
          assert original_comm_size >= requested_size
          communicator = _get_ensemble_communicator(original_comm, requested_size)
  
      try:
          previous_communicator = _current_communicator
          _current_communicator = communicator
          yield communicator
      finally:
          _current_communicator = previous_communicator
          if communicator is not None:
              communicator.Free()
function_tokens: def scoped_communicator ( original_comm , requested_size : int = None ) : from gmxapi . simulation . context import ( _acquire_communicator , _get_ensemble_communicator , ) global _current_communicator if original_comm is None : original_comm = _current_communicator if requested_size is None : communicator = _acquire_communicator ( communicator = original_comm ) else : if original_comm is None or not hasattr ( original_comm , 'Get_size' ) : error = f'Cannot get Comm size {requested_size} from {repr(original_comm)}.' logger . error ( error + ' ' + 'To get a scoped communicator of a specific size, provide a parent ' + 'communicator supporting the mpi4py.MPI.Comm interface.' ) raise exceptions . UsageError ( error ) original_comm_size = original_comm . Get_size ( ) if original_comm_size < requested_size : raise exceptions . FeatureNotAvailableError ( 'Cannot produce a subcommunicator of size {} from a communicator of size {}.' . format ( requested_size , original_comm_size ) ) assert original_comm_size >= requested_size communicator = _get_ensemble_communicator ( original_comm , requested_size ) try : previous_communicator = _current_communicator _current_communicator = communicator yield communicator finally : _current_communicator = previous_communicator if communicator is not None : communicator . Free ( )