# FORM TEAM

Statement: Defines team variables; creates one or more teams of images from the images on the current team.

## Syntax

The FORM TEAM statement takes the following form:

FORM TEAM(team-number, team-variable [, form-team-spec-list])

team-number | Is a scalar-integer-expression.
team-variable | Is a scalar variable of type TEAM_TYPE defined in the intrinsic module ISO_FORTRAN_ENV.
form-team-spec | NEW_INDEX = scalar-integer-expression or sync-stat-list
sync-stat-list | Is STAT= stat-var or ERRMSG = err-var
stat-var | Is a scalar integer variable in which the status of the FORM TEAM operation is stored.
err-var | Is a scalar default character variable in which explanatory text is stored if an error occurs.

The form-team-spec items can appear in any order. Each specifier in a FORM TEAM statement can appear at most once. stat-var and err-var cannot be coindexed variables.

## Description

A FORM TEAM statement creates a new team for each unique team-number specified by the active images of the current team. The teams are identified by their team numbers, which are positive integers. An image becomes a member of the team-number specified on the FORM TEAM statement the image executes. The team-variable becomes defined with values that describe the team.

An image index must be positive and less than or equal to n, the number of images on the team. If NEW_INDEX= is specified, the value of the scalar-integer-expression is the image index the image executing the FORM TEAM statement will have on its new team. Its value must be different from any value specified for every other image that is assigned to the same new team. If NEW_IMAGE= is not specified, the image is given a processor-dependent unique image index in the range 1, 2, … n on the new team.

All active images of the current team must execute the same FORM TEAM statement. An implicit SYNC ALL occurs at the FORM TEAM statement. Execution of the segment following the FORM TEAM statement is delayed until other images of the current team have executed the same FORM TEAM statement the same number of times. FORM TEAM is an image control statement; all segments executed before the FORM TEAM statement precede all segments that execute after the FORM TEAM statement.

If STAT= appears and no error occurs, stat-var becomes defined with the value 0. If an image on the current team has executed a STOP statement, stat-var is assigned the value STAT_STOPPED_IMAGE from the intrinsic module ISO_FORTRAN_ENV. If there is a failed image on the current team and no other error occurs, stat-var is assigned the value STAT_FAILED_IMAGE from ISO_FORTRAN_ENV. Otherwise, stat-var is assigned a positive integer value different from STAT_FAILED_IMAGE and STAT_STOPPED_IMAGE.

team-variable becomes undefined if an error condition occurs.

## Examples

Example 1:

       USE ISO_FORTRAN
       TYPE (TEAM_TYPE)    :: one_or_two
       IF (THIS_IMAGE() .LE. NUM_IMAGES() / 2) THEN
          new_team = 1
       ELSE
          new_team = 2
       END IF
       FORM TEAM (new_team, one_or_two)

If the initial team has seven images, and the initial team executes the above FORM TEAM statement, two teams are formed. The new image indices are assigned by the runtime system in a processor-dependent manner.

Team number 1 has three images, images [1, 2, 3] of the initial team with new image indices [1, 2, 3]. Team number 2 has four images, images [4, 5, 6, 7] from the initial team, with new image indices [1, 2, 3, 4]. The team variable `one_or_two` on initial team images [1, 2, 3] collectively describe team number 1, while the team variable `one_or_two` on the initial team images [4, 5, 6, 7] collectively describe team number 2.

Example 2:

       USE ISO_FORTRAN_ENV
       TYPE (TEAM_TYPE)    :: odd_even
       FORM TEAM (2-MOD(THIS_IMAGE(), 2), odd_even)

If a team with 10 images executes the above code, two teams are formed. Team number 1 contains the odd numbered images [1, 3, 5, 7, 9] of the parent team, and team number 2 contains the even numbered images [2, 4, 6, 8, 10] of the parent. New image indices on each team are assigned by the processor. The team variable `odd_even` across the odd numbered images on the parent team collectively describe team number 1, and the team variable `odd_even` across the even numbered images on the parent team collectively describe team number 2.

