CHANGE TEAM and END TEAM

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

Download PDF

ID 767251

Date 11/07/2023

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-9ABC4E18-6D86-4F77-A6B6-593ABEF297E6

View Details

CHANGE TEAM and END TEAM

Statement: Changes the current team of each image that executes the statement.

Syntax

The CHANGE TEAM construct takes the following form:

[name:] CHANGE TEAM (team-variable [, coarray-association-list][, sync-stat-list])

block

END TEAM [([sync-stat-list])] [name]

name	(Optional) Is the name of the CHANGE TEAM construct.
team-variable	Is a scalar variable of type TEAM_TYPE defined in the intrinsic module ISO_FORTRAN_ENV.
coarray-association	(Optional)Is `codimension-decl` => `selector`
codimension-decl	Is coarray-name [coarray-spec]
selector	Is a named coarray.
sync-stat	(Optional) 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.
block	Is a sequence of zero or more statements or constructs.

The sync-stat-list items can appear in any order, but each sync-stat specifier may appear at most once. A selector may appear only once in selector-list. stat-var and err-var cannot be coindexed variables. team-variable must have been previously defined by the execution of a FORM TEAM statement.

Description

A CHANGE TEAM statement begins the CHANGE TEAM construct. The current team of each image that executes a CHANGE team statement becomes the team specified by the team variable. This remains the current team of the image until another CHANGE TEAM construct is executed by the image, or until the corresponding END TEAM statement is executed. The current team of each image executing an END TEAM statement becomes the team that was current prior to execution of the corresponding CHANGE TEAM statement.

Branching into or out of a CHANGE TEAM construct is not permitted. A branch to an END TEAM statement is permitted only from within the corresponding CHANGE TEAM construct. An EXIT statement in a CHANGE TEAM construct is effectively the same as a branch to the END TEAM statement of the construct. Within a CHANGE TEAM construct, a CYCLE or EXIT statement is not allowed if it belongs to an outer construct. A RETURN statement may not appear in a CHANGE TEAM construct.

If a construct name appears on the CHANGE TEAM statement of the construct, the same name must also appear on the END TEAM construct. If a construct name appears on an END TEAM statement, the same construct name must appear on the corresponding CHANGE TEAM statement. The construct name must not be the same as any other construct name in the scoping unit.

The purpose of the coarray-association is to redefine the codimensions of a coarray during execution of the CHANGE TEAM construct. The associating entity is a coarray with the corank and cobounds specified in the codimension-decl. This means the coshape and cobounds of an associating entity can be different from that of the selector. When the CHANGE TEAM statement is executed, the selectors must all be established coarrays.

The coarray name in a coarray-association must not be the same as the name as the name of another coarray or of a selector in the CHANGE TEAM statement. The coarray names specified in the codimension-decl are associate names associated with their corresponding selectors. The type and type parameters of the associating entity is that of its selector. The associating entity is polymorphic if the selector is polymorphic, in which case the associating entity assumes the dynamic type and type parameters of the selector.

On each active image that executes the CHANGE TEAM statement, the team variables must have been defined by corresponding execution of the same FORM TEAM statement. The current team executing prior to the CHANGE TEAM statement must be the same team that executed the FORM TEAM statement that defined the team variables. On each image, the team variable specified in the CHANGE TEAM statement cannot become undefined or redefined during execution of the construct.

An allocatable coarray that has an allocation status of allocated when the CHANGE TEAM construct is entered cannot be deallocated during execution of the construct. Allocatable coarrays that are allocated during the CHANGE TEAM construct and remain allocated at the end of the construct are deallocated upon exit from the construct. This is true even if the allocatable coarray has the SAVE attribute.

Each image executing the CHANGE TEAM statement is implicitly synchronized with all the other active images that will be on the same team after execution of the CHANGE TEAM construct. Execution of the statements forming the block of the CHANGE TEAM construct are delayed until all images on the new team have entered the construct. The construct completes execution when the END TEAM statement is executed. The images of the team executing the construct are implicitly synchronized when the END TEAM statement is executed.

If STAT= is specified on a CHANGE TEAM or END TEAM statement, stat-var becomes defined with the value 0 if no error condition occurs. If the team executing the statement contains a stopped image, stat-var becomes defined with the value STAT_STOPPED_IMAGE from the intrinsic module ISO_FORTRAN_ENV. If the team contains a failed image and no other error condition occurs, stat-var becomes defined with the value STAT_FAILED_IMAGE defined in the module ISO_FORTRAN_ENV. Otherwise, stat-var becomes defined with a positive integer value other than STAT_FAILED_IMAGE or STAT_STOPPED_IMAGE. If STAT= is not specified, and the team contains a stopped or failed image, or if any other error occurs, error termination is initiated.

