MPI_CART_SUB(3)					     Open MPI					   MPI_CART_SUB(3)

MPI_Cart_sub — Partitions a communicator into subgroups, which form lower-dimensional Cartesian subgrids.

SYNTAX
   C Syntax
	  #include <mpi.h>

	  int MPI_Cart_sub(MPI_Comm comm, const int remain_dims[], MPI_Comm *comm_new)

   Fortran Syntax
	  USE MPI
	  ! or the older form: INCLUDE 'mpif.h'

	  MPI_CART_SUB(COMM, REMAIN_DIMS, COMM_NEW, IERROR)
	      INTEGER COMM, COMM_NEW, IERROR
	      LOGICAL REMAIN_DIMS(*)

   Fortran 2008 Syntax
	  USE mpi_f08

	  MPI_Cart_sub(comm, remain_dims, newcomm, ierror)
	      TYPE(MPI_Comm), INTENT(IN) :: comm
	      LOGICAL, INTENT(IN) :: remain_dims(*)
	      TYPE(MPI_Comm), INTENT(OUT) :: newcomm
	      INTEGER, OPTIONAL, INTENT(OUT) :: ierror

INPUT PARAMETERS
       • comm : Communicator with Cartesian structure (handle).

       •

	 remain_dims (The ith entry of remain_dims specifies whether the ith)
		dimension is kept in the subgrid (true) or is dropped (false) (logical vector).

OUTPUT PARAMETERS
       •

	 comm_new (Communicator containing the subgrid that includes the)
		calling process (handle).

       • ierror : Fortran only: Error status (integer).

DESCRIPTION
       If a Cartesian topology has been created with MPI_Cart_create <#mpi-cart-create>, the function MPI_Cart_sub
       can  be	used  to  partition  the  communicator	group into subgroups that form lower-dimensional Cartesian
       subgrids, and to build for each subgroup a communicator with the	 associated  subgrid  Cartesian	 topology.
       (This function is closely related to MPI_Comm_split <#mpi-comm-split>.)

       Example:	 Assume	 that MPI_Cart_create( ..., comm) has defined a (2 x 3 x 4) grid. Let remain_dims = (true,
       false, true). Then a call to

	  MPI_Cart_sub(comm, remain_dims, comm_new);

       will create three communicators, each with eight processes in a 2 x 4 Cartesian topology. If remain_dims	 =
       (false,	false,	true)  then  the  call	to  MPI_Cart_sub(comm,	remain_dims,  comm_new)	 will  create  six
       nonoverlapping communicators, each with four processes, in a one-dimensional Cartesian topology.

ERRORS
       Almost all MPI routines return an error value; C routines as the return result of the function and  Fortran
       routines in the last argument.

       Before  the error value is returned, the current MPI error handler associated with the communication object
       (e.g., communicator, window, file) is called.  If no communication object is associated with the MPI  call,
       then  the call is considered attached to MPI_COMM_SELF and will call the associated MPI error handler. When
       MPI_COMM_SELF is not initialized (i.e.,	before	MPI_Init  <#mpi-init>/MPI_Init_thread  <#mpi-init-thread>,
       after  MPI_Finalize  <#mpi-finalize>,  or  when	using the Sessions Model exclusively) the error raises the
       initial error handler. The initial error handler can  be	 changed  by  calling  MPI_Comm_set_errhandler	<#
       mpi-comm-set-errhandler>	 on  MPI_COMM_SELF  when  using the World model, or the mpi_initial_errhandler CLI
       argument	 to  mpiexec  or  info	key   to   MPI_Comm_spawn   <#mpi-comm-spawn>/MPI_Comm_spawn_multiple	<#
       mpi-comm-spawn-multiple>.   If  no other appropriate error handler has been set, then the MPI_ERRORS_RETURN
       error handler is called for MPI I/O functions and the MPI_ERRORS_ABORT error  handler  is  called  for  all
       other MPI functions.

       Open MPI includes three predefined error handlers that can be used:

       • MPI_ERRORS_ARE_FATAL Causes the program to abort all connected MPI processes.

       • MPI_ERRORS_ABORT  An  error handler that can be invoked on a communicator, window, file, or session. When
	 called on a communicator, it acts as if MPI_Abort <#mpi-abort> was called on that communicator. If called
	 on a window or file, acts as if MPI_Abort <#mpi-abort> was called on a communicator containing the  group
	 of processes in the corresponding window or file. If called on a session, aborts only the local process.

       • MPI_ERRORS_RETURN Returns an error code to the application.

       MPI applications can also implement their own error handlers by calling:

       • MPI_Comm_create_errhandler	 <#mpi-comm-create-errhandler>	   then	    MPI_Comm_set_errhandler	<#
	 mpi-comm-set-errhandler>

       • MPI_File_create_errhandler	<#mpi-file-create-errhandler>	  then	   MPI_File_set_errhandler	<#
	 mpi-file-set-errhandler>

       • MPI_Session_create_errhandler	 <#mpi-session-create-errhandler>   then   MPI_Session_set_errhandler	<#
	 mpi-session-set-errhandler> or at MPI_Session_init <#mpi-session-init>

       • MPI_Win_create_errhandler	<#mpi-win-create-errhandler>	  then	    MPI_Win_set_errhandler	<#
	 mpi-win-set-errhandler>

       Note that MPI does not guarantee that an MPI program can continue past an error.

       See the MPI man page <#open-mpi> for a full list of MPI error codes <#open-mpi-errors>.

       See the Error Handling section of the MPI-3.1 standard for more information.

       See also:

	  • MPI_Cart_create <#mpi-cart-create>

Copyright
       2003-2026, The Open MPI Community

						   Mar 05, 2026					   MPI_CART_SUB(3)