Example 3:

       USE ISO_FORTRAN_ENV
       INTEGER, PARAMETER       :: n = 4
       TYPE (TEAM_TYPE)         :: column
       REAL,CODIMENSION[n, *]   :: co_array
       INTEGER,DIMENSION(2)     :: my_cosubscripts
       my_cosubscripts (:)     = THIS_IMAGE(co_array)
       FORM TEAM (my_cosubscripts(2), column, NEW_INDEX = my_cosubscripts(1))

If there are 16 images on the initial team, the scalar coarray `co_array` will be distributed across a 4x4 grid of processors. The image indices of the 4x4 grid are:

1 | 5 | 9 | 13
2 | 6 | 10 | 14
3 | 7 | 11 | 15
4 | 8 | 12 | 16

THIS_IMAGE (co_array) will return a two element array of integer cosubscripts of `co_array` on the image that executes the reference to THIS_IMAGE. The cosubscripts of each image are:

1,1 | 1,2 | 1,3 | 1,4
2,1 | 2,2 | 2,3 | 2,4
3,1 | 3,2 | 3,3 | 3,4
4,1 | 4,2 | 4,3 | 4,4

Execution of the FORM TEAM statement divides the initial team into four teams of four images. Each team contains the images of one column of the grid of processors. The team number of each team is the column number in the processor grid, and the image indices on each new team are the row indices of the processor grid. The new image numbers on each team are shown below:

Team Number | 1 | 2 | 3 | 4
| 1 | 1 | 1 | 1
| 2 | 2 | 2 | 2
| 3 | 3 | 3 | 3
| 4 | 4 | 4 | 4

Example 4:

This example divides a 4x4 grid of images into 4 2x2 grids of images. Team numbers are assigned in the FORM TEAM statement that reflect the position of each team in the grid of subteams. The example also shows the use of NEW_INDEX to assign image indices to the images of the new teams.

The image indices of the 4x4 grid are:

1 | 5 | 9 | 13
2 | 6 | 10 | 14
3 | 7 | 11 | 15
4 | 8 | 12 | 16

The 2x2 grids are laid out and identified symbolically and with team numbers as:

top_left (1,1) | top_right (1,2)
bot_left (2,1) | bot_right (2,2)

The image numbers on each of the teams in the 2x2 grids become:

1 | 3 | 1 | 3
2 | 4 | 2 | 4
1 | 3 | 1 | 3
2 | 4 | 2 | 4

        PROGRAM MAIN
        USE ISO_FORTRAN_ENV
        INTEGER,PARAMETER          :: top_left=11, bot_left=21, top_right=12, bot_right=22
        INTEGER,DIMENSION(16)      :: quads = [top_left,  top_left,  bot_left,  bot_left,         &
                                               top_left,  top_left,  bot_left_ bot_left,          &
                                               top_right, top_right, bot_right, bot_right,        &
                                               top_right, top_right, bot_right, bot_right]
        INTEGER,DIMENSION(16)      :: images         = [1,2,1,2,3,4,3,4,1,2,1,2,3,4,3,4]
        TYPE(TEAM_TYPE)            :: quadrants
        INTEGER                    :: me

        me = THIS_IMAGE()
        FORM TEAM (quads(me), quadrants, NEW_INDEX=images(me))
          . . .
        END PROGRAM

Example 5:

        USE ISO_FORTRAN_ENV
        TYPE (TEAM_TYPE) :: original
        FORM TEAM (1, original, NEW_INDEX = THIS_IMAGE())

This example forms a single subteam described by the team variable original. The subteam has the same number of images as the initial team, and each image has the same image number on the initial team as on the subteam. However, `original` describes a team that is different but functionally the same as the initial team. It has a parent team, while the initial team does not.

Parent topic: E to F

## See Also

Image Control Statements
Coarrays
Using Coarrays