1. Extended submodel interface of echam6
S. Rast
HAMMOZ meeting, Zurich, /25

2. Radiation, convection, diffusion, clouds
Introduction
ECHAM6
General circulation
Physics of atmosphere
Radiation, convection, diffusion, clouds
I n t e r f a c e
Two way communication
Submodel 1
Submodel 2
...
Submodel n

3. General interface properties
Dummy subroutines:
Collection of subroutines providing hooks to echam6
Data structures:
Collect local echam6 variables in a data structure to pass to submodels
Data structure for transported quantities (tracers) includes transport properties (flags)
Chemical species and their physical properties are stored in separate data structure. The tracer and species concept supports families of species
Boundary conditions (emissions, climatologies) are collected in one data structure
Flexible diagnostics per species/tracer/mode

4. Differences with respect to echam5 submodel interface
Distinction between tracers and species allows for the introduction of families of species in one (transported) tracer
Boundary condition data structure allows for consistent and namelist controlled treatment of emissions and climatological boundary conditions
Diagnostic stream helps to control the quantity of output by namelist

5. Coupling submodels with help of this interface I
For introduction of submodels, one must change mo_submodel_interface only
Dummy subroutines for calls of specific submodel routines are provided
Interface based on data structures (streams) originally introduced by A. Rhodin, L. Kornblüh et. al.
extended on demand

6. Coupling submodels with help of this interface II
Register submodel
Read submodel specific namelist
Setup tracer/species structure and memory for submodel
Read boundary conditions
several hooks to interact with echam6 physics
diagnostics

7. Coupling among submodels
Coupling among submodels: Each submodel has to provide its own special interface
BUT
Data structures of echam6 can help:
Data structure for species, diagnostic, boundary conditions

8. Style guide - Icon style guide
The relevant style guide is the style guide for ICON:
„Programming Guide for ICON“ (ask S. Rast)
Example for header of Modules:
!>
!! <Short description of module for listings and indices> !!
!! <Describe the concepts of the routines and algorithms used in the module.>
!! <Details of procedures are documented below with their definitions.>
!! <Include any applicable external references inline as module::procedure,>
!! <external_procedure(), or by
!! <Donât forget references to literature.>
<Name, affiliation of author>
!! $Id: n/a$
Revision History
!! <Description of activity> by <Name> (<YYYY-MM-DD>)

9. Style guide - Icon style guide
Copyright
!! by DWD and MPI-M
!! This software is provided for non-commercial use only.
!! See the LICENSE and the WARRANTY conditions. !!
License
!! The use of ICON is hereby granted free of charge for an unlimited time,
!! provided the following rules are accepted and applied:
!! <ol>
!! <li> You may use or modify this code for your own non commercial and non
!! violent purposes.
!! <li> The code may not be re-distributed without the consent of the authors.
!! <li> The copyright notice and statement of authorship must appear in all
!! copies.
!! <li> You accept the warranty conditions (see WARRANTY).
!! <li> In case you intend to use the code commercially, we oblige you to sign
!! an according license agreement with DWD and MPI-M.
!! </ol>
Warranty
!! This code has been tested up to a certain level. Defects and weaknesses,
!! which may be included in the code, do not establish any warranties by the
!! authors.
!! The authors do not make any warranty, express or implied, or assume any
!! liability or responsibility for the use, acquisition or application of this
!! software.
MODULE mo_xyz

10. Test of your submodel - part I
Test your module on a PC (or small computer) with tests for
arithmetic exceptions
uninitialized variables
incompatible parameter lists of subroutines/functions
e.g. with the NAG compiler (-C=all -nan -gline)
Keep in mind: Any supercomputer is not a toy and testing on those machines is normally difficult.
If you like to send a rover to Mars, you will test it first on Earth before you realize that your solar module does not unfold because of programming errors!

11. Test of your submodel - part II
Pitfalls:
Even if your parameter lists are checked, the exact shape of your arrays is not checked. There will be a check of the number of dimensions and the total number of elements only!
E.g.:
REAL(dp) :: u(nlon,nlat)
call winds(u,nlon,nlat)
subroutine winds(u,nlat,nlon)
REAL(dp) :: u(nlat,nlon)

12. Test of your submodel
Before you can run your model on any supercomputer, it must pass the following tests on a PC/small system
Nproma test: Bit identical results for two different values of nproma which are not a divisor of nlon (e.g. 17 and 23)
Parallel test: Bit identical results on 1 and 2 processors
Rerun test: Bit identical results after a rerun as compared to an uninterrupted run
Submodel switch off test: Bit identical results for echam from main branch and your version but submodel switched off

13. Conclusion
Interface allows coupling of submodels to echam6 with changes of only one module
Code of submodels can be maintained somewhere else than at MPI Hamburg
Interface is flexible and can be extended easily
Data structures of interface are particularly suited for aerosol/chemistry submodels (tracers, species)
Easy handling of boundary conditions
Tests are extremely important