ESMF Early Adopters Tutorial Examples

1. ESMF Early Adopters “Tutorial Examples”Chris Hill, cnh@plume.mit.edu ESMF Community Meeting, Boulder, 2004 • Early Adopters (EA) group has been holding regular meetings at GFDL for five months. One focus of these meeting has been to begin to develop some introductory examples. For this afternoon look at these examples look at interoperability codes, user adoption activities.

2. Ways someone learns about ESMF • Background and introduction. • General orientation. • Application case studies. • Interoperability experiments experience. • Tutorial and idealized examples. • Downloadable sample code. • e.g flow solver demo, Early Adopters examples this morning this afternoon

3. Recap of this morning

4. Background and introduction Platforms • Context • describing motivation and goals. • Summary of ESMF architecture and 2.0 distribution • pointers to 2.0 distribution docs…

5. Case studies • Describes approaches of deployment projects - • Demonstrates approaches to ESMF adoption in large existing codes.

6. Key ESMF concepts • Gridded and Coupler Components. • Import and Export States. • Clocks. • Fields and Grids. • Model of underlying paralleism. • Tutorial Examples illustrate these concepts

7. Tutorial examples

8. Tutorial examples • So far from Early Adopters group • collecting its learning experience. • Assembling a range of examples • simple “hello world” to • useful sub-components e.g. solvers and “interpolators” • Small footprint • quick download • build on most Unix/Linux platforms.

9. Components (component_tutorials/) hello_world/ demonstrates SetServices(), Init(), Run(), Final() import_and_export/ demonstrates passing data in ESMF_States clock/ demonstrates alarms and clock. simple_couple_1/ demonstrates coupler components. combines SetServices, ESMF_State, clock in a simple application. Fields and grids (fields_and_grids_tutorials/) regrid/ interpolates Levitus SST through coupler with regrid demonstrates regridding and transferring data between parallel components. laplace/ estimates flow from 2o Topex SSH solves for non-divergent flow at arbitrary resolution. demonstrates halo(), globalsum() etc.. Current tutorial examples center on two basic areas Gridded and paralleism. Basic component wiring and control Not especially gridded.

10. component_tutorials/hello_world/

11. Hello World App-component_tutorials/hello_world - Top Layer App Driver • Every software project needs a Hello World • For ESMF, Hello World demonstrates • a single component driven from one layer above • using SetServices() and Gridded Components in practice. ESMF library code SetServices() Run() Initialize() Finalize()

12. MyWorldGridCompMod.F90contains the SetServices(), Initialize(), Run() and Finalize() code. hello_world_app.F90 contains the top layer app driver. Hello World has two source files

13. Top Layer App Driver

14. SetServices() Initialize() SetServices() and Initialize() Methods

15. Run() and Finalize() Methods Run() Finalize()

16. MyWorldGridCompMod.F90contains the SetServices(), Initialize(), Run() and Finalize() code. hello_world_app.F90 contains the top layer app driver. Compiling and executing Hello World Building Hello World demonstrates one way to compile programs that use ESMF. All the EA tutorial examples use this approach.

17. Compile with make Need to use same compiler as used to build ESMF. use compiler options consistent with ESMF build. use link options consistent with ESMF build. specify location of ESMF 2.0 distribution library and Fortran module files. Compiling Hello World - I Path names and compiler options for my laptop

18. File “.obj_list” in each example directory specifies what to compile Compiling Hello World - II • Shared directory “example_make_files” contains make files with fbase etc.. settings predefined • To make with an example make file

19. File “output.txt” in each example directory contains reference output Executing Hello World

20. component_tutorials/clock/

21. Top Layer App Driver ESMF library code SetServices() Initialize() Run() Finalize() Clock- component_tutorials/clock - • Clock • same approach as “hello_world”. • driver loops over run() stage • run() demonstrates simple use of clock and alarm (at Y2K).

22. MyWorldGridCompMod.F90contains the SetServices(), Initialize(), Run() and Finalize() code. clock_app.F90 contains the top layer app driver. top layer driver creates clock, sets initial time, sets alarm, advances clock. gridded component reads clock and checks alarm Clock source

23. like hello_world, creates component calls SetServices(), Init(), Run(), Finalize three extra blocks of code in top layer driver Clock top level clock_app.F90 1 - Declare clock variables and set default calendar. 2 - Set clock and alarm 3 - Iterate, advancing clock