If ERRMSG= is specified in a CHANGE TEAM or an END TEAM statement and an error condition occurs, err-var becomes defined with a character string containing an informative message about the error. The string is truncated or padded according to the rules of intrinsic assignment. If no error occurs, err-var is unchanged.

Examples

Example 1:

    USE ISO_FORTRAN_ENV
    TYPE (TEAM_TYPE)    :: odd_even
    FORM TEAM (2-MOD(THIS_IMAGE(), 2), odd_even)
    CHANGE TEAM (odd_even)
    ! Segment 1
     . . .
    END TEAM
    ! Segment 2
    . . .
    END PROGRAM

If a team with 8 images executes the above code, two teams are formed. Team number 1 contains the odd numbered images [1, 3, 5, 7] of the parent team with new image indices [1, 2, 3, 4], and team number 2 contains the even numbered images [2, 4, 6, 8] of the parent team with new image indices [1, 2, 3, 4].

Segment 1 can be executed by team number 1 once images 1, 3, 5, and 7 of the initial team have arrived at the CHANGE TEAM construct. Team number 1 can execute segment 2 once the same images have executed the END TEAM statement. Similarly, segment 1 can be executed by team 2 only after image 2, 4, 6, and 8 have all arrived at the CHANGE TEAM statement, and they can execute segment 2 after they have all reached the END TEAM statement.

Example 2:

    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))
    CHANGE TEAM (column, ca[*] => co_array)
     ….
    END TEAM

If there are 16 images on the initial team, the scalar coarray co_array will be distributed across a 4 x 4 grid of processors. 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. Inside the CHANGE TEAM construct, the image pattern is a 1 x 4 pattern.

On team 1, ca[1] is co_array[1, 1], ca[2] is co_array[2,1], …, and ca[4] is coarray[4, 1]. On team 2, ca[1] is co_array[1, 2], ca[2] is co_array [2,2], …, and ca[4] is co_array[2, 4]. On team 3, ca[1] is co_array[1, 3], ca[2] is co_array[2 ,3], …, and ca[4] is co_array[4, 3]. And on team 4, ca[1] is co_array[1, 4], ca[2] is co_array[2, 4], …, and ca[4] is co_array[4, 4].

co_array's cosubscripts:

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

ca’s cosubscripts on each team:

Team Number	1	2	3	4
	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

Example 3:

    USE ISO_FORTRAN_ENV
    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)
    SYNC ALL 
    CHANGE TEAM (one_or_two)
       ! Segment 1
       . . .
    END TEAM
    SYNC ALL 
    ! Segment 2
    . . . 
    END PROGRAM

In the above case, the FORM TEAM statement creates two teams, team 1 and team 2. The SYNC ALL statement before the CHANGE TEAM statement prevents either team from entering the CHANGE TEAM construct until all images of the other team are ready to enter it also. Similarly, the SYNC ALL after the END TEAM statement prevents either team from executing segment 2 until all images of the other team have exited the CHANGE TEAM construct.

Example 4:

This example divides a 4x4 grid of images into 4 2x2 grids of images. 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, original_team
    REAL                       :: co_array1[4,*], co_array2 [4, *]
    INTEGER                    :: me

    original_team = GET_TEAM(INITIAL_TEAM)   ! Create variable describing initial team
    me = THIS_IMAGE()
    FORM TEAM (quads(me), quadrants, NEW_INDEX=images(me))
    CHANGE TEAM (quadrants, ca[2, *] => co_array1)
    x  = ca[3, TEAM_NUMBER=top_right]
    . . .
    END TEAM
    . . .
    END PROGRAM

Here the CHANGE TEAM statement remaps the coarray co_array1 to 2x2 grids within each team accessed by the associate name ca. The assignment statement in the CHANGE TEAM construct assigns the value of ca[3] on team number 21 to x on all images of the initial team, assuming all four subteams execute the CHANGE TEAM construct. ca[3, TEAM_NUMBER=top_left] is co_array[1, 4] of the initial team located on image 13 of the initial team.

Parent topic: C to D

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

CHANGE TEAM and END TEAM

Syntax

Description

Examples

See Also