/*D
   MPI_Comm_split - Creates new communicators based on colors and keys

Synopsis:
.vb
int MPI_Comm_split(MPI_Comm comm, int color, int key, MPI_Comm *newcomm)
.ve

Input Parameters:
+ comm - communicator (handle)
. color - control of subset assignment (integer)
- key - control of rank assignment (integer)

Output Parameters:
. newcomm - new communicator (handle)

Notes:
  The 'color' must be non-negative or 'MPI_UNDEFINED'.

.N ThreadSafe

.N Fortran

Algorithm:
.vb
  1. Use MPI_Allgather to get the color and key from each process
  2. Count the number of processes with the same color; create a
     communicator with that many processes.  If this process has
     'MPI_UNDEFINED' as the color, create a process with a single member.
  3. Use key to order the ranks
.ve

.N Errors
.N MPI_SUCCESS
.N MPI_ERR_ARG
.N MPI_ERR_COMM
.N MPI_ERR_OTHER

.seealso: MPI_Comm_free
D*/

