FORM TEAM

Intel® Fortran Compiler Classic and Intel® Fortran Compiler Developer Guide and Reference

Download PDF

ID 767251

Date 9/08/2022

Version

Public

A newer version of this document is available. Customers should click here to go to the newest version.

Visible to Intel only — GUID: GUID-2D6BD2D5-098C-461A-B4B7-DC35E4B72D2C

View Details

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

Select Your Language

Using Intel.com Search

Quick Links

Recent Searches

Advanced Search

Only search in

Intel® Fortran Compiler Classic and Intel® Fortran Compiler Developer Guide and Reference

FORM TEAM

See Also