KERNEL-02_Coward_DoLoopMacros_part1

Last edition: 09/08/20 11:54:23 by acc

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.

1. Summary
2. Preview
3. Tests
4. Review

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

Since the preview step must be completed before the PI starts the coding, the previewer(s) answers are expected to be completed within the two weeks after the PI has sent the request to the previewer(s).
Then an iterative process should take place between PI and previewer(s) in order to find a consensus

Possible bottlenecks:

• the methodology
• the flowchart and list of routines to be changed
• the new list of variables wrt coding rules
• the summary of updates in literature

---

Once an agreement has been reached, preview is ended and the PI can start the development into his branch.

…

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

A successful review is needed to schedule the merge of this development into the future NEMO release during next Merge Party (usually in November).

Assessments:

• Is the proposed methodology now implemented?
• Are the code changes in agreement with the flowchart defined at preview step?
• Are the code changes in agreement with list of routines and variables as proposed at preview step?
  If, not, are the discrepancies acceptable?
• Is the in-line documentation accurate and sufficient?
• Do the code changes comply with NEMO coding standards?
• Is the development documented with sufficient details for others to understand the impact of the change?
• Is the project literature (manual, guide, web, …) now updated or completed following the proposed summary in preview section?

Finding:

Is the review fully successful? If not, please indicate what is still missing

---

Once review is successful, the development must be scheduled for merge during next Merge Party Meeting.

…