collapse

Date:

07-12-2019

NAME

collapse, nocollapse - control collapse of the immediately following loop nest

SYNOPSIS

#pragma _CRI collapse [(loop1,loop2[...])]
#pragma _CRI nocollapse

!DIR$ COLLAPSE [(do_var1,do_var2[...])]
!DIR$ NOCOLLAPSE

IMPLEMENTATION

Cray Linux Environment (CLE)

DESCRIPTION

Scope: Local

The syntax for C/C++ programs differs slightly from Fortran syntax.

The loop collapse directive controls collapse of the immediately following loop nest. The directive enables the compiler to assume appropriate conformity between trip counts. The compiler diagnoses misuse at compile time (when able) or at run time (if -h dir_check is specified in C/C++ or under option -Rd in Fortran.)

In Fortran, when the collapse directive is applied to a loop nest, the do_var variables are the names of the DO variables of the participating loops. They must be listed in order of increasing access stride. When the collapse directive is applied to an array assignment statement, the (do_var1,do_var2[…]) syntax is omitted.

For C/C++, loop numbers range from 1 to the nesting level of the most deeply nested loop.

The nocollapse directive disqualifies the next immediate loop from collapsing with any other loop. Collapse is almost always desirable, so use this directive sparingly.

Loop collapse is a special form of loop coalesce. Any perfect loop nest may be coalesced into a single loop, with explicit rediscovery of the intermediate values of original loop control variables. The rediscovery cost, which generally involves integer division, is quite high. Therefore, coalesce is rarely suitable for vectorization.

By definition, loop collapse occurs when loop coalesce may be done without the rediscovery overhead. To meet this requirement, all memory accesses must have uniform stride.

In Fortran arrays, uniform stride is achieved when a computation can flow from one column of a multidimensional array into the next, viewing the array as a flat sequence. Hence, array sections such as A(:,3:7) are generally suitable for collapse, while a section like A(1:n-1,:) lacks the needed access uniformity. Care must taken when applying the collapse directive to assumed shape dummy arguments and Fortran pointers because the underlying storage need not be contiguous.

Example 1: COLLAPSE directive

The following example in Fortran, the COLLAPSE directive will collapse loop I and loop J into a single loop. In this example, the directive enables the compiler to assume appropriate conformity between trip counts and array extents.

             SUBROUTINE S(A, N, N1, N2)
                     REAL A(N, *)
!DIR$ COLLAPSE (I, J)
                     DO I = 1, N1
                             DO J = 1, N2
                                             A(I,J) = A(I,J) + 42.0
                             ENDDO
                     ENDDO
                     END

The resulting behavior of the above example yields code that is equivalent to the following. However, the following code is only an example to show the resulting behavior, and should not be coded directly because as a program source, it violates the Fortran language standard.

SUBROUTINE S(A, N, N1, N2)
        REAL A(N, *)
        DO IJ = 1, N1*N2
                        A(IJ, 1) = A(IJ, 1) + 42.0
        ENDDO
        END

Example 2: COLLAPSE directive using array syntax

In this example, the directive enables the compiler to assume appropriate conformity between trip counts and array extends.

     SUBROUTINE S( A, B )
             REAL, DIMENSION(:,:) :: A, B
!DIR$ COLLAPSE
             A = B ! USER PROMISES UNIFORM ACCESS STRIDE.
             END

SEE ALSO

intro_directives(7)