24. Clock gridded component MyWorldGridCompMod.F90 • SetServices(), Initialize() like hello_world, • Run() has extra logic, to print time and check alarm. • in ESMF component interface standard CLOCK is passed in through Run() interface. Top Layer App Driver clock/ Run()

25. Running Clock- component_tutorials/clock - Iteration 1 Iteration 2 Iteration 3 • File “output.txt” contains reference output

26. component_tutorials/import_export/

27. Top Layer App Driver ESMF library code SetServices() Initialize() Run() Finalize() Import Exportcomponent_tutorials/import_export • Import Export • single gridded component as “hello_world” and “clock”. • demonstrates using ESMF_Array in ESMF_State to pass data in and out of a component Top Layer App Driver Export State Initialize Run 10 – Run() adds 1 to the contents of the ESMF Array in the Export State. 3 – Initialize creates an ESMF Array for holding data. 4 – Initialize adds ESMF Array to Export State. 5 – Export State is returned to top layer. 2 - Top Layer passes Export State to Initialize() 8 – Export state is returned to the top layer. 6 – Export State is passed to Run. 1 - Top Layer creates Export State 7 – Run adds the value 1 to the ESMF Array. 9 – Top layer calls run again, passing down import and export state. Export State 1 2 ESMF Array +1

28. MyWorldGridCompMod.F90contains the SetServices(), Initialize(), Run() and Finalize() code. import_export_app.F90 contains the top layer app driver. top layer driver creates import and export states, iterates over calling run. gridded component decodes import and export states and +1. Import Export source

29. like hello_world, creates component calls SetServices(), Init(), Run(), Finalize two extra blocks of code in top layer driver Import Export top level import_export_app.F90 1 –Setup import and export states 2 - Iterate

30. Import Export gridded component MyWorldGridCompMod.F90 • SetServices(), Initialize() like hello_world, • Run() has extra logic, to read and write to and from import and export state. • in ESMF component interface standard import, export are passed in through Run() interface. Top Layer App Driver import_export/ Run() …

31. Together hello_world, clock and import_export introduce key tools you need to wire examples like those shown the boxes are ESMF Gridded Components the data-flow between boxes occurs through ESMF import and ESMF export states time is synchronized through ESMF clocks Combining lessons Questions so far?

32. ESMF supports applications with more than one gridded component! simple_couple_1demonstrates multi-component programming under ESMF component_tutorials/simple_couple_1/

33. dtP dtQ dtR dtS Clock p, tauP P R PQ2R x=f(p,tau,t) x’=h(x,y) Out Q S PQ2S q, tauQ y=g(q,tau,t) y’=i(x,y) • simple_couple_1 • five “gridded components” (P, Q, R, S) that evaluate equations for an oscilloscope like device. • a clock that sends alarms to signal components to update their outputs. • two “coupler components” (PQ2R and PQ2S) that combine import states from multiple components into a single export state. • also demonstrates ESMF configuration attributes to get runtime parameters.

34. simple_couple_1.F90: acts as top driver, creates mid-level driver, calls Run() methods. GridComp*.F90, CplComp*.F90: components. oscillate.F90: mid-level driver. e_utils.F90: convenience functions that combine common ESMF operations. simple_couple_1 source

35. what the components do

36. Top level driver “simple_source_1.F90”

37. oscillate.F90 – mid-level driver • creates and manages components – passes them import/export states, configuration attribute resource files etc…

38. oscillate.F90 • to create the appropriate data flow we interconnect import and export state • latch everyone to a common clock

39. GridCompP.F90 (and Q,R,S ….) • called from mid-level driver • carry out computation, pass results out through export state.

40. Clock with multiple alarms is used at mid-level to • schedule calls to Gridded Components. • schedule calls to Output Component. • e.g.

41. Configuration attributes are used in getting alarm frequency parameters and other parameters e.g. GridCompP frequency

42. Running simple_couple- component_tutorials/simple_couple_1 - Outputs for different resource file settings.

43. simple_couple- component_tutorials/simple_couple_1 - Outputs for different resource file settings.

44. fields_and_grids_tutorials/regrid/

45. Regridding Levitus at 1o to 2o. Uses 1 component to read in data. A coupler component calls Regrid A second component writes the result. Can run in parallel. Uses VM and does lat decomp – lon decomp switch. Regrid tutorial