= KERNEL-02_Coward_DoLoopMacros_part1
Last edition: '''[[Wikinfo(changed_ts)]]''' by '''[[Wikinfo(changed_by)]]'''

The PI is responsible to closely follow the progress of the action, 
and especially to contact NEMO project manager if 
the delay on preview (or review) are longer than the 2 weeks expected.

[[PageOutline(2, , inline)]]

== Summary

||=Action       || KERNEL-02_Coward_DoLoopMacros_part1                        ||
||=PI(S)        || acc                                                ||
||=Digest       || Implement basic Do loop macros to replace contiguous nested loops in preparation for tiling work     ||
||=Dependencies || If any                                                ||
||=Branch       || source:/NEMO/branches/{YEAR}/dev_r{REV}_{ACTION_NAME} ||
||=Previewer(s) || Names                                                 ||
||=Reviewer(s)  || Names                                                 ||
||=Ticket       || #XXXX                                                 ||

=== Description

 Implement basic Do loop macros to replace contiguous nested loops in preparation for tiling work. This task simply replaces existing loops and should result in no change in results. It is hoped to achieve this early in the New Year and provide a basis for other 2020 developments.

=== Implementation

The do loop macros were introduced into the 2019 merge branch before this was merged back onto the trunk. Full details are given here:

https://forge.ipsl.jussieu.fr/nemo/changeset/12340

The merge back to the trunk happened at changeset:12377 and the macros have been available in all developments started since then

Following the mid-year merge in June 2020. The Do-loop macros were rewritten according to Italo's design to a simpler, functional form which is more flexible and better supports the extra halo options. This change occurred at changeset:13295 
=== Documentation updates

{{{
The primary aim of these macros is to assist in future applications of tiling
to improve performance. This is expected to be achieved by alternative versions of these macros in selected
locations. The initial introduction of these macros simply replaced all identifiable nested 2D- and 3D-loops
with single line statements (and adjusts indenting accordingly). Do loops were identifiable if they comformed
to either:
                                      DO jk = ....
  DO jj = ....                           DO jj = ...
     DO ji = ....                           DO ji = ...
        .                   OR                 . 
        .                                      .
    END DO                                  END DO
  END DO                                 END DO
                                      END DO
 and white-space variants thereof.

 Additionally, only loops with recognised jj and ji loops limits were treated; these were:
 Lower limits of 1, 2 or fs_2
 Upper limits of jpi, jpim1 or fs_jpim1 (for ji) or jpj, jpjm1 or fs_jpjm1 (for jj)

 The macro naming convention takes the form: DO_2D( B, T, L, R) where:
   B is the Bottom offset from the PE's inner domain;
   T is the Top    offset from the PE's inner domain;
   L is the Left   offset from the PE's inner domain;
   R is the Right  offset from the PE's inner domain

 So, given an inner domain of 2,jpim1 and 2,jpjm1, a typical example would replace:

   DO jj = 2, jpj
      DO ji = 1, jpim1
         .
         .
      END DO
   END DO

 with:

   DO_2D( 0, 1, 1, 0 )
      .
      .
   END_2D

 similar conventions apply to the 3D loops macros. jk loop limits are retained through macro arguments
 and are not restricted. This includes the possibility of strides for which an extra set of DO_3DS
 macros are defined.

 In the following definitions the inner PE domain is defined by start indices of (Nis0, Njs0) and end
 indices of (Nie0, Nje0) where:

 Nis0 =   1 + nn_hls     Njs0 =   1 + nn_hls
 Nie0 = jpi - nn_hls     Nje0 = jpj - nn_hls

#endif
#define DO_2D(B, T, L, R) DO jj = Njs0-(B), Nje0+(T)   ;   DO ji = Nis0-(L), Nie0+(R)
#define DO_3D(B, T, L, R, ks, ke) DO jk = ks, ke   ;   DO_2D(B, T, L, R)
#define DO_3DS(B, T, L, R, ks, ke, ki) DO jk = ks, ke, ki   ;   DO_2D(B, T, L, R)
#define END_2D   END DO   ;   END DO
#define END_3D   END DO   ;   END DO   ;   END DO
}}}

''...''

== Preview 

{{{#!box width=50em info
[[Include(wiki:Developers/DevProcess#preview_)]]
}}}

''...''

== Tests

The Do loop macros change code and layout but not function. Results before and after introduction of the macros should be identical. This has been verified at each stage by full SETTE testing.


== Review

{{{#!box width=50em info
[[Include(wiki:Developers/DevProcess#review)]]
}}}

''...''